Orders

An order in the T-Gate platform represents a customer's request placed against a specific brand, branch, and menu through a partner application. It is the central operational entity that links a customer, the items they purchased, the service they chose (dine-in, delivery, pick-up, curbside), and the payment they made together into a single trackable record.

For more details on the hierarchical structure and how different entities relate to each other, please refer to General → High Level Structure Guides.

Model Attributes

Attribute	Description	Type
id	The unique identifier of that table entity	Integer
app_order_uuid	The unique identifier of the order on the partner application side. This is used by partners to correlate T-Gate orders with their own internal records.	String
order_status	The current status of the order in its lifecycle. See the Order Statuses section for the full list of values and their transitions.	String
total_price	The final price of the order after taxes and discounts are applied.	Float
created_at	The timestamp at which the order was created in T-Gate.	Datetime
brand_id	The id of the brand under which the order was placed.	Integer
branch_id	The id of the branch fulfilling the order.	Integer
menu_id	The id of the menu used to construct the order's items.	Integer
service_type	The service used to fulfill the order. See the Service Types section for the full list of values.	String
payment_type	How the customer is paying for the order (cash or online).	String
payment_status	The current state of the payment (pending_payment or paid).	String
is_customer_arrived	Boolean flag that indicates whether the customer has arrived. Only applicable to curbside and app_delivery orders.	Boolean
full_address	The full delivery address provided by the customer. Required for delivery orders.	String or Null
lat	The latitude of the delivery location. Required for delivery orders.	Float or Null
lng	The longitude of the delivery location. Required for delivery orders.	Float or Null
estimated_time	The estimated time (in minutes) needed by the branch to fulfill the order, starting from the moment the order is accepted.	Integer
notes	Free-text notes attached to the order by the customer.	String or Null
items	Array of JSON objects representing the items included in the order, including their quantities, prices, modifiers, and nesting. See the Items Object section for details.	Object Array
cancellation_reason	JSON object that represents the cancellation reason attached to the order, if any. Only present when the order has been cancelled.	Object or Null

📘

app_order_uuid

app_order_uuid is unique per partner application source, meaning two different partner applications can each create an order with the same app_order_uuid without conflict. T-Gate enforces uniqueness on the combination of app_order_uuid + source.

📘

brand_id, branch_id and menu_id

Every order is scoped to a specific brand, branch, and menu. T-Gate validates that the brand/branch/menu combination is part of an active integration scope for the partner application creating the order. Orders cannot be created against a brand/branch/menu combination that has not been granted to the partner.

🕑

Estimated Time And Timezones

estimated_time represents a duration (in minutes), not an absolute time. It is initialized at order creation based on the branch service's default order estimated time (or the partner application's default delivery estimated time for app_delivery orders).

The actual expected completion time is derived from accepted_at + estimated_time once the order moves to in_progress. Since accepted_at is stored in UTC, applications consuming this value should apply the branch's timezone offset when rendering it to end users.

Service Types

Every order is created against one of the service types supported by the branch. The chosen service_type determines the valid status transitions and which fields are required.

Available service types are:

Service Type	Description
dine_in	The customer eats inside the branch.
delivery	The branch (or its delivery partner) delivers the order to the customer's location. Requires full_address, lat and lng.
pick_up	The customer collects the order from the branch.
curbside	The customer places the order, then collects it from their vehicle at a designated location outside the branch. Supports is_customer_arrived.
app_delivery	Delivery handled by the partner application itself. Requires that the partner application supports delivery. Supports is_customer_arrived.

✅

Branch Service Must Be Active

An order cannot be created against a branch unless the corresponding service is active on that branch (branch_service.is_active = true). For app_delivery, the partner application — not the branch — must support delivery.

Order Statuses

Order status transitions are validated by T-Gate. The set of allowed next statuses depends on both the current status and the order's service_type.

Available statuses are:

