Create an order

Opens an order with its first lines, and sends them to the kitchen when asked.

POSThttps://tablebuddy.radioworkflow.com/api/v1/orders

Write

Opens an order with its first round, as the POS does, and sends the round to the kitchen when send is true. The order is recorded as made through the API, and reads channel: table_buddy.

A dine-in order takes a free table (table_id), and needs one where the restaurant orders by table. A delivery needs delivery_address. Each line names a menu item on sale, a quantity from 1 to 999, the add-ons chosen from its groups, and a note for the kitchen. Prices, tax and the service charge come from the menu and the restaurant's settings, never from the request.

Sending a round makes a kitchen ticket and takes prepared food and recipe stock, as the POS does. See Idempotency before retrying.

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.

Request body

typeenumrequired

Dine-in, takeout, counter or delivery.

DINE_INTAKEAWAYCOUNTERDELIVERY

table_idstringidoptionalnullable

The table, for a dine-in order.

customer_namestring≤ 100 charsoptionalnullable

A name for the order, up to 100 characters.

No NUL character or unpaired surrogate.

customer_phonestring≤ 40 charsoptionalnullable

A phone for the order, up to 40 characters.

No NUL character or unpaired surrogate.

delivery_addressstring≤ 500 charsoptionalnullable

Where to deliver it, up to 500 characters. A delivery needs one.

No NUL character or unpaired surrogate.

guestsinteger1–999optional

How many guests, 1 to 999.

notestring≤ 500 charsoptionalnullable

A note on the whole order, up to 500 characters.

No NUL character or unpaired surrogate.

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

201Created

kot_number is null unless send was true. Read the order back with get-order.

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.

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:

Pick a table for a dine-in order.

A dine-in order with no table, where the restaurant orders by table.

Fix: Send table_id, a table from list-tables.

Table {table} already has order #{number} open. Add to that order instead.

The table already has an open order.

Fix: Add a round to that order with add-order-items.

Table {table} is switched off.

The table is switched off on the floor plan.

Fix: Pick another table from list-tables.

Add the delivery address before sending a delivery order.

A delivery with no address.

Fix: Send delivery_address.

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" \
  -H "Authorization: Bearer $TABLEBUDDY_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H 'Content-Type: application/json' \
  -d '{"type":"COUNTER","lines":[{"menu_item_id":"MENU_ITEM_ID","quantity":1,"addon_ids":[]}],"send":true}'

Response201

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