Integrating with Algolia

You can integrate Commerce with Algolia quickly and easily in Commerce Manager.

Whenever you publish a catalog, the full catalog is synced to Algolia using an index name composed of the catalog name and the first part of the catalog ID. This is triggered using events delivered by a webhook.

When a catalog is published, a catalog-release.updated event is triggered.
Once a catalog-release.updated event is received by the webhook, the integration begins to execute.
The integration performs the following:
- Retrieves product and taxonomy data for the catalog.
- Retrieves the mapping for Commerce fields to Algolia fields.
- Builds or updates the Algolia index.

For more information, watch a video.

Collecting Your Setup Information

Before you begin configuring your Algolia integration in Commerce Manager, you need to collect the necessary setup information from Algolia and Commerce Manager.

caution

Collect the following information and make sure you have it available, for example, in a text file, before configuring your Algolia integration in Commerce Manager. If you leave the Algolia Integration page in Commerce Manager, the integration is not saved and you must remove the integration and create a new one.

Collecting Algolia Setup Information

You can find this information in the Settings, Teams and Access, API keys section on the Algolia Dashboard.

Option	Description
App ID	Your Application ID for your Algolia account.
Admin API key	Your Admin API Key for your Algolia account.

Collecting Commerce Manager Setup Information

Collect the following Commerce API keys. You can find this information in SYSTEM > Application Keys in Commerce Manager when logged in as a user with Seller Admin privileges.

Commerce API Key	Description
API Base URL	Your Commerce API Base URL.
Client ID	Your Commerce Client ID.
Client Secret	Your Commerce Client Secret.

note

When integrating with third-party providers, we recommend you use the closest region in the third-party service to reduce latency as much as possible. See Regions and URLs table.

Configuring the Integration

Now that you've collected the setup information, let's begin by configuring the integration.

In Commerce Manager, go to COMPOSER > Integrations Hub.
Under Search, click on the Algolia Full /Delta / Large Catalog integration.
Review the Summary page and click Configure. The current version information is displayed.
Click Next.
Configure the following information and click Finish.

Configuration parameter	Value
Algolia Configuration Data: algolia_app_id	Your Application ID for your Algolia account.
Algolia Configuration Data: algolia_admin_api_key	Your Admin API Key for your Algolia account.
Commerce Configuration Data: Client ID	Your Commerce API Client ID.
Commerce Configuration Data: Client Secret	Your Commerce Client Secret.
Commerce Configuration Data: Token URL	Your Commerce API Token URL. For example, `https://euwest.api.elasticpath.com//oauth/access_token` (EU) or `https://useast.api.elasticpath.com/oauth/access_token` (US). See Regions and URLs.
epcc_base_url	Your Commerce API Base URL. For example, `https://euwest.api.elasticpath.com` (EU) or `https://useast.api.elasticpath.com` (US).
webhook_key	Send to create secret for EPCC Integration (Examples: Simple Phrase, UUID).
Post Processing Configuration Data (Optional): webhook_url	Optional post-processing URL that the release details are sent to upon completion of an integration attempt.
Post Processing Configuration Data (Optional): webhook_api_key	Optional post-processing API key for the above URL.
Integration Tuning Parameters: batch_size	The default page size when synchronizing. The default is 250.
Integration Tuning Parameters: concurrent threads	The number of threads that process each batch. The default is 10.

note

We recommend that you do not change the default tuning parameters. Contact Customer Success for more information.

The integration starts an execution which:

Configures a webhook to listen to the catalog-release.updated event, named EPCC Algolia Integration.
Creates a flow for containing field mappings between Commerce and Algolia, called Algolia Mapping.

caution

You must not delete the Algolia Mapping flow or the EPCC Algolia Integration webhook, or the integration ceases to work.

Now that you've configured the integration, let's learn how you use it.

Understanding Field Mappings Between Commerce and Algolia

To sync the catalog to Algolia, you create a map of the data to pass from Commerce to Algolia. The mapping consists of:

Source field.
Destination field.
Any flags to trigger optional functions.

The integration uses a flow to contain the fields that you want to use. The source of the Commerce data is the catalog delta file. Additionally, there are some special fields that perform additional transformation work. When the integration is initially configured, a default set of mapping fields are created. However, you can change these depending on your requirements.

The following table describes some example fields in Commerce Manager and their corresponding fields in Algolia.

Commerce Field	Maps to Algolia Field	Flags
attributes.sales	ep_sales
attributes.price	ep_price	forceSaleFlag
attributes.description	ep_description
attributes.mpn	ep_mpn
attributes.name	ep_name
attributes.sku	ep_sku
attributes.slug	ep_slug
attributes.status	ep_status
upc	ep_upc
main_image	ep_main_image_url	includeHierarchy
taxonomy	ep_categories. This field is used to trigger the creation of a hierarchy in Algolia.

