Skip to content
Table BuddyTable BuddyRestaurant platform
Sign inGet started
API referenceStock

Adjust stock

Try it

Records stock in, stock out, wastage, or a count that sets on-hand to what was counted.

POSThttps://tablebuddy.radioworkflow.com/api/v1/inventory/materials/{material_id}/adjustments
Write

What the stockroom screen records: stock in (in), stock out (out), wastage (wastage), or a count (count) that sets on-hand to what was counted and records the difference as a movement. Every count is kept, even one that finds the books right; that one moves nothing and answers changed: false.

Out and wastage may not take more than the books hold: count first. Stock in with a unit_cost re-weights the material's average cost. quantity_milli is in thousandths of the material's unit: 1.5 kg is 1500.

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
inventory:writeAdjust stock
The key's creator needs
Adjust stock (inventory.manage)

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

material_idstringidrequired
The material.

Request body

modeenumrequired
in, out or wastage moves stock by quantity_milli; count sets on-hand to it.
inoutwastagecount
quantity_milliinteger0–100,000,000required
Thousandths of the material's unit: 1.5 kg is 1500.
unit_costinteger0–100,000,000optionalnullable
For stock in: what one whole unit cost, in minor units.
reasonstring1–300 charsrequired
Why, 1 to 300 characters, not blank: the stock card keeps the first 200.

Not blank; no NUL character or unpaired surrogate.

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

delta_milli is how much on-hand moved; balance_milli is on hand now.

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.
adjustmentobject
What the adjustment did.
adjustment.changedboolean
False when a count found on-hand already right.
adjustment.namestring
The material's name.
adjustment.unitstring
Its unit.
adjustment.delta_milliintegermilli-units
How much on-hand moved, signed.
adjustment.balance_milliintegermilli-units
On hand now.

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 material is not this restaurant's.

Fix: Find it with list-materials.

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:

Only {quantity} of {material} is on the books. If there is more on the shelf, count it first.

Out or wastage past what the books hold.

Fix: Send a count of what is there first, then the out or the wastage.

{material} is archived. Restore it first.

An archived material.

Fix: Restore it in Table Buddy's stockroom first.

Enter a quantity above zero.

Stock in, out or wastage of zero.

Fix: Send a quantity above 0; only a count may be 0.

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/inventory/materials/MATERIAL_ID/adjustments" \
  -H "Authorization: Bearer $TABLEBUDDY_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H 'Content-Type: application/json' \
  -d '{"mode":"count","quantity_milli":17250,"reason":"Walk-in count"}'
Response200
{
  "currency": "USD",
  "minor_digits": 2,
  "adjustment": {
    "changed": true,
    "name": "Atlantic salmon fillet",
    "unit": "lb",
    "delta_milli": -1250,
    "balance_milli": 17250
  }
}