Status	Description
pending	The order has just been created and is waiting on the branch to accept it. Initial status for branches that do not auto-accept.
in_progress	The branch has accepted the order and is preparing it. Initial status for branches that have auto-accept enabled.
ready	The order is prepared and ready to be served, picked up, or handed to the delivery party.
in_route	The order is currently being delivered to the customer. Only applicable to delivery and app_delivery orders.
done	The order has been completed successfully.
cancelled	The order has been cancelled. A cancellation_reason is required.
rejected	The branch rejected the order while it was still pending.
company_force_cancelled	The order was forcibly cancelled by the company (e.g. via the company portal).
company_early_cancelled	The order was cancelled by the company before fulfillment progressed.
timed_out	The order was automatically cancelled because the branch did not accept it within the partner application's allowed timeout window.

🔁

Valid Status Transitions

Allowed transitions vary by service_type:

• dine_in / pick_up / curbside: pending → in_progress → ready → done, with cancelled reachable from pending, in_progress, and ready. From pending, the order can also be rejected.
• delivery: pending → in_progress → ready → in_route → done, with cancelled reachable from any non-terminal status and rejected reachable from pending.
• app_delivery: same as delivery, but done is also reachable directly from in_progress or ready since the partner application controls the delivery flow.

Statuses done, rejected, cancelled, company_force_cancelled, company_early_cancelled and timed_out are terminal — no further transitions are allowed once an order reaches them.

⏱️

Timeouts

When the partner application defines a positive order_timeouts_after value, T-Gate schedules a timeout job for the order at creation time. If the order is still pending when that window elapses, T-Gate automatically transitions it to timed_out.

Payments

Each order carries both a payment_type and a payment_status.

Field	Values	Description
payment_type	cash, online	How the customer is paying for the order.
payment_status	pending_payment, paid	Whether payment has been settled. Updatable via the order update endpoint.

Items Object

The items attribute is a hierarchical array describing every product, modifier group, and modifier ordered by the customer. Items are nested through the children array, allowing modifier groups and modifiers to be attached to their parent product.

Each item entry contains:

Attribute	Description	Type
item_id	The id of the underlying section_item (product, modifier group, or modifier) on the menu.	Integer
item_type	One of product, modifier_group, modifier.	String
item_name_en	The English name of the item at the time of order creation.	String
item_name_ar	The Arabic name of the item at the time of order creation.	String
quantity	The number of units ordered for that item. For modifier_group items the quantity is always 1.	Integer
basic_price_per_unit	Price of a single unit of the item before factoring in its children.	Float
total_basic_price_per_unit	Price of a single unit including the cost of its children (modifiers).	Float
total_basic_price	total_basic_price_per_unit * quantity for that line.	Float
total_basic_price_equation	A human-readable equation describing how total_basic_price was derived from the item and its children.	String
notes	Free-text notes attached to the specific item by the customer.	String or Null
pos_item_uuid	The id of the matching item in the brand's POS system, if integrated.	String or Null
children	Array of child items (same shape), used to attach modifier groups to products and modifiers to modifier groups.	Object Array

🧱

Root Items Must Be Products

Only items with item_type = product are valid as root entries of the items array. Modifier groups and modifiers must always appear as children of a product. T-Gate validates the full nesting tree at order creation and rejects orders with invalid hierarchies.

💵

Total Price Validation

The total_price provided on order creation is validated against the price T-Gate computes from the items array (basic_price plus future tax/discount logic). If the two values differ by more than 0.01, the order is rejected. Use the POST /partner_portal/v1/orders/calculate_total_price endpoint to obtain the price T-Gate will accept before creating the order.

Cancellation

When an order is cancelled, T-Gate requires a cancellation_reason to be attached.

Available cancellation reasons are:

Status	Description
customer_wants_to_cancel_while_the_order_is_pending	The customer cancelled the order before the branch accepted it.
customer_wants_to_cancel_before_the_estimation_time_ends	The customer cancelled the order before the branch finished preparing it.
customer_wants_to_cancel_because_the_company_is_late	The customer cancelled the order because the branch exceeded the estimated time.
company_wants_to_cancel_because_the_customer_didnt_show_up	The branch cancelled the order because the customer did not arrive (curbside/pick-up).

📘

cancellation_reason VS company_force_cancelled

A regular cancelled status always carries a cancellation_reason (sent by the partner application). company_force_cancelled, company_early_cancelled and timed_out are platform-driven terminal statuses and do not require a cancellation reason from the partner application.