The following are special field names:

main_image triggers a lookup of the URL from the file associated to the main image relationship on the product.
taxonomy retrieves the hierarchy and builds a custom Algolia-friendly format.

Alternate Taxonomy Fields

In addition to the ep_categories attribute, you can use the ep_slug_categories attribute. This attribute contains the formatted hierarchy values, but uses the category-node slug rather than the category-node name.

For example, the ep_categories field appears as follows

{
   lvl0: "Animal & Pet Supplies"
   lvl1: "Animal & Pet Supplies > Dog"
   lvl2: "Animal & Pet Supplies > Dog > Dog Containment"
   lvl3: "Animal & Pet Supplies > Dog > Dog Containment > Dog Houses Kennels & Pens"
}

And the ep_slug_categories field appears as follows:

{
   lvl0: "animal-and-pet-supplies"
   lvl1: "animal-and-pet-supplies > dog"
   lvl2: "animal-and-pet-supplies > dog > dog-containment"
   lvl3: "animal-and-pet-supplies > dog > dog-containment > dog-houses-kennels-and-pens"
}

Optionally, you can also generate a new field called ep_name_plus_slug_categories which is a formatted representation or the category-node name, and category-node slug fields available for faceting.

Using Create Category Name Slug Attribute, you can enable the creation and maintenance of this field.

Set Create Category Name Slug Attribute to true if you want to create the ep_name_plus_slug_categories attribute field.

For example, when enabled, the ep_name_plus_slug_categories field appears as follows:

{
  lvl0: "Animal & Pet Supplies#animal-and-pet-supplies"
  lvl1: "Animal & Pet Supplies#animal-and-pet-supplies > Dog#dog"
  lvl2: "Animal & Pet Supplies#animal-and-pet-supplies > Dog#dog > Dog Containment#dog-containment"
  lvl3: "Animal & Pet Supplies#animal-and-pet-supplies > Dog#dog > Dog Containment#dog-containment > Dog Houses Kennels & Pens#dog-houses-kennels-and-pens"
}

where, for each value the Name and SLUG values are concatenated to permit them both to be available to the front-end.

In all cases, when there are multiple product->node assignments, a comma is used to separate the data in the ep_categories, ep_slug_categories and the optional ep_name_plus_slug_categories fields.

For example,

   lvl0: "Farm and Ranch,Power Tools and Acc,Fasteners"

where the product is assigned to both Farm and Ranch, but also Power Tools and Acc as well as the Fasteners category nodes.

Creating new field mappings

In Commerce Manager, go to Flows > Algolia Mapping. (If you have just configured your integration, refresh Commerce Manager to pick up the newly-added flow from the integration.)
Click New Entry.
Create the field mappings you desire by supplying the source field and destination field.
In Algolia, create the fields described above. Refer to the documentation provided with Algolia for more information.

Mapping flags

The following mapping flags are available.

includeHierarchy - Use this flag if you want the name of the hierarchy to be included in the bread_crumbs.
forceSaleFlag - By default, if a price is on sale, an on_sale flag is set to true in the price book. If you also want an on_sale flag at the root of the product, you can add this flag to the price mapping.
forceJSON - It is a boolean value used to determine whether the input value should be parsed as JSON. This is useful if you want to treat an Elastic Path field as an embedded structure and not as a string.
convertDateToTS - A boolean value used to determine whether the input value is parsed as a date. The date is converted into a number that represents a UNIX timestamp.
isNullValue - Use this flag if you want to set the attribute value to 1 or 0 based on whether the EPCC value resolves to NULL. This is useful when Algolia filtering is used as Algolia does not support filtering on a null parameter value.

Managing the Integration

Once the integration is configured and you have the mappings you want, the catalog is synced with Algolia with every new publish of your catalogs.

Partial updates

If a catalog has already been published and changes are made to the catalog and the catalog is published again, this results in a partial catalog update. In other words, only the products that have been created, updated or removed from the previous catalog release are updated. These are made directly to the live index in Algolia.

Full updates

A full catalog update can be triggered in the following scenarios.

The first time a catalog is published. The delta file is then used to create a temporary index. The settings, rules, and so on, from the live version are then copied onto the temporary index. Once the index is completely loaded, the temporary index is moved to the live index.
You can trigger a full catalog update by setting export_full_delta to true when publishing a catalog. Here is a sample request:

curl --location -g '{{pcmUrl}}/catalogs/{{catalogId}}/releases' \
--header 'accept: application/json' \
--header 'content-type: application/json' \
--data {
    "export_full_delta" : true
}

