# Order Notification

**Event ID**: 6001
Keeta sends this webhook when a new order is created or when the order
status or final item facts change.
The payload has the same shape as the Order Details response and always
represents the latest complete order.
Possible order status values are:
- `RECEIVED`: The order has been accepted and is waiting for fulfillment processing.
- `PICKED`: Picking is complete. Service providers must process this
status and refresh the final picked item facts.
- `READY_FOR_PICKUP`: Packing is complete and the order is available
for rider pickup. Processing this status is optional for service
providers.
- `DISPATCHED`: The order has left the store.
- `DELIVERED`: The order has been delivered and is complete.
- `CANCELED`: The order was cancelled.

**Notes:** In the event that Keeta's platform sends a new order
notification but does not receive an acknowledgment from the
developer's system, Keeta will attempt to resend the notification up
to a maximum of three additional times.
**⚠️ IMPORTANT: Amount Availability and Finality**
The current Grocery Order payload does not expose a dedicated merchant
settlement breakdown. Where merchant settlement amounts are made
available, they may be calculated asynchronously and may therefore be
absent, null, or incomplete when an order notification is first
received. Service providers must not use merchant settlement amounts as
hard dependencies in order-processing logic. If settlement data is
missing or incomplete, re-query the Order Details endpoint after a short
delay. Reconciliation, invoicing, and other downstream workflows must
tolerate the temporary unavailability of settlement amounts without
blocking overall order processing.
The fields under `payment` represent customer payment amounts, not
merchant settlement amounts, and are not subject to settlement
calculation delays. These values may still change while picking or item
modifications are in progress. After picking is complete, the customer
payment amounts are final and will not change.

Endpoint: POST /orderNotification
Version: v.1.0.0

## Request fields (application/json):

  - `acceptedFor` (string, required)
    Time stamp in UTC which indicates the estimated delivery time.
    Example: 2022-02-07T16:03:06Z

  - `createdAt` (string, required)
    Time when the order was created, in UTC.
    Example: 2024-09-30T10:00:36.947Z

  - `updatedAt` (string, required)
    Time when the order was last updated, in UTC.
    Example: 2024-09-30T10:05:36.947Z

  - `comment` (string, required)
    Comment or remark related to the order.
    Example: My first order

  - `orderCode` (string, required)
    Short code used when handing the order to a rider.
    Example: 29332222

  - `orderId` (string, required)
    Unique Keeta order identifier.
    Example: 756823555555859

  - `orderType` (string, required)
    How the customer receives the order.
    Enum: "DELIVERY", "PICKUP"

  - `cancellation` (object)
    Present only when the order status is `CANCELED`.

  - `cancellation.cancelledBy` (string, required)
    Party responsible for the cancellation.
    Enum: "CUSTOMER", "VENDOR", "PLATFORM"

  - `cancellation.postPickedUp` (boolean, required)
    Whether the cancellation occurred after rider pickup.
    Example: false

  - `cancellation.code` (string, required)
    Code indicating why the order was cancelled. This is the string
