Webhooks · Tenvelo API

GET/v1/webhook-endpoints

List webhook endpoints

No. listWebhookEndpointsAuth webhooks:read
Returns the merchant's webhook endpoints, oldest first. A merchant registers where its events are delivered, and a third party that needs to know reads this.
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.
Responses

200
A page of webhook endpoints.

WebhookEndpointPage · application/json

has_moreboolean

Required

itemsarray of WebhookEndpoint

Required

idstring · uuid

RequiredRead only

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.

eventsarray of string
The event types this endpoint wants. Empty means all of them.

secretstring

Read only
The key the receiver verifies signatures with (RFC 9421, hmac-sha256), used as these characters. Sent only in the answer that creates the endpoint or rotates its secret, and never again: only the sealed copy is kept.

statusstring · enum

RequiredRead only
active is receiving deliveries. disabled is one we stopped retrying after it kept failing; inactive is set by a merchant. An endpoint the merchant deletes is absent rather than shown as inactive.
activeinactivedisabled

urlstring · uri

Required
The callback URL. Must be https.
≤ 2048 chars

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

next_cursorstring

Required
Opaque cursor to pass to the next request.

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.

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/webhook-endpoints' \ -H "Authorization: Bearer $TOKEN"
Response
{ "has_more": false, "items": [ { "id": "0192f1e4-7c3a-7b2e-9f10-5d6c7e8f9a0b", "created_at": "2026-09-08T09:41:12Z", "events": [ "order.completed", "order.voided" ], "secret": "string", "status": "active", "url": "https://example.com", "version": 7 } ], "next_cursor": "string" }
POST/v1/webhook-endpoints

Register a webhook endpoint

No. createWebhookEndpointAuth webhooks:write
Tells the API where to deliver a merchant's events and which of them. The server mints the id and a signing secret, returned once at creation so the merchant can verify RFC 9421 signatures. The URL must be https; events empty means all event types.
This is how an aggregator or an integration subscribes to the menu and 86 push, and how a merchant points our events at their own system. An endpoint is a single, server-minted record rather than a till-queue record, so it is created here and not through a batch.
Parameters

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 · WebhookEndpointCreate

eventsarray of string
The event types this endpoint wants. Empty means all of them.

urlstring · uri

Required
The callback URL. Must be https.
≤ 2048 chars
Responses

201
The registered endpoint.

WebhookEndpoint · application/json

idstring · uuid

RequiredRead only

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.

eventsarray of string
The event types this endpoint wants. Empty means all of them.

secretstring

Read only
The key the receiver verifies signatures with (RFC 9421, hmac-sha256), used as these characters. Sent only in the answer that creates the endpoint or rotates its secret, and never again: only the sealed copy is kept.

statusstring · enum

RequiredRead only
active is receiving deliveries. disabled is one we stopped retrying after it kept failing; inactive is set by a merchant. An endpoint the merchant deletes is absent rather than shown as inactive.
activeinactivedisabled

urlstring · uri

Required
The callback URL. Must be https.
≤ 2048 chars

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

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.

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.

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/webhook-endpoints' \ -H "Authorization: Bearer $TOKEN" \ -H 'Idempotency-Key: 01J8ZK3QF7X2N5V9C4B1A6D8E0' \ -H 'Content-Type: application/json' \ -d '{ "events": [ "order.completed", "order.voided" ], "url": "https://example.com" }'
Response
{ "id": "0192f1e4-7c3a-7b2e-9f10-5d6c7e8f9a0b", "created_at": "2026-09-08T09:41:12Z", "events": [ "order.completed", "order.voided" ], "secret": "string", "status": "active", "url": "https://example.com", "version": 7 }
PATCH/v1/webhook-endpoints/{id}

Update a webhook endpoint

No. updateWebhookEndpointAuth webhooks:write
Merge-patches an endpoint, guarded by If-Match: only the fields present change. status pauses or resumes delivery without deleting the endpoint, so a merchant can stop and restart a subscription with one request and keep its history.
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.

If-Matchheader · string
Required
The ETag from the read that produced the value you are updating.
Required on updates, not optional, because "last write wins" is the wrong default for a catalogue two managers might edit at once. If anything has been written since your read, the request is rejected with 412 and you re-read and re-apply.
Use * to mean "write regardless of current version" — an explicit, greppable override rather than the silent default.
Request body application/merge-patch+json · WebhookEndpointPatch

eventsarray of string
The event types this endpoint wants. Empty means all of them.

statusstring · enum
inactive pauses delivery; active resumes it. disabled is never set by a merchant — it is what we set when an endpoint kept failing and we gave up on it.
activeinactive

urlstring · uri
The callback URL. Must be https.
≤ 2048 chars
Responses

200
The changed endpoint.

WebhookEndpoint · application/json

idstring · uuid

RequiredRead only

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.

eventsarray of string
The event types this endpoint wants. Empty means all of them.

secretstring

Read only
The key the receiver verifies signatures with (RFC 9421, hmac-sha256), used as these characters. Sent only in the answer that creates the endpoint or rotates its secret, and never again: only the sealed copy is kept.

statusstring · enum

RequiredRead only
active is receiving deliveries. disabled is one we stopped retrying after it kept failing; inactive is set by a merchant. An endpoint the merchant deletes is absent rather than shown as inactive.
activeinactivedisabled

urlstring · uri

Required
The callback URL. Must be https.
≤ 2048 chars

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

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.

412
The If-Match version did not match the resource's current version: someone else wrote since you read.
This is the expected, healthy outcome of two clients editing the same record — not an error condition to suppress. Re-read the resource, re-apply your change on top of the new state, and retry with the fresh ETag.

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 PATCH 'https://api.tenvelo.com/v1/webhook-endpoints/0192f1e4-7c3a-7b2e-9f10-5d6c7e8f9a0b' \ -H "Authorization: Bearer $TOKEN" \ -H 'If-Match: "3"' \ -H 'Content-Type: application/merge-patch+json' \ -d '{ "events": [ "order.completed", "order.voided" ], "status": "active", "url": "https://example.com" }'
Response
{ "id": "0192f1e4-7c3a-7b2e-9f10-5d6c7e8f9a0b", "created_at": "2026-09-08T09:41:12Z", "events": [ "order.completed", "order.voided" ], "secret": "string", "status": "active", "url": "https://example.com", "version": 7 }
DELETE/v1/webhook-endpoints/{id}