Naming catalogs and indexes

Index names are created from the catalog name and a portion of the catalog id. This allows the integration to manage many catalogs at the same time. This dependency is important to consider when naming catalogs in Commerce and indexes in Algolia.

Updating a single product in Algolia

You can update a single Commerce product in Algolia without publishing a catalog. You can do this by sending a payload directly to an Algolia index using a URL available in the Algolia Integration. Updates to a single product checks if other catalog sync operations are in progress and delay the update until the other operations are completed.

you can add new fields. If there are new fields that do not currently exist, they are added. You must provide the full replacement value. In the example below, ep_categories is a complex object. To properly update the object, the full object must be provided.
you can update the values of existing fields.

Go to Composer > Integrations Hub.
Under Search, click Algolia Full /Delta / Large Catalog.
From the Summary tab, navigate to Trigger details > UpdateObject to Algolia - Direct.
Expand UpdateObject to Algolia - Direct.
From URL, select Copy URl to clipboard icon.

note
The URL is unique to each deployed instance of the Algolia Integration.
In Postman, open POST {{webhook-url}} where webhook-url is the URL you just copied.

The Body of the request can have the following parameters:

Name	Required	String	Description
`index_name`	Required	`string`	The name of the Algolia index that you want to update.
`objectID`	Required	`string`	The product ID of the Commerce product that you want to update.
`secret_key`	Required	`string`	The Commerce Client Secret that you used when you configured the Algolia Integration.
`payload`	Required	`string`	The payload contains the mapped fields for the Algolia object that you want to update. The schema must match the existing Algolia object.

An example request is shown below:

{
  "index_name": "Main_123450",
  "objectID": "b8e9af84-69f9-472c-ad18-57557e1d2c75",
  "secret_key": "n4bQgYhMfWWaL+qgxVrQFaO/TxsrC4Is0V1sFbDwCgg=",
  "payload": {
    "ep_name": "WALL MOUNTING BRACKET",
    "ep_slug": "18-025-999",
    "ep_categories": {
    "lvl0": "Shop"
    }
  }
}

Filtering Catalogs

By default, every catalog publish event triggers a sync to Algolia. You can restrict this to a specific subset of catalogs using the Selected Catalogs filter on the Advanced config page.

Configuration

Config Variable	Type	Required	Description
Selected Catalogs	list	Yes	Checkbox list of all available EPCC catalogs. Only catalogs checked here trigger an Algolia sync. At least one catalog must be selected. All catalogs are selected by default when installing the integration.

Behavior

The filter runs in the Main Process Flow, before any downstream sync is triggered.

Scenario	Result
Catalog is in the selected list	Processing continues normally
Catalog is not in the selected list	Logged as info; execution ends silently without error

Filtering Products

You can control which individual products from a catalog are sent to Algolia using a JavaScript filter expression. This is useful when a catalog contains products that should not be indexed, such as child product variants.

Configuration

Two config variables on the Advanced config page work together:

Config Variable	Type	Required	Description
Enable Product Filtering	boolean	No (default: `false`)	Master toggle. When `false`, all products are published and the expression below is ignored.
Filter Expression	code	No (default: `!record.attributes.base_product_id`)	A single JavaScript boolean expression evaluated against each product record. Records returning `true` are included; records returning `false` are dropped. Only evaluated when the toggle is `on`.

note

The default expression !record.attributes.base_product_id only takes effect once Enable Product Filtering is turned on. Existing deployments default the toggle to false, so upgrade behavior is unchanged.

Filter Expression Syntax

The variable record refers to the current product record from the catalog JSONL file. The expression must be a single expression — not a function body or a multi-statement block.

Key fields available on record:

record.id                          Top-level product UUID
record.type                        Always "product"
record.attributes.status           "live" or "draft"
record.attributes.base_product     Boolean; true for base/standalone products
record.attributes.base_product_id  Empty string for parent/base products; UUID for child products
record.meta.product_types          Array, e.g. ["parent"] or ["child"]
record.attributes.extensions       Object; may contain custom extension fields

Examples:

// Exclude child products — base_product_id is empty for parent/base, UUID for children
!record.attributes?.base_product_id

// Keep only non-child products using the product_types array
!record.meta?.product_types?.includes("child")

// Exclude wrapper products identified by a custom extension field
record.attributes?.extensions?.["products(metadata)"]?.["is-wrapper-product"] !== true

// Combine: keep non-child products that are not wrappers
!record.meta?.product_types?.includes("child")
  && record.attributes?.extensions?.["products(metadata)"]?.["is-wrapper-product"] !== true

tip

