Drawer sessions · Tenvelo API

GET/v1/drawer-flags

List drawer flags

No. listDrawerFlagsAuth pos:drawer-sessions:read
Returns the drawer flags nobody has dealt with yet, newest first.
A flag is what the server says instead of refusing. Nothing a device recorded is turned away — the count happened, the cash moved — so where the drawer projector cannot apply a fact, it applies the session as far as it goes and a flag says what did not fit. That makes this the only place some of them appear: a drawer counted twice looks settled on the report itself, and the money shortfall is nowhere else.
A flag's session_id may name a drawer that does not exist. That is the most serious kind there is: the projector could not place the count at all, so the drawer is on the device that recorded it and in no books. Those are returned like any other.
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
The open drawer flags, newest first.

DrawerFlagPage · application/json

has_moreboolean

Required
Whether another page follows.

itemsarray of DrawerFlag

Required

idstring · uuid

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

created_atTimestamp

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

detailstring

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

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

session_idstring · uuid

Required
The drawer session this is about, as the fact named it.
The session may not exist. A flag is raised for a fact the projector could not place at all — a count for a drawer nothing opened — and that is the most serious kind there is: the drawer was counted and the session is nowhere. Read this as the session it refers to, not as one you can always fetch.

next_cursorstring

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

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

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

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

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

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

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

500
Something failed on our side. trace_id identifies the request in our tracing — quote it in a support ticket.
The body never carries internal detail: no SQL, no stack traces, no upstream error strings. Safe to retry with the same Idempotency-Key.
Request
curl -X GET 'https://api.tenvelo.com/v1/drawer-flags' \ -H "Authorization: Bearer $TOKEN"
Response
{ "has_more": false, "items": [ { "id": "0192f1e4-7c3a-7b2e-9f10-5d6c7e8f9a0b", "created_at": "2026-09-08T09:41:12Z", "detail": "a second close on a drawer that is already counted", "fact_id": "0192f1e4-7c3a-7b2e-9f10-5d6c7e8f9a0b", "session_id": "0192f1e4-7c3a-7b2e-9f10-5d6c7e8f9a0b" } ], "next_cursor": "string" }
POST/v1/drawer-flags/{id}/clear

Record that a drawer flag was dealt with

No. clearDrawerFlagAuth pos:drawer-sessions:write
Records that a person has dealt with the flag: a flag_cleared fact on the drawer's subject, folded like any other — the clear is as much a fact as the flag was, and the row stays in place, so the same fact can never raise the flag again. This is the operation the list points at. It is not doing nothing: it is the person saying the money was handled.
Idempotent: the fact's id is derived from the flag, so a retry records the same fact once, and a flag already cleared answers as clear. A device token is refused with 403 — a till reads its own drawer through the X-read, and a flag is a person's to deal with.
Parameters

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

204
The flag is recorded as dealt with.

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

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

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

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

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

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

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

Submit drawer sessions

No. batchUpsertDrawerSessionsAuth pos:drawer-sessions:write
Submits drawer sessions a client has queued — a till's open and close while it was offline, or one sent the moment it happened.
The client mints every session's id, so a retried batch converges on the same records rather than opening two drawers. Each item carries its own idempotency_key and stands or falls on its own: an invalid or refused item fails in its result, and every other item is still applied.
A session arrives open with its counted float, and is written once more as closed — with the version it was written from, and the counted_cash and expected_cash the till saw — when the drawer is counted. It is one record throughout: the id the device minted is the id of the session. A device with a session already open is refused with 409.
Request body application/json · DrawerSessionBatchUpsertRequest

itemsarray of DrawerSessionBatchUpsertItem

Required
≥ 1 items · ≤ 500 items

drawer_sessionDrawerSessionWrite

Required
A drawer session as a client writes it: an open one with its float, or the same record written once more as closed when the till counts it. The device supplies the id, so submitting the same session twice — a retried batch after a lost response — converges on one record rather than opening a second drawer. The merchant, the business date, the over/short and the version are the server's, and are never demanded of or accepted from a client.

idstring · uuid

Required
UUIDv7, minted by the device.

closed_atstring · date-time

Nullable
When the drawer was closed, or null while the session is open.

closed_by_member_idstring · uuid
The member who closed this drawer session.

counted_cashMoney

Nullable
What was actually counted in the drawer at close. The merchant's figure, entered blind so the person counting does not see what the system expects first.

amountinteger · int64

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

currencyCurrency

Required
ISO 4217 currency code.
Determines the minor unit that Money.amount is 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

