مطوّرو ليتس بيتزاv1.0.0

مرجع الواجهة

الطلبات

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.

المصادقة
مفتاح الشريك في ترويسة Authorization
الصلاحيات المطلوبة
orders:read
curl -sS "$LP_BASE_URL/partner/v1/orders" \
  -H "Authorization: Bearer $LP_API_KEY"

المعاملات

الاسمالموضعالنوعالوصف
statequerystring
branchIdquerystring
updatedSincequerystring<date-time>ISO 8601 instant: only orders changed after it.
cursorquerystringThe nextCursor of the previous page.
limitqueryinteger

الردود

200OKPartnerOrderPage

الترويسات

الاسمالنوعالوصف
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.

البنية

  • itemsPartnerOrder[]مطلوب
    الحقول الداخلية (8)
    • orderOrderمطلوب
      الحقول الداخلية (25)
      • idstringمطلوب

        الطول: 1 – 64

      • numberstringمطلوب
      • statusstringمطلوب

        القيم: "pending_payment""payment_failed""placed""accepted""preparing""ready""out_for_delivery""delivered""picked_up""cancelled""rejected""delivery_failed""not_collected"

      • channelstringمطلوب

        القيم: "app""web""console""pos""dine_in"

      • branchIdstringمطلوب

        الطول: 1 – 64

      • fulfilmentstringمطلوب

        القيم: "delivery""pickup"

      • paymentMethodstringمطلوب

        القيم: "pay_at_branch""cash_on_delivery""online"

      • catalogVersionstringمطلوب
      • linesOrderLine[]مطلوب
        الحقول الداخلية (5)
        • lineIndexintegerمطلوب

          القيمة: ≥ 0

        • lineCartLineمطلوب
          الحقول الداخلية (5)
          • productIdstringمطلوب

            الطول: 1 – 64

          • qtyintegerمطلوب

            القيمة: ≥ 1

          • selectionsCartSelection[]مطلوب
            الحقول الداخلية (5)
            • groupIdstringمطلوب

              الطول: 1 – 64

            • optionIdstringمطلوب

              الطول: 1 – 64

            • qtyintegerمطلوب

              القيمة: ≥ 1

            • placementstringاختياري

              القيم: "whole""left""right"

            • amountstringاختياري

              القيم: "light""regular""extra"

          • notestringاختياري

            الطول: ≤ 200

          • sourceobjectاختياري
            الحقول الداخلية (2)
            • experiencestringمطلوب

              القيم: "classic""graphical"

            • modestringاختياري

              الطول: ≤ 32

        • unitPriceintegerمطلوب

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

          القيمة: ≥ 0

        • lineTotalintegerمطلوب

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

          القيمة: ≥ 0

        • snapshotLineSnapshotمطلوب
          الحقول الداخلية (2)
          • namesLocalizedمطلوب
            الحقول الداخلية (2)
            • arstringمطلوب
            • enstringمطلوب
          • optionsSnapshotOption[]مطلوب
            الحقول الداخلية (7)
            • groupIdstringمطلوب

              الطول: 1 – 64

            • optionIdstringمطلوب

              الطول: 1 – 64

            • namesLocalizedمطلوب
              الحقول الداخلية (2)
              • arstringمطلوب
              • enstringمطلوب
            • qtyintegerمطلوب

              القيمة: ≥ 1

            • priceintegerمطلوب

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

              القيمة: ≥ 0

            • placementstringاختياري

              القيم: "whole""left""right"

            • amountstringاختياري

              القيم: "light""regular""extra"

      • subtotalintegerمطلوب

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

        القيمة: ≥ 0

      • discountsDiscount[]مطلوب
        الحقول الداخلية (4)
        • kindstringمطلوب

          القيم: "coupon""offer"

        • codestringاختياري
        • namesLocalizedمطلوب
          الحقول الداخلية (2)
          • arstringمطلوب
          • enstringمطلوب
        • amountintegerمطلوب

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

          القيمة: ≥ 0

      • discountTotalintegerمطلوب

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

        القيمة: ≥ 0

      • deliveryFeeintegerمطلوب

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

        القيمة: ≥ 0

      • totalintegerمطلوب

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

        القيمة: ≥ 0

      • vatobjectمطلوب
        الحقول الداخلية (3)
        • rateBpsintegerمطلوب
        • amountintegerمطلوب

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

          القيمة: ≥ 0

        • includesDeliveryFeebooleanمطلوب
      • scheduledForstring<date-time>اختياري
      • notestringاختياري
      • cutlerybooleanاختياري
      • ifUnavailablestringاختياري
      • deliveryobjectاختياري
        الحقول الداخلية (5)
        • addressstringمطلوب

          الطول: 3 – 300

        • detailsstringاختياري

          الطول: ≤ 300

        • locationobjectاختياري
          الحقول الداخلية (2)
          • latnumberمطلوب

            القيمة: -90 – 90

          • lngnumberمطلوب

            القيمة: -180 – 180

        • contactNamestringمطلوب

          الطول: 1 – 80

        • contactPhonestringمطلوب

          الطول: 9 – 20

      • courierobjectاختياري
        الحقول الداخلية (2)
        • namestringمطلوب
        • phonestringاختياري
      • tenderstringاختياري
      • paidAtstring<date-time>اختياري
      • createdAtstring<date-time>مطلوب
      • historyStatusChange[]مطلوب
        الحقول الداخلية (7)
        • fromstringمطلوبيقبل null

          القيم: "pending_payment""payment_failed""placed""accepted""preparing""ready""out_for_delivery""delivered""picked_up""cancelled""rejected""delivery_failed""not_collected"

        • tostringمطلوب

          القيم: "pending_payment""payment_failed""placed""accepted""preparing""ready""out_for_delivery""delivered""picked_up""cancelled""rejected""delivery_failed""not_collected"

        • atstring<date-time>مطلوب
        • actorStatusChangeActorمطلوب

          القيم: "customer""staff""system""payment""partner"

        • reasonstringاختياري
        • reasonCodestringاختياري
        • returnedToBranchbooleanاختياري
    • statePartnerOrderStateمطلوب

      القيم: "awaiting_ack""acked""closed"

    • ackDueAtstring<date-time>مطلوبيقبل null
    • ackedAtstring<date-time>مطلوبيقبل null
    • externalOrderNostringمطلوبيقبل null
    • externalReceiptNostringمطلوبيقبل null
    • externalPartnerOrderExternalمطلوب
      الحقول الداخلية (4)
      • branchCodestringمطلوبيقبل null
      • linesobject[]مطلوب
        الحقول الداخلية (5)
        • lineIndexintegerمطلوب

          القيمة: ≥ 0

        • codestringمطلوبيقبل null
        • variantstringمطلوبيقبل null
        • unitstringمطلوبيقبل null
        • optionsobject[]مطلوب
          الحقول الداخلية (4)
          • groupIdstringمطلوب

            الطول: 1 – 64

          • optionIdstringمطلوب

            الطول: 1 – 64

          • codestringمطلوبيقبل null
          • variantstringمطلوبيقبل null
      • tenderCodestringمطلوبيقبل null
      • unmappedobject[]مطلوب
        الحقول الداخلية (2)
        • kindPartnerMappingKindمطلوب

          القيم: "branch""category""product""group""option""tender"

        • ourIdstringمطلوب
    • updatedAtstring<date-time>مطلوب
  • nextCursorstringمطلوبيقبل null