Always use optional chaining (?.) when accessing nested fields to avoid per-record runtime errors. Use bracket notation for field names containing hyphens or parentheses: record.attributes?.["field-name"].

Behavior and Edge Cases

Scenario	Result
Toggle off	All products are published; expression is ignored
Toggle on, valid expression	Expression evaluated per record; non-matching records are silently dropped
Toggle on, empty expression	All records pass through; an INFO log is written
Expression syntax error	Step fails immediately before any records are processed; Algolia is unchanged
All records filtered out (full publish)	Algolia index promotion is skipped; live index is preserved; execution completes without error
All records filtered out (delta publish)	No writes to Algolia; live index is unchanged; execution completes without error

Post-Processing Webhook Payload

When a post-processing webhook URL is configured, the payload is enriched with a filterStats object. This is additive — all existing fields remain at the same paths.

{
  "filterStats": {
    "totalBatchesSent": 12,
    "totalSuccessfulBatchCount": 12,
    "totalRetries": 0,
    "totalFilteredCount": 847,
    "totalEvalErrorCount": 0,
    "filterApplied": true
  }
}

When no filter is configured, filterStats is still present with all counters set to 0 and filterApplied: false.

Using an Extension Endpoint

The integration supports an optional extension endpoint that intercepts each batch of mapped product data after the Commerce-to-Algolia field mapping has been applied and before the batch is sent to Algolia. This allows an external service to enrich, filter, or modify records in-flight.

The endpoint receives already-mapped Algolia records — it does not have access to raw Commerce attributes that were not included in the field mapping.

Configuration

Four config variables are available on the Advanced config page:

Config Variable	Type	Required	Description
Send Data to Extension Endpoint	boolean	No (default: `false`)	Master toggle. When `true`, each batch is sent to the extension endpoint before Algolia.
Extension Endpoint Url	string	Yes (when enabled)	The HTTP(S) URL of the extension endpoint.
Extension Endpoint Header Name	string	No	Custom header name for authentication, for example `X-API-Key`.
Extension Endpoint Header Value	string	No	Custom header value for authentication.

Data Contract

The endpoint receives an HTTP POST with the Algolia multi-index batch format:

{
  "requests": [
    {
      "action": "updateObject",
      "indexName": "catalog_name_abc12345",
      "body": {
        "objectID": "product-uuid",
        "ep_name": "Example Product",
        "ep_sku": "SKU-001"
      }
    }
  ]
}

The endpoint must return a response with the same { "requests": [...] } wrapper. The endpoint can:

Enrich — modify the body of any request to add or update fields.
Filter — remove entries from the requests array to prevent specific products from being indexed.
Pass through — return the data unchanged.

Error Handling

Extension Response	Action	Log Level
Valid data with requests	Extension data is sent to Algolia	—
Call failed or timed out	Original mapped data is sent to Algolia (graceful fallback)	Warning
Empty `requests` array	Batch is skipped entirely; live index is unchanged	Info

If the extension endpoint is unreachable or returns an error, the integration falls back to sending the original mapped batch directly to Algolia. This ensures an unavailable extension endpoint does not block catalog sync.

Returning an empty requests array is treated as an intentional filter — no fallback to original data occurs for that batch.

note

The extension endpoint URL must start with http:// or https://. An invalid URL fails the execution before any records are sent.

API Documentation

Fundamentals & Getting Started

Composer

Commerce Manager

Developer Tools

Self-Managed Commerce

Collecting Your Setup Information​

Collecting Algolia Setup Information​

Collecting Commerce Manager Setup Information​

Configuring the Integration​

Understanding Field Mappings Between Commerce and Algolia​

Alternate Taxonomy Fields​

Creating new field mappings​

Mapping flags​

Managing the Integration​

Partial updates​

Full updates​

Naming catalogs and indexes​

Updating a single product in Algolia​

Filtering Catalogs​

Configuration​

Behavior​

Filtering Products​

Configuration​

Filter Expression Syntax​

Behavior and Edge Cases​

Post-Processing Webhook Payload​

Using an Extension Endpoint​

Configuration​

Data Contract​

Error Handling​

Collecting Your Setup Information

Collecting Algolia Setup Information

Collecting Commerce Manager Setup Information

Configuring the Integration

Understanding Field Mappings Between Commerce and Algolia

Alternate Taxonomy Fields

Creating new field mappings

Mapping flags

Managing the Integration

Partial updates

Full updates

Naming catalogs and indexes

Updating a single product in Algolia

Filtering Catalogs

Configuration

Behavior

Filtering Products

Configuration

Filter Expression Syntax

Behavior and Edge Cases

Post-Processing Webhook Payload

Using an Extension Endpoint

Configuration

Data Contract

Error Handling