Delete a webhook endpoint

No. deleteWebhookEndpointAuth webhooks:write
Stops delivering events to this endpoint. The row is retained so the audit trail survives; a deleted endpoint no longer appears in the list.
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.

If-Matchheader · string
Required
The ETag from the read that produced the value you are updating.
Required on updates, not optional, because "last write wins" is the wrong default for a catalogue two managers might edit at once. If anything has been written since your read, the request is rejected with 412 and you re-read and re-apply.
Use * to mean "write regardless of current version" — an explicit, greppable override rather than the silent default.
Responses

204
The endpoint was deleted.

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.

412
The If-Match version did not match the resource's current version: someone else wrote since you read.
This is the expected, healthy outcome of two clients editing the same record — not an error condition to suppress. Re-read the resource, re-apply your change on top of the new state, and retry with the fresh ETag.

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 DELETE 'https://api.tenvelo.com/v1/webhook-endpoints/0192f1e4-7c3a-7b2e-9f10-5d6c7e8f9a0b' \ -H "Authorization: Bearer $TOKEN" \ -H 'If-Match: "3"'
GET/v1/webhook-endpoints/{id}/deliveries

List an endpoint's deliveries

No. listWebhookDeliveriesAuth webhooks:read
Returns each attempt to deliver an event to the endpoint, newest first, with how it landed, so an endpoint's health is read from a record rather than guessed.
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.

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.
Responses

200
A page of delivery attempts.

WebhookDeliveryPage · application/json

has_moreboolean

Required

itemsarray of WebhookDelivery

Required

idstring · uuid

Required

attempted_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.

eventstring

Required
The event type delivered.

event_idstring

Required
The event's id, the same on every attempt to deliver it.

latency_msinteger · int64

Required
≥ 0

okboolean

Required
Whether the receiver took it.

resource_idstring

Required
The resource the event is about. Empty for one that carries none, which cannot be sent again.

status_codeinteger · int32

Required
The HTTP status the receiver answered with; 0 when it did not answer.

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.

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.

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/webhook-endpoints/0192f1e4-7c3a-7b2e-9f10-5d6c7e8f9a0b/deliveries' \ -H "Authorization: Bearer $TOKEN"
Response
{ "has_more": false, "items": [ { "id": "0192f1e4-7c3a-7b2e-9f10-5d6c7e8f9a0b", "attempted_at": "2026-09-08T09:41:12Z", "event": "order.completed", "event_id": "string", "latency_ms": 0, "ok": false, "resource_id": "string", "status_code": 0 } ], "next_cursor": "string" }
POST/v1/webhook-endpoints/{id}/deliveries/{delivery_id}/redeliver

Send a delivery again

No. redeliverWebhookDeliveryAuth webhooks:write
Queues the event an attempt was for to be delivered to the endpoint again. It carries the same event id, so a receiver that already handled it can tell, and the resource as it is now rather than as it was.
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.

delivery_idpath · string · uuid
Required
The delivery attempt whose event is sent again.

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

204
The event is queued to be delivered again.

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 POST 'https://api.tenvelo.com/v1/webhook-endpoints/0192f1e4-7c3a-7b2e-9f10-5d6c7e8f9a0b/deliveries/0192f1e4-7c3a-7b2e-9f10-5d6c7e8f9a0b/redeliver' \ -H "Authorization: Bearer $TOKEN" \ -H 'Idempotency-Key: 01J8ZK3QF7X2N5V9C4B1A6D8E0'
POST/v1/webhook-endpoints/{id}/rotate

Rotate an endpoint's signing secret

No. rotateWebhookEndpointAuth webhooks:write
Publishes a new signing secret beside the one in use and returns it, once. The secret in use keeps signing until the new one has been published for a day, and then keeps verifying for a week after that, so a receiver can take the new one without missing a delivery.
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.

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 endpoint, carrying its new secret this once.

WebhookEndpoint · application/json

idstring · uuid

RequiredRead only

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.

eventsarray of string
The event types this endpoint wants. Empty means all of them.

secretstring

Read only
The key the receiver verifies signatures with (RFC 9421, hmac-sha256), used as these characters. Sent only in the answer that creates the endpoint or rotates its secret, and never again: only the sealed copy is kept.

statusstring · enum

RequiredRead only
active is receiving deliveries. disabled is one we stopped retrying after it kept failing; inactive is set by a merchant. An endpoint the merchant deletes is absent rather than shown as inactive.
activeinactivedisabled

urlstring · uri

Required
The callback URL. Must be https.
≤ 2048 chars

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

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 POST 'https://api.tenvelo.com/v1/webhook-endpoints/0192f1e4-7c3a-7b2e-9f10-5d6c7e8f9a0b/rotate' \ -H "Authorization: Bearer $TOKEN" \ -H 'Idempotency-Key: 01J8ZK3QF7X2N5V9C4B1A6D8E0'
Response
{ "id": "0192f1e4-7c3a-7b2e-9f10-5d6c7e8f9a0b", "created_at": "2026-09-08T09:41:12Z", "events": [ "order.completed", "order.voided" ], "secret": "string", "status": "active", "url": "https://example.com", "version": 7 }
EVENTcustomer.created

Guest recorded

No. customerCreatedSent by us, to your endpoint
Sent when a guest is added to the directory — at the counter, in the back office, or by an integration with the customers:write scope.
A merchant running somebody else's CRM is told about a guest the same way it is told about an order; an integration that keeps a copy of the guest book here is the point of the event (guest-record item 19).
See WebhookEnvelope for signature verification, replay protection and the at-least-once delivery contract that applies to every webhook.
Payload application/json

type"customer.created"

dataCustomer

A guest of the merchant, as the back office and a CRM see them. This is the full record — identity, contact and the staff note — and it is only returned to a signed-in person, never to a device. See CustomerLoyalty for the limited projection a till gets when it looks a guest up to redeem points.

namestring

Required
≤ 200 chars

emailstring · email

Nullable

notestring
A staff-only note about the guest, e.g. preferences or allergies.

phonestring

Nullable
≤ 64 chars
Your reply

200
Acknowledged. Return this as soon as the delivery is durably recorded; do the actual work afterwards, asynchronously.

400
The payload was rejected. Treated as a failure and retried with backoff, so only return this for a delivery you genuinely could not accept.

