# 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.

Source: https://tamr.link/docs/guides/sending-orders

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](https://tamr.link/docs/api/send-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](https://tamr.link/docs/webhooks).

## The order

POST /api/v1/sdk/orders:

```json
{
  "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 | |
| --- | --- |
| `externalOrderId` | Your order's id. Required. Sending is idempotent on it. |
| `externalUserId` | Your user's id, the same as the token's `sub`. Required. Never a name, phone or email. |
| `branch` | Optional. The branch address. An unknown one is refused with 400. |
| `mode` | Optional. `dine_in`, `pickup` or `delivery`. |
| `status` | Required. `placed`, `completed`, `cancelled` or `refunded`. |
| `currency`, `total` | Required. A three-letter currency code and the total in minor units, as a string. |
| `placedAt`, `updatedAt` | `placedAt` is required. `updatedAt` is when you last changed the order; left out, it is `placedAt`. |
| `lines` | 1 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:

```json
{
  "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](https://tamr.link/docs/api/get-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](https://tamr.link/docs/guides/erasing-a-user) deletes their orders at once.
