Set your product ids
Map your own SKUs and product ids to the restaurant's dishes, sizes and options, up to 500 at a time.
/api/v1/catalog/external-idsServer API · secret keyYour ids for the restaurant's dishes (dish), sizes (variant) and options (option), so every cart line and webhook names your products. Up to 500 refs a call, all or nothing: a refused call is a 400 whose data.rows gives each bad row's index and reason. externalId: null removes a mapping, and branch makes an id apply at that branch only. Tamr's ids are in the External ids page's CSV and in Get the menu. See Your product ids and nutrition.
Authentication
Server API. Send a secret API key with the Catalog ids (SDK) permission (catalog: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 |
|---|---|---|---|
refs | array of object | Yes | 1 to 500 items. |
refs[].kind | string | Yes | One of dish, variant, option. |
refs[].tamrId | string | Yes | 1 to 200 characters. |
refs[].externalId | string or null | Yes | 1 to 200 characters. |
refs[].branch | string | No | An address: lower-case letters, digits and dashes. |
Response
| Field | Type | Description |
|---|---|---|
set | integer | 0 to 9,007,199,254,740,991. |
removed | integer | 0 to 9,007,199,254,740,991. |
Example
curl -X PUT https://tamr.link/api/v1/catalog/external-ids \
-H "Authorization: Bearer $TAMR_SECRET_KEY" \
-H "content-type: application/json" \
-d '{
"refs": [
{
"kind": "dish",
"tamrId": "dish_kafta",
"externalId": "SKU-1042"
},
{
"kind": "variant",
"tamrId": "var_large",
"externalId": "BOWL-L",
"branch": "achrafieh"
},
{
"kind": "option",
"tamrId": "opt_rice",
"externalId": null
}
]
}'import { createServerClient } from "@tamr/api/server";
const tamr = createServerClient({ secretKey: process.env.TAMR_SECRET_KEY });
const result = await tamr.externalIdsPut({
refs: [
{
kind: "dish",
tamrId: "dish_kafta",
externalId: "SKU-1042",
},
{
kind: "variant",
tamrId: "var_large",
externalId: "BOWL-L",
branch: "achrafieh",
},
{ kind: "option", tamrId: "opt_rice", externalId: null },
],
});
console.log(result);import os
import requests
API = "https://tamr.link/api/v1"
headers = {"Authorization": f"Bearer {os.environ['TAMR_SECRET_KEY']}"}
response = requests.put(
f"{API}/catalog/external-ids",
headers=headers,
json={
"refs": [
{
"kind": "dish",
"tamrId": "dish_kafta",
"externalId": "SKU-1042",
},
{
"kind": "variant",
"tamrId": "var_large",
"externalId": "BOWL-L",
"branch": "achrafieh",
},
{"kind": "option", "tamrId": "opt_rice", "externalId": None},
],
},
timeout=30,
)
response.raise_for_status()
print(response.json())Example response
{
"set": 2,
"removed": 1
}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 catalog: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. |