Application API

For partner applications: browse merchants and products, hand customers a checkout link, and follow the orders it creates.

Getting started

Responses and errors

One envelope for every paginated list, and a stable key on every validation error so you never parse a message.

Common response envelope

Every paginated endpoint returns:

Paginated list

{
    "data": [],
    "hasMore": true,
    "totalPages": 12,
    "totalCount": 230
}

Notes

/products adds a search_id field reserved for search analytics. It is currently always null — ignore it.
/reject-reasons and /states are reference lists and return only { 'data': [...] }.
Single-resource endpoints (/products/{slug}, /orders/{id}, cancel) return { 'data': {...} }.

Naming gotcha

The merchants endpoint's search parameter is q; every other endpoint uses query.

Errors

Status	When	Body
400	A request parameter failed validation	`{ "key", "message", "errors" }` — see below
400	A business rule refused the request (checkout token checks)	`{ "message": "…" }`
401	Authentication failed	`{ "message": "…" }` — see Authentication → Constraints
404	Resource not found, or not yours	`{ "message": "…" }` or `{ "key", "message" }`
422	A cancellation was refused	`{ "key", "message" }`
503	A dependency is temporarily unavailable (`/states` only)	`{ "message": "…" }`

Validation errors are 400, not 422

Response 400

{
    "key": "errors.validation.page_size.max",
    "message": "لا يمكن أن تكون page size أكبر من 100.",
    "errors": {
        "page_size": [
            "لا يمكن أن تكون page size أكبر من 100."
        ]
    }
}

Notes

Branch on key. It is stable and names the first failing field and rule: errors.validation.<field>.<rule>. message is a human sentence in the request's locale and changes with it — never parse it.
errors is the standard field → messages map, for marking individual inputs.
Every invalid parameter — a bad sort_by, an out-of-range page_size, non-CSV categories, an unknown category_id or client_id — comes back as 400. Do not test for 422 here.

Previous Visibility model Next Merchants