Conventions

Wire conventions that hold for every control-plane operation.

These hold for every operation in the control-plane API.

Topic	Rule
Field names	`snake_case`, in requests and responses.
Tenant scoping	`merchant_id` and `store_id` are never path or query parameters. They are resolved server-side from the verified token (or connector HMAC credential).
List envelope	`{ "data": [...], "page": { "cursor": string \| null, "has_more": boolean } }`
Pagination	Cursor-based: pass `cursor`; `limit` caps page size.
Error envelope	Every non-2xx is `{ "error": { "code", "message", "details" } }`.
Idempotency	Mutating operations accept an `Idempotency-Key` header; a replay returns the original result.
Money	Integer minor units (cents) plus an ISO-4217 `currency`. Never floats.
Timestamps	RFC 3339 / ISO 8601, UTC.

Example

curl -s https://api.sarvex.example.com/v1/stores \
  -H "Authorization: Bearer $TOKEN"

{
  "data": [{ "id": "...", "name": "..." }],
  "page": { "cursor": null, "has_more": false }
}

{
  "error": {
    "code": "not_found",
    "message": "store not found",
    "details": null
  }
}

The server URLs in the spec (api.sarvex.example.com) are placeholders for your deployment’s API host.