API conventions

Versioning

• The major version is in the path: /v1.
• Additive changes are not breaking: new endpoints, fields, event types and enum values. Ignore fields you don’t recognize and handle unknown enum values gracefully.
• Breaking changes get a new major version, with at least 6 months of overlap. Every change is announced in the changelog.

Formats

Topic	Convention
Encoding	JSON, UTF-8
Field names	snake_case
IDs	Opaque prefixed strings (ord_…). Don’t parse them.
Time	ISO 8601 in UTC, e.g. 2026-10-04T12:30:00Z. Locations also have an IANA timezone.
Money	{ "amount": 4550, "currency": "SAR" }. The amount is in minor units (halalas).
Text in two languages	{ "en": "…", "ar": "…" }; either may be null
Missing data	null, never invented

Pagination

List endpoints take limit (1–100, default 50) and return a cursor:

{ "data": [ … ], "next_cursor": "eyJpZCI6Im9yZF8…" }

Pass next_cursor as cursor to get the next page. It is null on the last page.

Rate limits

Limits apply per application. The default in the developer preview is 20 requests per second, with bursts up to 50. Every response carries:

Header	Meaning
RateLimit-Limit	Requests allowed in the current window
RateLimit-Remaining	Requests left
RateLimit-Reset	Seconds until the window resets

Over the limit, you get 429 with Retry-After. Prefer webhooks to frequent polling; they’re faster and don’t use your limit.

Request headers

Header	When
Authorization: Bearer <token>	Always
Loops-Merchant-Id: mer_…	Always for platform applications
Idempotency-Key: <uuid>	On write requests (coming with write endpoints)

Response headers

Header	Meaning
Loops-Request-Id	Unique request ID. Log it and quote it to support.