Order updates API

Four things, five minutes.

• A workspace key. Settings → API keys → create one with the write scope. It starts with tbk_. Send it as Authorization: Bearer.
• Order updates on. Bot → Automations → Order updates: switch it on, set the store website (it roots the “View order” button), press Install order templates, wait for Meta to approve them.
• The bot id. It is the id in your console URL: /bots/<botId>/….
• Your own wording. Every message can be rewritten under Automations with variables such as {name}, {order}, {total} and {tracking}; a change is submitted to Meta as a new version and only replaces the old one once approved.
• Opt-in. Only message customers who gave you their number for order updates. A line under the phone field at checkout is the standard basis.

POST /api/v1/orders/events

Records the order, then queues the update. It sends as soon as the template is approved, or after the wait you set for that event (confirmed waits two minutes so a payment seconds later folds into one message).

curl -X POST https://platform.tendabot.com/api/v1/orders/events \
  -H "Authorization: Bearer tbk_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: acme:5512:shipped:1" \
  -d '{
    "botId": "YOUR_BOT_ID",
    "event": "order.shipped",
    "order": {
      "externalId": "5512",
      "number": "4821",
      "status": "shipped",
      "total": "68.00",
      "currency": "GBP",
      "paymentMethod": "card",
      "orderUrl": "https://shop.example/orders/4821",
      "customer": { "name": "Sara Khan", "phone": "+447700900123", "city": "Leeds", "country": "GB" },
      "items": [{ "name": "10 ml bottle", "qty": 2 }],
      "tracking": { "carrier": "Royal Mail", "number": "RM482177301GB", "url": "https://www.royalmail.com/track-your-item#/tracking-results/RM482177301GB" },
      "occurredAt": "2026-09-05T10:12:00Z"
    }
  }'

201 { "status": "queued",    "event": "shipped", "eventId": "…", "scheduledAt": "2026-09-05T10:12:01.000Z" }
200 { "status": "duplicate", "event": "shipped", "reason": "already recorded for this order" }
200 { "status": "skipped",   "event": "shipped", "eventId": "…", "reason": "no usable phone number on the order" }
200 { "status": "off",       "event": "shipped", "reason": "order updates are switched off for this bot — enable them under Automations" }
401 { "error": "Send your workspace API key as \"Authorization: Bearer tbk_…\"." }
402 { "error": "This workspace has sent its 1,000 order updates for the month — upgrade in Billing for more." }
422 { "error": "order.customer.phone … / order.orderUrl must be an http(s) URL", "field": "order.orderUrl" }

• Events accept order.shipped or shipped. The full list is below.
• Phone should carry the country code. A local number is normalised with the bot's default country from Automations.
• Idempotency. One message per order per event, ever. Send your own Idempotency-Key header to make that per shipment, per attempt, or whatever your system counts.
• Old news. An event whose occurredAt is more than 24 hours ago is recorded and never sent. Pass "backfill": true to import history the same way.
• Tracking links go through https://platform.tendabot.com/t/<eventId>, which redirects to tracking.url, because a template button needs one fixed address.

Nine updates, one template each.

All nine are utility templates: no promotional wording, so they stay on Meta's cheapest rate. Each can be switched off per bot under Automations.

PUT /api/v1/orders/{externalId}

Records or updates an order without messaging anyone, so the AI can answer “where is my order” for a store that sends no updates, or ahead of the events that will.

curl -X PUT https://platform.tendabot.com/api/v1/orders/5512 \
  -H "Authorization: Bearer tbk_YOUR_KEY" -H "Content-Type: application/json" \
  -d '{ "botId": "YOUR_BOT_ID", "order": { "number": "4821", "status": "processing", "total": "68.00", "currency": "GBP",
        "customer": { "name": "Sara Khan", "phone": "+447700900123" } } }'

200 { "ok": true, "storeOrderId": "…", "reachableOnWhatsApp": true }

GET /api/v1/orders/{externalId}/events

Every update decided for the order: sent, delivered, read, replied, or skipped with the reason. Works with a read-only key. Add &source=wordpress for orders that arrived through the plugin.

curl "https://platform.tendabot.com/api/v1/orders/5512/events?botId=YOUR_BOT_ID" -H "Authorization: Bearer tbk_YOUR_KEY"

200 {
  "order":  { "externalId": "5512", "number": "4821", "status": "shipped", "codDecision": null, "updatedAt": "…" },
  "events": [
    { "id": "…", "event": "shipped", "status": "read", "template": "tb_order_shipped", "sentAt": "…", "deliveredAt": "…", "readAt": "…" },
    { "id": "…", "event": "placed",  "status": "skipped", "reason": "older than 24 hours when it arrived" }
  ]
}

order.replied

A tap on Confirm order, Cancel order, or a feedback button reaches you here. Add a webhook under Bot → Settings → Webhooks and tick order.replied; it is signed with your webhook secret like every Tendabot webhook. WooCommerce stores also get the decision written onto the order by the plugin.

{
  "event": "order.replied",
  "botId": "…", "eventId": "…", "externalId": "5512", "orderNumber": "4821", "source": "api",
  "decision": "confirm",            // confirm | cancel | feedback
  "score": 3,                       // feedback only: 1 not good · 2 okay · 3 great
  "customerWaId": "447700900123",
  "at": "2026-09-05T10:20:31.000Z"
}

What the plan and Meta allow.

• Per month: 1,000 order updates on Starter, 10,000 on Pro, unlimited on Scale. Over the cap the API answers 402 and the console says so.
• Meta's tier: a new WhatsApp number can reach 250 new customers a day, rising to 1,000, 10,000 and 100,000 as quality holds. Bursts are paced inside that.
• From Claude: the MCP tool send_order_update takes the same fields, so an assistant can send one without an HTTP call. See the tool reference.
• Questions: talk to us — pick “Technical support”.