400INVALID_REQUEST (field: state, updatedSince, cursor, limit)PartnerError

الترويسات

الاسمالنوعالوصف
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

الترويسات

الاسمالنوعالوصف
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

الترويسات

الاسمالنوعالوصف
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

الترويسات

الاسمالنوعالوصف
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

الترويسات

الاسمالنوعالوصف
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.

مثال الرد

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.

المصادقة
مفتاح الشريك في ترويسة Authorization
الصلاحيات المطلوبة
orders:read
curl -sS "$LP_BASE_URL/partner/v1/orders/7f3a2c10-5b8e-4d21-9c47-1a2b3c4d5e01" \
  -H "Authorization: Bearer $LP_API_KEY"

المعاملات

الاسمالموضعالنوعالوصف
id *pathstringThe Let's Pizza order id (order.id).

الردود

200OKPartnerOrder

الترويسات

الاسمالنوعالوصف
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.

البنية

  • orderOrderمطلوب
    الحقول الداخلية (25)
    • idstringمطلوب

      الطول: 1 – 64

    • numberstringمطلوب
    • statusstringمطلوب

      القيم: "pending_payment""payment_failed""placed""accepted""preparing""ready""out_for_delivery""delivered""picked_up""cancelled""rejected""delivery_failed""not_collected"

    • channelstringمطلوب

      القيم: "app""web""console""pos""dine_in"

    • branchIdstringمطلوب

      الطول: 1 – 64

    • fulfilmentstringمطلوب

      القيم: "delivery""pickup"

    • paymentMethodstringمطلوب

      القيم: "pay_at_branch""cash_on_delivery""online"

    • catalogVersionstringمطلوب
    • linesOrderLine[]مطلوب
      الحقول الداخلية (5)
      • lineIndexintegerمطلوب

        القيمة: ≥ 0

      • lineCartLineمطلوب
        الحقول الداخلية (5)
        • productIdstringمطلوب

          الطول: 1 – 64

        • qtyintegerمطلوب

          القيمة: ≥ 1

        • selectionsCartSelection[]مطلوب
          الحقول الداخلية (5)
          • groupIdstringمطلوب

            الطول: 1 – 64

          • optionIdstringمطلوب

            الطول: 1 – 64

          • qtyintegerمطلوب

            القيمة: ≥ 1

          • placementstringاختياري

            القيم: "whole""left""right"

          • amountstringاختياري

            القيم: "light""regular""extra"

        • notestringاختياري

          الطول: ≤ 200

        • sourceobjectاختياري
          الحقول الداخلية (2)
          • experiencestringمطلوب

            القيم: "classic""graphical"

          • modestringاختياري

            الطول: ≤ 32

      • unitPriceintegerمطلوب

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

        القيمة: ≥ 0

      • lineTotalintegerمطلوب

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

        القيمة: ≥ 0

      • snapshotLineSnapshotمطلوب
        الحقول الداخلية (2)
        • namesLocalizedمطلوب
          الحقول الداخلية (2)
          • arstringمطلوب
          • enstringمطلوب
        • optionsSnapshotOption[]مطلوب
          الحقول الداخلية (7)
          • groupIdstringمطلوب

            الطول: 1 – 64

          • optionIdstringمطلوب

            الطول: 1 – 64

          • namesLocalizedمطلوب
            الحقول الداخلية (2)
            • arstringمطلوب
            • enstringمطلوب
          • qtyintegerمطلوب

            القيمة: ≥ 1

          • priceintegerمطلوب

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

            القيمة: ≥ 0

          • placementstringاختياري

            القيم: "whole""left""right"

          • amountstringاختياري

            القيم: "light""regular""extra"

    • subtotalintegerمطلوب

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

      القيمة: ≥ 0

    • discountsDiscount[]مطلوب
      الحقول الداخلية (4)
      • kindstringمطلوب

        القيم: "coupon""offer"

      • codestringاختياري
      • namesLocalizedمطلوب
        الحقول الداخلية (2)
        • arstringمطلوب
        • enstringمطلوب
      • amountintegerمطلوب

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

        القيمة: ≥ 0

    • discountTotalintegerمطلوب

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

      القيمة: ≥ 0

    • deliveryFeeintegerمطلوب

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

      القيمة: ≥ 0

    • totalintegerمطلوب

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

      القيمة: ≥ 0

    • vatobjectمطلوب
      الحقول الداخلية (3)
      • rateBpsintegerمطلوب
      • amountintegerمطلوب

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

        القيمة: ≥ 0

      • includesDeliveryFeebooleanمطلوب
    • scheduledForstring<date-time>اختياري
    • notestringاختياري
    • cutlerybooleanاختياري
    • ifUnavailablestringاختياري
    • deliveryobjectاختياري
      الحقول الداخلية (5)
      • addressstringمطلوب

        الطول: 3 – 300

      • detailsstringاختياري

        الطول: ≤ 300

      • locationobjectاختياري
        الحقول الداخلية (2)
        • latnumberمطلوب

          القيمة: -90 – 90

        • lngnumberمطلوب

          القيمة: -180 – 180

      • contactNamestringمطلوب

        الطول: 1 – 80

      • contactPhonestringمطلوب

        الطول: 9 – 20

    • courierobjectاختياري
      الحقول الداخلية (2)
      • namestringمطلوب
      • phonestringاختياري
    • tenderstringاختياري
    • paidAtstring<date-time>اختياري
    • createdAtstring<date-time>مطلوب
    • historyStatusChange[]مطلوب
      الحقول الداخلية (7)
      • fromstringمطلوبيقبل null

        القيم: "pending_payment""payment_failed""placed""accepted""preparing""ready""out_for_delivery""delivered""picked_up""cancelled""rejected""delivery_failed""not_collected"

      • tostringمطلوب

        القيم: "pending_payment""payment_failed""placed""accepted""preparing""ready""out_for_delivery""delivered""picked_up""cancelled""rejected""delivery_failed""not_collected"

      • atstring<date-time>مطلوب
      • actorStatusChangeActorمطلوب

        القيم: "customer""staff""system""payment""partner"

      • reasonstringاختياري
      • reasonCodestringاختياري
      • returnedToBranchbooleanاختياري
  • statePartnerOrderStateمطلوب

    القيم: "awaiting_ack""acked""closed"

  • ackDueAtstring<date-time>مطلوبيقبل null
  • ackedAtstring<date-time>مطلوبيقبل null
  • externalOrderNostringمطلوبيقبل null
  • externalReceiptNostringمطلوبيقبل null
  • externalPartnerOrderExternalمطلوب
    الحقول الداخلية (4)
    • branchCodestringمطلوبيقبل null
    • linesobject[]مطلوب
      الحقول الداخلية (5)
      • lineIndexintegerمطلوب

        القيمة: ≥ 0

      • codestringمطلوبيقبل null
      • variantstringمطلوبيقبل null
      • unitstringمطلوبيقبل null
      • optionsobject[]مطلوب
        الحقول الداخلية (4)
        • groupIdstringمطلوب

          الطول: 1 – 64

        • optionIdstringمطلوب

          الطول: 1 – 64

        • codestringمطلوبيقبل null
        • variantstringمطلوبيقبل null
    • tenderCodestringمطلوبيقبل null
    • unmappedobject[]مطلوب
      الحقول الداخلية (2)
      • kindPartnerMappingKindمطلوب

        القيم: "branch""category""product""group""option""tender"

      • ourIdstringمطلوب
  • updatedAtstring<date-time>مطلوب
