Inventory · Tenvelo API

GET/v1/inventory-flags

List inventory flags

No. listInventoryFlagsAuth inventory:read
Returns the stock facts the ledger could not apply, newest first: a count or a movement naming a product the stock ledger does not track, recorded rather than refused. A flag names a product and no location, so only a person who sees the whole estate, or an integration holding inventory:read, may read them.
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 inventory flags.

InventoryFlagPage · application/json

has_moreboolean

Required

itemsarray of InventoryFlag

Required

idstring · uuid

Required

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.

product_idstring · uuid

Required

product_namestring

Required
The product's name, empty when the catalogue no longer holds it.

next_cursorstring

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

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

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

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

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

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

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

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

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

Record that an inventory flag was dealt with

No. clearInventoryFlagAuth inventory:write
Records that a person has dealt with the flag, as a fact on the stock stream — the clear is as much a fact as the flag was — and applies it at once. The row keeps its (product, fact) key, so the same fact can never raise the flag again. This is the operation the list points at. It is not doing nothing: it is the person saying the shelf's movement was handled.
Idempotent: the fact's id derives from the flag, so a retry records the same fact once, and a flag already cleared answers as clear. A device token is refused with 403 — a till may record a movement but not deal with a flag.
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/inventory-flags/0192f1e4-7c3a-7b2e-9f10-5d6c7e8f9a0b/clear' \ -H "Authorization: Bearer $TOKEN"
GET/v1/inventory-levels

List inventory levels

No. listInventoryLevelsAuth inventory:read
Returns current inventory levels per product per location.
Only products with track_inventory: true appear. Levels may be negative — an oversell is a real event a merchant needs to see, so it is reported rather than clamped to zero.
Parameters

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

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

location_idquery · string · uuid

product_idquery · string · uuid

variant_idquery · string · uuid
Only this variant's level (retail item 2, stage two). Absent means every level, product and variant.

reorder_onlyquery · boolean
Only rows at or below their reorder_point.
Responses

200
A page of inventory levels.

InventoryLevelPage · application/json

has_moreboolean

Required
Whether another page follows.

itemsarray of InventoryLevel

Required

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

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.

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.

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

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

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

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

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

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

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

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

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

503
Temporarily unable to serve the request — a dependency is down or the service is shedding load.
Retry with the same Idempotency-Key after Retry-After. This is always safe: a request that did take effect before the failure will be recognised as a replay.
Request
curl -X GET 'https://api.tenvelo.com/v1/inventory-levels' \ -H "Authorization: Bearer $TOKEN"
Response
{ "has_more": false, "items": [ { "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", "updated_at": "2026-09-08T09:41:12Z", "variant_id": "0192f1e4-7c3a-7b2e-9f10-5d6c7e8f9a0b", "version": 7 } ], "next_cursor": "string" }
POST/v1/inventory-levels/batch-upsert

Set when inventory is reordered

No. batchUpsertInventoryLevelsAuth inventory:write
Sets a level's reorder_point, the level at or below which it is low, and its reorder_level, the level a reorder brings it back up to. A setting an item leaves out is left as it is, and one sent as null is cleared. What is on the shelf is never written here: it moves only by the facts inventory/batch-create records.
Each item carries its own idempotency_key and stands or falls on its own. With version, an item is applied only while the level is still at that version, which a sale moves too.
Request body application/json · InventoryLevelBatchUpsertRequest

itemsarray of InventoryLevelBatchUpsertItem

Required
≥ 1 items · ≤ 500 items

idempotency_keyItemIdempotencyKey

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

location_idstring · uuid

Required

product_idstring · uuid

Required

reorder_levelQuantity

Nullable
The level a reorder brings this one back up to, in the product's unit_of_measure. Null clears it, and absent leaves it as it is.
≤ 26 chars · pattern ^-?(0|[1-9][0-9]*)(\.[0-9]{1,6})?$

reorder_pointQuantity

Nullable
The level at or below which this one is low, in the product's unit_of_measure. Null clears it, and absent leaves it as it is.
≤ 26 chars · pattern ^-?(0|[1-9][0-9]*)(\.[0-9]{1,6})?$

variant_idstring · uuid
The variant whose level this is. Absent means the product's own level.