Required
The till the drawer was open on.

device_seqinteger · int64

Nullable
The sequence this till had reached when it counted the drawer — the highest device_seq it has recorded a fact at ((device_id, device_seq), decision 0005).
Sent on a close, and it is what makes the over/short trustworthy. The server derives the expected cash from the session's takings, and a till's sales reach it as facts that are applied after they are acknowledged. Without this the close could be applied while sales it is for were still being applied, and the over/short — which is stored once and never recomputed — would be wrong by exactly those takings. Told what the close is a close for, the server waits until it has that much.
Null from a client that is not a device, and on an open session, which stores no figure to be wrong.
≥ 0

expected_cashMoney

Nullable
What the drawer should hold, computed by the till from the sales, refunds and cash movements it recorded in the session. Supplied at close; the server records it.

amountinteger · int64

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

currencyCurrency

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

float_cashMoney

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.

location_idstring · uuid

Required
The location the drawer belongs to.

opened_atstring · date-time

Required
When the drawer was opened, as the device saw it.

opened_by_member_idstring · uuid
The member who opened this drawer session.

over_short_reasonstring

Nullable
The manager's explanation for an over or short at close, recorded when the difference is above the merchant's over_short_threshold_minor. Every difference has a trail. Null while the drawer is open and when the close balanced.

statusstring · enum

Required
An open session has a float and no count; a closed one has the cash that was counted against what was expected. The two are stated together so a session can never be recorded in a state nobody expects.
openclosed

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

idempotency_keyItemIdempotencyKey

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

versioninteger · int64
The version of the session this write was made from, as the server last reported it. Required to write a session the server already holds (closing it), and refused as 412 when somebody else has written it since. Omitted to open a session the server has never seen.
≥ 1
Responses

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

BatchResponse · application/json

resultsarray of BatchResult

Required

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

idempotency_keystring

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

problemProblem

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

typestring · uri

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

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

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

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

invalid_paramsarray of InvalidParam

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

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

pointerstring

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

reasonstring

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

refusalsarray of Location refusal

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

kindstring

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

countinteger

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

statusinteger

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

titlestring

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

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

statusstring · enum

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

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

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

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

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

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

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

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

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

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

503
Temporarily unable to serve the request — a dependency is down or the service is shedding load.
Retry with the same Idempotency-Key after Retry-After. This is always safe: a request that did take effect before the failure will be recognised as a replay.
Request
curl -X POST 'https://api.tenvelo.com/v1/drawer-sessions/batch-upsert' \ -H "Authorization: Bearer $TOKEN" \ -H 'Content-Type: application/json' \ -d '{ "items": [ { "drawer_session": { "id": "0192f1e4-7c3a-7b2e-9f10-5d6c7e8f9a0b", "closed_at": "2026-09-11T09:30:00Z", "closed_by_member_id": "0192f1e4-7c3a-7b2e-9f10-5d6c7e8f9a0b", "counted_cash": { "amount": 1250, "currency": "GBP" }, "device_id": "0192f1e4-7c3a-7b2e-9f10-5d6c7e8f9a0b", "device_seq": 0, "expected_cash": { "amount": 1250, "currency": "GBP" }, "float_cash": { "amount": 1250, "currency": "GBP" }, "location_id": "0192f1e4-7c3a-7b2e-9f10-5d6c7e8f9a0b", "opened_at": "2026-09-11T09:30:00Z", "opened_by_member_id": "0192f1e4-7c3a-7b2e-9f10-5d6c7e8f9a0b", "over_short_reason": "string", "status": "open" }, "hlc": "117356101632000000", "idempotency_key": "01J8ZK3QF7X2N5V9C4B1A6D8E0", "version": 1 } ] }'
Response
{ "results": [ { "id": "0192f1e4-7c3a-7b2e-9f10-5d6c7e8f9a0b", "idempotency_key": "string", "problem": { "type": "https://api.tenvelo.com/problems/version-conflict", "api_version": "2026-10-10", "detail": "The product has been modified since version 7 was read.", "instance": "/v1/products/0195f8c7-4a1e-7c3b-9f22-8d4e6a1b2c3d", "invalid_params": [ { "code": "minimum", "pointer": "/line_items/0/quantity", "reason": "must be greater than or equal to 1" } ], "refusals": [ { "kind": "devices", "count": 3 } ], "status": 412, "title": "Version conflict", "trace_id": "4bf92f3577b34da6a3ce929d0e0e4736" }, "status": "created", "version": 0 } ] }
GET/v1/drawer-sessions/{id}

Get a drawer session

