Skip to main content

​
Sync Server API Basics

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: 
{
  "meta": { "requestId": "..." },
  "data": { "statesetOrderId": "..." }
}
Error: 
{
  "meta": { "requestId": "..." },
  "error": { "code": "validation_failed", "message": "..." }
}

​
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