Place a pickup order

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

POST/api/v1/pickup/ordersClient API

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

NameTypeRequiredDescription
x-tamr-devicestringNoGuest sessions only: the device id the session was exchanged with. Matches ^[A-Za-z0-9_-]{8,128}$.
x-tamr-appstringNoNative 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

FieldTypeRequiredDescription
branchstringYesAn address: lower-case letters, digits and dashes.
linesarray of objectYes1 to 60 items.
lines[].dishIdstringYes1 to 200 characters.
lines[].variantLabelstring or nullYes1 to 80 characters.
lines[].quantityintegerYes1 to 99.
lines[].notestring or nullNoAt most 140 characters.
lines[].choicesarray of objectNoAt most 6 items.
lines[].choices[].groupstringYes1 to 80 characters.
lines[].choices[].optionsarray of stringYesAt most 24 items. 1 to 80 characters.
lines[].fromWaiterbooleanNo
namestringYes1 to 40 characters.
phonestringYes1 to 32 characters.
atstring (date-time) or nullYes
howstringYesOne of counter, curbside.
carstringNoAt most 60 characters.
notestringNoAt most 280 characters.
allergyNotestringNoAt most 200 characters.
idempotencyKeystringYes8 to 64 characters.

Response

FieldTypeDescription
orderobject
order.orderIdstring1 to 200 characters.
order.numberintegerThe short number staff call out, per branch and service day. -9,007,199,254,740,991 to 9,007,199,254,740,991.
order.statusstringOne of awaiting_payment, sent, accepted, served, declined, cancelled, expired, unknown. An open list: read a value you don't know as unknown.
order.branchstringAn address: lower-case letters, digits and dashes.
order.tablestring or null1 to 40 characters.
order.currencystringA three-letter currency code (ISO 4217).
order.subtotalstringAn amount in minor units, as a string.
order.linesarray of object1 to 100 items.
order.lines[].dishIdstring or null1 to 200 characters.
order.lines[].externalIdstring or null1 to 200 characters.
order.lines[].titlestring1 to 200 characters.
order.lines[].variantLabelstring or null1 to 80 characters.
order.lines[].quantityinteger-9,007,199,254,740,991 to 9,007,199,254,740,991.
order.lines[].unitPricestringAn amount in minor units, as a string.
order.fulfilmentstringMay be absent. One of dine_in, pickup, unknown. An open list: read a value you don't know as unknown.
order.pickupAtstring (date-time) or nullMay be absent.
order.pickupCodestring or nullMay be absent. 1 to 12 characters.
order.testbooleanMay be absent.
order.paymentDueAtstring (date-time) or null
order.paidboolean

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"
}'

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.codeStatusWhat to do
app_key_invalid401The key is wrong, revoked or of another kind. Check it in the dashboard.
sdk_disabled403The SDK isn't switched on for this restaurant. Ask Tamr.
origin_not_allowed403A browser called from an origin the key doesn't list. Add the origin to the key.
session_expired401Start a new session with a fresh token or code, then send the call again once.
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.
pickup_refused409A pickup was refused. pickupRefusal says why.
unavailable503Tamr can't serve this now. Try again later.