Orders · Tenvelo API

GET/v1/exchanges

List a sale's exchanges

No. listExchangesAuth pos:orders:write
Returns the exchanges a sale is the original of, oldest first: each pairs a refund of this sale with the replacement sale the guest took instead. Always filtered by order_id.
Parameters

cursorquery · string
Opaque cursor from a previous page's next_cursor. Omit to start from the beginning.
Pass it back exactly as received. It is base64 and its structure is not part of this contract — decoding it, or constructing one by hand, will break without notice.

limitquery · integer · int32
Maximum items to return. The server may return fewer, so always drive the loop from has_more rather than from the size of the page you got back.

order_idquery · string · uuid
Required
The original sale.
Responses

200
A page of the sale's exchanges.

ExchangePage · application/json

has_moreboolean

Required
Whether another page follows.

itemsarray of Exchange

Required

idstring · uuid

Required
UUIDv7, minted by whoever recorded the exchange.

created_atTimestamp

RequiredRead only
Server-assigned RFC 3339 timestamp, always UTC.
Server-assigned because device clocks drift and cannot be trusted for ordering — a till that has been powered off for a week may come back with a clock hours out. Where the device's own view of time matters it is carried separately in client_created_at.

original_order_idstring · uuid

Required
The sale the goods came back from.

refund_idstring · uuid

Required
The refund of the returned goods, a refund of original_order_id.

replacement_order_idstring · uuid

Required
The completed sale of what the guest took instead. A different sale from the original.

next_cursorstring

Nullable
Opaque cursor for the next page, or null on the last page. Pass it back verbatim as the cursor query parameter; its contents are not part of this contract.

400
The request could not be parsed. Malformed JSON, a bad query parameter, or a header that failed to decode, among them an API-Version later than the server speaks or not a date (api-version-unknown, with the server's own in api_version).
Distinct from 422: a 400 never reached validation, so invalid_params is absent. Retrying without changing the request will fail again, except that a request refused for its API-Version goes once the server is updated.

401
No credentials, or credentials that could not be verified — missing bearer token, malformed JWT, expired token, or a signature that failed against the issuer's JWKS.
Refresh the token and retry once. Repeated 401 after a refresh means the device needs to re-enrol.

403
Authenticated, but not permitted. The token is valid and its merchant was resolved, but the caller's role does not allow this operation, or the target belongs to a different merchant.
Cross-tenant access is reported as 403 on a resource the caller may not see, and as 404 where even confirming existence would leak information. Retrying will not help.

410
The request names an API-Version this server no longer serves (docs/decisions/0011). Nothing in it was read. api_version names the version the server speaks: the client is behind, and sends the request again once it is updated.

422
The request parsed but failed validation.
invalid_params lists every failing field with a JSON Pointer, not just the first, so a client can mark up a whole form in one pass rather than making the user fix errors one round trip at a time.
Also returned when an Idempotency-Key is replayed with a different body, and when device-computed order totals disagree with the server's recomputation.

429
Rate limit exceeded. Honour Retry-After rather than applying your own backoff.
A fleet of tills coming back online together after an outage is the realistic cause, which is exactly when uncoordinated client-side retry turns a brief outage into a sustained one. The limit is per process, and per site for what records trade there — a request spends its site's budget, and a till's own smaller one inside it — and per (client, merchant) for everything else; no RateLimit field is sent, so this response and its Retry-After are the whole of the contract.

500
Something failed on our side. trace_id identifies the request in our tracing — quote it in a support ticket.
The body never carries internal detail: no SQL, no stack traces, no upstream error strings. Safe to retry with the same Idempotency-Key.

503
Temporarily unable to serve the request — a dependency is down or the service is shedding load.
Retry with the same Idempotency-Key after Retry-After. This is always safe: a request that did take effect before the failure will be recognised as a replay.
Request
curl -X GET 'https://api.tenvelo.com/v1/exchanges?order_id=…' \ -H "Authorization: Bearer $TOKEN"
Response
{ "has_more": false, "items": [ { "id": "0192f1e4-7c3a-7b2e-9f10-5d6c7e8f9a0b", "created_at": "2026-09-08T09:41:12Z", "original_order_id": "0192f1e4-7c3a-7b2e-9f10-5d6c7e8f9a0b", "refund_id": "0192f1e4-7c3a-7b2e-9f10-5d6c7e8f9a0b", "replacement_order_id": "0192f1e4-7c3a-7b2e-9f10-5d6c7e8f9a0b" } ], "next_cursor": "string" }
POST/v1/exchanges/batch-create

Record exchanges

No. batchCreateExchangesAuth pos:orders:write
Records that a refund and a later sale were one exchange: goods back and goods out. For an exchange recorded after both happened. One recorded with the refund names exchange_replacement_order_id on it instead, and is held to the same rules: the refund is of the original sale, and the replacement is a different, completed sale. Only those who may void a sale may record one.
An exchange is never edited, so this is batch-create. Each item carries its own idempotency_key and stands or falls on its own; the same exchange sent again is unchanged.
Request body application/json · ExchangeBatchCreateRequest

itemsarray of ExchangeBatchCreateItem

Required
≥ 1 items · ≤ 500 items

exchangeExchangeWrite

Required
An exchange to record. Its id is the client's, so a retry names the same record.

idstring · uuid

Required
UUIDv7, minted by the client.

original_order_idstring · uuid

Required
The sale the goods came back from.

refund_idstring · uuid

Required
The refund of the returned goods, a refund of original_order_id.

replacement_order_idstring · uuid

Required
The completed sale of what the guest took instead.

idempotency_keyItemIdempotencyKey

Required
A key for one item in a batch, minted by the client when it queues the item and reused on every attempt to send it. The item, not the request, is the unit of work: a retried batch returns the stored result for every item already applied under its key. A fresh key per attempt defeats the whole mechanism.
Scoped per merchant, so keys need only be unique within a merchant's own traffic.
16–255 chars
Responses

200
The batch was processed. results says what happened to each item.

BatchResponse · application/json

resultsarray of BatchResult

Required

idstring · uuid
The resource the item created or changed. Absent when it failed.

idempotency_keystring

Required
The item's key, echoed so a result can be matched by key as well as position.

problemProblem

Nullable
Why the item failed, as an RFC 9457 problem. A 422 means the item is malformed and will never succeed — drop it and show it to staff rather than retrying for ever. A 409 or a 5xx means try again later.

typestring · uri

Required
A stable URI identifying the problem kind. This is the field to branch on.
default about:blank

api_versionstring
Present on an api-version-retired or api-version-unknown refusal: the API-Version this server speaks (docs/decisions/0011).

detailstring
A human-readable explanation specific to this occurrence. Safe to show to a developer; never contains internal state, SQL, or stack traces.

instancestring · uri-reference
A URI reference identifying the specific occurrence.

invalid_paramsarray of InvalidParam

Present on 422 responses. Lists every field that failed validation, rather than only the first, so a client can highlight an entire form in one pass.

codestring
Stable machine-readable code for this failure, for clients that localise their own messages rather than showing reason.

pointerstring

Required
RFC 6901 JSON Pointer to the offending value within the request body. A pointer rather than a field name so that failures nested inside arrays — the third line item of an order — are addressable at all.

reasonstring

Required
Why this value was rejected, in human-readable form.

refusalsarray of Location refusal

Present on 409 responses to a withdrawal refused by the state it depends on (deleting a location with tills still assigned, open orders, …). Lists every reason at once, each with how much stands in the way, so a client can say what to put right and link to it rather than walking a person through one refusal after another.

kindstring

Required
A stable refusal kind — devices, open_orders, drawer_sessions, bookings or stock — that a client links to the screen that puts it right. Branch on this field, never on the surrounding prose.

countinteger

Required
How many things stand in the way of the withdrawal, so a client can repeat the number rather than re-read prose.
≥ 1

statusinteger

Required
The HTTP status code, repeated here so the body is self-contained.
100–599

titlestring

Required
A short, human-readable summary of the problem kind.

trace_idstring
The OpenTelemetry trace id for this request. Quote it in a support ticket and the whole request can be pulled up.

statusstring · enum

Required
created — the item made a new resource. updated — it changed an existing one.
unchanged — this key was already applied and the original outcome stands. A success, not an error: it is what a client retrying a batch it was unsure landed should expect, and it clears the item from its queue exactly as created does.
failed — the item was refused, and nothing else in the batch was affected. See problem.
createdupdatedunchangedfailed

versioninteger · int64
The resource's version after the item. Absent when it failed.

400
The request could not be parsed. Malformed JSON, a bad query parameter, or a header that failed to decode, among them an API-Version later than the server speaks or not a date (api-version-unknown, with the server's own in api_version).
Distinct from 422: a 400 never reached validation, so invalid_params is absent. Retrying without changing the request will fail again, except that a request refused for its API-Version goes once the server is updated.

401
No credentials, or credentials that could not be verified — missing bearer token, malformed JWT, expired token, or a signature that failed against the issuer's JWKS.
Refresh the token and retry once. Repeated 401 after a refresh means the device needs to re-enrol.

403
Authenticated, but not permitted. The token is valid and its merchant was resolved, but the caller's role does not allow this operation, or the target belongs to a different merchant.
Cross-tenant access is reported as 403 on a resource the caller may not see, and as 404 where even confirming existence would leak information. Retrying will not help.

410
The request names an API-Version this server no longer serves (docs/decisions/0011). Nothing in it was read. api_version names the version the server speaks: the client is behind, and sends the request again once it is updated.

415
The request Content-Type is not supported. This API accepts application/json on all mutations.

422
The request parsed but failed validation.
invalid_params lists every failing field with a JSON Pointer, not just the first, so a client can mark up a whole form in one pass rather than making the user fix errors one round trip at a time.
Also returned when an Idempotency-Key is replayed with a different body, and when device-computed order totals disagree with the server's recomputation.

429
Rate limit exceeded. Honour Retry-After rather than applying your own backoff.
A fleet of tills coming back online together after an outage is the realistic cause, which is exactly when uncoordinated client-side retry turns a brief outage into a sustained one. The limit is per process, and per site for what records trade there — a request spends its site's budget, and a till's own smaller one inside it — and per (client, merchant) for everything else; no RateLimit field is sent, so this response and its Retry-After are the whole of the contract.

500
Something failed on our side. trace_id identifies the request in our tracing — quote it in a support ticket.
The body never carries internal detail: no SQL, no stack traces, no upstream error strings. Safe to retry with the same Idempotency-Key.

503
Temporarily unable to serve the request — a dependency is down or the service is shedding load.
Retry with the same Idempotency-Key after Retry-After. This is always safe: a request that did take effect before the failure will be recognised as a replay.
Request
curl -X POST 'https://api.tenvelo.com/v1/exchanges/batch-create' \ -H "Authorization: Bearer $TOKEN" \ -H 'Content-Type: application/json' \ -d '{ "items": [ { "exchange": { "id": "0192f1e4-7c3a-7b2e-9f10-5d6c7e8f9a0b", "original_order_id": "0192f1e4-7c3a-7b2e-9f10-5d6c7e8f9a0b", "refund_id": "0192f1e4-7c3a-7b2e-9f10-5d6c7e8f9a0b", "replacement_order_id": "0192f1e4-7c3a-7b2e-9f10-5d6c7e8f9a0b" }, "idempotency_key": "01J8ZK3QF7X2N5V9C4B1A6D8E0" } ] }'
Response
{ "results": [ { "id": "0192f1e4-7c3a-7b2e-9f10-5d6c7e8f9a0b", "idempotency_key": "string", "problem": { "type": "https://api.tenvelo.com/problems/version-conflict", "api_version": "2026-10-10", "detail": "The product has been modified since version 7 was read.", "instance": "/v1/products/0195f8c7-4a1e-7c3b-9f22-8d4e6a1b2c3d", "invalid_params": [ { "code": "minimum", "pointer": "/line_items/0/quantity", "reason": "must be greater than or equal to 1" } ], "refusals": [ { "kind": "devices", "count": 3 } ], "status": 412, "title": "Version conflict", "trace_id": "4bf92f3577b34da6a3ce929d0e0e4736" }, "status": "created", "version": 0 } ] }
GET/v1/house-account-charges

List what a venue is still owed

No. listHouseAccountChargesAuth pos:orders:write
Returns the open house account charges, newest first: account tenders on completed sales that nobody has recorded as received (pos/tendering item 14).
A sale settled to a house account counts as paid at the till, but the money is owed until a manager records that it arrived. This is where a merchant sees that debt — an account tender is a valid way to settle a sale, and nowhere else is it said how much is still outstanding, or that anything is.
Parameters

cursorquery · string
Opaque cursor from a previous page's next_cursor. Omit to start from the beginning.
Pass it back exactly as received. It is base64 and its structure is not part of this contract — decoding it, or constructing one by hand, will break without notice.

limitquery · integer · int32
Maximum items to return. The server may return fewer, so always drive the loop from has_more rather than from the size of the page you got back.

location_idquery · string · uuid
Only charges at this site. Omit to see every site the caller may see.
Responses

200
A page of open charges.

HouseAccountChargePage · application/json

has_moreboolean

Required
Whether another page follows.

itemsarray of HouseAccountCharge

Required

amountMoney

Required
A monetary amount in a specific currency: Square's Money, and Stripe's amount beside its currency.
The amount is always an integer count of the currency's minor unit — pence for GBP, cents for USD. Zero-decimal currencies such as JPY have a minor unit equal to their major unit, so {"amount": 500, "currency": "JPY"} is ¥500 while {"amount": 500, "currency": "GBP"} is £5.00.
Floating point is never used for money anywhere in this API. Binary floats cannot represent most decimal fractions exactly, so accumulating them across the line items of an order produces totals that disagree with the printed receipt by a penny. Integer minor units make every arithmetic operation exact.

amountinteger · int64

Required
The amount, as a whole number of the currency's minor unit. May be negative to express a refund, discount or credit.

currencyCurrency

Required
ISO 4217 currency code.
Determines the minor unit that Money.amount is expressed in. Zero-decimal currencies such as JPY have a minor unit equal to the major unit.
One of 182 values; see the schema.

created_atstring · date-time

Required
When the tender was taken.

location_idstring · uuid

Required
The site that is owed the money.

order_idstring · uuid

Required
The sale the charge is from.

payment_idstring · uuid

Required
The sale's account tender, which the settlement is recorded against.

referencestring
The sale's reference, what staff typed or the till printed, so a merchant can find the sale in their own words. Empty when the sale has none.

staff_namestring
Who opened the sale, where a house tab belongs to a person rather than to the till. Empty when the sale has no staff member on it.

next_cursorstring

Nullable
Opaque cursor for the next page, or null on the last page. Pass it back verbatim as the cursor query parameter; its contents are not part of this contract.

400
The request could not be parsed. Malformed JSON, a bad query parameter, or a header that failed to decode, among them an API-Version later than the server speaks or not a date (api-version-unknown, with the server's own in api_version).
Distinct from 422: a 400 never reached validation, so invalid_params is absent. Retrying without changing the request will fail again, except that a request refused for its API-Version goes once the server is updated.

401
No credentials, or credentials that could not be verified — missing bearer token, malformed JWT, expired token, or a signature that failed against the issuer's JWKS.
Refresh the token and retry once. Repeated 401 after a refresh means the device needs to re-enrol.

403
Authenticated, but not permitted. The token is valid and its merchant was resolved, but the caller's role does not allow this operation, or the target belongs to a different merchant.
Cross-tenant access is reported as 403 on a resource the caller may not see, and as 404 where even confirming existence would leak information. Retrying will not help.

410
The request names an API-Version this server no longer serves (docs/decisions/0011). Nothing in it was read. api_version names the version the server speaks: the client is behind, and sends the request again once it is updated.

422
The request parsed but failed validation.
invalid_params lists every failing field with a JSON Pointer, not just the first, so a client can mark up a whole form in one pass rather than making the user fix errors one round trip at a time.
Also returned when an Idempotency-Key is replayed with a different body, and when device-computed order totals disagree with the server's recomputation.

429
Rate limit exceeded. Honour Retry-After rather than applying your own backoff.
A fleet of tills coming back online together after an outage is the realistic cause, which is exactly when uncoordinated client-side retry turns a brief outage into a sustained one. The limit is per process, and per site for what records trade there — a request spends its site's budget, and a till's own smaller one inside it — and per (client, merchant) for everything else; no RateLimit field is sent, so this response and its Retry-After are the whole of the contract.

500
Something failed on our side. trace_id identifies the request in our tracing — quote it in a support ticket.
The body never carries internal detail: no SQL, no stack traces, no upstream error strings. Safe to retry with the same Idempotency-Key.

503
Temporarily unable to serve the request — a dependency is down or the service is shedding load.
Retry with the same Idempotency-Key after Retry-After. This is always safe: a request that did take effect before the failure will be recognised as a replay.
Request
curl -X GET 'https://api.tenvelo.com/v1/house-account-charges' \ -H "Authorization: Bearer $TOKEN"
Response
{ "has_more": false, "items": [ { "amount": { "amount": 1250, "currency": "GBP" }, "created_at": "2026-09-11T09:30:00Z", "location_id": "0192f1e4-7c3a-7b2e-9f10-5d6c7e8f9a0b", "order_id": "0192f1e4-7c3a-7b2e-9f10-5d6c7e8f9a0b", "payment_id": "0192f1e4-7c3a-7b2e-9f10-5d6c7e8f9a0b", "reference": "string", "staff_name": "string" } ], "next_cursor": "string" }
POST/v1/house-account-charges/{payment_id}/settle

Record that what a venue was owed has arrived

No. settleHouseAccountChargeAuth pos:orders:write
Records that the money an open house account charge left owing has been received. The charge then stops being owed. Refused when the charge is not this merchant's, is not an account tender on a completed sale, or has already been settled — a second settlement would record the same money twice.
Parameters

payment_idpath · string · uuid
Required
The account tender of the charge being settled.

Idempotency-Keyheader · string
Required
A client-generated key making this request safe to retry.
Required on every mutation that creates a resource or moves money. A till on bad wifi cannot tell a lost response from a lost request; without a key its only options are to risk a duplicate sale or to drop a real one. With a key it retries freely: the first request to arrive is processed, and every replay returns that same stored response.
Rules:
Mint the key once, when the operation is first queued, and reuse it for every retry. A fresh key per attempt defeats the mechanism entirely.
Keys are scoped per merchant and per operation, and are retained for 30 days — long enough that a till switched off mid-sync can retry with the same key however long it stayed on the shelf.
Replaying a key with a different request body is a client bug and is rejected with 422, rather than silently returning the first result — quietly serving the old response would hide a real inconsistency in the caller.
A UUIDv7 or ULID is a good choice.
Request body application/json

notestring
What the manager wants kept with it, if anything — where the money was paid from, whose tab it was.
≤ 500 chars
Responses

200
The settlement recorded.

object · application/json

amountMoney

Required
A monetary amount in a specific currency: Square's Money, and Stripe's amount beside its currency.
The amount is always an integer count of the currency's minor unit — pence for GBP, cents for USD. Zero-decimal currencies such as JPY have a minor unit equal to their major unit, so {"amount": 500, "currency": "JPY"} is ¥500 while {"amount": 500, "currency": "GBP"} is £5.00.
Floating point is never used for money anywhere in this API. Binary floats cannot represent most decimal fractions exactly, so accumulating them across the line items of an order produces totals that disagree with the printed receipt by a penny. Integer minor units make every arithmetic operation exact.

amountinteger · int64

Required
The amount, as a whole number of the currency's minor unit. May be negative to express a refund, discount or credit.

currencyCurrency

Required
ISO 4217 currency code.
Determines the minor unit that Money.amount is expressed in. Zero-decimal currencies such as JPY have a minor unit equal to the major unit.
One of 182 values; see the schema.

notestring

order_idstring · uuid

payment_idstring · uuid

Required

settled_atstring · date-time

Required

settled_bystring

400
The request could not be parsed. Malformed JSON, a bad query parameter, or a header that failed to decode, among them an API-Version later than the server speaks or not a date (api-version-unknown, with the server's own in api_version).
Distinct from 422: a 400 never reached validation, so invalid_params is absent. Retrying without changing the request will fail again, except that a request refused for its API-Version goes once the server is updated.

401
No credentials, or credentials that could not be verified — missing bearer token, malformed JWT, expired token, or a signature that failed against the issuer's JWKS.
Refresh the token and retry once. Repeated 401 after a refresh means the device needs to re-enrol.

403
Authenticated, but not permitted. The token is valid and its merchant was resolved, but the caller's role does not allow this operation, or the target belongs to a different merchant.
Cross-tenant access is reported as 403 on a resource the caller may not see, and as 404 where even confirming existence would leak information. Retrying will not help.

404
No such resource, or none visible to this caller.
Also returned instead of 403 where acknowledging existence would itself leak information — so a 404 does not prove the id is unused globally, only that it is not yours.

409
The request conflicts with current state — a uniqueness constraint, or an attempt to mutate an order that is already completed or voided.
Unlike 412, re-reading and retrying unchanged will not resolve it; the request itself has to change.

410
The request names an API-Version this server no longer serves (docs/decisions/0011). Nothing in it was read. api_version names the version the server speaks: the client is behind, and sends the request again once it is updated.

422
The request parsed but failed validation.
invalid_params lists every failing field with a JSON Pointer, not just the first, so a client can mark up a whole form in one pass rather than making the user fix errors one round trip at a time.
Also returned when an Idempotency-Key is replayed with a different body, and when device-computed order totals disagree with the server's recomputation.

429
Rate limit exceeded. Honour Retry-After rather than applying your own backoff.
A fleet of tills coming back online together after an outage is the realistic cause, which is exactly when uncoordinated client-side retry turns a brief outage into a sustained one. The limit is per process, and per site for what records trade there — a request spends its site's budget, and a till's own smaller one inside it — and per (client, merchant) for everything else; no RateLimit field is sent, so this response and its Retry-After are the whole of the contract.

500
Something failed on our side. trace_id identifies the request in our tracing — quote it in a support ticket.
The body never carries internal detail: no SQL, no stack traces, no upstream error strings. Safe to retry with the same Idempotency-Key.

503
Temporarily unable to serve the request — a dependency is down or the service is shedding load.
Retry with the same Idempotency-Key after Retry-After. This is always safe: a request that did take effect before the failure will be recognised as a replay.
Request
curl -X POST 'https://api.tenvelo.com/v1/house-account-charges/0192f1e4-7c3a-7b2e-9f10-5d6c7e8f9a0b/settle' \ -H "Authorization: Bearer $TOKEN" \ -H 'Idempotency-Key: 01J8ZK3QF7X2N5V9C4B1A6D8E0' \ -H 'Content-Type: application/json' \ -d '{ "note": "string" }'
Response
{ "amount": { "amount": 1250, "currency": "GBP" }, "note": "string", "order_id": "0192f1e4-7c3a-7b2e-9f10-5d6c7e8f9a0b", "payment_id": "0192f1e4-7c3a-7b2e-9f10-5d6c7e8f9a0b", "settled_at": "2026-09-11T09:30:00Z", "settled_by": "string" }
GET/v1/order-flags

List order flags

No. listOrderFlagsAuth pos:orders:write
Returns the flags nobody has dealt with yet, newest first.
A flag is what the server says instead of refusing. Nothing a device records is turned away — the sale happened, the guest paid and left — so where a write would once have been rejected, the order is recorded and a flag says what is wrong with it. That makes this the only place some of them appear: a tab paid twice looks settled on the order itself, and the money owed back is nowhere else.
Flags also travel on the change feed as order_flag changes, scoped to the location of the order they name, so a device learns about one the same night rather than the next morning. This operation is for a client that has missed them, or is not on the feed at all.
A flag's order_id may name an order that does not exist. That is the most serious kind there is: the server could not turn the facts into an order, so the sale is on the device that recorded it and in no books. Those are returned like any other.
Nothing here clears a flag. What to do about one is a decision with money in it — refund a guest, write off a shortfall, correct a sale — and each of those is its own operation.
Parameters

cursorquery · string
Opaque cursor from a previous page's next_cursor. Omit to start from the beginning.
Pass it back exactly as received. It is base64 and its structure is not part of this contract — decoding it, or constructing one by hand, will break without notice.

limitquery · integer · int32
Maximum items to return. The server may return fewer, so always drive the loop from has_more rather than from the size of the page you got back.

location_idquery · string · uuid
Only flags on orders at this location. A flag whose order the books do not hold has no location and is not returned when this is set.
Responses

200
A page of open flags.

OrderFlagPage · application/json

has_moreboolean

Required
Whether another page follows.

itemsarray of OrderFlag

Required

idstring · uuid

Required
The flag's own id, minted by the server when it was raised.

kindOrderFlagKind

Required
What is wrong with an order, as something a client can switch on. detail is the same thing in the server's own words, for showing to staff.
This list grows, and a client is expected to meet a value it predates, for the same reason ResourceType is extensible: a device is deployed behind the server and cannot be force-upgraded. Show an unknown kind using detail, which is always readable, rather than dropping the flag — a flag nobody sees is money nobody chases.
payment_after_close — money taken against an order already completed or canceled. A guest who paid twice, which is money owed back.
change_after_close — a line or a label changed after the order closed.
void_beyond_line — more was voided than the line held; the line goes to zero.
void_of_unknown_line — a void naming a line nothing had rung up.
never_created — facts arrived for an order that nothing began.
totals_disagree — the device's total and the server's do not match. The server's stands; this says the device would have told the guest something else.
not_applied — the server recorded the order but could not check it. The catch-all, and detail is what it would have said.
stock_not_moved — the sale is in the books and the stock it sold was not taken off the shelf. A count to correct, and the movement is made when what stopped it is fixed.
loyalty_not_moved — the same for what the sale earned or spent: a guest short of points, or holding a reward the sale should have taken.
gift_card_not_moved — the same for the gift cards the sale issued, spent or returned value to: a card's balance short of the sale until what stopped it is fixed.
seal_broken — a fact whose signature is not the device's: altered after the device sealed it, or never sealed by it.
seal_ambiguous — a sealed fact that reads two ways, so its seal cannot say which the device vouched for: a field named twice, or a number too large to seal exactly.
chain_broken — a fact that does not name the device's fact before it: one removed, altered or inserted in between.
clock_disbelieved — a fact whose device's clock the server did not believe, or that came with no time: it is dated when it reached the server, not when the device said.

created_atTimestamp

RequiredRead only
Server-assigned RFC 3339 timestamp, always UTC.
Server-assigned because device clocks drift and cannot be trusted for ordering — a till that has been powered off for a week may come back with a clock hours out. Where the device's own view of time matters it is carried separately in client_created_at.

detailstring

Required
What is wrong, in the server's own words — what the write path would have said had it refused. Meant to be shown to staff as it is; kind is what a client switches on.
≤ 1024 chars

fact_idstring · uuid
The fact that raised it, so a client can say what happened rather than only that something did. Absent when the flag is not about one particular fact.

orderOrderFlagOrder

NullableRead only
Enough of the order to act on, as it stands now. null when the books hold no order by that id, which is the most serious kind of flag.

namestring

Required
The order's name, empty for a walk-in.

location_idstring · uuid

Required

statestring · enum

Required
opencompletedcanceledvoided

totalMoney

Required
A monetary amount in a specific currency: Square's Money, and Stripe's amount beside its currency.
The amount is always an integer count of the currency's minor unit — pence for GBP, cents for USD. Zero-decimal currencies such as JPY have a minor unit equal to their major unit, so {"amount": 500, "currency": "JPY"} is ¥500 while {"amount": 500, "currency": "GBP"} is £5.00.
Floating point is never used for money anywhere in this API. Binary floats cannot represent most decimal fractions exactly, so accumulating them across the line items of an order produces totals that disagree with the printed receipt by a penny. Integer minor units make every arithmetic operation exact.

amountinteger · int64

Required
The amount, as a whole number of the currency's minor unit. May be negative to express a refund, discount or credit.

currencyCurrency

Required
ISO 4217 currency code.
Determines the minor unit that Money.amount is expressed in. Zero-decimal currencies such as JPY have a minor unit equal to the major unit.
One of 182 values; see the schema.

order_idstring · uuid

Required
The order this is about.
The order may not exist. A flag is raised for a fact the server could not turn into an order at all, and that is the most serious kind there is: the sale is on the device that recorded it and in no books. Read this as the order it refers to, not as one you can always fetch.

next_cursorstring

Nullable
Opaque cursor for the next page, or null on the last page. Pass it back verbatim as the cursor query parameter; its contents are not part of this contract.

400
The request could not be parsed. Malformed JSON, a bad query parameter, or a header that failed to decode, among them an API-Version later than the server speaks or not a date (api-version-unknown, with the server's own in api_version).
Distinct from 422: a 400 never reached validation, so invalid_params is absent. Retrying without changing the request will fail again, except that a request refused for its API-Version goes once the server is updated.

401
No credentials, or credentials that could not be verified — missing bearer token, malformed JWT, expired token, or a signature that failed against the issuer's JWKS.
Refresh the token and retry once. Repeated 401 after a refresh means the device needs to re-enrol.

403
Authenticated, but not permitted. The token is valid and its merchant was resolved, but the caller's role does not allow this operation, or the target belongs to a different merchant.
Cross-tenant access is reported as 403 on a resource the caller may not see, and as 404 where even confirming existence would leak information. Retrying will not help.

410
The request names an API-Version this server no longer serves (docs/decisions/0011). Nothing in it was read. api_version names the version the server speaks: the client is behind, and sends the request again once it is updated.

422
The request parsed but failed validation.
invalid_params lists every failing field with a JSON Pointer, not just the first, so a client can mark up a whole form in one pass rather than making the user fix errors one round trip at a time.
Also returned when an Idempotency-Key is replayed with a different body, and when device-computed order totals disagree with the server's recomputation.

429
Rate limit exceeded. Honour Retry-After rather than applying your own backoff.
A fleet of tills coming back online together after an outage is the realistic cause, which is exactly when uncoordinated client-side retry turns a brief outage into a sustained one. The limit is per process, and per site for what records trade there — a request spends its site's budget, and a till's own smaller one inside it — and per (client, merchant) for everything else; no RateLimit field is sent, so this response and its Retry-After are the whole of the contract.

500
Something failed on our side. trace_id identifies the request in our tracing — quote it in a support ticket.
The body never carries internal detail: no SQL, no stack traces, no upstream error strings. Safe to retry with the same Idempotency-Key.

503
Temporarily unable to serve the request — a dependency is down or the service is shedding load.
Retry with the same Idempotency-Key after Retry-After. This is always safe: a request that did take effect before the failure will be recognised as a replay.
Request
curl -X GET 'https://api.tenvelo.com/v1/order-flags' \ -H "Authorization: Bearer $TOKEN"
Response
{ "has_more": false, "items": [ { "id": "0192f1e4-7c3a-7b2e-9f10-5d6c7e8f9a0b", "kind": "string", "created_at": "2026-09-08T09:41:12Z", "detail": "payments do not sum to the order total", "fact_id": "0192f1e4-7c3a-7b2e-9f10-5d6c7e8f9a0b", "order": { "name": "string", "location_id": "0192f1e4-7c3a-7b2e-9f10-5d6c7e8f9a0b", "state": "open", "total": { "amount": 1250, "currency": "GBP" } }, "order_id": "0192f1e4-7c3a-7b2e-9f10-5d6c7e8f9a0b" } ], "next_cursor": "string" }
POST/v1/order-flags/{id}/clear

Record that an order flag was dealt with

No. clearOrderFlagAuth pos:orders:write
Records that a person has dealt with the flag, as a fact on the order's own stream — the clear is as much a fact as the flag was — and applies it at once. The row keeps its (kind, fact_id) key, so the same fact can never raise the flag again. This is the operation the list points at. It is not doing nothing: it is the person saying the sale's money was handled.
Idempotent: the fact's id derives from the flag, so a retry records the same fact once, and a flag already cleared answers as clear. A device token is refused with 403, and so is a caller without the void's authority — a flag is a decision with money in it. A flag whose order the books do not hold is cleared where its facts are: the location comes from the log.
Parameters

idpath · string · uuid
Required
UUIDv7 of the resource.
For resources a device can originate — orders, and their line items — this id is minted by the client before the record is ever synced, which is what makes an offline create idempotent.
Responses

204
The flag is recorded as dealt with.

400
The request could not be parsed. Malformed JSON, a bad query parameter, or a header that failed to decode, among them an API-Version later than the server speaks or not a date (api-version-unknown, with the server's own in api_version).
Distinct from 422: a 400 never reached validation, so invalid_params is absent. Retrying without changing the request will fail again, except that a request refused for its API-Version goes once the server is updated.

401
No credentials, or credentials that could not be verified — missing bearer token, malformed JWT, expired token, or a signature that failed against the issuer's JWKS.
Refresh the token and retry once. Repeated 401 after a refresh means the device needs to re-enrol.

403
Authenticated, but not permitted. The token is valid and its merchant was resolved, but the caller's role does not allow this operation, or the target belongs to a different merchant.
Cross-tenant access is reported as 403 on a resource the caller may not see, and as 404 where even confirming existence would leak information. Retrying will not help.

404
No such resource, or none visible to this caller.
Also returned instead of 403 where acknowledging existence would itself leak information — so a 404 does not prove the id is unused globally, only that it is not yours.

410
The request names an API-Version this server no longer serves (docs/decisions/0011). Nothing in it was read. api_version names the version the server speaks: the client is behind, and sends the request again once it is updated.

429
Rate limit exceeded. Honour Retry-After rather than applying your own backoff.
A fleet of tills coming back online together after an outage is the realistic cause, which is exactly when uncoordinated client-side retry turns a brief outage into a sustained one. The limit is per process, and per site for what records trade there — a request spends its site's budget, and a till's own smaller one inside it — and per (client, merchant) for everything else; no RateLimit field is sent, so this response and its Retry-After are the whole of the contract.

500
Something failed on our side. trace_id identifies the request in our tracing — quote it in a support ticket.
The body never carries internal detail: no SQL, no stack traces, no upstream error strings. Safe to retry with the same Idempotency-Key.
Request
curl -X POST 'https://api.tenvelo.com/v1/order-flags/0192f1e4-7c3a-7b2e-9f10-5d6c7e8f9a0b/clear' \ -H "Authorization: Bearer $TOKEN"
GET/v1/orders

List orders

No. listOrdersAuth pos:orders:write ordering:write
Returns sales, newest first.
Filter by location_id, device_id, state, or a received_at window. The window is on received_at, not client_created_at, because only the former is monotonic and server-assigned — paging over a device-supplied timestamp would skip and duplicate rows as late-syncing tills backfill sales into the middle of the range.
Parameters

cursorquery · string
Opaque cursor from a previous page's next_cursor. Omit to start from the beginning.
Pass it back exactly as received. It is base64 and its structure is not part of this contract — decoding it, or constructing one by hand, will break without notice.

limitquery · integer · int32
Maximum items to return. The server may return fewer, so always drive the loop from has_more rather than from the size of the page you got back.

location_idquery · string · uuid

device_idquery · string · uuid

statequery · string · enum

channelquery · string · enum
Only orders from this channel: online is a location's own ordering page, which is how the venue's online orders screen reads what has been asked of it.

referencequery · string
The human-facing receipt number, which is how staff find a sale by.

qquery · string
The start of a receipt number, or any part of the name an order goes by, or the last four digits of the card that paid it (a payment shows "Visa •• 4242", and this is how staff find the sale it bought).

member_idquery · string · uuid
Only the orders this member rang.

payment_methodquery · string · enum
Only the orders this method paid towards.

total_fromquery · integer · int64
Only orders whose total is at least this, in the order's own minor units. Absent sets no floor.

total_toquery · integer · int64
Only orders whose total is at most this, in the order's own minor units. Absent sets no ceiling.

refundedquery · boolean
Only the orders a refund has given back against.

flaggedquery · boolean
Only the orders with a flag still open.

business_datequery · string · date
Only sales booked to this trading day, in each location's own reckoning.

business_date_fromquery · string · date
Only sales booked to this trading day or later.

business_date_toquery · string · date
Only sales booked to this trading day or earlier.

received_fromquery · string · date-time
Inclusive lower bound on received_at, RFC 3339.

received_toquery · string · date-time
Exclusive upper bound on received_at, RFC 3339.
Responses

200
A page of orders.

OrderPage · application/json

has_moreboolean

Required
Whether another page follows.

itemsarray of Order

Required

idstring · uuid

Required
UUIDv7, minted by the device before the sale is synced. This is what makes an offline order idempotent: replaying it targets the same id, so a retry over flaky wifi cannot create a duplicate sale.

namestring

Nullable
Whose sale it is, while it is open: a customer's name, whatever the shop shouts across the bar. Null is a walk-in being served at a counter right now.
≤ 128 chars

acceptancestring · enum

Read only
Where an asked-for order stands with the venue that must make it, beside its lifecycle: state keeps its four values. A till's own order is accepted as it is created; a channel's — the ordering page, an integration — is pending until a person or a rule takes it on, or it is rejected with a reason. Set by the server, never from the body: acceptance is a fact (engineering, recording what happened, section 12), not a field a client sets.
pendingacceptedrejected

age_confirmedboolean
Whether a sale carrying an age-restricted line recorded that the till confirmed the guest's age before it completed. False both for a sale with no age-restricted line and for one that needed the check and did not record it — the reports compare it with age_minimum to flag the second.
default false

age_minimuminteger · int32
The oldest buyer the sale's age-restricted lines allowed, as the till recorded it: the highest minimum_age among them, 0 when the sale carried none. A completed sale with age_minimum above 0 and age_confirmed false is a counter law miss.
≥ 0 · default 0

business_datestring · date

Read only
The trading day the sale belongs to, in its location's own reckoning: its time zone and the hour its day starts. Set by the server when the sale completes, from when the till says it happened, so a sale rung at 1am on a late night books to the night before. Absent on an order that has not completed.

channelstring · enum

Read only
Where the order came from, set by the server from the caller and never accepted from the body: pos is a till, table a table-side device, online an online storefront, integration a third-party integration. A till cannot attribute a sale to another channel. What the channel is tells an integration whose order arrived from where, which an order_type cannot.
postableonlineintegration

channel_costMoney

What the channel took from the order, at the stated cost in force on the order's business date (online-ordering item 18). Present only for an online order whose channel states a cost, and derived on read from the stated rates and the order's total — never stored, so it can never drift from them.

amountinteger · int64

Required
The amount, as a whole number of the currency's minor unit. May be negative to express a refund, discount or credit.

currencyCurrency

Required
ISO 4217 currency code.
Determines the minor unit that Money.amount is expressed in. Zero-decimal currencies such as JPY have a minor unit equal to the major unit.
One of 182 values; see the schema.

client_created_atstring · date-time

Required
When the device believes the sale happened. Trusted for display — it is what a receipt shows and what staff recognise — but never for ordering or for resolving conflicts, because till clocks drift. Compare with received_at to measure how long a device was offline.

closed_atstring · date-time

Nullable
When the order left open — was completed. A void does not change it; voided_at is when the sale was voided.

coversinteger · int32

RequiredRead only
How many people the party is, as counted at seating on the created fact; zero where nobody counted them. The covers-per-labour-hour and average-spend-per-cover figures are divided by it, so a tab opened without a count adds no covers rather than one.
0–1000 · default 0

created_atTimestamp

RequiredRead only
Server-assigned RFC 3339 timestamp, always UTC.
Server-assigned because device clocks drift and cannot be trusted for ordering — a till that has been powered off for a week may come back with a clock hours out. Where the device's own view of time matters it is carried separately in client_created_at.

currencyCurrency

Required
ISO 4217 currency code.
Determines the minor unit that Money.amount is expressed in. Zero-decimal currencies such as JPY have a minor unit equal to the major unit.
One of 182 values; see the schema.

customerCustomerLoyalty

This order's guest as a till may see them: name, loyalty balance and what it can afford. Carried on the order and its change-feed entry so a till that picks a tab up on another device shows the badge and offers a redemption without a second call. Absent for a walk-in and for a guest since erased or merged; customer_id remains the record. Additive: a client that predates it simply omits it.

idstring · uuid

Required

namestring

Required

loyalty_pointsinteger · int64
The guest's current loyalty balance, earned minus redeemed.

rewardsarray of Reward

The reward catalogue entries this guest can afford, so a till can offer them at redemption. Server-computed from the balance; a guest not enrolled sees none.

idstring · uuid

Required

namestring

Required
What the reward is called to the guest and on the receipt.

cost_pointsinteger · int64

Required
What redeeming it costs, in points.

discount_idstring · uuid

Required
The discount definition the reward is backed by.

tagsstring
The guest's labels, carried so a counter can offer them; still no contact details and no note.

tierLoyaltyTierStatus

A guest's standing in a loyalty programme's ladder at one moment (loyalty item 16): the tier they are on, the next tier above, and how much more they need to reach it.

currentLoyaltyTier

One named level in a loyalty programme's ladder (loyalty item 16). Exactly one of threshold_spend and threshold_visits is set; window_days is the rolling window over which the qualifying spend or visits are counted, and earn_rate_percentage is the multiplier on the programme's base earn rate (10000 is 1x).

idstring · uuid

Required

namestring

Required

earn_rate_percentageRelativePercentage
A percentage that may be negative or above 100, such as a change on a period before or a multiplier, in a decimal string with at most four decimal places: a fall of an eighth is "-12.5", and one and a half times is "150". Read and computed as a Percentage is, in parts per million.
pattern ^-?(0|[1-9][0-9]{0,8})(\.[0-9]{1,4})?$

threshold_spendMoney
A monetary amount in a specific currency: Square's Money, and Stripe's amount beside its currency.
The amount is always an integer count of the currency's minor unit — pence for GBP, cents for USD. Zero-decimal currencies such as JPY have a minor unit equal to their major unit, so {"amount": 500, "currency": "JPY"} is ¥500 while {"amount": 500, "currency": "GBP"} is £5.00.
Floating point is never used for money anywhere in this API. Binary floats cannot represent most decimal fractions exactly, so accumulating them across the line items of an order produces totals that disagree with the printed receipt by a penny. Integer minor units make every arithmetic operation exact.

threshold_visitsinteger · int64
The number of completed linked orders that reaches the tier.

window_daysinteger · int32

nextLoyaltyTier

One named level in a loyalty programme's ladder (loyalty item 16). Exactly one of threshold_spend and threshold_visits is set; window_days is the rolling window over which the qualifying spend or visits are counted, and earn_rate_percentage is the multiplier on the programme's base earn rate (10000 is 1x).

idstring · uuid

Required

namestring

Required

earn_rate_percentageRelativePercentage
A percentage that may be negative or above 100, such as a change on a period before or a multiplier, in a decimal string with at most four decimal places: a fall of an eighth is "-12.5", and one and a half times is "150". Read and computed as a Percentage is, in parts per million.
pattern ^-?(0|[1-9][0-9]{0,8})(\.[0-9]{1,4})?$

threshold_spendMoney
A monetary amount in a specific currency: Square's Money, and Stripe's amount beside its currency.
The amount is always an integer count of the currency's minor unit — pence for GBP, cents for USD. Zero-decimal currencies such as JPY have a minor unit equal to their major unit, so {"amount": 500, "currency": "JPY"} is ¥500 while {"amount": 500, "currency": "GBP"} is £5.00.
Floating point is never used for money anywhere in this API. Binary floats cannot represent most decimal fractions exactly, so accumulating them across the line items of an order produces totals that disagree with the printed receipt by a penny. Integer minor units make every arithmetic operation exact.

threshold_visitsinteger · int64
The number of completed linked orders that reaches the tier.

window_daysinteger · int32

spend_neededMoney

A monetary amount in a specific currency: Square's Money, and Stripe's amount beside its currency.
The amount is always an integer count of the currency's minor unit — pence for GBP, cents for USD. Zero-decimal currencies such as JPY have a minor unit equal to their major unit, so {"amount": 500, "currency": "JPY"} is ¥500 while {"amount": 500, "currency": "GBP"} is £5.00.
Floating point is never used for money anywhere in this API. Binary floats cannot represent most decimal fractions exactly, so accumulating them across the line items of an order produces totals that disagree with the printed receipt by a penny. Integer minor units make every arithmetic operation exact.

amountinteger · int64

Required
The amount, as a whole number of the currency's minor unit. May be negative to express a refund, discount or credit.

currencyCurrency

Required
ISO 4217 currency code.
Determines the minor unit that Money.amount is expressed in. Zero-decimal currencies such as JPY have a minor unit equal to the major unit.
One of 182 values; see the schema.

visits_neededinteger · int64
The visits still needed to reach next, when next is reached by visits.

versioninteger · int64

Required
The guest record's version, for the optimistic write a picker makes; it may be stale by the time the write lands, and the batch then refuses.

customer_idstring · uuid

Nullable
The guest this sale is recorded against, if any. Null for a walk-in.

delivery_addressAddress

Where a delivery order goes, as the writer stated it, when the order's fulfillment is delivery.

address_line_1string

Required
First line of the address — street number, street name, building name.
≤ 255 chars

address_line_2string
Second line of the address, if any.
≤ 255 chars

address_line_3string
Third line of the address, if any.
≤ 255 chars

administrative_district_level_1string
A civil entity within the country. The state in the US; the county in the UK.
≤ 128 chars

administrative_district_level_2string
A civil entity within administrative_district_level_1.
≤ 128 chars

countryCountry

Required
ISO 3166-1 alpha-2 country code.
ZZ is the unknown/unspecified placeholder.
One of 250 values; see the schema.

localitystring
The city or town.
≤ 128 chars

postal_codestring
The postal or ZIP code.
≤ 32 chars

sublocalitystring
A civil region within the locality, if any.
≤ 128 chars

delivery_feeMoney

Nullable
The venue's delivery charge on a delivered order (online-ordering: a shop may charge for delivery), snapshotted from its settings at write, or null when none. Part of the total; never folded into goods or their tax.

amountinteger · int64

Required
The amount, as a whole number of the currency's minor unit. May be negative to express a refund, discount or credit.

currencyCurrency

Required
ISO 4217 currency code.
Determines the minor unit that Money.amount is expressed in. Zero-decimal currencies such as JPY have a minor unit equal to the major unit.
One of 182 values; see the schema.

device_idstring · uuid
The till that last wrote the order. On an open order this is not ownership — any device at the location may pick a tab up, which is the entire point.

device_seqinteger · int64

Nullable
The device's monotonic sequence for this write, if the till recorded one.

documentOrderDocument

The fiscal document a completed order is recorded as, in the per-till series 0016 builds. Every sales document a till issues belongs to a series it was issued at enrolment, and the number is a gap-free counter in that series, incremented in the same transaction that completes the order. Printed on the receipt and sent with the order; the server stores it and refuses a duplicate (series, number).
This is the number a market's fiscal rules are about — the correlative number within a series. It is not the order's reference, which stays the short per-day call number for staff to find a sale.

kindstring · enum

Required
What the document is. invoice is the ordinary receipt — the simplified invoice most markets call a receipt. A full invoice and a rectifying document will be separate kinds, each in its own series.
invoice
default invoice

numberinteger · int64

Required
The gap-free sequence number within the series, starting at 1. Never reused: a void keeps its number, and a correction is a new document in a rectifying series.
≥ 1

seriesstring

Required
The series this document belongs to: a short code issued to one till at enrolment (e.g. B1-T3), one per device and kind of document. The ordinary receipt is in the invoice series.
≤ 32 chars

drawer_session_idstring · uuid

Nullable
The drawer session this sale was rung in, if any. Null otherwise.

email_receiptboolean
Whether the customer on this order asked for its receipt to be emailed. The address is always the customer record's — never typed onto the order, which is a financial record — and only honoured when the guest has consented. Additive, so a till that predates it simply omits it.
default false

external_referencestring

Read only
The writer's own reference for the order, when one was given.
≤ 128 chars

flagsarray of OrderFlagKind

Read only
The kinds of the flags still open on the order, which the books could not settle; absent when none is. Read beside the order as refunded is, and left out of the change feed.

fulfillment_statusstring · enum

Read only
Where an asked-for order has got to, for the guest and the venue: received until the venue takes it on, preparing once accepted, ready once said to be, collected once completed, or rejected or canceled. Derived from acceptance, ready_at and state when the order is read, never stored, so a client shows it rather than working it out again. Toast's fulfillmentStatus. Absent on a till's own sale, which is not asked for.
receivedpreparingreadycollectedrejectedcanceled

fulfillment_typestring · enum

Required
How the sale leaves the building, as the glossary names it and a tax rule is keyed by (docs/decisions/0014): on_premises is what the law calls eat-in, pickup is takeaway and delivery is delivery — Square's fulfillment type, Toast's dining option. A sale that does not say is on premises.
on_premisespickupdelivery

line_itemsarray of OrderLineItem

Required
What was sold. A completed order has at least one line; an open order may be empty for a moment, while the tab it is has just been started.

idstring · uuid

Required
UUIDv7, minted by the device.

namestring

Required
Product name as sold. Snapshot; never re-read from the product.
1–255 chars

approved_by_memberMemberSnapshot

Nullable
The manager or owner who authorised a staff member's discount or comp above the merchant's discount_approval_threshold_minor/discount_approval_threshold_percentage or a comp when comp_requires_manager is set, as they were then; null when no approval was needed.

idstring · uuid

Required
The roster's id, checked against the merchant's memberships.

namestring

Required
What the member was called.
≥ 1 chars

emailstring · email

Required
The member's address.

rolestring · enum

Required
The role the member held.
ownermanagerstaff

category_idstring · uuid

RequiredNullable
The category the product was filed under when the line was rung, for reporting. Snapshot: moving the product to another category later moves no sale. Null on an ad-hoc line or an uncategorised product.

category_namestring

Required
The category's name when the line was rung, so a report of past sales reads as they were filed. Snapshot; empty when category_id is null.
≤ 255 chars

comp_reasonstring
Why this line was given away. Present on a comp — an item given away at no charge — and means something different from a discount, so it is reported separately. Required when the line is a comp.
≤ 512 chars

courseinteger · int32

Nullable
The course this line belongs to, in a full-service kitchen — starters, mains, desserts. Set on the till when ringing to a course, and used to hold or fire a course from the till. Null for a single-course counter sale or a course-less line. Held courses are not sent (sent_at null) until they are fired.
≥ 1

discountMoney

A monetary amount in a specific currency: Square's Money, and Stripe's amount beside its currency.
The amount is always an integer count of the currency's minor unit — pence for GBP, cents for USD. Zero-decimal currencies such as JPY have a minor unit equal to their major unit, so {"amount": 500, "currency": "JPY"} is ¥500 while {"amount": 500, "currency": "GBP"} is £5.00.
Floating point is never used for money anywhere in this API. Binary floats cannot represent most decimal fractions exactly, so accumulating them across the line items of an order produces totals that disagree with the printed receipt by a penny. Integer minor units make every arithmetic operation exact.

amountinteger · int64

Required
The amount, as a whole number of the currency's minor unit. May be negative to express a refund, discount or credit.

currencyCurrency

Required
ISO 4217 currency code.
Determines the minor unit that Money.amount is expressed in. Zero-decimal currencies such as JPY have a minor unit equal to the major unit.
One of 182 values; see the schema.

discount_idstring · uuid

Nullable
The discount definition applied to this line, for reporting. Null for a line with no discount. Snapshot — the discount is recorded so its use can be attributed even if the definition later changes.

discount_namestring
The discount's name at the time the line was priced, snapshotted on the line — the reason a guest can be told, without re-resolving a definition that may have been renamed or deleted. Empty for a line with no discount.
≤ 200 chars

gift_card_codestring

Nullable
The code on the card being sold, when the line's product is a gift_card — typed or scanned at the till. The server issues the card (or refuses a code already live) when the order completes. Null for any other line.
≤ 64 chars

gift_card_token_hashstring

Nullable
The hash of the balance-page token for the card being sold: SHA-256 over the token's text, in base64url without padding. The device mints the token — 32 random bytes, unpadded base64url — and prints it on the receipt's balance link; only its hash leaves the device, so the token is never on the record of the sale, and the server checks a link by hashing the token it carries (W3C, "Good Practices for Capability URLs"). Absent leaves the card with no balance link until one is made (gift-card-balance-links). Null for any other line.
43–43 chars · pattern ^[A-Za-z0-9_-]{43}$

modifiersarray of OrderLineModifier

The options chosen on this line, snapshotted at the moment of sale. The line's unit_price already includes each option's delta.
The server checks only the shape of these — a negative delta is refused, an option chosen twice is refused — and never refuses a sale because the menu has changed since the till synced. A sale that was correct when rung stays correct.

idstring · uuid

Required
The modifier that was chosen. Kept for reporting, never re-resolved.

namestring

Required
Option name as sold. Snapshot.
1–255 chars

price_deltaMoney

Required
A monetary amount in a specific currency: Square's Money, and Stripe's amount beside its currency.
The amount is always an integer count of the currency's minor unit — pence for GBP, cents for USD. Zero-decimal currencies such as JPY have a minor unit equal to their major unit, so {"amount": 500, "currency": "JPY"} is ¥500 while {"amount": 500, "currency": "GBP"} is £5.00.
Floating point is never used for money anywhere in this API. Binary floats cannot represent most decimal fractions exactly, so accumulating them across the line items of an order produces totals that disagree with the printed receipt by a penny. Integer minor units make every arithmetic operation exact.

amountinteger · int64

Required
The amount, as a whole number of the currency's minor unit. May be negative to express a refund, discount or credit.

currencyCurrency

Required
ISO 4217 currency code.
Determines the minor unit that Money.amount is expressed in. Zero-decimal currencies such as JPY have a minor unit equal to the major unit.
One of 182 values; see the schema.

multibuyMultibuyRule

Nullable
The product's multibuy rule as it stood when the line was rung, snapshotted on the line so the server resolves the gross by the same deal the till did — re-pricing a product never rewrites a sale that was correct. Null on a line with no deal. A rule never applies to a weighed line.

everyinteger

Required
How many units make a run; 3 is the ordinary buy-two-get-one.
2–1000

priceMoney

Required
A monetary amount in a specific currency: Square's Money, and Stripe's amount beside its currency.
The amount is always an integer count of the currency's minor unit — pence for GBP, cents for USD. Zero-decimal currencies such as JPY have a minor unit equal to their major unit, so {"amount": 500, "currency": "JPY"} is ¥500 while {"amount": 500, "currency": "GBP"} is £5.00.
Floating point is never used for money anywhere in this API. Binary floats cannot represent most decimal fractions exactly, so accumulating them across the line items of an order produces totals that disagree with the printed receipt by a penny. Integer minor units make every arithmetic operation exact.

amountinteger · int64

Required
The amount, as a whole number of the currency's minor unit. May be negative to express a refund, discount or credit.

currencyCurrency

Required
ISO 4217 currency code.
Determines the minor unit that Money.amount is expressed in. Zero-decimal currencies such as JPY have a minor unit equal to the major unit.
One of 182 values; see the schema.

notestring
Free text from the till — "oat milk", "no sugar".
≤ 512 chars

originstring · enum

Read only
Where this line was rung from, as the server saw the writer: the till at the counter, a guest's phone on a tab, an ordering channel, an integration. It is the server's word and never the writer's, and it is how the share of a table's spend the table rang itself is told. Absent on a line recorded before origins were.
tillcustomeronlineintegration

product_idstring · uuid

Nullable
The catalogue product, for reporting. Null for an ad-hoc line — a miscellaneous item rung up at a custom price, which every real till needs.

product_typestring · enum

Required
What the product was when the line was rung: a gift_card sold is money taken for a promise, not revenue, and a combo is a set. Square's item_type. Snapshot, copied from the product at the moment of sale; standard on an ad-hoc line.
standardgift_cardcombo

quantityQuantity

Required
How much of something, as a decimal string in the unit_of_measure beside it (each where there is none), as Square's quantity is: three croissants are "3", 1.4 kg of beans is "1.4". A string because a JSON number is a binary float to most parsers.
It has at most as many decimal places as its unit's base unit holds — three in each, g and ml, six in kg and l — and a finer one is refused, never rounded. Tenvelo holds every quantity as an integer of that base unit (thousandths of an each, milligrams, microlitres; docs/decisions/0063); a client that computes with one should read the digits the same way, never through a float.
≤ 26 chars · pattern ^-?(0|[1-9][0-9]*)(\.[0-9]{1,6})?$

seatinteger · int32

Nullable
The seat this line is for, when a table's seats are numbered. Set on the till and carried to the kitchen and to split bills. Null for a counter sale or an unnumbered seat.
≥ 1

sent_atstring · date-time

Nullable
When this line was sent to the kitchen — set by the till when a tab is held or a sale completed, and immutable once set. A kitchen knows what to cook from the lines of a ticket, and a new round on a tab is a new set of sent_at values rather than the old lines re-sent. Null on a line the till has not yet held or completed.

serialsarray of string
The serial numbers of the units this line sold (retail item: serial numbers) — one per unit, in the order they were entered, printed on a product whose track_serial is set. Empty on any other line. A snapshot like the name and price: the record of which physical units left the shelf, so a specific unit sold is traceable to its sale.
default []

taxMoney

A monetary amount in a specific currency: Square's Money, and Stripe's amount beside its currency.
The amount is always an integer count of the currency's minor unit — pence for GBP, cents for USD. Zero-decimal currencies such as JPY have a minor unit equal to their major unit, so {"amount": 500, "currency": "JPY"} is ¥500 while {"amount": 500, "currency": "GBP"} is £5.00.
Floating point is never used for money anywhere in this API. Binary floats cannot represent most decimal fractions exactly, so accumulating them across the line items of an order produces totals that disagree with the printed receipt by a penny. Integer minor units make every arithmetic operation exact.

amountinteger · int64

Required
The amount, as a whole number of the currency's minor unit. May be negative to express a refund, discount or credit.

currencyCurrency

Required
ISO 4217 currency code.
Determines the minor unit that Money.amount is expressed in. Zero-decimal currencies such as JPY have a minor unit equal to the major unit.
One of 182 values; see the schema.

tax_breakdownarray of TaxBreakdownItem

Each rate's share of this line's tax, in the order its rule names the rates, when the line is taxed over several rates (each a separate calculation, each rounding with its own mode). Absent — null — on a line taxed at a single rate, where tax_rate_percentage and tax are the whole story.

amountMoney

Required
A monetary amount in a specific currency: Square's Money, and Stripe's amount beside its currency.
The amount is always an integer count of the currency's minor unit — pence for GBP, cents for USD. Zero-decimal currencies such as JPY have a minor unit equal to their major unit, so {"amount": 500, "currency": "JPY"} is ¥500 while {"amount": 500, "currency": "GBP"} is £5.00.
Floating point is never used for money anywhere in this API. Binary floats cannot represent most decimal fractions exactly, so accumulating them across the line items of an order produces totals that disagree with the printed receipt by a penny. Integer minor units make every arithmetic operation exact.

amountinteger · int64

Required
The amount, as a whole number of the currency's minor unit. May be negative to express a refund, discount or credit.

currencyCurrency

Required
ISO 4217 currency code.
Determines the minor unit that Money.amount is expressed in. Zero-decimal currencies such as JPY have a minor unit equal to the major unit.
One of 182 values; see the schema.

inclusiveboolean

Required
Whether this rate is inside the price (true) or added on top (false).

percentagePercentage

Required
A share of a whole, from "0" to "100", as a percentage in a decimal string with at most four decimal places, as Square's percentage and Stripe Tax's percentage_decimal are: UK VAT at 20% is "20", and an 8.875% US sales tax is "8.875".
A string because a JSON number is a binary float to most parsers, and a float cannot hold most decimal fractions exactly (RFC 7493 §2.2). Tenvelo computes with a percentage as an integer in parts per million ("8.875" is 88750), which every four-place percentage is exactly. A client that computes with one should read the digits the same way, never through a float.
pattern ^(100(\.0{1,4})?|(0|[1-9][0-9]?)(\.[0-9]{1,4})?)$

rate_idstring · uuid

Required
The rate this share belongs to.

tax_inclusiveboolean
Whether unit_price already contains the tax. Snapshot.

tax_rate_percentagePercentage
A share of a whole, from "0" to "100", as a percentage in a decimal string with at most four decimal places, as Square's percentage and Stripe Tax's percentage_decimal are: UK VAT at 20% is "20", and an 8.875% US sales tax is "8.875".
A string because a JSON number is a binary float to most parsers, and a float cannot hold most decimal fractions exactly (RFC 7493 §2.2). Tenvelo computes with a percentage as an integer in parts per million ("8.875" is 88750), which every four-place percentage is exactly. A client that computes with one should read the digits the same way, never through a float.
pattern ^(100(\.0{1,4})?|(0|[1-9][0-9]?)(\.[0-9]{1,4})?)$

totalMoney

Required
A monetary amount in a specific currency: Square's Money, and Stripe's amount beside its currency.
The amount is always an integer count of the currency's minor unit — pence for GBP, cents for USD. Zero-decimal currencies such as JPY have a minor unit equal to their major unit, so {"amount": 500, "currency": "JPY"} is ¥500 while {"amount": 500, "currency": "GBP"} is £5.00.
Floating point is never used for money anywhere in this API. Binary floats cannot represent most decimal fractions exactly, so accumulating them across the line items of an order produces totals that disagree with the printed receipt by a penny. Integer minor units make every arithmetic operation exact.

amountinteger · int64

Required
The amount, as a whole number of the currency's minor unit. May be negative to express a refund, discount or credit.

currencyCurrency

Required
ISO 4217 currency code.
Determines the minor unit that Money.amount is expressed in. Zero-decimal currencies such as JPY have a minor unit equal to the major unit.
One of 182 values; see the schema.

unit_of_measurestring · enum

Nullable
The unit this line was sold in, snapshotted from the product at the moment of sale (the product's own unit on a product line; any unit on an ad-hoc line). Absent means each.
eachkgglml

unit_priceMoney

Required
A monetary amount in a specific currency: Square's Money, and Stripe's amount beside its currency.
The amount is always an integer count of the currency's minor unit — pence for GBP, cents for USD. Zero-decimal currencies such as JPY have a minor unit equal to their major unit, so {"amount": 500, "currency": "JPY"} is ¥500 while {"amount": 500, "currency": "GBP"} is £5.00.
Floating point is never used for money anywhere in this API. Binary floats cannot represent most decimal fractions exactly, so accumulating them across the line items of an order produces totals that disagree with the printed receipt by a penny. Integer minor units make every arithmetic operation exact.

amountinteger · int64

Required
The amount, as a whole number of the currency's minor unit. May be negative to express a refund, discount or credit.

currencyCurrency

Required
ISO 4217 currency code.
Determines the minor unit that Money.amount is expressed in. Zero-decimal currencies such as JPY have a minor unit equal to the major unit.
One of 182 values; see the schema.

variant_idstring · uuid

Nullable
The variant that was sold, for reporting and stock. Null when the product itself is the sellable unit — a product with no variants, or with none picked. Like product_id, it is retained for reporting and never re-resolved: the descriptive and monetary fields on this line are the snapshot that is replayed, so a sale that was correct when rung stays correct even if the catalogue has changed since.

location_idstring · uuid

Required

loyalty_earnedinteger · int64

Read only
The points this sale earned its customer, recorded on the order.

loyalty_spentinteger · int64

Read only
The points this sale redeemed from its customer, recorded on the order.

memberMemberSnapshot

Nullable
The staff member who recorded this order — the person who rang it up — as they were then; nil when no person was attributed.

idstring · uuid

Required
The roster's id, checked against the merchant's memberships.

namestring

Required
What the member was called.
≥ 1 chars

emailstring · email

Required
The member's address.

rolestring · enum

Required
The role the member held.
ownermanagerstaff

merchant_idstring · uuid

RequiredRead only

owner_memberMemberSnapshot

Nullable
The staff member a tab belongs to — who opened it, and whom to ask when nobody has touched it. Checked against the merchant's memberships; nil for an order that was never a tab. Set once at open and only changed through a till's explicit transfer.

idstring · uuid

Required
The roster's id, checked against the merchant's memberships.

namestring

Required
What the member was called.
≥ 1 chars

emailstring · email

Required
The member's address.

rolestring · enum

Required
The role the member held.
ownermanagerstaff

paidMoney

A monetary amount in a specific currency: Square's Money, and Stripe's amount beside its currency.
The amount is always an integer count of the currency's minor unit — pence for GBP, cents for USD. Zero-decimal currencies such as JPY have a minor unit equal to their major unit, so {"amount": 500, "currency": "JPY"} is ¥500 while {"amount": 500, "currency": "GBP"} is £5.00.
Floating point is never used for money anywhere in this API. Binary floats cannot represent most decimal fractions exactly, so accumulating them across the line items of an order produces totals that disagree with the printed receipt by a penny. Integer minor units make every arithmetic operation exact.

amountinteger · int64

Required
The amount, as a whole number of the currency's minor unit. May be negative to express a refund, discount or credit.

currencyCurrency

Required
ISO 4217 currency code.
Determines the minor unit that Money.amount is expressed in. Zero-decimal currencies such as JPY have a minor unit equal to the major unit.
One of 182 values; see the schema.

paymentsarray of Payment

How the sale was paid for. Present on a completed order, and the thing that makes a day's takings reconcilable: an order that says completed without saying how it was paid records that something was sold and nothing about whether any money arrived.
An open order — a tab being split or part-paid — may also carry payments: a partial payment is appended while the tab stays open, and what remains is derived from the lines minus these payments and never stored. The server refuses a payment larger than what remains, and completes the order in the write whose payments cover the sale.

idstring · uuid
The payment's id. Minted by the device, so a retry of the same tender converges on the same row instead of recording the money twice; the server mints one when a writer does not supply it. A refund names it as payment_id, and a card refund is reversed against it, so it is returned with every read of the order and never renumbered.

amountMoney

Required
The total taken by this payment, including any tip.
Following Square: the tender's amount is what the customer parted with, and tip is the portion of it that is not for goods. Modelling it the other way — an amount that excludes the tip — means every reconciliation has to remember to add the two back together, and one place that forgets is a day's takings that do not balance.

amountinteger · int64

Required
The amount, as a whole number of the currency's minor unit. May be negative to express a refund, discount or credit.

currencyCurrency

Required
ISO 4217 currency code.
Determines the minor unit that Money.amount is expressed in. Zero-decimal currencies such as JPY have a minor unit equal to the major unit.
One of 182 values; see the schema.

buyer_suppliedMoney

Nullable
What the customer physically handed over. Cash only.
Recorded rather than assumed so that change is derived from it: a note tendered for a smaller sale is the ordinary case, and the drawer at close must agree with the sum of what went in.

amountinteger · int64

Required
The amount, as a whole number of the currency's minor unit. May be negative to express a refund, discount or credit.

currencyCurrency

Required
ISO 4217 currency code.
Determines the minor unit that Money.amount is expressed in. Zero-decimal currencies such as JPY have a minor unit equal to the major unit.
One of 182 values; see the schema.

card_brandstring

Read only
The scheme the processor read off the card, in its own words ("visa", "mastercard", "amex"). Card payments only; absent where the processor reports none.

card_confirmationstring · enum

Read only
How the card payment was confirmed against the checkout the processor says took it: confirmed when the approved checkout's amount matched and it belongs to this sale, unconfirmed when it is not approved, belongs to another sale, or took a different amount. An unconfirmed sale is still recorded — the money may already have moved — but the payment is flagged for a person to reconcile. The server's word, never the till's. Absent for a payment that is not a card, and for a card the till recorded by reference on a third-party terminal, which has no checkout to confirm against.
confirmedunconfirmed

card_last4string

Read only
The last four digits of the card that paid, as the processor masked them — what a payment shows as "Visa •• 4242", and what a person types into the order list's search to find the sale. Card payments only; absent where the processor reports none. Never the PAN.
≤ 4 chars

change_backMoney

NullableRead only
Change handed back, calculated by the server as buyer_supplied - amount and never accepted from a client.
Derived rather than submitted because it is the one figure a till could get wrong in a way that balances on screen and not in the drawer.

amountinteger · int64

Required
The amount, as a whole number of the currency's minor unit. May be negative to express a refund, discount or credit.

currencyCurrency

Required
ISO 4217 currency code.
Determines the minor unit that Money.amount is expressed in. Zero-decimal currencies such as JPY have a minor unit equal to the major unit.
One of 182 values; see the schema.

fingerprintstring

Read only
The processor's card-alias token, never the PAN, for a card payment it could identify. It is what lets a returning card be recognised without the card number. Card payments only; absent for cash and vouchers, and for a card payment the processor did not identify.
≤ 256 chars

gift_card_hold_idstring · uuid
The hold a till took on the voucher's card before tendering it (batchCreateGiftCardHolds), which this payment settles. Absent for a voucher tendered offline, which is spent against what the till last knew of the card.

line_idsarray of string · uuid
The lines this payment settled, when the till knows the split: a share pays whole lines, so a reopened tab shows the unpaid lines rather than a number, and a mistake cannot charge somebody twice (tabs item 13).
Empty when the payment named no lines — a whole-sale tender, an even split, a card share settling what is left, and every payment recorded before this existed. Empty and absent mean the same thing and are accepted alike, and a till sends the empty array.

memberMemberSnapshot

Nullable
The member who took this tender — the terminal operator who took the tip, not whoever rang the sale. The kept tip rule follows it. Absent for a payment recorded by something that is not a person.

idstring · uuid

Required
The roster's id, checked against the merchant's memberships.

namestring

Required
What the member was called.
≥ 1 chars

emailstring · email

Required
The member's address.

rolestring · enum

Required
The role the member held.
ownermanagerstaff

methodstring · enum

Required
cash — taken into the drawer. Settled by definition: nothing to capture, nothing that can later fail.
card — captured through the PSP. Recorded here as what the terminal reported, not as proof of settlement.
voucher — a gift card or credit note redeemed against the sale.
account — put on a customer's account to settle later. Requires the sale to name the customer (customer_id) and the merchant to have an open customer account for them; the till chooses the account at the tender and links the sale to its customer (retail: customer accounts).
A loyalty redemption is not a payment method any more: a reward redeems against its discount definition, the order line carries the discount, and the server spends the guest's points when the order is written. The points method was retired.
external — money a channel took before the order reached the venue: an online storefront, a delivery platform. The merchant settles with that channel, so the tender records the platform's reference rather than a card payment this merchant never captured. Only valid on an order a channel wrote, and the reference is required.
cashcardvoucheraccountexternal

pinstring
A voucher's PIN — the scratch-off second factor that proves possession of the card whose code is in reference (gift cards item 20). Required only when the card carries a PIN (a pre-printed or merchant-supplied code); a card with a generated code needs none, and the server refuses a sale whose voucher cannot prove the PIN. Only the hash is stored and compared; the plaintext never comes back.
≤ 12 chars

referencestring
The PSP's identifier for a card payment, or a voucher's code. Cash has neither and needs neither. Required for an external tender: it is the platform's own transaction or order reference, which is what reconciliation against that channel relies on.
≤ 128 chars

tipMoney

Nullable
The part of amount that is a gratuity rather than payment for goods.
Present because hospitality is not an edge case here: a bar or restaurant tab is the core flow, and a till that cannot record a tip cannot be used in one.

amountinteger · int64

Required
The amount, as a whole number of the currency's minor unit. May be negative to express a refund, discount or credit.

currencyCurrency

Required
ISO 4217 currency code.
Determines the minor unit that Money.amount is expressed in. Zero-decimal currencies such as JPY have a minor unit equal to the major unit.
One of 182 values; see the schema.

pickup_atstring · date-time

Read only
When the guest was told they could collect. Set by whoever took the order — the ordering page, or a till ringing a takeaway for collection at a time — and kept however the order is written afterwards: a later write that omits it leaves the promised time alone. Absent on an order nobody promised a time for.

ready_atstring · date-time

Read only
When the venue said an asked-for order was ready for the guest, recorded as a ready fact — the Ready button, the kitchen bumping the order's last ticket, or an integration. Absent until then, and again after a ready_undone takes it back. Read from the facts, never from whether the kitchen has any tickets for the order.

ready_to_pay_atstring · date-time

Read only
When a guest at the table said they were ready to pay (order-and-pay), on an open order. Absent until they tap; carried on the change feed as an order update, which is how the till shows the call.

received_atTimestamp

RequiredRead only
Server-assigned RFC 3339 timestamp, always UTC.
Server-assigned because device clocks drift and cannot be trusted for ordering — a till that has been powered off for a week may come back with a clock hours out. Where the device's own view of time matters it is carried separately in client_created_at.

referencestring
Short human-readable reference shown on the receipt and used by staff to find the order. Unique per location per business day.
≤ 64 chars

refundedMoney

A monetary amount in a specific currency: Square's Money, and Stripe's amount beside its currency.
The amount is always an integer count of the currency's minor unit — pence for GBP, cents for USD. Zero-decimal currencies such as JPY have a minor unit equal to their major unit, so {"amount": 500, "currency": "JPY"} is ¥500 while {"amount": 500, "currency": "GBP"} is £5.00.
Floating point is never used for money anywhere in this API. Binary floats cannot represent most decimal fractions exactly, so accumulating them across the line items of an order produces totals that disagree with the printed receipt by a penny. Integer minor units make every arithmetic operation exact.

amountinteger · int64

Required
The amount, as a whole number of the currency's minor unit. May be negative to express a refund, discount or credit.

currencyCurrency

Required
ISO 4217 currency code.
Determines the minor unit that Money.amount is expressed in. Zero-decimal currencies such as JPY have a minor unit equal to the major unit.
One of 182 values; see the schema.

rejection_notestring

Read only
The staff member's words, in their own voice, required when the reason is other.
≤ 512 chars

rejection_reasonstring · enum

Read only
Why an asked-for order was turned down, when it was. timed_out is the sweep that rejects an unanswered order past its location's deadline.
sold_outclosedtoo_busyothertimed_out

service_chargeMoney

Nullable
The discretionary service charge added to this bill (order-ledger item 9), in the order's currency, or null when none. Never folded into goods; part of the total payments must sum to.

amountinteger · int64

Required
The amount, as a whole number of the currency's minor unit. May be negative to express a refund, discount or credit.

currencyCurrency

Required
ISO 4217 currency code.
Determines the minor unit that Money.amount is expressed in. Zero-decimal currencies such as JPY have a minor unit equal to the major unit.
One of 182 values; see the schema.

service_charge_taxMoney

Nullable
The tax on the service charge, its own line and never folded into goods tax_total, or null when the charge is not taxed.

amountinteger · int64

Required
The amount, as a whole number of the currency's minor unit. May be negative to express a refund, discount or credit.

currencyCurrency

Required
ISO 4217 currency code.
Determines the minor unit that Money.amount is expressed in. Zero-decimal currencies such as JPY have a minor unit equal to the major unit.
One of 182 values; see the schema.

service_charge_tax_class_idstring · uuid

Nullable
The tax class the service charge was taxed under (decision record 0054), snapshotted from the location's config at write, or null when the charge is not taxed.

service_charge_tax_rate_percentagePercentage

Nullable
The combined tax rate that applied to the service charge, or null when not taxed.
pattern ^(100(\.0{1,4})?|(0|[1-9][0-9]?)(\.[0-9]{1,4})?)$

sourcestring

Read only
Which caller wrote the order — the device id for a pos or table order, storefront for one placed on a venue's ordering page, and the integration client id for an integration one. Set server-side from the caller, and an identifier's provenance, not a name.

source_namestring

Read only
The name the merchant gave the integration that wrote an integration order, as it was when the order was recorded; empty for any other channel.

statestring · enum

Required
open is a sale in progress, shared with the devices at its location. completed is finalised and immutable. canceled is an open order that ended without being paid. voided is a completed order reversed. Neither of the last two is deleted, so the audit trail survives.
opencompletedcanceledvoided

table_idstring · uuid

Nullable
The table an open order is parked on, if any. Occupancy is derived from this.

tipsMoney

A monetary amount in a specific currency: Square's Money, and Stripe's amount beside its currency.
The amount is always an integer count of the currency's minor unit — pence for GBP, cents for USD. Zero-decimal currencies such as JPY have a minor unit equal to their major unit, so {"amount": 500, "currency": "JPY"} is ¥500 while {"amount": 500, "currency": "GBP"} is £5.00.
Floating point is never used for money anywhere in this API. Binary floats cannot represent most decimal fractions exactly, so accumulating them across the line items of an order produces totals that disagree with the printed receipt by a penny. Integer minor units make every arithmetic operation exact.

amountinteger · int64

Required
The amount, as a whole number of the currency's minor unit. May be negative to express a refund, discount or credit.

currencyCurrency

Required
ISO 4217 currency code.
Determines the minor unit that Money.amount is expressed in. Zero-decimal currencies such as JPY have a minor unit equal to the major unit.
One of 182 values; see the schema.

totalsOrderTotals

Required
The money on an order, broken out.
These are computed and sent by the device, then independently recomputed by the server on receipt. A mismatch is rejected with 422 rather than quietly corrected: if the till printed a receipt showing one total and the server stored another, the merchant has an unreconcilable discrepancy and no way to know which is right. Failing loudly surfaces a till running stale tax configuration while it is still one order, not a month's worth.

cash_roundingMoney

Nullable
How much a cash settlement rounded the price, signed (docs/decisions/0015): a €10.02 bill rounded up to €10.05 has cash_rounding 3, and the cash payment's goods portion is the total plus this. The till computes it from the location's cash step; the server recomputes and rejects a mismatch. Zero on a sale no cash settles, and cards are never rounded.

amountinteger · int64

Required
The amount, as a whole number of the currency's minor unit. May be negative to express a refund, discount or credit.

currencyCurrency

Required
ISO 4217 currency code.
Determines the minor unit that Money.amount is expressed in. Zero-decimal currencies such as JPY have a minor unit equal to the major unit.
One of 182 values; see the schema.

discount_totalMoney

Required
A monetary amount in a specific currency: Square's Money, and Stripe's amount beside its currency.
The amount is always an integer count of the currency's minor unit — pence for GBP, cents for USD. Zero-decimal currencies such as JPY have a minor unit equal to their major unit, so {"amount": 500, "currency": "JPY"} is ¥500 while {"amount": 500, "currency": "GBP"} is £5.00.
Floating point is never used for money anywhere in this API. Binary floats cannot represent most decimal fractions exactly, so accumulating them across the line items of an order produces totals that disagree with the printed receipt by a penny. Integer minor units make every arithmetic operation exact.

amountinteger · int64

Required
The amount, as a whole number of the currency's minor unit. May be negative to express a refund, discount or credit.

currencyCurrency

Required
ISO 4217 currency code.
Determines the minor unit that Money.amount is expressed in. Zero-decimal currencies such as JPY have a minor unit equal to the major unit.
One of 182 values; see the schema.

service_chargeMoney

A monetary amount in a specific currency: Square's Money, and Stripe's amount beside its currency.
The amount is always an integer count of the currency's minor unit — pence for GBP, cents for USD. Zero-decimal currencies such as JPY have a minor unit equal to their major unit, so {"amount": 500, "currency": "JPY"} is ¥500 while {"amount": 500, "currency": "GBP"} is £5.00.
Floating point is never used for money anywhere in this API. Binary floats cannot represent most decimal fractions exactly, so accumulating them across the line items of an order produces totals that disagree with the printed receipt by a penny. Integer minor units make every arithmetic operation exact.

amountinteger · int64

Required
The amount, as a whole number of the currency's minor unit. May be negative to express a refund, discount or credit.

currencyCurrency

Required
ISO 4217 currency code.
Determines the minor unit that Money.amount is expressed in. Zero-decimal currencies such as JPY have a minor unit equal to the major unit.
One of 182 values; see the schema.

service_charge_taxMoney

Nullable
The tax on the service charge (decision record 0054), its own line and never folded into goods tax_total. Computed server-side from the location's service-charge tax class and the sale's fulfilment and business date. Null when the charge is not taxed.

amountinteger · int64

Required
The amount, as a whole number of the currency's minor unit. May be negative to express a refund, discount or credit.

currencyCurrency

Required
ISO 4217 currency code.
Determines the minor unit that Money.amount is expressed in. Zero-decimal currencies such as JPY have a minor unit equal to the major unit.
One of 182 values; see the schema.

subtotalMoney

Required
A monetary amount in a specific currency: Square's Money, and Stripe's amount beside its currency.
The amount is always an integer count of the currency's minor unit — pence for GBP, cents for USD. Zero-decimal currencies such as JPY have a minor unit equal to their major unit, so {"amount": 500, "currency": "JPY"} is ¥500 while {"amount": 500, "currency": "GBP"} is £5.00.
Floating point is never used for money anywhere in this API. Binary floats cannot represent most decimal fractions exactly, so accumulating them across the line items of an order produces totals that disagree with the printed receipt by a penny. Integer minor units make every arithmetic operation exact.

amountinteger · int64

Required
The amount, as a whole number of the currency's minor unit. May be negative to express a refund, discount or credit.

currencyCurrency

Required
ISO 4217 currency code.
Determines the minor unit that Money.amount is expressed in. Zero-decimal currencies such as JPY have a minor unit equal to the major unit.
One of 182 values; see the schema.

tax_totalMoney

Required
A monetary amount in a specific currency: Square's Money, and Stripe's amount beside its currency.
The amount is always an integer count of the currency's minor unit — pence for GBP, cents for USD. Zero-decimal currencies such as JPY have a minor unit equal to their major unit, so {"amount": 500, "currency": "JPY"} is ¥500 while {"amount": 500, "currency": "GBP"} is £5.00.
Floating point is never used for money anywhere in this API. Binary floats cannot represent most decimal fractions exactly, so accumulating them across the line items of an order produces totals that disagree with the printed receipt by a penny. Integer minor units make every arithmetic operation exact.

amountinteger · int64

Required
The amount, as a whole number of the currency's minor unit. May be negative to express a refund, discount or credit.

currencyCurrency

Required
ISO 4217 currency code.
Determines the minor unit that Money.amount is expressed in. Zero-decimal currencies such as JPY have a minor unit equal to the major unit.
One of 182 values; see the schema.

totalMoney

Required
A monetary amount in a specific currency: Square's Money, and Stripe's amount beside its currency.
The amount is always an integer count of the currency's minor unit — pence for GBP, cents for USD. Zero-decimal currencies such as JPY have a minor unit equal to their major unit, so {"amount": 500, "currency": "JPY"} is ¥500 while {"amount": 500, "currency": "GBP"} is £5.00.
Floating point is never used for money anywhere in this API. Binary floats cannot represent most decimal fractions exactly, so accumulating them across the line items of an order produces totals that disagree with the printed receipt by a penny. Integer minor units make every arithmetic operation exact.

amountinteger · int64

Required
The amount, as a whole number of the currency's minor unit. May be negative to express a refund, discount or credit.

currencyCurrency

Required
ISO 4217 currency code.
Determines the minor unit that Money.amount is expressed in. Zero-decimal currencies such as JPY have a minor unit equal to the major unit.
One of 182 values; see the schema.

updated_atTimestamp

RequiredRead only
Server-assigned RFC 3339 timestamp, always UTC.
Server-assigned because device clocks drift and cannot be trusted for ordering — a till that has been powered off for a week may come back with a clock hours out. Where the device's own view of time matters it is carried separately in client_created_at.

versionVersion

RequiredRead only
Optimistic concurrency version, raised by the server on every write. A version is never lower than one already returned for the resource, though it may rise by more than one.
Returned in the ETag response header as well as in the body. Send it back in If-Match on an update and the write is rejected with 412 if anyone else has written since — which is what stops two tills silently overwriting each other's edit to the same product when both come back online at once.
≥ 1

void_memberMemberSnapshot

Nullable
The staff member who voided this order, when it has been voided and the void was made by a person. Nil for a sale that was never voided, or one voided by something that is not a person.

idstring · uuid

Required
The roster's id, checked against the merchant's memberships.

namestring

Required
What the member was called.
≥ 1 chars

emailstring · email

Required
The member's address.

rolestring · enum

Required
The role the member held.
ownermanagerstaff

void_notestring
The staff member's note on the void, required when the reason is other.

void_reasonstring · enum
Why this sale was voided. Set on a voided order.
customer_canceledstaff_errorrefundother

voided_atstring · date-time

Nullable
When the sale was voided.

next_cursorstring

Nullable
Opaque cursor for the next page, or null on the last page. Pass it back verbatim as the cursor query parameter; its contents are not part of this contract.

400
The request could not be parsed. Malformed JSON, a bad query parameter, or a header that failed to decode, among them an API-Version later than the server speaks or not a date (api-version-unknown, with the server's own in api_version).
Distinct from 422: a 400 never reached validation, so invalid_params is absent. Retrying without changing the request will fail again, except that a request refused for its API-Version goes once the server is updated.

401
No credentials, or credentials that could not be verified — missing bearer token, malformed JWT, expired token, or a signature that failed against the issuer's JWKS.
Refresh the token and retry once. Repeated 401 after a refresh means the device needs to re-enrol.

403
Authenticated, but not permitted. The token is valid and its merchant was resolved, but the caller's role does not allow this operation, or the target belongs to a different merchant.
Cross-tenant access is reported as 403 on a resource the caller may not see, and as 404 where even confirming existence would leak information. Retrying will not help.

410
The request names an API-Version this server no longer serves (docs/decisions/0011). Nothing in it was read. api_version names the version the server speaks: the client is behind, and sends the request again once it is updated.

422
The request parsed but failed validation.
invalid_params lists every failing field with a JSON Pointer, not just the first, so a client can mark up a whole form in one pass rather than making the user fix errors one round trip at a time.
Also returned when an Idempotency-Key is replayed with a different body, and when device-computed order totals disagree with the server's recomputation.

429
Rate limit exceeded. Honour Retry-After rather than applying your own backoff.
A fleet of tills coming back online together after an outage is the realistic cause, which is exactly when uncoordinated client-side retry turns a brief outage into a sustained one. The limit is per process, and per site for what records trade there — a request spends its site's budget, and a till's own smaller one inside it — and per (client, merchant) for everything else; no RateLimit field is sent, so this response and its Retry-After are the whole of the contract.

500
Something failed on our side. trace_id identifies the request in our tracing — quote it in a support ticket.
The body never carries internal detail: no SQL, no stack traces, no upstream error strings. Safe to retry with the same Idempotency-Key.

503
Temporarily unable to serve the request — a dependency is down or the service is shedding load.
Retry with the same Idempotency-Key after Retry-After. This is always safe: a request that did take effect before the failure will be recognised as a replay.
Request
curl -X GET 'https://api.tenvelo.com/v1/orders' \ -H "Authorization: Bearer $TOKEN"
Response
{ "has_more": false, "items": [ { "id": "0192f1e4-7c3a-7b2e-9f10-5d6c7e8f9a0b", "name": "Sam", "acceptance": "pending", "age_confirmed": false, "age_minimum": 0, "business_date": "2026-09-11", "channel": "pos", "channel_cost": { "amount": 1250, "currency": "GBP" }, "client_created_at": "2026-09-11T09:30:00Z", "closed_at": "2026-09-11T09:30:00Z", "covers": 0, "created_at": "2026-09-08T09:41:12Z", "currency": "AED", "customer": { "id": "0192f1e4-7c3a-7b2e-9f10-5d6c7e8f9a0b", "name": "string", "loyalty_points": 0, "rewards": [ { "id": "0192f1e4-7c3a-7b2e-9f10-5d6c7e8f9a0b", "name": "string", "cost_points": 0, "discount_id": "0192f1e4-7c3a-7b2e-9f10-5d6c7e8f9a0b" } ], "tags": "string", "tier": { "current": { "id": "0192f1e4-7c3a-7b2e-9f10-5d6c7e8f9a0b", "name": "string", "earn_rate_percentage": "-12.5", "threshold_spend": { "amount": 1250, "currency": "GBP" }, "threshold_visits": 0, "window_days": 0 }, "next": { "id": "0192f1e4-7c3a-7b2e-9f10-5d6c7e8f9a0b", "name": "string", "earn_rate_percentage": "-12.5", "threshold_spend": { "amount": 1250, "currency": "GBP" }, "threshold_visits": 0, "window_days": 0 }, "spend_needed": { "amount": 1250, "currency": "GBP" }, "visits_needed": 0 }, "version": 0 }, "customer_id": "0192f1e4-7c3a-7b2e-9f10-5d6c7e8f9a0b", "delivery_address": { "address_line_1": "12 Bridge Street", "address_line_2": "string", "address_line_3": "string", "administrative_district_level_1": "Somerset", "administrative_district_level_2": "string", "country": "ZZ", "locality": "Bristol", "postal_code": "BS1 4ST", "sublocality": "string" }, "delivery_fee": { "amount": 1250, "currency": "GBP" }, "device_id": "0192f1e4-7c3a-7b2e-9f10-5d6c7e8f9a0b", "device_seq": 0, "document": { "kind": "invoice", "number": 148, "series": "B1-T3" }, "drawer_session_id": "0192f1e4-7c3a-7b2e-9f10-5d6c7e8f9a0b", "email_receipt": false, "external_reference": "string", "flags": [ "string" ], "fulfillment_status": "received", "fulfillment_type": "on_premises", "line_items": [ { "id": "0192f1e4-7c3a-7b2e-9f10-5d6c7e8f9a0b", "name": "Flat white", "approved_by_member": { "id": "0192f1e4-7c3a-7b2e-9f10-5d6c7e8f9a0b", "name": "string", "email": "ada@example.com", "role": "owner" }, "category_id": "0192f1e4-7c3a-7b2e-9f10-5d6c7e8f9a0b", "category_name": "string", "comp_reason": "string", "course": 1, "discount": { "amount": 1250, "currency": "GBP" }, "discount_id": "0192f1e4-7c3a-7b2e-9f10-5d6c7e8f9a0b", "discount_name": "string", "gift_card_code": "string", "gift_card_token_hash": "string", "modifiers": [ { "id": "0192f1e4-7c3a-7b2e-9f10-5d6c7e8f9a0b", "name": "Oat milk", "price_delta": { "amount": 1250, "currency": "GBP" } } ], "multibuy": { "every": 2, "price": { "amount": 1250, "currency": "GBP" } }, "note": "string", "origin": "till", "product_id": "0192f1e4-7c3a-7b2e-9f10-5d6c7e8f9a0b", "product_type": "standard", "quantity": "3", "seat": 1, "sent_at": "2026-09-11T09:30:00Z", "serials": [], "tax": { "amount": 1250, "currency": "GBP" }, "tax_breakdown": [ { "amount": { "amount": 1250, "currency": "GBP" }, "inclusive": false, "percentage": "20", "rate_id": "0192f1e4-7c3a-7b2e-9f10-5d6c7e8f9a0b" } ], "tax_inclusive": false, "tax_rate_percentage": "20", "total": { "amount": 1250, "currency": "GBP" }, "unit_of_measure": "each", "unit_price": { "amount": 1250, "currency": "GBP" }, "variant_id": "0192f1e4-7c3a-7b2e-9f10-5d6c7e8f9a0b" } ], "location_id": "0192f1e4-7c3a-7b2e-9f10-5d6c7e8f9a0b", "loyalty_earned": 0, "loyalty_spent": 0, "member": { "id": "0192f1e4-7c3a-7b2e-9f10-5d6c7e8f9a0b", "name": "string", "email": "ada@example.com", "role": "owner" }, "merchant_id": "0192f1e4-7c3a-7b2e-9f10-5d6c7e8f9a0b", "owner_member": { "id": "0192f1e4-7c3a-7b2e-9f10-5d6c7e8f9a0b", "name": "string", "email": "ada@example.com", "role": "owner" }, "paid": { "amount": 1250, "currency": "GBP" }, "payments": [ { "id": "0192f1e4-7c3a-7b2e-9f10-5d6c7e8f9a0b", "amount": { "amount": 1250, "currency": "GBP" }, "buyer_supplied": { "amount": 1250, "currency": "GBP" }, "card_brand": "string", "card_confirmation": "confirmed", "card_last4": "string", "change_back": { "amount": 1250, "currency": "GBP" }, "fingerprint": "string", "gift_card_hold_id": "0192f1e4-7c3a-7b2e-9f10-5d6c7e8f9a0b", "line_ids": [ "0192f1e4-7c3a-7b2e-9f10-5d6c7e8f9a0b" ], "member": { "id": "0192f1e4-7c3a-7b2e-9f10-5d6c7e8f9a0b", "name": "string", "email": "ada@example.com", "role": "owner" }, "method": "cash", "pin": "string", "reference": "pspRef_8829301", "tip": { "amount": 1250, "currency": "GBP" } } ], "pickup_at": "2026-09-11T09:30:00Z", "ready_at": "2026-09-11T09:30:00Z", "ready_to_pay_at": "2026-09-11T09:30:00Z", "received_at": "2026-09-08T09:41:12Z", "reference": "A-0148", "refunded": { "amount": 1250, "currency": "GBP" }, "rejection_note": "string", "rejection_reason": "sold_out", "service_charge": { "amount": 1250, "currency": "GBP" }, "service_charge_tax": { "amount": 1250, "currency": "GBP" }, "service_charge_tax_class_id": "0192f1e4-7c3a-7b2e-9f10-5d6c7e8f9a0b", "service_charge_tax_rate_percentage": "20", "source": "string", "source_name": "string", "state": "open", "table_id": "0192f1e4-7c3a-7b2e-9f10-5d6c7e8f9a0b", "tips": { "amount": 1250, "currency": "GBP" }, "totals": { "cash_rounding": { "amount": 1250, "currency": "GBP" }, "discount_total": { "amount": 1250, "currency": "GBP" }, "service_charge": { "amount": 1250, "currency": "GBP" }, "service_charge_tax": { "amount": 1250, "currency": "GBP" }, "subtotal": { "amount": 1250, "currency": "GBP" }, "tax_total": { "amount": 1250, "currency": "GBP" }, "total": { "amount": 1250, "currency": "GBP" } }, "updated_at": "2026-09-08T09:41:12Z", "version": 7, "void_member": { "id": "0192f1e4-7c3a-7b2e-9f10-5d6c7e8f9a0b", "name": "string", "email": "ada@example.com", "role": "owner" }, "void_note": "string", "void_reason": "customer_canceled", "voided_at": "2026-09-11T09:30:00Z" } ], "next_cursor": "string" }
POST/v1/orders/batch-create

Record what happened to orders

No. batchCreateOrdersAuth pos:orders:write ordering:write
Records facts about orders — a tab opened, a line rung up or voided, a payment taken, a tab renamed, a sale completed, canceled or voided, an asked-for order accepted or rejected — as many as a client has queued, across any number of orders. A fact is never edited, so this is batch-create: a correction is a fact of its own, such as a void.
Asynchronous. A fact is appended to the order's log and answered received; it is applied afterwards, and what the order has become is read back from GET /v1/orders/{id}, the change feed, or the order.* webhooks. Nothing about an order's current state can refuse a fact, because the thing it records has already happened: two rounds on one tab from two tills are two facts, and neither is refused. Only an item that is malformed — a type without the member it names, or a fact id already used for a different fact — fails, and it fails in its result, not the request.
Each item carries its own idempotency_key and the fact its own id, minted by the device. Sending a fact again returns received again and records it once, so a till that cannot tell a lost request from a lost response simply resends. Facts about one order may arrive in any order and from any device: a line before the tab it is on, a void before its line. They are held for their order until they can be applied.
See docs/engineering/recording-what-happened.md, section 12.
Request body application/json · OrderFactBatchCreateRequest

itemsarray of OrderFact

Required
≥ 1 items · ≤ 500 items

idstring · uuid

Required
UUIDv7, minted by the device that recorded the fact. Sending the same fact again under this id records it once; sending a different fact under it fails.

typestring · enum

Required
What happened, which decides the one member the fact carries.
createdline_item_addedline_item_voidedpayment_takenupdatedcompletedcanceledvoidedrefundedacceptedrejectedreadyready_undone

acceptanceOrderFactAcceptance

An asked-for order taken on (accepted) or turned down (rejected), beside its lifecycle rather than in it: an order's acceptance is pending from a channel that needs one — the ordering page, an integration — until one of these arrives, or its location's deadline passes and it is rejected as timed_out.

notestring
What the guest is told, in the staff member's words. Required when the reason is other.
≤ 512 chars

pickup_atstring · date-time
When the venue says the order will be ready, on accepted: the guest is told it, and it becomes the order's pickup_at. Absent keeps the time the guest asked for. Square's fulfilment key.

rejection_reasonstring · enum
Why the order was turned down. Required on rejected, absent on accepted. timed_out is the sweep that rejects an order nobody took on before its location's deadline.
sold_outclosedtoo_busyothertimed_out

cancellationOrderFactCancellation

An open order ended without being paid — a tab somebody walked out on, one opened by mistake — and kept, with its reason, so it is accounted for rather than vanishing. A completed order is voided instead.

notestring
What happened, in the staff member's words. Required when reason is other.
≤ 512 chars

reasonstring · enum

Required
abandoned is a tab nobody paid for; staff_error was opened by mistake. An order the business declined is rejected, a fact of its own.
abandonedstaff_errorother

completionOrderFactCompletion

The order paid and closed. Its total is derived from its lines, voids and payments when the completion is applied, never taken from here; totals is what the till showed the guest, kept so a disagreement can be flagged rather than silently resolved.

age_confirmedboolean
The till confirmed the guest's age before this sale completed: the sale carried an age-restricted line (its product's minimum_age), and the operator attested the guest could prove it. Absent on a sale with no age-restricted line.
default false

age_minimuminteger · int32
The oldest buyer the sale's age-restricted lines allowed, as the till recorded it: the highest minimum_age among the lines at the moment the sale completed. 0 when the sale carried none, or when no check was recorded.
0–100 · default 0

documentOrderDocument

The fiscal document a completed order is recorded as, in the per-till series 0016 builds. Every sales document a till issues belongs to a series it was issued at enrolment, and the number is a gap-free counter in that series, incremented in the same transaction that completes the order. Printed on the receipt and sent with the order; the server stores it and refuses a duplicate (series, number).
This is the number a market's fiscal rules are about — the correlative number within a series. It is not the order's reference, which stays the short per-day call number for staff to find a sale.

kindstring · enum

Required
What the document is. invoice is the ordinary receipt — the simplified invoice most markets call a receipt. A full invoice and a rectifying document will be separate kinds, each in its own series.
invoice
default invoice

numberinteger · int64

Required
The gap-free sequence number within the series, starting at 1. Never reused: a void keeps its number, and a correction is a new document in a rectifying series.
≥ 1

seriesstring

Required
The series this document belongs to: a short code issued to one till at enrolment (e.g. B1-T3), one per device and kind of document. The ordinary receipt is in the invoice series.
≤ 32 chars

loyalty_hold_idstring · uuid
The hold the till took on the guest's points before redeeming the sale's rewards (batchCreateLoyaltyHolds), which the completion settles. Absent for a sale that redeems nothing, or redeemed offline against what the till last knew.

referencestring
The short reference printed on the receipt and used by staff to find the order.
≤ 64 chars

service_chargeMoney

Nullable
The discretionary service charge the till added to the bill, in the order's currency; null when the merchant charges none.

amountinteger · int64

Required
The amount, as a whole number of the currency's minor unit. May be negative to express a refund, discount or credit.

currencyCurrency

Required
ISO 4217 currency code.
Determines the minor unit that Money.amount is expressed in. Zero-decimal currencies such as JPY have a minor unit equal to the major unit.
One of 182 values; see the schema.

service_charge_declinedboolean
The guest declined the discretionary service charge, so none is applied.
default false

totalsOrderTotals

Required
The money on an order, broken out.
These are computed and sent by the device, then independently recomputed by the server on receipt. A mismatch is rejected with 422 rather than quietly corrected: if the till printed a receipt showing one total and the server stored another, the merchant has an unreconcilable discrepancy and no way to know which is right. Failing loudly surfaces a till running stale tax configuration while it is still one order, not a month's worth.

cash_roundingMoney

Nullable
How much a cash settlement rounded the price, signed (docs/decisions/0015): a €10.02 bill rounded up to €10.05 has cash_rounding 3, and the cash payment's goods portion is the total plus this. The till computes it from the location's cash step; the server recomputes and rejects a mismatch. Zero on a sale no cash settles, and cards are never rounded.

amountinteger · int64

Required
The amount, as a whole number of the currency's minor unit. May be negative to express a refund, discount or credit.

currencyCurrency

Required
ISO 4217 currency code.
Determines the minor unit that Money.amount is expressed in. Zero-decimal currencies such as JPY have a minor unit equal to the major unit.
One of 182 values; see the schema.

discount_totalMoney

Required
A monetary amount in a specific currency: Square's Money, and Stripe's amount beside its currency.
The amount is always an integer count of the currency's minor unit — pence for GBP, cents for USD. Zero-decimal currencies such as JPY have a minor unit equal to their major unit, so {"amount": 500, "currency": "JPY"} is ¥500 while {"amount": 500, "currency": "GBP"} is £5.00.
Floating point is never used for money anywhere in this API. Binary floats cannot represent most decimal fractions exactly, so accumulating them across the line items of an order produces totals that disagree with the printed receipt by a penny. Integer minor units make every arithmetic operation exact.

amountinteger · int64

Required
The amount, as a whole number of the currency's minor unit. May be negative to express a refund, discount or credit.

currencyCurrency

Required
ISO 4217 currency code.
Determines the minor unit that Money.amount is expressed in. Zero-decimal currencies such as JPY have a minor unit equal to the major unit.
One of 182 values; see the schema.

service_chargeMoney

A monetary amount in a specific currency: Square's Money, and Stripe's amount beside its currency.
The amount is always an integer count of the currency's minor unit — pence for GBP, cents for USD. Zero-decimal currencies such as JPY have a minor unit equal to their major unit, so {"amount": 500, "currency": "JPY"} is ¥500 while {"amount": 500, "currency": "GBP"} is £5.00.
Floating point is never used for money anywhere in this API. Binary floats cannot represent most decimal fractions exactly, so accumulating them across the line items of an order produces totals that disagree with the printed receipt by a penny. Integer minor units make every arithmetic operation exact.

amountinteger · int64

Required
The amount, as a whole number of the currency's minor unit. May be negative to express a refund, discount or credit.

currencyCurrency

Required
ISO 4217 currency code.
Determines the minor unit that Money.amount is expressed in. Zero-decimal currencies such as JPY have a minor unit equal to the major unit.
One of 182 values; see the schema.

service_charge_taxMoney

Nullable
The tax on the service charge (decision record 0054), its own line and never folded into goods tax_total. Computed server-side from the location's service-charge tax class and the sale's fulfilment and business date. Null when the charge is not taxed.

amountinteger · int64

Required
The amount, as a whole number of the currency's minor unit. May be negative to express a refund, discount or credit.

currencyCurrency

Required
ISO 4217 currency code.
Determines the minor unit that Money.amount is expressed in. Zero-decimal currencies such as JPY have a minor unit equal to the major unit.
One of 182 values; see the schema.

subtotalMoney

Required
A monetary amount in a specific currency: Square's Money, and Stripe's amount beside its currency.
The amount is always an integer count of the currency's minor unit — pence for GBP, cents for USD. Zero-decimal currencies such as JPY have a minor unit equal to their major unit, so {"amount": 500, "currency": "JPY"} is ¥500 while {"amount": 500, "currency": "GBP"} is £5.00.
Floating point is never used for money anywhere in this API. Binary floats cannot represent most decimal fractions exactly, so accumulating them across the line items of an order produces totals that disagree with the printed receipt by a penny. Integer minor units make every arithmetic operation exact.

amountinteger · int64

Required
The amount, as a whole number of the currency's minor unit. May be negative to express a refund, discount or credit.

currencyCurrency

Required
ISO 4217 currency code.
Determines the minor unit that Money.amount is expressed in. Zero-decimal currencies such as JPY have a minor unit equal to the major unit.
One of 182 values; see the schema.

tax_totalMoney

Required
A monetary amount in a specific currency: Square's Money, and Stripe's amount beside its currency.
The amount is always an integer count of the currency's minor unit — pence for GBP, cents for USD. Zero-decimal currencies such as JPY have a minor unit equal to their major unit, so {"amount": 500, "currency": "JPY"} is ¥500 while {"amount": 500, "currency": "GBP"} is £5.00.
Floating point is never used for money anywhere in this API. Binary floats cannot represent most decimal fractions exactly, so accumulating them across the line items of an order produces totals that disagree with the printed receipt by a penny. Integer minor units make every arithmetic operation exact.

amountinteger · int64

Required
The amount, as a whole number of the currency's minor unit. May be negative to express a refund, discount or credit.

currencyCurrency

Required
ISO 4217 currency code.
Determines the minor unit that Money.amount is expressed in. Zero-decimal currencies such as JPY have a minor unit equal to the major unit.
One of 182 values; see the schema.

totalMoney

Required
A monetary amount in a specific currency: Square's Money, and Stripe's amount beside its currency.
The amount is always an integer count of the currency's minor unit — pence for GBP, cents for USD. Zero-decimal currencies such as JPY have a minor unit equal to their major unit, so {"amount": 500, "currency": "JPY"} is ¥500 while {"amount": 500, "currency": "GBP"} is £5.00.
Floating point is never used for money anywhere in this API. Binary floats cannot represent most decimal fractions exactly, so accumulating them across the line items of an order produces totals that disagree with the printed receipt by a penny. Integer minor units make every arithmetic operation exact.

amountinteger · int64

Required
The amount, as a whole number of the currency's minor unit. May be negative to express a refund, discount or credit.

currencyCurrency

Required
ISO 4217 currency code.
Determines the minor unit that Money.amount is expressed in. Zero-decimal currencies such as JPY have a minor unit equal to the major unit.
One of 182 values; see the schema.

device_seqinteger · int64

Nullable
The recording device's own sequence number for this fact, one higher than its last, across every fact it records. A gap is a fact that never arrived. Null from a client that is not a device.
≥ 1

hlcHLC
A hybrid logical clock stamp (Kulkarni et al., 2014): the recorder's wall clock in milliseconds in the high 48 bits and a counter in the low 16, a 64-bit integer written as its decimal digits in a string. A stamp is past 2^53, beyond the integers a JSON number holds exactly as most parsers read it, so I-JSON writes it as a string (RFC 7493 §2.2).
A device stamps every fact it records, as it records it, after every stamp it has made or pulled — every change on the feed carries one — so a fact recorded after seeing another ranks after it whatever either wall clock says. The stamp is when the fact happened. The server keeps it unless it is more than ten minutes ahead of the server's clock, more than thirty days behind it, or from before the device was paired. A fact is never refused for its stamp: one the server does not believe, cannot read or was not given is stamped as the server takes it, and flagged on what it dates — the order, the shift, the drawer or the shelf.

line_itemOrderLineItem

One line of a sale.
Every descriptive and monetary field here is a snapshot copied from the catalogue at the moment of sale. product_id is retained for reporting, but nothing on this line is ever re-resolved from it — otherwise editing a product would silently rewrite history.

idstring · uuid

Required
UUIDv7, minted by the device.

namestring

Required
Product name as sold. Snapshot; never re-read from the product.
1–255 chars

approved_by_memberMemberSnapshot

Nullable
The manager or owner who authorised a staff member's discount or comp above the merchant's discount_approval_threshold_minor/discount_approval_threshold_percentage or a comp when comp_requires_manager is set, as they were then; null when no approval was needed.

idstring · uuid

Required
The roster's id, checked against the merchant's memberships.

namestring

Required
What the member was called.
≥ 1 chars

emailstring · email

Required
The member's address.

rolestring · enum

Required
The role the member held.
ownermanagerstaff

category_idstring · uuid

RequiredNullable
The category the product was filed under when the line was rung, for reporting. Snapshot: moving the product to another category later moves no sale. Null on an ad-hoc line or an uncategorised product.

category_namestring

Required
The category's name when the line was rung, so a report of past sales reads as they were filed. Snapshot; empty when category_id is null.
≤ 255 chars

comp_reasonstring
Why this line was given away. Present on a comp — an item given away at no charge — and means something different from a discount, so it is reported separately. Required when the line is a comp.
≤ 512 chars

courseinteger · int32

Nullable
The course this line belongs to, in a full-service kitchen — starters, mains, desserts. Set on the till when ringing to a course, and used to hold or fire a course from the till. Null for a single-course counter sale or a course-less line. Held courses are not sent (sent_at null) until they are fired.
≥ 1

discountMoney

A monetary amount in a specific currency: Square's Money, and Stripe's amount beside its currency.
The amount is always an integer count of the currency's minor unit — pence for GBP, cents for USD. Zero-decimal currencies such as JPY have a minor unit equal to their major unit, so {"amount": 500, "currency": "JPY"} is ¥500 while {"amount": 500, "currency": "GBP"} is £5.00.
Floating point is never used for money anywhere in this API. Binary floats cannot represent most decimal fractions exactly, so accumulating them across the line items of an order produces totals that disagree with the printed receipt by a penny. Integer minor units make every arithmetic operation exact.

amountinteger · int64

Required
The amount, as a whole number of the currency's minor unit. May be negative to express a refund, discount or credit.

currencyCurrency

Required
ISO 4217 currency code.
Determines the minor unit that Money.amount is expressed in. Zero-decimal currencies such as JPY have a minor unit equal to the major unit.
One of 182 values; see the schema.

discount_idstring · uuid

Nullable
The discount definition applied to this line, for reporting. Null for a line with no discount. Snapshot — the discount is recorded so its use can be attributed even if the definition later changes.

discount_namestring
The discount's name at the time the line was priced, snapshotted on the line — the reason a guest can be told, without re-resolving a definition that may have been renamed or deleted. Empty for a line with no discount.
≤ 200 chars

gift_card_codestring

Nullable
The code on the card being sold, when the line's product is a gift_card — typed or scanned at the till. The server issues the card (or refuses a code already live) when the order completes. Null for any other line.
≤ 64 chars

gift_card_token_hashstring

Nullable
The hash of the balance-page token for the card being sold: SHA-256 over the token's text, in base64url without padding. The device mints the token — 32 random bytes, unpadded base64url — and prints it on the receipt's balance link; only its hash leaves the device, so the token is never on the record of the sale, and the server checks a link by hashing the token it carries (W3C, "Good Practices for Capability URLs"). Absent leaves the card with no balance link until one is made (gift-card-balance-links). Null for any other line.
43–43 chars · pattern ^[A-Za-z0-9_-]{43}$

modifiersarray of OrderLineModifier

The options chosen on this line, snapshotted at the moment of sale. The line's unit_price already includes each option's delta.
The server checks only the shape of these — a negative delta is refused, an option chosen twice is refused — and never refuses a sale because the menu has changed since the till synced. A sale that was correct when rung stays correct.

idstring · uuid

Required
The modifier that was chosen. Kept for reporting, never re-resolved.

namestring

Required
Option name as sold. Snapshot.
1–255 chars

price_deltaMoney

Required
A monetary amount in a specific currency: Square's Money, and Stripe's amount beside its currency.
The amount is always an integer count of the currency's minor unit — pence for GBP, cents for USD. Zero-decimal currencies such as JPY have a minor unit equal to their major unit, so {"amount": 500, "currency": "JPY"} is ¥500 while {"amount": 500, "currency": "GBP"} is £5.00.
Floating point is never used for money anywhere in this API. Binary floats cannot represent most decimal fractions exactly, so accumulating them across the line items of an order produces totals that disagree with the printed receipt by a penny. Integer minor units make every arithmetic operation exact.

amountinteger · int64

Required
The amount, as a whole number of the currency's minor unit. May be negative to express a refund, discount or credit.

currencyCurrency

Required
ISO 4217 currency code.
Determines the minor unit that Money.amount is expressed in. Zero-decimal currencies such as JPY have a minor unit equal to the major unit.
One of 182 values; see the schema.

multibuyMultibuyRule

Nullable
The product's multibuy rule as it stood when the line was rung, snapshotted on the line so the server resolves the gross by the same deal the till did — re-pricing a product never rewrites a sale that was correct. Null on a line with no deal. A rule never applies to a weighed line.

everyinteger

Required
How many units make a run; 3 is the ordinary buy-two-get-one.
2–1000

priceMoney

Required
A monetary amount in a specific currency: Square's Money, and Stripe's amount beside its currency.
The amount is always an integer count of the currency's minor unit — pence for GBP, cents for USD. Zero-decimal currencies such as JPY have a minor unit equal to their major unit, so {"amount": 500, "currency": "JPY"} is ¥500 while {"amount": 500, "currency": "GBP"} is £5.00.
Floating point is never used for money anywhere in this API. Binary floats cannot represent most decimal fractions exactly, so accumulating them across the line items of an order produces totals that disagree with the printed receipt by a penny. Integer minor units make every arithmetic operation exact.

amountinteger · int64

Required
The amount, as a whole number of the currency's minor unit. May be negative to express a refund, discount or credit.

currencyCurrency

Required
ISO 4217 currency code.
Determines the minor unit that Money.amount is expressed in. Zero-decimal currencies such as JPY have a minor unit equal to the major unit.
One of 182 values; see the schema.

notestring
Free text from the till — "oat milk", "no sugar".
≤ 512 chars

product_idstring · uuid

Nullable
The catalogue product, for reporting. Null for an ad-hoc line — a miscellaneous item rung up at a custom price, which every real till needs.

product_typestring · enum

Required
What the product was when the line was rung: a gift_card sold is money taken for a promise, not revenue, and a combo is a set. Square's item_type. Snapshot, copied from the product at the moment of sale; standard on an ad-hoc line.
standardgift_cardcombo

quantityQuantity

Required
How much of something, as a decimal string in the unit_of_measure beside it (each where there is none), as Square's quantity is: three croissants are "3", 1.4 kg of beans is "1.4". A string because a JSON number is a binary float to most parsers.
It has at most as many decimal places as its unit's base unit holds — three in each, g and ml, six in kg and l — and a finer one is refused, never rounded. Tenvelo holds every quantity as an integer of that base unit (thousandths of an each, milligrams, microlitres; docs/decisions/0063); a client that computes with one should read the digits the same way, never through a float.
≤ 26 chars · pattern ^-?(0|[1-9][0-9]*)(\.[0-9]{1,6})?$

seatinteger · int32

Nullable
The seat this line is for, when a table's seats are numbered. Set on the till and carried to the kitchen and to split bills. Null for a counter sale or an unnumbered seat.
≥ 1

sent_atstring · date-time

Nullable
When this line was sent to the kitchen — set by the till when a tab is held or a sale completed, and immutable once set. A kitchen knows what to cook from the lines of a ticket, and a new round on a tab is a new set of sent_at values rather than the old lines re-sent. Null on a line the till has not yet held or completed.

serialsarray of string
The serial numbers of the units this line sold (retail item: serial numbers) — one per unit, in the order they were entered, printed on a product whose track_serial is set. Empty on any other line. A snapshot like the name and price: the record of which physical units left the shelf, so a specific unit sold is traceable to its sale.
default []

taxMoney

A monetary amount in a specific currency: Square's Money, and Stripe's amount beside its currency.
The amount is always an integer count of the currency's minor unit — pence for GBP, cents for USD. Zero-decimal currencies such as JPY have a minor unit equal to their major unit, so {"amount": 500, "currency": "JPY"} is ¥500 while {"amount": 500, "currency": "GBP"} is £5.00.
Floating point is never used for money anywhere in this API. Binary floats cannot represent most decimal fractions exactly, so accumulating them across the line items of an order produces totals that disagree with the printed receipt by a penny. Integer minor units make every arithmetic operation exact.

amountinteger · int64

Required
The amount, as a whole number of the currency's minor unit. May be negative to express a refund, discount or credit.

currencyCurrency

Required
ISO 4217 currency code.
Determines the minor unit that Money.amount is expressed in. Zero-decimal currencies such as JPY have a minor unit equal to the major unit.
One of 182 values; see the schema.

tax_breakdownarray of TaxBreakdownItem

Each rate's share of this line's tax, in the order its rule names the rates, when the line is taxed over several rates (each a separate calculation, each rounding with its own mode). Absent — null — on a line taxed at a single rate, where tax_rate_percentage and tax are the whole story.

amountMoney

Required
A monetary amount in a specific currency: Square's Money, and Stripe's amount beside its currency.
The amount is always an integer count of the currency's minor unit — pence for GBP, cents for USD. Zero-decimal currencies such as JPY have a minor unit equal to their major unit, so {"amount": 500, "currency": "JPY"} is ¥500 while {"amount": 500, "currency": "GBP"} is £5.00.
Floating point is never used for money anywhere in this API. Binary floats cannot represent most decimal fractions exactly, so accumulating them across the line items of an order produces totals that disagree with the printed receipt by a penny. Integer minor units make every arithmetic operation exact.

amountinteger · int64

Required
The amount, as a whole number of the currency's minor unit. May be negative to express a refund, discount or credit.

currencyCurrency

Required
ISO 4217 currency code.
Determines the minor unit that Money.amount is expressed in. Zero-decimal currencies such as JPY have a minor unit equal to the major unit.
One of 182 values; see the schema.

inclusiveboolean

Required
Whether this rate is inside the price (true) or added on top (false).

percentagePercentage

Required
A share of a whole, from "0" to "100", as a percentage in a decimal string with at most four decimal places, as Square's percentage and Stripe Tax's percentage_decimal are: UK VAT at 20% is "20", and an 8.875% US sales tax is "8.875".
A string because a JSON number is a binary float to most parsers, and a float cannot hold most decimal fractions exactly (RFC 7493 §2.2). Tenvelo computes with a percentage as an integer in parts per million ("8.875" is 88750), which every four-place percentage is exactly. A client that computes with one should read the digits the same way, never through a float.
pattern ^(100(\.0{1,4})?|(0|[1-9][0-9]?)(\.[0-9]{1,4})?)$

rate_idstring · uuid

Required
The rate this share belongs to.

tax_inclusiveboolean
Whether unit_price already contains the tax. Snapshot.

tax_rate_percentagePercentage
A share of a whole, from "0" to "100", as a percentage in a decimal string with at most four decimal places, as Square's percentage and Stripe Tax's percentage_decimal are: UK VAT at 20% is "20", and an 8.875% US sales tax is "8.875".
A string because a JSON number is a binary float to most parsers, and a float cannot hold most decimal fractions exactly (RFC 7493 §2.2). Tenvelo computes with a percentage as an integer in parts per million ("8.875" is 88750), which every four-place percentage is exactly. A client that computes with one should read the digits the same way, never through a float.
pattern ^(100(\.0{1,4})?|(0|[1-9][0-9]?)(\.[0-9]{1,4})?)$

totalMoney

Required
A monetary amount in a specific currency: Square's Money, and Stripe's amount beside its currency.
The amount is always an integer count of the currency's minor unit — pence for GBP, cents for USD. Zero-decimal currencies such as JPY have a minor unit equal to their major unit, so {"amount": 500, "currency": "JPY"} is ¥500 while {"amount": 500, "currency": "GBP"} is £5.00.
Floating point is never used for money anywhere in this API. Binary floats cannot represent most decimal fractions exactly, so accumulating them across the line items of an order produces totals that disagree with the printed receipt by a penny. Integer minor units make every arithmetic operation exact.

amountinteger · int64

Required
The amount, as a whole number of the currency's minor unit. May be negative to express a refund, discount or credit.

currencyCurrency

Required
ISO 4217 currency code.
Determines the minor unit that Money.amount is expressed in. Zero-decimal currencies such as JPY have a minor unit equal to the major unit.
One of 182 values; see the schema.

unit_of_measurestring · enum

Nullable
The unit this line was sold in, snapshotted from the product at the moment of sale (the product's own unit on a product line; any unit on an ad-hoc line). Absent means each.
eachkgglml

unit_priceMoney

Required
A monetary amount in a specific currency: Square's Money, and Stripe's amount beside its currency.
The amount is always an integer count of the currency's minor unit — pence for GBP, cents for USD. Zero-decimal currencies such as JPY have a minor unit equal to their major unit, so {"amount": 500, "currency": "JPY"} is ¥500 while {"amount": 500, "currency": "GBP"} is £5.00.
Floating point is never used for money anywhere in this API. Binary floats cannot represent most decimal fractions exactly, so accumulating them across the line items of an order produces totals that disagree with the printed receipt by a penny. Integer minor units make every arithmetic operation exact.

amountinteger · int64

Required
The amount, as a whole number of the currency's minor unit. May be negative to express a refund, discount or credit.

currencyCurrency

Required
ISO 4217 currency code.
Determines the minor unit that Money.amount is expressed in. Zero-decimal currencies such as JPY have a minor unit equal to the major unit.
One of 182 values; see the schema.

variant_idstring · uuid

Nullable
The variant that was sold, for reporting and stock. Null when the product itself is the sellable unit — a product with no variants, or with none picked. Like product_id, it is retained for reporting and never re-resolved: the descriptive and monetary fields on this line are the snapshot that is replayed, so a sale that was correct when rung stays correct even if the catalogue has changed since.

line_item_voidOrderFactLineItemVoid

Some or all of a line taken back off an order before it was paid for. The void is a record of its own, as a refund or a reversal is: the line it names is never edited, and what the line stands at is what was rung up less every void of it.

approved_by_memberMemberSnapshot

A member of the team as whoever recorded it knew them when it happened: who they were, what they were called and how to reach them, and the role they held. A fact keeps all of it, so a later rename, new address or change of role restates nothing it says.

idstring · uuid

Required
The roster's id, checked against the merchant's memberships.

namestring

Required
What the member was called.
≥ 1 chars

emailstring · email

Required
The member's address.

rolestring · enum

Required
The role the member held.
ownermanagerstaff

line_item_idstring · uuid

Required
The line voided, by the id the device minted for it.

notestring
What happened, in the staff member's words. Required when reason is other.
≤ 512 chars

quantityQuantity

Required
How much of something, as a decimal string in the unit_of_measure beside it (each where there is none), as Square's quantity is: three croissants are "3", 1.4 kg of beans is "1.4". A string because a JSON number is a binary float to most parsers.
It has at most as many decimal places as its unit's base unit holds — three in each, g and ml, six in kg and l — and a finer one is refused, never rounded. Tenvelo holds every quantity as an integer of that base unit (thousandths of an each, milligrams, microlitres; docs/decisions/0063); a client that computes with one should read the digits the same way, never through a float.
≤ 26 chars · pattern ^-?(0|[1-9][0-9]*)(\.[0-9]{1,6})?$

reasonstring · enum

Required
Why, kept apart from the arithmetic. comp is a line given away after it was rung up; a discount given as it is rung up is on the line itself.
customer_changed_mindstaff_errorcompother

location_idstring · uuid

Required
The location the order is at, which every fact about it names, as Square's order does. The server applies a location's facts in the order it took them, and each location's apart from the others'. A till begins orders at its own location. Every other fact names its order's location wherever it was taken, so a refund at another location is its sale's. A fact naming a different location from its order's fails.

memberMemberSnapshot

Nullable
The staff member who did it, as the till knew them then; checked against the merchant's memberships when the fact is applied. Null when no person was attributed.

idstring · uuid

Required
The roster's id, checked against the merchant's memberships.

namestring

Required
What the member was called.
≥ 1 chars

emailstring · email

Required
The member's address.

rolestring · enum

Required
The role the member held.
ownermanagerstaff

occurred_atstring · date-time
What the recording device's own clock read when it recorded the fact, kept as it said it. Nothing is decided by it: the stamp (hlc) is when the fact happened.

orderOrderFactCreated

An order begun: a tab opened, a counter sale started, a guest's order asked for. What it holds — its lines, its payments — arrives as facts of their own, in the same batch or later. Whether an order needs accepting is decided from where it came from, never said here.

namestring
Whose order it is while it is open — a name the shop shouts across the bar.
≤ 128 chars

coversinteger · int32
How many people the party is, as counted at seating; zero where nobody counted them. It is stated when the order begins and is what the covers-per-labour-hour and average-spend-per-cover figures are divided by, so a tab opened without a count adds no covers rather than one.
0–1000 · default 0

currencyCurrency

Required
ISO 4217 currency code.
Determines the minor unit that Money.amount is expressed in. Zero-decimal currencies such as JPY have a minor unit equal to the major unit.
One of 182 values; see the schema.

customer_idstring · uuid
The guest the order is recorded against, if one was linked when it began.

delivery_addressAddress

A postal address.
The address_line_* fields carry the most specific part of the address — street number, street name, building name. Less specific detail belongs in locality, administrative_district_level_* and country.
The administrative_district_level_* fields are deliberately generic because their meaning is country-dependent: in the US level 1 is the state and level 2 the county; in the UK level 1 is the county.

address_line_1string

Required
First line of the address — street number, street name, building name.
≤ 255 chars

address_line_2string
Second line of the address, if any.
≤ 255 chars

address_line_3string
Third line of the address, if any.
≤ 255 chars

administrative_district_level_1string
A civil entity within the country. The state in the US; the county in the UK.
≤ 128 chars

administrative_district_level_2string
A civil entity within administrative_district_level_1.
≤ 128 chars

countryCountry

Required
ISO 3166-1 alpha-2 country code.
ZZ is the unknown/unspecified placeholder.
One of 250 values; see the schema.

localitystring
The city or town.
≤ 128 chars

postal_codestring
The postal or ZIP code.
≤ 32 chars

sublocalitystring
A civil region within the locality, if any.
≤ 128 chars

drawer_session_idstring · uuid
The drawer session the till had open when the order began, if any.

email_receiptboolean
The guest asked for the receipt by email. The address is always their customer record's, and honoured only with their consent.
default false

external_referencestring
The writer's own reference for the order — a delivery platform's order id — so the venue can match what the platform later says about it.
≤ 128 chars

fulfillment_typestring · enum
How the order leaves the building — eaten in, collected, or delivered — which a tax rule is keyed by (docs/decisions/0014).
on_premisespickupdelivery
default on_premises

location_idstring · uuid

Required
Where the order is being served, which every later fact about it inherits.

owner_memberMemberSnapshot

A member of the team as whoever recorded it knew them when it happened: who they were, what they were called and how to reach them, and the role they held. A fact keeps all of it, so a later rename, new address or change of role restates nothing it says.

idstring · uuid

Required
The roster's id, checked against the merchant's memberships.

namestring

Required
What the member was called.
≥ 1 chars

emailstring · email

Required
The member's address.

rolestring · enum

Required
The role the member held.
ownermanagerstaff

pickup_atstring · date-time
When the guest was told they could collect, where somebody promised a time.

table_idstring · uuid
The table the order is parked on, if any.

order_idstring · uuid

Required
The order this happened to, whose id the device that began it minted. A fact may name an order whose created has not arrived yet.

paymentPayment

How a sale was paid for.
A list rather than a single method, because a real sale splits: twenty pounds in cash and the rest on a card is ordinary, and a model that cannot express it forces staff to lie to the till.
Shaped to match Square's Tender, deliberately. Staff and integrators move between these systems, and the places where Square's model is subtle are places it has already been proven wrong the other way: amount includes the tip, cash records what the buyer actually handed over, and change is calculated rather than claimed.
This records payment; it does not take it. Cash is settled by definition — it is in the drawer. A card row is a claim about what the terminal reported, and becomes money only when the PSP settles it.

idstring · uuid
The payment's id. Minted by the device, so a retry of the same tender converges on the same row instead of recording the money twice; the server mints one when a writer does not supply it. A refund names it as payment_id, and a card refund is reversed against it, so it is returned with every read of the order and never renumbered.

amountMoney

Required
The total taken by this payment, including any tip.
Following Square: the tender's amount is what the customer parted with, and tip is the portion of it that is not for goods. Modelling it the other way — an amount that excludes the tip — means every reconciliation has to remember to add the two back together, and one place that forgets is a day's takings that do not balance.

amountinteger · int64

Required
The amount, as a whole number of the currency's minor unit. May be negative to express a refund, discount or credit.

currencyCurrency

Required
ISO 4217 currency code.
Determines the minor unit that Money.amount is expressed in. Zero-decimal currencies such as JPY have a minor unit equal to the major unit.
One of 182 values; see the schema.

buyer_suppliedMoney

Nullable
What the customer physically handed over. Cash only.
Recorded rather than assumed so that change is derived from it: a note tendered for a smaller sale is the ordinary case, and the drawer at close must agree with the sum of what went in.

amountinteger · int64

Required
The amount, as a whole number of the currency's minor unit. May be negative to express a refund, discount or credit.

currencyCurrency

Required
ISO 4217 currency code.
Determines the minor unit that Money.amount is expressed in. Zero-decimal currencies such as JPY have a minor unit equal to the major unit.
One of 182 values; see the schema.

gift_card_hold_idstring · uuid
The hold a till took on the voucher's card before tendering it (batchCreateGiftCardHolds), which this payment settles. Absent for a voucher tendered offline, which is spent against what the till last knew of the card.

line_idsarray of string · uuid
The lines this payment settled, when the till knows the split: a share pays whole lines, so a reopened tab shows the unpaid lines rather than a number, and a mistake cannot charge somebody twice (tabs item 13).
Empty when the payment named no lines — a whole-sale tender, an even split, a card share settling what is left, and every payment recorded before this existed. Empty and absent mean the same thing and are accepted alike, and a till sends the empty array.

memberMemberSnapshot

Nullable
The member who took this tender — the terminal operator who took the tip, not whoever rang the sale. The kept tip rule follows it. Absent for a payment recorded by something that is not a person.

idstring · uuid

Required
The roster's id, checked against the merchant's memberships.

namestring

Required
What the member was called.
≥ 1 chars

emailstring · email

Required
The member's address.

rolestring · enum

Required
The role the member held.
ownermanagerstaff

methodstring · enum

Required
cash — taken into the drawer. Settled by definition: nothing to capture, nothing that can later fail.
card — captured through the PSP. Recorded here as what the terminal reported, not as proof of settlement.
voucher — a gift card or credit note redeemed against the sale.
account — put on a customer's account to settle later. Requires the sale to name the customer (customer_id) and the merchant to have an open customer account for them; the till chooses the account at the tender and links the sale to its customer (retail: customer accounts).
A loyalty redemption is not a payment method any more: a reward redeems against its discount definition, the order line carries the discount, and the server spends the guest's points when the order is written. The points method was retired.
external — money a channel took before the order reached the venue: an online storefront, a delivery platform. The merchant settles with that channel, so the tender records the platform's reference rather than a card payment this merchant never captured. Only valid on an order a channel wrote, and the reference is required.
cashcardvoucheraccountexternal

pinstring
A voucher's PIN — the scratch-off second factor that proves possession of the card whose code is in reference (gift cards item 20). Required only when the card carries a PIN (a pre-printed or merchant-supplied code); a card with a generated code needs none, and the server refuses a sale whose voucher cannot prove the PIN. Only the hash is stored and compared; the plaintext never comes back.
≤ 12 chars

referencestring
The PSP's identifier for a card payment, or a voucher's code. Cash has neither and needs neither. Required for an external tender: it is the platform's own transaction or order reference, which is what reconciliation against that channel relies on.
≤ 128 chars

tipMoney

Nullable
The part of amount that is a gratuity rather than payment for goods.
Present because hospitality is not an edge case here: a bar or restaurant tab is the core flow, and a till that cannot record a tip cannot be used in one.

amountinteger · int64

Required
The amount, as a whole number of the currency's minor unit. May be negative to express a refund, discount or credit.

currencyCurrency

Required
ISO 4217 currency code.
Determines the minor unit that Money.amount is expressed in. Zero-decimal currencies such as JPY have a minor unit equal to the major unit.
One of 182 values; see the schema.

previous_hashstring
The hash of the fact this device recorded before this one, so a device's facts are one chain: SHA-256 over that fact's canonical form — the fact as sent, less its signature, in RFC 8785's JSON Canonicalization Scheme — in base64url without padding. Absent on a device's first fact. A fact that does not follow the one before it is recorded, and flagged chain_broken.
pattern ^[A-Za-z0-9_-]{43}$

refundOrderFactRefund

Money given back against a completed order. A refund is a new ledger entry: the sale stays completed, and this is the record of the money returning. It is applied against the order as the server holds it, and a refund the server cannot apply — more than was paid, a sale since voided — is kept and flagged for a person rather than refused.
A blind return, which has no sale behind it, is not a fact about an order and is written through orders/batch-refund.

idstring · uuid

Required
The refund id, minted by the device, which is what finds the refund again when the fact is sent twice.

approved_by_memberMemberSnapshot

A member of the team as whoever recorded it knew them when it happened: who they were, what they were called and how to reach them, and the role they held. A fact keeps all of it, so a later rename, new address or change of role restates nothing it says.

idstring · uuid

Required
The roster's id, checked against the merchant's memberships.

namestring

Required
What the member was called.
≥ 1 chars

emailstring · email

Required
The member's address.

rolestring · enum

Required
The role the member held.
ownermanagerstaff

destinationstring · enum
Where the refunded value went. store_credit issues a gift card for it.
moneystore_credit
default money

drawer_session_idstring · uuid
The drawer session a cash refund took money out of. Omitted when no cash went back.

exchange_replacement_order_idstring · uuid
The replacement sale this refund exchanges into (retail item 6). If it has not reached the server when the refund is applied, the refund is applied and the pairing flagged.

line_itemsarray of RefundLineItem

The lines returned and how much of each. Absent means the whole sale.

line_idstring · uuid

Required

quantityQuantity
How much of something, as a decimal string in the unit_of_measure beside it (each where there is none), as Square's quantity is: three croissants are "3", 1.4 kg of beans is "1.4". A string because a JSON number is a binary float to most parsers.
It has at most as many decimal places as its unit's base unit holds — three in each, g and ml, six in kg and l — and a finer one is refused, never rounded. Tenvelo holds every quantity as an integer of that base unit (thousandths of an each, milligrams, microlitres; docs/decisions/0063); a client that computes with one should read the digits the same way, never through a float.
≤ 26 chars · pattern ^-?(0|[1-9][0-9]*)(\.[0-9]{1,6})?$

unit_of_measurestring · enum
The unit quantity is in. It must measure what the line does, or the refund is refused. Absent means each.
eachkgglml

notestring
≤ 512 chars

paymentsarray of RefundPayment

How the money went back. Required for a money refund; absent for a store_credit one, which issues a gift card instead.
≤ 10 items

idstring · uuid

Required

amountMoney

Required
A monetary amount in a specific currency: Square's Money, and Stripe's amount beside its currency.
The amount is always an integer count of the currency's minor unit — pence for GBP, cents for USD. Zero-decimal currencies such as JPY have a minor unit equal to their major unit, so {"amount": 500, "currency": "JPY"} is ¥500 while {"amount": 500, "currency": "GBP"} is £5.00.
Floating point is never used for money anywhere in this API. Binary floats cannot represent most decimal fractions exactly, so accumulating them across the line items of an order produces totals that disagree with the printed receipt by a penny. Integer minor units make every arithmetic operation exact.

amountinteger · int64

Required
The amount, as a whole number of the currency's minor unit. May be negative to express a refund, discount or credit.

currencyCurrency

Required
ISO 4217 currency code.
Determines the minor unit that Money.amount is expressed in. Zero-decimal currencies such as JPY have a minor unit equal to the major unit.
One of 182 values; see the schema.

methodstring · enum

Required
cashcardvoucheraccountpoints

payment_idstring · uuid
The original payment this refund reverses. Null for a cash refund, which has no payment to point at.

referencestring
The card's code on a voucher refund, so the value returns to the card it came from. Omitted for cash and card refunds.

reasonstring

Required
Why the money went back, in the staff member's words.
≤ 512 chars

restockboolean
Whether the returned items went back into sellable stock.
default false

statutoryboolean
Whether this refund is the law's: faulty goods or goods not as described, where the money goes back to the payer (decision 0073). A statutory refund is never store_credit.
default false

store_credit_codestring
The code of the gift card a store_credit refund issues, as the till printed it. Required when destination is store_credit.

signaturestring
The device's signature over this fact's canonical form, with the key it enrolled: a detached JWS (RFC 7515 Appendix F) in compact form, header..signature. Its protected header is alg ES256, kid the key's RFC 7638 thumbprint, and typ fact-seal (RFC 8725 §3.11); its signature is the 64-byte r‖s in base64url without padding (RFC 7518 §3.4); its payload is the canonical form, which the fact itself carries, so any JOSE library verifies it given those bytes. A signature no key the device has held made is recorded, and flagged seal_broken. The canonical form is only defined for I-JSON (RFC 7493), so a sealed fact that names a field twice, or twice but for case, or carries a number beyond ±(2^53−1), is recorded and flagged seal_ambiguous. A fact with neither this nor previous_hash is not in a chain, and is not flagged for it.
pattern ^[A-Za-z0-9_-]{16,500}\.\.[A-Za-z0-9_-]{86}$

updateOrderFactUpdate

A change to what an order is labelled with, as a JSON Merge Patch (RFC 7396): a field present is set, a field set to null is cleared, a field absent is left alone. These are the one thing about an order that does not merge — two changes to one field race, and the later on the order's log wins — so money never travels here: lines, payments and voids are facts of their own.

namestring

Nullable
Whose order it is while it is open; null to clear it.
≤ 128 chars

coversinteger · int32
How many people the party turned out to be; zero if nobody counted after all. A recount is a correction to what was said at seating, not a second statement of it.
0–1000

customer_idstring · uuid

Nullable
The guest the order is now recorded against; null to unlink one. On a completed order this is not how a guest is changed: that is a void and a new sale.

delivery_addressAddress

Nullable
Where a delivery order goes, as the writer corrects it; null to clear it.

address_line_1string

Required
First line of the address — street number, street name, building name.
≤ 255 chars

address_line_2string
Second line of the address, if any.
≤ 255 chars

address_line_3string
Third line of the address, if any.
≤ 255 chars

administrative_district_level_1string
A civil entity within the country. The state in the US; the county in the UK.
≤ 128 chars

administrative_district_level_2string
A civil entity within administrative_district_level_1.
≤ 128 chars

countryCountry

Required
ISO 3166-1 alpha-2 country code.
ZZ is the unknown/unspecified placeholder.
One of 250 values; see the schema.

localitystring
The city or town.
≤ 128 chars

postal_codestring
The postal or ZIP code.
≤ 32 chars

sublocalitystring
A civil region within the locality, if any.
≤ 128 chars

email_receiptboolean

Nullable
Whether the guest now wants the receipt by email; false or null turns it off. Nullable so that turning it off is a value a patch carries, not one it drops.

external_referencestring

Nullable
The writer's own reference for the order, changed here; null to clear it.
≤ 128 chars

fulfillment_typestring · enum
How the order now leaves the building — a table's order turned takeaway.
on_premisespickupdelivery

owner_memberMemberSnapshot

A member of the team as whoever recorded it knew them when it happened: who they were, what they were called and how to reach them, and the role they held. A fact keeps all of it, so a later rename, new address or change of role restates nothing it says.

idstring · uuid

Required
The roster's id, checked against the merchant's memberships.

namestring

Required
What the member was called.
≥ 1 chars

emailstring · email

Required
The member's address.

rolestring · enum

Required
The role the member held.
ownermanagerstaff

table_idstring · uuid

Nullable
The table the order is moved to; null when it leaves a table.

voidOrderFactVoid

A completed order reversed. It is kept, voided, rather than deleted: a merchant, and later a regulator, needs to see that a sale happened and was reversed, not that it never existed.

approved_by_memberMemberSnapshot

A member of the team as whoever recorded it knew them when it happened: who they were, what they were called and how to reach them, and the role they held. A fact keeps all of it, so a later rename, new address or change of role restates nothing it says.

idstring · uuid

Required
The roster's id, checked against the merchant's memberships.

namestring

Required
What the member was called.
≥ 1 chars

emailstring · email

Required
The member's address.

rolestring · enum

Required
The role the member held.
ownermanagerstaff

notestring
What happened, in the staff member's words. Required when reason is other.
≤ 512 chars

reasonstring · enum

Required
Why the sale was reversed, kept apart from what the reversal did.
customer_canceledstaff_errorrefundother
Responses

202
Every item was read. results says, per item, whether its fact was received — in the log, and applied later — or failed as malformed.

OrderFactBatchResponse · application/json

resultsarray of OrderFactResult

Required

idstring · uuid
The fact's own id, echoed, so a result can be matched by id as well as position. Absent only when the item named no readable id, which is the one case position is the only match there is.

order_idstring · uuid
The order the fact is about, whose state is read at GET /v1/orders/{id}. The fact itself is not a resource there.

problemProblem

Nullable
Why the item failed, as an RFC 9457 problem. Null when it was received.

typestring · uri

Required
A stable URI identifying the problem kind. This is the field to branch on.
default about:blank

api_versionstring
Present on an api-version-retired or api-version-unknown refusal: the API-Version this server speaks (docs/decisions/0011).

detailstring
A human-readable explanation specific to this occurrence. Safe to show to a developer; never contains internal state, SQL, or stack traces.

instancestring · uri-reference
A URI reference identifying the specific occurrence.

invalid_paramsarray of InvalidParam

Present on 422 responses. Lists every field that failed validation, rather than only the first, so a client can highlight an entire form in one pass.

codestring
Stable machine-readable code for this failure, for clients that localise their own messages rather than showing reason.

pointerstring

Required
RFC 6901 JSON Pointer to the offending value within the request body. A pointer rather than a field name so that failures nested inside arrays — the third line item of an order — are addressable at all.

reasonstring

Required
Why this value was rejected, in human-readable form.

refusalsarray of Location refusal

Present on 409 responses to a withdrawal refused by the state it depends on (deleting a location with tills still assigned, open orders, …). Lists every reason at once, each with how much stands in the way, so a client can say what to put right and link to it rather than walking a person through one refusal after another.

kindstring

Required
A stable refusal kind — devices, open_orders, drawer_sessions, bookings or stock — that a client links to the screen that puts it right. Branch on this field, never on the surrounding prose.

countinteger

Required
How many things stand in the way of the withdrawal, so a client can repeat the number rather than re-read prose.
≥ 1

statusinteger

Required
The HTTP status code, repeated here so the body is self-contained.
100–599

titlestring

Required
A short, human-readable summary of the problem kind.

trace_idstring
The OpenTelemetry trace id for this request. Quote it in a support ticket and the whole request can be pulled up.

statusstring · enum

Required
received — the fact is in its order's log, whether it arrived now or before: a device clears it from its queue, and learns what it made of the order from the feed. Adyen answers an asynchronous modification with the same word.
failed — the item was malformed and nothing was recorded. See problem: a 422 will never succeed and is a defect in the client that sent it; a 5xx is worth sending again.
receivedfailed

settled_throughinteger · int64

Nullable
How far this device is settled: the highest device_seq of its facts that have been applied to their orders, with no gap below it. A cumulative acknowledgment, as TCP's is — it covers every fact at or below it, however many batches ago they were sent, and it only moves forward.
received says a fact cannot be lost; this says it has become part of its order. A device keeps its own copy of everything above this as the record, and what is at or below it as a cache it may evict — so a till holding anything unsettled must not be reset, re-paired or retired.
It lags the answer it rides on: facts are applied after they are received, so the batch just sent is rarely covered by the number returned with it. Null for a client that is not a device.
≥ 0

400
The request could not be parsed. Malformed JSON, a bad query parameter, or a header that failed to decode, among them an API-Version later than the server speaks or not a date (api-version-unknown, with the server's own in api_version).
Distinct from 422: a 400 never reached validation, so invalid_params is absent. Retrying without changing the request will fail again, except that a request refused for its API-Version goes once the server is updated.

401
No credentials, or credentials that could not be verified — missing bearer token, malformed JWT, expired token, or a signature that failed against the issuer's JWKS.
Refresh the token and retry once. Repeated 401 after a refresh means the device needs to re-enrol.

403
Authenticated, but not permitted. The token is valid and its merchant was resolved, but the caller's role does not allow this operation, or the target belongs to a different merchant.
Cross-tenant access is reported as 403 on a resource the caller may not see, and as 404 where even confirming existence would leak information. Retrying will not help.

410
The request names an API-Version this server no longer serves (docs/decisions/0011). Nothing in it was read. api_version names the version the server speaks: the client is behind, and sends the request again once it is updated.

415
The request Content-Type is not supported. This API accepts application/json on all mutations.

422
The request parsed but failed validation.
invalid_params lists every failing field with a JSON Pointer, not just the first, so a client can mark up a whole form in one pass rather than making the user fix errors one round trip at a time.
Also returned when an Idempotency-Key is replayed with a different body, and when device-computed order totals disagree with the server's recomputation.

429
Rate limit exceeded. Honour Retry-After rather than applying your own backoff.
A fleet of tills coming back online together after an outage is the realistic cause, which is exactly when uncoordinated client-side retry turns a brief outage into a sustained one. The limit is per process, and per site for what records trade there — a request spends its site's budget, and a till's own smaller one inside it — and per (client, merchant) for everything else; no RateLimit field is sent, so this response and its Retry-After are the whole of the contract.

500
Something failed on our side. trace_id identifies the request in our tracing — quote it in a support ticket.
The body never carries internal detail: no SQL, no stack traces, no upstream error strings. Safe to retry with the same Idempotency-Key.

503
Temporarily unable to serve the request — a dependency is down or the service is shedding load.
Retry with the same Idempotency-Key after Retry-After. This is always safe: a request that did take effect before the failure will be recognised as a replay.
Request
curl -X POST 'https://api.tenvelo.com/v1/orders/batch-create' \ -H "Authorization: Bearer $TOKEN" \ -H 'Content-Type: application/json' \ -d '{ "items": [ { "id": "0192f1e4-7c3a-7b2e-9f10-5d6c7e8f9a0b", "type": "created", "acceptance": { "note": "string", "pickup_at": "2026-09-11T09:30:00Z", "rejection_reason": "sold_out" }, "cancellation": { "note": "string", "reason": "abandoned" }, "completion": { "age_confirmed": false, "age_minimum": 0, "document": { "kind": "invoice", "number": 148, "series": "B1-T3" }, "loyalty_hold_id": "0192f1e4-7c3a-7b2e-9f10-5d6c7e8f9a0b", "reference": "string", "service_charge": { "amount": 1250, "currency": "GBP" }, "service_charge_declined": false, "totals": { "cash_rounding": { "amount": 1250, "currency": "GBP" }, "discount_total": { "amount": 1250, "currency": "GBP" }, "service_charge": { "amount": 1250, "currency": "GBP" }, "service_charge_tax": { "amount": 1250, "currency": "GBP" }, "subtotal": { "amount": 1250, "currency": "GBP" }, "tax_total": { "amount": 1250, "currency": "GBP" }, "total": { "amount": 1250, "currency": "GBP" } } }, "device_seq": 1, "hlc": "117356101632000000", "line_item": { "id": "0192f1e4-7c3a-7b2e-9f10-5d6c7e8f9a0b", "name": "Flat white", "approved_by_member": { "id": "0192f1e4-7c3a-7b2e-9f10-5d6c7e8f9a0b", "name": "string", "email": "ada@example.com", "role": "owner" }, "category_id": "0192f1e4-7c3a-7b2e-9f10-5d6c7e8f9a0b", "category_name": "string", "comp_reason": "string", "course": 1, "discount": { "amount": 1250, "currency": "GBP" }, "discount_id": "0192f1e4-7c3a-7b2e-9f10-5d6c7e8f9a0b", "discount_name": "string", "gift_card_code": "string", "gift_card_token_hash": "string", "modifiers": [ { "id": "0192f1e4-7c3a-7b2e-9f10-5d6c7e8f9a0b", "name": "Oat milk", "price_delta": { "amount": 1250, "currency": "GBP" } } ], "multibuy": { "every": 2, "price": { "amount": 1250, "currency": "GBP" } }, "note": "string", "product_id": "0192f1e4-7c3a-7b2e-9f10-5d6c7e8f9a0b", "product_type": "standard", "quantity": "3", "seat": 1, "sent_at": "2026-09-11T09:30:00Z", "serials": [], "tax": { "amount": 1250, "currency": "GBP" }, "tax_breakdown": [ { "amount": { "amount": 1250, "currency": "GBP" }, "inclusive": false, "percentage": "20", "rate_id": "0192f1e4-7c3a-7b2e-9f10-5d6c7e8f9a0b" } ], "tax_inclusive": false, "tax_rate_percentage": "20", "total": { "amount": 1250, "currency": "GBP" }, "unit_of_measure": "each", "unit_price": { "amount": 1250, "currency": "GBP" }, "variant_id": "0192f1e4-7c3a-7b2e-9f10-5d6c7e8f9a0b" }, "line_item_void": { "approved_by_member": { "id": "0192f1e4-7c3a-7b2e-9f10-5d6c7e8f9a0b", "name": "string", "email": "ada@example.com", "role": "owner" }, "line_item_id": "0192f1e4-7c3a-7b2e-9f10-5d6c7e8f9a0b", "note": "string", "quantity": "3", "reason": "customer_changed_mind" }, "location_id": "0192f1e4-7c3a-7b2e-9f10-5d6c7e8f9a0b", "member": { "id": "0192f1e4-7c3a-7b2e-9f10-5d6c7e8f9a0b", "name": "string", "email": "ada@example.com", "role": "owner" }, "occurred_at": "2026-09-11T09:30:00Z", "order": { "name": "string", "covers": 0, "currency": "AED", "customer_id": "0192f1e4-7c3a-7b2e-9f10-5d6c7e8f9a0b", "delivery_address": { "address_line_1": "12 Bridge Street", "address_line_2": "string", "address_line_3": "string", "administrative_district_level_1": "Somerset", "administrative_district_level_2": "string", "country": "ZZ", "locality": "Bristol", "postal_code": "BS1 4ST", "sublocality": "string" }, "drawer_session_id": "0192f1e4-7c3a-7b2e-9f10-5d6c7e8f9a0b", "email_receipt": false, "external_reference": "string", "fulfillment_type": "on_premises", "location_id": "0192f1e4-7c3a-7b2e-9f10-5d6c7e8f9a0b", "owner_member": { "id": "0192f1e4-7c3a-7b2e-9f10-5d6c7e8f9a0b", "name": "string", "email": "ada@example.com", "role": "owner" }, "pickup_at": "2026-09-11T09:30:00Z", "table_id": "0192f1e4-7c3a-7b2e-9f10-5d6c7e8f9a0b" }, "order_id": "0192f1e4-7c3a-7b2e-9f10-5d6c7e8f9a0b", "payment": { "id": "0192f1e4-7c3a-7b2e-9f10-5d6c7e8f9a0b", "amount": { "amount": 1250, "currency": "GBP" }, "buyer_supplied": { "amount": 1250, "currency": "GBP" }, "gift_card_hold_id": "0192f1e4-7c3a-7b2e-9f10-5d6c7e8f9a0b", "line_ids": [ "0192f1e4-7c3a-7b2e-9f10-5d6c7e8f9a0b" ], "member": { "id": "0192f1e4-7c3a-7b2e-9f10-5d6c7e8f9a0b", "name": "string", "email": "ada@example.com", "role": "owner" }, "method": "cash", "pin": "string", "reference": "pspRef_8829301", "tip": { "amount": 1250, "currency": "GBP" } }, "previous_hash": "string", "refund": { "id": "0192f1e4-7c3a-7b2e-9f10-5d6c7e8f9a0b", "approved_by_member": { "id": "0192f1e4-7c3a-7b2e-9f10-5d6c7e8f9a0b", "name": "string", "email": "ada@example.com", "role": "owner" }, "destination": "money", "drawer_session_id": "0192f1e4-7c3a-7b2e-9f10-5d6c7e8f9a0b", "exchange_replacement_order_id": "0192f1e4-7c3a-7b2e-9f10-5d6c7e8f9a0b", "line_items": [ { "line_id": "0192f1e4-7c3a-7b2e-9f10-5d6c7e8f9a0b", "quantity": "3", "unit_of_measure": "each" } ], "note": "string", "payments": [ { "id": "0192f1e4-7c3a-7b2e-9f10-5d6c7e8f9a0b", "amount": { "amount": 1250, "currency": "GBP" }, "method": "cash", "payment_id": "0192f1e4-7c3a-7b2e-9f10-5d6c7e8f9a0b", "reference": "string" } ], "reason": "string", "restock": false, "statutory": false, "store_credit_code": "string" }, "signature": "string", "update": { "name": "string", "covers": 0, "customer_id": "0192f1e4-7c3a-7b2e-9f10-5d6c7e8f9a0b", "delivery_address": { "address_line_1": "12 Bridge Street", "address_line_2": "string", "address_line_3": "string", "administrative_district_level_1": "Somerset", "administrative_district_level_2": "string", "country": "ZZ", "locality": "Bristol", "postal_code": "BS1 4ST", "sublocality": "string" }, "email_receipt": false, "external_reference": "string", "fulfillment_type": "on_premises", "owner_member": { "id": "0192f1e4-7c3a-7b2e-9f10-5d6c7e8f9a0b", "name": "string", "email": "ada@example.com", "role": "owner" }, "table_id": "0192f1e4-7c3a-7b2e-9f10-5d6c7e8f9a0b" }, "void": { "approved_by_member": { "id": "0192f1e4-7c3a-7b2e-9f10-5d6c7e8f9a0b", "name": "string", "email": "ada@example.com", "role": "owner" }, "note": "string", "reason": "customer_canceled" } } ] }'
Response
{ "results": [ { "id": "0192f1e4-7c3a-7b2e-9f10-5d6c7e8f9a0b", "order_id": "0192f1e4-7c3a-7b2e-9f10-5d6c7e8f9a0b", "problem": { "type": "https://api.tenvelo.com/problems/version-conflict", "api_version": "2026-10-10", "detail": "The product has been modified since version 7 was read.", "instance": "/v1/products/0195f8c7-4a1e-7c3b-9f22-8d4e6a1b2c3d", "invalid_params": [ { "code": "minimum", "pointer": "/line_items/0/quantity", "reason": "must be greater than or equal to 1" } ], "refusals": [ { "kind": "devices", "count": 3 } ], "status": 412, "title": "Version conflict", "trace_id": "4bf92f3577b34da6a3ce929d0e0e4736" }, "status": "received" } ], "settled_through": 0 }
POST/v1/orders/batch-refund

Refund orders

No. batchRefundOrdersAuth pos:orders:write
Refunds money on completed orders, each with the tenders that carry it back. A refund reaches the server through a till's queue like a sale does, so it is a batch; a batch of one refunds a single order.
A refund is a new ledger entry: it references the order and never edits it, so the sale stays completed and the refund is the record of the money going back. The server derives the refund total from the tenders and refuses one that would return more than was paid, or than remains after earlier refunds. Each item stands or falls on its own, exactly as in batchVoidOrders.
Request body application/json · OrderBatchRefundRequest

itemsarray of OrderBatchRefundItem

Required
≥ 1 items · ≤ 500 items

idstring · uuid

Required
The refund id. Minted by the device so a retry cannot create a second refund.

kindstring · enum
Whether this reverses a sale (the default) or is a blind return of goods with no original sale (retail item 8). A blind return is priced from the product and goes to store credit, never to cash.
refundblind_return
default refund

approved_by_memberMemberSnapshot

A member of the team as whoever recorded it knew them when it happened: who they were, what they were called and how to reach them, and the role they held. A fact keeps all of it, so a later rename, new address or change of role restates nothing it says.

idstring · uuid

Required
The roster's id, checked against the merchant's memberships.

namestring

Required
What the member was called.
≥ 1 chars

emailstring · email

Required
The member's address.

rolestring · enum

Required
The role the member held.
ownermanagerstaff

blind_priceMoney

A monetary amount in a specific currency: Square's Money, and Stripe's amount beside its currency.
The amount is always an integer count of the currency's minor unit — pence for GBP, cents for USD. Zero-decimal currencies such as JPY have a minor unit equal to their major unit, so {"amount": 500, "currency": "JPY"} is ¥500 while {"amount": 500, "currency": "GBP"} is £5.00.
Floating point is never used for money anywhere in this API. Binary floats cannot represent most decimal fractions exactly, so accumulating them across the line items of an order produces totals that disagree with the printed receipt by a penny. Integer minor units make every arithmetic operation exact.

amountinteger · int64

Required
The amount, as a whole number of the currency's minor unit. May be negative to express a refund, discount or credit.

currencyCurrency

Required
ISO 4217 currency code.
Determines the minor unit that Money.amount is expressed in. Zero-decimal currencies such as JPY have a minor unit equal to the major unit.
One of 182 values; see the schema.

blind_product_idstring · uuid
The product a blind return is for. Required when kind is blind_return.

blind_quantityQuantity
How much of something, as a decimal string in the unit_of_measure beside it (each where there is none), as Square's quantity is: three croissants are "3", 1.4 kg of beans is "1.4". A string because a JSON number is a binary float to most parsers.
It has at most as many decimal places as its unit's base unit holds — three in each, g and ml, six in kg and l — and a finer one is refused, never rounded. Tenvelo holds every quantity as an integer of that base unit (thousandths of an each, milligrams, microlitres; docs/decisions/0063); a client that computes with one should read the digits the same way, never through a float.
≤ 26 chars · pattern ^-?(0|[1-9][0-9]*)(\.[0-9]{1,6})?$

blind_unit_of_measurestring · enum
The unit blind_quantity is in. It must measure what the product does, or the return is refused. Absent means each.
eachkgglml

destinationstring · enum
Where the refunded value goes (retail item 9). money is the default; store_credit issues a gift card for the amount instead, so a shop can accept a return it must not pay cash for.
moneystore_credit
default money

drawer_session_idstring · uuid
The drawer session a cash refund took money out of. A till records it so the drawer's expected cash accounts for the cash that went back out; a card or gift-card refund never touches the drawer and omits it.

exchange_replacement_order_idstring · uuid
The replacement sale this refund exchanges into (retail item 6). When present, the server records the exchange pairing — original sale, refund and replacement — in the same transaction as the refund, so the ledger shows one exchange event rather than two unrelated ones. The replacement must already be a completed sale of this merchant's; if it has not reached the server yet (a till that was offline queues both), the refund is refused with a 409 and retried once it has.

hlcHLC
A hybrid logical clock stamp (Kulkarni et al., 2014): the recorder's wall clock in milliseconds in the high 48 bits and a counter in the low 16, a 64-bit integer written as its decimal digits in a string. A stamp is past 2^53, beyond the integers a JSON number holds exactly as most parsers read it, so I-JSON writes it as a string (RFC 7493 §2.2).
A device stamps every fact it records, as it records it, after every stamp it has made or pulled — every change on the feed carries one — so a fact recorded after seeing another ranks after it whatever either wall clock says. The stamp is when the fact happened. The server keeps it unless it is more than ten minutes ahead of the server's clock, more than thirty days behind it, or from before the device was paired. A fact is never refused for its stamp: one the server does not believe, cannot read or was not given is stamped as the server takes it, and flagged on what it dates — the order, the shift, the drawer or the shelf.

idempotency_keyItemIdempotencyKey

Required
A key for one item in a batch, minted by the client when it queues the item and reused on every attempt to send it. The item, not the request, is the unit of work: a retried batch returns the stored result for every item already applied under its key. A fresh key per attempt defeats the whole mechanism.
Scoped per merchant, so keys need only be unique within a merchant's own traffic.
16–255 chars

line_itemsarray of RefundLineItem

The lines being returned and how much of each. Absent means the whole sale is refunded; present means a line-level refund for exactly these lines, whole or by a partial quantity.

line_idstring · uuid

Required

quantityQuantity
How much of something, as a decimal string in the unit_of_measure beside it (each where there is none), as Square's quantity is: three croissants are "3", 1.4 kg of beans is "1.4". A string because a JSON number is a binary float to most parsers.
It has at most as many decimal places as its unit's base unit holds — three in each, g and ml, six in kg and l — and a finer one is refused, never rounded. Tenvelo holds every quantity as an integer of that base unit (thousandths of an each, milligrams, microlitres; docs/decisions/0063); a client that computes with one should read the digits the same way, never through a float.
≤ 26 chars · pattern ^-?(0|[1-9][0-9]*)(\.[0-9]{1,6})?$

unit_of_measurestring · enum
The unit quantity is in. It must measure what the line does, or the refund is refused. Absent means each.
eachkgglml

memberMemberSnapshot

A member of the team as whoever recorded it knew them when it happened: who they were, what they were called and how to reach them, and the role they held. A fact keeps all of it, so a later rename, new address or change of role restates nothing it says.

idstring · uuid

Required
The roster's id, checked against the merchant's memberships.

namestring

Required
What the member was called.
≥ 1 chars

emailstring · email

Required
The member's address.

rolestring · enum

Required
The role the member held.
ownermanagerstaff

notestring
≤ 512 chars

order_idstring · uuid
The sale being refunded. Required for a refund kind; absent for a blind_return.

paymentsarray of RefundPayment

How the money goes back. Required for a money refund; absent (or empty) for a store_credit one, which issues a gift card instead.
≤ 10 items

idstring · uuid

Required

amountMoney

Required
A monetary amount in a specific currency: Square's Money, and Stripe's amount beside its currency.
The amount is always an integer count of the currency's minor unit — pence for GBP, cents for USD. Zero-decimal currencies such as JPY have a minor unit equal to their major unit, so {"amount": 500, "currency": "JPY"} is ¥500 while {"amount": 500, "currency": "GBP"} is £5.00.
Floating point is never used for money anywhere in this API. Binary floats cannot represent most decimal fractions exactly, so accumulating them across the line items of an order produces totals that disagree with the printed receipt by a penny. Integer minor units make every arithmetic operation exact.

amountinteger · int64

Required
The amount, as a whole number of the currency's minor unit. May be negative to express a refund, discount or credit.

currencyCurrency

Required
ISO 4217 currency code.
Determines the minor unit that Money.amount is expressed in. Zero-decimal currencies such as JPY have a minor unit equal to the major unit.
One of 182 values; see the schema.

methodstring · enum

Required
cashcardvoucheraccountpoints

payment_idstring · uuid
The original payment this refund reverses. Null for a cash refund, which has no payment to point at.

referencestring
The card's code on a voucher refund, so the value returns to the card it came from. Omitted for cash and card refunds.

reasonstring

Required
≤ 512 chars

refunded_atstring · date-time
What the device's own clock read when it performed the refund, kept as it said it. Nothing is decided by it: the refund is dated by its stamp (hlc).

restockboolean
Whether the returned items go back into sellable stock. A returned item that cannot be resold — a printed menu, a personalised item — is not restocked.
default false

statutoryboolean
Whether this refund is the law's: faulty goods or goods not as described, where the money goes back to the payer (retail item 9, decision 0073). Named by the merchant at the counter, recorded, never inferred. A statutory refund cannot be store_credit — a shop does not pay a statutory refund in credit — and a blind_return is never statutory, because it has no sale behind it.
default false

store_credit_codestring
The code of the gift card a store_credit refund issues. Required when destination is store_credit; the till prints it at the counter.
Responses

200
The batch was processed. results says what happened to each item.

BatchResponse · application/json

resultsarray of BatchResult

Required

idstring · uuid
The resource the item created or changed. Absent when it failed.

idempotency_keystring

Required
The item's key, echoed so a result can be matched by key as well as position.

problemProblem

Nullable
Why the item failed, as an RFC 9457 problem. A 422 means the item is malformed and will never succeed — drop it and show it to staff rather than retrying for ever. A 409 or a 5xx means try again later.

typestring · uri

Required
A stable URI identifying the problem kind. This is the field to branch on.
default about:blank

api_versionstring
Present on an api-version-retired or api-version-unknown refusal: the API-Version this server speaks (docs/decisions/0011).

detailstring
A human-readable explanation specific to this occurrence. Safe to show to a developer; never contains internal state, SQL, or stack traces.

instancestring · uri-reference
A URI reference identifying the specific occurrence.

invalid_paramsarray of InvalidParam

Present on 422 responses. Lists every field that failed validation, rather than only the first, so a client can highlight an entire form in one pass.

codestring
Stable machine-readable code for this failure, for clients that localise their own messages rather than showing reason.

pointerstring

Required
RFC 6901 JSON Pointer to the offending value within the request body. A pointer rather than a field name so that failures nested inside arrays — the third line item of an order — are addressable at all.

reasonstring

Required
Why this value was rejected, in human-readable form.

refusalsarray of Location refusal

Present on 409 responses to a withdrawal refused by the state it depends on (deleting a location with tills still assigned, open orders, …). Lists every reason at once, each with how much stands in the way, so a client can say what to put right and link to it rather than walking a person through one refusal after another.

kindstring

Required
A stable refusal kind — devices, open_orders, drawer_sessions, bookings or stock — that a client links to the screen that puts it right. Branch on this field, never on the surrounding prose.

countinteger

Required
How many things stand in the way of the withdrawal, so a client can repeat the number rather than re-read prose.
≥ 1

statusinteger

Required
The HTTP status code, repeated here so the body is self-contained.
100–599

titlestring

Required
A short, human-readable summary of the problem kind.

trace_idstring
The OpenTelemetry trace id for this request. Quote it in a support ticket and the whole request can be pulled up.

statusstring · enum

Required
created — the item made a new resource. updated — it changed an existing one.
unchanged — this key was already applied and the original outcome stands. A success, not an error: it is what a client retrying a batch it was unsure landed should expect, and it clears the item from its queue exactly as created does.
failed — the item was refused, and nothing else in the batch was affected. See problem.
createdupdatedunchangedfailed

versioninteger · int64
The resource's version after the item. Absent when it failed.

400
The request could not be parsed. Malformed JSON, a bad query parameter, or a header that failed to decode, among them an API-Version later than the server speaks or not a date (api-version-unknown, with the server's own in api_version).
Distinct from 422: a 400 never reached validation, so invalid_params is absent. Retrying without changing the request will fail again, except that a request refused for its API-Version goes once the server is updated.

401
No credentials, or credentials that could not be verified — missing bearer token, malformed JWT, expired token, or a signature that failed against the issuer's JWKS.
Refresh the token and retry once. Repeated 401 after a refresh means the device needs to re-enrol.

403
Authenticated, but not permitted. The token is valid and its merchant was resolved, but the caller's role does not allow this operation, or the target belongs to a different merchant.
Cross-tenant access is reported as 403 on a resource the caller may not see, and as 404 where even confirming existence would leak information. Retrying will not help.

410
The request names an API-Version this server no longer serves (docs/decisions/0011). Nothing in it was read. api_version names the version the server speaks: the client is behind, and sends the request again once it is updated.

415
The request Content-Type is not supported. This API accepts application/json on all mutations.

422
The request parsed but failed validation.
invalid_params lists every failing field with a JSON Pointer, not just the first, so a client can mark up a whole form in one pass rather than making the user fix errors one round trip at a time.
Also returned when an Idempotency-Key is replayed with a different body, and when device-computed order totals disagree with the server's recomputation.

429
Rate limit exceeded. Honour Retry-After rather than applying your own backoff.
A fleet of tills coming back online together after an outage is the realistic cause, which is exactly when uncoordinated client-side retry turns a brief outage into a sustained one. The limit is per process, and per site for what records trade there — a request spends its site's budget, and a till's own smaller one inside it — and per (client, merchant) for everything else; no RateLimit field is sent, so this response and its Retry-After are the whole of the contract.

500
Something failed on our side. trace_id identifies the request in our tracing — quote it in a support ticket.
The body never carries internal detail: no SQL, no stack traces, no upstream error strings. Safe to retry with the same Idempotency-Key.

503
Temporarily unable to serve the request — a dependency is down or the service is shedding load.
Retry with the same Idempotency-Key after Retry-After. This is always safe: a request that did take effect before the failure will be recognised as a replay.
Request
curl -X POST 'https://api.tenvelo.com/v1/orders/batch-refund' \ -H "Authorization: Bearer $TOKEN" \ -H 'Content-Type: application/json' \ -d '{ "items": [ { "id": "0192f1e4-7c3a-7b2e-9f10-5d6c7e8f9a0b", "kind": "refund", "approved_by_member": { "id": "0192f1e4-7c3a-7b2e-9f10-5d6c7e8f9a0b", "name": "string", "email": "ada@example.com", "role": "owner" }, "blind_price": { "amount": 1250, "currency": "GBP" }, "blind_product_id": "0192f1e4-7c3a-7b2e-9f10-5d6c7e8f9a0b", "blind_quantity": "3", "blind_unit_of_measure": "each", "destination": "money", "drawer_session_id": "0192f1e4-7c3a-7b2e-9f10-5d6c7e8f9a0b", "exchange_replacement_order_id": "0192f1e4-7c3a-7b2e-9f10-5d6c7e8f9a0b", "hlc": "117356101632000000", "idempotency_key": "01J8ZK3QF7X2N5V9C4B1A6D8E0", "line_items": [ { "line_id": "0192f1e4-7c3a-7b2e-9f10-5d6c7e8f9a0b", "quantity": "3", "unit_of_measure": "each" } ], "member": { "id": "0192f1e4-7c3a-7b2e-9f10-5d6c7e8f9a0b", "name": "string", "email": "ada@example.com", "role": "owner" }, "note": "string", "order_id": "0192f1e4-7c3a-7b2e-9f10-5d6c7e8f9a0b", "payments": [ { "id": "0192f1e4-7c3a-7b2e-9f10-5d6c7e8f9a0b", "amount": { "amount": 1250, "currency": "GBP" }, "method": "cash", "payment_id": "0192f1e4-7c3a-7b2e-9f10-5d6c7e8f9a0b", "reference": "string" } ], "reason": "string", "refunded_at": "2026-09-11T09:30:00Z", "restock": false, "statutory": false, "store_credit_code": "string" } ] }'
Response
{ "results": [ { "id": "0192f1e4-7c3a-7b2e-9f10-5d6c7e8f9a0b", "idempotency_key": "string", "problem": { "type": "https://api.tenvelo.com/problems/version-conflict", "api_version": "2026-10-10", "detail": "The product has been modified since version 7 was read.", "instance": "/v1/products/0195f8c7-4a1e-7c3b-9f22-8d4e6a1b2c3d", "invalid_params": [ { "code": "minimum", "pointer": "/line_items/0/quantity", "reason": "must be greater than or equal to 1" } ], "refusals": [ { "kind": "devices", "count": 3 } ], "status": 412, "title": "Version conflict", "trace_id": "4bf92f3577b34da6a3ce929d0e0e4736" }, "status": "created", "version": 0 } ] }
GET/v1/orders/{id}

Get an order

No. getOrderAuth pos:orders:write ordering:write
Returns a single order with its line items and totals.
Parameters

idpath · string · uuid
Required
UUIDv7 of the resource.
For resources a device can originate — orders, and their line items — this id is minted by the client before the record is ever synced, which is what makes an offline create idempotent.
Responses

200
The order.

Order · application/json

idstring · uuid

Required
UUIDv7, minted by the device before the sale is synced. This is what makes an offline order idempotent: replaying it targets the same id, so a retry over flaky wifi cannot create a duplicate sale.

namestring

Nullable
Whose sale it is, while it is open: a customer's name, whatever the shop shouts across the bar. Null is a walk-in being served at a counter right now.
≤ 128 chars

acceptancestring · enum

Read only
Where an asked-for order stands with the venue that must make it, beside its lifecycle: state keeps its four values. A till's own order is accepted as it is created; a channel's — the ordering page, an integration — is pending until a person or a rule takes it on, or it is rejected with a reason. Set by the server, never from the body: acceptance is a fact (engineering, recording what happened, section 12), not a field a client sets.
pendingacceptedrejected

age_confirmedboolean
Whether a sale carrying an age-restricted line recorded that the till confirmed the guest's age before it completed. False both for a sale with no age-restricted line and for one that needed the check and did not record it — the reports compare it with age_minimum to flag the second.
default false

age_minimuminteger · int32
The oldest buyer the sale's age-restricted lines allowed, as the till recorded it: the highest minimum_age among them, 0 when the sale carried none. A completed sale with age_minimum above 0 and age_confirmed false is a counter law miss.
≥ 0 · default 0

business_datestring · date

Read only
The trading day the sale belongs to, in its location's own reckoning: its time zone and the hour its day starts. Set by the server when the sale completes, from when the till says it happened, so a sale rung at 1am on a late night books to the night before. Absent on an order that has not completed.

channelstring · enum

Read only
Where the order came from, set by the server from the caller and never accepted from the body: pos is a till, table a table-side device, online an online storefront, integration a third-party integration. A till cannot attribute a sale to another channel. What the channel is tells an integration whose order arrived from where, which an order_type cannot.
postableonlineintegration

channel_costMoney

What the channel took from the order, at the stated cost in force on the order's business date (online-ordering item 18). Present only for an online order whose channel states a cost, and derived on read from the stated rates and the order's total — never stored, so it can never drift from them.

amountinteger · int64

Required
The amount, as a whole number of the currency's minor unit. May be negative to express a refund, discount or credit.

currencyCurrency

Required
ISO 4217 currency code.
Determines the minor unit that Money.amount is expressed in. Zero-decimal currencies such as JPY have a minor unit equal to the major unit.
One of 182 values; see the schema.

client_created_atstring · date-time

Required
When the device believes the sale happened. Trusted for display — it is what a receipt shows and what staff recognise — but never for ordering or for resolving conflicts, because till clocks drift. Compare with received_at to measure how long a device was offline.

closed_atstring · date-time

Nullable
When the order left open — was completed. A void does not change it; voided_at is when the sale was voided.

coversinteger · int32

RequiredRead only
How many people the party is, as counted at seating on the created fact; zero where nobody counted them. The covers-per-labour-hour and average-spend-per-cover figures are divided by it, so a tab opened without a count adds no covers rather than one.
0–1000 · default 0

created_atTimestamp

RequiredRead only
Server-assigned RFC 3339 timestamp, always UTC.
Server-assigned because device clocks drift and cannot be trusted for ordering — a till that has been powered off for a week may come back with a clock hours out. Where the device's own view of time matters it is carried separately in client_created_at.

currencyCurrency

Required
ISO 4217 currency code.
Determines the minor unit that Money.amount is expressed in. Zero-decimal currencies such as JPY have a minor unit equal to the major unit.
One of 182 values; see the schema.

customerCustomerLoyalty

This order's guest as a till may see them: name, loyalty balance and what it can afford. Carried on the order and its change-feed entry so a till that picks a tab up on another device shows the badge and offers a redemption without a second call. Absent for a walk-in and for a guest since erased or merged; customer_id remains the record. Additive: a client that predates it simply omits it.

idstring · uuid

Required

namestring

Required

loyalty_pointsinteger · int64
The guest's current loyalty balance, earned minus redeemed.

rewardsarray of Reward

The reward catalogue entries this guest can afford, so a till can offer them at redemption. Server-computed from the balance; a guest not enrolled sees none.

idstring · uuid

Required

namestring

Required
What the reward is called to the guest and on the receipt.

cost_pointsinteger · int64

Required
What redeeming it costs, in points.

discount_idstring · uuid

Required
The discount definition the reward is backed by.

tagsstring
The guest's labels, carried so a counter can offer them; still no contact details and no note.

tierLoyaltyTierStatus

A guest's standing in a loyalty programme's ladder at one moment (loyalty item 16): the tier they are on, the next tier above, and how much more they need to reach it.

currentLoyaltyTier

One named level in a loyalty programme's ladder (loyalty item 16). Exactly one of threshold_spend and threshold_visits is set; window_days is the rolling window over which the qualifying spend or visits are counted, and earn_rate_percentage is the multiplier on the programme's base earn rate (10000 is 1x).

idstring · uuid

Required

namestring

Required

earn_rate_percentageRelativePercentage
A percentage that may be negative or above 100, such as a change on a period before or a multiplier, in a decimal string with at most four decimal places: a fall of an eighth is "-12.5", and one and a half times is "150". Read and computed as a Percentage is, in parts per million.
pattern ^-?(0|[1-9][0-9]{0,8})(\.[0-9]{1,4})?$

threshold_spendMoney

A monetary amount in a specific currency: Square's Money, and Stripe's amount beside its currency.
The amount is always an integer count of the currency's minor unit — pence for GBP, cents for USD. Zero-decimal currencies such as JPY have a minor unit equal to their major unit, so {"amount": 500, "currency": "JPY"} is ¥500 while {"amount": 500, "currency": "GBP"} is £5.00.
Floating point is never used for money anywhere in this API. Binary floats cannot represent most decimal fractions exactly, so accumulating them across the line items of an order produces totals that disagree with the printed receipt by a penny. Integer minor units make every arithmetic operation exact.

amountinteger · int64

Required
The amount, as a whole number of the currency's minor unit. May be negative to express a refund, discount or credit.

currencyCurrency

Required
ISO 4217 currency code.
Determines the minor unit that Money.amount is expressed in. Zero-decimal currencies such as JPY have a minor unit equal to the major unit.
One of 182 values; see the schema.

threshold_visitsinteger · int64
The number of completed linked orders that reaches the tier.

window_daysinteger · int32

nextLoyaltyTier

One named level in a loyalty programme's ladder (loyalty item 16). Exactly one of threshold_spend and threshold_visits is set; window_days is the rolling window over which the qualifying spend or visits are counted, and earn_rate_percentage is the multiplier on the programme's base earn rate (10000 is 1x).

idstring · uuid

Required

namestring

Required

earn_rate_percentageRelativePercentage
A percentage that may be negative or above 100, such as a change on a period before or a multiplier, in a decimal string with at most four decimal places: a fall of an eighth is "-12.5", and one and a half times is "150". Read and computed as a Percentage is, in parts per million.
pattern ^-?(0|[1-9][0-9]{0,8})(\.[0-9]{1,4})?$

threshold_spendMoney

A monetary amount in a specific currency: Square's Money, and Stripe's amount beside its currency.
The amount is always an integer count of the currency's minor unit — pence for GBP, cents for USD. Zero-decimal currencies such as JPY have a minor unit equal to their major unit, so {"amount": 500, "currency": "JPY"} is ¥500 while {"amount": 500, "currency": "GBP"} is £5.00.
Floating point is never used for money anywhere in this API. Binary floats cannot represent most decimal fractions exactly, so accumulating them across the line items of an order produces totals that disagree with the printed receipt by a penny. Integer minor units make every arithmetic operation exact.

amountinteger · int64

Required
The amount, as a whole number of the currency's minor unit. May be negative to express a refund, discount or credit.

currencyCurrency

Required
ISO 4217 currency code.
Determines the minor unit that Money.amount is expressed in. Zero-decimal currencies such as JPY have a minor unit equal to the major unit.
One of 182 values; see the schema.

threshold_visitsinteger · int64
The number of completed linked orders that reaches the tier.

window_daysinteger · int32

spend_neededMoney

A monetary amount in a specific currency: Square's Money, and Stripe's amount beside its currency.
The amount is always an integer count of the currency's minor unit — pence for GBP, cents for USD. Zero-decimal currencies such as JPY have a minor unit equal to their major unit, so {"amount": 500, "currency": "JPY"} is ¥500 while {"amount": 500, "currency": "GBP"} is £5.00.
Floating point is never used for money anywhere in this API. Binary floats cannot represent most decimal fractions exactly, so accumulating them across the line items of an order produces totals that disagree with the printed receipt by a penny. Integer minor units make every arithmetic operation exact.

amountinteger · int64

Required
The amount, as a whole number of the currency's minor unit. May be negative to express a refund, discount or credit.

currencyCurrency

Required
ISO 4217 currency code.
Determines the minor unit that Money.amount is expressed in. Zero-decimal currencies such as JPY have a minor unit equal to the major unit.
One of 182 values; see the schema.

visits_neededinteger · int64
The visits still needed to reach next, when next is reached by visits.

versioninteger · int64

Required
The guest record's version, for the optimistic write a picker makes; it may be stale by the time the write lands, and the batch then refuses.

customer_idstring · uuid

Nullable
The guest this sale is recorded against, if any. Null for a walk-in.

delivery_addressAddress

Where a delivery order goes, as the writer stated it, when the order's fulfillment is delivery.

address_line_1string

Required
First line of the address — street number, street name, building name.
≤ 255 chars

address_line_2string
Second line of the address, if any.
≤ 255 chars

address_line_3string
Third line of the address, if any.
≤ 255 chars

administrative_district_level_1string
A civil entity within the country. The state in the US; the county in the UK.
≤ 128 chars

administrative_district_level_2string
A civil entity within administrative_district_level_1.
≤ 128 chars

countryCountry

Required
ISO 3166-1 alpha-2 country code.
ZZ is the unknown/unspecified placeholder.
One of 250 values; see the schema.

localitystring
The city or town.
≤ 128 chars

postal_codestring
The postal or ZIP code.
≤ 32 chars

sublocalitystring
A civil region within the locality, if any.
≤ 128 chars

delivery_feeMoney

Nullable
The venue's delivery charge on a delivered order (online-ordering: a shop may charge for delivery), snapshotted from its settings at write, or null when none. Part of the total; never folded into goods or their tax.

amountinteger · int64

Required
The amount, as a whole number of the currency's minor unit. May be negative to express a refund, discount or credit.

currencyCurrency

Required
ISO 4217 currency code.
Determines the minor unit that Money.amount is expressed in. Zero-decimal currencies such as JPY have a minor unit equal to the major unit.
One of 182 values; see the schema.

device_idstring · uuid
The till that last wrote the order. On an open order this is not ownership — any device at the location may pick a tab up, which is the entire point.

device_seqinteger · int64

Nullable
The device's monotonic sequence for this write, if the till recorded one.

documentOrderDocument

The fiscal document a completed order is recorded as, in the per-till series 0016 builds. Every sales document a till issues belongs to a series it was issued at enrolment, and the number is a gap-free counter in that series, incremented in the same transaction that completes the order. Printed on the receipt and sent with the order; the server stores it and refuses a duplicate (series, number).
This is the number a market's fiscal rules are about — the correlative number within a series. It is not the order's reference, which stays the short per-day call number for staff to find a sale.

kindstring · enum

Required
What the document is. invoice is the ordinary receipt — the simplified invoice most markets call a receipt. A full invoice and a rectifying document will be separate kinds, each in its own series.
invoice
default invoice

numberinteger · int64

Required
The gap-free sequence number within the series, starting at 1. Never reused: a void keeps its number, and a correction is a new document in a rectifying series.
≥ 1

seriesstring

Required
The series this document belongs to: a short code issued to one till at enrolment (e.g. B1-T3), one per device and kind of document. The ordinary receipt is in the invoice series.
≤ 32 chars

drawer_session_idstring · uuid

Nullable
The drawer session this sale was rung in, if any. Null otherwise.

email_receiptboolean
Whether the customer on this order asked for its receipt to be emailed. The address is always the customer record's — never typed onto the order, which is a financial record — and only honoured when the guest has consented. Additive, so a till that predates it simply omits it.
default false

external_referencestring

Read only
The writer's own reference for the order, when one was given.
≤ 128 chars

flagsarray of OrderFlagKind

Read only
The kinds of the flags still open on the order, which the books could not settle; absent when none is. Read beside the order as refunded is, and left out of the change feed.

fulfillment_statusstring · enum

Read only
Where an asked-for order has got to, for the guest and the venue: received until the venue takes it on, preparing once accepted, ready once said to be, collected once completed, or rejected or canceled. Derived from acceptance, ready_at and state when the order is read, never stored, so a client shows it rather than working it out again. Toast's fulfillmentStatus. Absent on a till's own sale, which is not asked for.
receivedpreparingreadycollectedrejectedcanceled

fulfillment_typestring · enum

Required
How the sale leaves the building, as the glossary names it and a tax rule is keyed by (docs/decisions/0014): on_premises is what the law calls eat-in, pickup is takeaway and delivery is delivery — Square's fulfillment type, Toast's dining option. A sale that does not say is on premises.
on_premisespickupdelivery

line_itemsarray of OrderLineItem

Required
What was sold. A completed order has at least one line; an open order may be empty for a moment, while the tab it is has just been started.

idstring · uuid

Required
UUIDv7, minted by the device.

namestring

Required
Product name as sold. Snapshot; never re-read from the product.
1–255 chars

approved_by_memberMemberSnapshot

Nullable
The manager or owner who authorised a staff member's discount or comp above the merchant's discount_approval_threshold_minor/discount_approval_threshold_percentage or a comp when comp_requires_manager is set, as they were then; null when no approval was needed.

idstring · uuid

Required
The roster's id, checked against the merchant's memberships.

namestring

Required
What the member was called.
≥ 1 chars

emailstring · email

Required
The member's address.

rolestring · enum

Required
The role the member held.
ownermanagerstaff

category_idstring · uuid

RequiredNullable
The category the product was filed under when the line was rung, for reporting. Snapshot: moving the product to another category later moves no sale. Null on an ad-hoc line or an uncategorised product.

category_namestring

Required
The category's name when the line was rung, so a report of past sales reads as they were filed. Snapshot; empty when category_id is null.
≤ 255 chars

comp_reasonstring
Why this line was given away. Present on a comp — an item given away at no charge — and means something different from a discount, so it is reported separately. Required when the line is a comp.
≤ 512 chars

courseinteger · int32

Nullable
The course this line belongs to, in a full-service kitchen — starters, mains, desserts. Set on the till when ringing to a course, and used to hold or fire a course from the till. Null for a single-course counter sale or a course-less line. Held courses are not sent (sent_at null) until they are fired.
≥ 1

discountMoney

A monetary amount in a specific currency: Square's Money, and Stripe's amount beside its currency.
The amount is always an integer count of the currency's minor unit — pence for GBP, cents for USD. Zero-decimal currencies such as JPY have a minor unit equal to their major unit, so {"amount": 500, "currency": "JPY"} is ¥500 while {"amount": 500, "currency": "GBP"} is £5.00.
Floating point is never used for money anywhere in this API. Binary floats cannot represent most decimal fractions exactly, so accumulating them across the line items of an order produces totals that disagree with the printed receipt by a penny. Integer minor units make every arithmetic operation exact.

amountinteger · int64

Required
The amount, as a whole number of the currency's minor unit. May be negative to express a refund, discount or credit.

currencyCurrency

Required
ISO 4217 currency code.
Determines the minor unit that Money.amount is expressed in. Zero-decimal currencies such as JPY have a minor unit equal to the major unit.
One of 182 values; see the schema.

discount_idstring · uuid

Nullable
The discount definition applied to this line, for reporting. Null for a line with no discount. Snapshot — the discount is recorded so its use can be attributed even if the definition later changes.

discount_namestring
The discount's name at the time the line was priced, snapshotted on the line — the reason a guest can be told, without re-resolving a definition that may have been renamed or deleted. Empty for a line with no discount.
≤ 200 chars

gift_card_codestring

Nullable
The code on the card being sold, when the line's product is a gift_card — typed or scanned at the till. The server issues the card (or refuses a code already live) when the order completes. Null for any other line.
≤ 64 chars

gift_card_token_hashstring

Nullable
The hash of the balance-page token for the card being sold: SHA-256 over the token's text, in base64url without padding. The device mints the token — 32 random bytes, unpadded base64url — and prints it on the receipt's balance link; only its hash leaves the device, so the token is never on the record of the sale, and the server checks a link by hashing the token it carries (W3C, "Good Practices for Capability URLs"). Absent leaves the card with no balance link until one is made (gift-card-balance-links). Null for any other line.
43–43 chars · pattern ^[A-Za-z0-9_-]{43}$

modifiersarray of OrderLineModifier

The options chosen on this line, snapshotted at the moment of sale. The line's unit_price already includes each option's delta.
The server checks only the shape of these — a negative delta is refused, an option chosen twice is refused — and never refuses a sale because the menu has changed since the till synced. A sale that was correct when rung stays correct.

idstring · uuid

Required
The modifier that was chosen. Kept for reporting, never re-resolved.

namestring

Required
Option name as sold. Snapshot.
1–255 chars

price_deltaMoney

Required
A monetary amount in a specific currency: Square's Money, and Stripe's amount beside its currency.
The amount is always an integer count of the currency's minor unit — pence for GBP, cents for USD. Zero-decimal currencies such as JPY have a minor unit equal to their major unit, so {"amount": 500, "currency": "JPY"} is ¥500 while {"amount": 500, "currency": "GBP"} is £5.00.
Floating point is never used for money anywhere in this API. Binary floats cannot represent most decimal fractions exactly, so accumulating them across the line items of an order produces totals that disagree with the printed receipt by a penny. Integer minor units make every arithmetic operation exact.

amountinteger · int64

Required
The amount, as a whole number of the currency's minor unit. May be negative to express a refund, discount or credit.

currencyCurrency

Required
ISO 4217 currency code.
Determines the minor unit that Money.amount is expressed in. Zero-decimal currencies such as JPY have a minor unit equal to the major unit.
One of 182 values; see the schema.

multibuyMultibuyRule

Nullable
The product's multibuy rule as it stood when the line was rung, snapshotted on the line so the server resolves the gross by the same deal the till did — re-pricing a product never rewrites a sale that was correct. Null on a line with no deal. A rule never applies to a weighed line.

everyinteger

Required
How many units make a run; 3 is the ordinary buy-two-get-one.
2–1000

priceMoney

Required
A monetary amount in a specific currency: Square's Money, and Stripe's amount beside its currency.
The amount is always an integer count of the currency's minor unit — pence for GBP, cents for USD. Zero-decimal currencies such as JPY have a minor unit equal to their major unit, so {"amount": 500, "currency": "JPY"} is ¥500 while {"amount": 500, "currency": "GBP"} is £5.00.
Floating point is never used for money anywhere in this API. Binary floats cannot represent most decimal fractions exactly, so accumulating them across the line items of an order produces totals that disagree with the printed receipt by a penny. Integer minor units make every arithmetic operation exact.

amountinteger · int64

Required
The amount, as a whole number of the currency's minor unit. May be negative to express a refund, discount or credit.

currencyCurrency

Required
ISO 4217 currency code.
Determines the minor unit that Money.amount is expressed in. Zero-decimal currencies such as JPY have a minor unit equal to the major unit.
One of 182 values; see the schema.

notestring
Free text from the till — "oat milk", "no sugar".
≤ 512 chars

originstring · enum

Read only
Where this line was rung from, as the server saw the writer: the till at the counter, a guest's phone on a tab, an ordering channel, an integration. It is the server's word and never the writer's, and it is how the share of a table's spend the table rang itself is told. Absent on a line recorded before origins were.
tillcustomeronlineintegration

product_idstring · uuid

Nullable
The catalogue product, for reporting. Null for an ad-hoc line — a miscellaneous item rung up at a custom price, which every real till needs.

product_typestring · enum

Required
What the product was when the line was rung: a gift_card sold is money taken for a promise, not revenue, and a combo is a set. Square's item_type. Snapshot, copied from the product at the moment of sale; standard on an ad-hoc line.
standardgift_cardcombo

quantityQuantity

Required
How much of something, as a decimal string in the unit_of_measure beside it (each where there is none), as Square's quantity is: three croissants are "3", 1.4 kg of beans is "1.4". A string because a JSON number is a binary float to most parsers.
It has at most as many decimal places as its unit's base unit holds — three in each, g and ml, six in kg and l — and a finer one is refused, never rounded. Tenvelo holds every quantity as an integer of that base unit (thousandths of an each, milligrams, microlitres; docs/decisions/0063); a client that computes with one should read the digits the same way, never through a float.
≤ 26 chars · pattern ^-?(0|[1-9][0-9]*)(\.[0-9]{1,6})?$

seatinteger · int32

Nullable
The seat this line is for, when a table's seats are numbered. Set on the till and carried to the kitchen and to split bills. Null for a counter sale or an unnumbered seat.
≥ 1

sent_atstring · date-time

Nullable
When this line was sent to the kitchen — set by the till when a tab is held or a sale completed, and immutable once set. A kitchen knows what to cook from the lines of a ticket, and a new round on a tab is a new set of sent_at values rather than the old lines re-sent. Null on a line the till has not yet held or completed.

serialsarray of string
The serial numbers of the units this line sold (retail item: serial numbers) — one per unit, in the order they were entered, printed on a product whose track_serial is set. Empty on any other line. A snapshot like the name and price: the record of which physical units left the shelf, so a specific unit sold is traceable to its sale.
default []

taxMoney

A monetary amount in a specific currency: Square's Money, and Stripe's amount beside its currency.
The amount is always an integer count of the currency's minor unit — pence for GBP, cents for USD. Zero-decimal currencies such as JPY have a minor unit equal to their major unit, so {"amount": 500, "currency": "JPY"} is ¥500 while {"amount": 500, "currency": "GBP"} is £5.00.
Floating point is never used for money anywhere in this API. Binary floats cannot represent most decimal fractions exactly, so accumulating them across the line items of an order produces totals that disagree with the printed receipt by a penny. Integer minor units make every arithmetic operation exact.

amountinteger · int64

Required
The amount, as a whole number of the currency's minor unit. May be negative to express a refund, discount or credit.

currencyCurrency

Required
ISO 4217 currency code.
Determines the minor unit that Money.amount is expressed in. Zero-decimal currencies such as JPY have a minor unit equal to the major unit.
One of 182 values; see the schema.

tax_breakdownarray of TaxBreakdownItem

Each rate's share of this line's tax, in the order its rule names the rates, when the line is taxed over several rates (each a separate calculation, each rounding with its own mode). Absent — null — on a line taxed at a single rate, where tax_rate_percentage and tax are the whole story.

amountMoney

Required
A monetary amount in a specific currency: Square's Money, and Stripe's amount beside its currency.
The amount is always an integer count of the currency's minor unit — pence for GBP, cents for USD. Zero-decimal currencies such as JPY have a minor unit equal to their major unit, so {"amount": 500, "currency": "JPY"} is ¥500 while {"amount": 500, "currency": "GBP"} is £5.00.
Floating point is never used for money anywhere in this API. Binary floats cannot represent most decimal fractions exactly, so accumulating them across the line items of an order produces totals that disagree with the printed receipt by a penny. Integer minor units make every arithmetic operation exact.

amountinteger · int64

Required
The amount, as a whole number of the currency's minor unit. May be negative to express a refund, discount or credit.

currencyCurrency

Required
ISO 4217 currency code.
Determines the minor unit that Money.amount is expressed in. Zero-decimal currencies such as JPY have a minor unit equal to the major unit.
One of 182 values; see the schema.

inclusiveboolean

Required
Whether this rate is inside the price (true) or added on top (false).

percentagePercentage

Required
A share of a whole, from "0" to "100", as a percentage in a decimal string with at most four decimal places, as Square's percentage and Stripe Tax's percentage_decimal are: UK VAT at 20% is "20", and an 8.875% US sales tax is "8.875".
A string because a JSON number is a binary float to most parsers, and a float cannot hold most decimal fractions exactly (RFC 7493 §2.2). Tenvelo computes with a percentage as an integer in parts per million ("8.875" is 88750), which every four-place percentage is exactly. A client that computes with one should read the digits the same way, never through a float.
pattern ^(100(\.0{1,4})?|(0|[1-9][0-9]?)(\.[0-9]{1,4})?)$

rate_idstring · uuid

Required
The rate this share belongs to.

tax_inclusiveboolean
Whether unit_price already contains the tax. Snapshot.

tax_rate_percentagePercentage
A share of a whole, from "0" to "100", as a percentage in a decimal string with at most four decimal places, as Square's percentage and Stripe Tax's percentage_decimal are: UK VAT at 20% is "20", and an 8.875% US sales tax is "8.875".
A string because a JSON number is a binary float to most parsers, and a float cannot hold most decimal fractions exactly (RFC 7493 §2.2). Tenvelo computes with a percentage as an integer in parts per million ("8.875" is 88750), which every four-place percentage is exactly. A client that computes with one should read the digits the same way, never through a float.
pattern ^(100(\.0{1,4})?|(0|[1-9][0-9]?)(\.[0-9]{1,4})?)$

totalMoney

Required
A monetary amount in a specific currency: Square's Money, and Stripe's amount beside its currency.
The amount is always an integer count of the currency's minor unit — pence for GBP, cents for USD. Zero-decimal currencies such as JPY have a minor unit equal to their major unit, so {"amount": 500, "currency": "JPY"} is ¥500 while {"amount": 500, "currency": "GBP"} is £5.00.
Floating point is never used for money anywhere in this API. Binary floats cannot represent most decimal fractions exactly, so accumulating them across the line items of an order produces totals that disagree with the printed receipt by a penny. Integer minor units make every arithmetic operation exact.

amountinteger · int64

Required
The amount, as a whole number of the currency's minor unit. May be negative to express a refund, discount or credit.

currencyCurrency

Required
ISO 4217 currency code.
Determines the minor unit that Money.amount is expressed in. Zero-decimal currencies such as JPY have a minor unit equal to the major unit.
One of 182 values; see the schema.

unit_of_measurestring · enum

Nullable
The unit this line was sold in, snapshotted from the product at the moment of sale (the product's own unit on a product line; any unit on an ad-hoc line). Absent means each.
eachkgglml

unit_priceMoney

Required
A monetary amount in a specific currency: Square's Money, and Stripe's amount beside its currency.
The amount is always an integer count of the currency's minor unit — pence for GBP, cents for USD. Zero-decimal currencies such as JPY have a minor unit equal to their major unit, so {"amount": 500, "currency": "JPY"} is ¥500 while {"amount": 500, "currency": "GBP"} is £5.00.
Floating point is never used for money anywhere in this API. Binary floats cannot represent most decimal fractions exactly, so accumulating them across the line items of an order produces totals that disagree with the printed receipt by a penny. Integer minor units make every arithmetic operation exact.

amountinteger · int64

Required
The amount, as a whole number of the currency's minor unit. May be negative to express a refund, discount or credit.

currencyCurrency

Required
ISO 4217 currency code.
Determines the minor unit that Money.amount is expressed in. Zero-decimal currencies such as JPY have a minor unit equal to the major unit.
One of 182 values; see the schema.

variant_idstring · uuid

Nullable
The variant that was sold, for reporting and stock. Null when the product itself is the sellable unit — a product with no variants, or with none picked. Like product_id, it is retained for reporting and never re-resolved: the descriptive and monetary fields on this line are the snapshot that is replayed, so a sale that was correct when rung stays correct even if the catalogue has changed since.

location_idstring · uuid

Required

loyalty_earnedinteger · int64

Read only
The points this sale earned its customer, recorded on the order.

loyalty_spentinteger · int64

Read only
The points this sale redeemed from its customer, recorded on the order.

memberMemberSnapshot

Nullable
The staff member who recorded this order — the person who rang it up — as they were then; nil when no person was attributed.

idstring · uuid

Required
The roster's id, checked against the merchant's memberships.

namestring

Required
What the member was called.
≥ 1 chars

emailstring · email

Required
The member's address.

rolestring · enum

Required
The role the member held.
ownermanagerstaff

merchant_idstring · uuid

RequiredRead only

owner_memberMemberSnapshot

Nullable
The staff member a tab belongs to — who opened it, and whom to ask when nobody has touched it. Checked against the merchant's memberships; nil for an order that was never a tab. Set once at open and only changed through a till's explicit transfer.

idstring · uuid

Required
The roster's id, checked against the merchant's memberships.

namestring

Required
What the member was called.
≥ 1 chars

emailstring · email

Required
The member's address.

rolestring · enum

Required
The role the member held.
ownermanagerstaff

paidMoney

A monetary amount in a specific currency: Square's Money, and Stripe's amount beside its currency.
The amount is always an integer count of the currency's minor unit — pence for GBP, cents for USD. Zero-decimal currencies such as JPY have a minor unit equal to their major unit, so {"amount": 500, "currency": "JPY"} is ¥500 while {"amount": 500, "currency": "GBP"} is £5.00.
Floating point is never used for money anywhere in this API. Binary floats cannot represent most decimal fractions exactly, so accumulating them across the line items of an order produces totals that disagree with the printed receipt by a penny. Integer minor units make every arithmetic operation exact.

amountinteger · int64

Required
The amount, as a whole number of the currency's minor unit. May be negative to express a refund, discount or credit.

currencyCurrency

Required
ISO 4217 currency code.
Determines the minor unit that Money.amount is expressed in. Zero-decimal currencies such as JPY have a minor unit equal to the major unit.
One of 182 values; see the schema.

paymentsarray of Payment

How the sale was paid for. Present on a completed order, and the thing that makes a day's takings reconcilable: an order that says completed without saying how it was paid records that something was sold and nothing about whether any money arrived.
An open order — a tab being split or part-paid — may also carry payments: a partial payment is appended while the tab stays open, and what remains is derived from the lines minus these payments and never stored. The server refuses a payment larger than what remains, and completes the order in the write whose payments cover the sale.

idstring · uuid
The payment's id. Minted by the device, so a retry of the same tender converges on the same row instead of recording the money twice; the server mints one when a writer does not supply it. A refund names it as payment_id, and a card refund is reversed against it, so it is returned with every read of the order and never renumbered.

amountMoney

Required
The total taken by this payment, including any tip.
Following Square: the tender's amount is what the customer parted with, and tip is the portion of it that is not for goods. Modelling it the other way — an amount that excludes the tip — means every reconciliation has to remember to add the two back together, and one place that forgets is a day's takings that do not balance.

amountinteger · int64

Required
The amount, as a whole number of the currency's minor unit. May be negative to express a refund, discount or credit.

currencyCurrency

Required
ISO 4217 currency code.
Determines the minor unit that Money.amount is expressed in. Zero-decimal currencies such as JPY have a minor unit equal to the major unit.
One of 182 values; see the schema.

buyer_suppliedMoney

Nullable
What the customer physically handed over. Cash only.
Recorded rather than assumed so that change is derived from it: a note tendered for a smaller sale is the ordinary case, and the drawer at close must agree with the sum of what went in.

amountinteger · int64

Required
The amount, as a whole number of the currency's minor unit. May be negative to express a refund, discount or credit.

currencyCurrency

Required
ISO 4217 currency code.
Determines the minor unit that Money.amount is expressed in. Zero-decimal currencies such as JPY have a minor unit equal to the major unit.
One of 182 values; see the schema.

card_brandstring

Read only
The scheme the processor read off the card, in its own words ("visa", "mastercard", "amex"). Card payments only; absent where the processor reports none.

card_confirmationstring · enum

Read only
How the card payment was confirmed against the checkout the processor says took it: confirmed when the approved checkout's amount matched and it belongs to this sale, unconfirmed when it is not approved, belongs to another sale, or took a different amount. An unconfirmed sale is still recorded — the money may already have moved — but the payment is flagged for a person to reconcile. The server's word, never the till's. Absent for a payment that is not a card, and for a card the till recorded by reference on a third-party terminal, which has no checkout to confirm against.
confirmedunconfirmed

card_last4string

Read only
The last four digits of the card that paid, as the processor masked them — what a payment shows as "Visa •• 4242", and what a person types into the order list's search to find the sale. Card payments only; absent where the processor reports none. Never the PAN.
≤ 4 chars

change_backMoney

NullableRead only
Change handed back, calculated by the server as buyer_supplied - amount and never accepted from a client.
Derived rather than submitted because it is the one figure a till could get wrong in a way that balances on screen and not in the drawer.

amountinteger · int64

Required
The amount, as a whole number of the currency's minor unit. May be negative to express a refund, discount or credit.

currencyCurrency

Required
ISO 4217 currency code.
Determines the minor unit that Money.amount is expressed in. Zero-decimal currencies such as JPY have a minor unit equal to the major unit.
One of 182 values; see the schema.

fingerprintstring

Read only
The processor's card-alias token, never the PAN, for a card payment it could identify. It is what lets a returning card be recognised without the card number. Card payments only; absent for cash and vouchers, and for a card payment the processor did not identify.
≤ 256 chars

gift_card_hold_idstring · uuid
The hold a till took on the voucher's card before tendering it (batchCreateGiftCardHolds), which this payment settles. Absent for a voucher tendered offline, which is spent against what the till last knew of the card.

line_idsarray of string · uuid
The lines this payment settled, when the till knows the split: a share pays whole lines, so a reopened tab shows the unpaid lines rather than a number, and a mistake cannot charge somebody twice (tabs item 13).
Empty when the payment named no lines — a whole-sale tender, an even split, a card share settling what is left, and every payment recorded before this existed. Empty and absent mean the same thing and are accepted alike, and a till sends the empty array.

memberMemberSnapshot

Nullable
The member who took this tender — the terminal operator who took the tip, not whoever rang the sale. The kept tip rule follows it. Absent for a payment recorded by something that is not a person.

idstring · uuid

Required
The roster's id, checked against the merchant's memberships.

namestring

Required
What the member was called.
≥ 1 chars

emailstring · email

Required
The member's address.

rolestring · enum

Required
The role the member held.
ownermanagerstaff

methodstring · enum

Required
cash — taken into the drawer. Settled by definition: nothing to capture, nothing that can later fail.
card — captured through the PSP. Recorded here as what the terminal reported, not as proof of settlement.
voucher — a gift card or credit note redeemed against the sale.
account — put on a customer's account to settle later. Requires the sale to name the customer (customer_id) and the merchant to have an open customer account for them; the till chooses the account at the tender and links the sale to its customer (retail: customer accounts).
A loyalty redemption is not a payment method any more: a reward redeems against its discount definition, the order line carries the discount, and the server spends the guest's points when the order is written. The points method was retired.
external — money a channel took before the order reached the venue: an online storefront, a delivery platform. The merchant settles with that channel, so the tender records the platform's reference rather than a card payment this merchant never captured. Only valid on an order a channel wrote, and the reference is required.
cashcardvoucheraccountexternal

pinstring
A voucher's PIN — the scratch-off second factor that proves possession of the card whose code is in reference (gift cards item 20). Required only when the card carries a PIN (a pre-printed or merchant-supplied code); a card with a generated code needs none, and the server refuses a sale whose voucher cannot prove the PIN. Only the hash is stored and compared; the plaintext never comes back.
≤ 12 chars

referencestring
The PSP's identifier for a card payment, or a voucher's code. Cash has neither and needs neither. Required for an external tender: it is the platform's own transaction or order reference, which is what reconciliation against that channel relies on.
≤ 128 chars

tipMoney

Nullable
The part of amount that is a gratuity rather than payment for goods.
Present because hospitality is not an edge case here: a bar or restaurant tab is the core flow, and a till that cannot record a tip cannot be used in one.

amountinteger · int64

Required
The amount, as a whole number of the currency's minor unit. May be negative to express a refund, discount or credit.

currencyCurrency

Required
ISO 4217 currency code.
Determines the minor unit that Money.amount is expressed in. Zero-decimal currencies such as JPY have a minor unit equal to the major unit.
One of 182 values; see the schema.

pickup_atstring · date-time

Read only
When the guest was told they could collect. Set by whoever took the order — the ordering page, or a till ringing a takeaway for collection at a time — and kept however the order is written afterwards: a later write that omits it leaves the promised time alone. Absent on an order nobody promised a time for.

ready_atstring · date-time

Read only
When the venue said an asked-for order was ready for the guest, recorded as a ready fact — the Ready button, the kitchen bumping the order's last ticket, or an integration. Absent until then, and again after a ready_undone takes it back. Read from the facts, never from whether the kitchen has any tickets for the order.

ready_to_pay_atstring · date-time

Read only
When a guest at the table said they were ready to pay (order-and-pay), on an open order. Absent until they tap; carried on the change feed as an order update, which is how the till shows the call.

received_atTimestamp

RequiredRead only
Server-assigned RFC 3339 timestamp, always UTC.
Server-assigned because device clocks drift and cannot be trusted for ordering — a till that has been powered off for a week may come back with a clock hours out. Where the device's own view of time matters it is carried separately in client_created_at.

referencestring
Short human-readable reference shown on the receipt and used by staff to find the order. Unique per location per business day.
≤ 64 chars

refundedMoney

A monetary amount in a specific currency: Square's Money, and Stripe's amount beside its currency.
The amount is always an integer count of the currency's minor unit — pence for GBP, cents for USD. Zero-decimal currencies such as JPY have a minor unit equal to their major unit, so {"amount": 500, "currency": "JPY"} is ¥500 while {"amount": 500, "currency": "GBP"} is £5.00.
Floating point is never used for money anywhere in this API. Binary floats cannot represent most decimal fractions exactly, so accumulating them across the line items of an order produces totals that disagree with the printed receipt by a penny. Integer minor units make every arithmetic operation exact.

amountinteger · int64

Required
The amount, as a whole number of the currency's minor unit. May be negative to express a refund, discount or credit.

currencyCurrency

Required
ISO 4217 currency code.
Determines the minor unit that Money.amount is expressed in. Zero-decimal currencies such as JPY have a minor unit equal to the major unit.
One of 182 values; see the schema.

rejection_notestring

Read only
The staff member's words, in their own voice, required when the reason is other.
≤ 512 chars

rejection_reasonstring · enum

Read only
Why an asked-for order was turned down, when it was. timed_out is the sweep that rejects an unanswered order past its location's deadline.
sold_outclosedtoo_busyothertimed_out

service_chargeMoney

Nullable
The discretionary service charge added to this bill (order-ledger item 9), in the order's currency, or null when none. Never folded into goods; part of the total payments must sum to.

amountinteger · int64

Required
The amount, as a whole number of the currency's minor unit. May be negative to express a refund, discount or credit.

currencyCurrency

Required
ISO 4217 currency code.
Determines the minor unit that Money.amount is expressed in. Zero-decimal currencies such as JPY have a minor unit equal to the major unit.
One of 182 values; see the schema.

service_charge_taxMoney

Nullable
The tax on the service charge, its own line and never folded into goods tax_total, or null when the charge is not taxed.

amountinteger · int64

Required
The amount, as a whole number of the currency's minor unit. May be negative to express a refund, discount or credit.

currencyCurrency

Required
ISO 4217 currency code.
Determines the minor unit that Money.amount is expressed in. Zero-decimal currencies such as JPY have a minor unit equal to the major unit.
One of 182 values; see the schema.

service_charge_tax_class_idstring · uuid

Nullable
The tax class the service charge was taxed under (decision record 0054), snapshotted from the location's config at write, or null when the charge is not taxed.

service_charge_tax_rate_percentagePercentage

Nullable
The combined tax rate that applied to the service charge, or null when not taxed.
pattern ^(100(\.0{1,4})?|(0|[1-9][0-9]?)(\.[0-9]{1,4})?)$

sourcestring

Read only
Which caller wrote the order — the device id for a pos or table order, storefront for one placed on a venue's ordering page, and the integration client id for an integration one. Set server-side from the caller, and an identifier's provenance, not a name.

source_namestring

Read only
The name the merchant gave the integration that wrote an integration order, as it was when the order was recorded; empty for any other channel.

statestring · enum

Required
open is a sale in progress, shared with the devices at its location. completed is finalised and immutable. canceled is an open order that ended without being paid. voided is a completed order reversed. Neither of the last two is deleted, so the audit trail survives.
opencompletedcanceledvoided

table_idstring · uuid

Nullable
The table an open order is parked on, if any. Occupancy is derived from this.

tipsMoney

A monetary amount in a specific currency: Square's Money, and Stripe's amount beside its currency.
The amount is always an integer count of the currency's minor unit — pence for GBP, cents for USD. Zero-decimal currencies such as JPY have a minor unit equal to their major unit, so {"amount": 500, "currency": "JPY"} is ¥500 while {"amount": 500, "currency": "GBP"} is £5.00.
Floating point is never used for money anywhere in this API. Binary floats cannot represent most decimal fractions exactly, so accumulating them across the line items of an order produces totals that disagree with the printed receipt by a penny. Integer minor units make every arithmetic operation exact.

amountinteger · int64

Required
The amount, as a whole number of the currency's minor unit. May be negative to express a refund, discount or credit.

currencyCurrency

Required
ISO 4217 currency code.
Determines the minor unit that Money.amount is expressed in. Zero-decimal currencies such as JPY have a minor unit equal to the major unit.
One of 182 values; see the schema.

totalsOrderTotals

Required
The money on an order, broken out.
These are computed and sent by the device, then independently recomputed by the server on receipt. A mismatch is rejected with 422 rather than quietly corrected: if the till printed a receipt showing one total and the server stored another, the merchant has an unreconcilable discrepancy and no way to know which is right. Failing loudly surfaces a till running stale tax configuration while it is still one order, not a month's worth.

cash_roundingMoney

Nullable
How much a cash settlement rounded the price, signed (docs/decisions/0015): a €10.02 bill rounded up to €10.05 has cash_rounding 3, and the cash payment's goods portion is the total plus this. The till computes it from the location's cash step; the server recomputes and rejects a mismatch. Zero on a sale no cash settles, and cards are never rounded.

amountinteger · int64

Required
The amount, as a whole number of the currency's minor unit. May be negative to express a refund, discount or credit.

currencyCurrency

Required
ISO 4217 currency code.
Determines the minor unit that Money.amount is expressed in. Zero-decimal currencies such as JPY have a minor unit equal to the major unit.
One of 182 values; see the schema.

discount_totalMoney

Required
A monetary amount in a specific currency: Square's Money, and Stripe's amount beside its currency.
The amount is always an integer count of the currency's minor unit — pence for GBP, cents for USD. Zero-decimal currencies such as JPY have a minor unit equal to their major unit, so {"amount": 500, "currency": "JPY"} is ¥500 while {"amount": 500, "currency": "GBP"} is £5.00.
Floating point is never used for money anywhere in this API. Binary floats cannot represent most decimal fractions exactly, so accumulating them across the line items of an order produces totals that disagree with the printed receipt by a penny. Integer minor units make every arithmetic operation exact.

amountinteger · int64

Required
The amount, as a whole number of the currency's minor unit. May be negative to express a refund, discount or credit.

currencyCurrency

Required
ISO 4217 currency code.
Determines the minor unit that Money.amount is expressed in. Zero-decimal currencies such as JPY have a minor unit equal to the major unit.
One of 182 values; see the schema.

service_chargeMoney

A monetary amount in a specific currency: Square's Money, and Stripe's amount beside its currency.
The amount is always an integer count of the currency's minor unit — pence for GBP, cents for USD. Zero-decimal currencies such as JPY have a minor unit equal to their major unit, so {"amount": 500, "currency": "JPY"} is ¥500 while {"amount": 500, "currency": "GBP"} is £5.00.
Floating point is never used for money anywhere in this API. Binary floats cannot represent most decimal fractions exactly, so accumulating them across the line items of an order produces totals that disagree with the printed receipt by a penny. Integer minor units make every arithmetic operation exact.

amountinteger · int64

Required
The amount, as a whole number of the currency's minor unit. May be negative to express a refund, discount or credit.

currencyCurrency

Required
ISO 4217 currency code.
Determines the minor unit that Money.amount is expressed in. Zero-decimal currencies such as JPY have a minor unit equal to the major unit.
One of 182 values; see the schema.

service_charge_taxMoney

Nullable
The tax on the service charge (decision record 0054), its own line and never folded into goods tax_total. Computed server-side from the location's service-charge tax class and the sale's fulfilment and business date. Null when the charge is not taxed.

amountinteger · int64

Required
The amount, as a whole number of the currency's minor unit. May be negative to express a refund, discount or credit.

currencyCurrency

Required
ISO 4217 currency code.
Determines the minor unit that Money.amount is expressed in. Zero-decimal currencies such as JPY have a minor unit equal to the major unit.
One of 182 values; see the schema.

subtotalMoney

Required
A monetary amount in a specific currency: Square's Money, and Stripe's amount beside its currency.
The amount is always an integer count of the currency's minor unit — pence for GBP, cents for USD. Zero-decimal currencies such as JPY have a minor unit equal to their major unit, so {"amount": 500, "currency": "JPY"} is ¥500 while {"amount": 500, "currency": "GBP"} is £5.00.
Floating point is never used for money anywhere in this API. Binary floats cannot represent most decimal fractions exactly, so accumulating them across the line items of an order produces totals that disagree with the printed receipt by a penny. Integer minor units make every arithmetic operation exact.

amountinteger · int64

Required
The amount, as a whole number of the currency's minor unit. May be negative to express a refund, discount or credit.

currencyCurrency

Required
ISO 4217 currency code.
Determines the minor unit that Money.amount is expressed in. Zero-decimal currencies such as JPY have a minor unit equal to the major unit.
One of 182 values; see the schema.

tax_totalMoney

Required
A monetary amount in a specific currency: Square's Money, and Stripe's amount beside its currency.
The amount is always an integer count of the currency's minor unit — pence for GBP, cents for USD. Zero-decimal currencies such as JPY have a minor unit equal to their major unit, so {"amount": 500, "currency": "JPY"} is ¥500 while {"amount": 500, "currency": "GBP"} is £5.00.
Floating point is never used for money anywhere in this API. Binary floats cannot represent most decimal fractions exactly, so accumulating them across the line items of an order produces totals that disagree with the printed receipt by a penny. Integer minor units make every arithmetic operation exact.

amountinteger · int64

Required
The amount, as a whole number of the currency's minor unit. May be negative to express a refund, discount or credit.

currencyCurrency

Required
ISO 4217 currency code.
Determines the minor unit that Money.amount is expressed in. Zero-decimal currencies such as JPY have a minor unit equal to the major unit.
One of 182 values; see the schema.

totalMoney

Required
A monetary amount in a specific currency: Square's Money, and Stripe's amount beside its currency.
The amount is always an integer count of the currency's minor unit — pence for GBP, cents for USD. Zero-decimal currencies such as JPY have a minor unit equal to their major unit, so {"amount": 500, "currency": "JPY"} is ¥500 while {"amount": 500, "currency": "GBP"} is £5.00.
Floating point is never used for money anywhere in this API. Binary floats cannot represent most decimal fractions exactly, so accumulating them across the line items of an order produces totals that disagree with the printed receipt by a penny. Integer minor units make every arithmetic operation exact.

amountinteger · int64

Required
The amount, as a whole number of the currency's minor unit. May be negative to express a refund, discount or credit.

currencyCurrency

Required
ISO 4217 currency code.
Determines the minor unit that Money.amount is expressed in. Zero-decimal currencies such as JPY have a minor unit equal to the major unit.
One of 182 values; see the schema.

updated_atTimestamp

RequiredRead only
Server-assigned RFC 3339 timestamp, always UTC.
Server-assigned because device clocks drift and cannot be trusted for ordering — a till that has been powered off for a week may come back with a clock hours out. Where the device's own view of time matters it is carried separately in client_created_at.

versionVersion

RequiredRead only
Optimistic concurrency version, raised by the server on every write. A version is never lower than one already returned for the resource, though it may rise by more than one.
Returned in the ETag response header as well as in the body. Send it back in If-Match on an update and the write is rejected with 412 if anyone else has written since — which is what stops two tills silently overwriting each other's edit to the same product when both come back online at once.
≥ 1

void_memberMemberSnapshot

Nullable
The staff member who voided this order, when it has been voided and the void was made by a person. Nil for a sale that was never voided, or one voided by something that is not a person.

idstring · uuid

Required
The roster's id, checked against the merchant's memberships.

namestring

Required
What the member was called.
≥ 1 chars

emailstring · email

Required
The member's address.

rolestring · enum

Required
The role the member held.
ownermanagerstaff

void_notestring
The staff member's note on the void, required when the reason is other.

void_reasonstring · enum
Why this sale was voided. Set on a voided order.
customer_canceledstaff_errorrefundother

voided_atstring · date-time

Nullable
When the sale was voided.

400
The request could not be parsed. Malformed JSON, a bad query parameter, or a header that failed to decode, among them an API-Version later than the server speaks or not a date (api-version-unknown, with the server's own in api_version).
Distinct from 422: a 400 never reached validation, so invalid_params is absent. Retrying without changing the request will fail again, except that a request refused for its API-Version goes once the server is updated.

401
No credentials, or credentials that could not be verified — missing bearer token, malformed JWT, expired token, or a signature that failed against the issuer's JWKS.
Refresh the token and retry once. Repeated 401 after a refresh means the device needs to re-enrol.

403
Authenticated, but not permitted. The token is valid and its merchant was resolved, but the caller's role does not allow this operation, or the target belongs to a different merchant.
Cross-tenant access is reported as 403 on a resource the caller may not see, and as 404 where even confirming existence would leak information. Retrying will not help.

404
No such resource, or none visible to this caller.
Also returned instead of 403 where acknowledging existence would itself leak information — so a 404 does not prove the id is unused globally, only that it is not yours.

410
The request names an API-Version this server no longer serves (docs/decisions/0011). Nothing in it was read. api_version names the version the server speaks: the client is behind, and sends the request again once it is updated.

429
Rate limit exceeded. Honour Retry-After rather than applying your own backoff.
A fleet of tills coming back online together after an outage is the realistic cause, which is exactly when uncoordinated client-side retry turns a brief outage into a sustained one. The limit is per process, and per site for what records trade there — a request spends its site's budget, and a till's own smaller one inside it — and per (client, merchant) for everything else; no RateLimit field is sent, so this response and its Retry-After are the whole of the contract.

500
Something failed on our side. trace_id identifies the request in our tracing — quote it in a support ticket.
The body never carries internal detail: no SQL, no stack traces, no upstream error strings. Safe to retry with the same Idempotency-Key.

503
Temporarily unable to serve the request — a dependency is down or the service is shedding load.
Retry with the same Idempotency-Key after Retry-After. This is always safe: a request that did take effect before the failure will be recognised as a replay.
Request
curl -X GET 'https://api.tenvelo.com/v1/orders/0192f1e4-7c3a-7b2e-9f10-5d6c7e8f9a0b' \ -H "Authorization: Bearer $TOKEN"
Response
{ "id": "0192f1e4-7c3a-7b2e-9f10-5d6c7e8f9a0b", "name": "Sam", "acceptance": "pending", "age_confirmed": false, "age_minimum": 0, "business_date": "2026-09-11", "channel": "pos", "channel_cost": { "amount": 1250, "currency": "GBP" }, "client_created_at": "2026-09-11T09:30:00Z", "closed_at": "2026-09-11T09:30:00Z", "covers": 0, "created_at": "2026-09-08T09:41:12Z", "currency": "AED", "customer": { "id": "0192f1e4-7c3a-7b2e-9f10-5d6c7e8f9a0b", "name": "string", "loyalty_points": 0, "rewards": [ { "id": "0192f1e4-7c3a-7b2e-9f10-5d6c7e8f9a0b", "name": "string", "cost_points": 0, "discount_id": "0192f1e4-7c3a-7b2e-9f10-5d6c7e8f9a0b" } ], "tags": "string", "tier": { "current": { "id": "0192f1e4-7c3a-7b2e-9f10-5d6c7e8f9a0b", "name": "string", "earn_rate_percentage": "-12.5", "threshold_spend": { "amount": 1250, "currency": "GBP" }, "threshold_visits": 0, "window_days": 0 }, "next": { "id": "0192f1e4-7c3a-7b2e-9f10-5d6c7e8f9a0b", "name": "string", "earn_rate_percentage": "-12.5", "threshold_spend": { "amount": 1250, "currency": "GBP" }, "threshold_visits": 0, "window_days": 0 }, "spend_needed": { "amount": 1250, "currency": "GBP" }, "visits_needed": 0 }, "version": 0 }, "customer_id": "0192f1e4-7c3a-7b2e-9f10-5d6c7e8f9a0b", "delivery_address": { "address_line_1": "12 Bridge Street", "address_line_2": "string", "address_line_3": "string", "administrative_district_level_1": "Somerset", "administrative_district_level_2": "string", "country": "ZZ", "locality": "Bristol", "postal_code": "BS1 4ST", "sublocality": "string" }, "delivery_fee": { "amount": 1250, "currency": "GBP" }, "device_id": "0192f1e4-7c3a-7b2e-9f10-5d6c7e8f9a0b", "device_seq": 0, "document": { "kind": "invoice", "number": 148, "series": "B1-T3" }, "drawer_session_id": "0192f1e4-7c3a-7b2e-9f10-5d6c7e8f9a0b", "email_receipt": false, "external_reference": "string", "flags": [ "string" ], "fulfillment_status": "received", "fulfillment_type": "on_premises", "line_items": [ { "id": "0192f1e4-7c3a-7b2e-9f10-5d6c7e8f9a0b", "name": "Flat white", "approved_by_member": { "id": "0192f1e4-7c3a-7b2e-9f10-5d6c7e8f9a0b", "name": "string", "email": "ada@example.com", "role": "owner" }, "category_id": "0192f1e4-7c3a-7b2e-9f10-5d6c7e8f9a0b", "category_name": "string", "comp_reason": "string", "course": 1, "discount": { "amount": 1250, "currency": "GBP" }, "discount_id": "0192f1e4-7c3a-7b2e-9f10-5d6c7e8f9a0b", "discount_name": "string", "gift_card_code": "string", "gift_card_token_hash": "string", "modifiers": [ { "id": "0192f1e4-7c3a-7b2e-9f10-5d6c7e8f9a0b", "name": "Oat milk", "price_delta": { "amount": 1250, "currency": "GBP" } } ], "multibuy": { "every": 2, "price": { "amount": 1250, "currency": "GBP" } }, "note": "string", "origin": "till", "product_id": "0192f1e4-7c3a-7b2e-9f10-5d6c7e8f9a0b", "product_type": "standard", "quantity": "3", "seat": 1, "sent_at": "2026-09-11T09:30:00Z", "serials": [], "tax": { "amount": 1250, "currency": "GBP" }, "tax_breakdown": [ { "amount": { "amount": 1250, "currency": "GBP" }, "inclusive": false, "percentage": "20", "rate_id": "0192f1e4-7c3a-7b2e-9f10-5d6c7e8f9a0b" } ], "tax_inclusive": false, "tax_rate_percentage": "20", "total": { "amount": 1250, "currency": "GBP" }, "unit_of_measure": "each", "unit_price": { "amount": 1250, "currency": "GBP" }, "variant_id": "0192f1e4-7c3a-7b2e-9f10-5d6c7e8f9a0b" } ], "location_id": "0192f1e4-7c3a-7b2e-9f10-5d6c7e8f9a0b", "loyalty_earned": 0, "loyalty_spent": 0, "member": { "id": "0192f1e4-7c3a-7b2e-9f10-5d6c7e8f9a0b", "name": "string", "email": "ada@example.com", "role": "owner" }, "merchant_id": "0192f1e4-7c3a-7b2e-9f10-5d6c7e8f9a0b", "owner_member": { "id": "0192f1e4-7c3a-7b2e-9f10-5d6c7e8f9a0b", "name": "string", "email": "ada@example.com", "role": "owner" }, "paid": { "amount": 1250, "currency": "GBP" }, "payments": [ { "id": "0192f1e4-7c3a-7b2e-9f10-5d6c7e8f9a0b", "amount": { "amount": 1250, "currency": "GBP" }, "buyer_supplied": { "amount": 1250, "currency": "GBP" }, "card_brand": "string", "card_confirmation": "confirmed", "card_last4": "string", "change_back": { "amount": 1250, "currency": "GBP" }, "fingerprint": "string", "gift_card_hold_id": "0192f1e4-7c3a-7b2e-9f10-5d6c7e8f9a0b", "line_ids": [ "0192f1e4-7c3a-7b2e-9f10-5d6c7e8f9a0b" ], "member": { "id": "0192f1e4-7c3a-7b2e-9f10-5d6c7e8f9a0b", "name": "string", "email": "ada@example.com", "role": "owner" }, "method": "cash", "pin": "string", "reference": "pspRef_8829301", "tip": { "amount": 1250, "currency": "GBP" } } ], "pickup_at": "2026-09-11T09:30:00Z", "ready_at": "2026-09-11T09:30:00Z", "ready_to_pay_at": "2026-09-11T09:30:00Z", "received_at": "2026-09-08T09:41:12Z", "reference": "A-0148", "refunded": { "amount": 1250, "currency": "GBP" }, "rejection_note": "string", "rejection_reason": "sold_out", "service_charge": { "amount": 1250, "currency": "GBP" }, "service_charge_tax": { "amount": 1250, "currency": "GBP" }, "service_charge_tax_class_id": "0192f1e4-7c3a-7b2e-9f10-5d6c7e8f9a0b", "service_charge_tax_rate_percentage": "20", "source": "string", "source_name": "string", "state": "open", "table_id": "0192f1e4-7c3a-7b2e-9f10-5d6c7e8f9a0b", "tips": { "amount": 1250, "currency": "GBP" }, "totals": { "cash_rounding": { "amount": 1250, "currency": "GBP" }, "discount_total": { "amount": 1250, "currency": "GBP" }, "service_charge": { "amount": 1250, "currency": "GBP" }, "service_charge_tax": { "amount": 1250, "currency": "GBP" }, "subtotal": { "amount": 1250, "currency": "GBP" }, "tax_total": { "amount": 1250, "currency": "GBP" }, "total": { "amount": 1250, "currency": "GBP" } }, "updated_at": "2026-09-08T09:41:12Z", "version": 7, "void_member": { "id": "0192f1e4-7c3a-7b2e-9f10-5d6c7e8f9a0b", "name": "string", "email": "ada@example.com", "role": "owner" }, "void_note": "string", "void_reason": "customer_canceled", "voided_at": "2026-09-11T09:30:00Z" }
POST/v1/orders/{id}/accept

Take an online order on

No. acceptOrderAuth pos:orders:write
The person the venue's choose-who-accepts rule names takes an online order on, as the till does from the floor, from the manager app. The write is the same acceptance a till syncs: the fact's id derives from the order and the answer, so a retry never records twice, and the projector sends the lines to the kitchen and tells the guest whichever door accepted it.
Parameters

idpath · string · uuid
Required
UUIDv7 of the resource.
For resources a device can originate — orders, and their line items — this id is minted by the client before the record is ever synced, which is what makes an offline create idempotent.
Responses

200
The order as it now stands, taken on.

Order · application/json

idstring · uuid

Required
UUIDv7, minted by the device before the sale is synced. This is what makes an offline order idempotent: replaying it targets the same id, so a retry over flaky wifi cannot create a duplicate sale.

namestring

Nullable
Whose sale it is, while it is open: a customer's name, whatever the shop shouts across the bar. Null is a walk-in being served at a counter right now.
≤ 128 chars

acceptancestring · enum

Read only
Where an asked-for order stands with the venue that must make it, beside its lifecycle: state keeps its four values. A till's own order is accepted as it is created; a channel's — the ordering page, an integration — is pending until a person or a rule takes it on, or it is rejected with a reason. Set by the server, never from the body: acceptance is a fact (engineering, recording what happened, section 12), not a field a client sets.
pendingacceptedrejected

age_confirmedboolean
Whether a sale carrying an age-restricted line recorded that the till confirmed the guest's age before it completed. False both for a sale with no age-restricted line and for one that needed the check and did not record it — the reports compare it with age_minimum to flag the second.
default false

age_minimuminteger · int32
The oldest buyer the sale's age-restricted lines allowed, as the till recorded it: the highest minimum_age among them, 0 when the sale carried none. A completed sale with age_minimum above 0 and age_confirmed false is a counter law miss.
≥ 0 · default 0

business_datestring · date

Read only
The trading day the sale belongs to, in its location's own reckoning: its time zone and the hour its day starts. Set by the server when the sale completes, from when the till says it happened, so a sale rung at 1am on a late night books to the night before. Absent on an order that has not completed.

channelstring · enum

Read only
Where the order came from, set by the server from the caller and never accepted from the body: pos is a till, table a table-side device, online an online storefront, integration a third-party integration. A till cannot attribute a sale to another channel. What the channel is tells an integration whose order arrived from where, which an order_type cannot.
postableonlineintegration

channel_costMoney

What the channel took from the order, at the stated cost in force on the order's business date (online-ordering item 18). Present only for an online order whose channel states a cost, and derived on read from the stated rates and the order's total — never stored, so it can never drift from them.

amountinteger · int64

Required
The amount, as a whole number of the currency's minor unit. May be negative to express a refund, discount or credit.

currencyCurrency

Required
ISO 4217 currency code.
Determines the minor unit that Money.amount is expressed in. Zero-decimal currencies such as JPY have a minor unit equal to the major unit.
One of 182 values; see the schema.

client_created_atstring · date-time

Required
When the device believes the sale happened. Trusted for display — it is what a receipt shows and what staff recognise — but never for ordering or for resolving conflicts, because till clocks drift. Compare with received_at to measure how long a device was offline.

closed_atstring · date-time

Nullable
When the order left open — was completed. A void does not change it; voided_at is when the sale was voided.

coversinteger · int32

RequiredRead only
How many people the party is, as counted at seating on the created fact; zero where nobody counted them. The covers-per-labour-hour and average-spend-per-cover figures are divided by it, so a tab opened without a count adds no covers rather than one.
0–1000 · default 0

created_atTimestamp

RequiredRead only
Server-assigned RFC 3339 timestamp, always UTC.
Server-assigned because device clocks drift and cannot be trusted for ordering — a till that has been powered off for a week may come back with a clock hours out. Where the device's own view of time matters it is carried separately in client_created_at.

currencyCurrency

Required
ISO 4217 currency code.
Determines the minor unit that Money.amount is expressed in. Zero-decimal currencies such as JPY have a minor unit equal to the major unit.
One of 182 values; see the schema.

customerCustomerLoyalty

This order's guest as a till may see them: name, loyalty balance and what it can afford. Carried on the order and its change-feed entry so a till that picks a tab up on another device shows the badge and offers a redemption without a second call. Absent for a walk-in and for a guest since erased or merged; customer_id remains the record. Additive: a client that predates it simply omits it.

idstring · uuid

Required

namestring

Required

loyalty_pointsinteger · int64
The guest's current loyalty balance, earned minus redeemed.

rewardsarray of Reward

The reward catalogue entries this guest can afford, so a till can offer them at redemption. Server-computed from the balance; a guest not enrolled sees none.

idstring · uuid

Required

namestring

Required
What the reward is called to the guest and on the receipt.

cost_pointsinteger · int64

Required
What redeeming it costs, in points.

discount_idstring · uuid

Required
The discount definition the reward is backed by.

tagsstring
The guest's labels, carried so a counter can offer them; still no contact details and no note.

tierLoyaltyTierStatus

A guest's standing in a loyalty programme's ladder at one moment (loyalty item 16): the tier they are on, the next tier above, and how much more they need to reach it.

currentLoyaltyTier

One named level in a loyalty programme's ladder (loyalty item 16). Exactly one of threshold_spend and threshold_visits is set; window_days is the rolling window over which the qualifying spend or visits are counted, and earn_rate_percentage is the multiplier on the programme's base earn rate (10000 is 1x).

idstring · uuid

Required

namestring

Required

earn_rate_percentageRelativePercentage
A percentage that may be negative or above 100, such as a change on a period before or a multiplier, in a decimal string with at most four decimal places: a fall of an eighth is "-12.5", and one and a half times is "150". Read and computed as a Percentage is, in parts per million.
pattern ^-?(0|[1-9][0-9]{0,8})(\.[0-9]{1,4})?$

threshold_spendMoney

A monetary amount in a specific currency: Square's Money, and Stripe's amount beside its currency.
The amount is always an integer count of the currency's minor unit — pence for GBP, cents for USD. Zero-decimal currencies such as JPY have a minor unit equal to their major unit, so {"amount": 500, "currency": "JPY"} is ¥500 while {"amount": 500, "currency": "GBP"} is £5.00.
Floating point is never used for money anywhere in this API. Binary floats cannot represent most decimal fractions exactly, so accumulating them across the line items of an order produces totals that disagree with the printed receipt by a penny. Integer minor units make every arithmetic operation exact.

amountinteger · int64

Required
The amount, as a whole number of the currency's minor unit. May be negative to express a refund, discount or credit.

currencyCurrency

Required
ISO 4217 currency code.
Determines the minor unit that Money.amount is expressed in. Zero-decimal currencies such as JPY have a minor unit equal to the major unit.
One of 182 values; see the schema.

threshold_visitsinteger · int64
The number of completed linked orders that reaches the tier.

window_daysinteger · int32

nextLoyaltyTier

One named level in a loyalty programme's ladder (loyalty item 16). Exactly one of threshold_spend and threshold_visits is set; window_days is the rolling window over which the qualifying spend or visits are counted, and earn_rate_percentage is the multiplier on the programme's base earn rate (10000 is 1x).

idstring · uuid

Required

namestring

Required

earn_rate_percentageRelativePercentage
A percentage that may be negative or above 100, such as a change on a period before or a multiplier, in a decimal string with at most four decimal places: a fall of an eighth is "-12.5", and one and a half times is "150". Read and computed as a Percentage is, in parts per million.
pattern ^-?(0|[1-9][0-9]{0,8})(\.[0-9]{1,4})?$

threshold_spendMoney

A monetary amount in a specific currency: Square's Money, and Stripe's amount beside its currency.
The amount is always an integer count of the currency's minor unit — pence for GBP, cents for USD. Zero-decimal currencies such as JPY have a minor unit equal to their major unit, so {"amount": 500, "currency": "JPY"} is ¥500 while {"amount": 500, "currency": "GBP"} is £5.00.
Floating point is never used for money anywhere in this API. Binary floats cannot represent most decimal fractions exactly, so accumulating them across the line items of an order produces totals that disagree with the printed receipt by a penny. Integer minor units make every arithmetic operation exact.

amountinteger · int64

Required
The amount, as a whole number of the currency's minor unit. May be negative to express a refund, discount or credit.

currencyCurrency

Required
ISO 4217 currency code.
Determines the minor unit that Money.amount is expressed in. Zero-decimal currencies such as JPY have a minor unit equal to the major unit.
One of 182 values; see the schema.

threshold_visitsinteger · int64
The number of completed linked orders that reaches the tier.

window_daysinteger · int32

spend_neededMoney

A monetary amount in a specific currency: Square's Money, and Stripe's amount beside its currency.
The amount is always an integer count of the currency's minor unit — pence for GBP, cents for USD. Zero-decimal currencies such as JPY have a minor unit equal to their major unit, so {"amount": 500, "currency": "JPY"} is ¥500 while {"amount": 500, "currency": "GBP"} is £5.00.
Floating point is never used for money anywhere in this API. Binary floats cannot represent most decimal fractions exactly, so accumulating them across the line items of an order produces totals that disagree with the printed receipt by a penny. Integer minor units make every arithmetic operation exact.

amountinteger · int64

Required
The amount, as a whole number of the currency's minor unit. May be negative to express a refund, discount or credit.

currencyCurrency

Required
ISO 4217 currency code.
Determines the minor unit that Money.amount is expressed in. Zero-decimal currencies such as JPY have a minor unit equal to the major unit.
One of 182 values; see the schema.

visits_neededinteger · int64
The visits still needed to reach next, when next is reached by visits.

versioninteger · int64

Required
The guest record's version, for the optimistic write a picker makes; it may be stale by the time the write lands, and the batch then refuses.

customer_idstring · uuid

Nullable
The guest this sale is recorded against, if any. Null for a walk-in.

delivery_addressAddress

Where a delivery order goes, as the writer stated it, when the order's fulfillment is delivery.

address_line_1string

Required
First line of the address — street number, street name, building name.
≤ 255 chars

address_line_2string
Second line of the address, if any.
≤ 255 chars

address_line_3string
Third line of the address, if any.
≤ 255 chars

administrative_district_level_1string
A civil entity within the country. The state in the US; the county in the UK.
≤ 128 chars

administrative_district_level_2string
A civil entity within administrative_district_level_1.
≤ 128 chars

countryCountry

Required
ISO 3166-1 alpha-2 country code.
ZZ is the unknown/unspecified placeholder.
One of 250 values; see the schema.

localitystring
The city or town.
≤ 128 chars

postal_codestring
The postal or ZIP code.
≤ 32 chars

sublocalitystring
A civil region within the locality, if any.
≤ 128 chars

delivery_feeMoney

Nullable
The venue's delivery charge on a delivered order (online-ordering: a shop may charge for delivery), snapshotted from its settings at write, or null when none. Part of the total; never folded into goods or their tax.

amountinteger · int64

Required
The amount, as a whole number of the currency's minor unit. May be negative to express a refund, discount or credit.

currencyCurrency

Required
ISO 4217 currency code.
Determines the minor unit that Money.amount is expressed in. Zero-decimal currencies such as JPY have a minor unit equal to the major unit.
One of 182 values; see the schema.

device_idstring · uuid
The till that last wrote the order. On an open order this is not ownership — any device at the location may pick a tab up, which is the entire point.

device_seqinteger · int64

Nullable
The device's monotonic sequence for this write, if the till recorded one.

documentOrderDocument

The fiscal document a completed order is recorded as, in the per-till series 0016 builds. Every sales document a till issues belongs to a series it was issued at enrolment, and the number is a gap-free counter in that series, incremented in the same transaction that completes the order. Printed on the receipt and sent with the order; the server stores it and refuses a duplicate (series, number).
This is the number a market's fiscal rules are about — the correlative number within a series. It is not the order's reference, which stays the short per-day call number for staff to find a sale.

kindstring · enum

Required
What the document is. invoice is the ordinary receipt — the simplified invoice most markets call a receipt. A full invoice and a rectifying document will be separate kinds, each in its own series.
invoice
default invoice

numberinteger · int64

Required
The gap-free sequence number within the series, starting at 1. Never reused: a void keeps its number, and a correction is a new document in a rectifying series.
≥ 1

seriesstring

Required
The series this document belongs to: a short code issued to one till at enrolment (e.g. B1-T3), one per device and kind of document. The ordinary receipt is in the invoice series.
≤ 32 chars

drawer_session_idstring · uuid

Nullable
The drawer session this sale was rung in, if any. Null otherwise.

email_receiptboolean
Whether the customer on this order asked for its receipt to be emailed. The address is always the customer record's — never typed onto the order, which is a financial record — and only honoured when the guest has consented. Additive, so a till that predates it simply omits it.
default false

external_referencestring

Read only
The writer's own reference for the order, when one was given.
≤ 128 chars

flagsarray of OrderFlagKind

Read only
The kinds of the flags still open on the order, which the books could not settle; absent when none is. Read beside the order as refunded is, and left out of the change feed.

fulfillment_statusstring · enum

Read only
Where an asked-for order has got to, for the guest and the venue: received until the venue takes it on, preparing once accepted, ready once said to be, collected once completed, or rejected or canceled. Derived from acceptance, ready_at and state when the order is read, never stored, so a client shows it rather than working it out again. Toast's fulfillmentStatus. Absent on a till's own sale, which is not asked for.
receivedpreparingreadycollectedrejectedcanceled

fulfillment_typestring · enum

Required
How the sale leaves the building, as the glossary names it and a tax rule is keyed by (docs/decisions/0014): on_premises is what the law calls eat-in, pickup is takeaway and delivery is delivery — Square's fulfillment type, Toast's dining option. A sale that does not say is on premises.
on_premisespickupdelivery

line_itemsarray of OrderLineItem

Required
What was sold. A completed order has at least one line; an open order may be empty for a moment, while the tab it is has just been started.

idstring · uuid

Required
UUIDv7, minted by the device.

namestring

Required
Product name as sold. Snapshot; never re-read from the product.
1–255 chars

approved_by_memberMemberSnapshot

Nullable
The manager or owner who authorised a staff member's discount or comp above the merchant's discount_approval_threshold_minor/discount_approval_threshold_percentage or a comp when comp_requires_manager is set, as they were then; null when no approval was needed.

idstring · uuid

Required
The roster's id, checked against the merchant's memberships.

namestring

Required
What the member was called.
≥ 1 chars

emailstring · email

Required
The member's address.

rolestring · enum

Required
The role the member held.
ownermanagerstaff

category_idstring · uuid

RequiredNullable
The category the product was filed under when the line was rung, for reporting. Snapshot: moving the product to another category later moves no sale. Null on an ad-hoc line or an uncategorised product.

category_namestring

Required
The category's name when the line was rung, so a report of past sales reads as they were filed. Snapshot; empty when category_id is null.
≤ 255 chars

comp_reasonstring
Why this line was given away. Present on a comp — an item given away at no charge — and means something different from a discount, so it is reported separately. Required when the line is a comp.
≤ 512 chars

courseinteger · int32

Nullable
The course this line belongs to, in a full-service kitchen — starters, mains, desserts. Set on the till when ringing to a course, and used to hold or fire a course from the till. Null for a single-course counter sale or a course-less line. Held courses are not sent (sent_at null) until they are fired.
≥ 1

discountMoney

A monetary amount in a specific currency: Square's Money, and Stripe's amount beside its currency.
The amount is always an integer count of the currency's minor unit — pence for GBP, cents for USD. Zero-decimal currencies such as JPY have a minor unit equal to their major unit, so {"amount": 500, "currency": "JPY"} is ¥500 while {"amount": 500, "currency": "GBP"} is £5.00.
Floating point is never used for money anywhere in this API. Binary floats cannot represent most decimal fractions exactly, so accumulating them across the line items of an order produces totals that disagree with the printed receipt by a penny. Integer minor units make every arithmetic operation exact.

amountinteger · int64

Required
The amount, as a whole number of the currency's minor unit. May be negative to express a refund, discount or credit.

currencyCurrency

Required
ISO 4217 currency code.
Determines the minor unit that Money.amount is expressed in. Zero-decimal currencies such as JPY have a minor unit equal to the major unit.
One of 182 values; see the schema.

discount_idstring · uuid

Nullable
The discount definition applied to this line, for reporting. Null for a line with no discount. Snapshot — the discount is recorded so its use can be attributed even if the definition later changes.

discount_namestring
The discount's name at the time the line was priced, snapshotted on the line — the reason a guest can be told, without re-resolving a definition that may have been renamed or deleted. Empty for a line with no discount.
≤ 200 chars

gift_card_codestring

Nullable
The code on the card being sold, when the line's product is a gift_card — typed or scanned at the till. The server issues the card (or refuses a code already live) when the order completes. Null for any other line.
≤ 64 chars

gift_card_token_hashstring

Nullable
The hash of the balance-page token for the card being sold: SHA-256 over the token's text, in base64url without padding. The device mints the token — 32 random bytes, unpadded base64url — and prints it on the receipt's balance link; only its hash leaves the device, so the token is never on the record of the sale, and the server checks a link by hashing the token it carries (W3C, "Good Practices for Capability URLs"). Absent leaves the card with no balance link until one is made (gift-card-balance-links). Null for any other line.
43–43 chars · pattern ^[A-Za-z0-9_-]{43}$

modifiersarray of OrderLineModifier

The options chosen on this line, snapshotted at the moment of sale. The line's unit_price already includes each option's delta.
The server checks only the shape of these — a negative delta is refused, an option chosen twice is refused — and never refuses a sale because the menu has changed since the till synced. A sale that was correct when rung stays correct.

idstring · uuid

Required
The modifier that was chosen. Kept for reporting, never re-resolved.

namestring

Required
Option name as sold. Snapshot.
1–255 chars

price_deltaMoney

Required
A monetary amount in a specific currency: Square's Money, and Stripe's amount beside its currency.
The amount is always an integer count of the currency's minor unit — pence for GBP, cents for USD. Zero-decimal currencies such as JPY have a minor unit equal to their major unit, so {"amount": 500, "currency": "JPY"} is ¥500 while {"amount": 500, "currency": "GBP"} is £5.00.
Floating point is never used for money anywhere in this API. Binary floats cannot represent most decimal fractions exactly, so accumulating them across the line items of an order produces totals that disagree with the printed receipt by a penny. Integer minor units make every arithmetic operation exact.

amountinteger · int64

Required
The amount, as a whole number of the currency's minor unit. May be negative to express a refund, discount or credit.

currencyCurrency

Required
ISO 4217 currency code.
Determines the minor unit that Money.amount is expressed in. Zero-decimal currencies such as JPY have a minor unit equal to the major unit.
One of 182 values; see the schema.

multibuyMultibuyRule

Nullable
The product's multibuy rule as it stood when the line was rung, snapshotted on the line so the server resolves the gross by the same deal the till did — re-pricing a product never rewrites a sale that was correct. Null on a line with no deal. A rule never applies to a weighed line.

everyinteger

Required
How many units make a run; 3 is the ordinary buy-two-get-one.
2–1000

priceMoney

Required
A monetary amount in a specific currency: Square's Money, and Stripe's amount beside its currency.
The amount is always an integer count of the currency's minor unit — pence for GBP, cents for USD. Zero-decimal currencies such as JPY have a minor unit equal to their major unit, so {"amount": 500, "currency": "JPY"} is ¥500 while {"amount": 500, "currency": "GBP"} is £5.00.
Floating point is never used for money anywhere in this API. Binary floats cannot represent most decimal fractions exactly, so accumulating them across the line items of an order produces totals that disagree with the printed receipt by a penny. Integer minor units make every arithmetic operation exact.

amountinteger · int64

Required
The amount, as a whole number of the currency's minor unit. May be negative to express a refund, discount or credit.

currencyCurrency

Required
ISO 4217 currency code.
Determines the minor unit that Money.amount is expressed in. Zero-decimal currencies such as JPY have a minor unit equal to the major unit.
One of 182 values; see the schema.

notestring
Free text from the till — "oat milk", "no sugar".
≤ 512 chars

originstring · enum

Read only
Where this line was rung from, as the server saw the writer: the till at the counter, a guest's phone on a tab, an ordering channel, an integration. It is the server's word and never the writer's, and it is how the share of a table's spend the table rang itself is told. Absent on a line recorded before origins were.
tillcustomeronlineintegration

product_idstring · uuid

Nullable
The catalogue product, for reporting. Null for an ad-hoc line — a miscellaneous item rung up at a custom price, which every real till needs.

product_typestring · enum

Required
What the product was when the line was rung: a gift_card sold is money taken for a promise, not revenue, and a combo is a set. Square's item_type. Snapshot, copied from the product at the moment of sale; standard on an ad-hoc line.
standardgift_cardcombo

quantityQuantity

Required
How much of something, as a decimal string in the unit_of_measure beside it (each where there is none), as Square's quantity is: three croissants are "3", 1.4 kg of beans is "1.4". A string because a JSON number is a binary float to most parsers.
It has at most as many decimal places as its unit's base unit holds — three in each, g and ml, six in kg and l — and a finer one is refused, never rounded. Tenvelo holds every quantity as an integer of that base unit (thousandths of an each, milligrams, microlitres; docs/decisions/0063); a client that computes with one should read the digits the same way, never through a float.
≤ 26 chars · pattern ^-?(0|[1-9][0-9]*)(\.[0-9]{1,6})?$

seatinteger · int32

Nullable
The seat this line is for, when a table's seats are numbered. Set on the till and carried to the kitchen and to split bills. Null for a counter sale or an unnumbered seat.
≥ 1

sent_atstring · date-time

Nullable
When this line was sent to the kitchen — set by the till when a tab is held or a sale completed, and immutable once set. A kitchen knows what to cook from the lines of a ticket, and a new round on a tab is a new set of sent_at values rather than the old lines re-sent. Null on a line the till has not yet held or completed.

serialsarray of string
The serial numbers of the units this line sold (retail item: serial numbers) — one per unit, in the order they were entered, printed on a product whose track_serial is set. Empty on any other line. A snapshot like the name and price: the record of which physical units left the shelf, so a specific unit sold is traceable to its sale.
default []

taxMoney

A monetary amount in a specific currency: Square's Money, and Stripe's amount beside its currency.
The amount is always an integer count of the currency's minor unit — pence for GBP, cents for USD. Zero-decimal currencies such as JPY have a minor unit equal to their major unit, so {"amount": 500, "currency": "JPY"} is ¥500 while {"amount": 500, "currency": "GBP"} is £5.00.
Floating point is never used for money anywhere in this API. Binary floats cannot represent most decimal fractions exactly, so accumulating them across the line items of an order produces totals that disagree with the printed receipt by a penny. Integer minor units make every arithmetic operation exact.

amountinteger · int64

Required
The amount, as a whole number of the currency's minor unit. May be negative to express a refund, discount or credit.

currencyCurrency

Required
ISO 4217 currency code.
Determines the minor unit that Money.amount is expressed in. Zero-decimal currencies such as JPY have a minor unit equal to the major unit.
One of 182 values; see the schema.

tax_breakdownarray of TaxBreakdownItem

Each rate's share of this line's tax, in the order its rule names the rates, when the line is taxed over several rates (each a separate calculation, each rounding with its own mode). Absent — null — on a line taxed at a single rate, where tax_rate_percentage and tax are the whole story.

amountMoney

Required
A monetary amount in a specific currency: Square's Money, and Stripe's amount beside its currency.
The amount is always an integer count of the currency's minor unit — pence for GBP, cents for USD. Zero-decimal currencies such as JPY have a minor unit equal to their major unit, so {"amount": 500, "currency": "JPY"} is ¥500 while {"amount": 500, "currency": "GBP"} is £5.00.
Floating point is never used for money anywhere in this API. Binary floats cannot represent most decimal fractions exactly, so accumulating them across the line items of an order produces totals that disagree with the printed receipt by a penny. Integer minor units make every arithmetic operation exact.

amountinteger · int64

Required
The amount, as a whole number of the currency's minor unit. May be negative to express a refund, discount or credit.

currencyCurrency

Required
ISO 4217 currency code.
Determines the minor unit that Money.amount is expressed in. Zero-decimal currencies such as JPY have a minor unit equal to the major unit.
One of 182 values; see the schema.

inclusiveboolean

Required
Whether this rate is inside the price (true) or added on top (false).

percentagePercentage

Required
A share of a whole, from "0" to "100", as a percentage in a decimal string with at most four decimal places, as Square's percentage and Stripe Tax's percentage_decimal are: UK VAT at 20% is "20", and an 8.875% US sales tax is "8.875".
A string because a JSON number is a binary float to most parsers, and a float cannot hold most decimal fractions exactly (RFC 7493 §2.2). Tenvelo computes with a percentage as an integer in parts per million ("8.875" is 88750), which every four-place percentage is exactly. A client that computes with one should read the digits the same way, never through a float.
pattern ^(100(\.0{1,4})?|(0|[1-9][0-9]?)(\.[0-9]{1,4})?)$

rate_idstring · uuid

Required
The rate this share belongs to.

tax_inclusiveboolean
Whether unit_price already contains the tax. Snapshot.

tax_rate_percentagePercentage
A share of a whole, from "0" to "100", as a percentage in a decimal string with at most four decimal places, as Square's percentage and Stripe Tax's percentage_decimal are: UK VAT at 20% is "20", and an 8.875% US sales tax is "8.875".
A string because a JSON number is a binary float to most parsers, and a float cannot hold most decimal fractions exactly (RFC 7493 §2.2). Tenvelo computes with a percentage as an integer in parts per million ("8.875" is 88750), which every four-place percentage is exactly. A client that computes with one should read the digits the same way, never through a float.
pattern ^(100(\.0{1,4})?|(0|[1-9][0-9]?)(\.[0-9]{1,4})?)$

totalMoney

Required
A monetary amount in a specific currency: Square's Money, and Stripe's amount beside its currency.
The amount is always an integer count of the currency's minor unit — pence for GBP, cents for USD. Zero-decimal currencies such as JPY have a minor unit equal to their major unit, so {"amount": 500, "currency": "JPY"} is ¥500 while {"amount": 500, "currency": "GBP"} is £5.00.
Floating point is never used for money anywhere in this API. Binary floats cannot represent most decimal fractions exactly, so accumulating them across the line items of an order produces totals that disagree with the printed receipt by a penny. Integer minor units make every arithmetic operation exact.

amountinteger · int64

Required
The amount, as a whole number of the currency's minor unit. May be negative to express a refund, discount or credit.

currencyCurrency

Required
ISO 4217 currency code.
Determines the minor unit that Money.amount is expressed in. Zero-decimal currencies such as JPY have a minor unit equal to the major unit.
One of 182 values; see the schema.

unit_of_measurestring · enum

Nullable
The unit this line was sold in, snapshotted from the product at the moment of sale (the product's own unit on a product line; any unit on an ad-hoc line). Absent means each.
eachkgglml

unit_priceMoney

Required
A monetary amount in a specific currency: Square's Money, and Stripe's amount beside its currency.
The amount is always an integer count of the currency's minor unit — pence for GBP, cents for USD. Zero-decimal currencies such as JPY have a minor unit equal to their major unit, so {"amount": 500, "currency": "JPY"} is ¥500 while {"amount": 500, "currency": "GBP"} is £5.00.
Floating point is never used for money anywhere in this API. Binary floats cannot represent most decimal fractions exactly, so accumulating them across the line items of an order produces totals that disagree with the printed receipt by a penny. Integer minor units make every arithmetic operation exact.

amountinteger · int64

Required
The amount, as a whole number of the currency's minor unit. May be negative to express a refund, discount or credit.

currencyCurrency

Required
ISO 4217 currency code.
Determines the minor unit that Money.amount is expressed in. Zero-decimal currencies such as JPY have a minor unit equal to the major unit.
One of 182 values; see the schema.

variant_idstring · uuid

Nullable
The variant that was sold, for reporting and stock. Null when the product itself is the sellable unit — a product with no variants, or with none picked. Like product_id, it is retained for reporting and never re-resolved: the descriptive and monetary fields on this line are the snapshot that is replayed, so a sale that was correct when rung stays correct even if the catalogue has changed since.

location_idstring · uuid

Required

loyalty_earnedinteger · int64

Read only
The points this sale earned its customer, recorded on the order.

loyalty_spentinteger · int64

Read only
The points this sale redeemed from its customer, recorded on the order.

memberMemberSnapshot

Nullable
The staff member who recorded this order — the person who rang it up — as they were then; nil when no person was attributed.

idstring · uuid

Required
The roster's id, checked against the merchant's memberships.

namestring

Required
What the member was called.
≥ 1 chars

emailstring · email

Required
The member's address.

rolestring · enum

Required
The role the member held.
ownermanagerstaff

merchant_idstring · uuid

RequiredRead only

owner_memberMemberSnapshot

Nullable
The staff member a tab belongs to — who opened it, and whom to ask when nobody has touched it. Checked against the merchant's memberships; nil for an order that was never a tab. Set once at open and only changed through a till's explicit transfer.

idstring · uuid

Required
The roster's id, checked against the merchant's memberships.

namestring

Required
What the member was called.
≥ 1 chars

emailstring · email

Required
The member's address.

rolestring · enum

Required
The role the member held.
ownermanagerstaff

paidMoney

A monetary amount in a specific currency: Square's Money, and Stripe's amount beside its currency.
The amount is always an integer count of the currency's minor unit — pence for GBP, cents for USD. Zero-decimal currencies such as JPY have a minor unit equal to their major unit, so {"amount": 500, "currency": "JPY"} is ¥500 while {"amount": 500, "currency": "GBP"} is £5.00.
Floating point is never used for money anywhere in this API. Binary floats cannot represent most decimal fractions exactly, so accumulating them across the line items of an order produces totals that disagree with the printed receipt by a penny. Integer minor units make every arithmetic operation exact.

amountinteger · int64

Required
The amount, as a whole number of the currency's minor unit. May be negative to express a refund, discount or credit.

currencyCurrency

Required
ISO 4217 currency code.
Determines the minor unit that Money.amount is expressed in. Zero-decimal currencies such as JPY have a minor unit equal to the major unit.
One of 182 values; see the schema.

paymentsarray of Payment

How the sale was paid for. Present on a completed order, and the thing that makes a day's takings reconcilable: an order that says completed without saying how it was paid records that something was sold and nothing about whether any money arrived.
An open order — a tab being split or part-paid — may also carry payments: a partial payment is appended while the tab stays open, and what remains is derived from the lines minus these payments and never stored. The server refuses a payment larger than what remains, and completes the order in the write whose payments cover the sale.

idstring · uuid
The payment's id. Minted by the device, so a retry of the same tender converges on the same row instead of recording the money twice; the server mints one when a writer does not supply it. A refund names it as payment_id, and a card refund is reversed against it, so it is returned with every read of the order and never renumbered.

amountMoney

Required
The total taken by this payment, including any tip.
Following Square: the tender's amount is what the customer parted with, and tip is the portion of it that is not for goods. Modelling it the other way — an amount that excludes the tip — means every reconciliation has to remember to add the two back together, and one place that forgets is a day's takings that do not balance.

amountinteger · int64

Required
The amount, as a whole number of the currency's minor unit. May be negative to express a refund, discount or credit.

currencyCurrency

Required
ISO 4217 currency code.
Determines the minor unit that Money.amount is expressed in. Zero-decimal currencies such as JPY have a minor unit equal to the major unit.
One of 182 values; see the schema.

buyer_suppliedMoney

Nullable
What the customer physically handed over. Cash only.
Recorded rather than assumed so that change is derived from it: a note tendered for a smaller sale is the ordinary case, and the drawer at close must agree with the sum of what went in.

amountinteger · int64

Required
The amount, as a whole number of the currency's minor unit. May be negative to express a refund, discount or credit.

currencyCurrency

Required
ISO 4217 currency code.
Determines the minor unit that Money.amount is expressed in. Zero-decimal currencies such as JPY have a minor unit equal to the major unit.
One of 182 values; see the schema.

card_brandstring

Read only
The scheme the processor read off the card, in its own words ("visa", "mastercard", "amex"). Card payments only; absent where the processor reports none.

card_confirmationstring · enum

Read only
How the card payment was confirmed against the checkout the processor says took it: confirmed when the approved checkout's amount matched and it belongs to this sale, unconfirmed when it is not approved, belongs to another sale, or took a different amount. An unconfirmed sale is still recorded — the money may already have moved — but the payment is flagged for a person to reconcile. The server's word, never the till's. Absent for a payment that is not a card, and for a card the till recorded by reference on a third-party terminal, which has no checkout to confirm against.
confirmedunconfirmed

card_last4string

Read only
The last four digits of the card that paid, as the processor masked them — what a payment shows as "Visa •• 4242", and what a person types into the order list's search to find the sale. Card payments only; absent where the processor reports none. Never the PAN.
≤ 4 chars

change_backMoney

NullableRead only
Change handed back, calculated by the server as buyer_supplied - amount and never accepted from a client.
Derived rather than submitted because it is the one figure a till could get wrong in a way that balances on screen and not in the drawer.

amountinteger · int64

Required
The amount, as a whole number of the currency's minor unit. May be negative to express a refund, discount or credit.

currencyCurrency

Required
ISO 4217 currency code.
Determines the minor unit that Money.amount is expressed in. Zero-decimal currencies such as JPY have a minor unit equal to the major unit.
One of 182 values; see the schema.

fingerprintstring

Read only
The processor's card-alias token, never the PAN, for a card payment it could identify. It is what lets a returning card be recognised without the card number. Card payments only; absent for cash and vouchers, and for a card payment the processor did not identify.
≤ 256 chars

gift_card_hold_idstring · uuid
The hold a till took on the voucher's card before tendering it (batchCreateGiftCardHolds), which this payment settles. Absent for a voucher tendered offline, which is spent against what the till last knew of the card.

line_idsarray of string · uuid
The lines this payment settled, when the till knows the split: a share pays whole lines, so a reopened tab shows the unpaid lines rather than a number, and a mistake cannot charge somebody twice (tabs item 13).
Empty when the payment named no lines — a whole-sale tender, an even split, a card share settling what is left, and every payment recorded before this existed. Empty and absent mean the same thing and are accepted alike, and a till sends the empty array.

memberMemberSnapshot

Nullable
The member who took this tender — the terminal operator who took the tip, not whoever rang the sale. The kept tip rule follows it. Absent for a payment recorded by something that is not a person.

idstring · uuid

Required
The roster's id, checked against the merchant's memberships.

namestring

Required
What the member was called.
≥ 1 chars

emailstring · email

Required
The member's address.

rolestring · enum

Required
The role the member held.
ownermanagerstaff

methodstring · enum

Required
cash — taken into the drawer. Settled by definition: nothing to capture, nothing that can later fail.
card — captured through the PSP. Recorded here as what the terminal reported, not as proof of settlement.
voucher — a gift card or credit note redeemed against the sale.
account — put on a customer's account to settle later. Requires the sale to name the customer (customer_id) and the merchant to have an open customer account for them; the till chooses the account at the tender and links the sale to its customer (retail: customer accounts).
A loyalty redemption is not a payment method any more: a reward redeems against its discount definition, the order line carries the discount, and the server spends the guest's points when the order is written. The points method was retired.
external — money a channel took before the order reached the venue: an online storefront, a delivery platform. The merchant settles with that channel, so the tender records the platform's reference rather than a card payment this merchant never captured. Only valid on an order a channel wrote, and the reference is required.
cashcardvoucheraccountexternal

pinstring
A voucher's PIN — the scratch-off second factor that proves possession of the card whose code is in reference (gift cards item 20). Required only when the card carries a PIN (a pre-printed or merchant-supplied code); a card with a generated code needs none, and the server refuses a sale whose voucher cannot prove the PIN. Only the hash is stored and compared; the plaintext never comes back.
≤ 12 chars

referencestring
The PSP's identifier for a card payment, or a voucher's code. Cash has neither and needs neither. Required for an external tender: it is the platform's own transaction or order reference, which is what reconciliation against that channel relies on.
≤ 128 chars

tipMoney

Nullable
The part of amount that is a gratuity rather than payment for goods.
Present because hospitality is not an edge case here: a bar or restaurant tab is the core flow, and a till that cannot record a tip cannot be used in one.

amountinteger · int64

Required
The amount, as a whole number of the currency's minor unit. May be negative to express a refund, discount or credit.

currencyCurrency

Required
ISO 4217 currency code.
Determines the minor unit that Money.amount is expressed in. Zero-decimal currencies such as JPY have a minor unit equal to the major unit.
One of 182 values; see the schema.

pickup_atstring · date-time

Read only
When the guest was told they could collect. Set by whoever took the order — the ordering page, or a till ringing a takeaway for collection at a time — and kept however the order is written afterwards: a later write that omits it leaves the promised time alone. Absent on an order nobody promised a time for.

ready_atstring · date-time

Read only
When the venue said an asked-for order was ready for the guest, recorded as a ready fact — the Ready button, the kitchen bumping the order's last ticket, or an integration. Absent until then, and again after a ready_undone takes it back. Read from the facts, never from whether the kitchen has any tickets for the order.

ready_to_pay_atstring · date-time

Read only
When a guest at the table said they were ready to pay (order-and-pay), on an open order. Absent until they tap; carried on the change feed as an order update, which is how the till shows the call.

received_atTimestamp

RequiredRead only
Server-assigned RFC 3339 timestamp, always UTC.
Server-assigned because device clocks drift and cannot be trusted for ordering — a till that has been powered off for a week may come back with a clock hours out. Where the device's own view of time matters it is carried separately in client_created_at.

referencestring
Short human-readable reference shown on the receipt and used by staff to find the order. Unique per location per business day.
≤ 64 chars

refundedMoney

A monetary amount in a specific currency: Square's Money, and Stripe's amount beside its currency.
The amount is always an integer count of the currency's minor unit — pence for GBP, cents for USD. Zero-decimal currencies such as JPY have a minor unit equal to their major unit, so {"amount": 500, "currency": "JPY"} is ¥500 while {"amount": 500, "currency": "GBP"} is £5.00.
Floating point is never used for money anywhere in this API. Binary floats cannot represent most decimal fractions exactly, so accumulating them across the line items of an order produces totals that disagree with the printed receipt by a penny. Integer minor units make every arithmetic operation exact.

amountinteger · int64

Required
The amount, as a whole number of the currency's minor unit. May be negative to express a refund, discount or credit.

currencyCurrency

Required
ISO 4217 currency code.
Determines the minor unit that Money.amount is expressed in. Zero-decimal currencies such as JPY have a minor unit equal to the major unit.
One of 182 values; see the schema.

rejection_notestring

Read only
The staff member's words, in their own voice, required when the reason is other.
≤ 512 chars

rejection_reasonstring · enum

Read only
Why an asked-for order was turned down, when it was. timed_out is the sweep that rejects an unanswered order past its location's deadline.
sold_outclosedtoo_busyothertimed_out

service_chargeMoney

Nullable
The discretionary service charge added to this bill (order-ledger item 9), in the order's currency, or null when none. Never folded into goods; part of the total payments must sum to.

amountinteger · int64

Required
The amount, as a whole number of the currency's minor unit. May be negative to express a refund, discount or credit.

currencyCurrency

Required
ISO 4217 currency code.
Determines the minor unit that Money.amount is expressed in. Zero-decimal currencies such as JPY have a minor unit equal to the major unit.
One of 182 values; see the schema.

service_charge_taxMoney

Nullable
The tax on the service charge, its own line and never folded into goods tax_total, or null when the charge is not taxed.

amountinteger · int64

Required
The amount, as a whole number of the currency's minor unit. May be negative to express a refund, discount or credit.

currencyCurrency

Required
ISO 4217 currency code.
Determines the minor unit that Money.amount is expressed in. Zero-decimal currencies such as JPY have a minor unit equal to the major unit.
One of 182 values; see the schema.

service_charge_tax_class_idstring · uuid

Nullable
The tax class the service charge was taxed under (decision record 0054), snapshotted from the location's config at write, or null when the charge is not taxed.

service_charge_tax_rate_percentagePercentage

Nullable
The combined tax rate that applied to the service charge, or null when not taxed.
pattern ^(100(\.0{1,4})?|(0|[1-9][0-9]?)(\.[0-9]{1,4})?)$

sourcestring

Read only
Which caller wrote the order — the device id for a pos or table order, storefront for one placed on a venue's ordering page, and the integration client id for an integration one. Set server-side from the caller, and an identifier's provenance, not a name.

source_namestring

Read only
The name the merchant gave the integration that wrote an integration order, as it was when the order was recorded; empty for any other channel.

statestring · enum

Required
open is a sale in progress, shared with the devices at its location. completed is finalised and immutable. canceled is an open order that ended without being paid. voided is a completed order reversed. Neither of the last two is deleted, so the audit trail survives.
opencompletedcanceledvoided

table_idstring · uuid

Nullable
The table an open order is parked on, if any. Occupancy is derived from this.

tipsMoney

A monetary amount in a specific currency: Square's Money, and Stripe's amount beside its currency.
The amount is always an integer count of the currency's minor unit — pence for GBP, cents for USD. Zero-decimal currencies such as JPY have a minor unit equal to their major unit, so {"amount": 500, "currency": "JPY"} is ¥500 while {"amount": 500, "currency": "GBP"} is £5.00.
Floating point is never used for money anywhere in this API. Binary floats cannot represent most decimal fractions exactly, so accumulating them across the line items of an order produces totals that disagree with the printed receipt by a penny. Integer minor units make every arithmetic operation exact.

amountinteger · int64

Required
The amount, as a whole number of the currency's minor unit. May be negative to express a refund, discount or credit.

currencyCurrency

Required
ISO 4217 currency code.
Determines the minor unit that Money.amount is expressed in. Zero-decimal currencies such as JPY have a minor unit equal to the major unit.
One of 182 values; see the schema.

totalsOrderTotals

Required
The money on an order, broken out.
These are computed and sent by the device, then independently recomputed by the server on receipt. A mismatch is rejected with 422 rather than quietly corrected: if the till printed a receipt showing one total and the server stored another, the merchant has an unreconcilable discrepancy and no way to know which is right. Failing loudly surfaces a till running stale tax configuration while it is still one order, not a month's worth.

cash_roundingMoney

Nullable
How much a cash settlement rounded the price, signed (docs/decisions/0015): a €10.02 bill rounded up to €10.05 has cash_rounding 3, and the cash payment's goods portion is the total plus this. The till computes it from the location's cash step; the server recomputes and rejects a mismatch. Zero on a sale no cash settles, and cards are never rounded.

amountinteger · int64

Required
The amount, as a whole number of the currency's minor unit. May be negative to express a refund, discount or credit.

currencyCurrency

Required
ISO 4217 currency code.
Determines the minor unit that Money.amount is expressed in. Zero-decimal currencies such as JPY have a minor unit equal to the major unit.
One of 182 values; see the schema.

discount_totalMoney

Required
A monetary amount in a specific currency: Square's Money, and Stripe's amount beside its currency.
The amount is always an integer count of the currency's minor unit — pence for GBP, cents for USD. Zero-decimal currencies such as JPY have a minor unit equal to their major unit, so {"amount": 500, "currency": "JPY"} is ¥500 while {"amount": 500, "currency": "GBP"} is £5.00.
Floating point is never used for money anywhere in this API. Binary floats cannot represent most decimal fractions exactly, so accumulating them across the line items of an order produces totals that disagree with the printed receipt by a penny. Integer minor units make every arithmetic operation exact.

amountinteger · int64

Required
The amount, as a whole number of the currency's minor unit. May be negative to express a refund, discount or credit.

currencyCurrency

Required
ISO 4217 currency code.
Determines the minor unit that Money.amount is expressed in. Zero-decimal currencies such as JPY have a minor unit equal to the major unit.
One of 182 values; see the schema.

service_chargeMoney

A monetary amount in a specific currency: Square's Money, and Stripe's amount beside its currency.
The amount is always an integer count of the currency's minor unit — pence for GBP, cents for USD. Zero-decimal currencies such as JPY have a minor unit equal to their major unit, so {"amount": 500, "currency": "JPY"} is ¥500 while {"amount": 500, "currency": "GBP"} is £5.00.
Floating point is never used for money anywhere in this API. Binary floats cannot represent most decimal fractions exactly, so accumulating them across the line items of an order produces totals that disagree with the printed receipt by a penny. Integer minor units make every arithmetic operation exact.

amountinteger · int64

Required
The amount, as a whole number of the currency's minor unit. May be negative to express a refund, discount or credit.

currencyCurrency

Required
ISO 4217 currency code.
Determines the minor unit that Money.amount is expressed in. Zero-decimal currencies such as JPY have a minor unit equal to the major unit.
One of 182 values; see the schema.

service_charge_taxMoney

Nullable
The tax on the service charge (decision record 0054), its own line and never folded into goods tax_total. Computed server-side from the location's service-charge tax class and the sale's fulfilment and business date. Null when the charge is not taxed.

amountinteger · int64

Required
The amount, as a whole number of the currency's minor unit. May be negative to express a refund, discount or credit.

currencyCurrency

Required
ISO 4217 currency code.
Determines the minor unit that Money.amount is expressed in. Zero-decimal currencies such as JPY have a minor unit equal to the major unit.
One of 182 values; see the schema.

subtotalMoney

Required
A monetary amount in a specific currency: Square's Money, and Stripe's amount beside its currency.
The amount is always an integer count of the currency's minor unit — pence for GBP, cents for USD. Zero-decimal currencies such as JPY have a minor unit equal to their major unit, so {"amount": 500, "currency": "JPY"} is ¥500 while {"amount": 500, "currency": "GBP"} is £5.00.
Floating point is never used for money anywhere in this API. Binary floats cannot represent most decimal fractions exactly, so accumulating them across the line items of an order produces totals that disagree with the printed receipt by a penny. Integer minor units make every arithmetic operation exact.

amountinteger · int64

Required
The amount, as a whole number of the currency's minor unit. May be negative to express a refund, discount or credit.

currencyCurrency

Required
ISO 4217 currency code.
Determines the minor unit that Money.amount is expressed in. Zero-decimal currencies such as JPY have a minor unit equal to the major unit.
One of 182 values; see the schema.

tax_totalMoney

Required
A monetary amount in a specific currency: Square's Money, and Stripe's amount beside its currency.
The amount is always an integer count of the currency's minor unit — pence for GBP, cents for USD. Zero-decimal currencies such as JPY have a minor unit equal to their major unit, so {"amount": 500, "currency": "JPY"} is ¥500 while {"amount": 500, "currency": "GBP"} is £5.00.
Floating point is never used for money anywhere in this API. Binary floats cannot represent most decimal fractions exactly, so accumulating them across the line items of an order produces totals that disagree with the printed receipt by a penny. Integer minor units make every arithmetic operation exact.

amountinteger · int64

Required
The amount, as a whole number of the currency's minor unit. May be negative to express a refund, discount or credit.

currencyCurrency

Required
ISO 4217 currency code.
Determines the minor unit that Money.amount is expressed in. Zero-decimal currencies such as JPY have a minor unit equal to the major unit.
One of 182 values; see the schema.

totalMoney

Required
A monetary amount in a specific currency: Square's Money, and Stripe's amount beside its currency.
The amount is always an integer count of the currency's minor unit — pence for GBP, cents for USD. Zero-decimal currencies such as JPY have a minor unit equal to their major unit, so {"amount": 500, "currency": "JPY"} is ¥500 while {"amount": 500, "currency": "GBP"} is £5.00.
Floating point is never used for money anywhere in this API. Binary floats cannot represent most decimal fractions exactly, so accumulating them across the line items of an order produces totals that disagree with the printed receipt by a penny. Integer minor units make every arithmetic operation exact.

amountinteger · int64

Required
The amount, as a whole number of the currency's minor unit. May be negative to express a refund, discount or credit.

currencyCurrency

Required
ISO 4217 currency code.
Determines the minor unit that Money.amount is expressed in. Zero-decimal currencies such as JPY have a minor unit equal to the major unit.
One of 182 values; see the schema.

updated_atTimestamp

RequiredRead only
Server-assigned RFC 3339 timestamp, always UTC.
Server-assigned because device clocks drift and cannot be trusted for ordering — a till that has been powered off for a week may come back with a clock hours out. Where the device's own view of time matters it is carried separately in client_created_at.

versionVersion

RequiredRead only
Optimistic concurrency version, raised by the server on every write. A version is never lower than one already returned for the resource, though it may rise by more than one.
Returned in the ETag response header as well as in the body. Send it back in If-Match on an update and the write is rejected with 412 if anyone else has written since — which is what stops two tills silently overwriting each other's edit to the same product when both come back online at once.
≥ 1

void_memberMemberSnapshot

Nullable
The staff member who voided this order, when it has been voided and the void was made by a person. Nil for a sale that was never voided, or one voided by something that is not a person.

idstring · uuid

Required
The roster's id, checked against the merchant's memberships.

namestring

Required
What the member was called.
≥ 1 chars

emailstring · email

Required
The member's address.

rolestring · enum

Required
The role the member held.
ownermanagerstaff

void_notestring
The staff member's note on the void, required when the reason is other.

void_reasonstring · enum
Why this sale was voided. Set on a voided order.
customer_canceledstaff_errorrefundother

voided_atstring · date-time

Nullable
When the sale was voided.

400
The request could not be parsed. Malformed JSON, a bad query parameter, or a header that failed to decode, among them an API-Version later than the server speaks or not a date (api-version-unknown, with the server's own in api_version).
Distinct from 422: a 400 never reached validation, so invalid_params is absent. Retrying without changing the request will fail again, except that a request refused for its API-Version goes once the server is updated.

401
No credentials, or credentials that could not be verified — missing bearer token, malformed JWT, expired token, or a signature that failed against the issuer's JWKS.
Refresh the token and retry once. Repeated 401 after a refresh means the device needs to re-enrol.

403
Authenticated, but not permitted. The token is valid and its merchant was resolved, but the caller's role does not allow this operation, or the target belongs to a different merchant.
Cross-tenant access is reported as 403 on a resource the caller may not see, and as 404 where even confirming existence would leak information. Retrying will not help.

404
No such resource, or none visible to this caller.
Also returned instead of 403 where acknowledging existence would itself leak information — so a 404 does not prove the id is unused globally, only that it is not yours.

410
The request names an API-Version this server no longer serves (docs/decisions/0011). Nothing in it was read. api_version names the version the server speaks: the client is behind, and sends the request again once it is updated.

415
The request Content-Type is not supported. This API accepts application/json on all mutations.

422
The request parsed but failed validation.
invalid_params lists every failing field with a JSON Pointer, not just the first, so a client can mark up a whole form in one pass rather than making the user fix errors one round trip at a time.
Also returned when an Idempotency-Key is replayed with a different body, and when device-computed order totals disagree with the server's recomputation.

429
Rate limit exceeded. Honour Retry-After rather than applying your own backoff.
A fleet of tills coming back online together after an outage is the realistic cause, which is exactly when uncoordinated client-side retry turns a brief outage into a sustained one. The limit is per process, and per site for what records trade there — a request spends its site's budget, and a till's own smaller one inside it — and per (client, merchant) for everything else; no RateLimit field is sent, so this response and its Retry-After are the whole of the contract.

500
Something failed on our side. trace_id identifies the request in our tracing — quote it in a support ticket.
The body never carries internal detail: no SQL, no stack traces, no upstream error strings. Safe to retry with the same Idempotency-Key.

503
Temporarily unable to serve the request — a dependency is down or the service is shedding load.
Retry with the same Idempotency-Key after Retry-After. This is always safe: a request that did take effect before the failure will be recognised as a replay.
Request
curl -X POST 'https://api.tenvelo.com/v1/orders/0192f1e4-7c3a-7b2e-9f10-5d6c7e8f9a0b/accept' \ -H "Authorization: Bearer $TOKEN"
Response
{ "id": "0192f1e4-7c3a-7b2e-9f10-5d6c7e8f9a0b", "name": "Sam", "acceptance": "pending", "age_confirmed": false, "age_minimum": 0, "business_date": "2026-09-11", "channel": "pos", "channel_cost": { "amount": 1250, "currency": "GBP" }, "client_created_at": "2026-09-11T09:30:00Z", "closed_at": "2026-09-11T09:30:00Z", "covers": 0, "created_at": "2026-09-08T09:41:12Z", "currency": "AED", "customer": { "id": "0192f1e4-7c3a-7b2e-9f10-5d6c7e8f9a0b", "name": "string", "loyalty_points": 0, "rewards": [ { "id": "0192f1e4-7c3a-7b2e-9f10-5d6c7e8f9a0b", "name": "string", "cost_points": 0, "discount_id": "0192f1e4-7c3a-7b2e-9f10-5d6c7e8f9a0b" } ], "tags": "string", "tier": { "current": { "id": "0192f1e4-7c3a-7b2e-9f10-5d6c7e8f9a0b", "name": "string", "earn_rate_percentage": "-12.5", "threshold_spend": { "amount": 1250, "currency": "GBP" }, "threshold_visits": 0, "window_days": 0 }, "next": { "id": "0192f1e4-7c3a-7b2e-9f10-5d6c7e8f9a0b", "name": "string", "earn_rate_percentage": "-12.5", "threshold_spend": { "amount": 1250, "currency": "GBP" }, "threshold_visits": 0, "window_days": 0 }, "spend_needed": { "amount": 1250, "currency": "GBP" }, "visits_needed": 0 }, "version": 0 }, "customer_id": "0192f1e4-7c3a-7b2e-9f10-5d6c7e8f9a0b", "delivery_address": { "address_line_1": "12 Bridge Street", "address_line_2": "string", "address_line_3": "string", "administrative_district_level_1": "Somerset", "administrative_district_level_2": "string", "country": "ZZ", "locality": "Bristol", "postal_code": "BS1 4ST", "sublocality": "string" }, "delivery_fee": { "amount": 1250, "currency": "GBP" }, "device_id": "0192f1e4-7c3a-7b2e-9f10-5d6c7e8f9a0b", "device_seq": 0, "document": { "kind": "invoice", "number": 148, "series": "B1-T3" }, "drawer_session_id": "0192f1e4-7c3a-7b2e-9f10-5d6c7e8f9a0b", "email_receipt": false, "external_reference": "string", "flags": [ "string" ], "fulfillment_status": "received", "fulfillment_type": "on_premises", "line_items": [ { "id": "0192f1e4-7c3a-7b2e-9f10-5d6c7e8f9a0b", "name": "Flat white", "approved_by_member": { "id": "0192f1e4-7c3a-7b2e-9f10-5d6c7e8f9a0b", "name": "string", "email": "ada@example.com", "role": "owner" }, "category_id": "0192f1e4-7c3a-7b2e-9f10-5d6c7e8f9a0b", "category_name": "string", "comp_reason": "string", "course": 1, "discount": { "amount": 1250, "currency": "GBP" }, "discount_id": "0192f1e4-7c3a-7b2e-9f10-5d6c7e8f9a0b", "discount_name": "string", "gift_card_code": "string", "gift_card_token_hash": "string", "modifiers": [ { "id": "0192f1e4-7c3a-7b2e-9f10-5d6c7e8f9a0b", "name": "Oat milk", "price_delta": { "amount": 1250, "currency": "GBP" } } ], "multibuy": { "every": 2, "price": { "amount": 1250, "currency": "GBP" } }, "note": "string", "origin": "till", "product_id": "0192f1e4-7c3a-7b2e-9f10-5d6c7e8f9a0b", "product_type": "standard", "quantity": "3", "seat": 1, "sent_at": "2026-09-11T09:30:00Z", "serials": [], "tax": { "amount": 1250, "currency": "GBP" }, "tax_breakdown": [ { "amount": { "amount": 1250, "currency": "GBP" }, "inclusive": false, "percentage": "20", "rate_id": "0192f1e4-7c3a-7b2e-9f10-5d6c7e8f9a0b" } ], "tax_inclusive": false, "tax_rate_percentage": "20", "total": { "amount": 1250, "currency": "GBP" }, "unit_of_measure": "each", "unit_price": { "amount": 1250, "currency": "GBP" }, "variant_id": "0192f1e4-7c3a-7b2e-9f10-5d6c7e8f9a0b" } ], "location_id": "0192f1e4-7c3a-7b2e-9f10-5d6c7e8f9a0b", "loyalty_earned": 0, "loyalty_spent": 0, "member": { "id": "0192f1e4-7c3a-7b2e-9f10-5d6c7e8f9a0b", "name": "string", "email": "ada@example.com", "role": "owner" }, "merchant_id": "0192f1e4-7c3a-7b2e-9f10-5d6c7e8f9a0b", "owner_member": { "id": "0192f1e4-7c3a-7b2e-9f10-5d6c7e8f9a0b", "name": "string", "email": "ada@example.com", "role": "owner" }, "paid": { "amount": 1250, "currency": "GBP" }, "payments": [ { "id": "0192f1e4-7c3a-7b2e-9f10-5d6c7e8f9a0b", "amount": { "amount": 1250, "currency": "GBP" }, "buyer_supplied": { "amount": 1250, "currency": "GBP" }, "card_brand": "string", "card_confirmation": "confirmed", "card_last4": "string", "change_back": { "amount": 1250, "currency": "GBP" }, "fingerprint": "string", "gift_card_hold_id": "0192f1e4-7c3a-7b2e-9f10-5d6c7e8f9a0b", "line_ids": [ "0192f1e4-7c3a-7b2e-9f10-5d6c7e8f9a0b" ], "member": { "id": "0192f1e4-7c3a-7b2e-9f10-5d6c7e8f9a0b", "name": "string", "email": "ada@example.com", "role": "owner" }, "method": "cash", "pin": "string", "reference": "pspRef_8829301", "tip": { "amount": 1250, "currency": "GBP" } } ], "pickup_at": "2026-09-11T09:30:00Z", "ready_at": "2026-09-11T09:30:00Z", "ready_to_pay_at": "2026-09-11T09:30:00Z", "received_at": "2026-09-08T09:41:12Z", "reference": "A-0148", "refunded": { "amount": 1250, "currency": "GBP" }, "rejection_note": "string", "rejection_reason": "sold_out", "service_charge": { "amount": 1250, "currency": "GBP" }, "service_charge_tax": { "amount": 1250, "currency": "GBP" }, "service_charge_tax_class_id": "0192f1e4-7c3a-7b2e-9f10-5d6c7e8f9a0b", "service_charge_tax_rate_percentage": "20", "source": "string", "source_name": "string", "state": "open", "table_id": "0192f1e4-7c3a-7b2e-9f10-5d6c7e8f9a0b", "tips": { "amount": 1250, "currency": "GBP" }, "totals": { "cash_rounding": { "amount": 1250, "currency": "GBP" }, "discount_total": { "amount": 1250, "currency": "GBP" }, "service_charge": { "amount": 1250, "currency": "GBP" }, "service_charge_tax": { "amount": 1250, "currency": "GBP" }, "subtotal": { "amount": 1250, "currency": "GBP" }, "tax_total": { "amount": 1250, "currency": "GBP" }, "total": { "amount": 1250, "currency": "GBP" } }, "updated_at": "2026-09-08T09:41:12Z", "version": 7, "void_member": { "id": "0192f1e4-7c3a-7b2e-9f10-5d6c7e8f9a0b", "name": "string", "email": "ada@example.com", "role": "owner" }, "void_note": "string", "void_reason": "customer_canceled", "voided_at": "2026-09-11T09:30:00Z" }
POST/v1/orders/{id}/decline

Turn an online order away

No. declineOrderAuth pos:orders:write
The person the venue's choose-who-accepts rule names turns an online order down, as the till does from the floor, from the manager app. The write is the same rejection a till syncs: the fact's id derives from the order and the answer, so a retry never records twice, and the fold closes the order with the reason the guest is told.
Parameters

idpath · string · uuid
Required
UUIDv7 of the resource.
For resources a device can originate — orders, and their line items — this id is minted by the client before the record is ever synced, which is what makes an offline create idempotent.
Request body application/json · OrderDeclineWrite

notestring
What the guest is told, in the staff member's words. Required when the reason is other.
≤ 512 chars

rejection_reasonstring · enum

Required
Why the order was turned down.
sold_outclosedtoo_busyother
Responses

200
The order as it now stands, turned down.

Order · application/json

idstring · uuid

Required
UUIDv7, minted by the device before the sale is synced. This is what makes an offline order idempotent: replaying it targets the same id, so a retry over flaky wifi cannot create a duplicate sale.

namestring

Nullable
Whose sale it is, while it is open: a customer's name, whatever the shop shouts across the bar. Null is a walk-in being served at a counter right now.
≤ 128 chars

acceptancestring · enum

Read only
Where an asked-for order stands with the venue that must make it, beside its lifecycle: state keeps its four values. A till's own order is accepted as it is created; a channel's — the ordering page, an integration — is pending until a person or a rule takes it on, or it is rejected with a reason. Set by the server, never from the body: acceptance is a fact (engineering, recording what happened, section 12), not a field a client sets.
pendingacceptedrejected

age_confirmedboolean
Whether a sale carrying an age-restricted line recorded that the till confirmed the guest's age before it completed. False both for a sale with no age-restricted line and for one that needed the check and did not record it — the reports compare it with age_minimum to flag the second.
default false

age_minimuminteger · int32
The oldest buyer the sale's age-restricted lines allowed, as the till recorded it: the highest minimum_age among them, 0 when the sale carried none. A completed sale with age_minimum above 0 and age_confirmed false is a counter law miss.
≥ 0 · default 0

business_datestring · date

Read only
The trading day the sale belongs to, in its location's own reckoning: its time zone and the hour its day starts. Set by the server when the sale completes, from when the till says it happened, so a sale rung at 1am on a late night books to the night before. Absent on an order that has not completed.

channelstring · enum

Read only
Where the order came from, set by the server from the caller and never accepted from the body: pos is a till, table a table-side device, online an online storefront, integration a third-party integration. A till cannot attribute a sale to another channel. What the channel is tells an integration whose order arrived from where, which an order_type cannot.
postableonlineintegration

channel_costMoney

What the channel took from the order, at the stated cost in force on the order's business date (online-ordering item 18). Present only for an online order whose channel states a cost, and derived on read from the stated rates and the order's total — never stored, so it can never drift from them.

amountinteger · int64

Required
The amount, as a whole number of the currency's minor unit. May be negative to express a refund, discount or credit.

currencyCurrency

Required
ISO 4217 currency code.
Determines the minor unit that Money.amount is expressed in. Zero-decimal currencies such as JPY have a minor unit equal to the major unit.
One of 182 values; see the schema.

client_created_atstring · date-time

Required
When the device believes the sale happened. Trusted for display — it is what a receipt shows and what staff recognise — but never for ordering or for resolving conflicts, because till clocks drift. Compare with received_at to measure how long a device was offline.

closed_atstring · date-time

Nullable
When the order left open — was completed. A void does not change it; voided_at is when the sale was voided.

coversinteger · int32

RequiredRead only
How many people the party is, as counted at seating on the created fact; zero where nobody counted them. The covers-per-labour-hour and average-spend-per-cover figures are divided by it, so a tab opened without a count adds no covers rather than one.
0–1000 · default 0

created_atTimestamp

RequiredRead only
Server-assigned RFC 3339 timestamp, always UTC.
Server-assigned because device clocks drift and cannot be trusted for ordering — a till that has been powered off for a week may come back with a clock hours out. Where the device's own view of time matters it is carried separately in client_created_at.

currencyCurrency

Required
ISO 4217 currency code.
Determines the minor unit that Money.amount is expressed in. Zero-decimal currencies such as JPY have a minor unit equal to the major unit.
One of 182 values; see the schema.

customerCustomerLoyalty

This order's guest as a till may see them: name, loyalty balance and what it can afford. Carried on the order and its change-feed entry so a till that picks a tab up on another device shows the badge and offers a redemption without a second call. Absent for a walk-in and for a guest since erased or merged; customer_id remains the record. Additive: a client that predates it simply omits it.

idstring · uuid

Required

namestring

Required

loyalty_pointsinteger · int64
The guest's current loyalty balance, earned minus redeemed.

rewardsarray of Reward

The reward catalogue entries this guest can afford, so a till can offer them at redemption. Server-computed from the balance; a guest not enrolled sees none.

idstring · uuid

Required

namestring

Required
What the reward is called to the guest and on the receipt.

cost_pointsinteger · int64

Required
What redeeming it costs, in points.

discount_idstring · uuid

Required
The discount definition the reward is backed by.

tagsstring
The guest's labels, carried so a counter can offer them; still no contact details and no note.

tierLoyaltyTierStatus

A guest's standing in a loyalty programme's ladder at one moment (loyalty item 16): the tier they are on, the next tier above, and how much more they need to reach it.

currentLoyaltyTier

One named level in a loyalty programme's ladder (loyalty item 16). Exactly one of threshold_spend and threshold_visits is set; window_days is the rolling window over which the qualifying spend or visits are counted, and earn_rate_percentage is the multiplier on the programme's base earn rate (10000 is 1x).

idstring · uuid

Required

namestring

Required

earn_rate_percentageRelativePercentage
A percentage that may be negative or above 100, such as a change on a period before or a multiplier, in a decimal string with at most four decimal places: a fall of an eighth is "-12.5", and one and a half times is "150". Read and computed as a Percentage is, in parts per million.
pattern ^-?(0|[1-9][0-9]{0,8})(\.[0-9]{1,4})?$

threshold_spendMoney

A monetary amount in a specific currency: Square's Money, and Stripe's amount beside its currency.
The amount is always an integer count of the currency's minor unit — pence for GBP, cents for USD. Zero-decimal currencies such as JPY have a minor unit equal to their major unit, so {"amount": 500, "currency": "JPY"} is ¥500 while {"amount": 500, "currency": "GBP"} is £5.00.
Floating point is never used for money anywhere in this API. Binary floats cannot represent most decimal fractions exactly, so accumulating them across the line items of an order produces totals that disagree with the printed receipt by a penny. Integer minor units make every arithmetic operation exact.

amountinteger · int64

Required
The amount, as a whole number of the currency's minor unit. May be negative to express a refund, discount or credit.

currencyCurrency

Required
ISO 4217 currency code.
Determines the minor unit that Money.amount is expressed in. Zero-decimal currencies such as JPY have a minor unit equal to the major unit.
One of 182 values; see the schema.

threshold_visitsinteger · int64
The number of completed linked orders that reaches the tier.

window_daysinteger · int32

nextLoyaltyTier

One named level in a loyalty programme's ladder (loyalty item 16). Exactly one of threshold_spend and threshold_visits is set; window_days is the rolling window over which the qualifying spend or visits are counted, and earn_rate_percentage is the multiplier on the programme's base earn rate (10000 is 1x).

idstring · uuid

Required

namestring

Required

earn_rate_percentageRelativePercentage
A percentage that may be negative or above 100, such as a change on a period before or a multiplier, in a decimal string with at most four decimal places: a fall of an eighth is "-12.5", and one and a half times is "150". Read and computed as a Percentage is, in parts per million.
pattern ^-?(0|[1-9][0-9]{0,8})(\.[0-9]{1,4})?$

threshold_spendMoney

A monetary amount in a specific currency: Square's Money, and Stripe's amount beside its currency.
The amount is always an integer count of the currency's minor unit — pence for GBP, cents for USD. Zero-decimal currencies such as JPY have a minor unit equal to their major unit, so {"amount": 500, "currency": "JPY"} is ¥500 while {"amount": 500, "currency": "GBP"} is £5.00.
Floating point is never used for money anywhere in this API. Binary floats cannot represent most decimal fractions exactly, so accumulating them across the line items of an order produces totals that disagree with the printed receipt by a penny. Integer minor units make every arithmetic operation exact.

amountinteger · int64

Required
The amount, as a whole number of the currency's minor unit. May be negative to express a refund, discount or credit.

currencyCurrency

Required
ISO 4217 currency code.
Determines the minor unit that Money.amount is expressed in. Zero-decimal currencies such as JPY have a minor unit equal to the major unit.
One of 182 values; see the schema.

threshold_visitsinteger · int64
The number of completed linked orders that reaches the tier.

window_daysinteger · int32

spend_neededMoney

A monetary amount in a specific currency: Square's Money, and Stripe's amount beside its currency.
The amount is always an integer count of the currency's minor unit — pence for GBP, cents for USD. Zero-decimal currencies such as JPY have a minor unit equal to their major unit, so {"amount": 500, "currency": "JPY"} is ¥500 while {"amount": 500, "currency": "GBP"} is £5.00.
Floating point is never used for money anywhere in this API. Binary floats cannot represent most decimal fractions exactly, so accumulating them across the line items of an order produces totals that disagree with the printed receipt by a penny. Integer minor units make every arithmetic operation exact.

amountinteger · int64

Required
The amount, as a whole number of the currency's minor unit. May be negative to express a refund, discount or credit.

currencyCurrency

Required
ISO 4217 currency code.
Determines the minor unit that Money.amount is expressed in. Zero-decimal currencies such as JPY have a minor unit equal to the major unit.
One of 182 values; see the schema.

visits_neededinteger · int64
The visits still needed to reach next, when next is reached by visits.

versioninteger · int64

Required
The guest record's version, for the optimistic write a picker makes; it may be stale by the time the write lands, and the batch then refuses.

customer_idstring · uuid

Nullable
The guest this sale is recorded against, if any. Null for a walk-in.

delivery_addressAddress

Where a delivery order goes, as the writer stated it, when the order's fulfillment is delivery.

address_line_1string

Required
First line of the address — street number, street name, building name.
≤ 255 chars

address_line_2string
Second line of the address, if any.
≤ 255 chars

address_line_3string
Third line of the address, if any.
≤ 255 chars

administrative_district_level_1string
A civil entity within the country. The state in the US; the county in the UK.
≤ 128 chars

administrative_district_level_2string
A civil entity within administrative_district_level_1.
≤ 128 chars

countryCountry

Required
ISO 3166-1 alpha-2 country code.
ZZ is the unknown/unspecified placeholder.
One of 250 values; see the schema.

localitystring
The city or town.
≤ 128 chars

postal_codestring
The postal or ZIP code.
≤ 32 chars

sublocalitystring
A civil region within the locality, if any.
≤ 128 chars

delivery_feeMoney

Nullable
The venue's delivery charge on a delivered order (online-ordering: a shop may charge for delivery), snapshotted from its settings at write, or null when none. Part of the total; never folded into goods or their tax.

amountinteger · int64

Required
The amount, as a whole number of the currency's minor unit. May be negative to express a refund, discount or credit.

currencyCurrency

Required
ISO 4217 currency code.
Determines the minor unit that Money.amount is expressed in. Zero-decimal currencies such as JPY have a minor unit equal to the major unit.
One of 182 values; see the schema.

device_idstring · uuid
The till that last wrote the order. On an open order this is not ownership — any device at the location may pick a tab up, which is the entire point.

device_seqinteger · int64

Nullable
The device's monotonic sequence for this write, if the till recorded one.

documentOrderDocument

The fiscal document a completed order is recorded as, in the per-till series 0016 builds. Every sales document a till issues belongs to a series it was issued at enrolment, and the number is a gap-free counter in that series, incremented in the same transaction that completes the order. Printed on the receipt and sent with the order; the server stores it and refuses a duplicate (series, number).
This is the number a market's fiscal rules are about — the correlative number within a series. It is not the order's reference, which stays the short per-day call number for staff to find a sale.

kindstring · enum

Required
What the document is. invoice is the ordinary receipt — the simplified invoice most markets call a receipt. A full invoice and a rectifying document will be separate kinds, each in its own series.
invoice
default invoice

numberinteger · int64

Required
The gap-free sequence number within the series, starting at 1. Never reused: a void keeps its number, and a correction is a new document in a rectifying series.
≥ 1

seriesstring

Required
The series this document belongs to: a short code issued to one till at enrolment (e.g. B1-T3), one per device and kind of document. The ordinary receipt is in the invoice series.
≤ 32 chars

drawer_session_idstring · uuid

Nullable
The drawer session this sale was rung in, if any. Null otherwise.

email_receiptboolean
Whether the customer on this order asked for its receipt to be emailed. The address is always the customer record's — never typed onto the order, which is a financial record — and only honoured when the guest has consented. Additive, so a till that predates it simply omits it.
default false

external_referencestring

Read only
The writer's own reference for the order, when one was given.
≤ 128 chars

flagsarray of OrderFlagKind

Read only
The kinds of the flags still open on the order, which the books could not settle; absent when none is. Read beside the order as refunded is, and left out of the change feed.

fulfillment_statusstring · enum

Read only
Where an asked-for order has got to, for the guest and the venue: received until the venue takes it on, preparing once accepted, ready once said to be, collected once completed, or rejected or canceled. Derived from acceptance, ready_at and state when the order is read, never stored, so a client shows it rather than working it out again. Toast's fulfillmentStatus. Absent on a till's own sale, which is not asked for.
receivedpreparingreadycollectedrejectedcanceled

fulfillment_typestring · enum

Required
How the sale leaves the building, as the glossary names it and a tax rule is keyed by (docs/decisions/0014): on_premises is what the law calls eat-in, pickup is takeaway and delivery is delivery — Square's fulfillment type, Toast's dining option. A sale that does not say is on premises.
on_premisespickupdelivery

line_itemsarray of OrderLineItem

Required
What was sold. A completed order has at least one line; an open order may be empty for a moment, while the tab it is has just been started.

idstring · uuid

Required
UUIDv7, minted by the device.

namestring

Required
Product name as sold. Snapshot; never re-read from the product.
1–255 chars

approved_by_memberMemberSnapshot

Nullable
The manager or owner who authorised a staff member's discount or comp above the merchant's discount_approval_threshold_minor/discount_approval_threshold_percentage or a comp when comp_requires_manager is set, as they were then; null when no approval was needed.

idstring · uuid

Required
The roster's id, checked against the merchant's memberships.

namestring

Required
What the member was called.
≥ 1 chars

emailstring · email

Required
The member's address.

rolestring · enum

Required
The role the member held.
ownermanagerstaff

category_idstring · uuid

RequiredNullable
The category the product was filed under when the line was rung, for reporting. Snapshot: moving the product to another category later moves no sale. Null on an ad-hoc line or an uncategorised product.

category_namestring

Required
The category's name when the line was rung, so a report of past sales reads as they were filed. Snapshot; empty when category_id is null.
≤ 255 chars

comp_reasonstring
Why this line was given away. Present on a comp — an item given away at no charge — and means something different from a discount, so it is reported separately. Required when the line is a comp.
≤ 512 chars

courseinteger · int32

Nullable
The course this line belongs to, in a full-service kitchen — starters, mains, desserts. Set on the till when ringing to a course, and used to hold or fire a course from the till. Null for a single-course counter sale or a course-less line. Held courses are not sent (sent_at null) until they are fired.
≥ 1

discountMoney

A monetary amount in a specific currency: Square's Money, and Stripe's amount beside its currency.
The amount is always an integer count of the currency's minor unit — pence for GBP, cents for USD. Zero-decimal currencies such as JPY have a minor unit equal to their major unit, so {"amount": 500, "currency": "JPY"} is ¥500 while {"amount": 500, "currency": "GBP"} is £5.00.
Floating point is never used for money anywhere in this API. Binary floats cannot represent most decimal fractions exactly, so accumulating them across the line items of an order produces totals that disagree with the printed receipt by a penny. Integer minor units make every arithmetic operation exact.

amountinteger · int64

Required
The amount, as a whole number of the currency's minor unit. May be negative to express a refund, discount or credit.

currencyCurrency

Required
ISO 4217 currency code.
Determines the minor unit that Money.amount is expressed in. Zero-decimal currencies such as JPY have a minor unit equal to the major unit.
One of 182 values; see the schema.

discount_idstring · uuid

Nullable
The discount definition applied to this line, for reporting. Null for a line with no discount. Snapshot — the discount is recorded so its use can be attributed even if the definition later changes.

discount_namestring
The discount's name at the time the line was priced, snapshotted on the line — the reason a guest can be told, without re-resolving a definition that may have been renamed or deleted. Empty for a line with no discount.
≤ 200 chars

gift_card_codestring

Nullable
The code on the card being sold, when the line's product is a gift_card — typed or scanned at the till. The server issues the card (or refuses a code already live) when the order completes. Null for any other line.
≤ 64 chars

gift_card_token_hashstring

Nullable
The hash of the balance-page token for the card being sold: SHA-256 over the token's text, in base64url without padding. The device mints the token — 32 random bytes, unpadded base64url — and prints it on the receipt's balance link; only its hash leaves the device, so the token is never on the record of the sale, and the server checks a link by hashing the token it carries (W3C, "Good Practices for Capability URLs"). Absent leaves the card with no balance link until one is made (gift-card-balance-links). Null for any other line.
43–43 chars · pattern ^[A-Za-z0-9_-]{43}$

modifiersarray of OrderLineModifier

The options chosen on this line, snapshotted at the moment of sale. The line's unit_price already includes each option's delta.
The server checks only the shape of these — a negative delta is refused, an option chosen twice is refused — and never refuses a sale because the menu has changed since the till synced. A sale that was correct when rung stays correct.

idstring · uuid

Required
The modifier that was chosen. Kept for reporting, never re-resolved.

namestring

Required
Option name as sold. Snapshot.
1–255 chars

price_deltaMoney

Required
A monetary amount in a specific currency: Square's Money, and Stripe's amount beside its currency.
The amount is always an integer count of the currency's minor unit — pence for GBP, cents for USD. Zero-decimal currencies such as JPY have a minor unit equal to their major unit, so {"amount": 500, "currency": "JPY"} is ¥500 while {"amount": 500, "currency": "GBP"} is £5.00.
Floating point is never used for money anywhere in this API. Binary floats cannot represent most decimal fractions exactly, so accumulating them across the line items of an order produces totals that disagree with the printed receipt by a penny. Integer minor units make every arithmetic operation exact.

amountinteger · int64

Required
The amount, as a whole number of the currency's minor unit. May be negative to express a refund, discount or credit.

currencyCurrency

Required
ISO 4217 currency code.
Determines the minor unit that Money.amount is expressed in. Zero-decimal currencies such as JPY have a minor unit equal to the major unit.
One of 182 values; see the schema.

multibuyMultibuyRule

Nullable
The product's multibuy rule as it stood when the line was rung, snapshotted on the line so the server resolves the gross by the same deal the till did — re-pricing a product never rewrites a sale that was correct. Null on a line with no deal. A rule never applies to a weighed line.

everyinteger

Required
How many units make a run; 3 is the ordinary buy-two-get-one.
2–1000

priceMoney

Required
A monetary amount in a specific currency: Square's Money, and Stripe's amount beside its currency.
The amount is always an integer count of the currency's minor unit — pence for GBP, cents for USD. Zero-decimal currencies such as JPY have a minor unit equal to their major unit, so {"amount": 500, "currency": "JPY"} is ¥500 while {"amount": 500, "currency": "GBP"} is £5.00.
Floating point is never used for money anywhere in this API. Binary floats cannot represent most decimal fractions exactly, so accumulating them across the line items of an order produces totals that disagree with the printed receipt by a penny. Integer minor units make every arithmetic operation exact.

amountinteger · int64

Required
The amount, as a whole number of the currency's minor unit. May be negative to express a refund, discount or credit.

currencyCurrency

Required
ISO 4217 currency code.
Determines the minor unit that Money.amount is expressed in. Zero-decimal currencies such as JPY have a minor unit equal to the major unit.
One of 182 values; see the schema.

notestring
Free text from the till — "oat milk", "no sugar".
≤ 512 chars

originstring · enum

Read only
Where this line was rung from, as the server saw the writer: the till at the counter, a guest's phone on a tab, an ordering channel, an integration. It is the server's word and never the writer's, and it is how the share of a table's spend the table rang itself is told. Absent on a line recorded before origins were.
tillcustomeronlineintegration

product_idstring · uuid

Nullable
The catalogue product, for reporting. Null for an ad-hoc line — a miscellaneous item rung up at a custom price, which every real till needs.

product_typestring · enum

Required
What the product was when the line was rung: a gift_card sold is money taken for a promise, not revenue, and a combo is a set. Square's item_type. Snapshot, copied from the product at the moment of sale; standard on an ad-hoc line.
standardgift_cardcombo

quantityQuantity

Required
How much of something, as a decimal string in the unit_of_measure beside it (each where there is none), as Square's quantity is: three croissants are "3", 1.4 kg of beans is "1.4". A string because a JSON number is a binary float to most parsers.
It has at most as many decimal places as its unit's base unit holds — three in each, g and ml, six in kg and l — and a finer one is refused, never rounded. Tenvelo holds every quantity as an integer of that base unit (thousandths of an each, milligrams, microlitres; docs/decisions/0063); a client that computes with one should read the digits the same way, never through a float.
≤ 26 chars · pattern ^-?(0|[1-9][0-9]*)(\.[0-9]{1,6})?$

seatinteger · int32

Nullable
The seat this line is for, when a table's seats are numbered. Set on the till and carried to the kitchen and to split bills. Null for a counter sale or an unnumbered seat.
≥ 1

sent_atstring · date-time

Nullable
When this line was sent to the kitchen — set by the till when a tab is held or a sale completed, and immutable once set. A kitchen knows what to cook from the lines of a ticket, and a new round on a tab is a new set of sent_at values rather than the old lines re-sent. Null on a line the till has not yet held or completed.

serialsarray of string
The serial numbers of the units this line sold (retail item: serial numbers) — one per unit, in the order they were entered, printed on a product whose track_serial is set. Empty on any other line. A snapshot like the name and price: the record of which physical units left the shelf, so a specific unit sold is traceable to its sale.
default []

taxMoney

A monetary amount in a specific currency: Square's Money, and Stripe's amount beside its currency.
The amount is always an integer count of the currency's minor unit — pence for GBP, cents for USD. Zero-decimal currencies such as JPY have a minor unit equal to their major unit, so {"amount": 500, "currency": "JPY"} is ¥500 while {"amount": 500, "currency": "GBP"} is £5.00.
Floating point is never used for money anywhere in this API. Binary floats cannot represent most decimal fractions exactly, so accumulating them across the line items of an order produces totals that disagree with the printed receipt by a penny. Integer minor units make every arithmetic operation exact.

amountinteger · int64

Required
The amount, as a whole number of the currency's minor unit. May be negative to express a refund, discount or credit.

currencyCurrency

Required
ISO 4217 currency code.
Determines the minor unit that Money.amount is expressed in. Zero-decimal currencies such as JPY have a minor unit equal to the major unit.
One of 182 values; see the schema.

tax_breakdownarray of TaxBreakdownItem

Each rate's share of this line's tax, in the order its rule names the rates, when the line is taxed over several rates (each a separate calculation, each rounding with its own mode). Absent — null — on a line taxed at a single rate, where tax_rate_percentage and tax are the whole story.

amountMoney

Required
A monetary amount in a specific currency: Square's Money, and Stripe's amount beside its currency.
The amount is always an integer count of the currency's minor unit — pence for GBP, cents for USD. Zero-decimal currencies such as JPY have a minor unit equal to their major unit, so {"amount": 500, "currency": "JPY"} is ¥500 while {"amount": 500, "currency": "GBP"} is £5.00.
Floating point is never used for money anywhere in this API. Binary floats cannot represent most decimal fractions exactly, so accumulating them across the line items of an order produces totals that disagree with the printed receipt by a penny. Integer minor units make every arithmetic operation exact.

amountinteger · int64

Required
The amount, as a whole number of the currency's minor unit. May be negative to express a refund, discount or credit.

currencyCurrency

Required
ISO 4217 currency code.
Determines the minor unit that Money.amount is expressed in. Zero-decimal currencies such as JPY have a minor unit equal to the major unit.
One of 182 values; see the schema.

inclusiveboolean

Required
Whether this rate is inside the price (true) or added on top (false).

percentagePercentage

Required
A share of a whole, from "0" to "100", as a percentage in a decimal string with at most four decimal places, as Square's percentage and Stripe Tax's percentage_decimal are: UK VAT at 20% is "20", and an 8.875% US sales tax is "8.875".
A string because a JSON number is a binary float to most parsers, and a float cannot hold most decimal fractions exactly (RFC 7493 §2.2). Tenvelo computes with a percentage as an integer in parts per million ("8.875" is 88750), which every four-place percentage is exactly. A client that computes with one should read the digits the same way, never through a float.
pattern ^(100(\.0{1,4})?|(0|[1-9][0-9]?)(\.[0-9]{1,4})?)$

rate_idstring · uuid

Required
The rate this share belongs to.

tax_inclusiveboolean
Whether unit_price already contains the tax. Snapshot.

tax_rate_percentagePercentage
A share of a whole, from "0" to "100", as a percentage in a decimal string with at most four decimal places, as Square's percentage and Stripe Tax's percentage_decimal are: UK VAT at 20% is "20", and an 8.875% US sales tax is "8.875".
A string because a JSON number is a binary float to most parsers, and a float cannot hold most decimal fractions exactly (RFC 7493 §2.2). Tenvelo computes with a percentage as an integer in parts per million ("8.875" is 88750), which every four-place percentage is exactly. A client that computes with one should read the digits the same way, never through a float.
pattern ^(100(\.0{1,4})?|(0|[1-9][0-9]?)(\.[0-9]{1,4})?)$

totalMoney

Required
A monetary amount in a specific currency: Square's Money, and Stripe's amount beside its currency.
The amount is always an integer count of the currency's minor unit — pence for GBP, cents for USD. Zero-decimal currencies such as JPY have a minor unit equal to their major unit, so {"amount": 500, "currency": "JPY"} is ¥500 while {"amount": 500, "currency": "GBP"} is £5.00.
Floating point is never used for money anywhere in this API. Binary floats cannot represent most decimal fractions exactly, so accumulating them across the line items of an order produces totals that disagree with the printed receipt by a penny. Integer minor units make every arithmetic operation exact.

amountinteger · int64

Required
The amount, as a whole number of the currency's minor unit. May be negative to express a refund, discount or credit.

currencyCurrency

Required
ISO 4217 currency code.
Determines the minor unit that Money.amount is expressed in. Zero-decimal currencies such as JPY have a minor unit equal to the major unit.
One of 182 values; see the schema.

unit_of_measurestring · enum

Nullable
The unit this line was sold in, snapshotted from the product at the moment of sale (the product's own unit on a product line; any unit on an ad-hoc line). Absent means each.
eachkgglml

unit_priceMoney

Required
A monetary amount in a specific currency: Square's Money, and Stripe's amount beside its currency.
The amount is always an integer count of the currency's minor unit — pence for GBP, cents for USD. Zero-decimal currencies such as JPY have a minor unit equal to their major unit, so {"amount": 500, "currency": "JPY"} is ¥500 while {"amount": 500, "currency": "GBP"} is £5.00.
Floating point is never used for money anywhere in this API. Binary floats cannot represent most decimal fractions exactly, so accumulating them across the line items of an order produces totals that disagree with the printed receipt by a penny. Integer minor units make every arithmetic operation exact.

amountinteger · int64

Required
The amount, as a whole number of the currency's minor unit. May be negative to express a refund, discount or credit.

currencyCurrency

Required
ISO 4217 currency code.
Determines the minor unit that Money.amount is expressed in. Zero-decimal currencies such as JPY have a minor unit equal to the major unit.
One of 182 values; see the schema.

variant_idstring · uuid

Nullable
The variant that was sold, for reporting and stock. Null when the product itself is the sellable unit — a product with no variants, or with none picked. Like product_id, it is retained for reporting and never re-resolved: the descriptive and monetary fields on this line are the snapshot that is replayed, so a sale that was correct when rung stays correct even if the catalogue has changed since.

location_idstring · uuid

Required

loyalty_earnedinteger · int64

Read only
The points this sale earned its customer, recorded on the order.

loyalty_spentinteger · int64

Read only
The points this sale redeemed from its customer, recorded on the order.

memberMemberSnapshot

Nullable
The staff member who recorded this order — the person who rang it up — as they were then; nil when no person was attributed.

idstring · uuid

Required
The roster's id, checked against the merchant's memberships.

namestring

Required
What the member was called.
≥ 1 chars

emailstring · email

Required
The member's address.

rolestring · enum

Required
The role the member held.
ownermanagerstaff

merchant_idstring · uuid

RequiredRead only

owner_memberMemberSnapshot

Nullable
The staff member a tab belongs to — who opened it, and whom to ask when nobody has touched it. Checked against the merchant's memberships; nil for an order that was never a tab. Set once at open and only changed through a till's explicit transfer.

idstring · uuid

Required
The roster's id, checked against the merchant's memberships.

namestring

Required
What the member was called.
≥ 1 chars

emailstring · email

Required
The member's address.

rolestring · enum

Required
The role the member held.
ownermanagerstaff

paidMoney

A monetary amount in a specific currency: Square's Money, and Stripe's amount beside its currency.
The amount is always an integer count of the currency's minor unit — pence for GBP, cents for USD. Zero-decimal currencies such as JPY have a minor unit equal to their major unit, so {"amount": 500, "currency": "JPY"} is ¥500 while {"amount": 500, "currency": "GBP"} is £5.00.
Floating point is never used for money anywhere in this API. Binary floats cannot represent most decimal fractions exactly, so accumulating them across the line items of an order produces totals that disagree with the printed receipt by a penny. Integer minor units make every arithmetic operation exact.

amountinteger · int64

Required
The amount, as a whole number of the currency's minor unit. May be negative to express a refund, discount or credit.

currencyCurrency

Required
ISO 4217 currency code.
Determines the minor unit that Money.amount is expressed in. Zero-decimal currencies such as JPY have a minor unit equal to the major unit.
One of 182 values; see the schema.

paymentsarray of Payment

How the sale was paid for. Present on a completed order, and the thing that makes a day's takings reconcilable: an order that says completed without saying how it was paid records that something was sold and nothing about whether any money arrived.
An open order — a tab being split or part-paid — may also carry payments: a partial payment is appended while the tab stays open, and what remains is derived from the lines minus these payments and never stored. The server refuses a payment larger than what remains, and completes the order in the write whose payments cover the sale.

idstring · uuid
The payment's id. Minted by the device, so a retry of the same tender converges on the same row instead of recording the money twice; the server mints one when a writer does not supply it. A refund names it as payment_id, and a card refund is reversed against it, so it is returned with every read of the order and never renumbered.

amountMoney

Required
The total taken by this payment, including any tip.
Following Square: the tender's amount is what the customer parted with, and tip is the portion of it that is not for goods. Modelling it the other way — an amount that excludes the tip — means every reconciliation has to remember to add the two back together, and one place that forgets is a day's takings that do not balance.

amountinteger · int64

Required
The amount, as a whole number of the currency's minor unit. May be negative to express a refund, discount or credit.

currencyCurrency

Required
ISO 4217 currency code.
Determines the minor unit that Money.amount is expressed in. Zero-decimal currencies such as JPY have a minor unit equal to the major unit.
One of 182 values; see the schema.

buyer_suppliedMoney

Nullable
What the customer physically handed over. Cash only.
Recorded rather than assumed so that change is derived from it: a note tendered for a smaller sale is the ordinary case, and the drawer at close must agree with the sum of what went in.

amountinteger · int64

Required
The amount, as a whole number of the currency's minor unit. May be negative to express a refund, discount or credit.

currencyCurrency

Required
ISO 4217 currency code.
Determines the minor unit that Money.amount is expressed in. Zero-decimal currencies such as JPY have a minor unit equal to the major unit.
One of 182 values; see the schema.

card_brandstring

Read only
The scheme the processor read off the card, in its own words ("visa", "mastercard", "amex"). Card payments only; absent where the processor reports none.

card_confirmationstring · enum

Read only
How the card payment was confirmed against the checkout the processor says took it: confirmed when the approved checkout's amount matched and it belongs to this sale, unconfirmed when it is not approved, belongs to another sale, or took a different amount. An unconfirmed sale is still recorded — the money may already have moved — but the payment is flagged for a person to reconcile. The server's word, never the till's. Absent for a payment that is not a card, and for a card the till recorded by reference on a third-party terminal, which has no checkout to confirm against.
confirmedunconfirmed

card_last4string

Read only
The last four digits of the card that paid, as the processor masked them — what a payment shows as "Visa •• 4242", and what a person types into the order list's search to find the sale. Card payments only; absent where the processor reports none. Never the PAN.
≤ 4 chars

change_backMoney

NullableRead only
Change handed back, calculated by the server as buyer_supplied - amount and never accepted from a client.
Derived rather than submitted because it is the one figure a till could get wrong in a way that balances on screen and not in the drawer.

amountinteger · int64

Required
The amount, as a whole number of the currency's minor unit. May be negative to express a refund, discount or credit.

currencyCurrency

Required
ISO 4217 currency code.
Determines the minor unit that Money.amount is expressed in. Zero-decimal currencies such as JPY have a minor unit equal to the major unit.
One of 182 values; see the schema.

fingerprintstring

Read only
The processor's card-alias token, never the PAN, for a card payment it could identify. It is what lets a returning card be recognised without the card number. Card payments only; absent for cash and vouchers, and for a card payment the processor did not identify.
≤ 256 chars

gift_card_hold_idstring · uuid
The hold a till took on the voucher's card before tendering it (batchCreateGiftCardHolds), which this payment settles. Absent for a voucher tendered offline, which is spent against what the till last knew of the card.

line_idsarray of string · uuid
The lines this payment settled, when the till knows the split: a share pays whole lines, so a reopened tab shows the unpaid lines rather than a number, and a mistake cannot charge somebody twice (tabs item 13).
Empty when the payment named no lines — a whole-sale tender, an even split, a card share settling what is left, and every payment recorded before this existed. Empty and absent mean the same thing and are accepted alike, and a till sends the empty array.

memberMemberSnapshot

Nullable
The member who took this tender — the terminal operator who took the tip, not whoever rang the sale. The kept tip rule follows it. Absent for a payment recorded by something that is not a person.

idstring · uuid

Required
The roster's id, checked against the merchant's memberships.

namestring

Required
What the member was called.
≥ 1 chars

emailstring · email

Required
The member's address.

rolestring · enum

Required
The role the member held.
ownermanagerstaff

methodstring · enum

Required
cash — taken into the drawer. Settled by definition: nothing to capture, nothing that can later fail.
card — captured through the PSP. Recorded here as what the terminal reported, not as proof of settlement.
voucher — a gift card or credit note redeemed against the sale.
account — put on a customer's account to settle later. Requires the sale to name the customer (customer_id) and the merchant to have an open customer account for them; the till chooses the account at the tender and links the sale to its customer (retail: customer accounts).
A loyalty redemption is not a payment method any more: a reward redeems against its discount definition, the order line carries the discount, and the server spends the guest's points when the order is written. The points method was retired.
external — money a channel took before the order reached the venue: an online storefront, a delivery platform. The merchant settles with that channel, so the tender records the platform's reference rather than a card payment this merchant never captured. Only valid on an order a channel wrote, and the reference is required.
cashcardvoucheraccountexternal

pinstring
A voucher's PIN — the scratch-off second factor that proves possession of the card whose code is in reference (gift cards item 20). Required only when the card carries a PIN (a pre-printed or merchant-supplied code); a card with a generated code needs none, and the server refuses a sale whose voucher cannot prove the PIN. Only the hash is stored and compared; the plaintext never comes back.
≤ 12 chars

referencestring
The PSP's identifier for a card payment, or a voucher's code. Cash has neither and needs neither. Required for an external tender: it is the platform's own transaction or order reference, which is what reconciliation against that channel relies on.
≤ 128 chars

tipMoney

Nullable
The part of amount that is a gratuity rather than payment for goods.
Present because hospitality is not an edge case here: a bar or restaurant tab is the core flow, and a till that cannot record a tip cannot be used in one.

amountinteger · int64

Required
The amount, as a whole number of the currency's minor unit. May be negative to express a refund, discount or credit.

currencyCurrency

Required
ISO 4217 currency code.
Determines the minor unit that Money.amount is expressed in. Zero-decimal currencies such as JPY have a minor unit equal to the major unit.
One of 182 values; see the schema.

pickup_atstring · date-time

Read only
When the guest was told they could collect. Set by whoever took the order — the ordering page, or a till ringing a takeaway for collection at a time — and kept however the order is written afterwards: a later write that omits it leaves the promised time alone. Absent on an order nobody promised a time for.

ready_atstring · date-time

Read only
When the venue said an asked-for order was ready for the guest, recorded as a ready fact — the Ready button, the kitchen bumping the order's last ticket, or an integration. Absent until then, and again after a ready_undone takes it back. Read from the facts, never from whether the kitchen has any tickets for the order.

ready_to_pay_atstring · date-time

Read only
When a guest at the table said they were ready to pay (order-and-pay), on an open order. Absent until they tap; carried on the change feed as an order update, which is how the till shows the call.

received_atTimestamp

RequiredRead only
Server-assigned RFC 3339 timestamp, always UTC.
Server-assigned because device clocks drift and cannot be trusted for ordering — a till that has been powered off for a week may come back with a clock hours out. Where the device's own view of time matters it is carried separately in client_created_at.

referencestring
Short human-readable reference shown on the receipt and used by staff to find the order. Unique per location per business day.
≤ 64 chars

refundedMoney

A monetary amount in a specific currency: Square's Money, and Stripe's amount beside its currency.
The amount is always an integer count of the currency's minor unit — pence for GBP, cents for USD. Zero-decimal currencies such as JPY have a minor unit equal to their major unit, so {"amount": 500, "currency": "JPY"} is ¥500 while {"amount": 500, "currency": "GBP"} is £5.00.
Floating point is never used for money anywhere in this API. Binary floats cannot represent most decimal fractions exactly, so accumulating them across the line items of an order produces totals that disagree with the printed receipt by a penny. Integer minor units make every arithmetic operation exact.

amountinteger · int64

Required
The amount, as a whole number of the currency's minor unit. May be negative to express a refund, discount or credit.

currencyCurrency

Required
ISO 4217 currency code.
Determines the minor unit that Money.amount is expressed in. Zero-decimal currencies such as JPY have a minor unit equal to the major unit.
One of 182 values; see the schema.

rejection_notestring

Read only
The staff member's words, in their own voice, required when the reason is other.
≤ 512 chars

rejection_reasonstring · enum

Read only
Why an asked-for order was turned down, when it was. timed_out is the sweep that rejects an unanswered order past its location's deadline.
sold_outclosedtoo_busyothertimed_out

service_chargeMoney

Nullable
The discretionary service charge added to this bill (order-ledger item 9), in the order's currency, or null when none. Never folded into goods; part of the total payments must sum to.

amountinteger · int64

Required
The amount, as a whole number of the currency's minor unit. May be negative to express a refund, discount or credit.

currencyCurrency

Required
ISO 4217 currency code.
Determines the minor unit that Money.amount is expressed in. Zero-decimal currencies such as JPY have a minor unit equal to the major unit.
One of 182 values; see the schema.

service_charge_taxMoney

Nullable
The tax on the service charge, its own line and never folded into goods tax_total, or null when the charge is not taxed.

amountinteger · int64

Required
The amount, as a whole number of the currency's minor unit. May be negative to express a refund, discount or credit.

currencyCurrency

Required
ISO 4217 currency code.
Determines the minor unit that Money.amount is expressed in. Zero-decimal currencies such as JPY have a minor unit equal to the major unit.
One of 182 values; see the schema.

service_charge_tax_class_idstring · uuid

Nullable
The tax class the service charge was taxed under (decision record 0054), snapshotted from the location's config at write, or null when the charge is not taxed.

service_charge_tax_rate_percentagePercentage

Nullable
The combined tax rate that applied to the service charge, or null when not taxed.
pattern ^(100(\.0{1,4})?|(0|[1-9][0-9]?)(\.[0-9]{1,4})?)$

sourcestring

Read only
Which caller wrote the order — the device id for a pos or table order, storefront for one placed on a venue's ordering page, and the integration client id for an integration one. Set server-side from the caller, and an identifier's provenance, not a name.

source_namestring

Read only
The name the merchant gave the integration that wrote an integration order, as it was when the order was recorded; empty for any other channel.

statestring · enum

Required
open is a sale in progress, shared with the devices at its location. completed is finalised and immutable. canceled is an open order that ended without being paid. voided is a completed order reversed. Neither of the last two is deleted, so the audit trail survives.
opencompletedcanceledvoided

table_idstring · uuid

Nullable
The table an open order is parked on, if any. Occupancy is derived from this.

tipsMoney

A monetary amount in a specific currency: Square's Money, and Stripe's amount beside its currency.
The amount is always an integer count of the currency's minor unit — pence for GBP, cents for USD. Zero-decimal currencies such as JPY have a minor unit equal to their major unit, so {"amount": 500, "currency": "JPY"} is ¥500 while {"amount": 500, "currency": "GBP"} is £5.00.
Floating point is never used for money anywhere in this API. Binary floats cannot represent most decimal fractions exactly, so accumulating them across the line items of an order produces totals that disagree with the printed receipt by a penny. Integer minor units make every arithmetic operation exact.

amountinteger · int64

Required
The amount, as a whole number of the currency's minor unit. May be negative to express a refund, discount or credit.

currencyCurrency

Required
ISO 4217 currency code.
Determines the minor unit that Money.amount is expressed in. Zero-decimal currencies such as JPY have a minor unit equal to the major unit.
One of 182 values; see the schema.

totalsOrderTotals

Required
The money on an order, broken out.
These are computed and sent by the device, then independently recomputed by the server on receipt. A mismatch is rejected with 422 rather than quietly corrected: if the till printed a receipt showing one total and the server stored another, the merchant has an unreconcilable discrepancy and no way to know which is right. Failing loudly surfaces a till running stale tax configuration while it is still one order, not a month's worth.

cash_roundingMoney

Nullable
How much a cash settlement rounded the price, signed (docs/decisions/0015): a €10.02 bill rounded up to €10.05 has cash_rounding 3, and the cash payment's goods portion is the total plus this. The till computes it from the location's cash step; the server recomputes and rejects a mismatch. Zero on a sale no cash settles, and cards are never rounded.

amountinteger · int64

Required
The amount, as a whole number of the currency's minor unit. May be negative to express a refund, discount or credit.

currencyCurrency

Required
ISO 4217 currency code.
Determines the minor unit that Money.amount is expressed in. Zero-decimal currencies such as JPY have a minor unit equal to the major unit.
One of 182 values; see the schema.

discount_totalMoney

Required
A monetary amount in a specific currency: Square's Money, and Stripe's amount beside its currency.
The amount is always an integer count of the currency's minor unit — pence for GBP, cents for USD. Zero-decimal currencies such as JPY have a minor unit equal to their major unit, so {"amount": 500, "currency": "JPY"} is ¥500 while {"amount": 500, "currency": "GBP"} is £5.00.
Floating point is never used for money anywhere in this API. Binary floats cannot represent most decimal fractions exactly, so accumulating them across the line items of an order produces totals that disagree with the printed receipt by a penny. Integer minor units make every arithmetic operation exact.

amountinteger · int64

Required
The amount, as a whole number of the currency's minor unit. May be negative to express a refund, discount or credit.

currencyCurrency

Required
ISO 4217 currency code.
Determines the minor unit that Money.amount is expressed in. Zero-decimal currencies such as JPY have a minor unit equal to the major unit.
One of 182 values; see the schema.

service_chargeMoney

A monetary amount in a specific currency: Square's Money, and Stripe's amount beside its currency.
The amount is always an integer count of the currency's minor unit — pence for GBP, cents for USD. Zero-decimal currencies such as JPY have a minor unit equal to their major unit, so {"amount": 500, "currency": "JPY"} is ¥500 while {"amount": 500, "currency": "GBP"} is £5.00.
Floating point is never used for money anywhere in this API. Binary floats cannot represent most decimal fractions exactly, so accumulating them across the line items of an order produces totals that disagree with the printed receipt by a penny. Integer minor units make every arithmetic operation exact.

amountinteger · int64

Required
The amount, as a whole number of the currency's minor unit. May be negative to express a refund, discount or credit.

currencyCurrency

Required
ISO 4217 currency code.
Determines the minor unit that Money.amount is expressed in. Zero-decimal currencies such as JPY have a minor unit equal to the major unit.
One of 182 values; see the schema.

service_charge_taxMoney

Nullable
The tax on the service charge (decision record 0054), its own line and never folded into goods tax_total. Computed server-side from the location's service-charge tax class and the sale's fulfilment and business date. Null when the charge is not taxed.

amountinteger · int64

Required
The amount, as a whole number of the currency's minor unit. May be negative to express a refund, discount or credit.

currencyCurrency

Required
ISO 4217 currency code.
Determines the minor unit that Money.amount is expressed in. Zero-decimal currencies such as JPY have a minor unit equal to the major unit.
One of 182 values; see the schema.

subtotalMoney

Required
A monetary amount in a specific currency: Square's Money, and Stripe's amount beside its currency.
The amount is always an integer count of the currency's minor unit — pence for GBP, cents for USD. Zero-decimal currencies such as JPY have a minor unit equal to their major unit, so {"amount": 500, "currency": "JPY"} is ¥500 while {"amount": 500, "currency": "GBP"} is £5.00.
Floating point is never used for money anywhere in this API. Binary floats cannot represent most decimal fractions exactly, so accumulating them across the line items of an order produces totals that disagree with the printed receipt by a penny. Integer minor units make every arithmetic operation exact.

amountinteger · int64

Required
The amount, as a whole number of the currency's minor unit. May be negative to express a refund, discount or credit.

currencyCurrency

Required
ISO 4217 currency code.
Determines the minor unit that Money.amount is expressed in. Zero-decimal currencies such as JPY have a minor unit equal to the major unit.
One of 182 values; see the schema.

tax_totalMoney

Required
A monetary amount in a specific currency: Square's Money, and Stripe's amount beside its currency.
The amount is always an integer count of the currency's minor unit — pence for GBP, cents for USD. Zero-decimal currencies such as JPY have a minor unit equal to their major unit, so {"amount": 500, "currency": "JPY"} is ¥500 while {"amount": 500, "currency": "GBP"} is £5.00.
Floating point is never used for money anywhere in this API. Binary floats cannot represent most decimal fractions exactly, so accumulating them across the line items of an order produces totals that disagree with the printed receipt by a penny. Integer minor units make every arithmetic operation exact.

amountinteger · int64

Required
The amount, as a whole number of the currency's minor unit. May be negative to express a refund, discount or credit.

currencyCurrency

Required
ISO 4217 currency code.
Determines the minor unit that Money.amount is expressed in. Zero-decimal currencies such as JPY have a minor unit equal to the major unit.
One of 182 values; see the schema.

totalMoney

Required
A monetary amount in a specific currency: Square's Money, and Stripe's amount beside its currency.
The amount is always an integer count of the currency's minor unit — pence for GBP, cents for USD. Zero-decimal currencies such as JPY have a minor unit equal to their major unit, so {"amount": 500, "currency": "JPY"} is ¥500 while {"amount": 500, "currency": "GBP"} is £5.00.
Floating point is never used for money anywhere in this API. Binary floats cannot represent most decimal fractions exactly, so accumulating them across the line items of an order produces totals that disagree with the printed receipt by a penny. Integer minor units make every arithmetic operation exact.

amountinteger · int64

Required
The amount, as a whole number of the currency's minor unit. May be negative to express a refund, discount or credit.

currencyCurrency

Required
ISO 4217 currency code.
Determines the minor unit that Money.amount is expressed in. Zero-decimal currencies such as JPY have a minor unit equal to the major unit.
One of 182 values; see the schema.

updated_atTimestamp

RequiredRead only
Server-assigned RFC 3339 timestamp, always UTC.
Server-assigned because device clocks drift and cannot be trusted for ordering — a till that has been powered off for a week may come back with a clock hours out. Where the device's own view of time matters it is carried separately in client_created_at.

versionVersion

RequiredRead only
Optimistic concurrency version, raised by the server on every write. A version is never lower than one already returned for the resource, though it may rise by more than one.
Returned in the ETag response header as well as in the body. Send it back in If-Match on an update and the write is rejected with 412 if anyone else has written since — which is what stops two tills silently overwriting each other's edit to the same product when both come back online at once.
≥ 1

void_memberMemberSnapshot

Nullable
The staff member who voided this order, when it has been voided and the void was made by a person. Nil for a sale that was never voided, or one voided by something that is not a person.

idstring · uuid

Required
The roster's id, checked against the merchant's memberships.

namestring

Required
What the member was called.
≥ 1 chars

emailstring · email

Required
The member's address.

rolestring · enum

Required
The role the member held.
ownermanagerstaff

void_notestring
The staff member's note on the void, required when the reason is other.

void_reasonstring · enum
Why this sale was voided. Set on a voided order.
customer_canceledstaff_errorrefundother

voided_atstring · date-time

Nullable
When the sale was voided.

400
The request could not be parsed. Malformed JSON, a bad query parameter, or a header that failed to decode, among them an API-Version later than the server speaks or not a date (api-version-unknown, with the server's own in api_version).
Distinct from 422: a 400 never reached validation, so invalid_params is absent. Retrying without changing the request will fail again, except that a request refused for its API-Version goes once the server is updated.

401
No credentials, or credentials that could not be verified — missing bearer token, malformed JWT, expired token, or a signature that failed against the issuer's JWKS.
Refresh the token and retry once. Repeated 401 after a refresh means the device needs to re-enrol.

403
Authenticated, but not permitted. The token is valid and its merchant was resolved, but the caller's role does not allow this operation, or the target belongs to a different merchant.
Cross-tenant access is reported as 403 on a resource the caller may not see, and as 404 where even confirming existence would leak information. Retrying will not help.

404
No such resource, or none visible to this caller.
Also returned instead of 403 where acknowledging existence would itself leak information — so a 404 does not prove the id is unused globally, only that it is not yours.

410
The request names an API-Version this server no longer serves (docs/decisions/0011). Nothing in it was read. api_version names the version the server speaks: the client is behind, and sends the request again once it is updated.

415
The request Content-Type is not supported. This API accepts application/json on all mutations.

422
The request parsed but failed validation.
invalid_params lists every failing field with a JSON Pointer, not just the first, so a client can mark up a whole form in one pass rather than making the user fix errors one round trip at a time.
Also returned when an Idempotency-Key is replayed with a different body, and when device-computed order totals disagree with the server's recomputation.

429
Rate limit exceeded. Honour Retry-After rather than applying your own backoff.
A fleet of tills coming back online together after an outage is the realistic cause, which is exactly when uncoordinated client-side retry turns a brief outage into a sustained one. The limit is per process, and per site for what records trade there — a request spends its site's budget, and a till's own smaller one inside it — and per (client, merchant) for everything else; no RateLimit field is sent, so this response and its Retry-After are the whole of the contract.

500
Something failed on our side. trace_id identifies the request in our tracing — quote it in a support ticket.
The body never carries internal detail: no SQL, no stack traces, no upstream error strings. Safe to retry with the same Idempotency-Key.

503
Temporarily unable to serve the request — a dependency is down or the service is shedding load.
Retry with the same Idempotency-Key after Retry-After. This is always safe: a request that did take effect before the failure will be recognised as a replay.
Request
curl -X POST 'https://api.tenvelo.com/v1/orders/0192f1e4-7c3a-7b2e-9f10-5d6c7e8f9a0b/decline' \ -H "Authorization: Bearer $TOKEN" \ -H 'Content-Type: application/json' \ -d '{ "note": "string", "rejection_reason": "sold_out" }'
Response
{ "id": "0192f1e4-7c3a-7b2e-9f10-5d6c7e8f9a0b", "name": "Sam", "acceptance": "pending", "age_confirmed": false, "age_minimum": 0, "business_date": "2026-09-11", "channel": "pos", "channel_cost": { "amount": 1250, "currency": "GBP" }, "client_created_at": "2026-09-11T09:30:00Z", "closed_at": "2026-09-11T09:30:00Z", "covers": 0, "created_at": "2026-09-08T09:41:12Z", "currency": "AED", "customer": { "id": "0192f1e4-7c3a-7b2e-9f10-5d6c7e8f9a0b", "name": "string", "loyalty_points": 0, "rewards": [ { "id": "0192f1e4-7c3a-7b2e-9f10-5d6c7e8f9a0b", "name": "string", "cost_points": 0, "discount_id": "0192f1e4-7c3a-7b2e-9f10-5d6c7e8f9a0b" } ], "tags": "string", "tier": { "current": { "id": "0192f1e4-7c3a-7b2e-9f10-5d6c7e8f9a0b", "name": "string", "earn_rate_percentage": "-12.5", "threshold_spend": { "amount": 1250, "currency": "GBP" }, "threshold_visits": 0, "window_days": 0 }, "next": { "id": "0192f1e4-7c3a-7b2e-9f10-5d6c7e8f9a0b", "name": "string", "earn_rate_percentage": "-12.5", "threshold_spend": { "amount": 1250, "currency": "GBP" }, "threshold_visits": 0, "window_days": 0 }, "spend_needed": { "amount": 1250, "currency": "GBP" }, "visits_needed": 0 }, "version": 0 }, "customer_id": "0192f1e4-7c3a-7b2e-9f10-5d6c7e8f9a0b", "delivery_address": { "address_line_1": "12 Bridge Street", "address_line_2": "string", "address_line_3": "string", "administrative_district_level_1": "Somerset", "administrative_district_level_2": "string", "country": "ZZ", "locality": "Bristol", "postal_code": "BS1 4ST", "sublocality": "string" }, "delivery_fee": { "amount": 1250, "currency": "GBP" }, "device_id": "0192f1e4-7c3a-7b2e-9f10-5d6c7e8f9a0b", "device_seq": 0, "document": { "kind": "invoice", "number": 148, "series": "B1-T3" }, "drawer_session_id": "0192f1e4-7c3a-7b2e-9f10-5d6c7e8f9a0b", "email_receipt": false, "external_reference": "string", "flags": [ "string" ], "fulfillment_status": "received", "fulfillment_type": "on_premises", "line_items": [ { "id": "0192f1e4-7c3a-7b2e-9f10-5d6c7e8f9a0b", "name": "Flat white", "approved_by_member": { "id": "0192f1e4-7c3a-7b2e-9f10-5d6c7e8f9a0b", "name": "string", "email": "ada@example.com", "role": "owner" }, "category_id": "0192f1e4-7c3a-7b2e-9f10-5d6c7e8f9a0b", "category_name": "string", "comp_reason": "string", "course": 1, "discount": { "amount": 1250, "currency": "GBP" }, "discount_id": "0192f1e4-7c3a-7b2e-9f10-5d6c7e8f9a0b", "discount_name": "string", "gift_card_code": "string", "gift_card_token_hash": "string", "modifiers": [ { "id": "0192f1e4-7c3a-7b2e-9f10-5d6c7e8f9a0b", "name": "Oat milk", "price_delta": { "amount": 1250, "currency": "GBP" } } ], "multibuy": { "every": 2, "price": { "amount": 1250, "currency": "GBP" } }, "note": "string", "origin": "till", "product_id": "0192f1e4-7c3a-7b2e-9f10-5d6c7e8f9a0b", "product_type": "standard", "quantity": "3", "seat": 1, "sent_at": "2026-09-11T09:30:00Z", "serials": [], "tax": { "amount": 1250, "currency": "GBP" }, "tax_breakdown": [ { "amount": { "amount": 1250, "currency": "GBP" }, "inclusive": false, "percentage": "20", "rate_id": "0192f1e4-7c3a-7b2e-9f10-5d6c7e8f9a0b" } ], "tax_inclusive": false, "tax_rate_percentage": "20", "total": { "amount": 1250, "currency": "GBP" }, "unit_of_measure": "each", "unit_price": { "amount": 1250, "currency": "GBP" }, "variant_id": "0192f1e4-7c3a-7b2e-9f10-5d6c7e8f9a0b" } ], "location_id": "0192f1e4-7c3a-7b2e-9f10-5d6c7e8f9a0b", "loyalty_earned": 0, "loyalty_spent": 0, "member": { "id": "0192f1e4-7c3a-7b2e-9f10-5d6c7e8f9a0b", "name": "string", "email": "ada@example.com", "role": "owner" }, "merchant_id": "0192f1e4-7c3a-7b2e-9f10-5d6c7e8f9a0b", "owner_member": { "id": "0192f1e4-7c3a-7b2e-9f10-5d6c7e8f9a0b", "name": "string", "email": "ada@example.com", "role": "owner" }, "paid": { "amount": 1250, "currency": "GBP" }, "payments": [ { "id": "0192f1e4-7c3a-7b2e-9f10-5d6c7e8f9a0b", "amount": { "amount": 1250, "currency": "GBP" }, "buyer_supplied": { "amount": 1250, "currency": "GBP" }, "card_brand": "string", "card_confirmation": "confirmed", "card_last4": "string", "change_back": { "amount": 1250, "currency": "GBP" }, "fingerprint": "string", "gift_card_hold_id": "0192f1e4-7c3a-7b2e-9f10-5d6c7e8f9a0b", "line_ids": [ "0192f1e4-7c3a-7b2e-9f10-5d6c7e8f9a0b" ], "member": { "id": "0192f1e4-7c3a-7b2e-9f10-5d6c7e8f9a0b", "name": "string", "email": "ada@example.com", "role": "owner" }, "method": "cash", "pin": "string", "reference": "pspRef_8829301", "tip": { "amount": 1250, "currency": "GBP" } } ], "pickup_at": "2026-09-11T09:30:00Z", "ready_at": "2026-09-11T09:30:00Z", "ready_to_pay_at": "2026-09-11T09:30:00Z", "received_at": "2026-09-08T09:41:12Z", "reference": "A-0148", "refunded": { "amount": 1250, "currency": "GBP" }, "rejection_note": "string", "rejection_reason": "sold_out", "service_charge": { "amount": 1250, "currency": "GBP" }, "service_charge_tax": { "amount": 1250, "currency": "GBP" }, "service_charge_tax_class_id": "0192f1e4-7c3a-7b2e-9f10-5d6c7e8f9a0b", "service_charge_tax_rate_percentage": "20", "source": "string", "source_name": "string", "state": "open", "table_id": "0192f1e4-7c3a-7b2e-9f10-5d6c7e8f9a0b", "tips": { "amount": 1250, "currency": "GBP" }, "totals": { "cash_rounding": { "amount": 1250, "currency": "GBP" }, "discount_total": { "amount": 1250, "currency": "GBP" }, "service_charge": { "amount": 1250, "currency": "GBP" }, "service_charge_tax": { "amount": 1250, "currency": "GBP" }, "subtotal": { "amount": 1250, "currency": "GBP" }, "tax_total": { "amount": 1250, "currency": "GBP" }, "total": { "amount": 1250, "currency": "GBP" } }, "updated_at": "2026-09-08T09:41:12Z", "version": 7, "void_member": { "id": "0192f1e4-7c3a-7b2e-9f10-5d6c7e8f9a0b", "name": "string", "email": "ada@example.com", "role": "owner" }, "void_note": "string", "void_reason": "customer_canceled", "voided_at": "2026-09-11T09:30:00Z" }
GET/v1/orders/{id}/facts

List an order's facts

No. getOrderFactsAuth pos:orders:write ordering:write
Returns the facts recorded about an order, newest first by their stamp: what was rung up and taken off, each payment, and how the order was closed, voided or refunded. They are the facts the order is folded from, as their writers recorded them, each with happened_at.
Only the types a writer may record are listed. What the server works out from them, which an order already shows, is not, nor a card payment's fingerprint. Read under the same rules as GET /v1/orders/{id}, except that a guest at the table is refused with 403: what the staff did is theirs.
Parameters

idpath · string · uuid
Required
UUIDv7 of the resource.
For resources a device can originate — orders, and their line items — this id is minted by the client before the record is ever synced, which is what makes an offline create idempotent.
Responses

200
The order's facts.

OrderFacts · application/json

itemsarray of OrderFact

Required

idstring · uuid

Required
UUIDv7, minted by the device that recorded the fact. Sending the same fact again under this id records it once; sending a different fact under it fails.

typestring · enum

Required
What happened, which decides the one member the fact carries.
createdline_item_addedline_item_voidedpayment_takenupdatedcompletedcanceledvoidedrefundedacceptedrejectedreadyready_undone

acceptanceOrderFactAcceptance

An asked-for order taken on (accepted) or turned down (rejected), beside its lifecycle rather than in it: an order's acceptance is pending from a channel that needs one — the ordering page, an integration — until one of these arrives, or its location's deadline passes and it is rejected as timed_out.

notestring
What the guest is told, in the staff member's words. Required when the reason is other.
≤ 512 chars

pickup_atstring · date-time
When the venue says the order will be ready, on accepted: the guest is told it, and it becomes the order's pickup_at. Absent keeps the time the guest asked for. Square's fulfilment key.

rejection_reasonstring · enum
Why the order was turned down. Required on rejected, absent on accepted. timed_out is the sweep that rejects an order nobody took on before its location's deadline.
sold_outclosedtoo_busyothertimed_out

cancellationOrderFactCancellation

An open order ended without being paid — a tab somebody walked out on, one opened by mistake — and kept, with its reason, so it is accounted for rather than vanishing. A completed order is voided instead.

notestring
What happened, in the staff member's words. Required when reason is other.
≤ 512 chars

reasonstring · enum

Required
abandoned is a tab nobody paid for; staff_error was opened by mistake. An order the business declined is rejected, a fact of its own.
abandonedstaff_errorother

completionOrderFactCompletion

The order paid and closed. Its total is derived from its lines, voids and payments when the completion is applied, never taken from here; totals is what the till showed the guest, kept so a disagreement can be flagged rather than silently resolved.

age_confirmedboolean
The till confirmed the guest's age before this sale completed: the sale carried an age-restricted line (its product's minimum_age), and the operator attested the guest could prove it. Absent on a sale with no age-restricted line.
default false

age_minimuminteger · int32
The oldest buyer the sale's age-restricted lines allowed, as the till recorded it: the highest minimum_age among the lines at the moment the sale completed. 0 when the sale carried none, or when no check was recorded.
0–100 · default 0

documentOrderDocument

The fiscal document a completed order is recorded as, in the per-till series 0016 builds. Every sales document a till issues belongs to a series it was issued at enrolment, and the number is a gap-free counter in that series, incremented in the same transaction that completes the order. Printed on the receipt and sent with the order; the server stores it and refuses a duplicate (series, number).
This is the number a market's fiscal rules are about — the correlative number within a series. It is not the order's reference, which stays the short per-day call number for staff to find a sale.

kindstring · enum

Required
What the document is. invoice is the ordinary receipt — the simplified invoice most markets call a receipt. A full invoice and a rectifying document will be separate kinds, each in its own series.
invoice
default invoice

numberinteger · int64

Required
The gap-free sequence number within the series, starting at 1. Never reused: a void keeps its number, and a correction is a new document in a rectifying series.
≥ 1

seriesstring

Required
The series this document belongs to: a short code issued to one till at enrolment (e.g. B1-T3), one per device and kind of document. The ordinary receipt is in the invoice series.
≤ 32 chars

loyalty_hold_idstring · uuid
The hold the till took on the guest's points before redeeming the sale's rewards (batchCreateLoyaltyHolds), which the completion settles. Absent for a sale that redeems nothing, or redeemed offline against what the till last knew.

referencestring
The short reference printed on the receipt and used by staff to find the order.
≤ 64 chars

service_chargeMoney

Nullable
The discretionary service charge the till added to the bill, in the order's currency; null when the merchant charges none.

amountinteger · int64

Required
The amount, as a whole number of the currency's minor unit. May be negative to express a refund, discount or credit.

currencyCurrency

Required
ISO 4217 currency code.
Determines the minor unit that Money.amount is expressed in. Zero-decimal currencies such as JPY have a minor unit equal to the major unit.
One of 182 values; see the schema.

service_charge_declinedboolean
The guest declined the discretionary service charge, so none is applied.
default false

totalsOrderTotals

Required
The money on an order, broken out.
These are computed and sent by the device, then independently recomputed by the server on receipt. A mismatch is rejected with 422 rather than quietly corrected: if the till printed a receipt showing one total and the server stored another, the merchant has an unreconcilable discrepancy and no way to know which is right. Failing loudly surfaces a till running stale tax configuration while it is still one order, not a month's worth.

cash_roundingMoney

Nullable
How much a cash settlement rounded the price, signed (docs/decisions/0015): a €10.02 bill rounded up to €10.05 has cash_rounding 3, and the cash payment's goods portion is the total plus this. The till computes it from the location's cash step; the server recomputes and rejects a mismatch. Zero on a sale no cash settles, and cards are never rounded.

amountinteger · int64

Required
The amount, as a whole number of the currency's minor unit. May be negative to express a refund, discount or credit.

currencyCurrency

Required
ISO 4217 currency code.
Determines the minor unit that Money.amount is expressed in. Zero-decimal currencies such as JPY have a minor unit equal to the major unit.
One of 182 values; see the schema.

discount_totalMoney

Required
A monetary amount in a specific currency: Square's Money, and Stripe's amount beside its currency.
The amount is always an integer count of the currency's minor unit — pence for GBP, cents for USD. Zero-decimal currencies such as JPY have a minor unit equal to their major unit, so {"amount": 500, "currency": "JPY"} is ¥500 while {"amount": 500, "currency": "GBP"} is £5.00.
Floating point is never used for money anywhere in this API. Binary floats cannot represent most decimal fractions exactly, so accumulating them across the line items of an order produces totals that disagree with the printed receipt by a penny. Integer minor units make every arithmetic operation exact.

amountinteger · int64

Required
The amount, as a whole number of the currency's minor unit. May be negative to express a refund, discount or credit.

currencyCurrency

Required
ISO 4217 currency code.
Determines the minor unit that Money.amount is expressed in. Zero-decimal currencies such as JPY have a minor unit equal to the major unit.
One of 182 values; see the schema.

service_chargeMoney

A monetary amount in a specific currency: Square's Money, and Stripe's amount beside its currency.
The amount is always an integer count of the currency's minor unit — pence for GBP, cents for USD. Zero-decimal currencies such as JPY have a minor unit equal to their major unit, so {"amount": 500, "currency": "JPY"} is ¥500 while {"amount": 500, "currency": "GBP"} is £5.00.
Floating point is never used for money anywhere in this API. Binary floats cannot represent most decimal fractions exactly, so accumulating them across the line items of an order produces totals that disagree with the printed receipt by a penny. Integer minor units make every arithmetic operation exact.

amountinteger · int64

Required
The amount, as a whole number of the currency's minor unit. May be negative to express a refund, discount or credit.

currencyCurrency

Required
ISO 4217 currency code.
Determines the minor unit that Money.amount is expressed in. Zero-decimal currencies such as JPY have a minor unit equal to the major unit.
One of 182 values; see the schema.

service_charge_taxMoney

Nullable
The tax on the service charge (decision record 0054), its own line and never folded into goods tax_total. Computed server-side from the location's service-charge tax class and the sale's fulfilment and business date. Null when the charge is not taxed.

amountinteger · int64

Required
The amount, as a whole number of the currency's minor unit. May be negative to express a refund, discount or credit.

currencyCurrency

Required
ISO 4217 currency code.
Determines the minor unit that Money.amount is expressed in. Zero-decimal currencies such as JPY have a minor unit equal to the major unit.
One of 182 values; see the schema.

subtotalMoney

Required
A monetary amount in a specific currency: Square's Money, and Stripe's amount beside its currency.
The amount is always an integer count of the currency's minor unit — pence for GBP, cents for USD. Zero-decimal currencies such as JPY have a minor unit equal to their major unit, so {"amount": 500, "currency": "JPY"} is ¥500 while {"amount": 500, "currency": "GBP"} is £5.00.
Floating point is never used for money anywhere in this API. Binary floats cannot represent most decimal fractions exactly, so accumulating them across the line items of an order produces totals that disagree with the printed receipt by a penny. Integer minor units make every arithmetic operation exact.

amountinteger · int64

Required
The amount, as a whole number of the currency's minor unit. May be negative to express a refund, discount or credit.

currencyCurrency

Required
ISO 4217 currency code.
Determines the minor unit that Money.amount is expressed in. Zero-decimal currencies such as JPY have a minor unit equal to the major unit.
One of 182 values; see the schema.

tax_totalMoney

Required
A monetary amount in a specific currency: Square's Money, and Stripe's amount beside its currency.
The amount is always an integer count of the currency's minor unit — pence for GBP, cents for USD. Zero-decimal currencies such as JPY have a minor unit equal to their major unit, so {"amount": 500, "currency": "JPY"} is ¥500 while {"amount": 500, "currency": "GBP"} is £5.00.
Floating point is never used for money anywhere in this API. Binary floats cannot represent most decimal fractions exactly, so accumulating them across the line items of an order produces totals that disagree with the printed receipt by a penny. Integer minor units make every arithmetic operation exact.

amountinteger · int64

Required
The amount, as a whole number of the currency's minor unit. May be negative to express a refund, discount or credit.

currencyCurrency

Required
ISO 4217 currency code.
Determines the minor unit that Money.amount is expressed in. Zero-decimal currencies such as JPY have a minor unit equal to the major unit.
One of 182 values; see the schema.

totalMoney

Required
A monetary amount in a specific currency: Square's Money, and Stripe's amount beside its currency.
The amount is always an integer count of the currency's minor unit — pence for GBP, cents for USD. Zero-decimal currencies such as JPY have a minor unit equal to their major unit, so {"amount": 500, "currency": "JPY"} is ¥500 while {"amount": 500, "currency": "GBP"} is £5.00.
Floating point is never used for money anywhere in this API. Binary floats cannot represent most decimal fractions exactly, so accumulating them across the line items of an order produces totals that disagree with the printed receipt by a penny. Integer minor units make every arithmetic operation exact.

amountinteger · int64

Required
The amount, as a whole number of the currency's minor unit. May be negative to express a refund, discount or credit.

currencyCurrency

Required
ISO 4217 currency code.
Determines the minor unit that Money.amount is expressed in. Zero-decimal currencies such as JPY have a minor unit equal to the major unit.
One of 182 values; see the schema.

device_seqinteger · int64

Nullable
The recording device's own sequence number for this fact, one higher than its last, across every fact it records. A gap is a fact that never arrived. Null from a client that is not a device.
≥ 1

happened_atstring · date-time

Read only
When the fact happened: the wall-clock time its stamp (hlc) carries, which the server believed or gave it. Set on a read; a writer sends hlc.

hlcHLC
A hybrid logical clock stamp (Kulkarni et al., 2014): the recorder's wall clock in milliseconds in the high 48 bits and a counter in the low 16, a 64-bit integer written as its decimal digits in a string. A stamp is past 2^53, beyond the integers a JSON number holds exactly as most parsers read it, so I-JSON writes it as a string (RFC 7493 §2.2).
A device stamps every fact it records, as it records it, after every stamp it has made or pulled — every change on the feed carries one — so a fact recorded after seeing another ranks after it whatever either wall clock says. The stamp is when the fact happened. The server keeps it unless it is more than ten minutes ahead of the server's clock, more than thirty days behind it, or from before the device was paired. A fact is never refused for its stamp: one the server does not believe, cannot read or was not given is stamped as the server takes it, and flagged on what it dates — the order, the shift, the drawer or the shelf.

line_itemOrderLineItem

One line of a sale.
Every descriptive and monetary field here is a snapshot copied from the catalogue at the moment of sale. product_id is retained for reporting, but nothing on this line is ever re-resolved from it — otherwise editing a product would silently rewrite history.

idstring · uuid

Required
UUIDv7, minted by the device.

namestring

Required
Product name as sold. Snapshot; never re-read from the product.
1–255 chars

approved_by_memberMemberSnapshot

Nullable
The manager or owner who authorised a staff member's discount or comp above the merchant's discount_approval_threshold_minor/discount_approval_threshold_percentage or a comp when comp_requires_manager is set, as they were then; null when no approval was needed.

idstring · uuid

Required
The roster's id, checked against the merchant's memberships.

namestring

Required
What the member was called.
≥ 1 chars

emailstring · email

Required
The member's address.

rolestring · enum

Required
The role the member held.
ownermanagerstaff

category_idstring · uuid

RequiredNullable
The category the product was filed under when the line was rung, for reporting. Snapshot: moving the product to another category later moves no sale. Null on an ad-hoc line or an uncategorised product.

category_namestring

Required
The category's name when the line was rung, so a report of past sales reads as they were filed. Snapshot; empty when category_id is null.
≤ 255 chars

comp_reasonstring
Why this line was given away. Present on a comp — an item given away at no charge — and means something different from a discount, so it is reported separately. Required when the line is a comp.
≤ 512 chars

courseinteger · int32

Nullable
The course this line belongs to, in a full-service kitchen — starters, mains, desserts. Set on the till when ringing to a course, and used to hold or fire a course from the till. Null for a single-course counter sale or a course-less line. Held courses are not sent (sent_at null) until they are fired.
≥ 1

discountMoney

A monetary amount in a specific currency: Square's Money, and Stripe's amount beside its currency.
The amount is always an integer count of the currency's minor unit — pence for GBP, cents for USD. Zero-decimal currencies such as JPY have a minor unit equal to their major unit, so {"amount": 500, "currency": "JPY"} is ¥500 while {"amount": 500, "currency": "GBP"} is £5.00.
Floating point is never used for money anywhere in this API. Binary floats cannot represent most decimal fractions exactly, so accumulating them across the line items of an order produces totals that disagree with the printed receipt by a penny. Integer minor units make every arithmetic operation exact.

amountinteger · int64

Required
The amount, as a whole number of the currency's minor unit. May be negative to express a refund, discount or credit.

currencyCurrency

Required
ISO 4217 currency code.
Determines the minor unit that Money.amount is expressed in. Zero-decimal currencies such as JPY have a minor unit equal to the major unit.
One of 182 values; see the schema.

discount_idstring · uuid

Nullable
The discount definition applied to this line, for reporting. Null for a line with no discount. Snapshot — the discount is recorded so its use can be attributed even if the definition later changes.

discount_namestring
The discount's name at the time the line was priced, snapshotted on the line — the reason a guest can be told, without re-resolving a definition that may have been renamed or deleted. Empty for a line with no discount.
≤ 200 chars

gift_card_codestring

Nullable
The code on the card being sold, when the line's product is a gift_card — typed or scanned at the till. The server issues the card (or refuses a code already live) when the order completes. Null for any other line.
≤ 64 chars

gift_card_token_hashstring

Nullable
The hash of the balance-page token for the card being sold: SHA-256 over the token's text, in base64url without padding. The device mints the token — 32 random bytes, unpadded base64url — and prints it on the receipt's balance link; only its hash leaves the device, so the token is never on the record of the sale, and the server checks a link by hashing the token it carries (W3C, "Good Practices for Capability URLs"). Absent leaves the card with no balance link until one is made (gift-card-balance-links). Null for any other line.
43–43 chars · pattern ^[A-Za-z0-9_-]{43}$

modifiersarray of OrderLineModifier

The options chosen on this line, snapshotted at the moment of sale. The line's unit_price already includes each option's delta.
The server checks only the shape of these — a negative delta is refused, an option chosen twice is refused — and never refuses a sale because the menu has changed since the till synced. A sale that was correct when rung stays correct.

idstring · uuid

Required
The modifier that was chosen. Kept for reporting, never re-resolved.

namestring

Required
Option name as sold. Snapshot.
1–255 chars

price_deltaMoney

Required
A monetary amount in a specific currency: Square's Money, and Stripe's amount beside its currency.
The amount is always an integer count of the currency's minor unit — pence for GBP, cents for USD. Zero-decimal currencies such as JPY have a minor unit equal to their major unit, so {"amount": 500, "currency": "JPY"} is ¥500 while {"amount": 500, "currency": "GBP"} is £5.00.
Floating point is never used for money anywhere in this API. Binary floats cannot represent most decimal fractions exactly, so accumulating them across the line items of an order produces totals that disagree with the printed receipt by a penny. Integer minor units make every arithmetic operation exact.

amountinteger · int64

Required
The amount, as a whole number of the currency's minor unit. May be negative to express a refund, discount or credit.

currencyCurrency

Required
ISO 4217 currency code.
Determines the minor unit that Money.amount is expressed in. Zero-decimal currencies such as JPY have a minor unit equal to the major unit.
One of 182 values; see the schema.

multibuyMultibuyRule

Nullable
The product's multibuy rule as it stood when the line was rung, snapshotted on the line so the server resolves the gross by the same deal the till did — re-pricing a product never rewrites a sale that was correct. Null on a line with no deal. A rule never applies to a weighed line.

everyinteger

Required
How many units make a run; 3 is the ordinary buy-two-get-one.
2–1000

priceMoney

Required
A monetary amount in a specific currency: Square's Money, and Stripe's amount beside its currency.
The amount is always an integer count of the currency's minor unit — pence for GBP, cents for USD. Zero-decimal currencies such as JPY have a minor unit equal to their major unit, so {"amount": 500, "currency": "JPY"} is ¥500 while {"amount": 500, "currency": "GBP"} is £5.00.
Floating point is never used for money anywhere in this API. Binary floats cannot represent most decimal fractions exactly, so accumulating them across the line items of an order produces totals that disagree with the printed receipt by a penny. Integer minor units make every arithmetic operation exact.

amountinteger · int64

Required
The amount, as a whole number of the currency's minor unit. May be negative to express a refund, discount or credit.

currencyCurrency

Required
ISO 4217 currency code.
Determines the minor unit that Money.amount is expressed in. Zero-decimal currencies such as JPY have a minor unit equal to the major unit.
One of 182 values; see the schema.

notestring
Free text from the till — "oat milk", "no sugar".
≤ 512 chars

originstring · enum

Read only
Where this line was rung from, as the server saw the writer: the till at the counter, a guest's phone on a tab, an ordering channel, an integration. It is the server's word and never the writer's, and it is how the share of a table's spend the table rang itself is told. Absent on a line recorded before origins were.
tillcustomeronlineintegration

product_idstring · uuid

Nullable
The catalogue product, for reporting. Null for an ad-hoc line — a miscellaneous item rung up at a custom price, which every real till needs.

product_typestring · enum

Required
What the product was when the line was rung: a gift_card sold is money taken for a promise, not revenue, and a combo is a set. Square's item_type. Snapshot, copied from the product at the moment of sale; standard on an ad-hoc line.
standardgift_cardcombo

quantityQuantity

Required
How much of something, as a decimal string in the unit_of_measure beside it (each where there is none), as Square's quantity is: three croissants are "3", 1.4 kg of beans is "1.4". A string because a JSON number is a binary float to most parsers.
It has at most as many decimal places as its unit's base unit holds — three in each, g and ml, six in kg and l — and a finer one is refused, never rounded. Tenvelo holds every quantity as an integer of that base unit (thousandths of an each, milligrams, microlitres; docs/decisions/0063); a client that computes with one should read the digits the same way, never through a float.
≤ 26 chars · pattern ^-?(0|[1-9][0-9]*)(\.[0-9]{1,6})?$

seatinteger · int32

Nullable
The seat this line is for, when a table's seats are numbered. Set on the till and carried to the kitchen and to split bills. Null for a counter sale or an unnumbered seat.
≥ 1

sent_atstring · date-time

Nullable
When this line was sent to the kitchen — set by the till when a tab is held or a sale completed, and immutable once set. A kitchen knows what to cook from the lines of a ticket, and a new round on a tab is a new set of sent_at values rather than the old lines re-sent. Null on a line the till has not yet held or completed.

serialsarray of string
The serial numbers of the units this line sold (retail item: serial numbers) — one per unit, in the order they were entered, printed on a product whose track_serial is set. Empty on any other line. A snapshot like the name and price: the record of which physical units left the shelf, so a specific unit sold is traceable to its sale.
default []

taxMoney

A monetary amount in a specific currency: Square's Money, and Stripe's amount beside its currency.
The amount is always an integer count of the currency's minor unit — pence for GBP, cents for USD. Zero-decimal currencies such as JPY have a minor unit equal to their major unit, so {"amount": 500, "currency": "JPY"} is ¥500 while {"amount": 500, "currency": "GBP"} is £5.00.
Floating point is never used for money anywhere in this API. Binary floats cannot represent most decimal fractions exactly, so accumulating them across the line items of an order produces totals that disagree with the printed receipt by a penny. Integer minor units make every arithmetic operation exact.

amountinteger · int64

Required
The amount, as a whole number of the currency's minor unit. May be negative to express a refund, discount or credit.

currencyCurrency

Required
ISO 4217 currency code.
Determines the minor unit that Money.amount is expressed in. Zero-decimal currencies such as JPY have a minor unit equal to the major unit.
One of 182 values; see the schema.

tax_breakdownarray of TaxBreakdownItem

Each rate's share of this line's tax, in the order its rule names the rates, when the line is taxed over several rates (each a separate calculation, each rounding with its own mode). Absent — null — on a line taxed at a single rate, where tax_rate_percentage and tax are the whole story.

amountMoney

Required
A monetary amount in a specific currency: Square's Money, and Stripe's amount beside its currency.
The amount is always an integer count of the currency's minor unit — pence for GBP, cents for USD. Zero-decimal currencies such as JPY have a minor unit equal to their major unit, so {"amount": 500, "currency": "JPY"} is ¥500 while {"amount": 500, "currency": "GBP"} is £5.00.
Floating point is never used for money anywhere in this API. Binary floats cannot represent most decimal fractions exactly, so accumulating them across the line items of an order produces totals that disagree with the printed receipt by a penny. Integer minor units make every arithmetic operation exact.

amountinteger · int64

Required
The amount, as a whole number of the currency's minor unit. May be negative to express a refund, discount or credit.

currencyCurrency

Required
ISO 4217 currency code.
Determines the minor unit that Money.amount is expressed in. Zero-decimal currencies such as JPY have a minor unit equal to the major unit.
One of 182 values; see the schema.

inclusiveboolean

Required
Whether this rate is inside the price (true) or added on top (false).

percentagePercentage

Required
A share of a whole, from "0" to "100", as a percentage in a decimal string with at most four decimal places, as Square's percentage and Stripe Tax's percentage_decimal are: UK VAT at 20% is "20", and an 8.875% US sales tax is "8.875".
A string because a JSON number is a binary float to most parsers, and a float cannot hold most decimal fractions exactly (RFC 7493 §2.2). Tenvelo computes with a percentage as an integer in parts per million ("8.875" is 88750), which every four-place percentage is exactly. A client that computes with one should read the digits the same way, never through a float.
pattern ^(100(\.0{1,4})?|(0|[1-9][0-9]?)(\.[0-9]{1,4})?)$

rate_idstring · uuid

Required
The rate this share belongs to.

tax_inclusiveboolean
Whether unit_price already contains the tax. Snapshot.

tax_rate_percentagePercentage
A share of a whole, from "0" to "100", as a percentage in a decimal string with at most four decimal places, as Square's percentage and Stripe Tax's percentage_decimal are: UK VAT at 20% is "20", and an 8.875% US sales tax is "8.875".
A string because a JSON number is a binary float to most parsers, and a float cannot hold most decimal fractions exactly (RFC 7493 §2.2). Tenvelo computes with a percentage as an integer in parts per million ("8.875" is 88750), which every four-place percentage is exactly. A client that computes with one should read the digits the same way, never through a float.
pattern ^(100(\.0{1,4})?|(0|[1-9][0-9]?)(\.[0-9]{1,4})?)$

totalMoney

Required
A monetary amount in a specific currency: Square's Money, and Stripe's amount beside its currency.
The amount is always an integer count of the currency's minor unit — pence for GBP, cents for USD. Zero-decimal currencies such as JPY have a minor unit equal to their major unit, so {"amount": 500, "currency": "JPY"} is ¥500 while {"amount": 500, "currency": "GBP"} is £5.00.
Floating point is never used for money anywhere in this API. Binary floats cannot represent most decimal fractions exactly, so accumulating them across the line items of an order produces totals that disagree with the printed receipt by a penny. Integer minor units make every arithmetic operation exact.

amountinteger · int64

Required
The amount, as a whole number of the currency's minor unit. May be negative to express a refund, discount or credit.

currencyCurrency

Required
ISO 4217 currency code.
Determines the minor unit that Money.amount is expressed in. Zero-decimal currencies such as JPY have a minor unit equal to the major unit.
One of 182 values; see the schema.

unit_of_measurestring · enum

Nullable
The unit this line was sold in, snapshotted from the product at the moment of sale (the product's own unit on a product line; any unit on an ad-hoc line). Absent means each.
eachkgglml

unit_priceMoney

Required
A monetary amount in a specific currency: Square's Money, and Stripe's amount beside its currency.
The amount is always an integer count of the currency's minor unit — pence for GBP, cents for USD. Zero-decimal currencies such as JPY have a minor unit equal to their major unit, so {"amount": 500, "currency": "JPY"} is ¥500 while {"amount": 500, "currency": "GBP"} is £5.00.
Floating point is never used for money anywhere in this API. Binary floats cannot represent most decimal fractions exactly, so accumulating them across the line items of an order produces totals that disagree with the printed receipt by a penny. Integer minor units make every arithmetic operation exact.

amountinteger · int64

Required
The amount, as a whole number of the currency's minor unit. May be negative to express a refund, discount or credit.

currencyCurrency

Required
ISO 4217 currency code.
Determines the minor unit that Money.amount is expressed in. Zero-decimal currencies such as JPY have a minor unit equal to the major unit.
One of 182 values; see the schema.

variant_idstring · uuid

Nullable
The variant that was sold, for reporting and stock. Null when the product itself is the sellable unit — a product with no variants, or with none picked. Like product_id, it is retained for reporting and never re-resolved: the descriptive and monetary fields on this line are the snapshot that is replayed, so a sale that was correct when rung stays correct even if the catalogue has changed since.

line_item_voidOrderFactLineItemVoid

Some or all of a line taken back off an order before it was paid for. The void is a record of its own, as a refund or a reversal is: the line it names is never edited, and what the line stands at is what was rung up less every void of it.

approved_by_memberMemberSnapshot

A member of the team as whoever recorded it knew them when it happened: who they were, what they were called and how to reach them, and the role they held. A fact keeps all of it, so a later rename, new address or change of role restates nothing it says.

idstring · uuid

Required
The roster's id, checked against the merchant's memberships.

namestring

Required
What the member was called.
≥ 1 chars

emailstring · email

Required
The member's address.

rolestring · enum

Required
The role the member held.
ownermanagerstaff

line_item_idstring · uuid

Required
The line voided, by the id the device minted for it.

notestring
What happened, in the staff member's words. Required when reason is other.
≤ 512 chars

quantityQuantity

Required
How much of something, as a decimal string in the unit_of_measure beside it (each where there is none), as Square's quantity is: three croissants are "3", 1.4 kg of beans is "1.4". A string because a JSON number is a binary float to most parsers.
It has at most as many decimal places as its unit's base unit holds — three in each, g and ml, six in kg and l — and a finer one is refused, never rounded. Tenvelo holds every quantity as an integer of that base unit (thousandths of an each, milligrams, microlitres; docs/decisions/0063); a client that computes with one should read the digits the same way, never through a float.
≤ 26 chars · pattern ^-?(0|[1-9][0-9]*)(\.[0-9]{1,6})?$

reasonstring · enum

Required
Why, kept apart from the arithmetic. comp is a line given away after it was rung up; a discount given as it is rung up is on the line itself.
customer_changed_mindstaff_errorcompother

location_idstring · uuid

Required
The location the order is at, which every fact about it names, as Square's order does. The server applies a location's facts in the order it took them, and each location's apart from the others'. A till begins orders at its own location. Every other fact names its order's location wherever it was taken, so a refund at another location is its sale's. A fact naming a different location from its order's fails.

memberMemberSnapshot

Nullable
The staff member who did it, as the till knew them then; checked against the merchant's memberships when the fact is applied. Null when no person was attributed.

idstring · uuid

Required
The roster's id, checked against the merchant's memberships.

namestring

Required
What the member was called.
≥ 1 chars

emailstring · email

Required
The member's address.

rolestring · enum

Required
The role the member held.
ownermanagerstaff

occurred_atstring · date-time
What the recording device's own clock read when it recorded the fact, kept as it said it. Nothing is decided by it: the stamp (hlc) is when the fact happened.

orderOrderFactCreated

An order begun: a tab opened, a counter sale started, a guest's order asked for. What it holds — its lines, its payments — arrives as facts of their own, in the same batch or later. Whether an order needs accepting is decided from where it came from, never said here.

namestring
Whose order it is while it is open — a name the shop shouts across the bar.
≤ 128 chars

coversinteger · int32
How many people the party is, as counted at seating; zero where nobody counted them. It is stated when the order begins and is what the covers-per-labour-hour and average-spend-per-cover figures are divided by, so a tab opened without a count adds no covers rather than one.
0–1000 · default 0

currencyCurrency

Required
ISO 4217 currency code.
Determines the minor unit that Money.amount is expressed in. Zero-decimal currencies such as JPY have a minor unit equal to the major unit.
One of 182 values; see the schema.

customer_idstring · uuid
The guest the order is recorded against, if one was linked when it began.

delivery_addressAddress

A postal address.
The address_line_* fields carry the most specific part of the address — street number, street name, building name. Less specific detail belongs in locality, administrative_district_level_* and country.
The administrative_district_level_* fields are deliberately generic because their meaning is country-dependent: in the US level 1 is the state and level 2 the county; in the UK level 1 is the county.

address_line_1string

Required
First line of the address — street number, street name, building name.
≤ 255 chars

address_line_2string
Second line of the address, if any.
≤ 255 chars

address_line_3string
Third line of the address, if any.
≤ 255 chars

administrative_district_level_1string
A civil entity within the country. The state in the US; the county in the UK.
≤ 128 chars

administrative_district_level_2string
A civil entity within administrative_district_level_1.
≤ 128 chars

countryCountry

Required
ISO 3166-1 alpha-2 country code.
ZZ is the unknown/unspecified placeholder.
One of 250 values; see the schema.

localitystring
The city or town.
≤ 128 chars

postal_codestring
The postal or ZIP code.
≤ 32 chars

sublocalitystring
A civil region within the locality, if any.
≤ 128 chars

drawer_session_idstring · uuid
The drawer session the till had open when the order began, if any.

email_receiptboolean
The guest asked for the receipt by email. The address is always their customer record's, and honoured only with their consent.
default false

external_referencestring
The writer's own reference for the order — a delivery platform's order id — so the venue can match what the platform later says about it.
≤ 128 chars

fulfillment_typestring · enum
How the order leaves the building — eaten in, collected, or delivered — which a tax rule is keyed by (docs/decisions/0014).
on_premisespickupdelivery
default on_premises

location_idstring · uuid

Required
Where the order is being served, which every later fact about it inherits.

owner_memberMemberSnapshot

A member of the team as whoever recorded it knew them when it happened: who they were, what they were called and how to reach them, and the role they held. A fact keeps all of it, so a later rename, new address or change of role restates nothing it says.

idstring · uuid

Required
The roster's id, checked against the merchant's memberships.

namestring

Required
What the member was called.
≥ 1 chars

emailstring · email

Required
The member's address.

rolestring · enum

Required
The role the member held.
ownermanagerstaff

pickup_atstring · date-time
When the guest was told they could collect, where somebody promised a time.

table_idstring · uuid
The table the order is parked on, if any.

order_idstring · uuid

Required
The order this happened to, whose id the device that began it minted. A fact may name an order whose created has not arrived yet.

paymentPayment

How a sale was paid for.
A list rather than a single method, because a real sale splits: twenty pounds in cash and the rest on a card is ordinary, and a model that cannot express it forces staff to lie to the till.
Shaped to match Square's Tender, deliberately. Staff and integrators move between these systems, and the places where Square's model is subtle are places it has already been proven wrong the other way: amount includes the tip, cash records what the buyer actually handed over, and change is calculated rather than claimed.
This records payment; it does not take it. Cash is settled by definition — it is in the drawer. A card row is a claim about what the terminal reported, and becomes money only when the PSP settles it.

idstring · uuid
The payment's id. Minted by the device, so a retry of the same tender converges on the same row instead of recording the money twice; the server mints one when a writer does not supply it. A refund names it as payment_id, and a card refund is reversed against it, so it is returned with every read of the order and never renumbered.

amountMoney

Required
The total taken by this payment, including any tip.
Following Square: the tender's amount is what the customer parted with, and tip is the portion of it that is not for goods. Modelling it the other way — an amount that excludes the tip — means every reconciliation has to remember to add the two back together, and one place that forgets is a day's takings that do not balance.

amountinteger · int64

Required
The amount, as a whole number of the currency's minor unit. May be negative to express a refund, discount or credit.

currencyCurrency

Required
ISO 4217 currency code.
Determines the minor unit that Money.amount is expressed in. Zero-decimal currencies such as JPY have a minor unit equal to the major unit.
One of 182 values; see the schema.

buyer_suppliedMoney

Nullable
What the customer physically handed over. Cash only.
Recorded rather than assumed so that change is derived from it: a note tendered for a smaller sale is the ordinary case, and the drawer at close must agree with the sum of what went in.

amountinteger · int64

Required
The amount, as a whole number of the currency's minor unit. May be negative to express a refund, discount or credit.

currencyCurrency

Required
ISO 4217 currency code.
Determines the minor unit that Money.amount is expressed in. Zero-decimal currencies such as JPY have a minor unit equal to the major unit.
One of 182 values; see the schema.

card_brandstring

Read only
The scheme the processor read off the card, in its own words ("visa", "mastercard", "amex"). Card payments only; absent where the processor reports none.

card_confirmationstring · enum

Read only
How the card payment was confirmed against the checkout the processor says took it: confirmed when the approved checkout's amount matched and it belongs to this sale, unconfirmed when it is not approved, belongs to another sale, or took a different amount. An unconfirmed sale is still recorded — the money may already have moved — but the payment is flagged for a person to reconcile. The server's word, never the till's. Absent for a payment that is not a card, and for a card the till recorded by reference on a third-party terminal, which has no checkout to confirm against.
confirmedunconfirmed

card_last4string

Read only
The last four digits of the card that paid, as the processor masked them — what a payment shows as "Visa •• 4242", and what a person types into the order list's search to find the sale. Card payments only; absent where the processor reports none. Never the PAN.
≤ 4 chars

change_backMoney

NullableRead only
Change handed back, calculated by the server as buyer_supplied - amount and never accepted from a client.
Derived rather than submitted because it is the one figure a till could get wrong in a way that balances on screen and not in the drawer.

amountinteger · int64

Required
The amount, as a whole number of the currency's minor unit. May be negative to express a refund, discount or credit.

currencyCurrency

Required
ISO 4217 currency code.
Determines the minor unit that Money.amount is expressed in. Zero-decimal currencies such as JPY have a minor unit equal to the major unit.
One of 182 values; see the schema.

fingerprintstring

Read only
The processor's card-alias token, never the PAN, for a card payment it could identify. It is what lets a returning card be recognised without the card number. Card payments only; absent for cash and vouchers, and for a card payment the processor did not identify.
≤ 256 chars

gift_card_hold_idstring · uuid
The hold a till took on the voucher's card before tendering it (batchCreateGiftCardHolds), which this payment settles. Absent for a voucher tendered offline, which is spent against what the till last knew of the card.

line_idsarray of string · uuid
The lines this payment settled, when the till knows the split: a share pays whole lines, so a reopened tab shows the unpaid lines rather than a number, and a mistake cannot charge somebody twice (tabs item 13).
Empty when the payment named no lines — a whole-sale tender, an even split, a card share settling what is left, and every payment recorded before this existed. Empty and absent mean the same thing and are accepted alike, and a till sends the empty array.

memberMemberSnapshot

Nullable
The member who took this tender — the terminal operator who took the tip, not whoever rang the sale. The kept tip rule follows it. Absent for a payment recorded by something that is not a person.

idstring · uuid

Required
The roster's id, checked against the merchant's memberships.

namestring

Required
What the member was called.
≥ 1 chars

emailstring · email

Required
The member's address.

rolestring · enum

Required
The role the member held.
ownermanagerstaff

methodstring · enum

Required
cash — taken into the drawer. Settled by definition: nothing to capture, nothing that can later fail.
card — captured through the PSP. Recorded here as what the terminal reported, not as proof of settlement.
voucher — a gift card or credit note redeemed against the sale.
account — put on a customer's account to settle later. Requires the sale to name the customer (customer_id) and the merchant to have an open customer account for them; the till chooses the account at the tender and links the sale to its customer (retail: customer accounts).
A loyalty redemption is not a payment method any more: a reward redeems against its discount definition, the order line carries the discount, and the server spends the guest's points when the order is written. The points method was retired.
external — money a channel took before the order reached the venue: an online storefront, a delivery platform. The merchant settles with that channel, so the tender records the platform's reference rather than a card payment this merchant never captured. Only valid on an order a channel wrote, and the reference is required.
cashcardvoucheraccountexternal

pinstring
A voucher's PIN — the scratch-off second factor that proves possession of the card whose code is in reference (gift cards item 20). Required only when the card carries a PIN (a pre-printed or merchant-supplied code); a card with a generated code needs none, and the server refuses a sale whose voucher cannot prove the PIN. Only the hash is stored and compared; the plaintext never comes back.
≤ 12 chars

referencestring
The PSP's identifier for a card payment, or a voucher's code. Cash has neither and needs neither. Required for an external tender: it is the platform's own transaction or order reference, which is what reconciliation against that channel relies on.
≤ 128 chars

tipMoney

Nullable
The part of amount that is a gratuity rather than payment for goods.
Present because hospitality is not an edge case here: a bar or restaurant tab is the core flow, and a till that cannot record a tip cannot be used in one.

amountinteger · int64

Required
The amount, as a whole number of the currency's minor unit. May be negative to express a refund, discount or credit.

currencyCurrency

Required
ISO 4217 currency code.
Determines the minor unit that Money.amount is expressed in. Zero-decimal currencies such as JPY have a minor unit equal to the major unit.
One of 182 values; see the schema.

previous_hashstring
The hash of the fact this device recorded before this one, so a device's facts are one chain: SHA-256 over that fact's canonical form — the fact as sent, less its signature, in RFC 8785's JSON Canonicalization Scheme — in base64url without padding. Absent on a device's first fact. A fact that does not follow the one before it is recorded, and flagged chain_broken.
pattern ^[A-Za-z0-9_-]{43}$

refundOrderFactRefund

Money given back against a completed order. A refund is a new ledger entry: the sale stays completed, and this is the record of the money returning. It is applied against the order as the server holds it, and a refund the server cannot apply — more than was paid, a sale since voided — is kept and flagged for a person rather than refused.
A blind return, which has no sale behind it, is not a fact about an order and is written through orders/batch-refund.

idstring · uuid

Required
The refund id, minted by the device, which is what finds the refund again when the fact is sent twice.

approved_by_memberMemberSnapshot

A member of the team as whoever recorded it knew them when it happened: who they were, what they were called and how to reach them, and the role they held. A fact keeps all of it, so a later rename, new address or change of role restates nothing it says.

idstring · uuid

Required
The roster's id, checked against the merchant's memberships.

namestring

Required
What the member was called.
≥ 1 chars

emailstring · email

Required
The member's address.

rolestring · enum

Required
The role the member held.
ownermanagerstaff

destinationstring · enum
Where the refunded value went. store_credit issues a gift card for it.
moneystore_credit
default money

drawer_session_idstring · uuid
The drawer session a cash refund took money out of. Omitted when no cash went back.

exchange_replacement_order_idstring · uuid
The replacement sale this refund exchanges into (retail item 6). If it has not reached the server when the refund is applied, the refund is applied and the pairing flagged.

line_itemsarray of RefundLineItem

The lines returned and how much of each. Absent means the whole sale.

line_idstring · uuid

Required

quantityQuantity
How much of something, as a decimal string in the unit_of_measure beside it (each where there is none), as Square's quantity is: three croissants are "3", 1.4 kg of beans is "1.4". A string because a JSON number is a binary float to most parsers.
It has at most as many decimal places as its unit's base unit holds — three in each, g and ml, six in kg and l — and a finer one is refused, never rounded. Tenvelo holds every quantity as an integer of that base unit (thousandths of an each, milligrams, microlitres; docs/decisions/0063); a client that computes with one should read the digits the same way, never through a float.
≤ 26 chars · pattern ^-?(0|[1-9][0-9]*)(\.[0-9]{1,6})?$

unit_of_measurestring · enum
The unit quantity is in. It must measure what the line does, or the refund is refused. Absent means each.
eachkgglml

notestring
≤ 512 chars

paymentsarray of RefundPayment

How the money went back. Required for a money refund; absent for a store_credit one, which issues a gift card instead.
≤ 10 items

idstring · uuid

Required

amountMoney

Required
A monetary amount in a specific currency: Square's Money, and Stripe's amount beside its currency.
The amount is always an integer count of the currency's minor unit — pence for GBP, cents for USD. Zero-decimal currencies such as JPY have a minor unit equal to their major unit, so {"amount": 500, "currency": "JPY"} is ¥500 while {"amount": 500, "currency": "GBP"} is £5.00.
Floating point is never used for money anywhere in this API. Binary floats cannot represent most decimal fractions exactly, so accumulating them across the line items of an order produces totals that disagree with the printed receipt by a penny. Integer minor units make every arithmetic operation exact.

amountinteger · int64

Required
The amount, as a whole number of the currency's minor unit. May be negative to express a refund, discount or credit.

currencyCurrency

Required
ISO 4217 currency code.
Determines the minor unit that Money.amount is expressed in. Zero-decimal currencies such as JPY have a minor unit equal to the major unit.
One of 182 values; see the schema.

methodstring · enum

Required
cashcardvoucheraccountpoints

payment_idstring · uuid
The original payment this refund reverses. Null for a cash refund, which has no payment to point at.

referencestring
The card's code on a voucher refund, so the value returns to the card it came from. Omitted for cash and card refunds.

reasonstring

Required
Why the money went back, in the staff member's words.
≤ 512 chars

restockboolean
Whether the returned items went back into sellable stock.
default false

statutoryboolean
Whether this refund is the law's: faulty goods or goods not as described, where the money goes back to the payer (decision 0073). A statutory refund is never store_credit.
default false

store_credit_codestring
The code of the gift card a store_credit refund issues, as the till printed it. Required when destination is store_credit.

signaturestring
The device's signature over this fact's canonical form, with the key it enrolled: a detached JWS (RFC 7515 Appendix F) in compact form, header..signature. Its protected header is alg ES256, kid the key's RFC 7638 thumbprint, and typ fact-seal (RFC 8725 §3.11); its signature is the 64-byte r‖s in base64url without padding (RFC 7518 §3.4); its payload is the canonical form, which the fact itself carries, so any JOSE library verifies it given those bytes. A signature no key the device has held made is recorded, and flagged seal_broken. The canonical form is only defined for I-JSON (RFC 7493), so a sealed fact that names a field twice, or twice but for case, or carries a number beyond ±(2^53−1), is recorded and flagged seal_ambiguous. A fact with neither this nor previous_hash is not in a chain, and is not flagged for it.
pattern ^[A-Za-z0-9_-]{16,500}\.\.[A-Za-z0-9_-]{86}$

updateOrderFactUpdate

A change to what an order is labelled with, as a JSON Merge Patch (RFC 7396): a field present is set, a field set to null is cleared, a field absent is left alone. These are the one thing about an order that does not merge — two changes to one field race, and the later on the order's log wins — so money never travels here: lines, payments and voids are facts of their own.

namestring

Nullable
Whose order it is while it is open; null to clear it.
≤ 128 chars

coversinteger · int32
How many people the party turned out to be; zero if nobody counted after all. A recount is a correction to what was said at seating, not a second statement of it.
0–1000

customer_idstring · uuid

Nullable
The guest the order is now recorded against; null to unlink one. On a completed order this is not how a guest is changed: that is a void and a new sale.

delivery_addressAddress

Nullable
Where a delivery order goes, as the writer corrects it; null to clear it.

address_line_1string

Required
First line of the address — street number, street name, building name.
≤ 255 chars

address_line_2string
Second line of the address, if any.
≤ 255 chars

address_line_3string
Third line of the address, if any.
≤ 255 chars

administrative_district_level_1string
A civil entity within the country. The state in the US; the county in the UK.
≤ 128 chars

administrative_district_level_2string
A civil entity within administrative_district_level_1.
≤ 128 chars

countryCountry

Required
ISO 3166-1 alpha-2 country code.
ZZ is the unknown/unspecified placeholder.
One of 250 values; see the schema.

localitystring
The city or town.
≤ 128 chars

postal_codestring
The postal or ZIP code.
≤ 32 chars

sublocalitystring
A civil region within the locality, if any.
≤ 128 chars

email_receiptboolean

Nullable
Whether the guest now wants the receipt by email; false or null turns it off. Nullable so that turning it off is a value a patch carries, not one it drops.

external_referencestring

Nullable
The writer's own reference for the order, changed here; null to clear it.
≤ 128 chars

fulfillment_typestring · enum
How the order now leaves the building — a table's order turned takeaway.
on_premisespickupdelivery

owner_memberMemberSnapshot

A member of the team as whoever recorded it knew them when it happened: who they were, what they were called and how to reach them, and the role they held. A fact keeps all of it, so a later rename, new address or change of role restates nothing it says.

idstring · uuid

Required
The roster's id, checked against the merchant's memberships.

namestring

Required
What the member was called.
≥ 1 chars

emailstring · email

Required
The member's address.

rolestring · enum

Required
The role the member held.
ownermanagerstaff

table_idstring · uuid

Nullable
The table the order is moved to; null when it leaves a table.

voidOrderFactVoid

A completed order reversed. It is kept, voided, rather than deleted: a merchant, and later a regulator, needs to see that a sale happened and was reversed, not that it never existed.

approved_by_memberMemberSnapshot

A member of the team as whoever recorded it knew them when it happened: who they were, what they were called and how to reach them, and the role they held. A fact keeps all of it, so a later rename, new address or change of role restates nothing it says.

idstring · uuid

Required
The roster's id, checked against the merchant's memberships.

namestring

Required
What the member was called.
≥ 1 chars

emailstring · email

Required
The member's address.

rolestring · enum

Required
The role the member held.
ownermanagerstaff

notestring
What happened, in the staff member's words. Required when reason is other.
≤ 512 chars

reasonstring · enum

Required
Why the sale was reversed, kept apart from what the reversal did.
customer_canceledstaff_errorrefundother

400
The request could not be parsed. Malformed JSON, a bad query parameter, or a header that failed to decode, among them an API-Version later than the server speaks or not a date (api-version-unknown, with the server's own in api_version).
Distinct from 422: a 400 never reached validation, so invalid_params is absent. Retrying without changing the request will fail again, except that a request refused for its API-Version goes once the server is updated.

401
No credentials, or credentials that could not be verified — missing bearer token, malformed JWT, expired token, or a signature that failed against the issuer's JWKS.
Refresh the token and retry once. Repeated 401 after a refresh means the device needs to re-enrol.

403
Authenticated, but not permitted. The token is valid and its merchant was resolved, but the caller's role does not allow this operation, or the target belongs to a different merchant.
Cross-tenant access is reported as 403 on a resource the caller may not see, and as 404 where even confirming existence would leak information. Retrying will not help.

404
No such resource, or none visible to this caller.
Also returned instead of 403 where acknowledging existence would itself leak information — so a 404 does not prove the id is unused globally, only that it is not yours.

410
The request names an API-Version this server no longer serves (docs/decisions/0011). Nothing in it was read. api_version names the version the server speaks: the client is behind, and sends the request again once it is updated.

429
Rate limit exceeded. Honour Retry-After rather than applying your own backoff.
A fleet of tills coming back online together after an outage is the realistic cause, which is exactly when uncoordinated client-side retry turns a brief outage into a sustained one. The limit is per process, and per site for what records trade there — a request spends its site's budget, and a till's own smaller one inside it — and per (client, merchant) for everything else; no RateLimit field is sent, so this response and its Retry-After are the whole of the contract.

500
Something failed on our side. trace_id identifies the request in our tracing — quote it in a support ticket.
The body never carries internal detail: no SQL, no stack traces, no upstream error strings. Safe to retry with the same Idempotency-Key.

503
Temporarily unable to serve the request — a dependency is down or the service is shedding load.
Retry with the same Idempotency-Key after Retry-After. This is always safe: a request that did take effect before the failure will be recognised as a replay.
Request
curl -X GET 'https://api.tenvelo.com/v1/orders/0192f1e4-7c3a-7b2e-9f10-5d6c7e8f9a0b/facts' \ -H "Authorization: Bearer $TOKEN"
Response
{ "items": [ { "id": "0192f1e4-7c3a-7b2e-9f10-5d6c7e8f9a0b", "type": "created", "acceptance": { "note": "string", "pickup_at": "2026-09-11T09:30:00Z", "rejection_reason": "sold_out" }, "cancellation": { "note": "string", "reason": "abandoned" }, "completion": { "age_confirmed": false, "age_minimum": 0, "document": { "kind": "invoice", "number": 148, "series": "B1-T3" }, "loyalty_hold_id": "0192f1e4-7c3a-7b2e-9f10-5d6c7e8f9a0b", "reference": "string", "service_charge": { "amount": 1250, "currency": "GBP" }, "service_charge_declined": false, "totals": { "cash_rounding": { "amount": 1250, "currency": "GBP" }, "discount_total": { "amount": 1250, "currency": "GBP" }, "service_charge": { "amount": 1250, "currency": "GBP" }, "service_charge_tax": { "amount": 1250, "currency": "GBP" }, "subtotal": { "amount": 1250, "currency": "GBP" }, "tax_total": { "amount": 1250, "currency": "GBP" }, "total": { "amount": 1250, "currency": "GBP" } } }, "device_seq": 1, "happened_at": "2026-09-11T09:30:00Z", "hlc": "117356101632000000", "line_item": { "id": "0192f1e4-7c3a-7b2e-9f10-5d6c7e8f9a0b", "name": "Flat white", "approved_by_member": { "id": "0192f1e4-7c3a-7b2e-9f10-5d6c7e8f9a0b", "name": "string", "email": "ada@example.com", "role": "owner" }, "category_id": "0192f1e4-7c3a-7b2e-9f10-5d6c7e8f9a0b", "category_name": "string", "comp_reason": "string", "course": 1, "discount": { "amount": 1250, "currency": "GBP" }, "discount_id": "0192f1e4-7c3a-7b2e-9f10-5d6c7e8f9a0b", "discount_name": "string", "gift_card_code": "string", "gift_card_token_hash": "string", "modifiers": [ { "id": "0192f1e4-7c3a-7b2e-9f10-5d6c7e8f9a0b", "name": "Oat milk", "price_delta": { "amount": 1250, "currency": "GBP" } } ], "multibuy": { "every": 2, "price": { "amount": 1250, "currency": "GBP" } }, "note": "string", "origin": "till", "product_id": "0192f1e4-7c3a-7b2e-9f10-5d6c7e8f9a0b", "product_type": "standard", "quantity": "3", "seat": 1, "sent_at": "2026-09-11T09:30:00Z", "serials": [], "tax": { "amount": 1250, "currency": "GBP" }, "tax_breakdown": [ { "amount": { "amount": 1250, "currency": "GBP" }, "inclusive": false, "percentage": "20", "rate_id": "0192f1e4-7c3a-7b2e-9f10-5d6c7e8f9a0b" } ], "tax_inclusive": false, "tax_rate_percentage": "20", "total": { "amount": 1250, "currency": "GBP" }, "unit_of_measure": "each", "unit_price": { "amount": 1250, "currency": "GBP" }, "variant_id": "0192f1e4-7c3a-7b2e-9f10-5d6c7e8f9a0b" }, "line_item_void": { "approved_by_member": { "id": "0192f1e4-7c3a-7b2e-9f10-5d6c7e8f9a0b", "name": "string", "email": "ada@example.com", "role": "owner" }, "line_item_id": "0192f1e4-7c3a-7b2e-9f10-5d6c7e8f9a0b", "note": "string", "quantity": "3", "reason": "customer_changed_mind" }, "location_id": "0192f1e4-7c3a-7b2e-9f10-5d6c7e8f9a0b", "member": { "id": "0192f1e4-7c3a-7b2e-9f10-5d6c7e8f9a0b", "name": "string", "email": "ada@example.com", "role": "owner" }, "occurred_at": "2026-09-11T09:30:00Z", "order": { "name": "string", "covers": 0, "currency": "AED", "customer_id": "0192f1e4-7c3a-7b2e-9f10-5d6c7e8f9a0b", "delivery_address": { "address_line_1": "12 Bridge Street", "address_line_2": "string", "address_line_3": "string", "administrative_district_level_1": "Somerset", "administrative_district_level_2": "string", "country": "ZZ", "locality": "Bristol", "postal_code": "BS1 4ST", "sublocality": "string" }, "drawer_session_id": "0192f1e4-7c3a-7b2e-9f10-5d6c7e8f9a0b", "email_receipt": false, "external_reference": "string", "fulfillment_type": "on_premises", "location_id": "0192f1e4-7c3a-7b2e-9f10-5d6c7e8f9a0b", "owner_member": { "id": "0192f1e4-7c3a-7b2e-9f10-5d6c7e8f9a0b", "name": "string", "email": "ada@example.com", "role": "owner" }, "pickup_at": "2026-09-11T09:30:00Z", "table_id": "0192f1e4-7c3a-7b2e-9f10-5d6c7e8f9a0b" }, "order_id": "0192f1e4-7c3a-7b2e-9f10-5d6c7e8f9a0b", "payment": { "id": "0192f1e4-7c3a-7b2e-9f10-5d6c7e8f9a0b", "amount": { "amount": 1250, "currency": "GBP" }, "buyer_supplied": { "amount": 1250, "currency": "GBP" }, "card_brand": "string", "card_confirmation": "confirmed", "card_last4": "string", "change_back": { "amount": 1250, "currency": "GBP" }, "fingerprint": "string", "gift_card_hold_id": "0192f1e4-7c3a-7b2e-9f10-5d6c7e8f9a0b", "line_ids": [ "0192f1e4-7c3a-7b2e-9f10-5d6c7e8f9a0b" ], "member": { "id": "0192f1e4-7c3a-7b2e-9f10-5d6c7e8f9a0b", "name": "string", "email": "ada@example.com", "role": "owner" }, "method": "cash", "pin": "string", "reference": "pspRef_8829301", "tip": { "amount": 1250, "currency": "GBP" } }, "previous_hash": "string", "refund": { "id": "0192f1e4-7c3a-7b2e-9f10-5d6c7e8f9a0b", "approved_by_member": { "id": "0192f1e4-7c3a-7b2e-9f10-5d6c7e8f9a0b", "name": "string", "email": "ada@example.com", "role": "owner" }, "destination": "money", "drawer_session_id": "0192f1e4-7c3a-7b2e-9f10-5d6c7e8f9a0b", "exchange_replacement_order_id": "0192f1e4-7c3a-7b2e-9f10-5d6c7e8f9a0b", "line_items": [ { "line_id": "0192f1e4-7c3a-7b2e-9f10-5d6c7e8f9a0b", "quantity": "3", "unit_of_measure": "each" } ], "note": "string", "payments": [ { "id": "0192f1e4-7c3a-7b2e-9f10-5d6c7e8f9a0b", "amount": { "amount": 1250, "currency": "GBP" }, "method": "cash", "payment_id": "0192f1e4-7c3a-7b2e-9f10-5d6c7e8f9a0b", "reference": "string" } ], "reason": "string", "restock": false, "statutory": false, "store_credit_code": "string" }, "signature": "string", "update": { "name": "string", "covers": 0, "customer_id": "0192f1e4-7c3a-7b2e-9f10-5d6c7e8f9a0b", "delivery_address": { "address_line_1": "12 Bridge Street", "address_line_2": "string", "address_line_3": "string", "administrative_district_level_1": "Somerset", "administrative_district_level_2": "string", "country": "ZZ", "locality": "Bristol", "postal_code": "BS1 4ST", "sublocality": "string" }, "email_receipt": false, "external_reference": "string", "fulfillment_type": "on_premises", "owner_member": { "id": "0192f1e4-7c3a-7b2e-9f10-5d6c7e8f9a0b", "name": "string", "email": "ada@example.com", "role": "owner" }, "table_id": "0192f1e4-7c3a-7b2e-9f10-5d6c7e8f9a0b" }, "void": { "approved_by_member": { "id": "0192f1e4-7c3a-7b2e-9f10-5d6c7e8f9a0b", "name": "string", "email": "ada@example.com", "role": "owner" }, "note": "string", "reason": "customer_canceled" } } ] }
POST/v1/orders/{id}/payment-links

Mint a payment link for an order

No. mintOrderPaymentLinkAuth terminal-checkouts:write
Gives the caller's open order the one payment link a guest pays by card from their own device (virtual-till item 4). The link is the credential — the token is returned once, only its hash is kept — and it stops working when it expires, or the moment a new one is minted, or the order is settled.
A till or a manager may mint; the link is for an order still owed, so a settled order is refused. A merchant without a payment account that takes card-not-present gets the link anyway — refusing to mint is the guest's problem, not the merchant's; the pay side answers with what the merchant's processor can do.
Parameters

idpath · string · uuid
Required
The order being paid for.

Idempotency-Keyheader · string
Required
A client-generated key making this request safe to retry.
Required on every mutation that creates a resource or moves money. A till on bad wifi cannot tell a lost response from a lost request; without a key its only options are to risk a duplicate sale or to drop a real one. With a key it retries freely: the first request to arrive is processed, and every replay returns that same stored response.
Rules:
Mint the key once, when the operation is first queued, and reuse it for every retry. A fresh key per attempt defeats the mechanism entirely.
Keys are scoped per merchant and per operation, and are retained for 30 days — long enough that a till switched off mid-sync can retry with the same key however long it stayed on the shelf.
Replaying a key with a different request body is a client bug and is rejected with 422, rather than silently returning the first result — quietly serving the old response would hide a real inconsistency in the caller.
A UUIDv7 or ULID is a good choice.
Responses

201
The link.

PaymentLink · application/json

expires_atstring · date-time

Required
When the link stops being good.

tokenstring

Required
The link's secret, random and never derived from the order id.
43–43 chars

400
The request could not be parsed. Malformed JSON, a bad query parameter, or a header that failed to decode, among them an API-Version later than the server speaks or not a date (api-version-unknown, with the server's own in api_version).
Distinct from 422: a 400 never reached validation, so invalid_params is absent. Retrying without changing the request will fail again, except that a request refused for its API-Version goes once the server is updated.

401
No credentials, or credentials that could not be verified — missing bearer token, malformed JWT, expired token, or a signature that failed against the issuer's JWKS.
Refresh the token and retry once. Repeated 401 after a refresh means the device needs to re-enrol.

403
Authenticated, but not permitted. The token is valid and its merchant was resolved, but the caller's role does not allow this operation, or the target belongs to a different merchant.
Cross-tenant access is reported as 403 on a resource the caller may not see, and as 404 where even confirming existence would leak information. Retrying will not help.

404
No such resource, or none visible to this caller.
Also returned instead of 403 where acknowledging existence would itself leak information — so a 404 does not prove the id is unused globally, only that it is not yours.

409
The request conflicts with current state — a uniqueness constraint, or an attempt to mutate an order that is already completed or voided.
Unlike 412, re-reading and retrying unchanged will not resolve it; the request itself has to change.

410
The request names an API-Version this server no longer serves (docs/decisions/0011). Nothing in it was read. api_version names the version the server speaks: the client is behind, and sends the request again once it is updated.

429
Rate limit exceeded. Honour Retry-After rather than applying your own backoff.
A fleet of tills coming back online together after an outage is the realistic cause, which is exactly when uncoordinated client-side retry turns a brief outage into a sustained one. The limit is per process, and per site for what records trade there — a request spends its site's budget, and a till's own smaller one inside it — and per (client, merchant) for everything else; no RateLimit field is sent, so this response and its Retry-After are the whole of the contract.

500
Something failed on our side. trace_id identifies the request in our tracing — quote it in a support ticket.
The body never carries internal detail: no SQL, no stack traces, no upstream error strings. Safe to retry with the same Idempotency-Key.

503
Temporarily unable to serve the request — a dependency is down or the service is shedding load.
Retry with the same Idempotency-Key after Retry-After. This is always safe: a request that did take effect before the failure will be recognised as a replay.
Request
curl -X POST 'https://api.tenvelo.com/v1/orders/0192f1e4-7c3a-7b2e-9f10-5d6c7e8f9a0b/payment-links' \ -H "Authorization: Bearer $TOKEN" \ -H 'Idempotency-Key: 01J8ZK3QF7X2N5V9C4B1A6D8E0'
Response
{ "expires_at": "2026-09-11T09:30:00Z", "token": "string" }
GET/v1/orders/{id}/receipt

Get an order's receipt

No. getOrderReceiptAuth pos:orders:write ordering:write
The document printed from an order: whose name, address and tax registration head it, and the goods tax totalled per rate. The lines, payments and totals are the order's own.
Parameters

idpath · string · uuid
Required
UUIDv7 of the resource.
For resources a device can originate — orders, and their line items — this id is minted by the client before the record is ever synced, which is what makes an offline create idempotent.
Responses

200
The receipt.

OrderReceipt · application/json

addressAddress

RequiredNullable
The location's address, or null when it has none.

address_line_1string

Required
First line of the address — street number, street name, building name.
≤ 255 chars

address_line_2string
Second line of the address, if any.
≤ 255 chars

address_line_3string
Third line of the address, if any.
≤ 255 chars

administrative_district_level_1string
A civil entity within the country. The state in the US; the county in the UK.
≤ 128 chars

administrative_district_level_2string
A civil entity within administrative_district_level_1.
≤ 128 chars

countryCountry

Required
ISO 3166-1 alpha-2 country code.
ZZ is the unknown/unspecified placeholder.
One of 250 values; see the schema.

localitystring
The city or town.
≤ 128 chars

postal_codestring
The postal or ZIP code.
≤ 32 chars

sublocalitystring
A civil region within the locality, if any.
≤ 128 chars

business_namestring

Required
The name the business trades under, else its legal name.

location_namestring

Required

order_idstring · uuid

Required

tax_by_ratearray of ReceiptTaxRate

Required
The goods tax per rate, in the order the rates first appear on the lines. A line taxed over several rates counts each share at its own rate. Service-charge tax is the order's own line.

amountMoney

Required
A monetary amount in a specific currency: Square's Money, and Stripe's amount beside its currency.
The amount is always an integer count of the currency's minor unit — pence for GBP, cents for USD. Zero-decimal currencies such as JPY have a minor unit equal to their major unit, so {"amount": 500, "currency": "JPY"} is ¥500 while {"amount": 500, "currency": "GBP"} is £5.00.
Floating point is never used for money anywhere in this API. Binary floats cannot represent most decimal fractions exactly, so accumulating them across the line items of an order produces totals that disagree with the printed receipt by a penny. Integer minor units make every arithmetic operation exact.

amountinteger · int64

Required
The amount, as a whole number of the currency's minor unit. May be negative to express a refund, discount or credit.

currencyCurrency

Required
ISO 4217 currency code.
Determines the minor unit that Money.amount is expressed in. Zero-decimal currencies such as JPY have a minor unit equal to the major unit.
One of 182 values; see the schema.

percentagePercentage

Required
A share of a whole, from "0" to "100", as a percentage in a decimal string with at most four decimal places, as Square's percentage and Stripe Tax's percentage_decimal are: UK VAT at 20% is "20", and an 8.875% US sales tax is "8.875".
A string because a JSON number is a binary float to most parsers, and a float cannot hold most decimal fractions exactly (RFC 7493 §2.2). Tenvelo computes with a percentage as an integer in parts per million ("8.875" is 88750), which every four-place percentage is exactly. A client that computes with one should read the digits the same way, never through a float.
pattern ^(100(\.0{1,4})?|(0|[1-9][0-9]?)(\.[0-9]{1,4})?)$

tax_registration_numberstring

Required
The location's own tax registration, else the merchant's; empty when neither has one. A multi-country estate has one taxpayer per country, and the receipt prints this venue's address.

timezoneTimezone

Required
IANA time zone identifier.
Used to resolve a location's business day for reporting and settlement.
One of 348 values; see the schema.

400
The request could not be parsed. Malformed JSON, a bad query parameter, or a header that failed to decode, among them an API-Version later than the server speaks or not a date (api-version-unknown, with the server's own in api_version).
Distinct from 422: a 400 never reached validation, so invalid_params is absent. Retrying without changing the request will fail again, except that a request refused for its API-Version goes once the server is updated.

401
No credentials, or credentials that could not be verified — missing bearer token, malformed JWT, expired token, or a signature that failed against the issuer's JWKS.
Refresh the token and retry once. Repeated 401 after a refresh means the device needs to re-enrol.

403
Authenticated, but not permitted. The token is valid and its merchant was resolved, but the caller's role does not allow this operation, or the target belongs to a different merchant.
Cross-tenant access is reported as 403 on a resource the caller may not see, and as 404 where even confirming existence would leak information. Retrying will not help.

404
No such resource, or none visible to this caller.
Also returned instead of 403 where acknowledging existence would itself leak information — so a 404 does not prove the id is unused globally, only that it is not yours.

410
The request names an API-Version this server no longer serves (docs/decisions/0011). Nothing in it was read. api_version names the version the server speaks: the client is behind, and sends the request again once it is updated.

429
Rate limit exceeded. Honour Retry-After rather than applying your own backoff.
A fleet of tills coming back online together after an outage is the realistic cause, which is exactly when uncoordinated client-side retry turns a brief outage into a sustained one. The limit is per process, and per site for what records trade there — a request spends its site's budget, and a till's own smaller one inside it — and per (client, merchant) for everything else; no RateLimit field is sent, so this response and its Retry-After are the whole of the contract.

500
Something failed on our side. trace_id identifies the request in our tracing — quote it in a support ticket.
The body never carries internal detail: no SQL, no stack traces, no upstream error strings. Safe to retry with the same Idempotency-Key.

503
Temporarily unable to serve the request — a dependency is down or the service is shedding load.
Retry with the same Idempotency-Key after Retry-After. This is always safe: a request that did take effect before the failure will be recognised as a replay.
Request
curl -X GET 'https://api.tenvelo.com/v1/orders/0192f1e4-7c3a-7b2e-9f10-5d6c7e8f9a0b/receipt' \ -H "Authorization: Bearer $TOKEN"
Response
{ "address": { "address_line_1": "12 Bridge Street", "address_line_2": "string", "address_line_3": "string", "administrative_district_level_1": "Somerset", "administrative_district_level_2": "string", "country": "ZZ", "locality": "Bristol", "postal_code": "BS1 4ST", "sublocality": "string" }, "business_name": "string", "location_name": "string", "order_id": "0192f1e4-7c3a-7b2e-9f10-5d6c7e8f9a0b", "tax_by_rate": [ { "amount": { "amount": 1250, "currency": "GBP" }, "percentage": "20" } ], "tax_registration_number": "string", "timezone": "Europe/Andorra" }
POST/v1/orders/{id}/tip-amendments

Record a tip the venue took but the till did not

No. createTipAmendmentAuth pos:orders:write
A manager or owner records a tip on a completed sale — a signed slip at a restaurant. The amendment is a fact on the order stream (payment_tip_amended): the payment's amount and tip rise by the same amount, so the goods portion and the sale are untouched, and the change the rollups read carries the delta. The caller must hold changes-pay (the owner or a manager), or the amendment must carry an approved_by_member_id from one — the same ladder an approval uses, applied by the server whatever a device claims.
Parameters

idpath · string · uuid
Required
UUIDv7 of the resource.
For resources a device can originate — orders, and their line items — this id is minted by the client before the record is ever synced, which is what makes an offline create idempotent.
Request body application/json

idstring · uuid

Required
The amendment's own id, so a retry is the same fact.

amountMoney

Required
A monetary amount in a specific currency: Square's Money, and Stripe's amount beside its currency.
The amount is always an integer count of the currency's minor unit — pence for GBP, cents for USD. Zero-decimal currencies such as JPY have a minor unit equal to their major unit, so {"amount": 500, "currency": "JPY"} is ¥500 while {"amount": 500, "currency": "GBP"} is £5.00.
Floating point is never used for money anywhere in this API. Binary floats cannot represent most decimal fractions exactly, so accumulating them across the line items of an order produces totals that disagree with the printed receipt by a penny. Integer minor units make every arithmetic operation exact.

amountinteger · int64

Required
The amount, as a whole number of the currency's minor unit. May be negative to express a refund, discount or credit.

currencyCurrency

Required
ISO 4217 currency code.
Determines the minor unit that Money.amount is expressed in. Zero-decimal currencies such as JPY have a minor unit equal to the major unit.
One of 182 values; see the schema.

approved_by_member_idstring · uuid

Required
The manager or owner who vouched for the slip.

member_idstring · uuid
The server the slip names, when it names another; absent keeps the payment's.

payment_idstring · uuid

Required
The payment on the sale the tip belongs to.

reasonstring

Required
Why the tip was not recorded at the counter — the audit trail a slip tip needs.
≥ 1 chars
Responses

200
The amendment as recorded.

object · application/json

idstring · uuid

Required

400
The request could not be parsed. Malformed JSON, a bad query parameter, or a header that failed to decode, among them an API-Version later than the server speaks or not a date (api-version-unknown, with the server's own in api_version).
Distinct from 422: a 400 never reached validation, so invalid_params is absent. Retrying without changing the request will fail again, except that a request refused for its API-Version goes once the server is updated.

401
No credentials, or credentials that could not be verified — missing bearer token, malformed JWT, expired token, or a signature that failed against the issuer's JWKS.
Refresh the token and retry once. Repeated 401 after a refresh means the device needs to re-enrol.

403
Authenticated, but not permitted. The token is valid and its merchant was resolved, but the caller's role does not allow this operation, or the target belongs to a different merchant.
Cross-tenant access is reported as 403 on a resource the caller may not see, and as 404 where even confirming existence would leak information. Retrying will not help.

404
No such resource, or none visible to this caller.
Also returned instead of 403 where acknowledging existence would itself leak information — so a 404 does not prove the id is unused globally, only that it is not yours.

410
The request names an API-Version this server no longer serves (docs/decisions/0011). Nothing in it was read. api_version names the version the server speaks: the client is behind, and sends the request again once it is updated.

415
The request Content-Type is not supported. This API accepts application/json on all mutations.

422
The request parsed but failed validation.
invalid_params lists every failing field with a JSON Pointer, not just the first, so a client can mark up a whole form in one pass rather than making the user fix errors one round trip at a time.
Also returned when an Idempotency-Key is replayed with a different body, and when device-computed order totals disagree with the server's recomputation.

429
Rate limit exceeded. Honour Retry-After rather than applying your own backoff.
A fleet of tills coming back online together after an outage is the realistic cause, which is exactly when uncoordinated client-side retry turns a brief outage into a sustained one. The limit is per process, and per site for what records trade there — a request spends its site's budget, and a till's own smaller one inside it — and per (client, merchant) for everything else; no RateLimit field is sent, so this response and its Retry-After are the whole of the contract.

500
Something failed on our side. trace_id identifies the request in our tracing — quote it in a support ticket.
The body never carries internal detail: no SQL, no stack traces, no upstream error strings. Safe to retry with the same Idempotency-Key.

503
Temporarily unable to serve the request — a dependency is down or the service is shedding load.
Retry with the same Idempotency-Key after Retry-After. This is always safe: a request that did take effect before the failure will be recognised as a replay.
Request
curl -X POST 'https://api.tenvelo.com/v1/orders/0192f1e4-7c3a-7b2e-9f10-5d6c7e8f9a0b/tip-amendments' \ -H "Authorization: Bearer $TOKEN" \ -H 'Content-Type: application/json' \ -d '{ "id": "0192f1e4-7c3a-7b2e-9f10-5d6c7e8f9a0b", "amount": { "amount": 1250, "currency": "GBP" }, "approved_by_member_id": "0192f1e4-7c3a-7b2e-9f10-5d6c7e8f9a0b", "member_id": "0192f1e4-7c3a-7b2e-9f10-5d6c7e8f9a0b", "payment_id": "0192f1e4-7c3a-7b2e-9f10-5d6c7e8f9a0b", "reason": "string" }'
Response
{ "id": "0192f1e4-7c3a-7b2e-9f10-5d6c7e8f9a0b" }
POST/v1/receipt-mailings/batch-create

Email sales' receipts to their guests again

No. batchCreateReceiptMailingsAuth pos:orders:write
Asks for a completed sale's receipt to be emailed again to the guest on it, at the address their record holds when it is sent, never to an address the request carries. A sale that is not completed, names no guest, or whose guest has no address fails its item.
Each item carries its own idempotency_key, which names the request, so sending it again asks once. Anyone who may read the sale may send it; a guest at the table may not.
Request body application/json · ReceiptMailingBatchCreateRequest

itemsarray of ReceiptMailingBatchCreateItem

Required
≥ 1 items · ≤ 500 items

idempotency_keyItemIdempotencyKey

Required
A key for one item in a batch, minted by the client when it queues the item and reused on every attempt to send it. The item, not the request, is the unit of work: a retried batch returns the stored result for every item already applied under its key. A fresh key per attempt defeats the whole mechanism.
Scoped per merchant, so keys need only be unique within a merchant's own traffic.
16–255 chars

order_idstring · uuid

Required
Responses

200
The batch was processed. results says what happened to each item.

BatchResponse · application/json

resultsarray of BatchResult

Required

idstring · uuid
The resource the item created or changed. Absent when it failed.

idempotency_keystring

Required
The item's key, echoed so a result can be matched by key as well as position.

problemProblem

Nullable
Why the item failed, as an RFC 9457 problem. A 422 means the item is malformed and will never succeed — drop it and show it to staff rather than retrying for ever. A 409 or a 5xx means try again later.

typestring · uri

Required
A stable URI identifying the problem kind. This is the field to branch on.
default about:blank

api_versionstring
Present on an api-version-retired or api-version-unknown refusal: the API-Version this server speaks (docs/decisions/0011).

detailstring
A human-readable explanation specific to this occurrence. Safe to show to a developer; never contains internal state, SQL, or stack traces.

instancestring · uri-reference
A URI reference identifying the specific occurrence.

invalid_paramsarray of InvalidParam

Present on 422 responses. Lists every field that failed validation, rather than only the first, so a client can highlight an entire form in one pass.

codestring
Stable machine-readable code for this failure, for clients that localise their own messages rather than showing reason.

pointerstring

Required
RFC 6901 JSON Pointer to the offending value within the request body. A pointer rather than a field name so that failures nested inside arrays — the third line item of an order — are addressable at all.

reasonstring

Required
Why this value was rejected, in human-readable form.

refusalsarray of Location refusal

Present on 409 responses to a withdrawal refused by the state it depends on (deleting a location with tills still assigned, open orders, …). Lists every reason at once, each with how much stands in the way, so a client can say what to put right and link to it rather than walking a person through one refusal after another.

kindstring

Required
A stable refusal kind — devices, open_orders, drawer_sessions, bookings or stock — that a client links to the screen that puts it right. Branch on this field, never on the surrounding prose.

countinteger

Required
How many things stand in the way of the withdrawal, so a client can repeat the number rather than re-read prose.
≥ 1

statusinteger

Required
The HTTP status code, repeated here so the body is self-contained.
100–599

titlestring

Required
A short, human-readable summary of the problem kind.

trace_idstring
The OpenTelemetry trace id for this request. Quote it in a support ticket and the whole request can be pulled up.

statusstring · enum

Required
created — the item made a new resource. updated — it changed an existing one.
unchanged — this key was already applied and the original outcome stands. A success, not an error: it is what a client retrying a batch it was unsure landed should expect, and it clears the item from its queue exactly as created does.
failed — the item was refused, and nothing else in the batch was affected. See problem.
createdupdatedunchangedfailed

versioninteger · int64
The resource's version after the item. Absent when it failed.

400
The request could not be parsed. Malformed JSON, a bad query parameter, or a header that failed to decode, among them an API-Version later than the server speaks or not a date (api-version-unknown, with the server's own in api_version).
Distinct from 422: a 400 never reached validation, so invalid_params is absent. Retrying without changing the request will fail again, except that a request refused for its API-Version goes once the server is updated.

401
No credentials, or credentials that could not be verified — missing bearer token, malformed JWT, expired token, or a signature that failed against the issuer's JWKS.
Refresh the token and retry once. Repeated 401 after a refresh means the device needs to re-enrol.

403
Authenticated, but not permitted. The token is valid and its merchant was resolved, but the caller's role does not allow this operation, or the target belongs to a different merchant.
Cross-tenant access is reported as 403 on a resource the caller may not see, and as 404 where even confirming existence would leak information. Retrying will not help.

410
The request names an API-Version this server no longer serves (docs/decisions/0011). Nothing in it was read. api_version names the version the server speaks: the client is behind, and sends the request again once it is updated.

415
The request Content-Type is not supported. This API accepts application/json on all mutations.

422
The request parsed but failed validation.
invalid_params lists every failing field with a JSON Pointer, not just the first, so a client can mark up a whole form in one pass rather than making the user fix errors one round trip at a time.
Also returned when an Idempotency-Key is replayed with a different body, and when device-computed order totals disagree with the server's recomputation.

429
Rate limit exceeded. Honour Retry-After rather than applying your own backoff.
A fleet of tills coming back online together after an outage is the realistic cause, which is exactly when uncoordinated client-side retry turns a brief outage into a sustained one. The limit is per process, and per site for what records trade there — a request spends its site's budget, and a till's own smaller one inside it — and per (client, merchant) for everything else; no RateLimit field is sent, so this response and its Retry-After are the whole of the contract.

500
Something failed on our side. trace_id identifies the request in our tracing — quote it in a support ticket.
The body never carries internal detail: no SQL, no stack traces, no upstream error strings. Safe to retry with the same Idempotency-Key.
Request
curl -X POST 'https://api.tenvelo.com/v1/receipt-mailings/batch-create' \ -H "Authorization: Bearer $TOKEN" \ -H 'Content-Type: application/json' \ -d '{ "items": [ { "idempotency_key": "01J8ZK3QF7X2N5V9C4B1A6D8E0", "order_id": "0192f1e4-7c3a-7b2e-9f10-5d6c7e8f9a0b" } ] }'
Response
{ "results": [ { "id": "0192f1e4-7c3a-7b2e-9f10-5d6c7e8f9a0b", "idempotency_key": "string", "problem": { "type": "https://api.tenvelo.com/problems/version-conflict", "api_version": "2026-10-10", "detail": "The product has been modified since version 7 was read.", "instance": "/v1/products/0195f8c7-4a1e-7c3b-9f22-8d4e6a1b2c3d", "invalid_params": [ { "code": "minimum", "pointer": "/line_items/0/quantity", "reason": "must be greater than or equal to 1" } ], "refusals": [ { "kind": "devices", "count": 3 } ], "status": 412, "title": "Version conflict", "trace_id": "4bf92f3577b34da6a3ce929d0e0e4736" }, "status": "created", "version": 0 } ] }
GET/v1/refunds

List a sale's refunds

No. listRefundsAuth pos:orders:write
Returns the refunds of one sale, newest first, each with the tenders that carried the money back. A sale is refunded a few times at most, so this is always filtered by order_id; the estate's refunds are reported, not listed.
Parameters

cursorquery · string
Opaque cursor from a previous page's next_cursor. Omit to start from the beginning.
Pass it back exactly as received. It is base64 and its structure is not part of this contract — decoding it, or constructing one by hand, will break without notice.

limitquery · integer · int32
Maximum items to return. The server may return fewer, so always drive the loop from has_more rather than from the size of the page you got back.

order_idquery · string · uuid
Required
The sale whose refunds these are.
Responses

200
A page of the sale's refunds.

RefundPage · application/json

has_moreboolean

Required
Whether another page follows.

itemsarray of Refund

Required

idstring · uuid

Required

kindstring · enum
Whether this reverses a sale or is a blind return (retail item 8).
refundblind_return

approved_by_memberMemberSnapshot

Nullable
The manager or owner who approved a staff member's refund above the merchant's refund_approval_threshold_minor, as they were when they approved it; nil when no approval was needed.

idstring · uuid

Required
The roster's id, checked against the merchant's memberships.

namestring

Required
What the member was called.
≥ 1 chars

emailstring · email

Required
The member's address.

rolestring · enum

Required
The role the member held.
ownermanagerstaff

blind_priceMoney

A monetary amount in a specific currency: Square's Money, and Stripe's amount beside its currency.
The amount is always an integer count of the currency's minor unit — pence for GBP, cents for USD. Zero-decimal currencies such as JPY have a minor unit equal to their major unit, so {"amount": 500, "currency": "JPY"} is ¥500 while {"amount": 500, "currency": "GBP"} is £5.00.
Floating point is never used for money anywhere in this API. Binary floats cannot represent most decimal fractions exactly, so accumulating them across the line items of an order produces totals that disagree with the printed receipt by a penny. Integer minor units make every arithmetic operation exact.

amountinteger · int64

Required
The amount, as a whole number of the currency's minor unit. May be negative to express a refund, discount or credit.

currencyCurrency

Required
ISO 4217 currency code.
Determines the minor unit that Money.amount is expressed in. Zero-decimal currencies such as JPY have a minor unit equal to the major unit.
One of 182 values; see the schema.

blind_product_idstring · uuid
The product a blind return was priced from, when it was one.

blind_quantityQuantity
How much of something, as a decimal string in the unit_of_measure beside it (each where there is none), as Square's quantity is: three croissants are "3", 1.4 kg of beans is "1.4". A string because a JSON number is a binary float to most parsers.
It has at most as many decimal places as its unit's base unit holds — three in each, g and ml, six in kg and l — and a finer one is refused, never rounded. Tenvelo holds every quantity as an integer of that base unit (thousandths of an each, milligrams, microlitres; docs/decisions/0063); a client that computes with one should read the digits the same way, never through a float.
≤ 26 chars · pattern ^-?(0|[1-9][0-9]*)(\.[0-9]{1,6})?$

blind_unit_of_measurestring · enum
The unit blind_quantity is in. Absent means each.
eachkgglml

created_atstring · date-time

Required

destinationstring · enum
Where the refunded value went (retail item 9). store_credit issued a gift card for the amount.
moneystore_credit
default money

device_idstring · uuid
The till that performed the refund, if it came from one.

exchange_replacement_order_idstring · uuid

Nullable
The replacement sale this refund is paired with as an exchange (retail item 6), when the refund recorded one. Null for a plain refund.

line_itemsarray of RefundLineItem

The lines that were returned and how much of each, if this was a line-level refund. Absent for a whole-sale refund.

line_idstring · uuid

Required

quantityQuantity
How much of something, as a decimal string in the unit_of_measure beside it (each where there is none), as Square's quantity is: three croissants are "3", 1.4 kg of beans is "1.4". A string because a JSON number is a binary float to most parsers.
It has at most as many decimal places as its unit's base unit holds — three in each, g and ml, six in kg and l — and a finer one is refused, never rounded. Tenvelo holds every quantity as an integer of that base unit (thousandths of an each, milligrams, microlitres; docs/decisions/0063); a client that computes with one should read the digits the same way, never through a float.
≤ 26 chars · pattern ^-?(0|[1-9][0-9]*)(\.[0-9]{1,6})?$

unit_of_measurestring · enum
The unit quantity is in. It must measure what the line does, or the refund is refused. Absent means each.
eachkgglml

memberMemberSnapshot

Nullable
The staff member who performed the refund. Checked against the merchant's memberships; nil when the refund was made by something that is not a person.

idstring · uuid

Required
The roster's id, checked against the merchant's memberships.

namestring

Required
What the member was called.
≥ 1 chars

emailstring · email

Required
The member's address.

rolestring · enum

Required
The role the member held.
ownermanagerstaff

notestring
≤ 512 chars

order_idstring · uuid

Required

outside_return_windowboolean
True when the sale being refunded is older than the merchant's returns window (return_window_days) and the merchant has set one. The till warns rather than refuses (0002's rule: inform, never block).

paymentsarray of RefundPayment

Required
≥ 1 items

idstring · uuid

Required

amountMoney

Required
A monetary amount in a specific currency: Square's Money, and Stripe's amount beside its currency.
The amount is always an integer count of the currency's minor unit — pence for GBP, cents for USD. Zero-decimal currencies such as JPY have a minor unit equal to their major unit, so {"amount": 500, "currency": "JPY"} is ¥500 while {"amount": 500, "currency": "GBP"} is £5.00.
Floating point is never used for money anywhere in this API. Binary floats cannot represent most decimal fractions exactly, so accumulating them across the line items of an order produces totals that disagree with the printed receipt by a penny. Integer minor units make every arithmetic operation exact.

amountinteger · int64

Required
The amount, as a whole number of the currency's minor unit. May be negative to express a refund, discount or credit.

currencyCurrency

Required
ISO 4217 currency code.
Determines the minor unit that Money.amount is expressed in. Zero-decimal currencies such as JPY have a minor unit equal to the major unit.
One of 182 values; see the schema.

methodstring · enum

Required
cashcardvoucheraccountpoints

payment_idstring · uuid
The original payment this refund reverses. Null for a cash refund, which has no payment to point at.

referencestring
The card's code on a voucher refund, so the value returns to the card it came from. Omitted for cash and card refunds.

reasonstring

Required
Why the money went back. Free text, because a refund reason is something a manager writes in their own words, not a fixed list.
≤ 512 chars

restockboolean
Whether the returned items went back into sellable stock.

statutoryboolean
Whether this refund was the law's — faulty goods or goods not as described, where the money went back to the payer (retail item 9, decision 0073). Named by the merchant at the counter; false for a goodwill return and for a blind_return, which has no sale behind it.
default false

store_credit_codestring
The code of the gift card a store-credit refund issued.

totalMoney

A monetary amount in a specific currency: Square's Money, and Stripe's amount beside its currency.
The amount is always an integer count of the currency's minor unit — pence for GBP, cents for USD. Zero-decimal currencies such as JPY have a minor unit equal to their major unit, so {"amount": 500, "currency": "JPY"} is ¥500 while {"amount": 500, "currency": "GBP"} is £5.00.
Floating point is never used for money anywhere in this API. Binary floats cannot represent most decimal fractions exactly, so accumulating them across the line items of an order produces totals that disagree with the printed receipt by a penny. Integer minor units make every arithmetic operation exact.

amountinteger · int64

Required
The amount, as a whole number of the currency's minor unit. May be negative to express a refund, discount or credit.

currencyCurrency

Required
ISO 4217 currency code.
Determines the minor unit that Money.amount is expressed in. Zero-decimal currencies such as JPY have a minor unit equal to the major unit.
One of 182 values; see the schema.

versioninteger
The refund's version. Always 1 today; a refund is immutable, and the field is present so a client and the server can agree it never changed.

next_cursorstring

Nullable
Opaque cursor for the next page, or null on the last page. Pass it back verbatim as the cursor query parameter; its contents are not part of this contract.

400
The request could not be parsed. Malformed JSON, a bad query parameter, or a header that failed to decode, among them an API-Version later than the server speaks or not a date (api-version-unknown, with the server's own in api_version).
Distinct from 422: a 400 never reached validation, so invalid_params is absent. Retrying without changing the request will fail again, except that a request refused for its API-Version goes once the server is updated.

401
No credentials, or credentials that could not be verified — missing bearer token, malformed JWT, expired token, or a signature that failed against the issuer's JWKS.
Refresh the token and retry once. Repeated 401 after a refresh means the device needs to re-enrol.

403
Authenticated, but not permitted. The token is valid and its merchant was resolved, but the caller's role does not allow this operation, or the target belongs to a different merchant.
Cross-tenant access is reported as 403 on a resource the caller may not see, and as 404 where even confirming existence would leak information. Retrying will not help.

410
The request names an API-Version this server no longer serves (docs/decisions/0011). Nothing in it was read. api_version names the version the server speaks: the client is behind, and sends the request again once it is updated.

422
The request parsed but failed validation.
invalid_params lists every failing field with a JSON Pointer, not just the first, so a client can mark up a whole form in one pass rather than making the user fix errors one round trip at a time.
Also returned when an Idempotency-Key is replayed with a different body, and when device-computed order totals disagree with the server's recomputation.

429
Rate limit exceeded. Honour Retry-After rather than applying your own backoff.
A fleet of tills coming back online together after an outage is the realistic cause, which is exactly when uncoordinated client-side retry turns a brief outage into a sustained one. The limit is per process, and per site for what records trade there — a request spends its site's budget, and a till's own smaller one inside it — and per (client, merchant) for everything else; no RateLimit field is sent, so this response and its Retry-After are the whole of the contract.

500
Something failed on our side. trace_id identifies the request in our tracing — quote it in a support ticket.
The body never carries internal detail: no SQL, no stack traces, no upstream error strings. Safe to retry with the same Idempotency-Key.

503
Temporarily unable to serve the request — a dependency is down or the service is shedding load.
Retry with the same Idempotency-Key after Retry-After. This is always safe: a request that did take effect before the failure will be recognised as a replay.
Request
curl -X GET 'https://api.tenvelo.com/v1/refunds?order_id=…' \ -H "Authorization: Bearer $TOKEN"
Response
{ "has_more": false, "items": [ { "id": "0192f1e4-7c3a-7b2e-9f10-5d6c7e8f9a0b", "kind": "refund", "approved_by_member": { "id": "0192f1e4-7c3a-7b2e-9f10-5d6c7e8f9a0b", "name": "string", "email": "ada@example.com", "role": "owner" }, "blind_price": { "amount": 1250, "currency": "GBP" }, "blind_product_id": "0192f1e4-7c3a-7b2e-9f10-5d6c7e8f9a0b", "blind_quantity": "3", "blind_unit_of_measure": "each", "created_at": "2026-09-11T09:30:00Z", "destination": "money", "device_id": "0192f1e4-7c3a-7b2e-9f10-5d6c7e8f9a0b", "exchange_replacement_order_id": "0192f1e4-7c3a-7b2e-9f10-5d6c7e8f9a0b", "line_items": [ { "line_id": "0192f1e4-7c3a-7b2e-9f10-5d6c7e8f9a0b", "quantity": "3", "unit_of_measure": "each" } ], "member": { "id": "0192f1e4-7c3a-7b2e-9f10-5d6c7e8f9a0b", "name": "string", "email": "ada@example.com", "role": "owner" }, "note": "string", "order_id": "0192f1e4-7c3a-7b2e-9f10-5d6c7e8f9a0b", "outside_return_window": false, "payments": [ { "id": "0192f1e4-7c3a-7b2e-9f10-5d6c7e8f9a0b", "amount": { "amount": 1250, "currency": "GBP" }, "method": "cash", "payment_id": "0192f1e4-7c3a-7b2e-9f10-5d6c7e8f9a0b", "reference": "string" } ], "reason": "string", "restock": false, "statutory": false, "store_credit_code": "string", "total": { "amount": 1250, "currency": "GBP" }, "version": 0 } ], "next_cursor": "string" }
GET/v1/refunds/{refund_id}

Get a refund

No. getRefundAuth pos:orders:write
Returns a single refund with the tenders that carried the money back.
Parameters

refund_idpath · string · uuid
Required
Responses

200
The refund.

Refund · application/json

idstring · uuid

Required

kindstring · enum
Whether this reverses a sale or is a blind return (retail item 8).
refundblind_return

approved_by_memberMemberSnapshot

Nullable
The manager or owner who approved a staff member's refund above the merchant's refund_approval_threshold_minor, as they were when they approved it; nil when no approval was needed.

idstring · uuid

Required
The roster's id, checked against the merchant's memberships.

namestring

Required
What the member was called.
≥ 1 chars

emailstring · email

Required
The member's address.

rolestring · enum

Required
The role the member held.
ownermanagerstaff

blind_priceMoney

A monetary amount in a specific currency: Square's Money, and Stripe's amount beside its currency.
The amount is always an integer count of the currency's minor unit — pence for GBP, cents for USD. Zero-decimal currencies such as JPY have a minor unit equal to their major unit, so {"amount": 500, "currency": "JPY"} is ¥500 while {"amount": 500, "currency": "GBP"} is £5.00.
Floating point is never used for money anywhere in this API. Binary floats cannot represent most decimal fractions exactly, so accumulating them across the line items of an order produces totals that disagree with the printed receipt by a penny. Integer minor units make every arithmetic operation exact.

amountinteger · int64

Required
The amount, as a whole number of the currency's minor unit. May be negative to express a refund, discount or credit.

currencyCurrency

Required
ISO 4217 currency code.
Determines the minor unit that Money.amount is expressed in. Zero-decimal currencies such as JPY have a minor unit equal to the major unit.
One of 182 values; see the schema.

blind_product_idstring · uuid
The product a blind return was priced from, when it was one.

blind_quantityQuantity
How much of something, as a decimal string in the unit_of_measure beside it (each where there is none), as Square's quantity is: three croissants are "3", 1.4 kg of beans is "1.4". A string because a JSON number is a binary float to most parsers.
It has at most as many decimal places as its unit's base unit holds — three in each, g and ml, six in kg and l — and a finer one is refused, never rounded. Tenvelo holds every quantity as an integer of that base unit (thousandths of an each, milligrams, microlitres; docs/decisions/0063); a client that computes with one should read the digits the same way, never through a float.
≤ 26 chars · pattern ^-?(0|[1-9][0-9]*)(\.[0-9]{1,6})?$

blind_unit_of_measurestring · enum
The unit blind_quantity is in. Absent means each.
eachkgglml

created_atstring · date-time

Required

destinationstring · enum
Where the refunded value went (retail item 9). store_credit issued a gift card for the amount.
moneystore_credit
default money

device_idstring · uuid
The till that performed the refund, if it came from one.

exchange_replacement_order_idstring · uuid

Nullable
The replacement sale this refund is paired with as an exchange (retail item 6), when the refund recorded one. Null for a plain refund.

line_itemsarray of RefundLineItem

The lines that were returned and how much of each, if this was a line-level refund. Absent for a whole-sale refund.

line_idstring · uuid

Required

quantityQuantity
How much of something, as a decimal string in the unit_of_measure beside it (each where there is none), as Square's quantity is: three croissants are "3", 1.4 kg of beans is "1.4". A string because a JSON number is a binary float to most parsers.
It has at most as many decimal places as its unit's base unit holds — three in each, g and ml, six in kg and l — and a finer one is refused, never rounded. Tenvelo holds every quantity as an integer of that base unit (thousandths of an each, milligrams, microlitres; docs/decisions/0063); a client that computes with one should read the digits the same way, never through a float.
≤ 26 chars · pattern ^-?(0|[1-9][0-9]*)(\.[0-9]{1,6})?$

unit_of_measurestring · enum
The unit quantity is in. It must measure what the line does, or the refund is refused. Absent means each.
eachkgglml

memberMemberSnapshot

Nullable
The staff member who performed the refund. Checked against the merchant's memberships; nil when the refund was made by something that is not a person.

idstring · uuid

Required
The roster's id, checked against the merchant's memberships.

namestring

Required
What the member was called.
≥ 1 chars

emailstring · email

Required
The member's address.

rolestring · enum

Required
The role the member held.
ownermanagerstaff

notestring
≤ 512 chars

order_idstring · uuid

Required

outside_return_windowboolean
True when the sale being refunded is older than the merchant's returns window (return_window_days) and the merchant has set one. The till warns rather than refuses (0002's rule: inform, never block).

paymentsarray of RefundPayment

Required
≥ 1 items

idstring · uuid

Required

amountMoney

Required
A monetary amount in a specific currency: Square's Money, and Stripe's amount beside its currency.
The amount is always an integer count of the currency's minor unit — pence for GBP, cents for USD. Zero-decimal currencies such as JPY have a minor unit equal to their major unit, so {"amount": 500, "currency": "JPY"} is ¥500 while {"amount": 500, "currency": "GBP"} is £5.00.
Floating point is never used for money anywhere in this API. Binary floats cannot represent most decimal fractions exactly, so accumulating them across the line items of an order produces totals that disagree with the printed receipt by a penny. Integer minor units make every arithmetic operation exact.

amountinteger · int64

Required
The amount, as a whole number of the currency's minor unit. May be negative to express a refund, discount or credit.

currencyCurrency

Required
ISO 4217 currency code.
Determines the minor unit that Money.amount is expressed in. Zero-decimal currencies such as JPY have a minor unit equal to the major unit.
One of 182 values; see the schema.

methodstring · enum

Required
cashcardvoucheraccountpoints

payment_idstring · uuid
The original payment this refund reverses. Null for a cash refund, which has no payment to point at.

referencestring
The card's code on a voucher refund, so the value returns to the card it came from. Omitted for cash and card refunds.

reasonstring

Required
Why the money went back. Free text, because a refund reason is something a manager writes in their own words, not a fixed list.
≤ 512 chars

restockboolean
Whether the returned items went back into sellable stock.

statutoryboolean
Whether this refund was the law's — faulty goods or goods not as described, where the money went back to the payer (retail item 9, decision 0073). Named by the merchant at the counter; false for a goodwill return and for a blind_return, which has no sale behind it.
default false

store_credit_codestring
The code of the gift card a store-credit refund issued.

totalMoney

A monetary amount in a specific currency: Square's Money, and Stripe's amount beside its currency.
The amount is always an integer count of the currency's minor unit — pence for GBP, cents for USD. Zero-decimal currencies such as JPY have a minor unit equal to their major unit, so {"amount": 500, "currency": "JPY"} is ¥500 while {"amount": 500, "currency": "GBP"} is £5.00.
Floating point is never used for money anywhere in this API. Binary floats cannot represent most decimal fractions exactly, so accumulating them across the line items of an order produces totals that disagree with the printed receipt by a penny. Integer minor units make every arithmetic operation exact.

amountinteger · int64

Required
The amount, as a whole number of the currency's minor unit. May be negative to express a refund, discount or credit.

currencyCurrency

Required
ISO 4217 currency code.
Determines the minor unit that Money.amount is expressed in. Zero-decimal currencies such as JPY have a minor unit equal to the major unit.
One of 182 values; see the schema.

versioninteger
The refund's version. Always 1 today; a refund is immutable, and the field is present so a client and the server can agree it never changed.

400
The request could not be parsed. Malformed JSON, a bad query parameter, or a header that failed to decode, among them an API-Version later than the server speaks or not a date (api-version-unknown, with the server's own in api_version).
Distinct from 422: a 400 never reached validation, so invalid_params is absent. Retrying without changing the request will fail again, except that a request refused for its API-Version goes once the server is updated.

401
No credentials, or credentials that could not be verified — missing bearer token, malformed JWT, expired token, or a signature that failed against the issuer's JWKS.
Refresh the token and retry once. Repeated 401 after a refresh means the device needs to re-enrol.

403
Authenticated, but not permitted. The token is valid and its merchant was resolved, but the caller's role does not allow this operation, or the target belongs to a different merchant.
Cross-tenant access is reported as 403 on a resource the caller may not see, and as 404 where even confirming existence would leak information. Retrying will not help.

404
No such resource, or none visible to this caller.
Also returned instead of 403 where acknowledging existence would itself leak information — so a 404 does not prove the id is unused globally, only that it is not yours.

410
The request names an API-Version this server no longer serves (docs/decisions/0011). Nothing in it was read. api_version names the version the server speaks: the client is behind, and sends the request again once it is updated.

429
Rate limit exceeded. Honour Retry-After rather than applying your own backoff.
A fleet of tills coming back online together after an outage is the realistic cause, which is exactly when uncoordinated client-side retry turns a brief outage into a sustained one. The limit is per process, and per site for what records trade there — a request spends its site's budget, and a till's own smaller one inside it — and per (client, merchant) for everything else; no RateLimit field is sent, so this response and its Retry-After are the whole of the contract.

500
Something failed on our side. trace_id identifies the request in our tracing — quote it in a support ticket.
The body never carries internal detail: no SQL, no stack traces, no upstream error strings. Safe to retry with the same Idempotency-Key.

503
Temporarily unable to serve the request — a dependency is down or the service is shedding load.
Retry with the same Idempotency-Key after Retry-After. This is always safe: a request that did take effect before the failure will be recognised as a replay.
Request
curl -X GET 'https://api.tenvelo.com/v1/refunds/0192f1e4-7c3a-7b2e-9f10-5d6c7e8f9a0b' \ -H "Authorization: Bearer $TOKEN"
Response
{ "id": "0192f1e4-7c3a-7b2e-9f10-5d6c7e8f9a0b", "kind": "refund", "approved_by_member": { "id": "0192f1e4-7c3a-7b2e-9f10-5d6c7e8f9a0b", "name": "string", "email": "ada@example.com", "role": "owner" }, "blind_price": { "amount": 1250, "currency": "GBP" }, "blind_product_id": "0192f1e4-7c3a-7b2e-9f10-5d6c7e8f9a0b", "blind_quantity": "3", "blind_unit_of_measure": "each", "created_at": "2026-09-11T09:30:00Z", "destination": "money", "device_id": "0192f1e4-7c3a-7b2e-9f10-5d6c7e8f9a0b", "exchange_replacement_order_id": "0192f1e4-7c3a-7b2e-9f10-5d6c7e8f9a0b", "line_items": [ { "line_id": "0192f1e4-7c3a-7b2e-9f10-5d6c7e8f9a0b", "quantity": "3", "unit_of_measure": "each" } ], "member": { "id": "0192f1e4-7c3a-7b2e-9f10-5d6c7e8f9a0b", "name": "string", "email": "ada@example.com", "role": "owner" }, "note": "string", "order_id": "0192f1e4-7c3a-7b2e-9f10-5d6c7e8f9a0b", "outside_return_window": false, "payments": [ { "id": "0192f1e4-7c3a-7b2e-9f10-5d6c7e8f9a0b", "amount": { "amount": 1250, "currency": "GBP" }, "method": "cash", "payment_id": "0192f1e4-7c3a-7b2e-9f10-5d6c7e8f9a0b", "reference": "string" } ], "reason": "string", "restock": false, "statutory": false, "store_credit_code": "string", "total": { "amount": 1250, "currency": "GBP" }, "version": 0 }
GET/v1/reports/order-states

Count orders by state

No. getOrderStateCountsAuth pos:orders:write
How many orders each of the order list's tabs holds: every order, each state, and those a refund has given back against or with a flag still open, under the same filters GET /v1/orders takes. A tab's count is the length of the list it opens, kept to the locations the caller holds as the list is. A device token is refused with 403.
Parameters

location_idquery · string · uuid

device_idquery · string · uuid

channelquery · string · enum
Only orders from this channel: online is a location's own ordering page, which is how the venue's online orders screen reads what has been asked of it.

referencequery · string
The human-facing receipt number, which is how staff find a sale by.

qquery · string
The start of a receipt number, or any part of the name an order goes by.

member_idquery · string · uuid
Only the orders this member rang.

payment_methodquery · string · enum
Only the orders this method paid towards.

total_fromquery · integer · int64
Only orders whose total is at least this, in the order's own minor units. Absent sets no floor.

total_toquery · integer · int64
Only orders whose total is at most this, in the order's own minor units. Absent sets no ceiling.

business_datequery · string · date
Only sales booked to this trading day, in each location's own reckoning.

business_date_fromquery · string · date
Only sales booked to this trading day or later.

business_date_toquery · string · date
Only sales booked to this trading day or earlier.

received_fromquery · string · date-time
Inclusive lower bound on received_at, RFC 3339.

received_toquery · string · date-time
Exclusive upper bound on received_at, RFC 3339.
Responses

200
The counts.

OrderStateCounts · application/json

allinteger · int64

Required
≥ 0

canceledinteger · int64

Required
≥ 0

completedinteger · int64

Required
≥ 0

completed_totalarray of Money

Required
What the completed orders came to, one sum per currency, by currency code.

amountinteger · int64

Required
The amount, as a whole number of the currency's minor unit. May be negative to express a refund, discount or credit.

currencyCurrency

Required
ISO 4217 currency code.
Determines the minor unit that Money.amount is expressed in. Zero-decimal currencies such as JPY have a minor unit equal to the major unit.
One of 182 values; see the schema.

flaggedinteger · int64

Required
≥ 0

openinteger · int64

Required
≥ 0

refundedinteger · int64

Required
≥ 0

rejectedinteger · int64

Required
The asked-for orders the venue turned down, which are among the cancelled.
≥ 0

voidedinteger · int64

Required
≥ 0

400
The request could not be parsed. Malformed JSON, a bad query parameter, or a header that failed to decode, among them an API-Version later than the server speaks or not a date (api-version-unknown, with the server's own in api_version).
Distinct from 422: a 400 never reached validation, so invalid_params is absent. Retrying without changing the request will fail again, except that a request refused for its API-Version goes once the server is updated.

401
No credentials, or credentials that could not be verified — missing bearer token, malformed JWT, expired token, or a signature that failed against the issuer's JWKS.
Refresh the token and retry once. Repeated 401 after a refresh means the device needs to re-enrol.

403
Authenticated, but not permitted. The token is valid and its merchant was resolved, but the caller's role does not allow this operation, or the target belongs to a different merchant.
Cross-tenant access is reported as 403 on a resource the caller may not see, and as 404 where even confirming existence would leak information. Retrying will not help.

410
The request names an API-Version this server no longer serves (docs/decisions/0011). Nothing in it was read. api_version names the version the server speaks: the client is behind, and sends the request again once it is updated.

422
The request parsed but failed validation.
invalid_params lists every failing field with a JSON Pointer, not just the first, so a client can mark up a whole form in one pass rather than making the user fix errors one round trip at a time.
Also returned when an Idempotency-Key is replayed with a different body, and when device-computed order totals disagree with the server's recomputation.

429
Rate limit exceeded. Honour Retry-After rather than applying your own backoff.
A fleet of tills coming back online together after an outage is the realistic cause, which is exactly when uncoordinated client-side retry turns a brief outage into a sustained one. The limit is per process, and per site for what records trade there — a request spends its site's budget, and a till's own smaller one inside it — and per (client, merchant) for everything else; no RateLimit field is sent, so this response and its Retry-After are the whole of the contract.

500
Something failed on our side. trace_id identifies the request in our tracing — quote it in a support ticket.
The body never carries internal detail: no SQL, no stack traces, no upstream error strings. Safe to retry with the same Idempotency-Key.
Request
curl -X GET 'https://api.tenvelo.com/v1/reports/order-states' \ -H "Authorization: Bearer $TOKEN"
Response
{ "all": 0, "canceled": 0, "completed": 0, "completed_total": [ { "amount": 1250, "currency": "GBP" } ], "flagged": 0, "open": 0, "refunded": 0, "rejected": 0, "voided": 0 }
GET/v1/reports/orders-open

What the orders still open come to

No. getOrdersOpenReportAuth pos:orders:write
The board of the orders still open at the caller's locations, or at one: how many, what is on them, the longest any has gone quiet, which hold a card, and when each counts as a possible walk-out. A guest at a table is refused with 403.
Parameters

location_idquery · string · uuid
Only this location's orders. Absent reads every location the caller holds.
Responses

200
The board.

OrdersOpenReport · application/json

cards_heldinteger · int64

Required
How many of the orders a card is held on now.
≥ 0

countinteger · int64

Required
≥ 0

ordersarray of OrderStillOpen

Required

card_heldboolean

Required
Whether a card is held on the order now.

last_activity_atstring · date-time

Required
When the order was last written to.

left_overnightboolean
The tab was opened on a business day before this one and is still open — where a day's close would have auto-closed it if it held a card (tabs item 9). The manager settles it.

order_idstring · uuid

Required

walk_out_atstring · date-time

Required
When the order counts as a possible walk-out: an hour without a write, the same moment the till reports (testdata/tabs/walk-out.json).

quiet_sincestring · date-time

RequiredNullable
The last activity of the order quiet longest; null when none is open.

totalsarray of Money

Required
What is on the orders, one sum per currency, by currency code.

amountinteger · int64

Required
The amount, as a whole number of the currency's minor unit. May be negative to express a refund, discount or credit.

currencyCurrency

Required
ISO 4217 currency code.
Determines the minor unit that Money.amount is expressed in. Zero-decimal currencies such as JPY have a minor unit equal to the major unit.
One of 182 values; see the schema.

400
The request could not be parsed. Malformed JSON, a bad query parameter, or a header that failed to decode, among them an API-Version later than the server speaks or not a date (api-version-unknown, with the server's own in api_version).
Distinct from 422: a 400 never reached validation, so invalid_params is absent. Retrying without changing the request will fail again, except that a request refused for its API-Version goes once the server is updated.

401
No credentials, or credentials that could not be verified — missing bearer token, malformed JWT, expired token, or a signature that failed against the issuer's JWKS.
Refresh the token and retry once. Repeated 401 after a refresh means the device needs to re-enrol.

403
Authenticated, but not permitted. The token is valid and its merchant was resolved, but the caller's role does not allow this operation, or the target belongs to a different merchant.
Cross-tenant access is reported as 403 on a resource the caller may not see, and as 404 where even confirming existence would leak information. Retrying will not help.

410
The request names an API-Version this server no longer serves (docs/decisions/0011). Nothing in it was read. api_version names the version the server speaks: the client is behind, and sends the request again once it is updated.

429
Rate limit exceeded. Honour Retry-After rather than applying your own backoff.
A fleet of tills coming back online together after an outage is the realistic cause, which is exactly when uncoordinated client-side retry turns a brief outage into a sustained one. The limit is per process, and per site for what records trade there — a request spends its site's budget, and a till's own smaller one inside it — and per (client, merchant) for everything else; no RateLimit field is sent, so this response and its Retry-After are the whole of the contract.

500
Something failed on our side. trace_id identifies the request in our tracing — quote it in a support ticket.
The body never carries internal detail: no SQL, no stack traces, no upstream error strings. Safe to retry with the same Idempotency-Key.
Request
curl -X GET 'https://api.tenvelo.com/v1/reports/orders-open' \ -H "Authorization: Bearer $TOKEN"
Response
{ "cards_held": 0, "count": 0, "orders": [ { "card_held": false, "last_activity_at": "2026-09-11T09:30:00Z", "left_overnight": false, "order_id": "0192f1e4-7c3a-7b2e-9f10-5d6c7e8f9a0b", "walk_out_at": "2026-09-11T09:30:00Z" } ], "quiet_since": "2026-09-11T09:30:00Z", "totals": [ { "amount": 1250, "currency": "GBP" } ] }

Parameters

Responses

Request body application/json · ExchangeBatchCreateRequest

Responses

Parameters

Responses

Parameters

Request body application/json

Responses

Parameters

Responses

Parameters

Responses

Parameters

Responses

Request body application/json · OrderFactBatchCreateRequest

Responses

Request body application/json · OrderBatchRefundRequest

Responses

Parameters

Responses

Parameters

Responses

Parameters

Request body application/json · OrderDeclineWrite

Responses

Parameters

Responses

Parameters

Responses

Parameters

Responses

Parameters

Request body application/json

Responses

Request body application/json · ReceiptMailingBatchCreateRequest

Responses

Parameters

Responses

Parameters

Responses

Parameters

Responses

Parameters

Responses