500
Handler failed. Retried with exponential backoff for 24 hours, then dead-lettered.
Payload
{ "type": "customer.created", "data": { "name": "string", "email": "ada@example.com", "note": "string", "phone": "string" } }
EVENTcustomer.erased

Guest erased

No. customerErasedSent by us, to your endpoint
Sent when a guest is erased under the right to erasure. The guest record is a tombstone from then on — name, phone and email blanked — and this is the fact a CRM must hear: a copy of somebody who has exercised their right is kept personal data. Do NOT keep the old details beyond the receipt your own logs demand.
A merchant running somebody else's CRM is told about a guest the same way it is told about an order; an integration that keeps a copy of the guest book here is the point of the event (guest-record item 19).
See WebhookEnvelope for signature verification, replay protection and the at-least-once delivery contract that applies to every webhook.
Payload application/json

type"customer.erased"

dataCustomer

A guest of the merchant, as the back office and a CRM see them. This is the full record — identity, contact and the staff note — and it is only returned to a signed-in person, never to a device. See CustomerLoyalty for the limited projection a till gets when it looks a guest up to redeem points.

namestring

Required
≤ 200 chars

emailstring · email

Nullable

notestring
A staff-only note about the guest, e.g. preferences or allergies.

phonestring

Nullable
≤ 64 chars
Your reply

200
Acknowledged. Return this as soon as the delivery is durably recorded; do the actual work afterwards, asynchronously.

400
The payload was rejected. Treated as a failure and retried with backoff, so only return this for a delivery you genuinely could not accept.

500
Handler failed. Retried with exponential backoff for 24 hours, then dead-lettered.
Payload
{ "type": "customer.erased", "data": { "name": "string", "email": "ada@example.com", "note": "string", "phone": "string" } }
EVENTcustomer.updated

Guest changed

No. customerUpdatedSent by us, to your endpoint
Sent when a guest record is changed — details, tags, allergies, a merge folding a duplicate into the survivor. An integration keeping a CRM in sync hears the survivor with its new state, and every later change after that one.
A merchant running somebody else's CRM is told about a guest the same way it is told about an order; an integration that keeps a copy of the guest book here is the point of the event (guest-record item 19).
See WebhookEnvelope for signature verification, replay protection and the at-least-once delivery contract that applies to every webhook.
Payload application/json

type"customer.updated"

dataCustomer

A guest of the merchant, as the back office and a CRM see them. This is the full record — identity, contact and the staff note — and it is only returned to a signed-in person, never to a device. See CustomerLoyalty for the limited projection a till gets when it looks a guest up to redeem points.

namestring

Required
≤ 200 chars

emailstring · email

Nullable

notestring
A staff-only note about the guest, e.g. preferences or allergies.

phonestring

Nullable
≤ 64 chars
Your reply

200
Acknowledged. Return this as soon as the delivery is durably recorded; do the actual work afterwards, asynchronously.

400
The payload was rejected. Treated as a failure and retried with backoff, so only return this for a delivery you genuinely could not accept.

500
Handler failed. Retried with exponential backoff for 24 hours, then dead-lettered.
Payload
{ "type": "customer.updated", "data": { "name": "string", "email": "ada@example.com", "note": "string", "phone": "string" } }
EVENTdispute.opened

Dispute opened

No. disputeOpenedSent by us, to your endpoint
Sent when a processor opens a card dispute against a payment.
The dispute's data carries the deadline by which evidence must be submitted, because that deadline is the half the merchant can act on — a dispute opened is a clock started, not a decision made.
See WebhookEnvelope for signature verification, replay protection and the at-least-once delivery contract that applies to every webhook.
Payload application/json

type"dispute.opened"

dataobject

idstring · uuid

Required

created_atstring · date-time

Required

deadlinestring · date-time

Required
By when the evidence must be submitted to the processor.

payment_idstring · uuid

Required
The card payment this dispute challenges.

processor_refstring
The processor's own reference for the dispute, where it has one. The property is omitted when the processor has none.
≤ 128 chars

statusstring · enum

Required
openedevidence_submittedwonlost

updated_atstring · date-time
Omitted until the processor reports a change.
Your reply

200
Acknowledged. Return this as soon as the delivery is durably recorded; do the actual work afterwards, asynchronously.

400
The payload was rejected. Treated as a failure and retried with backoff, so only return this for a delivery you genuinely could not accept.

500
Handler failed. Retried with exponential backoff for 24 hours, then dead-lettered.
Payload
{ "type": "dispute.opened", "data": { "id": "0192f1e4-7c3a-7b2e-9f10-5d6c7e8f9a0b", "created_at": "2026-09-11T09:30:00Z", "deadline": "2026-09-11T09:30:00Z", "payment_id": "0192f1e4-7c3a-7b2e-9f10-5d6c7e8f9a0b", "processor_ref": "string", "status": "opened", "updated_at": "2026-09-11T09:30:00Z" } }
EVENTinventory_level.low

Inventory level low

No. inventoryLevelLowSent by us, to your endpoint
Sent when a product's inventory at a location falls to or below its reorder_point.
Fires on the transition, not on every subsequent sale, so a product sitting below its reorder point does not generate an event per transaction. It fires again only after inventory rises back above the reorder point and falls through it once more.
See WebhookEnvelope for signature verification, replay protection and the at-least-once delivery contract that applies to every webhook.
Payload application/json

type"inventory_level.low"

dataInventoryLevel

The inventory level of one product at one location.
Inventory is the one resource that is neither purely server- nor purely device-authoritative, because both the dashboard (deliveries, stocktakes) and tills (sales) move it. It is therefore never written as an absolute value from a device — only as a signed adjustment, applied server-side.
That distinction is what makes offline inventory correct. Two tills that both go offline holding "12 in stock" and each sell 3 would, on absolute writes, both send "9" and lose a sale. Sending "-3" twice yields 6, which is the truth.

location_idstring · uuid

Required

lowboolean

Required
Whether the level is at or below its reorder_point. False when it has none.

product_idstring · uuid

Required

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})?$

reorder_levelQuantity

Nullable
The level a reorder brings this one back up to. Null when none is set, and nothing is suggested for it.
≤ 26 chars · pattern ^-?(0|[1-9][0-9]*)(\.[0-9]{1,6})?$

