Add a round to an order

Adds lines to an open order, and sends them to the kitchen when asked.

POSThttps://tablebuddy.radioworkflow.com/api/v1/orders/{order_id}/items

Write

Adds a round of lines to an open order, and sends it to the kitchen when send is true. The lines follow create-order's rules. A completed or cancelled order is refused, and so is a check another system recorded, which arrives closed.

Authentication

Key

Authorization: Bearer <key>, or the same key in x-api-key. A key acts as the person who made it, cut down to this endpoint’s scope, and never as an owner. How keys work

Scope

orders:writeCreate orders, send rounds and change unsent items

The key's creator needs

Take orders on the POS (pos.use)

Request headers

Authorizationrequired

Bearer <key>. x-api-key: <key> works too; Authorization wins when both are sent.

Idempotency-Keyrequired

A fresh key for each operation, such as a UUID. Send the same key only to retry the same request: the kept answer comes back, and nothing runs twice. Idempotency

Content-Typerequired

application/json: the body is JSON.

Path parameters

order_idstringidrequired

The order.

Request body

linesarray of object1–200 itemsrequired

The lines to ring up, 1 to 200.

lines[].menu_item_idstringidrequired

A menu item from list-menu-items.

lines[].quantityinteger1–999required

How many, 1 to 999.

lines[].addon_idsarray of stringid≤ 40 itemsoptional

Add-ons chosen from the item's groups.

Default [].

lines[].notestring≤ 200 charsoptionalnullable

A note for the kitchen on this line.

No NUL character or unpaired surrogate.

sendbooleanoptional

Send the new lines to the kitchen at once.

Default false.

A field the endpoint does not take is answered 422 invalid_request naming it, before anything is looked up or the Idempotency-Key is used.

Response

200OK

kot_number is null unless send was true.

currencystringISO 4217

The restaurant's currency: every amount in this answer is in its minor units.

minor_digitsinteger0–3

Digits after the point when an amount is shown: 2 for USD (cents), 0 for JPY.

order_idstringid

The order.

numberinteger

Its number.

kot_numberintegernullable

The kitchen ticket this round made; null when nothing was sent.

An answer may gain fields within v1: ignore the ones you do not know. Versioning

Response headers

request-idalways

This request’s id. Quote it when asking for help.

Cache-Controlalways

no-store: an answer is never cached.

RateLimit-Limit, RateLimit-Remaining, RateLimit-Resetonce the key is known

The key’s units a minute, what is left of this minute’s, and the seconds until the window starts again. Never on a 401. Rate limits

x-error-codeon an error

The error’s code, the same as error.code in the body.

Idempotent-Replayed, Original-Request-Idon a replayed write

true, and the request-id of the request that ran: this is the kept answer to an earlier request with the same Idempotency-Key.

Retry-Afteron a 429, and a 409 idempotency_key_in_use

Seconds to wait before sending the same request again.

WWW-Authenticateon a 401, and a 403 insufficient_scope

The Bearer challenge, naming what was wrong with the key or the scope it lacks.

Errors

400invalid_idempotency_key

The Idempotency-Key header is not 8–255 of A–Z a–z 0–9 - _ . : ~ + / =.

Fix: Send a UUID.

400idempotency_key_required

A POST was sent without an Idempotency-Key.

Fix: Generate one per operation; reuse it only to retry that operation.

403insufficient_scope

The key does not carry the endpoint's scope.

Fix: Scopes are fixed when a key is made: make a new key with the scope.

403issuer_access_ended

The key's creator has left the restaurant, was suspended, or was removed and invited back.

Fix: Make a new key from an active account.

403issuer_permission_changed

The key's creator no longer holds any permission that could put this scope on a key.

Fix: Ask an owner to restore the permission, or make a new key from an account that holds it.

403permission_required

The key's permissions for this endpoint (its creator's, cut down to the endpoint's scope) do not include what this endpoint, or this argument, needs. The message names it.

Fix: Use a key with the named scope, from a creator who holds the named permission.

404not_found

The order is not this restaurant's.

Fix: Find it with list-orders.

409refused

The engine refused the act; the message is its own sentence, the same the console shows, except that it never names a guest or a staff member.

Fix: Read the sentence: it says what to change. The endpoint page lists the common ones.

409idempotency_key_in_use

Another request with this key is still running.

Fix: Wait Retry-After seconds and send the same request again.

413payload_too_large

The body is over 1 MiB.

Fix: Send less; split a batch.

415json_required

A write without Content-Type: application/json.

Fix: Send JSON with that header.

422invalid_request

The request does not match the endpoint's published schema: a missing or unknown field or query parameter, a value out of range. The message names the first four problems.

Fix: Fix the named fields. Nothing was done, and an Idempotency-Key is not used up.

422idempotency_key_reused

The key was used for a different request in the last 24 hours.

Fix: Use a new key for a new request.

Refused by the restaurant’s rules

Answered 409 refused with the engine’s own sentence, the one the console shows. The common ones:

Order #{number} is closed. Start a new order.

The order is completed or cancelled, or a check another system recorded.

Fix: Open a new order with create-order.

One of those items is no longer on the menu.

An item that is off the menu, or not this restaurant's.

Fix: Pick items from list-menu-items with active=true.

{item} is marked unavailable.

An item that is sold out (86ed).

Fix: Pick another item, or put it back on sale with set-menu-item-availability.

{item} is sold out.

A prepared item with no portions left.

Fix: Pick another item, or log more portions made in Table Buddy.

{item} is in a category hidden from the POS.

An item in a category hidden from the POS.

Fix: Pick another item, or show its category on the POS.

That add-on is not available for {item}.

An add-on the item does not offer.

Fix: Pick add-ons from the item's addon_groups (get-menu-item).

{item}: choose {count} {group}.

Fewer add-ons than a group requires.

Fix: Choose at least the group's min_select add-ons from it.

{item}: choose at most {count} for {group}.

More add-ons than a group allows.

Fix: Choose at most the group's max_select add-ons from it.

Possible on every endpoint

401missing_api_keyNo Authorization: Bearer header and no x-api-key header.

401invalid_api_keyThe key is unknown, revoked or expired (answered alike).

429rate_limitedOver the key's 60 units a minute, or over 30 unknown keys a minute from one network (an address; an IPv6 caller's /64).

500internal_errorSomething failed on our side. Nothing kept the Idempotency-Key.

Every code, and when to retry

Request

curl -X POST "$TABLEBUDDY_URL/api/v1/orders/ORDER_ID/items" \
  -H "Authorization: Bearer $TABLEBUDDY_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H 'Content-Type: application/json' \
  -d '{"lines":[{"menu_item_id":"MENU_ITEM_ID","quantity":2,"addon_ids":["ADDON_ID"],"note":"Well done"}],"send":false}'

Response200

{
  "currency": "USD",
  "minor_digits": 2,
  "order_id": "cmg5x0q2k0001tb2j8v4h6y3n",
  "number": 142,
  "kot_number": null
}