Let's Pizza Developersv1.0.0

API reference

Orders

The order feed, acknowledgement, statuses, cancellations, facts (receipts, invoices, money collected) and payments.

GETThe order feed#

GET/partner/v1/orders

Scope 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.

Authentication
Partner key in the Authorization header
Scopes required
orders:read
curl -sS "$LP_BASE_URL/partner/v1/orders" \
  -H "Authorization: Bearer $LP_API_KEY"

Parameters

NameInTypeDescription
statequerystring
branchIdquerystring
updatedSincequerystring<date-time>ISO 8601 instant: only orders changed after it.
cursorquerystringThe nextCursor of the previous page.
limitqueryinteger

Responses

200OKPartnerOrderPage

Headers

NameTypeDescription
X-Request-IdstringThe 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-LimitintegerThe key's requests per minute.
RateLimit-RemainingintegerRequests left in the current minute.
RateLimit-ResetintegerSeconds until the minute window resets.

Schema

  • itemsPartnerOrder[]required
    Child attributes (8)
    • orderOrderrequired
      Child attributes (25)
      • idstringrequired

        length 1 – 64

      • numberstringrequired
      • statusstringrequired

        Values: "pending_payment""payment_failed""placed""accepted""preparing""ready""out_for_delivery""delivered""picked_up""cancelled""rejected""delivery_failed""not_collected"

      • channelstringrequired

        Values: "app""web""console""pos""dine_in"

      • branchIdstringrequired

        length 1 – 64

      • fulfilmentstringrequired

        Values: "delivery""pickup"

      • paymentMethodstringrequired

        Values: "pay_at_branch""cash_on_delivery""online"

      • catalogVersionstringrequired
      • linesOrderLine[]required
        Child attributes (5)
        • lineIndexintegerrequired

          value ≥ 0

        • lineCartLinerequired
          Child attributes (5)
          • productIdstringrequired

            length 1 – 64

          • qtyintegerrequired

            value ≥ 1

          • selectionsCartSelection[]required
            Child attributes (5)
            • groupIdstringrequired

              length 1 – 64

            • optionIdstringrequired

              length 1 – 64

            • qtyintegerrequired

              value ≥ 1

            • placementstringoptional

              Values: "whole""left""right"

            • amountstringoptional

              Values: "light""regular""extra"

          • notestringoptional

            length ≤ 200

          • sourceobjectoptional
            Child attributes (2)
            • experiencestringrequired

              Values: "classic""graphical"

            • modestringoptional

              length ≤ 32

        • unitPriceintegerrequired

          Amount in halalas (1 riyal = 100), VAT-inclusive

          value ≥ 0

        • lineTotalintegerrequired

          Amount in halalas (1 riyal = 100), VAT-inclusive

          value ≥ 0

        • snapshotLineSnapshotrequired
          Child attributes (2)
          • namesLocalizedrequired
            Child attributes (2)
            • arstringrequired
            • enstringrequired
          • optionsSnapshotOption[]required
            Child attributes (7)
            • groupIdstringrequired

              length 1 – 64

            • optionIdstringrequired

              length 1 – 64

            • namesLocalizedrequired
              Child attributes (2)
              • arstringrequired
              • enstringrequired
            • qtyintegerrequired

              value ≥ 1

            • priceintegerrequired

              Amount in halalas (1 riyal = 100), VAT-inclusive

              value ≥ 0

            • placementstringoptional

              Values: "whole""left""right"

            • amountstringoptional

              Values: "light""regular""extra"

      • subtotalintegerrequired

        Amount in halalas (1 riyal = 100), VAT-inclusive

        value ≥ 0

      • discountsDiscount[]required
        Child attributes (4)
        • kindstringrequired

          Values: "coupon""offer"

        • codestringoptional
        • namesLocalizedrequired
          Child attributes (2)
          • arstringrequired
          • enstringrequired
        • amountintegerrequired

          Amount in halalas (1 riyal = 100), VAT-inclusive

          value ≥ 0

      • discountTotalintegerrequired

        Amount in halalas (1 riyal = 100), VAT-inclusive

        value ≥ 0

      • deliveryFeeintegerrequired

        Amount in halalas (1 riyal = 100), VAT-inclusive

        value ≥ 0

      • totalintegerrequired

        Amount in halalas (1 riyal = 100), VAT-inclusive

        value ≥ 0

      • vatobjectrequired
        Child attributes (3)
        • rateBpsintegerrequired
        • amountintegerrequired

          Amount in halalas (1 riyal = 100), VAT-inclusive

          value ≥ 0

        • includesDeliveryFeebooleanrequired
      • scheduledForstring<date-time>optional
      • notestringoptional
      • cutlerybooleanoptional
      • ifUnavailablestringoptional
      • deliveryobjectoptional
        Child attributes (5)
        • addressstringrequired

          length 3 – 300

        • detailsstringoptional

          length ≤ 300

        • locationobjectoptional
          Child attributes (2)
          • latnumberrequired

            value -90 – 90

          • lngnumberrequired

            value -180 – 180

        • contactNamestringrequired

          length 1 – 80

        • contactPhonestringrequired

          length 9 – 20

      • courierobjectoptional
        Child attributes (2)
        • namestringrequired
        • phonestringoptional
      • tenderstringoptional
      • paidAtstring<date-time>optional
      • createdAtstring<date-time>required
      • historyStatusChange[]required
        Child attributes (7)
        • fromstringrequirednullable

          Values: "pending_payment""payment_failed""placed""accepted""preparing""ready""out_for_delivery""delivered""picked_up""cancelled""rejected""delivery_failed""not_collected"

        • tostringrequired

          Values: "pending_payment""payment_failed""placed""accepted""preparing""ready""out_for_delivery""delivered""picked_up""cancelled""rejected""delivery_failed""not_collected"

        • atstring<date-time>required
        • actorStatusChangeActorrequired

          Values: "customer""staff""system""payment""partner"

        • reasonstringoptional
        • reasonCodestringoptional
        • returnedToBranchbooleanoptional
    • statePartnerOrderStaterequired

      Values: "awaiting_ack""acked""closed"

    • ackDueAtstring<date-time>requirednullable
    • ackedAtstring<date-time>requirednullable
    • externalOrderNostringrequirednullable
    • externalReceiptNostringrequirednullable
    • externalPartnerOrderExternalrequired
      Child attributes (4)
      • branchCodestringrequirednullable
      • linesobject[]required
        Child attributes (5)
        • lineIndexintegerrequired

          value ≥ 0

        • codestringrequirednullable
        • variantstringrequirednullable
        • unitstringrequirednullable
        • optionsobject[]required
          Child attributes (4)
          • groupIdstringrequired

            length 1 – 64

          • optionIdstringrequired

            length 1 – 64

          • codestringrequirednullable
          • variantstringrequirednullable
      • tenderCodestringrequirednullable
      • unmappedobject[]required
        Child attributes (2)
        • kindPartnerMappingKindrequired

          Values: "branch""category""product""group""option""tender"

        • ourIdstringrequired
    • updatedAtstring<date-time>required
  • nextCursorstringrequirednullable
