API reference
Orders
The order feed, acknowledgement, statuses, cancellations, facts (receipts, invoices, money collected) and payments.
GETThe order feed#
/partner/v1/ordersScope orders:read. Your orders, oldest change first. An order becomes yours when your settings say (placed if you accept orders, accepted if Let's Pizza accepts them first, ready for a delivery fleet), at your live branches. Poll with state=awaiting_ack (default) and acknowledge each; or follow everything with state=all and the last nextCursor (or updatedSince): any change of an order (a status, your acknowledgement) brings it back.
curl -sS "$LP_BASE_URL/partner/v1/orders" \
-H "Authorization: Bearer $LP_API_KEY"Parameters
| Name | In | Type | Description |
|---|---|---|---|
state | query | string | |
branchId | query | string | |
updatedSince | query | string<date-time> | ISO 8601 instant: only orders changed after it. |
cursor | query | string | The nextCursor of the previous page. |
limit | query | integer |
Responses
200OKPartnerOrderPage
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
itemsPartnerOrder[]requiredChild attributes (8)
orderOrderrequiredChild attributes (25)
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
statePartnerOrderStaterequiredValues:
"awaiting_ack""acked""closed"ackDueAtstring<date-time>requirednullableackedAtstring<date-time>requirednullableexternalOrderNostringrequirednullableexternalReceiptNostringrequirednullableexternalPartnerOrderExternalrequiredChild attributes (4)
branchCodestringrequirednullablelinesobject[]requiredChild attributes (5)
lineIndexintegerrequiredvalue ≥ 0
codestringrequirednullablevariantstringrequirednullableunitstringrequirednullableoptionsobject[]requiredChild attributes (4)
groupIdstringrequiredlength 1 – 64
optionIdstringrequiredlength 1 – 64
codestringrequirednullablevariantstringrequirednullable
tenderCodestringrequirednullableunmappedobject[]requiredChild attributes (2)
kindPartnerMappingKindrequiredValues:
"branch""category""product""group""option""tender"ourIdstringrequired
updatedAtstring<date-time>required
nextCursorstringrequirednullable
400INVALID_REQUEST (field: state, updatedSince, cursor, limit)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. |
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. |
403PARTNER_SUSPENDED, IP_NOT_ALLOWED, SCOPE_REQUIRED (detail.required lists the scopes), BRANCH_NOT_ALLOWEDPartnerError
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
{
"items": [
{
"order": {
"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"
}
]
},
"state": "awaiting_ack",
"ackDueAt": "2026-11-19T19:30:12+03:00",
"ackedAt": null,
"externalOrderNo": null,
"externalReceiptNo": null,
"external": {
"branchCode": "string",
"lines": [
{
"lineIndex": 0,
"code": "string",
"variant": "string",
"unit": "string",
"options": [
{
"groupId": "string",
"optionId": "string",
"code": "string",
"variant": "string"
}
]
}
],
"tenderCode": "string",
"unmapped": [
{
"kind": "branch",
"ourId": "string"
}
]
},
"updatedAt": "2026-11-19T19:30:12+03:00"
}
],
"nextCursor": null
}GETOne order of the feed#
/partner/v1/orders/{id}Scope orders:read.
curl -sS "$LP_BASE_URL/partner/v1/orders/7f3a2c10-5b8e-4d21-9c47-1a2b3c4d5e01" \
-H "Authorization: Bearer $LP_API_KEY"Parameters
| Name | In | Type | Description |
|---|---|---|---|
id * | path | string | The Let's Pizza order id (order.id). |
Responses
200OKPartnerOrder
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
orderOrderrequiredChild attributes (25)
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
statePartnerOrderStaterequiredValues:
"awaiting_ack""acked""closed"ackDueAtstring<date-time>requirednullableackedAtstring<date-time>requirednullableexternalOrderNostringrequirednullableexternalReceiptNostringrequirednullableexternalPartnerOrderExternalrequiredChild attributes (4)
branchCodestringrequirednullablelinesobject[]requiredChild attributes (5)
lineIndexintegerrequiredvalue ≥ 0
codestringrequirednullablevariantstringrequirednullableunitstringrequirednullableoptionsobject[]requiredChild attributes (4)
groupIdstringrequiredlength 1 – 64
optionIdstringrequiredlength 1 – 64
codestringrequirednullablevariantstringrequirednullable
tenderCodestringrequirednullableunmappedobject[]requiredChild attributes (2)
kindPartnerMappingKindrequiredValues:
"branch""category""product""group""option""tender"ourIdstringrequired
updatedAtstring<date-time>required
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. |
403PARTNER_SUSPENDED, IP_NOT_ALLOWED, SCOPE_REQUIRED (detail.required lists the scopes), BRANCH_NOT_ALLOWEDPartnerError
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. |
404ORDER_NOT_FOUND: not one of your orders (or not at your branches)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
{
"order": {
"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"
}
]
},
"state": "awaiting_ack",
"ackDueAt": "2026-11-19T19:30:12+03:00",
"ackedAt": null,
"externalOrderNo": null,
"externalReceiptNo": null,
"external": {
"branchCode": "string",
"lines": [
{
"lineIndex": 0,
"code": "string",
"variant": "string",
"unit": "string",
"options": [
{
"groupId": "string",
"optionId": "string",
"code": "string",
"variant": "string"
}
]
}
],
"tenderCode": "string",
"unmapped": [
{
"kind": "branch",
"ourId": "string"
}
]
},
"updatedAt": "2026-11-19T19:30:12+03:00"
}POSTAcknowledge an order#
/partner/v1/orders/{id}/ackScope orders:ack. The order reached your system. Send your own numbers when you have them. Acknowledge within settings.orders.ackMinutes or Let's Pizza is alerted (order.ack_overdue). A repeat with the same numbers answers the same; other numbers are 409 ACK_CONFLICT. Answers the order as it is now.
curl -sS -X POST "$LP_BASE_URL/partner/v1/orders/7f3a2c10-5b8e-4d21-9c47-1a2b3c4d5e01/ack" \
-H "Authorization: Bearer $LP_API_KEY" \
-H "Idempotency-Key: $(uuidgen)" \
-H "Content-Type: application/json" \
--data '{
"externalOrderNo": "WEB-ORD-000123"
}'Parameters
| Name | In | Type | Description |
|---|---|---|---|
id * | path | string | The Let's Pizza order id (order.id). |
Idempotency-Key * | header | string | Your unique id of this request (≤ 128 characters). A repeat with the same key and body returns the first answer; the same key with another body is 422 IDEMPOTENCY_KEY_REUSED. |
Request body AckOrderRequest
externalOrderNostringoptionallength 1 – 50
externalReceiptNostringoptionallength 1 – 50
Responses
200OKPartnerOrder
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
orderOrderrequiredChild attributes (25)
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
statePartnerOrderStaterequiredValues:
"awaiting_ack""acked""closed"ackDueAtstring<date-time>requirednullableackedAtstring<date-time>requirednullableexternalOrderNostringrequirednullableexternalReceiptNostringrequirednullableexternalPartnerOrderExternalrequiredChild attributes (4)
branchCodestringrequirednullablelinesobject[]requiredChild attributes (5)
lineIndexintegerrequiredvalue ≥ 0
codestringrequirednullablevariantstringrequirednullableunitstringrequirednullableoptionsobject[]requiredChild attributes (4)
groupIdstringrequiredlength 1 – 64
optionIdstringrequiredlength 1 – 64
codestringrequirednullablevariantstringrequirednullable
tenderCodestringrequirednullableunmappedobject[]requiredChild attributes (2)
kindPartnerMappingKindrequiredValues:
"branch""category""product""group""option""tender"ourIdstringrequired
updatedAtstring<date-time>required
400INVALID_REQUEST (field, detail.issues), IDEMPOTENCY_KEY_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. |
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. |
403PARTNER_SUSPENDED, IP_NOT_ALLOWED, SCOPE_REQUIRED (detail.required lists the scopes), BRANCH_NOT_ALLOWEDPartnerError
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. |
404ORDER_NOT_FOUND: not one of your orders (or not at your branches)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. |
409ACK_CONFLICT (detail.current)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
{
"order": {
"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"
}
]
},
"state": "awaiting_ack",
"ackDueAt": "2026-11-19T19:30:12+03:00",
"ackedAt": null,
"externalOrderNo": null,
"externalReceiptNo": null,
"external": {
"branchCode": "string",
"lines": [
{
"lineIndex": 0,
"code": "string",
"variant": "string",
"unit": "string",
"options": [
{
"groupId": "string",
"optionId": "string",
"code": "string",
"variant": "string"
}
]
}
],
"tenderCode": "string",
"unmapped": [
{
"kind": "branch",
"ourId": "string"
}
]
},
"updatedAt": "2026-11-19T19:30:12+03:00"
}POSTReport a status#
/partner/v1/orders/{id}/statusScope orders:status; to must be in your settings.orders.statuses. The order moves forward only, through the steps between (a ready before preparing passes both); one behind it is ignored; a finished order never moves. rejected applies from placed, cancelled from placed or accepted: later they are parked for a person. delivery_failed needs a reasonCode (or reasonText). Each eventId is applied once (duplicate).
curl -sS -X POST "$LP_BASE_URL/partner/v1/orders/7f3a2c10-5b8e-4d21-9c47-1a2b3c4d5e01/status" \
-H "Authorization: Bearer $LP_API_KEY" \
-H "Idempotency-Key: $(uuidgen)" \
-H "Content-Type: application/json" \
--data '{
"eventId": "BC-EVT-000985",
"to": "preparing",
"expectedFrom": "accepted",
"occurredAt": "2026-11-19T19:35:02+03:00",
"estimatedReadyAt": "2026-11-19T19:50:00+03:00"
}'Parameters
| Name | In | Type | Description |
|---|---|---|---|
id * | path | string | The Let's Pizza order id (order.id). |
Idempotency-Key * | header | string | Your unique id of this request (≤ 128 characters). A repeat with the same key and body returns the first answer; the same key with another body is 422 IDEMPOTENCY_KEY_REUSED. |
Request body PartnerStatusRequest
eventIdstringrequiredlength 1 – 64
toPartnerStatusTargetrequiredValues:
"accepted""rejected""preparing""ready""picked_up""cancelled""out_for_delivery""delivered""delivery_failed"expectedFromstringoptionalValues:
"pending_payment""payment_failed""placed""accepted""preparing""ready""out_for_delivery""delivered""picked_up""cancelled""rejected""delivery_failed""not_collected"reasonCodestringoptionalreasonTextstringoptionallength 1 – 300
occurredAtstring<date-time>requiredestimatedReadyAtstring<date-time>optional
Responses
200OKPartnerStatusResult
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
outcomestringrequiredValues:
"applied""duplicate""ignored""parked"statusstringrequiredValues:
"pending_payment""payment_failed""placed""accepted""preparing""ready""out_for_delivery""delivered""picked_up""cancelled""rejected""delivery_failed""not_collected"reasonstringrequirednullable
400INVALID_REQUEST (field, detail.issues), IDEMPOTENCY_KEY_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. |
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. |
403STATUS_NOT_ALLOWED (detail.allowed), PARTNER_SUSPENDED, IP_NOT_ALLOWED, SCOPE_REQUIRED, BRANCH_NOT_ALLOWEDPartnerError
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. |
404ORDER_NOT_FOUND: not one of your orders (or not at your branches)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. |
409STATUS_CHANGED (expectedFrom no longer true; detail.current), BRANCH_NOT_LIVE, EVENT_ID_REUSED (the eventId belongs to another order)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. |
422REASON_REQUIRED, IDEMPOTENCY_KEY_REUSEDPartnerError
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
{
"outcome": "applied",
"status": "preparing",
"reason": null
}POSTCancel an order#
/partner/v1/orders/{id}/cancelScope orders:cancel. Applies before the kitchen starts (placed, accepted); later it is parked and Let’s Pizza staff decide (the food may be made and paid). Same answer and rules as a status.
curl -sS -X POST "$LP_BASE_URL/partner/v1/orders/7f3a2c10-5b8e-4d21-9c47-1a2b3c4d5e01/cancel" \
-H "Authorization: Bearer $LP_API_KEY" \
-H "Idempotency-Key: $(uuidgen)" \
-H "Content-Type: application/json" \
--data '{
"eventId": "BC-EVT-000985",
"reasonCode": "customer_request",
"reasonText": "العميل اتصل بالفرع وألغى الطلب",
"occurredAt": "2026-11-19T19:35:02+03:00"
}'Parameters
| Name | In | Type | Description |
|---|---|---|---|
id * | path | string | The Let's Pizza order id (order.id). |
Idempotency-Key * | header | string | Your unique id of this request (≤ 128 characters). A repeat with the same key and body returns the first answer; the same key with another body is 422 IDEMPOTENCY_KEY_REUSED. |
Request body PartnerCancelRequest
eventIdstringrequiredlength 1 – 64
reasonCodeExitReasonCoderequiredValues:
"customer_unreachable""wrong_address""customer_refused""accident_or_damage""kitchen_error""out_of_stock""customer_request""other"reasonTextstringoptionallength 1 – 300
occurredAtstring<date-time>required
Responses
200OKPartnerStatusResult
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
outcomestringrequiredValues:
"applied""duplicate""ignored""parked"statusstringrequiredValues:
"pending_payment""payment_failed""placed""accepted""preparing""ready""out_for_delivery""delivered""picked_up""cancelled""rejected""delivery_failed""not_collected"reasonstringrequirednullable
400INVALID_REQUEST (field, detail.issues), IDEMPOTENCY_KEY_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. |
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. |
403PARTNER_SUSPENDED, IP_NOT_ALLOWED, SCOPE_REQUIRED (detail.required lists the scopes), BRANCH_NOT_ALLOWEDPartnerError
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. |
404ORDER_NOT_FOUND: not one of your orders (or not at your branches)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. |
409BRANCH_NOT_LIVE, EVENT_ID_REUSEDPartnerError
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
{
"outcome": "applied",
"status": "preparing",
"reason": null
}POSTRecord a fact on an order#
/partner/v1/orders/{id}/eventsScope orders:events. receipt_issued (receiptNo), invoice_issued (invoiceNo, optional ZATCA invoiceQr), payment_collected (amount in halalas, tender), note (note). Each eventId once.
curl -sS -X POST "$LP_BASE_URL/partner/v1/orders/7f3a2c10-5b8e-4d21-9c47-1a2b3c4d5e01/events" \
-H "Authorization: Bearer $LP_API_KEY" \
-H "Idempotency-Key: $(uuidgen)" \
-H "Content-Type: application/json" \
--data '{
"eventId": "BC-EVT-000985",
"type": "payment_collected",
"amount": 11400,
"tender": "cash",
"occurredAt": "2026-11-19T19:35:02+03:00"
}'Parameters
| Name | In | Type | Description |
|---|---|---|---|
id * | path | string | The Let's Pizza order id (order.id). |
Idempotency-Key * | header | string | Your unique id of this request (≤ 128 characters). A repeat with the same key and body returns the first answer; the same key with another body is 422 IDEMPOTENCY_KEY_REUSED. |
Request body PartnerOrderEventRequest
eventIdstringrequiredlength 1 – 64
typestringrequiredValues:
"receipt_issued""invoice_issued""payment_collected""note"receiptNostringoptionallength 1 – 50
invoiceNostringoptionallength 1 – 50
invoiceQrstringoptionallength ≤ 1000
amountintegeroptionalAmount in halalas (1 riyal = 100), VAT-inclusive
value ≥ 0
tenderstringoptionalValues:
"cash""card"notestringoptionallength 1 – 300
occurredAtstring<date-time>required
Responses
200OKPartnerOrderEventResult
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
outcomestringrequiredValues:
"recorded""duplicate"
400INVALID_REQUEST (field, detail.issues), IDEMPOTENCY_KEY_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. |
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. |
403PARTNER_SUSPENDED, IP_NOT_ALLOWED, SCOPE_REQUIRED (detail.required lists the scopes), BRANCH_NOT_ALLOWEDPartnerError
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. |
404ORDER_NOT_FOUND: not one of your orders (or not at your branches)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. |
409EVENT_ID_REUSEDPartnerError
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. |
422FIELD_REQUIRED (field), IDEMPOTENCY_KEY_REUSEDPartnerError
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
{
"outcome": "recorded"
}GETHow an order is paid#
/partner/v1/orders/{id}/paymentsScope payments:read. The method, what was paid and refunded (halalas), the online payment attempts and the refunds.
curl -sS "$LP_BASE_URL/partner/v1/orders/7f3a2c10-5b8e-4d21-9c47-1a2b3c4d5e01/payments" \
-H "Authorization: Bearer $LP_API_KEY"Parameters
| Name | In | Type | Description |
|---|---|---|---|
id * | path | string | The Let's Pizza order id (order.id). |
Responses
200OKPartnerOrderPayments
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
orderIdstringrequiredlength 1 – 64
paymentMethodstringrequiredValues:
"pay_at_branch""cash_on_delivery""online"totalintegerrequiredAmount in halalas (1 riyal = 100), VAT-inclusive
value ≥ 0
paidintegerrequiredAmount in halalas (1 riyal = 100), VAT-inclusive
value ≥ 0
refundedintegerrequiredAmount in halalas (1 riyal = 100), VAT-inclusive
value ≥ 0
attemptsobject[]requiredChild attributes (4)
idstringrequiredlength 1 – 64
statusstringrequiredamountintegerrequiredAmount in halalas (1 riyal = 100), VAT-inclusive
value ≥ 0
createdAtstring<date-time>required
refundsRefund[]requiredChild attributes (10)
idstringrequiredlength 1 – 64
orderIdstringrequiredlength 1 – 64
intentIdstringrequirednullablelength 1 – 64
amountintegerrequiredAmount in halalas (1 riyal = 100), VAT-inclusive
value ≥ 0
reasonstringrequiredValues:
"cancelled_by_customer""cancelled_by_branch""rejected""item_unavailable""quality""other"notestringoptionallength ≤ 500
statusstringrequiredValues:
"requested""processing""succeeded""failed"requestedBystringrequiredlength ≥ 1
createdAtstring<date-time>requiredsettledAtstring<date-time>optional
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. |
403PARTNER_SUSPENDED, IP_NOT_ALLOWED, SCOPE_REQUIRED (detail.required lists the scopes), BRANCH_NOT_ALLOWEDPartnerError
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. |
404ORDER_NOT_FOUND: not one of your orders (or not at your branches)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
{
"orderId": "7f3a2c10-5b8e-4d21-9c47-1a2b3c4d5e01",
"paymentMethod": "pay_at_branch",
"total": 0,
"paid": 0,
"refunded": 0,
"attempts": [
{
"id": "7f3a2c10-5b8e-4d21-9c47-1a2b3c4d5e01",
"status": "string",
"amount": 0,
"createdAt": "2026-11-19T19:30:12+03:00"
}
],
"refunds": [
{
"id": "7f3a2c10-5b8e-4d21-9c47-1a2b3c4d5e01",
"orderId": "7f3a2c10-5b8e-4d21-9c47-1a2b3c4d5e01",
"intentId": "string",
"amount": 0,
"reason": "cancelled_by_customer",
"note": "string",
"status": "requested",
"requestedBy": "string",
"createdAt": "2026-11-19T19:30:12+03:00",
"settledAt": "2026-11-19T19:30:12+03:00"
}
]
}