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.

PUT/api/v1/catalog/external-idsServer API · secret key

Your 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

FieldTypeRequiredDescription
refsarray of objectYes1 to 500 items.
refs[].kindstringYesOne of dish, variant, option.
refs[].tamrIdstringYes1 to 200 characters.
refs[].externalIdstring or nullYes1 to 200 characters.
refs[].branchstringNoAn address: lower-case letters, digits and dashes.

Response

FieldTypeDescription
setinteger0 to 9,007,199,254,740,991.
removedinteger0 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
    }
  ]
}'

Example response

{
  "set": 2,
  "removed": 1
}

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 catalog: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.