Guides

Typesense

If your custom storefront keeps its product catalogue in Typesense, this guide walks you through wiring that catalogue into Deducto. The result is a search integration: while you're authoring promotions inside the Deducto Dashboard, you can search and pick products, categories, brands, and so on directly from your Typesense collections instead of typing names or IDs by hand.

📘

Where this fits in the bigger picture

Deducto doesn't read your Typesense collections when evaluating promotions at runtime – it evaluates against the cart data your storefront sends in each request. The search integration is purely a Dashboard-side convenience: it makes authoring promotion logic faster and less error-prone by giving you the same searcher experience you'd have shopping the site. It's entirely optional, but if your catalogue is large enough that typing IDs in by hand becomes unpleasant, it pays for itself quickly.

If you're not using Typesense and want the same convenience, the Algolia integration has identical capability.

There are four steps to set up a Typesense-backed project end-to-end. Steps 1 and 4 are Typesense-specific; steps 2 and 3 cover the project's attribute definitions and apply equally to any custom-storefront project (so if you've already set those up, you can skip ahead).

To begin, click the Edit icon next to your project in the project list and open the project configuration.

Step 1: Connect to your Typesense host

This step gives Deducto credentials to query your Typesense instance from the Dashboard. It's read-only – Deducto only ever issues search requests.

  1. Navigate to the Integration tab in the project configuration.
  2. Select Typesense.
  3. Click Configure Connection Details.
  4. Enter your Typesense Host (e.g. <your-unique-subdomain>.typesense.net) and a search-only API key.
  5. Click Save Connection Details.
📘

Use a search-only API key

Typesense admin keys can write to your collections and mint new keys themselves – Deducto never needs that. A search-only key limits the blast radius if the credential is ever compromised. You can create one from the API Keys area of your Typesense cluster.

Step 2: Define attributes

This step defines the custom attributes your project will use in promotion logic (for example: Brand, Material). These are independent of Typesense – they're the canonical attribute definitions for your project. See Attributes for the full conceptual treatment.

  1. Navigate to the Attributes tab in the project configuration.
  2. For each attribute you want to use:
    • Click Add Attribute for a single-value attribute, or Add Array Attribute if the attribute will hold a list of values.
    • Provide a label – this is what you'll see when referencing the attribute in promotion conditions.
    • Choose the attribute type (String, Number, Boolean, etc.).
    • Tick compulsory if every cart item must carry the attribute for promotion eligibility.

Repeat for each custom product attribute and cart attribute the project needs.

Step 3: Map attributes to incoming request fields

Defining an attribute names it in the Dashboard; mapping it tells Deducto which field in your storefront's request carries the attribute's value. The two can have different names – for example, your Typesense field might be brand_name while you'd rather see Brand in the Dashboard.

  1. Navigate to the Mappings tab in the project configuration.
  2. For each product attribute and cart attribute, enter the Field Name the storefront will send. The expected data type is shown by the icon next to the field; array attributes have a distinctive marker.

After steps 1–3, the project is functionally complete – you can author promotions, the storefront can call the API, and Deducto will evaluate everything correctly. Step 4 adds Dashboard-side polish.

Step 4: Configure search collections

This is the step where setting up the Typesense integration really earns its keep. You're describing each collection you want available inside the Entity Searcher – the in-Dashboard search UI that appears whenever a promotion condition needs to reference specific products, brands, categories, etc.

Have your Typesense dashboard open in another tab; you'll need to copy collection names and field names across.

Navigate to the Search tab in the project configuration (this tab is only visible once you've selected Algolia or Typesense in step 1). Click Add Collection for each collection you want to register.

For each collection, you'll pick between two flavours:

ID-based vs value-based: when to use which

  • ID-based collection – the searcher stores the record ID in the promotion. Use this when the underlying entity is stable but renameable: products, categories with their own records, brands stored as separate documents. Renaming "Nike" to "Nike Inc." in your document won't break the promotion because the promotion is bound to the ID, not the display string. Only Single Membership and Multi Membership attribute types can be linked to an ID-based collection.
  • Value-based collection – the searcher stores the facet value itself in the promotion (e.g. the literal string "Nike"). Use this when the attribute lives only as a facet value, not as a separate record – sizes, colours, simple category names. If you later rename the facet value, any promotions referencing it have to be updated. Only Exact String and Wildcard String attribute types can be linked to a value-based collection.

Rule of thumb: if there's a dedicated Typesense collection for the entity (a products collection, a categories collection, a brands collection), prefer ID-based. If the values live only as facet values on a parent collection, value-based is the right choice.

Configuring an ID-based collection

  1. Click Add Collection and choose ID Based from the dropdown.
  2. Collection Setup – enter the Typesense collection name.
  3. Item Nouns – set the singular and plural labels (e.g. "Product", "Products"). These appear throughout the Dashboard when referring to records from this collection.
  4. Collection Attributes & Sorting – set the required base attributes:
    • ID Attribute – the Typesense field holding the unique identifier. This is the value stored in promotion logic.
    • Name Attribute – the human-readable title field. This is what the Dashboard displays in the searcher and condition editor.
    • URL Path Attribute (optional) – the storefront path for the record. When provided alongside the project's Frontend Base URL, the searcher renders selected records as clickable links to the live store page.
  5. Collection Attributes – click Add Attribute for any additional columns to surface in the searcher:
    • Display Label – the column header in the searcher.
    • Attribute – the Typesense field name.
    • Refinement – tick to expose the attribute as a filter (requires the field to be facetable in Typesense).
    • Hidden in Results – on refinement attributes, hide the column but keep the filter.
  6. Sort By Options – add sort options using the Add Sort Option button. For each:
    • Sort Value – the Typesense field plus direction (e.g. price:desc).
    • Display Label – a friendly name ("Price: high to low").
  7. Advanced Config (optional) – tune Results Per Page, or apply a permanent Filters clause to exclude records (e.g. discontinued:=false to hide retired products from the searcher).
  8. Click Back in the top left to save.
  9. Locate the collection you just created and tick the custom attribute(s) that should be backed by it.

Configuring a value-based collection

  1. Click Add Collection and choose Value Based from the dropdown.
  2. Enter the Typesense collection that contains the facetable field.
  3. Set the singular and plural item nouns (e.g. "Size", "Sizes" for a sizes facet).
  4. Under Base Attributes > Target Attribute, enter the Typesense field name holding your facet values. These values are what gets stored in promotion logic.
  5. Advanced Config (optional) – same as for ID-based: Results Per Page and Filters.
  6. Click Back to save.
  7. Locate the collection and tick the custom attribute(s) that should be backed by it.

Example: Categories

A concrete scenario makes the ID-vs-value choice clearer. Suppose your product collection has a categories field on each product:

  • If categories holds category names (["Mens", "Outerwear"]) – set up a value-based collection pointing at the product collection's categories facet. Promotions reference the literal name strings.
  • If categories holds category IDs (["cat_123", "cat_456"]) and you have a separate categories collection keyed by those IDs – set up an ID-based collection against the categories collection. Promotions reference the IDs; renaming a category in your CMS doesn't break the promotion.

Either setup is then linked to a Categories custom array product attribute as the final action in step 4.

Updated 13 days ago