# Send an order

> Send an order your own checkout placed to Tamr, so the AI waiter can offer the diner's usual, reorders and post-meal reviews.

Source: https://tamr.link/docs/api/send-order

`POST https://tamr.link/api/v1/sdk/orders`

When the restaurant's orders go to your app's cart, your checkout places them and your backend sends each one here. Tamr uses them for the diner's usual, one-tap reorder, post-meal reviews and the restaurant's Insights; they never show on the kitchen's screens. Sending is idempotent on `externalOrderId`: the same order with the same or an earlier `updatedAt` changes nothing, and a later `updatedAt` replaces the order whole. See [Sending your orders](https://tamr.link/docs/guides/sending-orders).

## Authentication

**Server API.** Send a secret API key with the **Orders (SDK)** permission (`orders:sdk`) as `Authorization: Bearer <key>`. Secret keys are made in **Settings > API keys** by an owner or admin. Keep them on your server: no browser can call this route.

## Request body

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `externalOrderId` | string | Yes | 1 to 200 characters. |
| `externalUserId` | string | Yes | 1 to 200 characters. |
| `branch` | string | No | An address: lower-case letters, digits and dashes. |
| `mode` | string | No | One of `dine_in`, `pickup`, `delivery`. |
| `status` | string | Yes | One of `placed`, `completed`, `cancelled`, `refunded`. |
| `currency` | string | Yes | A three-letter currency code (ISO 4217). |
| `total` | string | Yes | An amount in minor units, as a string. |
| `placedAt` | string (date-time) | Yes |  |
| `updatedAt` | string (date-time) | No |  |
| `lines` | array of object | Yes | 1 to 100 items. |
| `lines[].dishId` | string | No | 1 to 200 characters. |
| `lines[].externalId` | string | No | 1 to 200 characters. |
| `lines[].variantId` | string | No | 1 to 200 characters. |
| `lines[].variantExternalId` | string | No | 1 to 200 characters. |
| `lines[].optionIds` | array of string | No | At most 20 items. 1 to 200 characters. |
| `lines[].optionExternalIds` | array of string | No | At most 20 items. 1 to 200 characters. |
| `lines[].title` | string | Yes | 1 to 200 characters. |
| `lines[].quantity` | integer | Yes | 1 to 99. |
| `lines[].unitPrice` | string | Yes | An amount in minor units, as a string. |
| `lines[].picks` | array of object | No | At most 120 items. |
| `lines[].picks[].pickId` | string | No | 1 to 200 characters. |
| `lines[].picks[].externalId` | string | No | 1 to 200 characters. |
| `lines[].picks[].variantExternalId` | string | No | 1 to 200 characters. |
| `lines[].picks[].count` | integer | Yes | 1 to 20. |

## Response

| Field | Type | Description |
| --- | --- | --- |
| `orderId` | string | 1 to 200 characters. |
| `externalOrderId` | string | 1 to 200 characters. |
| `status` | string | One of `placed`, `completed`, `cancelled`, `refunded`. An open list: read a value you don't know as `placed`. |
| `updatedAt` | string (date-time) |  |
| `currencyMismatch` | boolean |  |
| `lines` | array of object | 1 to 100 items. |
| `lines[].dishId` | string or null | 1 to 200 characters. |
| `lines[].mapped` | boolean |  |

## Example

curl:

```bash
curl https://tamr.link/api/v1/sdk/orders \
  -H "Authorization: Bearer $TAMR_SECRET_KEY" \
  -H "content-type: application/json" \
  -d '{
  "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"
    }
  ]
}'
```

Node:

```js
import { createServerClient } from "@tamr/api/server";

const tamr = createServerClient({ secretKey: process.env.TAMR_SECRET_KEY });

const result = await tamr.sdkOrders({
  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",
    },
  ],
});
console.log(result);
```

Python:

```python
import os

import requests

API = "https://tamr.link/api/v1"
headers = {"Authorization": f"Bearer {os.environ['TAMR_SECRET_KEY']}"}

response = requests.post(
    f"{API}/sdk/orders",
    headers=headers,
    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",
            },
        ],
    },
    timeout=30,
)
response.raise_for_status()
print(response.json())
```

## Example response

```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
    }
  ]
}
```

## Errors

Every error has the same body; switch on `data.code`. See [Errors and rate limits](https://tamr.link/docs/errors).

| `data.code` | Status | What to do |
| --- | --- | --- |
| `other` | 401 | No secret key, or one Tamr doesn't accept: wrong, revoked, or made by someone who is no longer an owner or admin. |
| `other` | 403 | The key doesn't have the `orders:sdk` permission. |
| `invalid_request` | 400 | A field doesn't match the spec. The message says which. |
| `rate_limited` | 429 | Wait `retryAfter` seconds (also in the `Retry-After` header), then try again. |
| `sdk_disabled` | 403 | The SDK isn't switched on for this restaurant. Ask Tamr. |
