Get started
Conventions
Rules every call and answer follows. Read them once and save yourself many mistakes.
JSON and UTF-8#
Every body is JSON in UTF-8; Arabic text arrives as is. Send Content-Type: application/json with every write.
Money: integer halalas, VAT-inclusive#
Every amount is an integer number of halalas (1 riyal = 100) and includes 15 % VAT. No decimals, no rounding errors.
| In the API | Means |
|---|---|
4200 | 42 |
1487 | VAT inside 114: 14.87 |
14490 | 144.90 |
From an order priced by the real engine (branch At Takhassusi):
{
"subtotal": 9600,
"deliveryFee": 1800,
"total": 11400,
"vat": {
"rateBps": 1500,
"amount": 1487,
"includesDeliveryFee": true
}
}Texts in two languages#
Every customer-facing text comes as an object with Arabic and English. Show the one your user chose.
{
"ar": "التخصصي",
"en": "At Takhassusi"
}Times#
Times are ISO 8601 with an offset, such as 2026-11-19T19:30:12+03:00. Branches run on Riyadh time. Compare instants, never strings.
Ids and external codes#
Let's Pizza ids are stable and never reused: branch 28, product 649 (large Margherita). Your own codes are linked to them in a mapping table per environment, so neither side changes its ids.
Answers carry your code in fields such as externalCode, null until mapped.
Idempotency-Key on writes#
Every write carries an Idempotency-Key header (up to 128 characters). Repeating a call with the same key and body returns the first answer and does nothing twice, so you can retry safely after a network failure.
POST /partner/v1/orders/{id}/ack HTTP/1.1
Authorization: Bearer lpk_test_…
Idempotency-Key: 6f1d2c3e-0b8a-4f5e-9c7d-1a2b3c4d5e6f
Content-Type: application/json| Case | Answer |
|---|---|
| No key | IDEMPOTENCY_KEY_REQUIRED |
| Same key, same body | The first answer again |
| Same key, different body | IDEMPOTENCY_KEY_REUSED |
X-Request-Id#
Every answer carries X-Request-Id . You may send your own (8–64 of A-Z a-z 0-9 . _ -) to trace a call end to end; otherwise we make one. Log it with every error and quote it to support.
Cursor pagination#
Long lists are read page by page: the answer carries nextCursor; send it back as is in the next call until it is null. A cursor is opaque: never build or parse one.
{
"items": [
"…"
],
"nextCursor": "eyJhZnRlciI6MTA0Mn0"
}Versioning and deprecation#
The version is part of the path: /partner/v1. Within v1 we may add fields, endpoints, events and enum values: ignore what you do not know. Anything that breaks compatibility comes as /partner/v2, announced in advance.
A call that is going away carries Deprecation and Sunset (the end date), and is listed in the changelog.