Synchronize an external catalog

Outcome: an external catalog can be replayed into Thor without relying on exactly-once delivery or environment-specific Thor IDs.

Prerequisites

Define the source of truth, ownership per field, deletion policy, batch checkpoint, and a stable source identifier. Store the source identifier in namespaced metadata and maintain a mapping to Thor IDs per project.

1. Order dependencies

Write shared configuration before dependent resources:

Flow

Code in text

Do not publish incomplete products merely because their base row arrived first.

2. Use bounded operations

Read existing resources with cursor pagination and stable filters. Use bulk mutations only where the public API exposes them, keep each input at or below its documented limit, and treat each operation’s transaction/error contract independently. Inventory bulk create validates its batch and saves once; it is not a per-item partial-success loop.

Persist a checkpoint only after the destination operation and source mapping are durable. On a retry, query by the stored mapping or source metadata before creating another resource.

3. Update and delete deliberately

Patch fields owned by the integration without erasing merchant-owned values. For missing source records, choose archive, unpublish, or delete based on the resource lifecycle and downstream references. Never infer that source absence means safe deletion.

4. Recover and reconcile

Record rejected batches with safe input identifiers and typed errors. Correct the cause and replay the whole transactional batch or the exact supported failed unit. Run periodic reconciliation that compares source counts and identifiers with Thor; webhooks improve freshness but do not provide an exactly-once guarantee.

Verify a sample through the Admin API and the same Storefront context buyers use. See Bulk operations and import/export jobs and Errors and retries.