reorder_pointQuantity

Nullable
Level at or below which an inventory_level.low webhook fires. Null disables it.
≤ 26 chars · pattern ^-?(0|[1-9][0-9]*)(\.[0-9]{1,6})?$

unit_of_measurestring · enum
The unit quantity, reorder_point and reorder_level are in — the product's own unit of measure, normalized.
eachkgglml

variant_idstring · uuid
The variant this level is for, when it is a variant rather than the product itself (retail item 2, stage two). Absent means the product's own level.
Your reply

200
Acknowledged. Return this as soon as the delivery is durably recorded; do the actual work afterwards, asynchronously.

400
The payload was rejected. Treated as a failure and retried with backoff, so only return this for a delivery you genuinely could not accept.

500
Handler failed. Retried with exponential backoff for 24 hours, then dead-lettered.
Payload
{ "type": "inventory_level.low", "data": { "location_id": "0192f1e4-7c3a-7b2e-9f10-5d6c7e8f9a0b", "low": false, "product_id": "0192f1e4-7c3a-7b2e-9f10-5d6c7e8f9a0b", "quantity": "3", "reorder_level": "3", "reorder_point": "3", "unit_of_measure": "each", "variant_id": "0192f1e4-7c3a-7b2e-9f10-5d6c7e8f9a0b" } }
EVENTinventory_movement.created

Inventory movement created

No. inventoryMovementCreatedSent by us, to your endpoint
Sent when a stock movement is recorded in a product's ledger — an adjustment, a stocktake, a received purchase order, a transfer between locations, or wastage.
Fires in the same transaction as the movement, so a movement that commits always has its announcement queued and one that rolls back never does. Sales and refunds are not announced here — they are already covered by order.completed, order.voided and order.refunded, and the reason of a movement tells a receiver why it happened.
See WebhookEnvelope for signature verification, replay protection and the at-least-once delivery contract that applies to every webhook.
Payload application/json

type"inventory_movement.created"

dataInventory movement

One entry in a product's movement ledger at one location.

idstring · uuid

Required
The movement's own id.

costMoney

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 movement was recorded.

deltaQuantity

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})?$

location_idstring · uuid

Required
The location the movement happened at.

member_namestring
The member who made the sale or void, when one is on record.

notestring
A free note the merchant left, when there is one.

order_idstring · uuid

Nullable
The order the movement belongs to, when it was a sale or a void.

order_referencestring
The order's human reference, when it has one.

product_idstring · uuid

Required
The product the movement is for.

reasonstring

Required
Why it moved: sale, refund, void, adjustment, count, transfer or purchase.

unit_of_measurestring · enum
The unit delta is in: each, kg, g, l or ml (inventory item 16). Absent means each.
eachkgglml

variant_idstring · uuid
The variant this movement is for, when it is a variant rather than the product itself (retail item 2, stage two). Absent means the product.
Your reply

200
Acknowledged. Return this as soon as the delivery is durably recorded; do the actual work afterwards, asynchronously.

400
The payload was rejected. Treated as a failure and retried with backoff, so only return this for a delivery you genuinely could not accept.

500
Handler failed. Retried with exponential backoff for 24 hours, then dead-lettered.
Payload
{ "type": "inventory_movement.created", "data": { "id": "0192f1e4-7c3a-7b2e-9f10-5d6c7e8f9a0b", "cost": { "amount": 1250, "currency": "GBP" }, "created_at": "2026-09-11T09:30:00Z", "delta": "3", "location_id": "0192f1e4-7c3a-7b2e-9f10-5d6c7e8f9a0b", "member_name": "string", "note": "string", "order_id": "0192f1e4-7c3a-7b2e-9f10-5d6c7e8f9a0b", "order_reference": "string", "product_id": "0192f1e4-7c3a-7b2e-9f10-5d6c7e8f9a0b", "reason": "string", "unit_of_measure": "each", "variant_id": "0192f1e4-7c3a-7b2e-9f10-5d6c7e8f9a0b" } }
EVENTinventory_price.alert

Inventory price alert

No. inventoryPriceAlertSent by us, to your endpoint
Sent when a delivery's unit cost for a product at a location moved at or beyond the merchant's price_spike_threshold_percentage against the previous delivery of the same product to the same location (inventory item 18).
Fires on the delivery that moved, so a supplier's new price generates one event and not one per subsequent sale. It never fires for a product's first delivery to a location, since there is nothing to compare against, nor when the merchant has set no threshold.
The payload is the product's inventory at that location — the subject the alert is about, re-read at delivery time. It names the product and the location, and the costs behind the move are read from GET /v1/inventory/price-history, which carries each delivery's unit cost, the one before it and the supplier who charged it. The event deliberately does not carry a cost of its own: a snapshot taken when the job was enqueued would be stale by the time a retry ran.
See WebhookEnvelope for signature verification, replay protection and the at-least-once delivery contract that applies to every webhook.
Payload application/json

type"inventory_price.alert"

dataInventoryLevel

The inventory level of one product at one location.
Inventory is the one resource that is neither purely server- nor purely device-authoritative, because both the dashboard (deliveries, stocktakes) and tills (sales) move it. It is therefore never written as an absolute value from a device — only as a signed adjustment, applied server-side.
That distinction is what makes offline inventory correct. Two tills that both go offline holding "12 in stock" and each sell 3 would, on absolute writes, both send "9" and lose a sale. Sending "-3" twice yields 6, which is the truth.

location_idstring · uuid

Required

lowboolean

Required
Whether the level is at or below its reorder_point. False when it has none.

product_idstring · uuid

Required

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})?$

reorder_levelQuantity

Nullable
The level a reorder brings this one back up to. Null when none is set, and nothing is suggested for it.
≤ 26 chars · pattern ^-?(0|[1-9][0-9]*)(\.[0-9]{1,6})?$

reorder_pointQuantity

Nullable
Level at or below which an inventory_level.low webhook fires. Null disables it.
≤ 26 chars · pattern ^-?(0|[1-9][0-9]*)(\.[0-9]{1,6})?$

unit_of_measurestring · enum
The unit quantity, reorder_point and reorder_level are in — the product's own unit of measure, normalized.
eachkgglml

variant_idstring · uuid
The variant this level is for, when it is a variant rather than the product itself (retail item 2, stage two). Absent means the product's own level.
Your reply