401UNAUTHENTICATED (no key, a wrong or revoked one), KEY_EXPIRED, KEY_ENVIRONMENT_MISMATCH (a test key on production or the other way round)PartnerError

الترويسات

الاسمالنوعالوصف
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

الترويسات

الاسمالنوعالوصف
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

الترويسات

الاسمالنوعالوصف
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

الترويسات

الاسمالنوعالوصف
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

الترويسات

الاسمالنوعالوصف
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.

مثال الرد

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.

المصادقة
مفتاح الشريك في ترويسة Authorization
الصلاحيات المطلوبة
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"
}'

المعاملات

الاسمالموضعالنوعالوصف
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.

جسم الطلب AckOrderRequest

  • externalOrderNostringاختياري

    الطول: 1 – 50

  • externalReceiptNostringاختياري

    الطول: 1 – 50

الردود

200OKPartnerOrder

الترويسات

الاسمالنوعالوصف
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.

البنية

  • orderOrderمطلوب
    الحقول الداخلية (25)
    • idstringمطلوب

      الطول: 1 – 64

    • numberstringمطلوب
    • statusstringمطلوب

      القيم: "pending_payment""payment_failed""placed""accepted""preparing""ready""out_for_delivery""delivered""picked_up""cancelled""rejected""delivery_failed""not_collected"

    • channelstringمطلوب

      القيم: "app""web""console""pos""dine_in"

    • branchIdstringمطلوب

      الطول: 1 – 64

    • fulfilmentstringمطلوب

      القيم: "delivery""pickup"

    • paymentMethodstringمطلوب

      القيم: "pay_at_branch""cash_on_delivery""online"

    • catalogVersionstringمطلوب
    • linesOrderLine[]مطلوب
      الحقول الداخلية (5)
      • lineIndexintegerمطلوب

        القيمة: ≥ 0

      • lineCartLineمطلوب
        الحقول الداخلية (5)
        • productIdstringمطلوب

          الطول: 1 – 64

        • qtyintegerمطلوب

          القيمة: ≥ 1

        • selectionsCartSelection[]مطلوب
          الحقول الداخلية (5)
          • groupIdstringمطلوب

            الطول: 1 – 64

          • optionIdstringمطلوب

            الطول: 1 – 64

          • qtyintegerمطلوب

            القيمة: ≥ 1

          • placementstringاختياري

            القيم: "whole""left""right"

          • amountstringاختياري

            القيم: "light""regular""extra"

        • notestringاختياري

          الطول: ≤ 200

        • sourceobjectاختياري
          الحقول الداخلية (2)
          • experiencestringمطلوب

            القيم: "classic""graphical"

          • modestringاختياري

            الطول: ≤ 32

      • unitPriceintegerمطلوب

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

        القيمة: ≥ 0

      • lineTotalintegerمطلوب

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

        القيمة: ≥ 0

      • snapshotLineSnapshotمطلوب
        الحقول الداخلية (2)
        • namesLocalizedمطلوب
          الحقول الداخلية (2)
          • arstringمطلوب
          • enstringمطلوب
        • optionsSnapshotOption[]مطلوب
          الحقول الداخلية (7)
          • groupIdstringمطلوب

            الطول: 1 – 64

          • optionIdstringمطلوب

            الطول: 1 – 64

          • namesLocalizedمطلوب
            الحقول الداخلية (2)
            • arstringمطلوب
            • enstringمطلوب
          • qtyintegerمطلوب

            القيمة: ≥ 1

          • priceintegerمطلوب

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

            القيمة: ≥ 0

          • placementstringاختياري

            القيم: "whole""left""right"

          • amountstringاختياري

            القيم: "light""regular""extra"

    • subtotalintegerمطلوب

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

      القيمة: ≥ 0

    • discountsDiscount[]مطلوب
      الحقول الداخلية (4)
      • kindstringمطلوب

        القيم: "coupon""offer"

      • codestringاختياري
      • namesLocalizedمطلوب
        الحقول الداخلية (2)
        • arstringمطلوب
        • enstringمطلوب
      • amountintegerمطلوب

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

        القيمة: ≥ 0

    • discountTotalintegerمطلوب

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

      القيمة: ≥ 0

    • deliveryFeeintegerمطلوب

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

      القيمة: ≥ 0

    • totalintegerمطلوب

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

      القيمة: ≥ 0

    • vatobjectمطلوب
      الحقول الداخلية (3)
      • rateBpsintegerمطلوب
      • amountintegerمطلوب

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

        القيمة: ≥ 0

      • includesDeliveryFeebooleanمطلوب
    • scheduledForstring<date-time>اختياري
    • notestringاختياري
    • cutlerybooleanاختياري
    • ifUnavailablestringاختياري
    • deliveryobjectاختياري
      الحقول الداخلية (5)
      • addressstringمطلوب

        الطول: 3 – 300

      • detailsstringاختياري

        الطول: ≤ 300

      • locationobjectاختياري
        الحقول الداخلية (2)
        • latnumberمطلوب

          القيمة: -90 – 90

        • lngnumberمطلوب

          القيمة: -180 – 180

      • contactNamestringمطلوب

        الطول: 1 – 80

      • contactPhonestringمطلوب

        الطول: 9 – 20

    • courierobjectاختياري
      الحقول الداخلية (2)
      • namestringمطلوب
      • phonestringاختياري
    • tenderstringاختياري
    • paidAtstring<date-time>اختياري
    • createdAtstring<date-time>مطلوب
    • historyStatusChange[]مطلوب
      الحقول الداخلية (7)
      • fromstringمطلوبيقبل null

        القيم: "pending_payment""payment_failed""placed""accepted""preparing""ready""out_for_delivery""delivered""picked_up""cancelled""rejected""delivery_failed""not_collected"

      • tostringمطلوب

        القيم: "pending_payment""payment_failed""placed""accepted""preparing""ready""out_for_delivery""delivered""picked_up""cancelled""rejected""delivery_failed""not_collected"

      • atstring<date-time>مطلوب
      • actorStatusChangeActorمطلوب

        القيم: "customer""staff""system""payment""partner"

      • reasonstringاختياري
      • reasonCodestringاختياري
      • returnedToBranchbooleanاختياري
  • statePartnerOrderStateمطلوب

    القيم: "awaiting_ack""acked""closed"

  • ackDueAtstring<date-time>مطلوبيقبل null
  • ackedAtstring<date-time>مطلوبيقبل null
  • externalOrderNostringمطلوبيقبل null
  • externalReceiptNostringمطلوبيقبل null
  • externalPartnerOrderExternalمطلوب
    الحقول الداخلية (4)
    • branchCodestringمطلوبيقبل null
    • linesobject[]مطلوب
      الحقول الداخلية (5)
      • lineIndexintegerمطلوب

        القيمة: ≥ 0

      • codestringمطلوبيقبل null
      • variantstringمطلوبيقبل null
      • unitstringمطلوبيقبل null
      • optionsobject[]مطلوب
        الحقول الداخلية (4)
        • groupIdstringمطلوب

          الطول: 1 – 64

        • optionIdstringمطلوب

          الطول: 1 – 64

        • codestringمطلوبيقبل null
        • variantstringمطلوبيقبل null
    • tenderCodestringمطلوبيقبل null
    • unmappedobject[]مطلوب
      الحقول الداخلية (2)
      • kindPartnerMappingKindمطلوب

        القيم: "branch""category""product""group""option""tender"

      • ourIdstringمطلوب
  • updatedAtstring<date-time>مطلوب
