Orders, delivery tracking & returns

Overview

Once a customer is verified, the bot reads that customer’s recent orders and answers with the real status, the courier and the tracking number. It does not estimate delivery dates your system has not given it, and it never reports an order as delivered unless your data says so.

The “where is my order?” journey

1. 1
   The customer asks about an order. The bot asks for their full name plus an email address or mobile number (connectors look the customer up by email or mobile; a postcode can be the extra check).
2. 2
   A one-time code is sent to the contact details already held for that customer — never to a number typed in the chat. The customer types the code and a 30-minute session starts.
3. 3
   The bot calls the orders endpoint with the session token. For a connector that isPOST https://www.siluxchat.com/api/connect/{connection_id}/orders; for your own system it is POST {your base}/orders.
4. 4
   The bot answers from the rows returned: “Order ORD-50231, placed on 20 September, has been dispatched with Royal Mail Tracked 48. The tracking number is TT123456789GB.”
5. 5
   If the customer has several orders, the bot asks which one they mean, or answers about the most recent.

The order shape

Every source is mapped to the same fields. order_number and placed must be present for a row to count; the rest are included when the source has them. Money reported in minor units (pence or cents) is converted to pounds, and dates are normalised to YYYY-MM-DD.

Some shop connectors also map a refunded amount or the customer’s email on the order. When an email is present, a safety net drops any order that names a different customer’s email address, whatever the vendor’s search returned.

Orders from your own system (Account Connect)

# export SESSION=<the session_token returned by POST /verify-otp>
: "${SESSION:?export SESSION first}"
curl -s -X POST "https://www.siluxchat.com/api/account-connect-demo/v1/orders" \
  -H "X-API-Key: demo-account-connect-key" \
  -H "Content-Type: application/json" \
  -d "{\"session_token\":\"$SESSION\"}"

{
  "success": true,
  "orders": [
    {
      "order_number": "ORD-50231",
      "placed": "2026-09-20",
      "status": "dispatched",
      "courier": "Royal Mail Tracked 48",
      "tracking": "TT123456789GB"
    }
  ]
}

{
  "success": true,
  "orders": []
}

The whole flow, copy and paste

BASE=https://www.siluxchat.com/api/account-connect-demo/v1
KEY=demo-account-connect-key

# 1. Identify Test Customer (the demo never sends a text; the code is always 123456)
OTP=$(curl -s -X POST $BASE/verify-identity -H "X-API-Key: $KEY" -H 'Content-Type: application/json' \
  -d '{"full_name":"Test Customer","postcode":"TE5 7ST"}' | python3 -c 'import sys,json;print(json.load(sys.stdin)["otp_token"])')

# 2. Exchange the code for a session token
SESSION=$(curl -s -X POST $BASE/verify-otp -H "X-API-Key: $KEY" -H 'Content-Type: application/json' \
  -d "{\"otp_token\":\"$OTP\",\"otp_code\":\"123456\"}" | python3 -c 'import sys,json;print(json.load(sys.stdin)["session_token"])')

# 3. Read the customer's orders
curl -s -X POST $BASE/orders -H "X-API-Key: $KEY" -H 'Content-Type: application/json' -d "{\"session_token\":\"$SESSION\"}"; echo

Recommendations

• Return the most recent orders first — the last 10 is ample. The bot reads roughly the first 2,000 characters of a response.
• Use statuses a customer understands: processing, dispatched, out for delivery, delivered,cancelled, returned, refunded. Translate internal warehouse codes before returning them.
• Include the courier and tracking number as soon as a parcel is dispatched; if you have a courier tracking link, add it as an extra field (for example tracking_url) and the bot can share it.
• An estimated delivery date is helpful only if your system genuinely has one — add it as eta. The bot will not make one up.
• Never return another customer’s orders; filter by the customer bound to the session token only.

Looking up one order by number

Dashboard → Integrations also offers a Track Order template: an endpoint on your system that receives{"order_number": "ORD-12345"} and returns that order’s status, courier and tracking number. It is marked as requiring verification, so it runs only for a customer who has passed the one-time-code check. Use it when your customers typically quote an order number and you already have a “find order” API.

{
  "order_number": "ORD-12345",
  "status": "dispatched",
  "courier": "DPD",
  "tracking": "15501234567890",
  "eta": "2026-09-28"
}

Shop and payment connectors with orders

These connectors read a verified customer’s orders. Each page lists where to create the read-only key in the vendor’s admin, the permissions to grant and the exact fields mapped.

Try it end to end with no vendor account: connect the Silux Demo Store using the key demo-account-connect-key. It reads from a demo shop API with fictional customers:

curl -s "https://www.siluxchat.com/api/account-connect-demo/v1/vendor/orders?customer_id=C1001" \
  -H "X-API-Key: demo-account-connect-key"

{
  "orders": [
    {
      "order_number": "ORD-50231",
      "placed": "2026-09-20",
      "status": "dispatched",
      "courier": "Royal Mail Tracked 48",
      "tracking": "TT123456789GB"
    }
  ]
}

Couriers and tracking connectors

Courier and shipping-platform connectors (AfterShip, Royal Mail Click & Drop, ShipStation, DHL, UPS, FedEx and others) carry an order tracking capability. Connected, it becomes your bot’s Track My Parcel tool: the customer gives the tracking number from their dispatch email or text and the bot answers with the live status and courier.

Switching it on

• Connect the courier in Dashboard → Integrations → Connectors. If your bot has no parcel tracking yet, Track My Parcel is switched on automatically once the tracking test passes.
• To choose which connection answers tracking, press Use for tracking on it (POST /api/tenants/{tenant_id}/connectors/{id}/use-for-tracking).
• Some shipping platforms (AfterShip, ShipStation, Printful) also hold the customer’s name and email on each order, so they can verify customers too — see identity verification.

{"tracking_number": "TT123456789GB"}

{
  "success": true,
  "orders": [
    {"order_number": "1001", "status": "InTransit",
     "tracking": "TT123456789GB", "courier": "royal-mail"}
  ]
}

Returns and refunds

There is no separate returns endpoint, and the bot does not pretend there is. Returns are handled in three honest steps:

1. 1
   Policy from your knowledge base. The bot explains your returns window, condition rules and how to send an item back from the returns policy you have added to your knowledge base.
2. 2
   Status from your order data. If your system reports return or refund progress on the order — statuses such asreturn requested, returned or refunded, or a refunded amount — the bot reads it like any other status.
3. 3
   A ticket for the request itself. When a customer wants to start a return, the bot raises a support ticket for your team with the order number and reason, and tells the customer a person will follow it up.

Errors and edge cases

Full status-code reference and fixes: Troubleshooting. To try every call safely first, see Testing with the live demo.

Get help

Running a platform that is not listed, or a warehouse system with its own order API? Email support@siluxcall.co.uk with the system name and an anonymised sample of an order — our integration team will recommend the quickest route.