200
Acknowledged. Return this as soon as the delivery is durably recorded; do the actual work afterwards, asynchronously.

400
The payload was rejected. Treated as a failure and retried with backoff, so only return this for a delivery you genuinely could not accept.

500
Handler failed. Retried with exponential backoff for 24 hours, then dead-lettered.
Payload
{ "type": "inventory_price.alert", "data": { "location_id": "0192f1e4-7c3a-7b2e-9f10-5d6c7e8f9a0b", "low": false, "product_id": "0192f1e4-7c3a-7b2e-9f10-5d6c7e8f9a0b", "quantity": "3", "reorder_level": "3", "reorder_point": "3", "unit_of_measure": "each", "variant_id": "0192f1e4-7c3a-7b2e-9f10-5d6c7e8f9a0b" } }
EVENTjob.completed

Job completed

No. jobCompletedSent by us, to your endpoint
Sent when a long-running job finished, successfully or not.
The job was started by a 202 Accepted response, and clients that started it may poll rather than register a webhook. data is the job record; a data.status of failed is a normal outcome to handle, not an error in the delivery. Sent when a background job the merchant's integration started finishes.
The job's data names the operation and its resource, so a receiver can continue whatever it queued — reading for the work the job produced.
See WebhookEnvelope for signature verification, replay protection and the at-least-once delivery contract that applies to every webhook.
Payload application/json

type"job.completed"

dataJob

Long-running work started by a 202 Accepted response.
Work that cannot complete inside a request — a catalogue import of ten thousand rows, a month-end export, a settlement run — returns 202 with a Location pointing at one of these, and the client polls it. Poll no faster than the Retry-After given on the original response.

idstring · uuid

Required

typeJobType

Required
What a job is doing, named for what started it: a catalog_import is created by POST /v1/catalog-imports. report_export and settlement_run are reserved for work not built yet.
catalog_importreport_exportsettlement_run

finished_atstring · date-time

Nullable

problemProblem

Nullable
Present when status is failed.

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.

progressobject

Nullable
Best-effort progress. Advisory only — total_units may be revised upward as work is discovered, so never treat completed_units == total_units as completion. status is the only authority on whether the job is done.

completed_unitsinteger · int64

Required
Units of work finished so far.
≥ 0

total_unitsinteger · int64

Required
Units of work known about. Named total_units rather than total because a bare total beside monetary fields reads as an amount, and in an API where every other total is money that ambiguity is worth spending a word on.
≥ 0

resultobject

Nullable
What the job produced, present when status is succeeded. For an export this carries a time-limited download URL.

started_atstring · date-time

Nullable

statusstring · enum

Required
pending — accepted and queued, not yet picked up by a worker.
running — in progress; progress may be populated.
succeeded — finished; result is populated.
failed — finished unsuccessfully; problem explains why. Terminal: the job will not be retried on its own, though the request may be re-submitted.
canceled — stopped before it finished. Terminal.
pendingrunningsucceededfailedcanceled
Your reply

200
Acknowledged. Return this as soon as the delivery is durably recorded; do the actual work afterwards, asynchronously.

400
The payload was rejected. Treated as a failure and retried with backoff, so only return this for a delivery you genuinely could not accept.

500
Handler failed. Retried with exponential backoff for 24 hours, then dead-lettered.
Payload
{ "type": "job.completed", "data": { "id": "0192f1e4-7c3a-7b2e-9f10-5d6c7e8f9a0b", "type": "catalog_import", "finished_at": "2026-09-11T09:30:00Z", "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" }, "progress": { "completed_units": 0, "total_units": 0 }, "result": {}, "started_at": "2026-09-11T09:30:00Z", "status": "pending" } }
EVENTorder.accepted

Order accepted

No. orderAcceptedSent by us, to your endpoint
Sent when the venue takes on an order that asked to be accepted — an online order, or one from another channel whose orders wait for the venue — once, on the transition. A till's own sale is never waiting, so it never sends this. The order is still open.
See WebhookEnvelope for signature verification, replay protection and the at-least-once delivery contract that applies to every webhook.
Payload application/json

type"order.accepted"

dataOrder

A sale, from the moment it is started to the moment it is paid, and after.
An order has a lifecycle (docs/decisions/0012). open is being built — a tab at a bar, a parked sale at a shop — and changes freely, shared between the devices at its location. completed is the financial fact, and completed orders are append-only: the server never modifies one, and corrections happen by voiding and re-issuing, because an order is a financial record and a payfac needs it to be immutable and auditable. An open order that ends without being paid is canceled and kept.
Every monetary field is a snapshot taken at the moment of sale, not a reference to current catalogue data. If the price of a flat white rises tomorrow, yesterday's receipt must still reprint at yesterday's price — so the line item stores the name, unit price and tax rate it was actually sold at, and resolving product_id is only ever for reporting.

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

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

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.

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

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

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

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

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.

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.

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.

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})?)$

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.

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.
Your reply

200
Acknowledged. Return this as soon as the delivery is durably recorded; do the actual work afterwards, asynchronously.

400
The payload was rejected. Treated as a failure and retried with backoff, so only return this for a delivery you genuinely could not accept.

500
Handler failed. Retried with exponential backoff for 24 hours, then dead-lettered.
Payload
{ "type": "order.accepted", "data": { "id": "0192f1e4-7c3a-7b2e-9f10-5d6c7e8f9a0b", "name": "Sam", "age_confirmed": false, "age_minimum": 0, "channel_cost": { "amount": 1250, "currency": "GBP" }, "client_created_at": "2026-09-11T09:30:00Z", "closed_at": "2026-09-11T09:30:00Z", "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, "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", "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", "member": { "id": "0192f1e4-7c3a-7b2e-9f10-5d6c7e8f9a0b", "name": "string", "email": "ada@example.com", "role": "owner" }, "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" }, "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" } } ], "reference": "A-0148", "refunded": { "amount": 1250, "currency": "GBP" }, "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", "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" } }, "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" } }
EVENTorder.canceled

Order canceled

No. orderCanceledSent by us, to your endpoint
Sent when an open order is canceled — a venue turns away an online order, or a guest leaves before paying. The order's own canceled_reason says why. Fires in the same transaction as the cancel, so a retry under the same idempotency key never re-announces it.
See WebhookEnvelope for signature verification, replay protection and the at-least-once delivery contract that applies to every webhook.
Payload application/json

type"order.canceled"

dataOrder

A sale, from the moment it is started to the moment it is paid, and after.
An order has a lifecycle (docs/decisions/0012). open is being built — a tab at a bar, a parked sale at a shop — and changes freely, shared between the devices at its location. completed is the financial fact, and completed orders are append-only: the server never modifies one, and corrections happen by voiding and re-issuing, because an order is a financial record and a payfac needs it to be immutable and auditable. An open order that ends without being paid is canceled and kept.
Every monetary field is a snapshot taken at the moment of sale, not a reference to current catalogue data. If the price of a flat white rises tomorrow, yesterday's receipt must still reprint at yesterday's price — so the line item stores the name, unit price and tax rate it was actually sold at, and resolving product_id is only ever for reporting.

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

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

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.

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

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

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

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

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.

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.

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.

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})?)$

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.

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.
Your reply