No. getDrawerSessionAuth pos:drawer-sessions:read
Returns a single drawer session.
Parameters

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

200
The drawer session.

DrawerSession · application/json

idstring · uuid

Required
UUIDv7, minted by the device.

business_datestring · date

RequiredRead only
The trading day the session belongs to, in the location's time zone. Stamped by the server from when the drawer opened, the way a sale's business day is, because the till does not yet hold its location's time zone.

closed_atstring · date-time

Nullable
When the drawer was closed, or null while the session is open.

closed_by_member_idstring · uuid
The member who closed this drawer session.

counted_cashMoney

Nullable
What was actually counted in the drawer at close. The merchant's figure, entered blind so the person counting does not see what the system expects first.

amountinteger · int64

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

currencyCurrency

Required
ISO 4217 currency code.
Determines the minor unit that Money.amount is 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_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.

device_idstring · uuid

Required
The till the drawer was open on.

expected_cashMoney

Nullable
What the drawer should hold, computed by the till from the sales, refunds and cash movements it recorded in the session. Supplied at close; the server records it.

amountinteger · int64

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

currencyCurrency

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

float_cashMoney

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.

location_idstring · uuid

Required
The location the drawer belongs to.

merchant_idstring · uuid

RequiredRead only

opened_atstring · date-time

Required
When the drawer was opened, as the device saw it.

opened_by_member_idstring · uuid
The member who opened this drawer session.

over_shortMoney

NullableRead only
counted_cash - expected_cash in the session's currency. Positive is an over; a negative is a short. Derived by the server and never accepted from a device.

amountinteger · int64

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

currencyCurrency

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

over_short_reasonstring

Nullable
The manager's explanation for an over or short at close, recorded when the difference is above the merchant's over_short_threshold_minor. Every difference has a trail. Null while the drawer is open and when the close balanced.

statusstring · enum

Required
An open session has a float and no count; a closed one has the cash that was counted against what was expected. The two are stated together so a session can never be recorded in a state nobody expects.
openclosed

updated_atTimestamp

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

versionVersion

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

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

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

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

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

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

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

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

503
Temporarily unable to serve the request — a dependency is down or the service is shedding load.
Retry with the same Idempotency-Key after Retry-After. This is always safe: a request that did take effect before the failure will be recognised as a replay.
Request
curl -X GET 'https://api.tenvelo.com/v1/drawer-sessions/0192f1e4-7c3a-7b2e-9f10-5d6c7e8f9a0b' \ -H "Authorization: Bearer $TOKEN"
Response
{ "id": "0192f1e4-7c3a-7b2e-9f10-5d6c7e8f9a0b", "business_date": "2026-09-11", "closed_at": "2026-09-11T09:30:00Z", "closed_by_member_id": "0192f1e4-7c3a-7b2e-9f10-5d6c7e8f9a0b", "counted_cash": { "amount": 1250, "currency": "GBP" }, "created_at": "2026-09-08T09:41:12Z", "device_id": "0192f1e4-7c3a-7b2e-9f10-5d6c7e8f9a0b", "expected_cash": { "amount": 1250, "currency": "GBP" }, "float_cash": { "amount": 1250, "currency": "GBP" }, "location_id": "0192f1e4-7c3a-7b2e-9f10-5d6c7e8f9a0b", "merchant_id": "0192f1e4-7c3a-7b2e-9f10-5d6c7e8f9a0b", "opened_at": "2026-09-11T09:30:00Z", "opened_by_member_id": "0192f1e4-7c3a-7b2e-9f10-5d6c7e8f9a0b", "over_short": { "amount": 1250, "currency": "GBP" }, "over_short_reason": "string", "status": "open", "updated_at": "2026-09-08T09:41:12Z", "version": 7 }
GET/v1/drawer-sessions/{id}/x-read

Get a drawer session's running state

No. getDrawerSessionXReadAuth pos:drawer-sessions:read
Returns what a drawer session has taken so far, the cash movements against it, and the cash its drawer should hold, without closing it. An X-read is the running counterpart of a close: it never fixes figures and can be asked at any time, so a manager can see a session's position mid-shift — the cash that should be in the drawer and where it came from — without ending it.
Parameters

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

200
The drawer session's running state.

DrawerXRead · application/json

by_methodarray of ZReportByMethod

Required

methodstring · enum

Required
cashcardvoucheraccountpoints

paymentsinteger · int64

Required

takenMoney

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.

tipsMoney

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.

expectedMoney

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.

pay_insMoney

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.

pay_outsMoney

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.

