> ## Documentation Index
> Fetch the complete documentation index at: https://algolia.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Index with the Ingestion API

> Route indexing requests through the Algolia Ingestion API for Collections and Transformations support.

export const Records = () => <Tooltip tip="A record is a searchable object in an Algolia index. Each record consists of named attributes." cta="Algolia records" href="/doc/guides/sending-and-managing-data/prepare-your-data#algolia-records">
    records
  </Tooltip>;

By default, the Algolia Salesforce B2C Commerce cartridge sends indexing requests to the [Algolia Search API](/doc/rest-api/search).
You can switch the cartridge to the [Algolia Ingestion API](/doc/rest-api/ingestion) to unlock features such as:

* [**Collections**](/doc/guides/solutions/ecommerce/browse/tutorials/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](/doc/guides/sending-and-managing-data/send-and-update-your-data/how-to/transform-your-data-without-code) using the dashboard's visual editor, or [with code](/doc/guides/sending-and-managing-data/send-and-update-your-data/how-to/transform-your-data-with-code) by writing JavaScript.

<Tip>
  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.
</Tip>

## What the setting affects

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](/doc/integration/salesforce-commerce-cloud-b2c/guides/realtime-updates), 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.

## Before you begin

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](/doc/guides/security/api-keys) 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**](https://dashboard.algolia.com/account/infrastructure/analytics) in the Algolia dashboard. Allowed values are `us` and `eu`.
* An Ingestion task for every destination index the cartridge writes to. See [Create a Push task per destination index](#create-a-push-task-per-destination-index).

## Create a Push task per destination index

The Ingestion API routes every write through a [task](/doc/guides/sending-and-managing-data/send-and-update-your-data/connectors/push) 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](/doc/guides/sending-and-managing-data/send-and-update-your-data/connectors/push#create-a-new-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](/doc/guides/sending-and-managing-data/send-and-update-your-data/how-to/transform-your-data-without-code) or [with code](/doc/guides/sending-and-managing-data/send-and-update-your-data/how-to/transform-your-data-with-code).
* **By creating a Collection**: under **Search > Collections**, create a [Collection](/doc/guides/solutions/ecommerce/browse/tutorials/collections) on the destination index. Algolia provisions the Push task that backs the collection.

<Note>
  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.
</Note>

## Enable the Ingestion API

1. Go to **Merchant Tools > Algolia > Algolia**.

2. Set **Indexing API** to **Ingestion API**.

3. Set **Analytics region** to `us` or `eu` to match your Algolia application.

4. 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`.

## How indexing differs

### Endpoint and host

|                 | Search API                                                                   | Ingestion API                                                       |
| --------------- | ---------------------------------------------------------------------------- | ------------------------------------------------------------------- |
| Endpoint family | `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.

## Observability and reporting

When product jobs run on the Ingestion API, the semantics of the **records sent** and **chunks sent** counters in their [job reports](/doc/integration/salesforce-commerce-cloud-b2c/troubleshooting/monitoring) change.
Category and content job reports don't change: they always reflect Search API behavior.

<Warning>
  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](https://dashboard.algolia.com/connectors/debugger).
</Warning>

The following table compares the counters for the product, product price, product inventory, and product delta jobs:

| Counter                    | Search API                                                                                                                               | Ingestion API                                                                                        |
| -------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------- |
| **records sent**           | <Records /> Algolia accepted **and** indexed. Algolia returns record-level errors synchronously, and the cartridge counts them as failed | <Records /> 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                                 |
| **chunks sent and failed** | Confirmed by the API                                                                                                                     | Confirmed at the transport layer                                                                     |

### Where to find asynchronous errors

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:

1. Go to your Algolia application in the [Algolia dashboard](https://dashboard.algolia.com).
2. On the left sidebar, select <Icon icon="database" /> **Data sources**, then [**Connector Debugger**](https://dashboard.algolia.com/connectors/debugger).
3. Open the run that corresponds to your job execution.
4. Inspect events with status `failed` or `partial` for the per-record error details.

## Caveats

* **Performance overhead**: Algolia processes each Push request asynchronously, and the cartridge groups <Records /> 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 <Records /> fail asynchronously. Always cross-check the [Connector Debugger](https://dashboard.algolia.com/connectors/debugger) when reconciling product record counts.

## Switch back to the Search API

1. Go to **Merchant Tools > Algolia > Algolia**.
2. Set **Indexing API** to **Search API**.
3. Click **Apply**.

You don't need to clear **Analytics region**: the cartridge ignores it with the Search API selected.

## See also

* [Custom preferences](/doc/integration/salesforce-commerce-cloud-b2c/getting-started/custom-preferences)
* [Push to Algolia connector](/doc/guides/sending-and-managing-data/send-and-update-your-data/connectors/push)
* [Ingestion API reference](/doc/rest-api/ingestion)