200
Acknowledged. Return this as soon as the delivery is durably recorded; do the actual work afterwards, asynchronously.

400
The payload was rejected. Treated as a failure and retried with backoff, so only return this for a delivery you genuinely could not accept.

500
Handler failed. Retried with exponential backoff for 24 hours, then dead-lettered.
Payload
{ "type": "order.canceled", "data": { "id": "0192f1e4-7c3a-7b2e-9f10-5d6c7e8f9a0b", "name": "Sam", "age_confirmed": false, "age_minimum": 0, "channel_cost": { "amount": 1250, "currency": "GBP" }, "client_created_at": "2026-09-11T09:30:00Z", "closed_at": "2026-09-11T09:30:00Z", "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, "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", "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", "member": { "id": "0192f1e4-7c3a-7b2e-9f10-5d6c7e8f9a0b", "name": "string", "email": "ada@example.com", "role": "owner" }, "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" }, "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" } } ], "reference": "A-0148", "refunded": { "amount": 1250, "currency": "GBP" }, "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", "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" } }, "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" } }
EVENTorder.completed

Order completed

No. orderCompletedSent by us, to your endpoint
Sent when a sale is finalised.
For an offline sale this fires when the order reaches the server, not when the till took it — which may be hours later. Use data.client_created_at if you need the time of sale itself, and expect events for sales that are already old.
See WebhookEnvelope for signature verification, replay protection and the at-least-once delivery contract that applies to every webhook.
Payload application/json

type"order.completed"

dataOrder

A sale, from the moment it is started to the moment it is paid, and after.
An order has a lifecycle (docs/decisions/0012). open is being built — a tab at a bar, a parked sale at a shop — and changes freely, shared between the devices at its location. completed is the financial fact, and completed orders are append-only: the server never modifies one, and corrections happen by voiding and re-issuing, because an order is a financial record and a payfac needs it to be immutable and auditable. An open order that ends without being paid is canceled and kept.
Every monetary field is a snapshot taken at the moment of sale, not a reference to current catalogue data. If the price of a flat white rises tomorrow, yesterday's receipt must still reprint at yesterday's price — so the line item stores the name, unit price and tax rate it was actually sold at, and resolving product_id is only ever for reporting.

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

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

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.

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

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

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

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

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.

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.

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.

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})?)$

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.

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.
Your reply

200
Acknowledged. Return this as soon as the delivery is durably recorded; do the actual work afterwards, asynchronously.

400
The payload was rejected. Treated as a failure and retried with backoff, so only return this for a delivery you genuinely could not accept.

500
Handler failed. Retried with exponential backoff for 24 hours, then dead-lettered.
Payload
{ "type": "order.completed", "data": { "id": "0192f1e4-7c3a-7b2e-9f10-5d6c7e8f9a0b", "name": "Sam", "age_confirmed": false, "age_minimum": 0, "channel_cost": { "amount": 1250, "currency": "GBP" }, "client_created_at": "2026-09-11T09:30:00Z", "closed_at": "2026-09-11T09:30:00Z", "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, "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", "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", "member": { "id": "0192f1e4-7c3a-7b2e-9f10-5d6c7e8f9a0b", "name": "string", "email": "ada@example.com", "role": "owner" }, "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" }, "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" } } ], "reference": "A-0148", "refunded": { "amount": 1250, "currency": "GBP" }, "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", "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" } }, "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" } }
EVENTorder.opened

Order opened

No. orderOpenedSent by us, to your endpoint
Sent when an order is first written open — a tab opened at a table, or an online order that has just arrived. This fires on the first write of the open order, not on a later update to it, and in the same transaction, so an integration sees it the moment it lands rather than only when it is later completed or canceled.
See WebhookEnvelope for signature verification, replay protection and the at-least-once delivery contract that applies to every webhook.
Payload application/json

type"order.opened"

dataOrder

A sale, from the moment it is started to the moment it is paid, and after.
An order has a lifecycle (docs/decisions/0012). open is being built — a tab at a bar, a parked sale at a shop — and changes freely, shared between the devices at its location. completed is the financial fact, and completed orders are append-only: the server never modifies one, and corrections happen by voiding and re-issuing, because an order is a financial record and a payfac needs it to be immutable and auditable. An open order that ends without being paid is canceled and kept.
Every monetary field is a snapshot taken at the moment of sale, not a reference to current catalogue data. If the price of a flat white rises tomorrow, yesterday's receipt must still reprint at yesterday's price — so the line item stores the name, unit price and tax rate it was actually sold at, and resolving product_id is only ever for reporting.

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

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

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.

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

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

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

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

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.

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.

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.

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})?)$

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.

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.
Your reply

200
Acknowledged. Return this as soon as the delivery is durably recorded; do the actual work afterwards, asynchronously.

400
The payload was rejected. Treated as a failure and retried with backoff, so only return this for a delivery you genuinely could not accept.