400INVALID_REQUEST (field, detail.issues), IDEMPOTENCY_KEY_REQUIREDPartnerError

الترويسات

الاسمالنوعالوصف
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

الترويسات

الاسمالنوعالوصف
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

الترويسات

الاسمالنوعالوصف
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

الترويسات

الاسمالنوعالوصف
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

الترويسات

الاسمالنوعالوصف
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

الترويسات

الاسمالنوعالوصف
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

الترويسات

الاسمالنوعالوصف
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.

مثال الرد

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

المصادقة
مفتاح الشريك في ترويسة Authorization
الصلاحيات المطلوبة
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"
}'

المعاملات

الاسمالموضعالنوعالوصف
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.

جسم الطلب PartnerStatusRequest

  • eventIdstringمطلوب

    الطول: 1 – 64

  • toPartnerStatusTargetمطلوب

    القيم: "accepted""rejected""preparing""ready""picked_up""cancelled""out_for_delivery""delivered""delivery_failed"

  • expectedFromstringاختياري

    القيم: "pending_payment""payment_failed""placed""accepted""preparing""ready""out_for_delivery""delivered""picked_up""cancelled""rejected""delivery_failed""not_collected"

  • reasonCodestringاختياري
  • reasonTextstringاختياري

    الطول: 1 – 300

  • occurredAtstring<date-time>مطلوب
  • estimatedReadyAtstring<date-time>اختياري

