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.

POST/api/v1/sdk/ordersServer API · secret key

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.

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

FieldTypeRequiredDescription
externalOrderIdstringYes1 to 200 characters.
externalUserIdstringYes1 to 200 characters.
branchstringNoAn address: lower-case letters, digits and dashes.
modestringNoOne of dine_in, pickup, delivery.
statusstringYesOne of placed, completed, cancelled, refunded.
currencystringYesA three-letter currency code (ISO 4217).
totalstringYesAn amount in minor units, as a string.
placedAtstring (date-time)Yes
updatedAtstring (date-time)No
linesarray of objectYes1 to 100 items.
lines[].dishIdstringNo1 to 200 characters.
lines[].externalIdstringNo1 to 200 characters.
lines[].variantIdstringNo1 to 200 characters.
lines[].variantExternalIdstringNo1 to 200 characters.
lines[].optionIdsarray of stringNoAt most 20 items. 1 to 200 characters.
lines[].optionExternalIdsarray of stringNoAt most 20 items. 1 to 200 characters.
lines[].titlestringYes1 to 200 characters.
lines[].quantityintegerYes1 to 99.
lines[].unitPricestringYesAn amount in minor units, as a string.
lines[].picksarray of objectNoAt most 120 items.
lines[].picks[].pickIdstringNo1 to 200 characters.
lines[].picks[].externalIdstringNo1 to 200 characters.
lines[].picks[].variantExternalIdstringNo1 to 200 characters.
lines[].picks[].countintegerYes1 to 20.

Response

FieldTypeDescription
orderIdstring1 to 200 characters.
externalOrderIdstring1 to 200 characters.
statusstringOne of placed, completed, cancelled, refunded. An open list: read a value you don't know as placed.
updatedAtstring (date-time)
currencyMismatchboolean
linesarray of object1 to 100 items.
lines[].dishIdstring or null1 to 200 characters.
lines[].mappedboolean

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"
    }
  ]
}'

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.codeStatusWhat to do
other401No secret key, or one Tamr doesn't accept: wrong, revoked, or made by someone who is no longer an owner or admin.
other403The key doesn't have the orders:sdk permission.
invalid_request400A field doesn't match the spec. The message says which.
rate_limited429Wait retryAfter seconds (also in the Retry-After header), then try again.
sdk_disabled403The SDK isn't switched on for this restaurant. Ask Tamr.