🧾 Orders

This object represents a single transaction. It is an immutable historical record of a purchase, capturing details at the time the order was placed.

Fields

Name	Type	Description
`id`	string	Unique identifier for the order (e.g., `ord_...`).
`customer_id`	string	ID of the `Customer`.
`merchant_id`	string	ID of the `Merchant`.
`order_number`	string	Customer-facing, human-readable order number (e.g., `Sanal-10026`).
`ordered_items`	array	List of items purchased. See structure below.
`subtotal`	number	Total cost of `ordered_items` before fees/taxes.
`delivery_fee`	number	Charge for delivery.
`taxes`	number	Total tax charged.
`total_amount`	number	Final grand total (`subtotal` + `delivery_fee` + `taxes`).
`currency`	string	Currency of the transaction (e.g., "SAR", "AED"). Based on merchant's country.
`status`	string	Current status (e.g., `pending_confirmation`, `delivered`, `cancelled`).
`delivery_address`	object	The delivery address used for this specific order, including coordinates, instructions, and recipient details. See structure below.
`payment_method`	string	Payment method used (e.g., "credit_card", "apple_pay").
`payment_status`	string	Status of the payment (e.g., `paid`, `pending`, `failed`).
`updated_at`	string	Timestamp of the last status change (ISO 8601 UTC).

Structure of `delivery_address` Object

Enhanced delivery address with location coordinates, delivery instructions, and recipient information.

Name	Type	Description
`tag`	string	User-defined label for the address (e.g., "Home", "Office").
`house_number`	string	House/building number (e.g., "123", "45A").
`building_name`	string	Optional. Name of the building (e.g., "Al-Fahad Tower").
`street`	string	Street name without house number (e.g., "Olaya Street").
`area`	string	Optional. Area/neighborhood name (e.g., "Olaya").
`city`	string	City name.
`postal_code`	string	Optional. Postal/ZIP code.
`country`	string	Country code (ISO 3166-1 alpha-2).
`location`	object	Precise geographic coordinates (`latitude`, `longitude`).
`delivery_instructions`	string	Optional. Special instructions for delivery (e.g., "Ring doorbell twice", "Leave at front door").
`recipient_name`	string	Optional. Name of the person to deliver to.
`recipient_phone`	string	Optional. Phone number of the recipient for delivery coordination.

Structure of `ordered_items` Object

Each object captures the state of a purchased item, including the specific variant SKU chosen and any selected modifiers.

Name	Type	Description
`product_id`	string	ID of the `Product` (merchant's offer) purchased.
`item_id`	string	ID of the global `Item`.
`variant_combination_sku`	string	Optional. The unique SKU from `Product.variant_combinations` representing the specific variant chosen. `null` if the base product was ordered.
`purchase_product_name`	string	The product/variant name at time of purchase.
`purchase_unit_price`	number	The final unit price for the chosen variant combination (before modifiers).
`quantity`	integer	Number of units ordered.
`selected_modifiers`	array	Optional. The list of chosen modifiers (`id`, `name`, `purchase_price`).

Sample JSON

Simple Retail Order Example

{
  "id": "ord_retail_xyz",
  "customer_id": "cus_a1b2c3d4",
  "merchant_id": "mer_tamimi_riyadh",
  "order_number": "Sanal-10027",
  "ordered_items": [
    {
      "product_id": "prod_tm_55667",
      "item_id": "item_almarai_milk_1l",
      "variant_combination_sku": null,
      "purchase_product_name": "Fresh Full Fat Milk - 1L",
      "purchase_unit_price": 5.75,
      "quantity": 2,
      "selected_modifiers": []
    },
    {
      "product_id": "prod_tm_banana",
      "item_id": "item_banana_each",
      "variant_combination_sku": null,
      "purchase_product_name": "Banana (Single)",
      "purchase_unit_price": 1.50,
      "quantity": 5,
      "selected_modifiers": []
    }
  ],
  "subtotal": 19.00,
  "delivery_fee": 10.00,
  "taxes": 2.85,
  "total_amount": 31.85,
  "currency": "SAR",
  "status": "delivered",
  "delivery_address": { 
    "tag": "Home", 
    "house_number": "123",
    "building_name": "Al-Fahad Tower",
    "street": "Olaya Street", 
    "area": "Olaya",
    "city": "Riyadh",
    "postal_code": "12345",
    "country": "SA",
    "location": { "latitude": 24.7136, "longitude": 46.6753 },
    "delivery_instructions": "Ring the doorbell twice, leave at front door if no answer",
    "recipient_name": "Fatima Al-Fahad",
    "recipient_phone": "+966551234567"
  },
  "payment_method": "apple_pay",
  "payment_status": "paid",
  "updated_at": "2025-10-17T15:00:00Z"
}

Complex Restaurant Order Example (Burger with Variant and Modifier)

{
  "id": "ord_resto_abc",
  "customer_id": "cus_b5e6f7g8",
  "merchant_id": "mer_riyadh_burger_house",
  "order_number": "Sanal-10028",
  "ordered_items": [
    {
      "product_id": "prod_rbh_classic_burger",
      "item_id": "item_rbh_classic_burger",
      "variant_combination_sku": "RBH-CLASSIC-D", // User chose the Double Patty variant
      "purchase_product_name": "Classic Riyadh Burger - Double Patty", // Name reflects variant
      "purchase_unit_price": 42.00, // Price from the variant combination
      "quantity": 1,
      "selected_modifiers": [ // User added Extra Cheese
        { "id": "mod_cheese", "name": "Extra Cheese", "purchase_price": 3.00 }
      ]
    }
    // ... potentially other items like drinks
  ],
  "subtotal": 45.00, // (42.00 + 3.00)
  "delivery_fee": 12.00,
  "taxes": 6.75,
  "total_amount": 63.75,
  "currency": "SAR",
  "status": "delivered",
  "delivery_address": { 
    "tag": "Office", 
    "house_number": "456",
    "building_name": "King Abdullah Financial District",
    "street": "KAFD", 
    "area": "KAFD",
    "city": "Riyadh",
    "postal_code": "13519",
    "country": "SA",
    "location": { "latitude": 24.7625, "longitude": 46.6418 },
    "delivery_instructions": "Call when you arrive, security will let you in",
    "recipient_name": "Ahmed Al-Rashid",
    "recipient_phone": "+966501234567"
  },
  "payment_method": "credit_card",
  "payment_status": "paid",
  "updated_at": "2025-10-17T15:30:00Z"
}

Fields#

Structure of delivery_address Object#

Structure of ordered_items Object#

Sample JSON#