الردود

200OKPartnerStatusResult

الترويسات

الاسمالنوعالوصف
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.

البنية

  • outcomestringمطلوب

    القيم: "applied""duplicate""ignored""parked"

  • statusstringمطلوب

    القيم: "pending_payment""payment_failed""placed""accepted""preparing""ready""out_for_delivery""delivered""picked_up""cancelled""rejected""delivery_failed""not_collected"

  • reasonstringمطلوبيقبل null
400INVALID_REQUEST (field, detail.issues), IDEMPOTENCY_KEY_REQUIREDPartnerError

الترويسات

الاسمالنوعالوصف
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

الترويسات

الاسمالنوعالوصف
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

الترويسات

الاسمالنوعالوصف
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

الترويسات

الاسمالنوعالوصف
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

الترويسات

الاسمالنوعالوصف
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

الترويسات

الاسمالنوعالوصف
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

الترويسات

الاسمالنوعالوصف
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

الترويسات

الاسمالنوعالوصف
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.

مثال الرد

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.

المصادقة
مفتاح الشريك في ترويسة Authorization
الصلاحيات المطلوبة
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"
}'

المعاملات

الاسمالموضعالنوعالوصف
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.

جسم الطلب PartnerCancelRequest

  • eventIdstringمطلوب

    الطول: 1 – 64

  • reasonCodeExitReasonCodeمطلوب

    القيم: "customer_unreachable""wrong_address""customer_refused""accident_or_damage""kitchen_error""out_of_stock""customer_request""other"

  • reasonTextstringاختياري

    الطول: 1 – 300

  • occurredAtstring<date-time>مطلوب

