Copy page

Commerce Partners

Catalog Integration

The Commerce API uses a Pull Model for catalog synchronization, and ingestion is asynchronous — you notify Gett, then poll for the outcome.

Notify, then poll

1. Host your CatalogSet JSON at a publicly reachable URL.
2. POST /catalogset-notification?storeId=… with { "callbackUrl": "…" }. Gett responds 202 Accepted with a body — { "catalogIngestId", "statusUrl" } — and a Retry-After header. The 202 only means accepted, not ingested.
3. Poll statusUrl (GET /v1/commerce/stores/{storeId}/catalog-ingest/{catalogIngestId}/status), honoring Retry-After, until the run reaches a terminal state.

Ingest status lifecycle

status moves through:

Status	Meaning
queued	Accepted; not yet started.
pulling	Downloading the CatalogSet from your callbackUrl.
processing	Validating and building the store catalog.
succeeded	The store now serves the new catalog.
failed	Ingestion did not complete — see errors.

A run reaches succeeded only when the store actually flips to the new catalog, so polling to succeeded is a reliable confirmation. On failed, errors[] carries sanitized, partner-safe reasons (e.g. an unreachable callbackUrl, or a CatalogSet whose references don't resolve).

Optional: catalog sync webhooks

If you'd rather not poll, configure a Webhook Base URL (the same one used for Order Webhooks) and Gett will push the terminal outcome to {baseUrl}/catalog-sync as soon as the ingest finishes. The webhook is optional and best-effort — polling the statusUrl remains the authoritative signal, so treat the push as a latency optimization, not a guarantee. With no Webhook Base URL configured, nothing is sent.

Two event types fire, both as a Standard Webhooks envelope (type / timestamp / data):

type	Fires when	data.errors
catalog.sync.succeeded	The store flipped to your new catalog.	empty
catalog.sync.failed	A pull / validation / generation stage failed.	the same sanitized reasons as the poll

data.catalogIngestId matches the id from the original 202, so you can correlate the push to your notification:

Code
{
  "type": "catalog.sync.succeeded",
  "timestamp": "2026-06-17T12:00:00.000Z",
  "data": {
    "catalogIngestId": "018f4d2a-c5b0-7c4e-9b3a-2d1e8f7a6b5c",
    "storeId": "7c3a1e90-2b4d-4f8a-9c1e-5a6b7c8d9e0f",
    "status": "succeeded",
    "errors": []
  }
}

Code
{
  "type": "catalog.sync.failed",
  "timestamp": "2026-06-17T12:00:00.000Z",
  "data": {
    "catalogIngestId": "018f4d2a-c5b0-7c4e-9b3a-2d1e8f7a6b5c",
    "storeId": "7c3a1e90-2b4d-4f8a-9c1e-5a6b7c8d9e0f",
    "status": "failed",
    "errors": [
      { "path": "sections.{id}.itemIds[2]", "message": "Item id not present in Items" }
    ]
  }
}

These are signed exactly like the order webhooks — the same Authorization + Standard Webhooks headers and the same whsec_… signing secret — so verify them with the identical code (see Security — Standard Webhooks signing). webhook-id (and Idempotency-Key) equal data.catalogIngestId, so a redelivery is trivially deduplicated. Acknowledge with any 2xx. The envelope schema is in the Commerce API Reference (CatalogSyncWebhook); both event types are also listed under Webhooks on the reference overview.

Failure modes to handle

• Unknown store — the POST returns 404 if the storeId isn't registered to your partner account.
• Unreachable / slow callbackUrl — the pull times out and the run ends failed. Make sure the URL is publicly reachable and returns the catalog JSON promptly.
• Invalid CatalogSet — Gett rejects a catalog whose cross-references don't resolve (e.g. an item ID referenced by a section but absent from the items dictionary). The run ends failed and the store keeps serving its previous catalog (fail-closed). Validate against the schema before notifying.

For the machine-readable contract — request/response schemas, parameters, and a try-it console — see Notify Catalog Update and Get Catalog Ingest Status in the Commerce API Reference.