representation of `cancelCode` used by the Order Cancellation API.
    Enum: "500000", "500001", "500002", "500003"

  - `cancellation.reason` (string)
    Optional detailed cancellation reason mapped from the Keeta cancellation record. When `code` is `500000`, this field provides the specific cancellation explanation.
    Example: ITEM_UNAVAILABLE

  - `client` (object, required)
    Chain and vendor information associated with the order.

  - `client.chainId` (string, required)
    Unique chain or brand identifier.
    Example: 1297211

  - `client.countryCode` (string, required)
    Uppercase ISO 3166-1 alpha-2 market code, such as `SA`, `KW`, `QA`, `BH`, or `AE`.
    Example: SA

  - `client.name` (string, required)
    Vendor display name.
    Example: POS Test Vendor

  - `client.vendorId` (string, required)
    Unique Keeta platform vendor identifier.
    Example: 611469

  - `client.externalVendorId` (string)
    Merchant's internal vendor identifier. Present only when the merchant has maintained a vendor mapping in Keeta.
    Example: 123456

  - `customer` (object, required)
    Customer and delivery destination information.

  - `customer.id` (string, required)
    Internal Keeta customer identifier.
    Example: 10000030108064

  - `customer.deliveryAddress` (object, required)
    Structured customer delivery address.

  - `customer.deliveryAddress.apartment` (string)
    Masked apartment or unit number.
    Example: Big Ap******

  - `customer.deliveryAddress.block` (string)
    Masked block, district, phase, or estate information.
    Example: Bcasca******

  - `customer.deliveryAddress.building` (string)
    Masked building name.
    Example: ******

  - `customer.deliveryAddress.city` (string)
    City name.
    Example: Berlin

  - `customer.deliveryAddress.company` (string)
    Company or organization at the address.
    Example: Keeta

  - `customer.deliveryAddress.country` (string)
    Market or country code.
    Example: SA

  - `customer.deliveryAddress.floor` (string)
    Floor or unit information.
    Example: 12

  - `customer.deliveryAddress.formattedAddress` (string, required)
    Human-readable full address.

  - `customer.deliveryAddress.instructions` (string)
    Delivery instructions supplied with the address.
    Example: Leave at the reception

  - `customer.deliveryAddress.latitude` (number, required)
    Delivery latitude.
    Example: 0

  - `customer.deliveryAddress.longitude` (number, required)
    Delivery longitude.
    Example: 0

  - `customer.deliveryAddress.number` (string)
    Masked street number.
    Example: ******

  - `customer.deliveryAddress.street` (string)
    Street name.
    Example: Evergreen Street

  - `customer.deliveryAddress.zipcode` (string)
    Postal code.
    Example: 28001

  - `customer.name` (string, required)
    Masked customer name.
    Example: ***

  - `customer.phoneNumber` (string, required)
    Masked customer phone number, including country code when available.
    Example: ***

  - `items` (array, required)
    Latest order item facts available from Keeta.

  - `items.id` (string, required)
    Unique order-item identifier.
    Example: 1261779167

  - `items.barcode` (array, required)
    Product barcodes associated with the order item.
    Example: ["6281100875093"]

  - `items.name` (string, required)
    Product name.
    Example: Test product

  - `items.originalPricing` (object, required)
    Price and quantity originally ordered by the customer.

  - `items.originalPricing.pricingType` (string, required)
    Pricing type indicates whether the item is priced by `UNIT` or by `KG`.
    Enum: "UNIT", "KG"

  - `items.originalPricing.quantity` (number, required)
    Quantity of order items as ordered by the customer. Applies when `pricingType` is `UNIT`.
    Example: 1

  - `items.originalPricing.totalPrice` (number, required)
    Original total item amount in local currency.
    Example: 39.75

  - `items.originalPricing.unitPrice` (number, required)
    Original unit price in local currency.
    Example: 39.75

  - `items.originalPricing.listPrice` (number, required)
    Item price before discounts.
    Example: 39.75

  - `items.originalPricing.vatPercent` (number, required)
    VAT percentage. Keeta has no source field, so the value is always `0`.
    Example: 0

  - `items.originalPricing.weight` (number, required)
    Weight of order items as ordered by the customer. Applies when `pricingType` is `KG`.
    Example: 0

  - `items.pricing` (object, required)
    Latest price and quantity available from Keeta.

  - `items.pricing.pricingType` (string, required)
    Pricing type indicates whether the item is priced by `UNIT` or by `KG`.
    Enum: "UNIT", "KG"

  - `items.pricing.quantity` (number, required)
    Quantity of order items as fulfilled by the partner. Applies when `pricingType` is `UNIT`.
    Example: 1

  - `items.pricing.totalPrice` (number, required)
    Latest total item amount in local currency.
    Example: 39.75

  - `items.pricing.unitPrice` (number, required)
    Latest unit price in local currency.
    Example: 39.75

  - `items.pricing.vatPercent` (number, required)
    VAT percentage. Keeta has no source field, so the value is always `0`.
    Example: 0

  - `items.pricing.weight` (number, required)
    Weight of order items as fulfilled by the partner. Applies when `pricingType` is `KG`.
    Example: 0

  - `items.replacedId` (string)
    ID of the original order item replaced by this item. This field is
