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

Source: https://tamr.link/docs/api/match-cart

`POST https://tamr.link/api/v1/cart/match`

Your 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](https://tamr.link/docs/api/start-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:

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

Node:

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

Python:

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

```json
{
  "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](https://tamr.link/docs/errors).

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