A complete snapshot is the recommended initial import and periodic synchronization mechanism for POS integrations.
catalog_id is your identifier and is unique only within the location. It may be reused for another restaurant.
The snapshot is authoritative. Send every category, product, modifier group, modifier, and bundle.
An entity omitted from a later successful snapshot is deleted. Send an empty array when a
collection must become empty.
Submit a snapshot
The request requires an Idempotency-Key. Array order becomes display order. A product may set an explicit non-negative order; products without one are placed after explicitly ordered products in their category, preserving their snapshot order.
The server validates IDs, references, selection bounds, prices, currency, and size before accepting the work. IDs may contain letters, numbers, ., _, :, and -, have a maximum length of 128 characters, and cannot be changed later.
Poll synchronization status
A valid request returns 202 Accepted, a catalog_sync object, and a Location header.
Poll the URL from Location until status is succeeded or failed. Use bounded exponential backoff starting at the Retry-After value. Repeating the original request with the same idempotency key and body returns the same synchronization; reusing that key with another body returns an idempotency conflict.
The last successfully committed catalog remains readable while a new snapshot is queued. Submit a new snapshot only after the previous synchronization becomes terminal.
Replacement rules
Matching uses your IDs, preserving Chataigne’s private database relationships. A snapshot is authoritative for every public field. Omitting description or image_url clears it. Omitting operational fields applies their safe defaults: disabled: false, out_of_stock: false, restrictions: [], price_overrides: [], and bundle_only: false. Empty rule arrays clear existing rules.
Private fields that remain outside this API version—such as best-seller state, tax, delivery-package data, provider metadata, settings, and promotions—are preserved on matching entities.
Complete imports and the material database step of granular writes for one catalog are serialized. Public snapshot image preparation remains outside that critical section. Granular changes are not merged with a queued snapshot in V1: a granular write that commits before the snapshot’s material step is reflected in its authoritative replacement, while one that reaches the mutation boundary after the snapshot owns the lease waits for a bounded interval and commits afterward. If the catalog remains busy, the granular request returns 409 catalog_sync_lock_timeout and can be retried. The last committed write wins. 
