Skip to main content
This guide summarizes the core HTTP and gRPC contract for the Sync Server.

​
Base URLs & Versioning

  • HTTP base path: /v1
  • OpenAPI: /api-docs/openapi.json
  • Docs UI: /docs/ or /swagger-ui/
  • Responses include x-api-version and x-api-supported-versions

​
Response Envelopes

Success:
Error:

​
Error Codes (Common)

  • validation_failed
  • rate_limit_exceeded
  • integration_missing
  • upstream_error
  • internal_error

​
Idempotency

  • Order creation is idempotent on shopify_order_id
  • Write endpoints accept idempotency-key (cached for 24h)
  • Retries return idempotency-replayed: true
Keep the requestId from meta on every response, success or failure. It is the only handle that ties a call here to the downstream integration attempt it produced, and support cannot trace a failed sync without it. Log it before you branch on the result, not inside the error path — the calls that are hardest to explain later are the ones that returned 200.

​
Next steps

Full API contract

The complete HTTP and gRPC contract this summarises.

gRPC dispatch

Getting orders into the Sync Server durably.

gRPC flow

What happens to an order after it is accepted.

ACP guide

Protocol support built on this contract.
Last modified on August 29, 2026