--- title: "Update order state" method: PUT path: "/orders/{order_id}" tags: ["Order API endpoints"] --- # Update order state `PUT /orders/{order_id}` Use this endpoint to accept/cancel an order or mark an order as ready for pickup. **Unavailable Items** When cancelling an order due to item unavailability (e.g. `ITEM_PERMANENTLY_NOT_AVAILABLE` or `ITEM_TEMPORARILY_UNAVAILABLE`), you can optionally provide the list of unavailable items in the `unavailable_items` field. This data is used to drive future decisions such as automatically snoozing items that are temporarily out of stock, preventing them from appearing on the menu until they are available again. **Example request body:** ```json { "state": "cancelled", "cancellation_reason": "ITEM_TEMPORARILY_UNAVAILABLE", "unavailable_items": [ { "item_id": "item-123", "item_type": "item" }, { "item_id": "modifier-456", "item_type": "modifier_option" } ] } ``` ## Path parameters - `order_id` integer, required ## Headers - `Authorization` string, required - `User-Agent` string, required - `Brand-Id` string - `Branch-Id` string, required ## Request body - UpdateOrderRequest - `state` 'accepted' | 'ready' | 'cancelled', required — The state of the order. We've recently introduced the `ready` state, which enables partners' to achieve more accurate tracking of their orders. - `cancellation_reason` 'ITEM_PERMANENTLY_NOT_AVAILABLE' | 'ITEM_TEMPORARILY_UNAVAILABLE' | 'KITCHEN_TOO_BUSY_TO_PREPARE_ORDER' | 'OUT_OF_KITCHEN_OPERATIONAL_HOURS' | 'OUTLET_CLOSED' | 'PARTNER_POS_OUTAGE' | 'PARTNER_ORDER_TIMEOUT' | 'OTHER', required — Please select cancellation reason from the predefined list. These reasons are case-sensitive. - `unavailable_items` CancellationItem[] — Optional list of items that are unavailable and caused the order cancellation. Applicable when `cancellation_reason` is `ITEM_PERMANENTLY_NOT_AVAILABLE` or `ITEM_TEMPORARILY_UNAVAILABLE`. - `item_id` string, required — The unique identifier of the unavailable item. - `item_type` 'item' | 'modifier_option', required — The type of the unavailable item. ## Response `200` Order state updated successfully - CancelledOrder — Order details - `id` string, required — The id of the order - `status` 'pending' | 'accepted' | 'cancelled' | 'delivered', required — The current status of the order - `branch` Branch, required — Branch information - `id` string, required — The id of the branch - `name` string, required — The name of the branch. - `brand_id` string, required — the parent brand id of this branch - `state` 'UNMAPPED' | 'MAPPED', required — The state of this branch. - `created_at` string, required — Time RFC3339 format in UTC in which the brand has been updated - `updated_at` string, required — Time RFC3339 format in UTC in which the brand has been updated - `notes` string — Customer notes - `price` OrderPrice, required — Order price details - `original_total_price` number — is the total price of items and options without applying taxes nor discounts - `careem_discount_amount` number — is the Careem contribution amount of the total promotion discount - `merchant_discount_amount` number — is the Merchant contribution amount of the total promotion discount - `merchant_promo_amount` number — is the Careem contribution amount of the total promo code discount - `careem_promo_amount` number — is the Merchant contribution amount of the total promo code discount - `tax_percentage` number — is the tax percentage of the order - `total_taxable_price` number — is the total taxable amount of the order after applying taxes and the discount and adding delivery fees - `delivery_fee` number — is the delivery fee charged - `free_delivery_discount_value` number — is the discount amount on delivery fee. This value does not affect the total price of the order. However, it is important for the partner to take this value into account when performing their calculations. - `service_fee` number — is the service fee charged - `promo_code` string — Promotion code applicable for the order - `customer` Customer — information about the owner of the order in case of a self delivery orders - `name` string, required — the name of the customer - `phone_number` string, required — the phone number of the customer - `address` Address — show address details - `name` string, required — name of address - `location` object, required — geolocation of the address - `lat` string, required — the latitude of the address location - `lng` string, required — the longitude of the address location - `number` string, required — the number of the flat/villa - `building` string, required — the name of the building - `street` string, required — the name of the street - `area` string, required — the name of the area - `city` string, required — the name of the city - `note` string, required — additional notes or landmarks - `payment_type` 'cash' | 'card' | 'wallet' | 'apple_pay' — the payment type chosen by the customer like cash, card etc - `captain` Captain — the captain who is going to deliver the order - `name` string, required — the name of the driver - `phone_number` string, required — the phone number of the driver - `eta` string, required — is captain-to-merchant ETA in UTC using the RFC3339 format and is provided only in the pending event. This attribute will be absent if unavailable. - `items` OrderItem[], required - `id` string, required — is the id of the item - `quantity` integer, required — the total number of items selected - `groups` ItemGroup[] — the groups of the items - `id` string, required — the id of the group - `options` ItemOption[] — the options of the items - `id` string, required — the id of the option - `quantity` integer, required — is the quantity of the options selected - `discount` number — is the total discount on the option - `careem_discount_amount` number — is the Careem contribution amount of the discount - `merchant_discount_amount` number — is the Merchant contribution amount of the discount - `total_price` number, required — the total price of the selected options without applying taxes - `groups` ItemNestedGroup[] — Nested Modifiers allow nesting of the same item and its children options being shown under it instead of scrolling through. - `id` string, required — the id of the group - `options` ItemNestedOption[], required — the options of the items - `id` string, required — the id of the option - `quantity` integer, required — is the quantity of the options selected - `discount` number — is the total discount on the option - `careem_discount_amount` number — is the Careem contribution amount of the discount - `merchant_discount_amount` number — is the Merchant contribution amount of the discount - `total_price` number, required — the total price of the selected options without applying taxes - `unit_price` number — single item price - `item_price` number, required — is the unit_price * quantity - `total_price` number, required — total price of this item with the options - `discount` number, required — is the total discount on this item - `careem_discount_amount` number, required — is the Careem contribution amount of the discount - `merchant_discount_amount` number, required — is the Merchant contribution amount of the discount - `notes` string — instructions, comments, notes for an item - `tags` string[], required — List of tags associated with the item, only predefined tags are allowed - `cancellation_reason` string, required — The cancellation reason. This field is populated when the order is cancelled - `created_at` string, required — Time RFC3339 format in UTC in which the brand has been updated - `updated_at` string, required — Time RFC3339 format in UTC in which the brand has been updated ## Other responses - `400` — Bad request - `404` — Order with the specified ID was not found - `500` — Internal server error --- [API](https://skmtc.net/careemnow/apis/careem-pos-api.md) · [All operations](https://skmtc.net/careemnow/apis/careem-pos-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/careemnow/careem-pos-api/versions/374e3e0dddca/schema)