# Place a pickup order

> Place the diner's pickup order for collection at a branch, paid at the counter or ahead with Tamr Pay.

Source: https://tamr.link/docs/api/place-pickup

`POST https://tamr.link/api/v1/pickup/orders`

The name and phone go to the restaurant only: no answer, event, webhook or log carries them. Paid at the counter, the order reaches the team at once; paid ahead, it waits as `awaiting_payment` until paid and expires unpaid. With a test key it is a [test order](https://tamr.link/docs/guides/test-orders): priced as a real one, answered with `test: true`, never sent to the restaurant.

The name and phone go to the restaurant only: no answer, event, webhook or log carries them. Paid at the counter, the order reaches the team now; paid ahead (the location's `payFirst`), it waits as `awaiting_payment` until paid with `POST /api/v1/pay` and `pay: "order"`, and expires unpaid after 15 minutes.

## 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 | Yes | An address: lower-case letters, digits and dashes. |
| `lines` | array of object | Yes | 1 to 60 items. |
| `lines[].dishId` | string | Yes | 1 to 200 characters. |
| `lines[].variantLabel` | string or null | Yes | 1 to 80 characters. |
| `lines[].quantity` | integer | Yes | 1 to 99. |
| `lines[].note` | string or null | No | At most 140 characters. |
| `lines[].choices` | array of object | No | At most 6 items. |
| `lines[].choices[].group` | string | Yes | 1 to 80 characters. |
| `lines[].choices[].options` | array of string | Yes | At most 24 items. 1 to 80 characters. |
| `lines[].fromWaiter` | boolean | No |  |
| `name` | string | Yes | 1 to 40 characters. |
| `phone` | string | Yes | 1 to 32 characters. |
| `at` | string (date-time) or null | Yes |  |
| `how` | string | Yes | One of `counter`, `curbside`. |
| `car` | string | No | At most 60 characters. |
| `note` | string | No | At most 280 characters. |
| `allergyNote` | string | No | At most 200 characters. |
| `idempotencyKey` | string | Yes | 8 to 64 characters. |

## Response

| Field | Type | Description |
| --- | --- | --- |
| `order` | object |  |
| `order.orderId` | string | 1 to 200 characters. |
| `order.number` | integer | The short number staff call out, per branch and service day. -9,007,199,254,740,991 to 9,007,199,254,740,991. |
| `order.status` | string | One of `awaiting_payment`, `sent`, `accepted`, `served`, `declined`, `cancelled`, `expired`, `unknown`. An open list: read a value you don't know as `unknown`. |
| `order.branch` | string | An address: lower-case letters, digits and dashes. |
| `order.table` | string or null | 1 to 40 characters. |
| `order.currency` | string | A three-letter currency code (ISO 4217). |
| `order.subtotal` | string | An amount in minor units, as a string. |
| `order.lines` | array of object | 1 to 100 items. |
| `order.lines[].dishId` | string or null | 1 to 200 characters. |
| `order.lines[].externalId` | string or null | 1 to 200 characters. |
| `order.lines[].title` | string | 1 to 200 characters. |
| `order.lines[].variantLabel` | string or null | 1 to 80 characters. |
| `order.lines[].quantity` | integer | -9,007,199,254,740,991 to 9,007,199,254,740,991. |
| `order.lines[].unitPrice` | string | An amount in minor units, as a string. |
| `order.fulfilment` | string | May be absent. One of `dine_in`, `pickup`, `unknown`. An open list: read a value you don't know as `unknown`. |
| `order.pickupAt` | string (date-time) or null | May be absent. |
| `order.pickupCode` | string or null | May be absent. 1 to 12 characters. |
| `order.test` | boolean | May be absent. |
| `order.paymentDueAt` | string (date-time) or null |  |
| `order.paid` | boolean |  |

## Example

curl:

```bash
curl https://tamr.link/api/v1/pickup/orders \
  -H "x-tamr-key: $TAMR_APP_KEY" \
  -H "x-tamr-session: $TAMR_SESSION" \
  -H "content-type: application/json" \
  -d '{
  "branch": "hamra",
  "lines": [
    {
      "dishId": "dish_kafta",
      "variantLabel": null,
      "quantity": 2
    }
  ],
  "name": "Rania",
  "phone": "+961 71 234 567",
  "at": null,
  "how": "counter",
  "idempotencyKey": "pickup-aaaaaaaa"
}'
```

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.pickupOrdersPlace({
  branch: "hamra",
  lines: [
    { dishId: "dish_kafta", variantLabel: null, quantity: 2 },
  ],
  name: "Rania",
  phone: "+961 71 234 567",
  at: null,
  how: "counter",
  idempotencyKey: "pickup-aaaaaaaa",
});
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}/pickup/orders",
    headers=headers,
    json={
        "branch": "hamra",
        "lines": [
            {
                "dishId": "dish_kafta",
                "variantLabel": None,
                "quantity": 2,
            },
        ],
        "name": "Rania",
        "phone": "+961 71 234 567",
        "at": None,
        "how": "counter",
        "idempotencyKey": "pickup-aaaaaaaa",
    },
    timeout=30,
)
response.raise_for_status()
print(response.json())
```

## Example response

```json
{
  "order": {
    "orderId": "ord_0599",
    "number": 23,
    "status": "sent",
    "branch": "hamra",
    "table": null,
    "currency": "LBP",
    "subtotal": "290000",
    "lines": [
      {
        "dishId": "dish_kafta",
        "externalId": "SKU-1042",
        "title": "Kafta plate",
        "variantLabel": null,
        "quantity": 2,
        "unitPrice": "145000"
      }
    ],
    "fulfilment": "pickup",
    "pickupAt": null,
    "pickupCode": "4821",
    "paymentDueAt": null,
    "paid": false
  }
}
```

## 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. |
| `pickup_refused` | 409 | A pickup was refused. `pickupRefusal` says why. |
| `unavailable` | 503 | Tamr can't serve this now. Try again later. |
