Match your cart
Match your app's cart lines to the dishes the AI waiter serves, by Tamr's ids or your own; unplaceable lines come back unmapped.
POST
/api/v1/cart/matchClient APIYour cart's lines as the dishes of the menu the waiter serves, by Tamr's ids or yours. Lines Tamr can't place come back in unmapped, such as drinks from another system.
Authentication
Client API. Send your publishable key in x-tamr-key and the diner's session in x-tamr-session, from Start a session. For a guest's session, also send its device id in x-tamr-device. A browser may call it only from an origin listed on the key.
Headers
| Name | Type | Required | Description |
|---|---|---|---|
x-tamr-device | string | No | Guest sessions only: the device id the session was exchanged with. Matches ^[A-Za-z0-9_-]{8,128}$. |
x-tamr-app | string | No | Native apps only: the app's iOS bundle id or Android package name. A key used from an app it doesn't list is logged, never refused. Matches ^[A-Za-z][A-Za-z0-9_-]*(\.[A-Za-z0-9_-]+)+$. |
Request body
| Field | Type | Required | Description |
|---|---|---|---|
branch | string | No | An address: lower-case letters, digits and dashes. |
mode | string | No | One of dine_in, pickup, delivery. |
lines | array of object | Yes | At most 50 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[].quantity | integer | Yes | 1 to 99. |
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 |
|---|---|---|
lines | array of object | At most 50 items. |
lines[].dishId | string | 1 to 200 characters. |
lines[].name | string | 1 to 200 characters. |
lines[].variantId | string or null | 1 to 200 characters. |
lines[].optionIds | array of string | At most 20 items. 1 to 200 characters. |
lines[].quantity | integer | 1 to 99. |
lines[].picks | array of object | May be absent. At most 120 items. |
lines[].picks[].pickId | string | 1 to 200 characters. |
lines[].picks[].count | integer | 1 to 20. |
unmapped | array of object | At most 50 items. |
unmapped[].externalId | string | 1 to 200 characters. |
Example
curl https://tamr.link/api/v1/cart/match \
-H "x-tamr-key: $TAMR_APP_KEY" \
-H "x-tamr-session: $TAMR_SESSION" \
-H "content-type: application/json" \
-d '{
"lines": [
{
"dishId": "dish_kafta",
"quantity": 2
},
{
"externalId": "SKU-1042",
"quantity": 1
},
{
"externalId": "DRINK-7",
"quantity": 3
}
]
}'import { createClient } from "@tamr/api";
const tamr = createClient({ appKey: process.env.TAMR_APP_KEY });
// Sign the diner in first, with a token your backend signed (or a launch code).
await tamr.startSession({ token: dinerToken });
const result = await tamr.cartMatch({
lines: [
{ dishId: "dish_kafta", quantity: 2 },
{ externalId: "SKU-1042", quantity: 1 },
{ externalId: "DRINK-7", quantity: 3 },
],
});
console.log(result);import os
import requests
API = "https://tamr.link/api/v1"
headers = {
"x-tamr-key": os.environ["TAMR_APP_KEY"],
"x-tamr-session": os.environ["TAMR_SESSION"], # from POST /api/v1/sdk/session
}
response = requests.post(
f"{API}/cart/match",
headers=headers,
json={
"lines": [
{"dishId": "dish_kafta", "quantity": 2},
{"externalId": "SKU-1042", "quantity": 1},
{"externalId": "DRINK-7", "quantity": 3},
],
},
timeout=30,
)
response.raise_for_status()
print(response.json())Example response
{
"lines": [
{
"dishId": "dish_kafta",
"name": "Kafta plate",
"variantId": null,
"optionIds": [],
"quantity": 3
},
{
"dishId": "dish_bowl",
"name": "Build your bowl",
"variantId": "var_large",
"optionIds": [
"opt_chicken"
],
"quantity": 1
}
],
"unmapped": [
{
"externalId": "DRINK-7"
}
]
}Errors
Every error has the same body; switch on data.code. See Errors and rate limits.
data.code | Status | What to do |
|---|---|---|
app_key_invalid | 401 | The key is wrong, revoked or of another kind. Check it in the dashboard. |
sdk_disabled | 403 | The SDK isn't switched on for this restaurant. Ask Tamr. |
origin_not_allowed | 403 | A browser called from an origin the key doesn't list. Add the origin to the key. |
session_expired | 401 | Start a new session with a fresh token or code, then send the call again once. |
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. |
menu_unavailable | 404 | No published menu is served at that branch and service mode. |
not_found | 404 | Not this diner's, or doesn't exist. The two read the same on purpose. |