500
Handler failed. Retried with exponential backoff for 24 hours, then dead-lettered.
Payload
{ "type": "order.opened", "data": { "id": "0192f1e4-7c3a-7b2e-9f10-5d6c7e8f9a0b", "name": "Sam", "age_confirmed": false, "age_minimum": 0, "channel_cost": { "amount": 1250, "currency": "GBP" }, "client_created_at": "2026-09-11T09:30:00Z", "closed_at": "2026-09-11T09:30:00Z", "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, "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", "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", "member": { "id": "0192f1e4-7c3a-7b2e-9f10-5d6c7e8f9a0b", "name": "string", "email": "ada@example.com", "role": "owner" }, "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" }, "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" } } ], "reference": "A-0148", "refunded": { "amount": 1250, "currency": "GBP" }, "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", "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" } }, "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" } }
EVENTorder.refunded

Order refunded

No. orderRefundedSent by us, to your endpoint
Sent when money is returned on a completed sale.
A refund is a new ledger entry that references the original order and never edits it. data is the refund record, not the order; use its order_id to find the sale it reversed. Sent when an order is refunded.
For an offline sale this fires when the refund reaches the server, not when the till recorded it — which may be hours later. The refund's data carries the original sale's reference, so a receiver can match it to the order it holds.
See WebhookEnvelope for signature verification, replay protection and the at-least-once delivery contract that applies to every webhook.
Payload application/json

type"order.refunded"

dataRefund

A refund is a new ledger entry that returns money on a completed sale. It references the original order and never edits it: the sale stays exactly as it was, and this is the record of the money going back. The total is derived from the payments server-side and is never accepted from a client.

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.
Your reply

200
Acknowledged. Return this as soon as the delivery is durably recorded; do the actual work afterwards, asynchronously.

400
The payload was rejected. Treated as a failure and retried with backoff, so only return this for a delivery you genuinely could not accept.

500
Handler failed. Retried with exponential backoff for 24 hours, then dead-lettered.
Payload
{ "type": "order.refunded", "data": { "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 } }
EVENTorder.rejected

Order rejected

No. orderRejectedSent by us, to your endpoint
Sent when the venue turns away an order that asked to be accepted, or nobody answered it before its deadline and it was rejected for them — once, on the transition. The order is canceled, and data says why.
See WebhookEnvelope for signature verification, replay protection and the at-least-once delivery contract that applies to every webhook.
Payload application/json

type"order.rejected"

dataOrder

A sale, from the moment it is started to the moment it is paid, and after.
An order has a lifecycle (docs/decisions/0012). open is being built — a tab at a bar, a parked sale at a shop — and changes freely, shared between the devices at its location. completed is the financial fact, and completed orders are append-only: the server never modifies one, and corrections happen by voiding and re-issuing, because an order is a financial record and a payfac needs it to be immutable and auditable. An open order that ends without being paid is canceled and kept.
Every monetary field is a snapshot taken at the moment of sale, not a reference to current catalogue data. If the price of a flat white rises tomorrow, yesterday's receipt must still reprint at yesterday's price — so the line item stores the name, unit price and tax rate it was actually sold at, and resolving product_id is only ever for reporting.

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

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

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.

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

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

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

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

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.

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.

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.

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})?)$

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.

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.
Your reply

200
Acknowledged. Return this as soon as the delivery is durably recorded; do the actual work afterwards, asynchronously.

400
The payload was rejected. Treated as a failure and retried with backoff, so only return this for a delivery you genuinely could not accept.

500
Handler failed. Retried with exponential backoff for 24 hours, then dead-lettered.
Payload
{ "type": "order.rejected", "data": { "id": "0192f1e4-7c3a-7b2e-9f10-5d6c7e8f9a0b", "name": "Sam", "age_confirmed": false, "age_minimum": 0, "channel_cost": { "amount": 1250, "currency": "GBP" }, "client_created_at": "2026-09-11T09:30:00Z", "closed_at": "2026-09-11T09:30:00Z", "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, "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", "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", "member": { "id": "0192f1e4-7c3a-7b2e-9f10-5d6c7e8f9a0b", "name": "string", "email": "ada@example.com", "role": "owner" }, "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" }, "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" } } ], "reference": "A-0148", "refunded": { "amount": 1250, "currency": "GBP" }, "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", "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" } }, "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" } }
EVENTorder.voided

Order voided

No. orderVoidedSent by us, to your endpoint
Sent when a sale is cancelled. The order still exists, in voided state — do not treat this as a deletion.
See WebhookEnvelope for signature verification, replay protection and the at-least-once delivery contract that applies to every webhook.
Payload application/json

type"order.voided"

dataOrder

A sale, from the moment it is started to the moment it is paid, and after.
An order has a lifecycle (docs/decisions/0012). open is being built — a tab at a bar, a parked sale at a shop — and changes freely, shared between the devices at its location. completed is the financial fact, and completed orders are append-only: the server never modifies one, and corrections happen by voiding and re-issuing, because an order is a financial record and a payfac needs it to be immutable and auditable. An open order that ends without being paid is canceled and kept.
Every monetary field is a snapshot taken at the moment of sale, not a reference to current catalogue data. If the price of a flat white rises tomorrow, yesterday's receipt must still reprint at yesterday's price — so the line item stores the name, unit price and tax rate it was actually sold at, and resolving product_id is only ever for reporting.

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

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

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.

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

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

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

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

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.

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.

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.

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})?)$

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.

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.
Your reply

200
Acknowledged. Return this as soon as the delivery is durably recorded; do the actual work afterwards, asynchronously.

400
The payload was rejected. Treated as a failure and retried with backoff, so only return this for a delivery you genuinely could not accept.

