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.
/api/v1/sdk/ordersServer API · secret keyWhen 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.
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 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"
}
]
}'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);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
{
"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.
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. |