What it does
Opens an order on behalf of a user. Dedup key is vendor_order_ref — send the same one twice and you get the first order back with replayed: true.
Body
user_idRequired
SG user id — get it from
getUserToken in the mini app.vendor_order_refRequired
Your cart/order id, ≤ 40 printable-ASCII chars. Idempotency key for this call.
itemsRequired
Non-empty array of line items — see the orderPayment section for the per-category shape.
subtotal, total_amountRequired
Money as decimal string. The platform checks arithmetic (subtotal + delivery + tax = total).
delivery_address, shop_icon, shop_address, order_type
Display metadata for the receipt / order card.
Request schema
{
"user_id": <number>, // required
"vendor_order_ref": <string, 1..40 printable ASCII>, // required — dedup key
"items": [ /* see orderPayment */ ], // required, non-empty
"subtotal": <string, decimal>, // required
"total_amount": <string, decimal>, // required
"delivery_fee": <string, decimal>, // optional
"tax_amount": <string, decimal>, // optional
"currency": <string, ISO 4217>, // optional, defaults to mini-app currency
"delivery_address": <object> | null, // optional
"shop_name_en": <string, ≤120>, // optional — branch name (EN)
"shop_name_ar": <string, ≤120>, // optional — branch name (AR)
"shop_icon": <string URL, ≤2048>, // optional — branch icon
"shop_address": <object> | null, // optional — branch address
"order_type": <string, ≤60>, // optional — "delivery" | "pickup" | ...
"customer_meta": <object> | null // optional — free-form JSON
}Response
statusboolean
Always
true on 2xx. Check the HTTP status code for error branches.replayedboolean
true when the same vendor_order_ref was seen before — the returned data is the original order and no duplicate was created. Use this to keep your retry loops idempotent.data.order_uuidstring, UUID
Stable id for this order. Use it for the read endpoint and to match webhook payloads.
data.order_numberstring
Human-readable receipt number shown to the user in-app (e.g.
MA-2026-00042).data.vendor_order_refstring
Echo of the ref you sent — useful for reconciling against your cart on your side.
data.status, order_status, payment_status{ id, name }
Machine
id for logic, localized name for display. status mirrors order_status for backwards-compat.data.itemsarray
Line items you sent, normalized (money coerced to decimal strings, category-specific fields kept).
data.subtotal, delivery_fee, tax_amount, total_amountstring, decimal
Money as decimal strings — do not parse to a float, keep them as strings until display.
data.currencystring, ISO 4217
Falls back to the mini-app's default currency if you omitted it on create.
data.payment_methodstring | null
Null until a payment succeeds; then one of
card, wallet, apple_pay, tamara.data.created_at, updated_atstring, ISO 8601 UTC
Timestamps for audit and diffing against your side.
messagestring
Human string — do not parse or branch on it. Use the HTTP status and
data.*.id fields for logic.Response schema
// 201 Created — new order (replayed = false)
// 200 OK — same vendor_order_ref re-sent (replayed = true, no duplicate created)
{
"status": true,
"replayed": <boolean>,
"data": {
"order_uuid": "0193b09d-9c8a-7af3-8b56-a51d6a3e4f10",
"order_number": "MA-2026-00042",
"vendor_order_ref": "VND-CART-9b3f12",
"state": "created",
"status": { "id": "created", "name": "Created" },
"order_status": { "id": "created", "name": "Created" },
"payment_status": { "id": "unpaid", "name": "Unpaid" },
"items": [
{ "sku": "pizza-pep-l", "name": "Pepperoni Pizza — Large", "qty": 2, "unit_price": 49.00 }
],
"subtotal": "98.00",
"delivery_fee": "10.00",
"tax_amount": "16.20",
"total_amount": "124.20",
"currency": "SAR",
"payment_method": null, // "card" | "wallet" | "apple_pay" | "tamara" once paid
"created_at": "2026-09-13T14:22:11.000Z",
"updated_at": "2026-09-13T14:22:11.000Z"
},
"message": "Order created"
}Try it