Order tracking API¶

When a shopper asks the chatbot about an order — «وين طلبي؟», "where is my order #15135?" — Sunono asks your store live and answers with your own status words, delivery estimate and tracking link. This page is the contract your store implements. It is optional: the shop owner switches it on in Dashboard → Integration → Magento → Order tracking, after you deploy the endpoint.

Direction: Sunono → your store. One request per question; nothing is pushed.
Status pushes are separate: keep sending order.status_changed so the shop's dashboard stays current. This API is what the shopper sees in chat.

Today: Magento stores

Sunono calls this endpoint through the shop's existing Magento integration. Building on another platform? Contact us — the request/response below is the same contract.

1. Endpoint & authentication¶

POST {your Magento base URL}/rest/V1/sunono/order/track
Content-Type: application/json

Store-root path, no store code (/rest/V1/…, not /rest/jo_en/V1/…).
Authentication: the same Magento Integration Sunono already uses to place orders, signed with OAuth 1.0a (HMAC-SHA256). Add a dedicated ACL resource for this route (e.g. Vendor_Module::order_track) and grant it to that integration — no new credentials, and the token can read nothing else it doesn't need.
No redirects: Sunono does not follow 3xx. Serve the route directly over https.
IP allowlist (optional): Sunono production calls from 49.13.201.224.

The dashboard shows the exact URL Sunono calls for your shop under Order tracking.

2. Request¶

Field	Type	Required	Notes
`phone`	string	yes	Always E.164 from Sunono (`+962791234567`). Match it against the order's account, shipping and billing phone, whatever format your store saved them in.
`order_id`	string	no	The order number the shopper sees (the one in your SMS/email). Return that order only if it belongs to `phone`. Omitted → the phone's most recent order.
`lang`	string	no	`ar` or `en`. Labels, status texts and product names in that language.

{ "phone": "+962791234567", "order_id": "15135", "lang": "ar" }

Never confirm an order to the wrong phone

order_id + phone that don't belong together must answer exactly like a missing order (404), so nobody can discover other people's orders by guessing numbers. Sunono only calls you with a phone the shopper has proven (their WhatsApp number, or an SMS code) — but your check is the last line of defence.

3. Response — `200 OK`¶

Sunono reads these fields; anything else is ignored.

Field	Type	Meaning
`order_id`	string \| number	The customer-facing order number — the same one in your SMS/emails and the same id you return when Sunono places an order.
`display_status`	string	The step the shopper is at — see status codes. Use stable codes, not text.
`is_canceled`	boolean	`true` for cancelled/closed orders (wins over `display_status`).
`status_label`	string	Ready-to-show status text in `lang` («قيد التحضير», "Processing"). Shown verbatim.
`status_description`	string \| null	One sentence explaining the status, in `lang`.
`estimated_arrival`	string \| null	Text like «1–3 أيام عمل» / "1–3 business days"; `null` once delivered or cancelled.
`items[]`	array	`name` (in `lang`), `qty`, `unit_price`, `subtotal` (VAT-inclusive, decimal).
`payment.total`	decimal	What the shopper pays / paid.
`payment.currency`	string	`JOD`.
`track_url`	string \| null	Link to the order's tracking page. https on your store's own domain (or a subdomain / its parent site); any other link is dropped.

{
  "order_id": 15135,
  "display_status": "processing",
  "is_canceled": false,
  "status_label": "قيد التحضير",
  "status_description": "عم نجهز طلبك هلأ.",
  "estimated_arrival": "1–3 أيام عمل",
  "items": [{ "name": "سيروم شعر 120مل", "qty": 1, "unit_price": 7.75, "subtotal": 7.75 }],
  "payment": { "currency": "JOD", "total": 15.00 },
  "track_url": "https://yourstore.com/t/v3PSZA3"
}

Send less personal data

Sunono drops the customer's name, address, phone, notes and invoice links on arrival — they never reach the chat, the AI or Sunono's logs. You may leave them out entirely.

Status codes¶

`display_status`	Shopper hears (Sunono status)
`pending`	received (`placed`)
`processing`, `sent_to_fulfillment`, `packed_roots`, `ready_to_ship_roots`	being prepared (`preparing`)
`shipped_roots`	on its way (`dispatched`)
`delivered`, `complete`	delivered (`delivered`)
`canceled`, or `is_canceled: true`	cancelled (`cancelled`)
anything else	being prepared — your `status_label` is still shown verbatim

Add a new code? Tell us, so it maps to the right step.

4. Errors¶

HTTP	When	Sunono does
`404`	No order for this phone, or `order_id` isn't this phone's	Tells the shopper the order isn't on that number and offers to verify another number
`401` / `403`	Bad signature or missing ACL permission	Says it can't check right now; the dashboard Test shows "login rejected"
`400`	Invalid input	Same as above
`5xx`, timeout	Your side is down	Same as above

Respond within 1 s; Sunono waits 3 s, then answers without you.
Magento's own "Request does not match any route" 404 means the module isn't installed — the dashboard Test reports it as "endpoint missing".

5. Test it¶

Deploy the route and grant the ACL resource to Sunono's integration.
In Dashboard → Integration → Magento → Order tracking, press Test connection. Sunono calls your endpoint for +962790000000 with no order_id — a number no customer has. Expected: 404. That proves the route, the signature and the permission without touching anyone's order.
Switch it on and ask the chatbot about a real order from that order's phone.