Full catalog sync

When to use a replace session

Upserts and deletes change the documents you name. They cannot remove a product you forgot to delete. A replace session makes the index hold exactly what you send: you open it, send the whole catalog in batches and commit. Search switches to the new catalog in one step, and every document you did not send is gone.

Use a replace session when:

• your shop exports the full catalog on a schedule, for example every night, and you have no reliable list of deleted products;
• the index has drifted from the shop and you want a clean copy;
• you changed the mapping and want to rebuild from your source data instead of from the stored documents.

Use upserts and deletes for changes during the day. They are cheaper, and they keep working while a session is open.

How a session works

Opening a session builds a new, empty version of the index next to the live one, with the saved mapping. Search keeps using the live version the whole time.

• Batches sent to the session go to the new version only.
• Normal upserts and deletes sent while the session is open go to both versions, so they survive the commit.
• Commit waits until every batch is written, then swaps search to the new version in one step.

The index's status is REINDEXING while the session is open, and its buildingVersion is the session's version.

Run a sync

curl -X POST https://api.search.zaproo.cloud/v1/projects/$PROJECT_ID/indices/$INDEX_ID/replace-sessions \
  -H "Authorization: Bearer $ZS_KEY"

{
  "id": "5d2c9a40-8a51-4c3e-b8f1-2f6d0e7c9b13",
  "version": 4,
  "status": "OPEN",
  "expiresAt": "2026-10-16T15:30:00.000Z",
  "commitTaskId": null
}

curl -X POST https://api.search.zaproo.cloud/v1/projects/$PROJECT_ID/indices/$INDEX_ID/replace-sessions/$SESSION_ID/documents \
  -H "Authorization: Bearer $ZS_KEY" -H "Content-Type: application/json" \
  -H "Idempotency-Key: nightly-2026-10-16-batch-1" \
  -d '[{"id": "tape-48", "title": "Brown packaging tape 48mm", "price": 1.86}]'

Watch a session

In the cabinet, open the index, then Fields & mapping. While a session is OPEN or COMMITTING, the Reindex panel at the top says so, with the session's version and when it expires. The index overview shows the same panel while a version is being built. The session's batch and commit tasks are listed on Tasks.

The Reindex panel sits at the top of Fields & mapping, and lists an open session there

With the API:

The index itself names its open session in openReplaceSessionId. The session's status is one of:

Abort a session

Aborting drops the new version and cancels batches that have not finished. Search never sees any of it.

curl -X POST https://api.search.zaproo.cloud/v1/projects/$PROJECT_ID/indices/$INDEX_ID/replace-sessions/$SESSION_ID/abort \
  -H "Authorization: Bearer $ZS_KEY"

Session lifetime

A session expires 6 hours after it was opened, counted from the open, not from the last batch. Within a minute of expiresAt, an open session becomes EXPIRED and its new version is dropped. Commit before then. A session that is already committing does not expire.

Errors

Common mistakes

• Committing before every batch task has finished without errors. Commit waits for the batches, but it does not check their results. Failed documents are missing from the new catalog.
• Opening a session and never committing it. The index stays REINDEXING, and no reindex or breaking mapping change can start until the session expires 6 hours later. Abort it instead.
• Running a full sync for a handful of changes. Upserts are enough, and they do not block other builds.

Related

• Documents and tasks
• Reindex and versions
• Data source
• Follow a task