500
Handler failed. Retried with exponential backoff for 24 hours, then dead-lettered.
Payload
{ "type": "order.voided", "data": { "id": "0192f1e4-7c3a-7b2e-9f10-5d6c7e8f9a0b", "name": "Sam", "age_confirmed": false, "age_minimum": 0, "channel_cost": { "amount": 1250, "currency": "GBP" }, "client_created_at": "2026-09-11T09:30:00Z", "closed_at": "2026-09-11T09:30:00Z", "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, "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", "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", "member": { "id": "0192f1e4-7c3a-7b2e-9f10-5d6c7e8f9a0b", "name": "string", "email": "ada@example.com", "role": "owner" }, "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" }, "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" } } ], "reference": "A-0148", "refunded": { "amount": 1250, "currency": "GBP" }, "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", "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" } }, "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" } }
EVENTpayout.paid

Payout paid

No. payoutPaidSent by us, to your endpoint
Sent when a transfer from the processor to the merchant's bank has moved.
data is the payout, including the itemised movements that make it up. Whether the money has cleared the merchant's bank is the bank's business and not something this records; use it to reconcile a bank line, not to confirm settlement. Sent when a payout leaves the processor.
The payout's data is the record a bookkeeper reconciles a bank line against — what arrived and the movements it is made of. This is the event that replaces polling GET /v1/payouts for a merchant who wants to know when money moves.
See WebhookEnvelope for signature verification, replay protection and the at-least-once delivery contract that applies to every webhook.
Payload application/json

type"payout.paid"

dataPayout

One transfer from the processor to the merchant's bank, with the movements that make it up. This is the record a bookkeeper reconciles a bank line against: the total is what arrived, and the items say where it came from.

idstring · uuid

Required

amountMoney

Required
What arrived, which is the sum of the items' signed amounts.

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.

arrival_datestring · date

Nullable
When the processor expects it to arrive, where it has said.

by_kindarray of PayoutKindTotal

Required
The items summed by kind, signed: what each kind added to the payout or took from it, so they add up to amount. Captures first, then what reduced them; a kind the payout has none of is absent.

kindstring · enum

Required
capturerefundfeechargebackadjustment

amountMoney

Required
Signed, so the kinds of a payout add up to its amount.

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.

itemsarray of PayoutItem

Required
The movements that make up the total, in the order the processor gave them.

kindstring · enum

Required
capture — a sale settling, which adds to the payout.
refund — money returned to a cardholder, which takes from it.
fee — the processor's charge.
chargeback — a disputed sale clawed back.
adjustment — anything else the processor moved, carrying its own sign.
capturerefundfeechargebackadjustment

amountMoney

Required
The movement's magnitude. For every kind but adjustment this is non-negative and the kind decides the direction; an adjustment carries its own sign.

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

Nullable
The order this movement belongs to, when it is one of ours.

payment_idstring · uuid

Nullable
The payment this movement settles, when it is one of ours.

referencestring

Required
The processor's own reference for the movement, for reconciliation.
≤ 255 chars

payment_account_idstring · uuid

Required
The payment account the money was paid out of.

settlement_datestring · date

Nullable
The processor's settlement day the payout was built from, on the processor's own clock: the takings it pays out. Null for a payout recorded before settlement reports were kept.

statusstring · enum

Required
pending — the processor has announced it but the money has not moved (Stripe's word).
paid — it has left the processor. Whether it has cleared the merchant's bank is the bank's business and not something this records.
failed — it did not go through; the money stays with the processor and is normally carried into a later payout.
pendingpaidfailed

transitionsarray of PayoutTransition

Every move of the payout's status, oldest first: who said so and when. Present on a payout read by its id.

amountMoney

The amount the processor gave with the move, where it gave 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.

processor_event_idstring
The processor's own id for the event, where it gave one.

processor_occurred_atstring · date-time

Nullable
When the processor says the move happened.

received_atstring · date-time

Required
When we learned of it.

sourcestring · enum

Required
processor when the processor said so, merchant when somebody here recorded it, and reconstructed when nobody said so and it was inferred from the status the payout held.
processormerchantreconstructed

statusstring · enum

Required
pendingpaidfailed
Your reply

200
Acknowledged. Return this as soon as the delivery is durably recorded; do the actual work afterwards, asynchronously.

400
The payload was rejected. Treated as a failure and retried with backoff, so only return this for a delivery you genuinely could not accept.

500
Handler failed. Retried with exponential backoff for 24 hours, then dead-lettered.
Payload
{ "type": "payout.paid", "data": { "id": "0192f1e4-7c3a-7b2e-9f10-5d6c7e8f9a0b", "amount": { "amount": 1250, "currency": "GBP" }, "arrival_date": "2026-09-11", "by_kind": [ { "kind": "capture", "amount": { "amount": 1250, "currency": "GBP" } } ], "items": [ { "kind": "capture", "amount": { "amount": 1250, "currency": "GBP" }, "order_id": "0192f1e4-7c3a-7b2e-9f10-5d6c7e8f9a0b", "payment_id": "0192f1e4-7c3a-7b2e-9f10-5d6c7e8f9a0b", "reference": "string" } ], "payment_account_id": "0192f1e4-7c3a-7b2e-9f10-5d6c7e8f9a0b", "settlement_date": "2026-09-11", "status": "pending", "transitions": [ { "amount": { "amount": 1250, "currency": "GBP" }, "processor_event_id": "string", "processor_occurred_at": "2026-09-11T09:30:00Z", "received_at": "2026-09-11T09:30:00Z", "source": "processor", "status": "pending" } ] } }
EVENTproduct_availability.updated

Product availability updated

No. productAvailabilityUpdatedSent by us, to your endpoint
Sent when a product's availability changes at a location — a dish is 86'd or brought back. Fires in the same transaction as the change, so a retry under the same idempotency key never re-announces it, and an integration upstream stops holding the stale flag.
See WebhookEnvelope for signature verification, replay protection and the at-least-once delivery contract that applies to every webhook.
Payload application/json

type"product_availability.updated"

dataobject

availableboolean

Required

location_idstring · uuid

Required

product_idstring · uuid

Required
Your reply

200
Acknowledged. Return this as soon as the delivery is durably recorded; do the actual work afterwards, asynchronously.

400
The payload was rejected. Treated as a failure and retried with backoff, so only return this for a delivery you genuinely could not accept.

500
Handler failed. Retried with exponential backoff for 24 hours, then dead-lettered.
Payload
{ "type": "product_availability.updated", "data": { "available": false, "location_id": "0192f1e4-7c3a-7b2e-9f10-5d6c7e8f9a0b", "product_id": "0192f1e4-7c3a-7b2e-9f10-5d6c7e8f9a0b" } }

Parameters

Responses

Parameters

Request body application/json · WebhookEndpointCreate

Responses

Parameters

Request body application/merge-patch+json · WebhookEndpointPatch

Responses

Parameters

Responses

Parameters

Responses

Parameters

Responses

Parameters

Responses

Payload application/json

Your reply

Payload application/json

Your reply

Payload application/json

Your reply

Payload application/json

Your reply

Payload application/json

Your reply

Payload application/json

Your reply

Payload application/json

Your reply

Payload application/json

Your reply

Payload application/json

Your reply

Payload application/json

Your reply

Payload application/json

Your reply

Payload application/json

Your reply

Payload application/json

Your reply

Payload application/json

Your reply

Payload application/json

Your reply

Payload application/json

Your reply

Payload application/json

Your reply