Place a pickup order
Place the diner's pickup order for collection at a branch, paid at the counter or ahead with Tamr Pay.
/api/v1/pickup/ordersClient APIThe 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: 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. 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 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"
}'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);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
{
"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.
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. |