400INVALID_REQUEST (field: state, updatedSince, cursor, limit)PartnerError

Headers

NameTypeDescription
X-Request-IdstringThe 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

NameTypeDescription
X-Request-IdstringThe 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

NameTypeDescription
X-Request-IdstringThe 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

NameTypeDescription
X-Request-IdstringThe 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

NameTypeDescription
X-Request-IdstringThe 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

200 · PartnerOrderPage
{
  "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#

GET/partner/v1/orders/{id}

Scope orders:read.

Authentication
Partner key in the Authorization header
Scopes required
orders:read
curl -sS "$LP_BASE_URL/partner/v1/orders/7f3a2c10-5b8e-4d21-9c47-1a2b3c4d5e01" \
  -H "Authorization: Bearer $LP_API_KEY"

Parameters

NameInTypeDescription
id *pathstringThe Let's Pizza order id (order.id).

Responses

200OKPartnerOrder

Headers

NameTypeDescription
X-Request-IdstringThe 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-LimitintegerThe key's requests per minute.
RateLimit-RemainingintegerRequests left in the current minute.
RateLimit-ResetintegerSeconds until the minute window resets.

Schema

  • orderOrderrequired
    Child attributes (25)
    • idstringrequired

      length 1 – 64

    • numberstringrequired
    • statusstringrequired

      Values: "pending_payment""payment_failed""placed""accepted""preparing""ready""out_for_delivery""delivered""picked_up""cancelled""rejected""delivery_failed""not_collected"

    • channelstringrequired

      Values: "app""web""console""pos""dine_in"

    • branchIdstringrequired

      length 1 – 64

    • fulfilmentstringrequired

      Values: "delivery""pickup"

    • paymentMethodstringrequired

      Values: "pay_at_branch""cash_on_delivery""online"

    • catalogVersionstringrequired
    • linesOrderLine[]required
      Child attributes (5)
      • lineIndexintegerrequired

        value ≥ 0

      • lineCartLinerequired
        Child attributes (5)
        • productIdstringrequired

          length 1 – 64

        • qtyintegerrequired

          value ≥ 1

        • selectionsCartSelection[]required
          Child attributes (5)
          • groupIdstringrequired

            length 1 – 64

          • optionIdstringrequired

            length 1 – 64

          • qtyintegerrequired

            value ≥ 1

          • placementstringoptional

            Values: "whole""left""right"

          • amountstringoptional

            Values: "light""regular""extra"

        • notestringoptional

          length ≤ 200

        • sourceobjectoptional
          Child attributes (2)
          • experiencestringrequired

            Values: "classic""graphical"

          • modestringoptional

            length ≤ 32

      • unitPriceintegerrequired

        Amount in halalas (1 riyal = 100), VAT-inclusive

        value ≥ 0

      • lineTotalintegerrequired

        Amount in halalas (1 riyal = 100), VAT-inclusive

        value ≥ 0

      • snapshotLineSnapshotrequired
        Child attributes (2)
        • namesLocalizedrequired
          Child attributes (2)
          • arstringrequired
          • enstringrequired
        • optionsSnapshotOption[]required
          Child attributes (7)
          • groupIdstringrequired

            length 1 – 64

          • optionIdstringrequired

            length 1 – 64

          • namesLocalizedrequired
            Child attributes (2)
            • arstringrequired
            • enstringrequired
          • qtyintegerrequired

            value ≥ 1

          • priceintegerrequired

            Amount in halalas (1 riyal = 100), VAT-inclusive

            value ≥ 0

          • placementstringoptional

            Values: "whole""left""right"

          • amountstringoptional

            Values: "light""regular""extra"

    • subtotalintegerrequired

      Amount in halalas (1 riyal = 100), VAT-inclusive

      value ≥ 0

    • discountsDiscount[]required
      Child attributes (4)
      • kindstringrequired

        Values: "coupon""offer"

      • codestringoptional
      • namesLocalizedrequired
        Child attributes (2)
        • arstringrequired
        • enstringrequired
      • amountintegerrequired

        Amount in halalas (1 riyal = 100), VAT-inclusive

        value ≥ 0

    • discountTotalintegerrequired

      Amount in halalas (1 riyal = 100), VAT-inclusive

      value ≥ 0

    • deliveryFeeintegerrequired

      Amount in halalas (1 riyal = 100), VAT-inclusive

      value ≥ 0

    • totalintegerrequired

      Amount in halalas (1 riyal = 100), VAT-inclusive

      value ≥ 0

    • vatobjectrequired
      Child attributes (3)
      • rateBpsintegerrequired
      • amountintegerrequired

        Amount in halalas (1 riyal = 100), VAT-inclusive

        value ≥ 0

      • includesDeliveryFeebooleanrequired
    • scheduledForstring<date-time>optional
    • notestringoptional
    • cutlerybooleanoptional
    • ifUnavailablestringoptional
    • deliveryobjectoptional
      Child attributes (5)
      • addressstringrequired

        length 3 – 300

      • detailsstringoptional

        length ≤ 300

      • locationobjectoptional
        Child attributes (2)
        • latnumberrequired

          value -90 – 90

        • lngnumberrequired

          value -180 – 180

      • contactNamestringrequired

        length 1 – 80

      • contactPhonestringrequired

        length 9 – 20

    • courierobjectoptional
      Child attributes (2)
      • namestringrequired
      • phonestringoptional
    • tenderstringoptional
    • paidAtstring<date-time>optional
    • createdAtstring<date-time>required
    • historyStatusChange[]required
      Child attributes (7)
      • fromstringrequirednullable

        Values: "pending_payment""payment_failed""placed""accepted""preparing""ready""out_for_delivery""delivered""picked_up""cancelled""rejected""delivery_failed""not_collected"

      • tostringrequired

        Values: "pending_payment""payment_failed""placed""accepted""preparing""ready""out_for_delivery""delivered""picked_up""cancelled""rejected""delivery_failed""not_collected"

      • atstring<date-time>required
      • actorStatusChangeActorrequired

        Values: "customer""staff""system""payment""partner"

      • reasonstringoptional
      • reasonCodestringoptional
      • returnedToBranchbooleanoptional
  • statePartnerOrderStaterequired

    Values: "awaiting_ack""acked""closed"

  • ackDueAtstring<date-time>requirednullable
  • ackedAtstring<date-time>requirednullable
  • externalOrderNostringrequirednullable
  • externalReceiptNostringrequirednullable
  • externalPartnerOrderExternalrequired
    Child attributes (4)
    • branchCodestringrequirednullable
    • linesobject[]required
      Child attributes (5)
      • lineIndexintegerrequired

        value ≥ 0

      • codestringrequirednullable
      • variantstringrequirednullable
      • unitstringrequirednullable
      • optionsobject[]required
        Child attributes (4)
        • groupIdstringrequired

          length 1 – 64

        • optionIdstringrequired

          length 1 – 64

        • codestringrequirednullable
        • variantstringrequirednullable
    • tenderCodestringrequirednullable
    • unmappedobject[]required
      Child attributes (2)
      • kindPartnerMappingKindrequired

        Values: "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

NameTypeDescription
X-Request-IdstringThe 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

NameTypeDescription
X-Request-IdstringThe 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

NameTypeDescription
X-Request-IdstringThe 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

NameTypeDescription
X-Request-IdstringThe 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

NameTypeDescription
X-Request-IdstringThe 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

200 · PartnerOrder
{
  "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#

POST/partner/v1/orders/{id}/ack

Scope 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.

Authentication
Partner key in the Authorization header
Scopes required
orders:ack
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

NameInTypeDescription
id *pathstringThe Let's Pizza order id (order.id).
Idempotency-Key *headerstringYour 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

  • externalOrderNostringoptional

    length 1 – 50

  • externalReceiptNostringoptional

    length 1 – 50

Responses

200OKPartnerOrder

Headers

NameTypeDescription
X-Request-IdstringThe 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-LimitintegerThe key's requests per minute.
RateLimit-RemainingintegerRequests left in the current minute.
RateLimit-ResetintegerSeconds until the minute window resets.

Schema

  • orderOrderrequired
    Child attributes (25)
    • idstringrequired

      length 1 – 64

    • numberstringrequired
    • statusstringrequired

      Values: "pending_payment""payment_failed""placed""accepted""preparing""ready""out_for_delivery""delivered""picked_up""cancelled""rejected""delivery_failed""not_collected"

    • channelstringrequired

      Values: "app""web""console""pos""dine_in"

    • branchIdstringrequired

      length 1 – 64

    • fulfilmentstringrequired

      Values: "delivery""pickup"

    • paymentMethodstringrequired

      Values: "pay_at_branch""cash_on_delivery""online"

    • catalogVersionstringrequired
    • linesOrderLine[]required
      Child attributes (5)
      • lineIndexintegerrequired

        value ≥ 0

      • lineCartLinerequired
        Child attributes (5)
        • productIdstringrequired

          length 1 – 64

        • qtyintegerrequired

          value ≥ 1

        • selectionsCartSelection[]required
          Child attributes (5)
          • groupIdstringrequired

            length 1 – 64

          • optionIdstringrequired

            length 1 – 64

          • qtyintegerrequired

            value ≥ 1

          • placementstringoptional

            Values: "whole""left""right"

          • amountstringoptional

            Values: "light""regular""extra"

        • notestringoptional

          length ≤ 200

        • sourceobjectoptional
          Child attributes (2)
          • experiencestringrequired

            Values: "classic""graphical"

          • modestringoptional

            length ≤ 32

      • unitPriceintegerrequired

        Amount in halalas (1 riyal = 100), VAT-inclusive

        value ≥ 0

      • lineTotalintegerrequired

        Amount in halalas (1 riyal = 100), VAT-inclusive

        value ≥ 0

      • snapshotLineSnapshotrequired
        Child attributes (2)
        • namesLocalizedrequired
          Child attributes (2)
          • arstringrequired
          • enstringrequired
        • optionsSnapshotOption[]required
          Child attributes (7)
          • groupIdstringrequired

            length 1 – 64

          • optionIdstringrequired

            length 1 – 64

          • namesLocalizedrequired
            Child attributes (2)
            • arstringrequired
            • enstringrequired
          • qtyintegerrequired

            value ≥ 1

          • priceintegerrequired

            Amount in halalas (1 riyal = 100), VAT-inclusive

            value ≥ 0

          • placementstringoptional

            Values: "whole""left""right"

          • amountstringoptional

            Values: "light""regular""extra"

    • subtotalintegerrequired

      Amount in halalas (1 riyal = 100), VAT-inclusive

      value ≥ 0

    • discountsDiscount[]required
      Child attributes (4)
      • kindstringrequired

        Values: "coupon""offer"

      • codestringoptional
      • namesLocalizedrequired
        Child attributes (2)
        • arstringrequired
        • enstringrequired
      • amountintegerrequired

        Amount in halalas (1 riyal = 100), VAT-inclusive

        value ≥ 0

    • discountTotalintegerrequired

      Amount in halalas (1 riyal = 100), VAT-inclusive

      value ≥ 0

    • deliveryFeeintegerrequired

      Amount in halalas (1 riyal = 100), VAT-inclusive

      value ≥ 0

    • totalintegerrequired

      Amount in halalas (1 riyal = 100), VAT-inclusive

      value ≥ 0

    • vatobjectrequired
      Child attributes (3)
      • rateBpsintegerrequired
      • amountintegerrequired

        Amount in halalas (1 riyal = 100), VAT-inclusive

        value ≥ 0

      • includesDeliveryFeebooleanrequired
    • scheduledForstring<date-time>optional
    • notestringoptional
    • cutlerybooleanoptional
    • ifUnavailablestringoptional
    • deliveryobjectoptional
      Child attributes (5)
      • addressstringrequired

        length 3 – 300

      • detailsstringoptional

        length ≤ 300

      • locationobjectoptional
        Child attributes (2)
        • latnumberrequired

          value -90 – 90

        • lngnumberrequired

          value -180 – 180

      • contactNamestringrequired

        length 1 – 80

      • contactPhonestringrequired

        length 9 – 20

    • courierobjectoptional
      Child attributes (2)
      • namestringrequired
      • phonestringoptional
    • tenderstringoptional
    • paidAtstring<date-time>optional
    • createdAtstring<date-time>required
    • historyStatusChange[]required
      Child attributes (7)
      • fromstringrequirednullable

        Values: "pending_payment""payment_failed""placed""accepted""preparing""ready""out_for_delivery""delivered""picked_up""cancelled""rejected""delivery_failed""not_collected"

      • tostringrequired

        Values: "pending_payment""payment_failed""placed""accepted""preparing""ready""out_for_delivery""delivered""picked_up""cancelled""rejected""delivery_failed""not_collected"

      • atstring<date-time>required
      • actorStatusChangeActorrequired

        Values: "customer""staff""system""payment""partner"

      • reasonstringoptional
      • reasonCodestringoptional
      • returnedToBranchbooleanoptional
  • statePartnerOrderStaterequired

    Values: "awaiting_ack""acked""closed"

  • ackDueAtstring<date-time>requirednullable
  • ackedAtstring<date-time>requirednullable
  • externalOrderNostringrequirednullable
  • externalReceiptNostringrequirednullable
  • externalPartnerOrderExternalrequired
    Child attributes (4)
    • branchCodestringrequirednullable
    • linesobject[]required
      Child attributes (5)
      • lineIndexintegerrequired

        value ≥ 0

      • codestringrequirednullable
      • variantstringrequirednullable
      • unitstringrequirednullable
      • optionsobject[]required
        Child attributes (4)
        • groupIdstringrequired

          length 1 – 64

        • optionIdstringrequired

          length 1 – 64

        • codestringrequirednullable
        • variantstringrequirednullable
    • tenderCodestringrequirednullable
    • unmappedobject[]required
      Child attributes (2)
      • kindPartnerMappingKindrequired

        Values: "branch""category""product""group""option""tender"

      • ourIdstringrequired
  • updatedAtstring<date-time>required
400INVALID_REQUEST (field, detail.issues), IDEMPOTENCY_KEY_REQUIREDPartnerError

Headers

NameTypeDescription
X-Request-IdstringThe 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

NameTypeDescription
X-Request-IdstringThe 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

NameTypeDescription
X-Request-IdstringThe 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

NameTypeDescription
X-Request-IdstringThe 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

NameTypeDescription
X-Request-IdstringThe 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

NameTypeDescription
X-Request-IdstringThe 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

NameTypeDescription
X-Request-IdstringThe 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

200 · PartnerOrder
{
  "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#

POST/partner/v1/orders/{id}/status

Scope 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).

Authentication
Partner key in the Authorization header
Scopes required
orders:status
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

NameInTypeDescription
id *pathstringThe Let's Pizza order id (order.id).
Idempotency-Key *headerstringYour 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

  • eventIdstringrequired

    length 1 – 64

  • toPartnerStatusTargetrequired

    Values: "accepted""rejected""preparing""ready""picked_up""cancelled""out_for_delivery""delivered""delivery_failed"

  • expectedFromstringoptional

    Values: "pending_payment""payment_failed""placed""accepted""preparing""ready""out_for_delivery""delivered""picked_up""cancelled""rejected""delivery_failed""not_collected"

  • reasonCodestringoptional
  • reasonTextstringoptional

    length 1 – 300

  • occurredAtstring<date-time>required
  • estimatedReadyAtstring<date-time>optional

Responses

200OKPartnerStatusResult

Headers

NameTypeDescription
X-Request-IdstringThe 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-LimitintegerThe key's requests per minute.
RateLimit-RemainingintegerRequests left in the current minute.
RateLimit-ResetintegerSeconds until the minute window resets.

Schema

  • outcomestringrequired

    Values: "applied""duplicate""ignored""parked"

  • statusstringrequired

    Values: "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

NameTypeDescription
X-Request-IdstringThe 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

NameTypeDescription
X-Request-IdstringThe 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

NameTypeDescription
X-Request-IdstringThe 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

NameTypeDescription
X-Request-IdstringThe 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

NameTypeDescription
X-Request-IdstringThe 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

NameTypeDescription
X-Request-IdstringThe 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

NameTypeDescription
X-Request-IdstringThe 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

NameTypeDescription
X-Request-IdstringThe 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

200 · PartnerStatusResult
{
  "outcome": "applied",
  "status": "preparing",
  "reason": null
}

POSTCancel an order#

POST/partner/v1/orders/{id}/cancel

Scope 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.

Authentication
Partner key in the Authorization header
Scopes required
orders:cancel
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

NameInTypeDescription
id *pathstringThe Let's Pizza order id (order.id).
Idempotency-Key *headerstringYour 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

  • eventIdstringrequired

    length 1 – 64

  • reasonCodeExitReasonCoderequired

    Values: "customer_unreachable""wrong_address""customer_refused""accident_or_damage""kitchen_error""out_of_stock""customer_request""other"

  • reasonTextstringoptional

    length 1 – 300

  • occurredAtstring<date-time>required

Responses

200OKPartnerStatusResult

Headers

NameTypeDescription
X-Request-IdstringThe 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-LimitintegerThe key's requests per minute.
RateLimit-RemainingintegerRequests left in the current minute.
RateLimit-ResetintegerSeconds until the minute window resets.

Schema

  • outcomestringrequired

    Values: "applied""duplicate""ignored""parked"

  • statusstringrequired

    Values: "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

NameTypeDescription
X-Request-IdstringThe 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

NameTypeDescription
X-Request-IdstringThe 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

NameTypeDescription
X-Request-IdstringThe 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

NameTypeDescription
X-Request-IdstringThe 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

NameTypeDescription
X-Request-IdstringThe 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

NameTypeDescription
X-Request-IdstringThe 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

NameTypeDescription
X-Request-IdstringThe 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

200 · PartnerStatusResult
{
  "outcome": "applied",
  "status": "preparing",
  "reason": null
}

POSTRecord a fact on an order#

POST/partner/v1/orders/{id}/events

Scope orders:events. receipt_issued (receiptNo), invoice_issued (invoiceNo, optional ZATCA invoiceQr), payment_collected (amount in halalas, tender), note (note). Each eventId once.

Authentication
Partner key in the Authorization header
Scopes required
orders:events
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

NameInTypeDescription
id *pathstringThe Let's Pizza order id (order.id).
Idempotency-Key *headerstringYour 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

  • eventIdstringrequired

    length 1 – 64

  • typestringrequired

    Values: "receipt_issued""invoice_issued""payment_collected""note"

  • receiptNostringoptional

    length 1 – 50

  • invoiceNostringoptional

    length 1 – 50

  • invoiceQrstringoptional

    length ≤ 1000

  • amountintegeroptional

    Amount in halalas (1 riyal = 100), VAT-inclusive

    value ≥ 0

  • tenderstringoptional

    Values: "cash""card"

  • notestringoptional

    length 1 – 300

  • occurredAtstring<date-time>required

Responses

200OKPartnerOrderEventResult

Headers

NameTypeDescription
X-Request-IdstringThe 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-LimitintegerThe key's requests per minute.
RateLimit-RemainingintegerRequests left in the current minute.
RateLimit-ResetintegerSeconds until the minute window resets.

Schema

  • outcomestringrequired

    Values: "recorded""duplicate"

400INVALID_REQUEST (field, detail.issues), IDEMPOTENCY_KEY_REQUIREDPartnerError

Headers

NameTypeDescription
X-Request-IdstringThe 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

NameTypeDescription
X-Request-IdstringThe 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

NameTypeDescription
X-Request-IdstringThe 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

NameTypeDescription
X-Request-IdstringThe 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

NameTypeDescription
X-Request-IdstringThe 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

NameTypeDescription
X-Request-IdstringThe 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

NameTypeDescription
X-Request-IdstringThe 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

NameTypeDescription
X-Request-IdstringThe 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

200 · PartnerOrderEventResult
{
  "outcome": "recorded"
}

GETHow an order is paid#

GET/partner/v1/orders/{id}/payments

Scope payments:read. The method, what was paid and refunded (halalas), the online payment attempts and the refunds.

Authentication
Partner key in the Authorization header
Scopes required
payments:read
curl -sS "$LP_BASE_URL/partner/v1/orders/7f3a2c10-5b8e-4d21-9c47-1a2b3c4d5e01/payments" \
  -H "Authorization: Bearer $LP_API_KEY"

Parameters

NameInTypeDescription
id *pathstringThe Let's Pizza order id (order.id).

Responses

200OKPartnerOrderPayments

Headers

NameTypeDescription
X-Request-IdstringThe 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-LimitintegerThe key's requests per minute.
RateLimit-RemainingintegerRequests left in the current minute.
RateLimit-ResetintegerSeconds until the minute window resets.

Schema

  • orderIdstringrequired

    length 1 – 64

  • paymentMethodstringrequired

    Values: "pay_at_branch""cash_on_delivery""online"

  • totalintegerrequired

    Amount in halalas (1 riyal = 100), VAT-inclusive

    value ≥ 0

  • paidintegerrequired

    Amount in halalas (1 riyal = 100), VAT-inclusive

    value ≥ 0

  • refundedintegerrequired

    Amount in halalas (1 riyal = 100), VAT-inclusive

    value ≥ 0

  • attemptsobject[]required
    Child attributes (4)
    • idstringrequired

      length 1 – 64

    • statusstringrequired
    • amountintegerrequired

      Amount in halalas (1 riyal = 100), VAT-inclusive

      value ≥ 0

    • createdAtstring<date-time>required
  • refundsRefund[]required
    Child attributes (10)
    • idstringrequired

      length 1 – 64

    • orderIdstringrequired

      length 1 – 64

    • intentIdstringrequirednullable

      length 1 – 64

    • amountintegerrequired

      Amount in halalas (1 riyal = 100), VAT-inclusive

      value ≥ 0

    • reasonstringrequired

      Values: "cancelled_by_customer""cancelled_by_branch""rejected""item_unavailable""quality""other"

    • notestringoptional

      length ≤ 500

    • statusstringrequired

      Values: "requested""processing""succeeded""failed"

    • requestedBystringrequired

      length ≥ 1

    • createdAtstring<date-time>required
    • settledAtstring<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

NameTypeDescription
X-Request-IdstringThe 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

NameTypeDescription
X-Request-IdstringThe 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

NameTypeDescription
X-Request-IdstringThe 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

NameTypeDescription
X-Request-IdstringThe 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

NameTypeDescription
X-Request-IdstringThe 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

200 · PartnerOrderPayments
{
  "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"
    }
  ]
}