sessionDrawerSession

Required
A period a till's cash drawer was open, from a counted float at open to a counted total at close.
Device-originated, like a shift: the till records when it opened its drawer and when it closed it against a count, offline if it has to, and the server is the record of record. The float, the cash counted at close and the expected cash are the device's view of the drawer; the server stores them as told and derives the over/short so a mismatch between counted and expected is never stored inconsistently.

idstring · uuid

Required
UUIDv7, minted by the device.

business_datestring · date

RequiredRead only
The trading day the session belongs to, in the location's time zone. Stamped by the server from when the drawer opened, the way a sale's business day is, because the till does not yet hold its location's time zone.

closed_atstring · date-time

Nullable
When the drawer was closed, or null while the session is open.

closed_by_member_idstring · uuid
The member who closed this drawer session.

counted_cashMoney

Nullable
What was actually counted in the drawer at close. The merchant's figure, entered blind so the person counting does not see what the system expects first.

amountinteger · int64

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

currencyCurrency

Required
ISO 4217 currency code.
Determines the minor unit that Money.amount is 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_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.

device_idstring · uuid

Required
The till the drawer was open on.

expected_cashMoney

Nullable
What the drawer should hold, computed by the till from the sales, refunds and cash movements it recorded in the session. Supplied at close; the server records it.

amountinteger · int64

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

currencyCurrency

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

float_cashMoney

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.

location_idstring · uuid

Required
The location the drawer belongs to.

merchant_idstring · uuid

RequiredRead only

opened_atstring · date-time

Required
When the drawer was opened, as the device saw it.

opened_by_member_idstring · uuid
The member who opened this drawer session.

over_shortMoney

NullableRead only
counted_cash - expected_cash in the session's currency. Positive is an over; a negative is a short. Derived by the server and never accepted from a device.

amountinteger · int64

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

currencyCurrency

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

over_short_reasonstring

Nullable
The manager's explanation for an over or short at close, recorded when the difference is above the merchant's over_short_threshold_minor. Every difference has a trail. Null while the drawer is open and when the close balanced.

statusstring · enum

Required
An open session has a float and no count; a closed one has the cash that was counted against what was expected. The two are stated together so a session can never be recorded in a state nobody expects.
openclosed

updated_atTimestamp

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

versionVersion

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

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

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

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

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

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

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

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

503
Temporarily unable to serve the request — a dependency is down or the service is shedding load.
Retry with the same Idempotency-Key after Retry-After. This is always safe: a request that did take effect before the failure will be recognised as a replay.
Request
curl -X GET 'https://api.tenvelo.com/v1/drawer-sessions/0192f1e4-7c3a-7b2e-9f10-5d6c7e8f9a0b/x-read' \ -H "Authorization: Bearer $TOKEN"
Response
{ "by_method": [ { "method": "cash", "payments": 0, "taken": { "amount": 1250, "currency": "GBP" }, "tips": { "amount": 1250, "currency": "GBP" } } ], "expected": { "amount": 1250, "currency": "GBP" }, "pay_ins": { "amount": 1250, "currency": "GBP" }, "pay_outs": { "amount": 1250, "currency": "GBP" }, "session": { "id": "0192f1e4-7c3a-7b2e-9f10-5d6c7e8f9a0b", "business_date": "2026-09-11", "closed_at": "2026-09-11T09:30:00Z", "closed_by_member_id": "0192f1e4-7c3a-7b2e-9f10-5d6c7e8f9a0b", "counted_cash": { "amount": 1250, "currency": "GBP" }, "created_at": "2026-09-08T09:41:12Z", "device_id": "0192f1e4-7c3a-7b2e-9f10-5d6c7e8f9a0b", "expected_cash": { "amount": 1250, "currency": "GBP" }, "float_cash": { "amount": 1250, "currency": "GBP" }, "location_id": "0192f1e4-7c3a-7b2e-9f10-5d6c7e8f9a0b", "merchant_id": "0192f1e4-7c3a-7b2e-9f10-5d6c7e8f9a0b", "opened_at": "2026-09-11T09:30:00Z", "opened_by_member_id": "0192f1e4-7c3a-7b2e-9f10-5d6c7e8f9a0b", "over_short": { "amount": 1250, "currency": "GBP" }, "over_short_reason": "string", "status": "open", "updated_at": "2026-09-08T09:41:12Z", "version": 7 } }

Parameters

Responses

Parameters

Responses

Request body application/json · DrawerSessionBatchUpsertRequest

Responses

Parameters

Responses

Parameters

Responses