Route indexing requests through the Algolia Ingestion API for Collections and Transformations support.
By default, the Algolia Salesforce B2C Commerce cartridge sends indexing requests to the Algolia Search API.
You can switch the cartridge to the Algolia Ingestion API to unlock features such as:
Collections: curate manually selected or rule-based product listings without maintaining them in your index ahead of time.
Transformations: shape your records before they’re written to the index, either without code using the dashboard’s visual editor, or with code by writing JavaScript.
The Ingestion API has slightly higher per-request overhead than the Search API.
If you don’t need Transformations, Collections, or other Ingestion-only features, keep the default Search API.
The Indexing API preference applies to product indexing only. The following jobs and hooks route through the selected API:
AlgoliaProductIndex_v2, including its full catalog reindex and partial-record update modes.
AlgoliaProductPriceIndex_v2 and AlgoliaProductInventoryIndex_v2. Both reuse the product indexing step internally.
AlgoliaProductDeltaIndex_v2.
The real-time inventory hook, which fires on SFRA order placement and on headless (OCAPI/SCAPI) order placement.
AlgoliaCategoryIndex_v2 and AlgoliaContentIndex_v2 always send their writes through the Search API, regardless of this setting.Even when you select the Ingestion API for product writes, the cartridge still calls the Search API for related operations:
Copying settings from the production product index to the temporary index at the start of an atomic reindex.
Moving the temporary index into production at the end of an atomic reindex.
Waiting on the resulting Search API tasks for those copy and move operations.
Your Write API Key must remain valid for both APIs.
The ACL set required by the Ingestion API includes every entry the Search API needs, plus editSettings, so a single key with addObject, deleteObject, deleteIndex, settings, and editSettings covers all requests.
Prerequisites for using the Ingestion API for indexing:
Cartridge version 26.2.0 or later.
Re-imported cartridge metadata. After upgrading, re-import the updated metadata/algolia/meta/system-objecttype-extensions.xml so Business Manager picks up the new Indexing API and Analytics region site preferences.
An Algolia Write API key with these ACL entries: addObject, deleteObject, deleteIndex, settings, editSettings. The Ingestion API also requires editSettings, which the Search API doesn’t. The cartridge validates this when you save your Business Manager settings.
The analytics region of your Algolia application. Find it under Infrastructure > Analytics in the Algolia dashboard. Allowed values are us and eu.
The Ingestion API routes every write through a task that links a source to a destination index.
You need one task per product index the cartridge writes to.Product index names follow the pattern <HOSTNAME>__<SITE_ID>__products__<LOCALE> (or use your Index Prefix override).
For example, a site indexing products in en_US and fr_FR needs two Push tasks.
You don’t need tasks for category or content indices, because AlgoliaCategoryIndex_v2 and AlgoliaContentIndex_v2 always use the Search API.You can create a task in two ways:
With the Push to Algolia connector: set up a Push to Algolia connector in the Algolia dashboard under Data sources > Connectors. The setup wizard walks you through picking the destination index and creating the task. You can optionally attach a Transformation in the same flow, either without code or with code.
By creating a Collection: under Search > Collections, create a Collection on the destination index. Algolia provisions the Push task that backs the collection.
If a destination index has no Push task, the cartridge’s Push request returns an error and the records for that index aren’t indexed.
After adding or removing locales, record types, or sites, create the matching tasks before the next indexing run.
Set Analytics region to us or eu to match your Algolia application.
Click Apply.When you save, the Business Manager validates your Write API Key against the ACL required by the selected API.
The form rejects the save if the key is missing permissions, or if you entered a non-empty Analytics region that isn’t us or eu.
After saving, the next product indexing job run uses the Ingestion API endpoint https://data.<region>.algolia.com.
https://<APP_ID>.algolia.net plus three failover hosts on algolianet.com
https://data.<region>.algolia.com (single host)
Region scoping
Global
Bound to your Algolia application’s analytics region (us or eu)
Failover
Cartridge fails over across four hosts
Single host, with three in-place retries on transient errors
The Ingestion API exposes a single host per region, so the cartridge retries the same host to absorb transient network errors instead of failing over to a different host.
When product jobs run on the Ingestion API, the semantics of the records sent and chunks sent counters in their job reports change.
Category and content job reports don’t change: they always reflect Search API behavior.
With the Ingestion API, a successful HTTP response only confirms transport-level acceptance of the payload.
The actual indexing happens asynchronously on Algolia’s side.
Record-level errors (for example, a record exceeding the size limit, or a failed transformation) surface only after the asynchronous run completes, in the Connector Debugger.
The following table compares the counters for the product, product price, product inventory, and product delta jobs:
Counter
Search API
Ingestion API
records sent
Algolia accepted and indexed. Algolia returns record-level errors synchronously, and the cartridge counts them as failed
Algolia accepted at the HTTP layer. They might still fail during asynchronous processing
records failed
Includes records rejected synchronously, for example, “record too big”
Reflects only transport-level failures, like HTTP errors or timeouts
Product job reports in Business Manager and the cartridge logs only show what the cartridge can observe synchronously.
For record-level errors that occur during asynchronous processing, use the Algolia dashboard:
Performance overhead: Algolia processes each Push request asynchronously, and the cartridge groups by index and action before sending. For high-volume catalogs, expect slightly longer end-to-end indexing times than with the Search API.
Single host per region: there’s no multi-host failover for Ingestion. The cartridge mitigates with in-place retries, but a regional outage stops product indexing for the duration. Category and content indexing keep their multi-host failover.
Analytics region must match: pushing to the wrong region (for example, us for an EU application) returns errors. The cartridge can’t auto-detect the region.
Asynchronous error surface: product job reports can show all chunks as sent while a subset of fail asynchronously. Always cross-check the Connector Debugger when reconciling product record counts.
