Sending your orders to Tamr

When orders go to your app's cart, send each order your checkout placed to Tamr from your backend, so the AI waiter can offer the diner's usual and one-tap reorder.

When the restaurant's orders go to your app's cart, your checkout places them, not Tamr. Your backend sends each one to Tamr with Send an order, using a secret key with the orders:sdk permission. Tamr uses them for the diner's usual, one-tap reorder, post-meal reviews and the restaurant's Insights. They never show on the restaurant's kitchen or service screens.

When orders go to Tamr, there is nothing to send: your backend hears order.placed and payment.completed as webhooks.

The order

POST /api/v1/sdk/orders
{
  "externalOrderId": "EXT-ORDER-88",
  "externalUserId": "user-88213",
  "branch": "achrafieh",
  "mode": "delivery",
  "status": "completed",
  "currency": "LBP",
  "total": "355000",
  "placedAt": "2026-10-23T11:40:00Z",
  "lines": [
    {
      "externalId": "SKU-1042",
      "title": "Kafta plate",
      "quantity": 2,
      "unitPrice": "145000"
    },
    {
      "externalId": "BOWL",
      "variantExternalId": "BOWL-L",
      "optionExternalIds": [
        "CHK",
        "HUM"
      ],
      "title": "Build your bowl",
      "quantity": 1,
      "unitPrice": "320000"
    }
  ]
}
Field
externalOrderIdYour order's id. Required. Sending is idempotent on it.
externalUserIdYour user's id, the same as the token's sub. Required. Never a name, phone or email.
branchOptional. The branch address. An unknown one is refused with 400.
modeOptional. dine_in, pickup or delivery.
statusRequired. placed, completed, cancelled or refunded.
currency, totalRequired. A three-letter currency code and the total in minor units, as a string.
placedAt, updatedAtplacedAt is required. updatedAt is when you last changed the order; left out, it is placedAt.
lines1 to 100. Each names its dish by exactly one id, Tamr's dishId or your externalId, with sizes and options by Tamr's ids or yours. title, quantity (1 to 99) and unitPrice are required. picks only on a set.

Sending again

  • The same order with the same or an earlier updatedAt changes nothing and returns the same answer. Retry freely after a timeout.
  • A later updatedAt replaces the order's status, totals and lines. Send the whole order each time it changes (a refund, a cancellation): a field you leave out is cleared.

The answer

200 OK
{
  "orderId": "aord_0001",
  "externalOrderId": "EXT-ORDER-88",
  "status": "completed",
  "updatedAt": "2026-10-23T11:40:00.000Z",
  "currencyMismatch": false,
  "lines": [
    {
      "dishId": "dish_kafta",
      "mapped": true
    },
    {
      "dishId": null,
      "mapped": false
    }
  ]
}

A line Tamr can't place on a dish comes back mapped: false and is kept with its title; it starts counting once you map the product. currencyMismatch is true when the currency isn't one the restaurant's menus use; the order is kept as sent and never converted. Read a status you don't know as placed.

What the waiter does with them

For a signed-in diner, the waiter reads their orders on every message. Their usual is the top 3 dishes that appear in at least half of their last 10 completed orders, with at least 3 such orders; otherwise their last order stands in. When the diner asks for "the usual" or "the same as last time", the waiter proposes those lines to your cart at today's menu and prices, and names any dish no longer on the menu.

The waiter page also shows a "Your usual" card on the welcome screen, with a Reorder button, when at least one of those dishes is on sale. A client that draws its own chat reads the same thing from Get the diner's usual. An order can arrive before the user's first chat. Guests have no usual.

How long orders are kept

Orders you send are kept for 12 months from placedAt, then deleted. A restaurant's agreement with Tamr can set a shorter period. Erasing a user deletes their orders at once.