الردود

200OKPartnerStatusResult

الترويسات

الاسمالنوعالوصف
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.

البنية

  • outcomestringمطلوب

    القيم: "applied""duplicate""ignored""parked"

  • statusstringمطلوب

    القيم: "pending_payment""payment_failed""placed""accepted""preparing""ready""out_for_delivery""delivered""picked_up""cancelled""rejected""delivery_failed""not_collected"

  • reasonstringمطلوبيقبل null
400INVALID_REQUEST (field, detail.issues), IDEMPOTENCY_KEY_REQUIREDPartnerError

الترويسات

الاسمالنوعالوصف
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

الترويسات

الاسمالنوعالوصف
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

الترويسات

الاسمالنوعالوصف
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

الترويسات

الاسمالنوعالوصف
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

الترويسات

الاسمالنوعالوصف
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

الترويسات

الاسمالنوعالوصف
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

الترويسات

الاسمالنوعالوصف
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.

مثال الرد

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.

المصادقة
مفتاح الشريك في ترويسة Authorization
الصلاحيات المطلوبة
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"
}'

المعاملات

الاسمالموضعالنوعالوصف
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.

جسم الطلب PartnerOrderEventRequest

  • eventIdstringمطلوب

    الطول: 1 – 64

  • typestringمطلوب

    القيم: "receipt_issued""invoice_issued""payment_collected""note"

  • receiptNostringاختياري

    الطول: 1 – 50

  • invoiceNostringاختياري

    الطول: 1 – 50

  • invoiceQrstringاختياري

    الطول: ≤ 1000

  • amountintegerاختياري

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

    القيمة: ≥ 0

  • tenderstringاختياري

    القيم: "cash""card"

  • notestringاختياري

    الطول: 1 – 300

  • occurredAtstring<date-time>مطلوب