present only on a replacement item and points to another item in
the same order whose status is `REPLACED`. The replacement item
must have status `IN_CART` and a non-empty `name`.
Multiple replacement items may use the same `replacedId` to
represent one original item being replaced by multiple items. The
value must not reference the current item itself. Omit this field
for original, unchanged, not-found, and independently added items.
    Example: 1261779167

  - `items.sku` (string, required)
    Partner catalog SKU or open item code.
    Example: HSMVTE

  - `items.imageUrls` (array, required)
    Product image URLs sourced from `products[].picList`.
    Example: ["https://images.talabat.io/image.jpg"]

  - `items.status` (string, required)
    Item status. Possible values are:
- `NOT_PROCESSED`: The item's default status when the order is received.
- `IN_CART`: The item is available in full or partial quantities for
fulfillment. A replacement item also uses this status and points
to the original item through `replacedId`.
- `NOT_FOUND`: The item is out of stock and will not be fulfilled.
- `REPLACED`: The original item is out of stock and was replaced by
one or more items. Its `id` is referenced by each replacement
item's `replacedId`.
- `ADDITION`: The item was independently added by the picker and is
not a replacement; `replacedId` is omitted.
    Enum: "NOT_PROCESSED", "IN_CART", "NOT_FOUND", "REPLACED", "ADDITION"

  - `items.promotion` (array)
    Promotions applied to the item.

  - `items.promotion.name` (string, required)
    Promotion display name.
    Example: Drinks 0.5l and 1l on sale

  - `items.promotion.type` (string, required)
    Promotion type.
    Enum: "STRIKETHROUGH", "SAME_ITEM_BUNDLE"

  - `items.promotion.discountAmount` (number, required)
    Total promotion discount in local currency.
    Example: 2.25

  - `items.promotion.sponsorships` (array, required)
    Contribution by each promotion sponsor.

  - `items.promotion.sponsorships.sponsor` (string, required)
    Type of the sponsor. Currently, only `VENDOR` is supported.
    Enum: "VENDOR"

  - `items.promotion.sponsorships.amount` (number, required)
    Sponsor contribution in local currency.
    Example: 2.25

  - `payment` (object, required)
    Customer charges, discounts, totals, and payment type.

  - `payment.additionalFees` (object)
    Any fee not explicitly included in the other payment fields.

  - `payment.additionalFees.tip` (number)
    Tip charged in local currency.

  - `payment.additionalFees.droneServiceFee` (number)
    Drone service fee in local currency.

  - `payment.deliveryFee` (number, required)
    Delivery fee in local currency.
    Example: 1

  - `payment.differenceToMinimum` (number, required)
    Charge added to reach the minimum order value.
    Example: 0

  - `payment.discount` (number, required)
    Total discount as a negative amount, following Talabat semantics.
    Example: -1

  - `payment.discounts` (array, required)
    Detailed order-level discounts.

  - `payment.discounts.name` (string, required)
    Discount name.
    Example: First discount

  - `payment.discounts.value` (number, required)
    Discount as a negative amount, following Talabat semantics.
    Example: -1

  - `payment.orderTotal` (number, required)
    Final amount payable by the customer.
    Example: 41.75

  - `payment.serviceFee` (number, required)
    Platform service fee.
    Example: 0

  - `payment.subTotal` (number, required)
    Item subtotal before delivery and service fees.
    Example: 39.75

  - `payment.totalTaxes` (number, required)
    Tax amounts are not currently provided by this API contract, so
this value is fixed at 0.
    Enum: 0

  - `payment.type` (string, required)
    Customer payment type.
    Enum: "PAID", "CASH_ON_DELIVERY"

  - `status` (string, required)
    Current order lifecycle status.
    Enum: "RECEIVED", "PICKED", "READY_FOR_PICKUP", "DISPATCHED", "DELIVERED", "CANCELED"

  - `transportType` (string, required)
    Party responsible for delivering the order.
    Enum: "VENDOR_DELIVERY", "LOGISTICS_DELIVERY"