# 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.

Source: https://tamr.link/docs/api/set-external-ids

`PUT https://tamr.link/api/v1/catalog/external-ids`

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](https://tamr.link/docs/api/get-menu). See [Your product ids and nutrition](https://tamr.link/docs/guides/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:

```bash
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
    }
  ]
}'
```

Node:

```js
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);
```

Python:

```python
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

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

## Errors

Every error has the same body; switch on `data.code`. See [Errors and rate limits](https://tamr.link/docs/errors).

| `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. |