الردود

200OKPartnerOrderEventResult

الترويسات

الاسمالنوعالوصف
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.

البنية

  • outcomestringمطلوب

    القيم: "recorded""duplicate"

400INVALID_REQUEST (field, detail.issues), IDEMPOTENCY_KEY_REQUIREDPartnerError

الترويسات

الاسمالنوعالوصف
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

الترويسات

الاسمالنوعالوصف
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

الترويسات

الاسمالنوعالوصف
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

الترويسات

الاسمالنوعالوصف
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

الترويسات

الاسمالنوعالوصف
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

الترويسات

الاسمالنوعالوصف
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

الترويسات

الاسمالنوعالوصف
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

الترويسات

الاسمالنوعالوصف
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.

مثال الرد

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.

المصادقة
مفتاح الشريك في ترويسة Authorization
الصلاحيات المطلوبة
payments:read
curl -sS "$LP_BASE_URL/partner/v1/orders/7f3a2c10-5b8e-4d21-9c47-1a2b3c4d5e01/payments" \
  -H "Authorization: Bearer $LP_API_KEY"

المعاملات

الاسمالموضعالنوعالوصف
id *pathstringThe Let's Pizza order id (order.id).

الردود

200OKPartnerOrderPayments

الترويسات

الاسمالنوعالوصف
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.

البنية

  • orderIdstringمطلوب

    الطول: 1 – 64

  • paymentMethodstringمطلوب

    القيم: "pay_at_branch""cash_on_delivery""online"

  • totalintegerمطلوب

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

    القيمة: ≥ 0

  • paidintegerمطلوب

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

    القيمة: ≥ 0

  • refundedintegerمطلوب

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

    القيمة: ≥ 0

  • attemptsobject[]مطلوب
    الحقول الداخلية (4)
    • idstringمطلوب

      الطول: 1 – 64

    • statusstringمطلوب
    • amountintegerمطلوب

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

      القيمة: ≥ 0

    • createdAtstring<date-time>مطلوب
  • refundsRefund[]مطلوب
    الحقول الداخلية (10)
    • idstringمطلوب

      الطول: 1 – 64

    • orderIdstringمطلوب

      الطول: 1 – 64

    • intentIdstringمطلوبيقبل null

      الطول: 1 – 64

    • amountintegerمطلوب

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

      القيمة: ≥ 0

    • reasonstringمطلوب

      القيم: "cancelled_by_customer""cancelled_by_branch""rejected""item_unavailable""quality""other"

    • notestringاختياري

      الطول: ≤ 500

    • statusstringمطلوب

      القيم: "requested""processing""succeeded""failed"

    • requestedBystringمطلوب

      الطول: ≥ 1

    • createdAtstring<date-time>مطلوب
    • settledAtstring<date-time>اختياري
401UNAUTHENTICATED (no key, a wrong or revoked one), KEY_EXPIRED, KEY_ENVIRONMENT_MISMATCH (a test key on production or the other way round)PartnerError

الترويسات

الاسمالنوعالوصف
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

الترويسات

الاسمالنوعالوصف
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

الترويسات

الاسمالنوعالوصف
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

الترويسات

الاسمالنوعالوصف
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

الترويسات

الاسمالنوعالوصف
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.

مثال الرد

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"
    }
  ]
}