API reference
Sandbox
Tools that exist on the sandbox only: test orders.
POSTPlace a test order#
/partner/v1/sandbox/ordersSandbox only (403 SANDBOX_ONLY on production). Scopes orders:read and orders:status. A real order on the sandbox, made the way a customer’s is (quote, then order), so it reaches your feed, your webhooks and your connector like any order — at a branch your key may act on. Lines absent = one Margherita. Then move it with your status calls, or let the sandbox branch staff do it.
curl -sS -X POST "$LP_BASE_URL/partner/v1/sandbox/orders" \
-H "Authorization: Bearer $LP_API_KEY" \
-H "Content-Type: application/json" \
--data '{
"branchId": "28",
"fulfilment": "pickup",
"paymentMethod": "pay_at_branch"
}'Request body PartnerSandboxOrderRequest
branchIdstringrequiredlength 1 – 64
fulfilmentstringrequiredValues:
"pickup""delivery"linesCartLine[]optionalitems 1 – 20
Child attributes (5)
productIdstringrequiredlength 1 – 64
qtyintegerrequiredvalue ≥ 1
selectionsCartSelection[]requiredChild attributes (5)
groupIdstringrequiredlength 1 – 64
optionIdstringrequiredlength 1 – 64
qtyintegerrequiredvalue ≥ 1
placementstringoptionalValues:
"whole""left""right"amountstringoptionalValues:
"light""regular""extra"
notestringoptionallength ≤ 200
sourceobjectoptionalChild attributes (2)
experiencestringrequiredValues:
"classic""graphical"modestringoptionallength ≤ 32
paymentMethodstringoptionalValues:
"pay_at_branch""cash_on_delivery"deliveryobjectoptionalChild attributes (5)
addressstringrequiredlength 3 – 300
detailsstringoptionallength ≤ 300
locationobjectoptionalChild attributes (2)
latnumberrequiredvalue -90 – 90
lngnumberrequiredvalue -180 – 180
contactNamestringrequiredlength 1 – 80
contactPhonestringrequiredlength 9 – 20
Responses
201CreatedOrder
Headers
| Name | Type | Description |
|---|---|---|
X-Request-Id | string | The id of this request: quote it to support. Send your own (8–64 of A-Z a-z 0-9 . _ -) to trace a call end to end. |
RateLimit-Limit | integer | The key's requests per minute. |
RateLimit-Remaining | integer | Requests left in the current minute. |
RateLimit-Reset | integer | Seconds until the minute window resets. |
Schema
idstringrequiredlength 1 – 64
numberstringrequiredstatusstringrequiredValues:
"pending_payment""payment_failed""placed""accepted""preparing""ready""out_for_delivery""delivered""picked_up""cancelled""rejected""delivery_failed""not_collected"channelstringrequiredValues:
"app""web""console""pos""dine_in"branchIdstringrequiredlength 1 – 64
fulfilmentstringrequiredValues:
"delivery""pickup"paymentMethodstringrequiredValues:
"pay_at_branch""cash_on_delivery""online"catalogVersionstringrequiredlinesOrderLine[]requiredChild attributes (5)
lineIndexintegerrequiredvalue ≥ 0
lineCartLinerequiredChild attributes (5)
productIdstringrequiredlength 1 – 64
qtyintegerrequiredvalue ≥ 1
selectionsCartSelection[]requiredChild attributes (5)
groupIdstringrequiredlength 1 – 64
optionIdstringrequiredlength 1 – 64
qtyintegerrequiredvalue ≥ 1
placementstringoptionalValues:
"whole""left""right"amountstringoptionalValues:
"light""regular""extra"
notestringoptionallength ≤ 200
sourceobjectoptionalChild attributes (2)
experiencestringrequiredValues:
"classic""graphical"modestringoptionallength ≤ 32
unitPriceintegerrequiredAmount in halalas (1 riyal = 100), VAT-inclusive
value ≥ 0
lineTotalintegerrequiredAmount in halalas (1 riyal = 100), VAT-inclusive
value ≥ 0
snapshotLineSnapshotrequiredChild attributes (2)
namesLocalizedrequiredChild attributes (2)
arstringrequiredenstringrequired
optionsSnapshotOption[]requiredChild attributes (7)
groupIdstringrequiredlength 1 – 64
optionIdstringrequiredlength 1 – 64
namesLocalizedrequiredChild attributes (2)
arstringrequiredenstringrequired
qtyintegerrequiredvalue ≥ 1
priceintegerrequiredAmount in halalas (1 riyal = 100), VAT-inclusive
value ≥ 0
placementstringoptionalValues:
"whole""left""right"amountstringoptionalValues:
"light""regular""extra"
subtotalintegerrequiredAmount in halalas (1 riyal = 100), VAT-inclusive
value ≥ 0
discountsDiscount[]requiredChild attributes (4)
kindstringrequiredValues:
"coupon""offer"codestringoptionalnamesLocalizedrequiredChild attributes (2)
arstringrequiredenstringrequired
amountintegerrequiredAmount in halalas (1 riyal = 100), VAT-inclusive
value ≥ 0
discountTotalintegerrequiredAmount in halalas (1 riyal = 100), VAT-inclusive
value ≥ 0
deliveryFeeintegerrequiredAmount in halalas (1 riyal = 100), VAT-inclusive
value ≥ 0
totalintegerrequiredAmount in halalas (1 riyal = 100), VAT-inclusive
value ≥ 0
vatobjectrequiredChild attributes (3)
rateBpsintegerrequiredamountintegerrequiredAmount in halalas (1 riyal = 100), VAT-inclusive
value ≥ 0
includesDeliveryFeebooleanrequired
scheduledForstring<date-time>optionalnotestringoptionalcutlerybooleanoptionalifUnavailablestringoptionaldeliveryobjectoptionalChild attributes (5)
addressstringrequiredlength 3 – 300
detailsstringoptionallength ≤ 300
locationobjectoptionalChild attributes (2)
latnumberrequiredvalue -90 – 90
lngnumberrequiredvalue -180 – 180
contactNamestringrequiredlength 1 – 80
contactPhonestringrequiredlength 9 – 20
courierobjectoptionalChild attributes (2)
namestringrequiredphonestringoptional
tenderstringoptionalpaidAtstring<date-time>optionalcreatedAtstring<date-time>requiredhistoryStatusChange[]requiredChild attributes (7)
fromstringrequirednullableValues:
"pending_payment""payment_failed""placed""accepted""preparing""ready""out_for_delivery""delivered""picked_up""cancelled""rejected""delivery_failed""not_collected"tostringrequiredValues:
"pending_payment""payment_failed""placed""accepted""preparing""ready""out_for_delivery""delivered""picked_up""cancelled""rejected""delivery_failed""not_collected"atstring<date-time>requiredactorStatusChangeActorrequiredValues:
"customer""staff""system""payment""partner"reasonstringoptionalreasonCodestringoptionalreturnedToBranchbooleanoptional
401UNAUTHENTICATED (no key, a wrong or revoked one), KEY_EXPIRED, KEY_ENVIRONMENT_MISMATCH (a test key on production or the other way round)PartnerError
Headers
| Name | Type | Description |
|---|---|---|
X-Request-Id | string | The id of this request: quote it to support. Send your own (8–64 of A-Z a-z 0-9 . _ -) to trace a call end to end. |
403SANDBOX_ONLY, BRANCH_NOT_ALLOWED, SCOPE_REQUIREDPartnerError
Headers
| Name | Type | Description |
|---|---|---|
X-Request-Id | string | The id of this request: quote it to support. Send your own (8–64 of A-Z a-z 0-9 . _ -) to trace a call end to end. |
422SANDBOX_QUOTE_INVALID (detail.errors: the quote’s codes, e.g. BRANCH_CLOSED)PartnerError
Headers
| Name | Type | Description |
|---|---|---|
X-Request-Id | string | The id of this request: quote it to support. Send your own (8–64 of A-Z a-z 0-9 . _ -) to trace a call end to end. |
429RATE_LIMITED: wait Retry-After seconds (also in detail.retryAfterSeconds)PartnerError
Headers
| Name | Type | Description |
|---|---|---|
X-Request-Id | string | The id of this request: quote it to support. Send your own (8–64 of A-Z a-z 0-9 . _ -) to trace a call end to end. |
500INTERNAL_ERROR: retryable; quote the X-Request-Id if it persistsPartnerError
Headers
| Name | Type | Description |
|---|---|---|
X-Request-Id | string | The id of this request: quote it to support. Send your own (8–64 of A-Z a-z 0-9 . _ -) to trace a call end to end. |
Example response
{
"id": "7f3a2c10-5b8e-4d21-9c47-1a2b3c4d5e01",
"number": "261119-0041",
"status": "placed",
"channel": "app",
"branchId": "28",
"fulfilment": "delivery",
"paymentMethod": "cash_on_delivery",
"catalogVersion": "taker-2026-10-06.5d01b76bc1",
"lines": [
{
"lineIndex": 0,
"line": {
"productId": "649",
"qty": 2,
"selections": [
{
"groupId": "1362",
"optionId": "11836",
"qty": 1
}
],
"source": {
"experience": "classic"
}
},
"unitPrice": 4200,
"lineTotal": 8400,
"snapshot": {
"names": {
"ar": "مارقريتا",
"en": "Margherita Pizza"
},
"options": [
{
"groupId": "1362",
"optionId": "11836",
"names": {
"ar": "صلصة طماطم",
"en": "Tomato Sauce"
},
"qty": 1,
"price": 0
}
]
}
},
{
"lineIndex": 1,
"line": {
"productId": "740",
"qty": 2,
"selections": [],
"source": {
"experience": "classic"
}
},
"unitPrice": 600,
"lineTotal": 1200,
"snapshot": {
"names": {
"ar": "كولا",
"en": "Coca Cola Can"
},
"options": []
}
}
],
"subtotal": 9600,
"discounts": [],
"discountTotal": 0,
"deliveryFee": 1800,
"total": 11400,
"vat": {
"rateBps": 1500,
"amount": 1487,
"includesDeliveryFee": true
},
"cutlery": false,
"ifUnavailable": "call",
"delivery": {
"address": "حي المعذر الشمالي، شارع الأمير سلطان، عمارة 14",
"details": "الدور الثاني، شقة 5، بجوار الصيدلية",
"location": {
"lat": 24.6921,
"lng": 46.6853
},
"contactName": "عبدالله",
"contactPhone": "+966500000000"
},
"createdAt": "2026-11-19T19:30:12+03:00",
"history": [
{
"from": null,
"to": "placed",
"at": "2026-11-19T19:30:12+03:00",
"actor": "customer"
}
]
}