versioninteger · int64
The version of the level this write was made from. When sent, the item is refused as 412 if the level has moved since.
≥ 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/inventory-levels/batch-upsert' \ -H "Authorization: Bearer $TOKEN" \ -H 'Content-Type: application/json' \ -d '{ "items": [ { "idempotency_key": "01J8ZK3QF7X2N5V9C4B1A6D8E0", "location_id": "0192f1e4-7c3a-7b2e-9f10-5d6c7e8f9a0b", "product_id": "0192f1e4-7c3a-7b2e-9f10-5d6c7e8f9a0b", "reorder_level": "3", "reorder_point": "3", "variant_id": "0192f1e4-7c3a-7b2e-9f10-5d6c7e8f9a0b", "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/inventory-movements

List a product's inventory movements

No. listInventoryMovementsAuth inventory:read
Returns the movement ledger for one product, newest first: what moved, by how much, why, and which order did it. Paged with the cursor of the previous page.
Parameters

product_idquery · string · uuid
Required

location_idquery · string · uuid

variant_idquery · string · uuid
Only movements of this variant (retail item 2, stage two). Absent means the product's whole ledger.

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

Inventory movement page · application/json

has_moreboolean

Required
Whether another page may follow.

itemsarray of Inventory movement

Required

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.

next_cursorstring

Nullable
Pass as cursor for the next page, when has_more is true.

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

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

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

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

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

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

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

503
Temporarily unable to serve the request — a dependency is down or the service is shedding load.
Retry with the same Idempotency-Key after Retry-After. This is always safe: a request that did take effect before the failure will be recognised as a replay.
Request
curl -X GET 'https://api.tenvelo.com/v1/inventory-movements?product_id=…' \ -H "Authorization: Bearer $TOKEN"
Response
{ "has_more": false, "items": [ { "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" } ], "next_cursor": "string" }
POST/v1/inventory/batch-create

Record what happened to stock

No. batchCreateInventoryFactsAuth pos:orders:write
Records facts about stock — a signed movement, a shelf count, a transfer between locations — as many as a client has queued. A fact is never edited, so this is batch-create; a correction is a fact of its own.
Asynchronous. A fact is appended to the stock log and answered received; it is applied afterwards, and what the level has become is read back from GET /v1/inventory-levels/..., the change feed, or the inventory.* webhooks. Only an item that is malformed — a type without the member it names, a fact id already used for a different fact, a reason the server derives itself — fails, and it fails in its result, not the request.
Each item carries its own idempotency_key and the fact its own id, minted by the device. Sending a fact again returns received again and records it once, so a till that cannot tell a lost request from a lost response simply resends. Facts about one product may arrive in any order, and each takes its place by when it happened, as Square's inventory does: the shelf is its latest count plus what moved after it, so a count that arrives late does not erase the sales made since, a sale synced after a count it preceded is in that count, and a count older than one already applied changes nothing (docs/decisions/0002, 0129).
Sale, refund and walk-out movements are NOT facts a client sends: they are derived from the order's own facts, and a client reporting them as well would make a second, independent record of one event.
See docs/engineering/recording-what-happened.md, "Stock is facts too".
Request body application/json · StockFactBatchCreateRequest

itemsarray of StockFact

Required
≥ 1 items · ≤ 500 items

idstring · uuid

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

typestring · enum

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

adjustedStockFactAdjusted

A signed movement of inventory, applied relative to whatever level the ledger holds when the fact is applied. Relative rather than absolute by design: two offline tills each reporting a loss from a shared shelf must subtract between them, which absolute writes cannot express. delta is added inside the projector's transaction, so concurrent facts compose correctly without any of them needing to have seen the others.
delta is in its unit_of_measure, each where none is sent.

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

notestring
≤ 512 chars

product_idstring · uuid

Required

reasonstring · enum

Required
Why it moved. A stocktake is a counted fact, a transfer a transferred fact; the sale, refund and walkout movements are the order's to derive.
deliverywastagecorrection

sub_reasonstring
A wastage movement's why, on top of the reason (spoilage, prep waste, breakage, a mistake on the line). Carried as reported; used by the waste report.
≤ 64 chars

unit_of_measurestring · enum
The unit the movement was entered in. It must measure what the product does, or the fact is flagged rather than applied. Absent means each.
eachkgglml

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

countedStockFactCounted

A shelf count of one product at one location, taken on a device. The device reports what is on the shelf, never the difference it worked out from a possibly stale level; the server keeps what was counted at counted_at, as Square keeps a physical count, so an offline notion of the shelf can never bake in and a count that arrives late keeps what sold after it was taken.
counted_quantity is in its unit_of_measure, each where none is sent, and may be a fraction of it: 1.4 bottles, 2.5 kg.

counted_atstring · date-time

Required
When the count was taken, as the device saw it. The count is applied as of this moment: every movement recorded after it is kept on the level.

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

location_idstring · uuid

Required

product_idstring · uuid

Required

unit_of_measurestring · enum
The unit the shelf was counted in. It must measure what the product does — mass, volume or a count — or the fact is flagged rather than applied. Absent means each.
eachkgglml

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

device_seqinteger · int64

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

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

member_idstring · uuid

Nullable
The staff member who did it — the roster's id, checked against the merchant's memberships when the fact is applied. Null when no person was attributed.

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

transferredStockFactTransferred

One paired movement across two locations: negative at the source, positive at the destination, applied together or neither at all.
quantity is in its unit_of_measure, each where none is sent.

from_location_idstring · uuid

Required

notestring
≤ 512 chars

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

to_location_idstring · uuid

Required

unit_of_measurestring · enum
The unit the transfer was entered in. It must measure what the product does — mass, volume or a count — or the fact is flagged rather than applied. Absent means each.
eachkgglml

variant_idstring · uuid
The variant being moved, when it is a size rather than the product itself (retail item 2, stage two). Absent means the product's own level. The same variant moves at both ends: a transfer never turns one size into another.
Responses

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

StockFactBatchResponse · application/json

resultsarray of StockFactResult

Required

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

problemProblem

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

typestring · uri

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

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

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

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

invalid_paramsarray of InvalidParam

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

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

pointerstring

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

reasonstring

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

refusalsarray of Location refusal

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

kindstring

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

countinteger

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

statusinteger

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

titlestring

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

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

statusstring · enum

Required
received — the fact is in the stock log, whether it arrived now or before: a device clears it from its queue, and learns what it made of the ledger from the inventory endpoints and the webhooks.
failed — the item was malformed and nothing was recorded. See problem: a 422 will never succeed and is a defect in the client that sent it; a 5xx is worth sending again.
receivedfailed

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/inventory/batch-create' \ -H "Authorization: Bearer $TOKEN" \ -H 'Content-Type: application/json' \ -d '{ "items": [ { "id": "0192f1e4-7c3a-7b2e-9f10-5d6c7e8f9a0b", "type": "adjusted", "adjusted": { "delta": "3", "location_id": "0192f1e4-7c3a-7b2e-9f10-5d6c7e8f9a0b", "note": "string", "product_id": "0192f1e4-7c3a-7b2e-9f10-5d6c7e8f9a0b", "reason": "delivery", "sub_reason": "string", "unit_of_measure": "each", "variant_id": "0192f1e4-7c3a-7b2e-9f10-5d6c7e8f9a0b" }, "counted": { "counted_at": "2026-09-11T09:30:00Z", "counted_quantity": "3", "location_id": "0192f1e4-7c3a-7b2e-9f10-5d6c7e8f9a0b", "product_id": "0192f1e4-7c3a-7b2e-9f10-5d6c7e8f9a0b", "unit_of_measure": "each", "variant_id": "0192f1e4-7c3a-7b2e-9f10-5d6c7e8f9a0b" }, "device_seq": 1, "hlc": "117356101632000000", "member_id": "0192f1e4-7c3a-7b2e-9f10-5d6c7e8f9a0b", "occurred_at": "2026-09-11T09:30:00Z", "transferred": { "from_location_id": "0192f1e4-7c3a-7b2e-9f10-5d6c7e8f9a0b", "note": "string", "product_id": "0192f1e4-7c3a-7b2e-9f10-5d6c7e8f9a0b", "quantity": "3", "to_location_id": "0192f1e4-7c3a-7b2e-9f10-5d6c7e8f9a0b", "unit_of_measure": "each", "variant_id": "0192f1e4-7c3a-7b2e-9f10-5d6c7e8f9a0b" } } ] }'
Response
{ "results": [ { "id": "0192f1e4-7c3a-7b2e-9f10-5d6c7e8f9a0b", "problem": { "type": "https://api.tenvelo.com/problems/version-conflict", "api_version": "2026-10-10", "detail": "The product has been modified since version 7 was read.", "instance": "/v1/products/0195f8c7-4a1e-7c3b-9f22-8d4e6a1b2c3d", "invalid_params": [ { "code": "minimum", "pointer": "/line_items/0/quantity", "reason": "must be greater than or equal to 1" } ], "refusals": [ { "kind": "devices", "count": 3 } ], "status": 412, "title": "Version conflict", "trace_id": "4bf92f3577b34da6a3ce929d0e0e4736" }, "status": "received" } ] }
GET/v1/purchase-orders

List purchase orders

No. listPurchaseOrdersAuth inventory:read
Returns the merchant's purchase orders, newest first, without lines (fetch one for its lines). Paged with the cursor of the previous page. Signed-in staff or an integration with the inventory:read scope; a device token gets a 403.
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 purchase orders.

Purchase order page · application/json

has_moreboolean

Required
Whether another page may follow.

itemsarray of PurchaseOrder

Required

idstring · uuid

Required

created_atstring · date-time

Required

linesarray of PurchaseOrderLine

Required

idstring · uuid
Client- or server-minted; a client may supply one for idempotent replays.

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

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

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.

unit_costMoney

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
The variant (a size, a strength) this line orders, when the product is sold as variants — the sellable unit retail counts and receives against (retail item 2). Absent, the line orders the product itself, which is every hospitality line. Must be a choice of the named product and of the merchant, or the write is refused.

referencestring

Required
≤ 64 chars

statusstring · enum

Required
proposed is a draft: it has been worked out but not sent to the supplier, and is still editable. Placing it (POST …/place) makes it ordered, which is what commits the business to the purchase. received is set when every line has fully arrived; an order part-delivered stays ordered with its receipts recorded against each line.
proposed was missing from this list while the back office was already creating drafts, so an order a merchant could see on their own screen was one this contract said could not exist.
proposedorderedreceived

supplier_idstring · uuid

Required

supplier_namestring
Joined on reads for display; never written.

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.

updated_atstring · date-time

Required

versioninteger · int64

Required
Bumped on every write; a change must be made from the version it was read at.

next_cursorstring

Nullable
Pass as cursor for the next page, when has_more is true.

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

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

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

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

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

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

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

503
Temporarily unable to serve the request — a dependency is down or the service is shedding load.
Retry with the same Idempotency-Key after Retry-After. This is always safe: a request that did take effect before the failure will be recognised as a replay.
Request
curl -X GET 'https://api.tenvelo.com/v1/purchase-orders' \ -H "Authorization: Bearer $TOKEN"
Response
{ "has_more": false, "items": [ { "id": "0192f1e4-7c3a-7b2e-9f10-5d6c7e8f9a0b", "created_at": "2026-09-11T09:30:00Z", "lines": [ { "id": "0192f1e4-7c3a-7b2e-9f10-5d6c7e8f9a0b", "product_id": "0192f1e4-7c3a-7b2e-9f10-5d6c7e8f9a0b", "quantity": "3", "received_quantity": "3", "total": { "amount": 1250, "currency": "GBP" }, "unit_cost": { "amount": 1250, "currency": "GBP" }, "variant_id": "0192f1e4-7c3a-7b2e-9f10-5d6c7e8f9a0b" } ], "reference": "string", "status": "proposed", "supplier_id": "0192f1e4-7c3a-7b2e-9f10-5d6c7e8f9a0b", "supplier_name": "string", "total": { "amount": 1250, "currency": "GBP" }, "updated_at": "2026-09-11T09:30:00Z", "version": 0 } ], "next_cursor": "string" }
POST/v1/purchase-orders

Place a purchase order

No. createPurchaseOrderAuth inventory:write
Records a request to a supplier for goods. Every line names a product this merchant owns and the order is scoped to the merchant; a supplier or product from another account is refused. Owner or manager, or an integration with the inventory:write scope. Not the catalogue's gate: a menu-management integration should not be able to commit the business to a purchase.
Request body application/json · PurchaseOrderCreate

idstring · uuid

Required
Minted by the caller; a retry with the same id replays instead of placing the order twice.

linesarray of PurchaseOrderLine

Required
≥ 1 items

idstring · uuid
Client- or server-minted; a client may supply one for idempotent replays.

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

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

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.

unit_costMoney

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
The variant (a size, a strength) this line orders, when the product is sold as variants — the sellable unit retail counts and receives against (retail item 2). Absent, the line orders the product itself, which is every hospitality line. Must be a choice of the named product and of the merchant, or the write is refused.

referencestring

Required
≤ 64 chars

statusstring · enum
ordered — the default — places the order with the supplier now. proposed saves a draft, which stays editable and commits nobody until it is placed.
A draft is the state a reorder proposal arrives in: a level below its reorder point suggests an order, and somebody decides whether to send it. received cannot be asked for; goods arrive through POST …/accept and nowhere else.
proposedordered
default ordered

supplier_idstring · uuid

Required
Responses

201
The purchase order, with its lines.

PurchaseOrder · application/json

idstring · uuid

Required

created_atstring · date-time

Required

linesarray of PurchaseOrderLine

Required

idstring · uuid
Client- or server-minted; a client may supply one for idempotent replays.

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

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

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.

unit_costMoney

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
The variant (a size, a strength) this line orders, when the product is sold as variants — the sellable unit retail counts and receives against (retail item 2). Absent, the line orders the product itself, which is every hospitality line. Must be a choice of the named product and of the merchant, or the write is refused.

referencestring

Required
≤ 64 chars

statusstring · enum

Required
proposed is a draft: it has been worked out but not sent to the supplier, and is still editable. Placing it (POST …/place) makes it ordered, which is what commits the business to the purchase. received is set when every line has fully arrived; an order part-delivered stays ordered with its receipts recorded against each line.
proposed was missing from this list while the back office was already creating drafts, so an order a merchant could see on their own screen was one this contract said could not exist.
proposedorderedreceived

supplier_idstring · uuid

Required

supplier_namestring
Joined on reads for display; never written.

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.

updated_atstring · date-time

Required

versioninteger · int64

Required
Bumped on every write; a change must be made from the version it was read at.

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 POST 'https://api.tenvelo.com/v1/purchase-orders' \ -H "Authorization: Bearer $TOKEN" \ -H 'Content-Type: application/json' \ -d '{ "id": "0192f1e4-7c3a-7b2e-9f10-5d6c7e8f9a0b", "lines": [ { "id": "0192f1e4-7c3a-7b2e-9f10-5d6c7e8f9a0b", "product_id": "0192f1e4-7c3a-7b2e-9f10-5d6c7e8f9a0b", "quantity": "3", "received_quantity": "3", "total": { "amount": 1250, "currency": "GBP" }, "unit_cost": { "amount": 1250, "currency": "GBP" }, "variant_id": "0192f1e4-7c3a-7b2e-9f10-5d6c7e8f9a0b" } ], "reference": "string", "status": "ordered", "supplier_id": "0192f1e4-7c3a-7b2e-9f10-5d6c7e8f9a0b" }'
Response
{ "id": "0192f1e4-7c3a-7b2e-9f10-5d6c7e8f9a0b", "created_at": "2026-09-11T09:30:00Z", "lines": [ { "id": "0192f1e4-7c3a-7b2e-9f10-5d6c7e8f9a0b", "product_id": "0192f1e4-7c3a-7b2e-9f10-5d6c7e8f9a0b", "quantity": "3", "received_quantity": "3", "total": { "amount": 1250, "currency": "GBP" }, "unit_cost": { "amount": 1250, "currency": "GBP" }, "variant_id": "0192f1e4-7c3a-7b2e-9f10-5d6c7e8f9a0b" } ], "reference": "string", "status": "proposed", "supplier_id": "0192f1e4-7c3a-7b2e-9f10-5d6c7e8f9a0b", "supplier_name": "string", "total": { "amount": 1250, "currency": "GBP" }, "updated_at": "2026-09-11T09:30:00Z", "version": 0 }
GET/v1/purchase-orders/{id}

Get a purchase order

No. getPurchaseOrderAuth inventory:read
Returns one purchase order with its lines. Signed-in staff or an integration with the inventory:read scope; a device token gets a 403 — a till never orders stock.
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 purchase order.

PurchaseOrder · application/json

idstring · uuid

Required

created_atstring · date-time

Required

linesarray of PurchaseOrderLine

Required

idstring · uuid
Client- or server-minted; a client may supply one for idempotent replays.

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

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

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.

unit_costMoney

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
The variant (a size, a strength) this line orders, when the product is sold as variants — the sellable unit retail counts and receives against (retail item 2). Absent, the line orders the product itself, which is every hospitality line. Must be a choice of the named product and of the merchant, or the write is refused.

referencestring

Required
≤ 64 chars

statusstring · enum

Required
proposed is a draft: it has been worked out but not sent to the supplier, and is still editable. Placing it (POST …/place) makes it ordered, which is what commits the business to the purchase. received is set when every line has fully arrived; an order part-delivered stays ordered with its receipts recorded against each line.
proposed was missing from this list while the back office was already creating drafts, so an order a merchant could see on their own screen was one this contract said could not exist.
proposedorderedreceived

supplier_idstring · uuid

Required

supplier_namestring
Joined on reads for display; never written.

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.

updated_atstring · date-time

Required

versioninteger · int64

Required
Bumped on every write; a change must be made from the version it was read at.

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/purchase-orders/0192f1e4-7c3a-7b2e-9f10-5d6c7e8f9a0b' \ -H "Authorization: Bearer $TOKEN"
Response
{ "id": "0192f1e4-7c3a-7b2e-9f10-5d6c7e8f9a0b", "created_at": "2026-09-11T09:30:00Z", "lines": [ { "id": "0192f1e4-7c3a-7b2e-9f10-5d6c7e8f9a0b", "product_id": "0192f1e4-7c3a-7b2e-9f10-5d6c7e8f9a0b", "quantity": "3", "received_quantity": "3", "total": { "amount": 1250, "currency": "GBP" }, "unit_cost": { "amount": 1250, "currency": "GBP" }, "variant_id": "0192f1e4-7c3a-7b2e-9f10-5d6c7e8f9a0b" } ], "reference": "string", "status": "proposed", "supplier_id": "0192f1e4-7c3a-7b2e-9f10-5d6c7e8f9a0b", "supplier_name": "string", "total": { "amount": 1250, "currency": "GBP" }, "updated_at": "2026-09-11T09:30:00Z", "version": 0 }
POST/v1/purchase-orders/{id}/accept

Receive a purchase order

No. acceptPurchaseOrderAuth inventory:write
Posts the goods: each line arriving becomes an inventory:delivery movement at the given location, and the order is marked received once every line has arrived in full — all in one transaction under the order's own row lock.
A delivery may be partial. Send receipts naming how much of each line arrived now; the order then stays ordered at a bumped version with each line's received_quantity grown, so the rest can be received when it turns up. Send no body, or no receipts, to receive everything the order still expects.
An order already fully received is refused — the order is its own idempotency key — and a stale If-Match is a 412. Owner or manager, or an integration with the inventory:write scope.
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.

location_idquery · string · uuid
Required
Request body application/json · PurchaseOrderAcceptRequest

receiptsarray of PurchaseOrderReceipt

One entry per line arriving now. A line not named is untouched.
≥ 1 items · ≤ 500 items

idstring · uuid
Client-minted, so a receive retried after a lost response records the delivery once rather than booking the stock twice. Server-minted when absent.

line_idstring · uuid

Required
The line this delivery is against.

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

200
The received purchase order.

PurchaseOrder · application/json

idstring · uuid

Required

created_atstring · date-time

Required

linesarray of PurchaseOrderLine

Required

idstring · uuid
Client- or server-minted; a client may supply one for idempotent replays.

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

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

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.

unit_costMoney

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
The variant (a size, a strength) this line orders, when the product is sold as variants — the sellable unit retail counts and receives against (retail item 2). Absent, the line orders the product itself, which is every hospitality line. Must be a choice of the named product and of the merchant, or the write is refused.

referencestring

Required
≤ 64 chars

statusstring · enum

Required
proposed is a draft: it has been worked out but not sent to the supplier, and is still editable. Placing it (POST …/place) makes it ordered, which is what commits the business to the purchase. received is set when every line has fully arrived; an order part-delivered stays ordered with its receipts recorded against each line.
proposed was missing from this list while the back office was already creating drafts, so an order a merchant could see on their own screen was one this contract said could not exist.
proposedorderedreceived

supplier_idstring · uuid

Required

supplier_namestring
Joined on reads for display; never written.

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.

updated_atstring · date-time

Required

versioninteger · int64

Required
Bumped on every write; a change must be made from the version it was read at.

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.

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/purchase-orders/0192f1e4-7c3a-7b2e-9f10-5d6c7e8f9a0b/accept?location_id=…' \ -H "Authorization: Bearer $TOKEN" \ -H 'If-Match: "3"' \ -H 'Content-Type: application/json' \ -d '{ "receipts": [ { "id": "0192f1e4-7c3a-7b2e-9f10-5d6c7e8f9a0b", "line_id": "0192f1e4-7c3a-7b2e-9f10-5d6c7e8f9a0b", "quantity": "3" } ] }'
Response
{ "id": "0192f1e4-7c3a-7b2e-9f10-5d6c7e8f9a0b", "created_at": "2026-09-11T09:30:00Z", "lines": [ { "id": "0192f1e4-7c3a-7b2e-9f10-5d6c7e8f9a0b", "product_id": "0192f1e4-7c3a-7b2e-9f10-5d6c7e8f9a0b", "quantity": "3", "received_quantity": "3", "total": { "amount": 1250, "currency": "GBP" }, "unit_cost": { "amount": 1250, "currency": "GBP" }, "variant_id": "0192f1e4-7c3a-7b2e-9f10-5d6c7e8f9a0b" } ], "reference": "string", "status": "proposed", "supplier_id": "0192f1e4-7c3a-7b2e-9f10-5d6c7e8f9a0b", "supplier_name": "string", "total": { "amount": 1250, "currency": "GBP" }, "updated_at": "2026-09-11T09:30:00Z", "version": 0 }
POST/v1/purchase-orders/{id}/close

Close receiving, marking what is still due as coming no more

No. closePurchaseOrderAuth inventory:write
Finishes receiving an ordered order: the goods that are coming are in, and whatever the order still expects is coming no more. Only at this moment is a delivery that came in short knowable, so the close records a fact naming the short value — the total of what was still due at the lines' unit costs — and the back office's Activity shows it.
Only an ordered order may be closed; one already received has nothing due, and a draft has not been committed to anyone. The fact's id derives from the order and the fact itself, so a second close is the same fact and the log keeps one — a retry never records a second shortfall. The goods themselves are untouched: what arrived arrived, and the order's status is still ordered until every line has.
Owner or manager, or an integration with the inventory:write scope. A till is refused: a till records what it sells and does not decide what a supplier owes.
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

200
The closed purchase order.

PurchaseOrder · application/json

idstring · uuid

Required

created_atstring · date-time

Required

linesarray of PurchaseOrderLine

Required

idstring · uuid
Client- or server-minted; a client may supply one for idempotent replays.

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

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

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.

unit_costMoney

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
The variant (a size, a strength) this line orders, when the product is sold as variants — the sellable unit retail counts and receives against (retail item 2). Absent, the line orders the product itself, which is every hospitality line. Must be a choice of the named product and of the merchant, or the write is refused.

referencestring

Required
≤ 64 chars

statusstring · enum

Required
proposed is a draft: it has been worked out but not sent to the supplier, and is still editable. Placing it (POST …/place) makes it ordered, which is what commits the business to the purchase. received is set when every line has fully arrived; an order part-delivered stays ordered with its receipts recorded against each line.
proposed was missing from this list while the back office was already creating drafts, so an order a merchant could see on their own screen was one this contract said could not exist.
proposedorderedreceived

supplier_idstring · uuid

Required

supplier_namestring
Joined on reads for display; never written.

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.

updated_atstring · date-time

Required

versioninteger · int64

Required
Bumped on every write; a change must be made from the version it was read at.

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.

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/purchase-orders/0192f1e4-7c3a-7b2e-9f10-5d6c7e8f9a0b/close' \ -H "Authorization: Bearer $TOKEN" \ -H 'If-Match: "3"'
Response
{ "id": "0192f1e4-7c3a-7b2e-9f10-5d6c7e8f9a0b", "created_at": "2026-09-11T09:30:00Z", "lines": [ { "id": "0192f1e4-7c3a-7b2e-9f10-5d6c7e8f9a0b", "product_id": "0192f1e4-7c3a-7b2e-9f10-5d6c7e8f9a0b", "quantity": "3", "received_quantity": "3", "total": { "amount": 1250, "currency": "GBP" }, "unit_cost": { "amount": 1250, "currency": "GBP" }, "variant_id": "0192f1e4-7c3a-7b2e-9f10-5d6c7e8f9a0b" } ], "reference": "string", "status": "proposed", "supplier_id": "0192f1e4-7c3a-7b2e-9f10-5d6c7e8f9a0b", "supplier_name": "string", "total": { "amount": 1250, "currency": "GBP" }, "updated_at": "2026-09-11T09:30:00Z", "version": 0 }
POST/v1/purchase-orders/{id}/place

Place a draft purchase order with its supplier

No. placePurchaseOrderAuth inventory:write
Approves a proposed order and makes it ordered: this is what commits the business to the purchase, and it is the only way a draft becomes one.
A draft is worked out — by a person, or by a reorder proposal from a level that has fallen below its reorder point — and stays editable until it is placed. Only a proposed order may be placed; one already ordered or received is refused, so the order is its own idempotency key and a second press cannot order the goods twice.
Owner or manager, or an integration with the inventory:write scope. A till is refused: a till records what it sells and does not commit the business to a purchase.
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

200
The placed purchase order.

PurchaseOrder · application/json

idstring · uuid

Required

created_atstring · date-time

Required

linesarray of PurchaseOrderLine

Required

idstring · uuid
Client- or server-minted; a client may supply one for idempotent replays.

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

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

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.

unit_costMoney

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
The variant (a size, a strength) this line orders, when the product is sold as variants — the sellable unit retail counts and receives against (retail item 2). Absent, the line orders the product itself, which is every hospitality line. Must be a choice of the named product and of the merchant, or the write is refused.

referencestring

Required
≤ 64 chars

statusstring · enum

Required
proposed is a draft: it has been worked out but not sent to the supplier, and is still editable. Placing it (POST …/place) makes it ordered, which is what commits the business to the purchase. received is set when every line has fully arrived; an order part-delivered stays ordered with its receipts recorded against each line.
proposed was missing from this list while the back office was already creating drafts, so an order a merchant could see on their own screen was one this contract said could not exist.
proposedorderedreceived

supplier_idstring · uuid

Required

supplier_namestring
Joined on reads for display; never written.

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.

updated_atstring · date-time

Required

versioninteger · int64

Required
Bumped on every write; a change must be made from the version it was read at.

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.

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/purchase-orders/0192f1e4-7c3a-7b2e-9f10-5d6c7e8f9a0b/place' \ -H "Authorization: Bearer $TOKEN" \ -H 'If-Match: "3"'
Response
{ "id": "0192f1e4-7c3a-7b2e-9f10-5d6c7e8f9a0b", "created_at": "2026-09-11T09:30:00Z", "lines": [ { "id": "0192f1e4-7c3a-7b2e-9f10-5d6c7e8f9a0b", "product_id": "0192f1e4-7c3a-7b2e-9f10-5d6c7e8f9a0b", "quantity": "3", "received_quantity": "3", "total": { "amount": 1250, "currency": "GBP" }, "unit_cost": { "amount": 1250, "currency": "GBP" }, "variant_id": "0192f1e4-7c3a-7b2e-9f10-5d6c7e8f9a0b" } ], "reference": "string", "status": "proposed", "supplier_id": "0192f1e4-7c3a-7b2e-9f10-5d6c7e8f9a0b", "supplier_name": "string", "total": { "amount": 1250, "currency": "GBP" }, "updated_at": "2026-09-11T09:30:00Z", "version": 0 }
GET/v1/reports/inventory-value

Get what the inventory is worth

No. getInventoryValueReportAuth inventory:read
Returns each inventory level valued at the last price paid for it, exactly, from the amount on hand in its own unit, with the total in each currency. A person scoped to locations sees theirs. A device token is refused with 403.
Responses

200
What the inventory is worth.

InventoryValueReport · application/json

itemsarray of InventoryValueItem

Required

average_costMoney

RequiredNullable
The average of the delivered unit costs, weighted by quantity. Null when none is on record.

amountinteger · int64

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

currencyCurrency

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

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

unit_costMoney

RequiredNullable
What one unit last cost delivered here, or the product's own cost when it is in the location's currency and nothing has been delivered. Null when neither is on record.

amountinteger · int64

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

currencyCurrency

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

Required
eachkgglml

valueMoney

RequiredNullable
What is on hand is worth at unit_cost. Null when no cost is on record.

amountinteger · int64

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

currencyCurrency

Required
ISO 4217 currency code.
Determines the minor unit that Money.amount is 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
The variant whose level this is. Absent means the product's own level.

totalsarray of Money

Required
What the valued stock is worth, one amount per currency: a site need not trade in the merchant's, and amounts in two currencies do not add up.

amountinteger · int64

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

currencyCurrency

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

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

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

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

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

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

500
Something failed on our side. trace_id identifies the request in our tracing — quote it in a support ticket.
The body never carries internal detail: no SQL, no stack traces, no upstream error strings. Safe to retry with the same Idempotency-Key.
Request
curl -X GET 'https://api.tenvelo.com/v1/reports/inventory-value' \ -H "Authorization: Bearer $TOKEN"
Response
{ "items": [ { "average_cost": { "amount": 1250, "currency": "GBP" }, "location_id": "0192f1e4-7c3a-7b2e-9f10-5d6c7e8f9a0b", "product_id": "0192f1e4-7c3a-7b2e-9f10-5d6c7e8f9a0b", "quantity": "3", "unit_cost": { "amount": 1250, "currency": "GBP" }, "unit_of_measure": "each", "value": { "amount": 1250, "currency": "GBP" }, "variant_id": "0192f1e4-7c3a-7b2e-9f10-5d6c7e8f9a0b" } ], "totals": [ { "amount": 1250, "currency": "GBP" } ] }
GET/v1/reports/recipe-costs

Made items' recipe cost at a site

No. getRecipeCostsReportAuth inventory:read
What one unit of each made item costs, from its recipe and the ingredients' unit costs on record at the site — never the made item's own cost field, which it does not have. A made item whose ingredients are not all priced is complete: false and carries no cost, rather than a partial figure passed off as one.
Parameters

location_idquery · string · uuid
Required
Responses

200
One row per made item, by name.

RecipeCostsReport · application/json

itemsarray of ShopCostRow

Required

namestring

Required

completeboolean

Required

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.

linesarray of ShopCostLine

Required

currencystring
The currency every minor amount in this report is in (the site's).

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

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

unit_of_measurestring · enum
The unit quantity is in, the ingredient's own. Absent means each.
eachkgglml

product_idstring · uuid

Required

unitstring · enum

Required
The unit one unit of the made item is sold in.
eachkgglml

location_idstring · uuid

Required

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

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

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

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

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

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

500
Something failed on our side. trace_id identifies the request in our tracing — quote it in a support ticket.
The body never carries internal detail: no SQL, no stack traces, no upstream error strings. Safe to retry with the same Idempotency-Key.
Request
curl -X GET 'https://api.tenvelo.com/v1/reports/recipe-costs?location_id=…' \ -H "Authorization: Bearer $TOKEN"
Response
{ "items": [ { "name": "string", "complete": false, "cost": { "amount": 1250, "currency": "GBP" }, "lines": [ { "currency": "string", "product_id": "0192f1e4-7c3a-7b2e-9f10-5d6c7e8f9a0b", "quantity": "3", "unit_cost": { "amount": 1250, "currency": "GBP" }, "unit_of_measure": "each" } ], "product_id": "0192f1e4-7c3a-7b2e-9f10-5d6c7e8f9a0b", "unit": "each" } ], "location_id": "0192f1e4-7c3a-7b2e-9f10-5d6c7e8f9a0b" }
GET/v1/reports/reorder

Get what to reorder

No. getReorderReportAuth inventory:read
Returns each inventory level below its reorder_level, with how much to order to bring it back up, grouped by supplier and location into what one purchase order would carry. Beside each line are what sales of it took over the last 30 days and its cost at the last price paid. A person scoped to locations sees theirs. A device token is refused with 403.
Responses

200
What to reorder.

ReorderReport · application/json

groupsarray of ReorderGroup

Required

costMoney

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.

currencyCurrency

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

linesarray of ReorderLine

Required

costMoney

RequiredNullable
What quantity costs at unit_cost. Null when no cost is on record.

amountinteger · int64

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

currencyCurrency

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

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

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

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

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

unit_costMoney

RequiredNullable
What one unit cost when it was last delivered here. Null when no cost is on record.

amountinteger · int64

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

currencyCurrency

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

Required
eachkgglml

variant_idstring · uuid
The variant whose level this is. Absent means the product's own level.

location_idstring · uuid

Required

supplier_idstring · uuid

RequiredNullable
Who the products are bought from. Null for products with no supplier on record.

sincestring · date-time

Required
The start of the window whose sales are shown beside each line.

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

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

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

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

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

500
Something failed on our side. trace_id identifies the request in our tracing — quote it in a support ticket.
The body never carries internal detail: no SQL, no stack traces, no upstream error strings. Safe to retry with the same Idempotency-Key.
Request
curl -X GET 'https://api.tenvelo.com/v1/reports/reorder' \ -H "Authorization: Bearer $TOKEN"
Response
{ "groups": [ { "cost": { "amount": 1250, "currency": "GBP" }, "currency": "AED", "lines": [ { "cost": { "amount": 1250, "currency": "GBP" }, "location_id": "0192f1e4-7c3a-7b2e-9f10-5d6c7e8f9a0b", "on_hand_quantity": "3", "product_id": "0192f1e4-7c3a-7b2e-9f10-5d6c7e8f9a0b", "quantity": "3", "reorder_level": "3", "sold_quantity": "3", "unit_cost": { "amount": 1250, "currency": "GBP" }, "unit_of_measure": "each", "variant_id": "0192f1e4-7c3a-7b2e-9f10-5d6c7e8f9a0b" } ], "location_id": "0192f1e4-7c3a-7b2e-9f10-5d6c7e8f9a0b", "supplier_id": "0192f1e4-7c3a-7b2e-9f10-5d6c7e8f9a0b" } ], "since": "2026-09-11T09:30:00Z" }
GET/v1/reports/supplier-prices

Get what suppliers have charged, delivery by delivery

No. getSupplierPriceReportAuth inventory:read
Returns the unit cost of every delivered purchase-order line, newest first, with the product and supplier it was for.
A history rather than a current price per product. What a supplier charges moves, and a single number would show today's and hide the change — which is the whole reason a merchant looks: an invoice to check, or a cost that has crept up between deliveries.
Responses

200
The supplier price history.

SupplierPriceReport · application/json

itemsarray of SupplierPrice

Required

alertboolean

Required
Whether change is at or beyond the merchant's price-spike threshold, measured against the previous delivery. False on the first delivery, and when no threshold is set.

changeMoney

What the unit cost moved by since this supplier's previous delivery of this product: positive for a rise, negative for a fall, zero for no change. Absent on the first delivery, which has nothing to compare against — and absent is not zero, because a first delivery reported as "no change" is a price nobody was told had been set.
Derived here rather than by each reader. It is money arithmetic, so it belongs to the layer that owns the noun (docs/decisions/0055), and a rise is exactly the figure a merchant, a CSV export and an integration must all agree about.

amountinteger · int64

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

currencyCurrency

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

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

product_idstring · uuid

Required

product_namestring

Required
The product's name as it stands now, for display.

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

supplier_idstring · uuid

Required

supplier_namestring

Required
The supplier's name as it stands now, for display.

unit_costMoney

Required
What one purchase unit cost on this delivery.

amountinteger · int64

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

currencyCurrency

Required
ISO 4217 currency code.
Determines the minor unit that Money.amount is 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
The variant delivered, when it was a size rather than the product itself.

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/reports/supplier-prices' \ -H "Authorization: Bearer $TOKEN"
Response
{ "items": [ { "alert": false, "change": { "amount": 1250, "currency": "GBP" }, "delivered_at": "2026-09-08T09:41:12Z", "product_id": "0192f1e4-7c3a-7b2e-9f10-5d6c7e8f9a0b", "product_name": "string", "quantity": "3", "supplier_id": "0192f1e4-7c3a-7b2e-9f10-5d6c7e8f9a0b", "supplier_name": "string", "unit_cost": { "amount": 1250, "currency": "GBP" }, "variant_id": "0192f1e4-7c3a-7b2e-9f10-5d6c7e8f9a0b" } ] }
GET/v1/reports/variance

Get a site's stock variance over a period

No. getVarianceReportAuth inventory:read
What one site's shelf did over a period, per product that moved: the theoretical usage recipes say the sales consumed, against what the ledger records as thrown away or transferred, and what a count found that none of those explain. A count is the only voice the shelf itself has, so a period with no count in it reports a ledger-only arithmetic; a product with no cost on record values nothing rather than guessing. The period is a closed range of business dates: from and to are dates, inclusive; business_date is the single-day form. A device token is refused with 403.
Parameters

location_idquery · string · uuid
Required

fromquery · string · date
The first business day of the range, inclusive.

toquery · string · date
The last business day of the range, inclusive.

business_datequery · string · date
A single business day to report on.
Responses

200
The variance report.

VarianceReport · application/json

itemsarray of VarianceItem

Required

namestring

Required

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

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

product_idstring · uuid

Required

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

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

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

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

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

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

unitstring · enum

Required
The unit every base quantity in this row is counted in.
eachkgglml

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

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

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

location_idstring · uuid

Required

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

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

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

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

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

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

500
Something failed on our side. trace_id identifies the request in our tracing — quote it in a support ticket.
The body never carries internal detail: no SQL, no stack traces, no upstream error strings. Safe to retry with the same Idempotency-Key.
Request
curl -X GET 'https://api.tenvelo.com/v1/reports/variance?location_id=…' \ -H "Authorization: Bearer $TOKEN"
Response
{ "items": [ { "name": "string", "closing_quantity": "3", "opening_quantity": "3", "product_id": "0192f1e4-7c3a-7b2e-9f10-5d6c7e8f9a0b", "received_quantity": "3", "sold_cost": { "amount": 1250, "currency": "GBP" }, "sold_quantity": "3", "transferred_quantity": "3", "unexplained_cost": { "amount": 1250, "currency": "GBP" }, "unexplained_quantity": "3", "unit": "each", "unit_cost": { "amount": 1250, "currency": "GBP" }, "walkout_quantity": "3", "wastage_quantity": "3" } ], "location_id": "0192f1e4-7c3a-7b2e-9f10-5d6c7e8f9a0b" }

Parameters

Responses

Parameters

Responses

Parameters

Responses

Request body application/json · InventoryLevelBatchUpsertRequest

Responses

Parameters

Responses

Request body application/json · StockFactBatchCreateRequest

Responses

Parameters

Responses

Request body application/json · PurchaseOrderCreate

Responses

Parameters

Responses

Parameters

Request body application/json · PurchaseOrderAcceptRequest

Responses

Parameters

Responses

Parameters

Responses

Responses

Parameters

Responses

Responses

Responses

Parameters

Responses