Customers · Tenvelo API

GET/v1/campaigns

List the campaigns

No. listCampaignsAuth customers:read

The business's campaigns, newest first, each with what the send reached and what became of the deliveries. An owner or a manager; an integration with customers:read. Paged with the cursor of the previous page.

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 campaigns.
CampaignPage · application/json
- has_moreboolean
  
  Required
  Whether another page may follow.
- itemsarray of Campaign
  
  Required
  - idstring · uuid
    
    Required
  - namestring
    
    Required
    What the merchant calls it, seen on the list.
    1–120 chars
  - bodystring
    
    Required
    The message, in the merchant's words.
    1–5000 chars
  - 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.
  - recipientsinteger · int64
    
    Required
    How many guests the send reached and asked for a delivery to.
  - refusedinteger · int64
    
    Required
    How many were refused — a permanent suppression, or an address that could not be reached.
  - segment_idstring · uuid
    
    RequiredNullable
    The saved segment whose guests are the audience, or null for every guest who has consented to marketing and has an email.
  - sentinteger · int64
    
    Required
    How many of them were delivered.
  - sent_atTimestamp
    
    Nullable
    When the send was asked for, or null while it is still a draft.
  - statusstring · enum
    
    Required
    draft — still being written.
    sending — the send happened; deliveries are going out.
    sent — every delivery the send asked for has gone or been refused. Derived: a send whose deliveries are still arriving shows sending until the counts settle.
    draftsendingsent
  - subjectstring
    
    Required
    The subject line a guest sees.
    1–200 chars
  - updated_atTimestamp
    
    RequiredRead only
    Server-assigned RFC 3339 timestamp, always UTC.
    Server-assigned because device clocks drift and cannot be trusted for ordering — a till that has been powered off for a week may come back with a clock hours out. Where the device's own view of time matters it is carried separately in client_created_at.
  - versionVersion
    
    RequiredRead only
    Optimistic concurrency version, raised by the server on every write. A version is never lower than one already returned for the resource, though it may rise by more than one.
    Returned in the ETag response header as well as in the body. Send it back in If-Match on an update and the write is rejected with 412 if anyone else has written since — which is what stops two tills silently overwriting each other's edit to the same product when both come back online at once.
    ≥ 1
- 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.

Request

curl -X GET 'https://api.tenvelo.com/v1/campaigns' \
  -H "Authorization: Bearer $TOKEN"

Response

{
  "has_more": false,
  "items": [
    {
      "id": "0192f1e4-7c3a-7b2e-9f10-5d6c7e8f9a0b",
      "name": "string",
      "body": "string",
      "created_at": "2026-09-08T09:41:12Z",
      "recipients": 0,
      "refused": 0,
      "segment_id": "0192f1e4-7c3a-7b2e-9f10-5d6c7e8f9a0b",
      "sent": 0,
      "sent_at": "2026-09-08T09:41:12Z",
      "status": "draft",
      "subject": "string",
      "updated_at": "2026-09-08T09:41:12Z",
      "version": 7
    }
  ],
  "next_cursor": "string"
}

POST/v1/campaigns/batch-upsert

Save campaigns

No. batchUpsertCampaignsAuth customers:write

Saves campaigns under the ids the caller minted: a draft is written new or saved over the version read, and one already sent is refused. The send is separate — this is only the words and the audience. An owner or a manager; an integration with customers:write.

Request body application/json · CampaignBatchUpsertRequest

itemsarray of CampaignBatchUpsertItem

Required
≥ 1 items · ≤ 100 items
- idstring · uuid
  
  Required
- namestring
  
  Required
  1–120 chars
- bodystring
  
  Required
  1–5000 chars
- 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
- segment_idstring · uuid
  
  RequiredNullable
- subjectstring
  
  Required
  1–200 chars

Responses

200
The batch was processed. results says what happened to each item.
BatchResponse · application/json
- resultsarray of BatchResult
  
  Required
  - idstring · uuid
    The resource the item created or changed. Absent when it failed.
  - idempotency_keystring
    
    Required
    The item's key, echoed so a result can be matched by key as well as position.
  - problemProblem
    
    Nullable
    Why the item failed, as an RFC 9457 problem. A 422 means the item is malformed and will never succeed — drop it and show it to staff rather than retrying for ever. A 409 or a 5xx means try again later.
    
    typestring · uri
    
    Required
    A stable URI identifying the problem kind. This is the field to branch on.
    default about:blank
    
    api_versionstring
    Present on an api-version-retired or api-version-unknown refusal: the API-Version this server speaks (docs/decisions/0011).
    
    detailstring
    A human-readable explanation specific to this occurrence. Safe to show to a developer; never contains internal state, SQL, or stack traces.
    
    instancestring · uri-reference
    A URI reference identifying the specific occurrence.
    
    invalid_paramsarray of InvalidParam
    
    Present on 422 responses. Lists every field that failed validation, rather than only the first, so a client can highlight an entire form in one pass.
    
    codestring
    Stable machine-readable code for this failure, for clients that localise their own messages rather than showing reason.
    
    pointerstring
    
    Required
    RFC 6901 JSON Pointer to the offending value within the request body. A pointer rather than a field name so that failures nested inside arrays — the third line item of an order — are addressable at all.
    
    reasonstring
    
    Required
    Why this value was rejected, in human-readable form.
    
    refusalsarray of Location refusal
    
    Present on 409 responses to a withdrawal refused by the state it depends on (deleting a location with tills still assigned, open orders, …). Lists every reason at once, each with how much stands in the way, so a client can say what to put right and link to it rather than walking a person through one refusal after another.
    
    kindstring
    
    Required
    A stable refusal kind — devices, open_orders, drawer_sessions, bookings or stock — that a client links to the screen that puts it right. Branch on this field, never on the surrounding prose.
    
    countinteger
    
    Required
    How many things stand in the way of the withdrawal, so a client can repeat the number rather than re-read prose.
    ≥ 1
    
    statusinteger
    
    Required
    The HTTP status code, repeated here so the body is self-contained.
    100–599
    
    titlestring
    
    Required
    A short, human-readable summary of the problem kind.
    
    trace_idstring
    The OpenTelemetry trace id for this request. Quote it in a support ticket and the whole request can be pulled up.
  - statusstring · enum
    
    Required
    created — the item made a new resource. updated — it changed an existing one.
    unchanged — this key was already applied and the original outcome stands. A success, not an error: it is what a client retrying a batch it was unsure landed should expect, and it clears the item from its queue exactly as created does.
    failed — the item was refused, and nothing else in the batch was affected. See problem.
    createdupdatedunchangedfailed
  - versioninteger · int64
    The resource's version after the item. Absent when it failed.
400
The request could not be parsed. Malformed JSON, a bad query parameter, or a header that failed to decode, among them an API-Version later than the server speaks or not a date (api-version-unknown, with the server's own in api_version).
Distinct from 422: a 400 never reached validation, so invalid_params is absent. Retrying without changing the request will fail again, except that a request refused for its API-Version goes once the server is updated.
401
No credentials, or credentials that could not be verified — missing bearer token, malformed JWT, expired token, or a signature that failed against the issuer's JWKS.
Refresh the token and retry once. Repeated 401 after a refresh means the device needs to re-enrol.
403
Authenticated, but not permitted. The token is valid and its merchant was resolved, but the caller's role does not allow this operation, or the target belongs to a different merchant.
Cross-tenant access is reported as 403 on a resource the caller may not see, and as 404 where even confirming existence would leak information. Retrying will not help.
410
The request names an API-Version this server no longer serves (docs/decisions/0011). Nothing in it was read. api_version names the version the server speaks: the client is behind, and sends the request again once it is updated.
415
The request Content-Type is not supported. This API accepts application/json on all mutations.
422
The request parsed but failed validation.
invalid_params lists every failing field with a JSON Pointer, not just the first, so a client can mark up a whole form in one pass rather than making the user fix errors one round trip at a time.
Also returned when an Idempotency-Key is replayed with a different body, and when device-computed order totals disagree with the server's recomputation.
429
Rate limit exceeded. Honour Retry-After rather than applying your own backoff.
A fleet of tills coming back online together after an outage is the realistic cause, which is exactly when uncoordinated client-side retry turns a brief outage into a sustained one. The limit is per process, and per site for what records trade there — a request spends its site's budget, and a till's own smaller one inside it — and per (client, merchant) for everything else; no RateLimit field is sent, so this response and its Retry-After are the whole of the contract.
500
Something failed on our side. trace_id identifies the request in our tracing — quote it in a support ticket.
The body never carries internal detail: no SQL, no stack traces, no upstream error strings. Safe to retry with the same Idempotency-Key.

Request

curl -X POST 'https://api.tenvelo.com/v1/campaigns/batch-upsert' \
  -H "Authorization: Bearer $TOKEN" \
  -H 'Content-Type: application/json' \
  -d '{
  "items": [
    {
      "id": "0192f1e4-7c3a-7b2e-9f10-5d6c7e8f9a0b",
      "name": "string",
      "body": "string",
      "idempotency_key": "01J8ZK3QF7X2N5V9C4B1A6D8E0",
      "segment_id": "0192f1e4-7c3a-7b2e-9f10-5d6c7e8f9a0b",
      "subject": "string"
    }
  ]
}'

Response

{
  "results": [
    {
      "id": "0192f1e4-7c3a-7b2e-9f10-5d6c7e8f9a0b",
      "idempotency_key": "string",
      "problem": {
        "type": "https://api.tenvelo.com/problems/version-conflict",
        "api_version": "2026-10-10",
        "detail": "The product has been modified since version 7 was read.",
        "instance": "/v1/products/0195f8c7-4a1e-7c3b-9f22-8d4e6a1b2c3d",
        "invalid_params": [
          {
            "code": "minimum",
            "pointer": "/line_items/0/quantity",
            "reason": "must be greater than or equal to 1"
          }
        ],
        "refusals": [
          {
            "kind": "devices",
            "count": 3
          }
        ],
        "status": 412,
        "title": "Version conflict",
        "trace_id": "4bf92f3577b34da6a3ce929d0e0e4736"
      },
      "status": "created",
      "version": 0
    }
  ]
}

POST/v1/campaigns/{id}

Send a campaign

No. sendCampaignAuth customers:write

Sends the draft once: the audience is resolved and held, and a delivery is asked for each guest it reached. A send that reaches nobody it may tell, or a merchant over its marketing allowance, is refused. The send is not undone, so make sure of the words. An owner or a manager; an integration with customers:write.

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

Responses

200
The campaign, now sending.
Campaign · application/json
- idstring · uuid
  
  Required
- namestring
  
  Required
  What the merchant calls it, seen on the list.
  1–120 chars
- bodystring
  
  Required
  The message, in the merchant's words.
  1–5000 chars
- 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.
- recipientsinteger · int64
  
  Required
  How many guests the send reached and asked for a delivery to.
- refusedinteger · int64
  
  Required
  How many were refused — a permanent suppression, or an address that could not be reached.
- segment_idstring · uuid
  
  RequiredNullable
  The saved segment whose guests are the audience, or null for every guest who has consented to marketing and has an email.
- sentinteger · int64
  
  Required
  How many of them were delivered.
- sent_atTimestamp
  
  Nullable
  When the send was asked for, or null while it is still a draft.
- statusstring · enum
  
  Required
  draft — still being written.
  sending — the send happened; deliveries are going out.
  sent — every delivery the send asked for has gone or been refused. Derived: a send whose deliveries are still arriving shows sending until the counts settle.
  draftsendingsent
- subjectstring
  
  Required
  The subject line a guest sees.
  1–200 chars
- updated_atTimestamp
  
  RequiredRead only
  Server-assigned RFC 3339 timestamp, always UTC.
  Server-assigned because device clocks drift and cannot be trusted for ordering — a till that has been powered off for a week may come back with a clock hours out. Where the device's own view of time matters it is carried separately in client_created_at.
- versionVersion
  
  RequiredRead only
  Optimistic concurrency version, raised by the server on every write. A version is never lower than one already returned for the resource, though it may rise by more than one.
  Returned in the ETag response header as well as in the body. Send it back in If-Match on an update and the write is rejected with 412 if anyone else has written since — which is what stops two tills silently overwriting each other's edit to the same product when both come back online at once.
  ≥ 1
400
The request could not be parsed. Malformed JSON, a bad query parameter, or a header that failed to decode, among them an API-Version later than the server speaks or not a date (api-version-unknown, with the server's own in api_version).
Distinct from 422: a 400 never reached validation, so invalid_params is absent. Retrying without changing the request will fail again, except that a request refused for its API-Version goes once the server is updated.
401
No credentials, or credentials that could not be verified — missing bearer token, malformed JWT, expired token, or a signature that failed against the issuer's JWKS.
Refresh the token and retry once. Repeated 401 after a refresh means the device needs to re-enrol.
403
Authenticated, but not permitted. The token is valid and its merchant was resolved, but the caller's role does not allow this operation, or the target belongs to a different merchant.
Cross-tenant access is reported as 403 on a resource the caller may not see, and as 404 where even confirming existence would leak information. Retrying will not help.
404
No such resource, or none visible to this caller.
Also returned instead of 403 where acknowledging existence would itself leak information — so a 404 does not prove the id is unused globally, only that it is not yours.
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.
422
The request parsed but failed validation.
invalid_params lists every failing field with a JSON Pointer, not just the first, so a client can mark up a whole form in one pass rather than making the user fix errors one round trip at a time.
Also returned when an Idempotency-Key is replayed with a different body, and when device-computed order totals disagree with the server's recomputation.
429
Rate limit exceeded. Honour Retry-After rather than applying your own backoff.
A fleet of tills coming back online together after an outage is the realistic cause, which is exactly when uncoordinated client-side retry turns a brief outage into a sustained one. The limit is per process, and per site for what records trade there — a request spends its site's budget, and a till's own smaller one inside it — and per (client, merchant) for everything else; no RateLimit field is sent, so this response and its Retry-After are the whole of the contract.
500
Something failed on our side. trace_id identifies the request in our tracing — quote it in a support ticket.
The body never carries internal detail: no SQL, no stack traces, no upstream error strings. Safe to retry with the same Idempotency-Key.

Request

curl -X POST 'https://api.tenvelo.com/v1/campaigns/0192f1e4-7c3a-7b2e-9f10-5d6c7e8f9a0b' \
  -H "Authorization: Bearer $TOKEN" \
  -H 'If-Match: "3"' \
  -H 'Idempotency-Key: 01J8ZK3QF7X2N5V9C4B1A6D8E0'

Response

{
  "id": "0192f1e4-7c3a-7b2e-9f10-5d6c7e8f9a0b",
  "name": "string",
  "body": "string",
  "created_at": "2026-09-08T09:41:12Z",
  "recipients": 0,
  "refused": 0,
  "segment_id": "0192f1e4-7c3a-7b2e-9f10-5d6c7e8f9a0b",
  "sent": 0,
  "sent_at": "2026-09-08T09:41:12Z",
  "status": "draft",
  "subject": "string",
  "updated_at": "2026-09-08T09:41:12Z",
  "version": 7
}

DELETE/v1/campaigns/{id}

Delete a draft campaign

No. deleteCampaignAuth customers:write

Takes a draft off; one already sent is refused, because its deliveries are the record. The guests it would have reached are untouched. An owner or a manager.

Parameters

idpath · string · uuid
Required
UUIDv7 of the resource.
For resources a device can originate — orders, and their line items — this id is minted by the client before the record is ever synced, which is what makes an offline create idempotent.
If-Matchheader · string
Required
The ETag from the read that produced the value you are updating.
Required on updates, not optional, because "last write wins" is the wrong default for a catalogue two managers might edit at once. If anything has been written since your read, the request is rejected with 412 and you re-read and re-apply.
Use * to mean "write regardless of current version" — an explicit, greppable override rather than the silent default.

Responses

204
The draft is deleted.
400
The request could not be parsed. Malformed JSON, a bad query parameter, or a header that failed to decode, among them an API-Version later than the server speaks or not a date (api-version-unknown, with the server's own in api_version).
Distinct from 422: a 400 never reached validation, so invalid_params is absent. Retrying without changing the request will fail again, except that a request refused for its API-Version goes once the server is updated.
401
No credentials, or credentials that could not be verified — missing bearer token, malformed JWT, expired token, or a signature that failed against the issuer's JWKS.
Refresh the token and retry once. Repeated 401 after a refresh means the device needs to re-enrol.
403
Authenticated, but not permitted. The token is valid and its merchant was resolved, but the caller's role does not allow this operation, or the target belongs to a different merchant.
Cross-tenant access is reported as 403 on a resource the caller may not see, and as 404 where even confirming existence would leak information. Retrying will not help.
404
No such resource, or none visible to this caller.
Also returned instead of 403 where acknowledging existence would itself leak information — so a 404 does not prove the id is unused globally, only that it is not yours.
410
The request names an API-Version this server no longer serves (docs/decisions/0011). Nothing in it was read. api_version names the version the server speaks: the client is behind, and sends the request again once it is updated.
412
The If-Match version did not match the resource's current version: someone else wrote since you read.
This is the expected, healthy outcome of two clients editing the same record — not an error condition to suppress. Re-read the resource, re-apply your change on top of the new state, and retry with the fresh ETag.
429
Rate limit exceeded. Honour Retry-After rather than applying your own backoff.
A fleet of tills coming back online together after an outage is the realistic cause, which is exactly when uncoordinated client-side retry turns a brief outage into a sustained one. The limit is per process, and per site for what records trade there — a request spends its site's budget, and a till's own smaller one inside it — and per (client, merchant) for everything else; no RateLimit field is sent, so this response and its Retry-After are the whole of the contract.
500
Something failed on our side. trace_id identifies the request in our tracing — quote it in a support ticket.
The body never carries internal detail: no SQL, no stack traces, no upstream error strings. Safe to retry with the same Idempotency-Key.

GET/v1/campaigns/{id}/audience

How many guests a campaign would reach

No. getCampaignAudienceAuth customers:read

Returns how many guests a send of this draft would reach, with the same criteria and consent rule the send itself applies. This is the number shown before a manager presses send: the audience is resolved when send is asked for, and this lets them see that audience first rather than learning what it was after the mail went out.

A campaign that is not a draft is refused with 409: an audience preview is for a send not yet made, and a campaign already sent has that number recorded in what it reached.

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 audience a send would reach.
CampaignAudience · application/json
- countinteger · int64
  
  Required
  How many guests the campaign would reach. Only guests who have said yes to marketing and who match the campaign's segment — or, with none, every consenting guest — count.
  ≥ 0
400
The request could not be parsed. Malformed JSON, a bad query parameter, or a header that failed to decode, among them an API-Version later than the server speaks or not a date (api-version-unknown, with the server's own in api_version).
Distinct from 422: a 400 never reached validation, so invalid_params is absent. Retrying without changing the request will fail again, except that a request refused for its API-Version goes once the server is updated.
401
No credentials, or credentials that could not be verified — missing bearer token, malformed JWT, expired token, or a signature that failed against the issuer's JWKS.
Refresh the token and retry once. Repeated 401 after a refresh means the device needs to re-enrol.
403
Authenticated, but not permitted. The token is valid and its merchant was resolved, but the caller's role does not allow this operation, or the target belongs to a different merchant.
Cross-tenant access is reported as 403 on a resource the caller may not see, and as 404 where even confirming existence would leak information. Retrying will not help.
404
No such resource, or none visible to this caller.
Also returned instead of 403 where acknowledging existence would itself leak information — so a 404 does not prove the id is unused globally, only that it is not yours.
409
The request conflicts with current state — a uniqueness constraint, or an attempt to mutate an order that is already completed or voided.
Unlike 412, re-reading and retrying unchanged will not resolve it; the request itself has to change.
410
The request names an API-Version this server no longer serves (docs/decisions/0011). Nothing in it was read. api_version names the version the server speaks: the client is behind, and sends the request again once it is updated.
429
Rate limit exceeded. Honour Retry-After rather than applying your own backoff.
A fleet of tills coming back online together after an outage is the realistic cause, which is exactly when uncoordinated client-side retry turns a brief outage into a sustained one. The limit is per process, and per site for what records trade there — a request spends its site's budget, and a till's own smaller one inside it — and per (client, merchant) for everything else; no RateLimit field is sent, so this response and its Retry-After are the whole of the contract.
500
Something failed on our side. trace_id identifies the request in our tracing — quote it in a support ticket.
The body never carries internal detail: no SQL, no stack traces, no upstream error strings. Safe to retry with the same Idempotency-Key.

GET/v1/card-recognition

What this card is to this merchant, pseudonymously

No. getCardRecognitionAuth customers:read

Answers "who (if anyone) is this card, and how often has it been here" for the cold-read recognition on a card nobody has introduced (docs/product/merchant/guest-record.md item 17). The response carries a merchant-scoped visit count and, when somebody has linked the card, the guest id it belongs to — never a name, a contact detail or a spend. An unlinked card is not a person and is never returned as one; a card never confirmed on a completed sale here answers 404, which is how a till knows it is meeting the card for the first time.

The count is confirmed card payments on completed sales only, derived over the ledger on read — never stored — so an unconfirmed checkout's fingerprint (which may belong to a card that did not pay the sale) cannot inflate it. The fingerprint is a query parameter rather than a path segment, for the same reason as GET /v1/customer-cards: it identifies a payment instrument and the request log records url.path.

Parameters

fingerprintquery · string
Required
The processor's fingerprint for the card, compared for equality.

Responses

200
The recognition record: visits, and the guest the card is linked to, if any.
CardRecognition · application/json
- customer_idstring · uuid
  
  Read only
  The guest this card has been linked to, when somebody has introduced it. Absent for a card nobody has linked — the count is what the till may say, and a name is never invented.
- fingerprintstring
  
  RequiredRead only
  The card alias this record answers for.
- visitsinteger · int64
  
  RequiredRead only
  Completed sales this card fingerprint has been confirmed on, derived over the ledger on read. Zero is a card confirmed on no completed sale yet.
400
The request could not be parsed. Malformed JSON, a bad query parameter, or a header that failed to decode, among them an API-Version later than the server speaks or not a date (api-version-unknown, with the server's own in api_version).
Distinct from 422: a 400 never reached validation, so invalid_params is absent. Retrying without changing the request will fail again, except that a request refused for its API-Version goes once the server is updated.
401
No credentials, or credentials that could not be verified — missing bearer token, malformed JWT, expired token, or a signature that failed against the issuer's JWKS.
Refresh the token and retry once. Repeated 401 after a refresh means the device needs to re-enrol.
403
Authenticated, but not permitted. The token is valid and its merchant was resolved, but the caller's role does not allow this operation, or the target belongs to a different merchant.
Cross-tenant access is reported as 403 on a resource the caller may not see, and as 404 where even confirming existence would leak information. Retrying will not help.
404
No such resource, or none visible to this caller.
Also returned instead of 403 where acknowledging existence would itself leak information — so a 404 does not prove the id is unused globally, only that it is not yours.
410
The request names an API-Version this server no longer serves (docs/decisions/0011). Nothing in it was read. api_version names the version the server speaks: the client is behind, and sends the request again once it is updated.
429
Rate limit exceeded. Honour Retry-After rather than applying your own backoff.
A fleet of tills coming back online together after an outage is the realistic cause, which is exactly when uncoordinated client-side retry turns a brief outage into a sustained one. The limit is per process, and per site for what records trade there — a request spends its site's budget, and a till's own smaller one inside it — and per (client, merchant) for everything else; no RateLimit field is sent, so this response and its Retry-After are the whole of the contract.
500
Something failed on our side. trace_id identifies the request in our tracing — quote it in a support ticket.
The body never carries internal detail: no SQL, no stack traces, no upstream error strings. Safe to retry with the same Idempotency-Key.

Request

curl -X GET 'https://api.tenvelo.com/v1/card-recognition?fingerprint=…' \
  -H "Authorization: Bearer $TOKEN"

Response

{
  "customer_id": "0192f1e4-7c3a-7b2e-9f10-5d6c7e8f9a0b",
  "fingerprint": "string",
  "visits": 0
}

GET/v1/customer-accounts

List the merchant's customer accounts

No. listCustomerAccountsAuth pos:orders:write

Returns the customer accounts a merchant has opened, with what each is owed, newest is not the order — the directory is by the customer's name, like the guest book, so a counter can find a payer. A search term matches the customer's name or phone; the till calls this the same way when an operator chooses an account to charge.

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.
qquery · string
Match the customer's name or phone, case-insensitively.

Responses

200
A page of customer accounts.
CustomerAccountPage · application/json
- has_moreboolean
  
  Required
- itemsarray of CustomerAccount
  
  Required
  - idstring · uuid
    
    Required
    The account's id.
  - balanceMoney
    
    What the account is still owed, in its most recent charge's currency. Absent when the account has never been charged.
    
    amountinteger · int64
    
    Required
    The amount, as a whole number of the currency's minor unit. May be negative to express a refund, discount or credit.
    
    currencyCurrency
    
    Required
    ISO 4217 currency code.
    Determines the minor unit that Money.amount is 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
  - credit_limitMoney
    
    Nullable
    The most the account may be owed before a charge is refused, in the account's trading currency. Absent is no limit.
    
    amountinteger · int64
    
    Required
    The amount, as a whole number of the currency's minor unit. May be negative to express a refund, discount or credit.
    
    currencyCurrency
    
    Required
    ISO 4217 currency code.
    Determines the minor unit that Money.amount is expressed in. Zero-decimal currencies such as JPY have a minor unit equal to the major unit.
    One of 182 values; see the schema.
  - customer_idstring · uuid
    
    Required
    The customer (guest record) the account belongs to.
  - customer_namestring
    
    Required
    The customer's name, as of now — the till searches an account by it.
  - customer_phonestring
    The customer's phone, as of now. Empty when the customer has none.
  - statusstring · enum
    
    Required
    open — the account takes new charges. closed — it takes no more; what is already owed is still owed until recorded received.
    openclosed
  - updated_atstring · date-time
    
    Required
  - versioninteger · int64
    
    Required
    The version of the last write to the account, for a stale write to be refused.
- next_cursorstring
  The cursor of the next page, absent when this is the last.
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/customer-accounts' \
  -H "Authorization: Bearer $TOKEN"

Response

{
  "has_more": false,
  "items": [
    {
      "id": "0192f1e4-7c3a-7b2e-9f10-5d6c7e8f9a0b",
      "balance": {
        "amount": 1250,
        "currency": "GBP"
      },
      "created_at": "2026-09-11T09:30:00Z",
      "credit_limit": {
        "amount": 1250,
        "currency": "GBP"
      },
      "customer_id": "0192f1e4-7c3a-7b2e-9f10-5d6c7e8f9a0b",
      "customer_name": "string",
      "customer_phone": "string",
      "status": "open",
      "updated_at": "2026-09-11T09:30:00Z",
      "version": 0
    }
  ],
  "next_cursor": "string"
}

POST/v1/customer-accounts

Open an account for a customer

No. createCustomerAccountAuth customers:write

Opens the account a merchant extends to one of their customers — the trade counter's "put it on the account". One account per customer: opening again returns the same account rather than a second one.

Request body application/json

customer_idstring · uuid

Required
The customer (guest record) the account belongs to.

Responses

200
The account, existing or newly opened.
CustomerAccount · application/json
- idstring · uuid
  
  Required
  The account's id.
- balanceMoney
  
  What the account is still owed, in its most recent charge's currency. Absent when the account has never been charged.
  - amountinteger · int64
    
    Required
    The amount, as a whole number of the currency's minor unit. May be negative to express a refund, discount or credit.
  - currencyCurrency
    
    Required
    ISO 4217 currency code.
    Determines the minor unit that Money.amount is 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
- credit_limitMoney
  
  Nullable
  The most the account may be owed before a charge is refused, in the account's trading currency. Absent is no limit.
  - amountinteger · int64
    
    Required
    The amount, as a whole number of the currency's minor unit. May be negative to express a refund, discount or credit.
  - currencyCurrency
    
    Required
    ISO 4217 currency code.
    Determines the minor unit that Money.amount is expressed in. Zero-decimal currencies such as JPY have a minor unit equal to the major unit.
    One of 182 values; see the schema.
- customer_idstring · uuid
  
  Required
  The customer (guest record) the account belongs to.
- customer_namestring
  
  Required
  The customer's name, as of now — the till searches an account by it.
- customer_phonestring
  The customer's phone, as of now. Empty when the customer has none.
- statusstring · enum
  
  Required
  open — the account takes new charges. closed — it takes no more; what is already owed is still owed until recorded received.
  openclosed
- updated_atstring · date-time
  
  Required
- versioninteger · int64
  
  Required
  The version of the last write to the account, for a stale write to be refused.
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/customer-accounts' \
  -H "Authorization: Bearer $TOKEN" \
  -H 'Content-Type: application/json' \
  -d '{
  "customer_id": "0192f1e4-7c3a-7b2e-9f10-5d6c7e8f9a0b"
}'

Response

{
  "id": "0192f1e4-7c3a-7b2e-9f10-5d6c7e8f9a0b",
  "balance": {
    "amount": 1250,
    "currency": "GBP"
  },
  "created_at": "2026-09-11T09:30:00Z",
  "credit_limit": {
    "amount": 1250,
    "currency": "GBP"
  },
  "customer_id": "0192f1e4-7c3a-7b2e-9f10-5d6c7e8f9a0b",
  "customer_name": "string",
  "customer_phone": "string",
  "status": "open",
  "updated_at": "2026-09-11T09:30:00Z",
  "version": 0
}

GET/v1/customer-accounts/{id}

A customer's account, its statement and balance

No. getCustomerAccountStatementAuth pos:orders:write

Returns one customer's account with its recent charges and receipts and what is left. The balance is derived from the ledger — every account tender on a completed sale that names the account's customer, minus what has been received.

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 account's statement.
CustomerAccountStatement · application/json
- accountCustomerAccount
  
  Required
  The balance a merchant extends to one of their customers (retail: customer accounts — the trade counter). A sale is charged to it by an account tender on an order that names the customer; the merchant records money received against it, and the balance is what is still owed. One account per customer, opened in the back office.
  The balance is derived, never stored: what the customer's completed sales charged (account tenders) minus what has been received (receipts, a legacy per-sale settlement, and money a refund returned to the account). It is in the currency of the account's most recent charge; absent when the account has never been charged.
  - idstring · uuid
    
    Required
    The account's id.
  - balanceMoney
    
    What the account is still owed, in its most recent charge's currency. Absent when the account has never been charged.
    
    amountinteger · int64
    
    Required
    The amount, as a whole number of the currency's minor unit. May be negative to express a refund, discount or credit.
    
    currencyCurrency
    
    Required
    ISO 4217 currency code.
    Determines the minor unit that Money.amount is 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
  - credit_limitMoney
    
    Nullable
    The most the account may be owed before a charge is refused, in the account's trading currency. Absent is no limit.
    
    amountinteger · int64
    
    Required
    The amount, as a whole number of the currency's minor unit. May be negative to express a refund, discount or credit.
    
    currencyCurrency
    
    Required
    ISO 4217 currency code.
    Determines the minor unit that Money.amount is expressed in. Zero-decimal currencies such as JPY have a minor unit equal to the major unit.
    One of 182 values; see the schema.
  - customer_idstring · uuid
    
    Required
    The customer (guest record) the account belongs to.
  - customer_namestring
    
    Required
    The customer's name, as of now — the till searches an account by it.
  - customer_phonestring
    The customer's phone, as of now. Empty when the customer has none.
  - statusstring · enum
    
    Required
    open — the account takes new charges. closed — it takes no more; what is already owed is still owed until recorded received.
    openclosed
  - updated_atstring · date-time
    
    Required
  - versioninteger · int64
    
    Required
    The version of the last write to the account, for a stale write to be refused.
- balanceMoney
  
  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.
- chargesarray of CustomerAccountCharge
  
  Required
  What the account has been charged, newest first: an account tender on completed sales that name the customer.
  - amountMoney
    
    Required
    A monetary amount in a specific currency: Square's Money, and Stripe's amount beside its currency.
    The amount is always an integer count of the currency's minor unit — pence for GBP, cents for USD. Zero-decimal currencies such as JPY have a minor unit equal to their major unit, so {"amount": 500, "currency": "JPY"} is ¥500 while {"amount": 500, "currency": "GBP"} is £5.00.
    Floating point is never used for money anywhere in this API. Binary floats cannot represent most decimal fractions exactly, so accumulating them across the line items of an order produces totals that disagree with the printed receipt by a penny. Integer minor units make every arithmetic operation exact.
    
    amountinteger · int64
    
    Required
    The amount, as a whole number of the currency's minor unit. May be negative to express a refund, discount or credit.
    
    currencyCurrency
    
    Required
    ISO 4217 currency code.
    Determines the minor unit that Money.amount is expressed in. Zero-decimal currencies such as JPY have a minor unit equal to the major unit.
    One of 182 values; see the schema.
  - created_atstring · date-time
    
    Required
    When the tender was taken.
  - location_idstring · uuid
    
    Required
    The site that is owed the money.
  - order_idstring · uuid
    
    Required
    The sale the charge is from.
  - payment_idstring · uuid
    
    Required
    The sale's account tender.
  - referencestring
    The sale's reference, what staff typed or the till printed, so a merchant can find the sale in their own words. Empty when the sale has none.
  - staff_namestring
    Who opened the sale, where an account belongs to a person rather than to the till. Empty when the sale has no staff member on it.
- receiptsarray of CustomerAccountReceipt
  
  Required
  What has been received against the account, newest first.
  - idstring · uuid
    
    Required
  - account_idstring · uuid
    
    Required
    The account the money was received against.
  - amountMoney
    
    Required
    A monetary amount in a specific currency: Square's Money, and Stripe's amount beside its currency.
    The amount is always an integer count of the currency's minor unit — pence for GBP, cents for USD. Zero-decimal currencies such as JPY have a minor unit equal to their major unit, so {"amount": 500, "currency": "JPY"} is ¥500 while {"amount": 500, "currency": "GBP"} is £5.00.
    Floating point is never used for money anywhere in this API. Binary floats cannot represent most decimal fractions exactly, so accumulating them across the line items of an order produces totals that disagree with the printed receipt by a penny. Integer minor units make every arithmetic operation exact.
    
    amountinteger · int64
    
    Required
    The amount, as a whole number of the currency's minor unit. May be negative to express a refund, discount or credit.
    
    currencyCurrency
    
    Required
    ISO 4217 currency code.
    Determines the minor unit that Money.amount is expressed in. Zero-decimal currencies such as JPY have a minor unit equal to the major unit.
    One of 182 values; see the schema.
  - notestring
    
    Required
    What the payment was for, in the merchant's own words. Empty when none was written.
  - recorded_atstring · date-time
    
    Required
  - recorded_bystring
    
    Required
    Who recorded the receipt — the caller's subject, which for a person is their roster id.
  - versioninteger · int64
    
    Required
    The version of the last write to the receipt, for a stale write to be refused.
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/customer-accounts/0192f1e4-7c3a-7b2e-9f10-5d6c7e8f9a0b' \
  -H "Authorization: Bearer $TOKEN"

Response

{
  "account": {
    "id": "0192f1e4-7c3a-7b2e-9f10-5d6c7e8f9a0b",
    "balance": {
      "amount": 1250,
      "currency": "GBP"
    },
    "created_at": "2026-09-11T09:30:00Z",
    "credit_limit": {
      "amount": 1250,
      "currency": "GBP"
    },
    "customer_id": "0192f1e4-7c3a-7b2e-9f10-5d6c7e8f9a0b",
    "customer_name": "string",
    "customer_phone": "string",
    "status": "open",
    "updated_at": "2026-09-11T09:30:00Z",
    "version": 0
  },
  "balance": {
    "amount": 1250,
    "currency": "GBP"
  },
  "charges": [
    {
      "amount": {
        "amount": 1250,
        "currency": "GBP"
      },
      "created_at": "2026-09-11T09:30:00Z",
      "location_id": "0192f1e4-7c3a-7b2e-9f10-5d6c7e8f9a0b",
      "order_id": "0192f1e4-7c3a-7b2e-9f10-5d6c7e8f9a0b",
      "payment_id": "0192f1e4-7c3a-7b2e-9f10-5d6c7e8f9a0b",
      "reference": "string",
      "staff_name": "string"
    }
  ],
  "receipts": [
    {
      "id": "0192f1e4-7c3a-7b2e-9f10-5d6c7e8f9a0b",
      "account_id": "0192f1e4-7c3a-7b2e-9f10-5d6c7e8f9a0b",
      "amount": {
        "amount": 1250,
        "currency": "GBP"
      },
      "note": "string",
      "recorded_at": "2026-09-11T09:30:00Z",
      "recorded_by": "string",
      "version": 0
    }
  ]
}

PATCH/v1/customer-accounts/{id}

Change an account's status or credit limit

No. updateCustomerAccountAuth customers:write

Applies a JSON Merge Patch (RFC 7396) to the account, guarded by If-Match. Send only the fields that change; the patch is refused with 412 if the account has changed since the version you read. A manager or the owner closes an account (no new charges; what is owed stays owed) or reopens it, and sets or clears the most the account may be owed.

Parameters

idpath · string · uuid
Required
UUIDv7 of the resource.
For resources a device can originate — orders, and their line items — this id is minted by the client before the record is ever synced, which is what makes an offline create idempotent.
If-Matchheader · string
Required
The ETag from the read that produced the value you are updating.
Required on updates, not optional, because "last write wins" is the wrong default for a catalogue two managers might edit at once. If anything has been written since your read, the request is rejected with 412 and you re-read and re-apply.
Use * to mean "write regardless of current version" — an explicit, greppable override rather than the silent default.

Request body application/merge-patch+json · CustomerAccountPatch

credit_limitMoney

Nullable
The most the account may be owed before a charge is refused, in the account's trading currency. Null (or absent) is no limit.
- amountinteger · int64
  
  Required
  The amount, as a whole number of the currency's minor unit. May be negative to express a refund, discount or credit.
- currencyCurrency
  
  Required
  ISO 4217 currency code.
  Determines the minor unit that Money.amount is expressed in. Zero-decimal currencies such as JPY have a minor unit equal to the major unit.
  One of 182 values; see the schema.
statusstring · enum
open — the account takes new charges. closed — it takes no more; what is already owed is still owed until recorded received.
openclosed

Responses

200
The account as it now stands.
CustomerAccount · application/json
- idstring · uuid
  
  Required
  The account's id.
- balanceMoney
  
  What the account is still owed, in its most recent charge's currency. Absent when the account has never been charged.
  - amountinteger · int64
    
    Required
    The amount, as a whole number of the currency's minor unit. May be negative to express a refund, discount or credit.
  - currencyCurrency
    
    Required
    ISO 4217 currency code.
    Determines the minor unit that Money.amount is 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
- credit_limitMoney
  
  Nullable
  The most the account may be owed before a charge is refused, in the account's trading currency. Absent is no limit.
  - amountinteger · int64
    
    Required
    The amount, as a whole number of the currency's minor unit. May be negative to express a refund, discount or credit.
  - currencyCurrency
    
    Required
    ISO 4217 currency code.
    Determines the minor unit that Money.amount is expressed in. Zero-decimal currencies such as JPY have a minor unit equal to the major unit.
    One of 182 values; see the schema.
- customer_idstring · uuid
  
  Required
  The customer (guest record) the account belongs to.
- customer_namestring
  
  Required
  The customer's name, as of now — the till searches an account by it.
- customer_phonestring
  The customer's phone, as of now. Empty when the customer has none.
- statusstring · enum
  
  Required
  open — the account takes new charges. closed — it takes no more; what is already owed is still owed until recorded received.
  openclosed
- updated_atstring · date-time
  
  Required
- versioninteger · int64
  
  Required
  The version of the last write to the account, for a stale write to be refused.
400
The request could not be parsed. Malformed JSON, a bad query parameter, or a header that failed to decode, among them an API-Version later than the server speaks or not a date (api-version-unknown, with the server's own in api_version).
Distinct from 422: a 400 never reached validation, so invalid_params is absent. Retrying without changing the request will fail again, except that a request refused for its API-Version goes once the server is updated.
401
No credentials, or credentials that could not be verified — missing bearer token, malformed JWT, expired token, or a signature that failed against the issuer's JWKS.
Refresh the token and retry once. Repeated 401 after a refresh means the device needs to re-enrol.
403
Authenticated, but not permitted. The token is valid and its merchant was resolved, but the caller's role does not allow this operation, or the target belongs to a different merchant.
Cross-tenant access is reported as 403 on a resource the caller may not see, and as 404 where even confirming existence would leak information. Retrying will not help.
404
No such resource, or none visible to this caller.
Also returned instead of 403 where acknowledging existence would itself leak information — so a 404 does not prove the id is unused globally, only that it is not yours.
409
The request conflicts with current state — a uniqueness constraint, or an attempt to mutate an order that is already completed or voided.
Unlike 412, re-reading and retrying unchanged will not resolve it; the request itself has to change.
410
The request names an API-Version this server no longer serves (docs/decisions/0011). Nothing in it was read. api_version names the version the server speaks: the client is behind, and sends the request again once it is updated.
412
The If-Match version did not match the resource's current version: someone else wrote since you read.
This is the expected, healthy outcome of two clients editing the same record — not an error condition to suppress. Re-read the resource, re-apply your change on top of the new state, and retry with the fresh ETag.
415
The request Content-Type is not supported. This API accepts application/json on all mutations.
422
The request parsed but failed validation.
invalid_params lists every failing field with a JSON Pointer, not just the first, so a client can mark up a whole form in one pass rather than making the user fix errors one round trip at a time.
Also returned when an Idempotency-Key is replayed with a different body, and when device-computed order totals disagree with the server's recomputation.
429
Rate limit exceeded. Honour Retry-After rather than applying your own backoff.
A fleet of tills coming back online together after an outage is the realistic cause, which is exactly when uncoordinated client-side retry turns a brief outage into a sustained one. The limit is per process, and per site for what records trade there — a request spends its site's budget, and a till's own smaller one inside it — and per (client, merchant) for everything else; no RateLimit field is sent, so this response and its Retry-After are the whole of the contract.
500
Something failed on our side. trace_id identifies the request in our tracing — quote it in a support ticket.
The body never carries internal detail: no SQL, no stack traces, no upstream error strings. Safe to retry with the same Idempotency-Key.
503
Temporarily unable to serve the request — a dependency is down or the service is shedding load.
Retry with the same Idempotency-Key after Retry-After. This is always safe: a request that did take effect before the failure will be recognised as a replay.

Request

curl -X PATCH 'https://api.tenvelo.com/v1/customer-accounts/0192f1e4-7c3a-7b2e-9f10-5d6c7e8f9a0b' \
  -H "Authorization: Bearer $TOKEN" \
  -H 'If-Match: "3"' \
  -H 'Content-Type: application/merge-patch+json' \
  -d '{
  "credit_limit": {
    "amount": 1250,
    "currency": "GBP"
  },
  "status": "open"
}'

Response

{
  "id": "0192f1e4-7c3a-7b2e-9f10-5d6c7e8f9a0b",
  "balance": {
    "amount": 1250,
    "currency": "GBP"
  },
  "created_at": "2026-09-11T09:30:00Z",
  "credit_limit": {
    "amount": 1250,
    "currency": "GBP"
  },
  "customer_id": "0192f1e4-7c3a-7b2e-9f10-5d6c7e8f9a0b",
  "customer_name": "string",
  "customer_phone": "string",
  "status": "open",
  "updated_at": "2026-09-11T09:30:00Z",
  "version": 0
}

POST/v1/customer-accounts/{id}/receipts

Record money received against a customer's account

No. createCustomerAccountReceiptAuth pos:orders:write

Records that the money a customer's account is owed has arrived. A manager or the owner does it, with a note and who recorded it; the balance drops by the amount, and a replay of the same request returns the same receipt rather than recording twice.

Parameters

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

Request body application/json

amountMoney

Required
A monetary amount in a specific currency: Square's Money, and Stripe's amount beside its currency.
The amount is always an integer count of the currency's minor unit — pence for GBP, cents for USD. Zero-decimal currencies such as JPY have a minor unit equal to their major unit, so {"amount": 500, "currency": "JPY"} is ¥500 while {"amount": 500, "currency": "GBP"} is £5.00.
Floating point is never used for money anywhere in this API. Binary floats cannot represent most decimal fractions exactly, so accumulating them across the line items of an order produces totals that disagree with the printed receipt by a penny. Integer minor units make every arithmetic operation exact.
- amountinteger · int64
  
  Required
  The amount, as a whole number of the currency's minor unit. May be negative to express a refund, discount or credit.
- currencyCurrency
  
  Required
  ISO 4217 currency code.
  Determines the minor unit that Money.amount is expressed in. Zero-decimal currencies such as JPY have a minor unit equal to the major unit.
  One of 182 values; see the schema.
notestring
What the payment was for, in the merchant's own words.

Responses

200
The receipt recorded.
CustomerAccountReceipt · application/json
- idstring · uuid
  
  Required
- account_idstring · uuid
  
  Required
  The account the money was received against.
- amountMoney
  
  Required
  A monetary amount in a specific currency: Square's Money, and Stripe's amount beside its currency.
  The amount is always an integer count of the currency's minor unit — pence for GBP, cents for USD. Zero-decimal currencies such as JPY have a minor unit equal to their major unit, so {"amount": 500, "currency": "JPY"} is ¥500 while {"amount": 500, "currency": "GBP"} is £5.00.
  Floating point is never used for money anywhere in this API. Binary floats cannot represent most decimal fractions exactly, so accumulating them across the line items of an order produces totals that disagree with the printed receipt by a penny. Integer minor units make every arithmetic operation exact.
  - amountinteger · int64
    
    Required
    The amount, as a whole number of the currency's minor unit. May be negative to express a refund, discount or credit.
  - currencyCurrency
    
    Required
    ISO 4217 currency code.
    Determines the minor unit that Money.amount is expressed in. Zero-decimal currencies such as JPY have a minor unit equal to the major unit.
    One of 182 values; see the schema.
- notestring
  
  Required
  What the payment was for, in the merchant's own words. Empty when none was written.
- recorded_atstring · date-time
  
  Required
- recorded_bystring
  
  Required
  Who recorded the receipt — the caller's subject, which for a person is their roster id.
- versioninteger · int64
  
  Required
  The version of the last write to the receipt, for a stale write to be refused.
400
The request could not be parsed. Malformed JSON, a bad query parameter, or a header that failed to decode, among them an API-Version later than the server speaks or not a date (api-version-unknown, with the server's own in api_version).
Distinct from 422: a 400 never reached validation, so invalid_params is absent. Retrying without changing the request will fail again, except that a request refused for its API-Version goes once the server is updated.
401
No credentials, or credentials that could not be verified — missing bearer token, malformed JWT, expired token, or a signature that failed against the issuer's JWKS.
Refresh the token and retry once. Repeated 401 after a refresh means the device needs to re-enrol.
403
Authenticated, but not permitted. The token is valid and its merchant was resolved, but the caller's role does not allow this operation, or the target belongs to a different merchant.
Cross-tenant access is reported as 403 on a resource the caller may not see, and as 404 where even confirming existence would leak information. Retrying will not help.
404
No such resource, or none visible to this caller.
Also returned instead of 403 where acknowledging existence would itself leak information — so a 404 does not prove the id is unused globally, only that it is not yours.
409
The request conflicts with current state — a uniqueness constraint, or an attempt to mutate an order that is already completed or voided.
Unlike 412, re-reading and retrying unchanged will not resolve it; the request itself has to change.
410
The request names an API-Version this server no longer serves (docs/decisions/0011). Nothing in it was read. api_version names the version the server speaks: the client is behind, and sends the request again once it is updated.
422
The request parsed but failed validation.
invalid_params lists every failing field with a JSON Pointer, not just the first, so a client can mark up a whole form in one pass rather than making the user fix errors one round trip at a time.
Also returned when an Idempotency-Key is replayed with a different body, and when device-computed order totals disagree with the server's recomputation.
429
Rate limit exceeded. Honour Retry-After rather than applying your own backoff.
A fleet of tills coming back online together after an outage is the realistic cause, which is exactly when uncoordinated client-side retry turns a brief outage into a sustained one. The limit is per process, and per site for what records trade there — a request spends its site's budget, and a till's own smaller one inside it — and per (client, merchant) for everything else; no RateLimit field is sent, so this response and its Retry-After are the whole of the contract.
500
Something failed on our side. trace_id identifies the request in our tracing — quote it in a support ticket.
The body never carries internal detail: no SQL, no stack traces, no upstream error strings. Safe to retry with the same Idempotency-Key.
503
Temporarily unable to serve the request — a dependency is down or the service is shedding load.
Retry with the same Idempotency-Key after Retry-After. This is always safe: a request that did take effect before the failure will be recognised as a replay.

Request

curl -X POST 'https://api.tenvelo.com/v1/customer-accounts/0192f1e4-7c3a-7b2e-9f10-5d6c7e8f9a0b/receipts' \
  -H "Authorization: Bearer $TOKEN" \
  -H 'Idempotency-Key: 01J8ZK3QF7X2N5V9C4B1A6D8E0' \
  -H 'Content-Type: application/json' \
  -d '{
  "amount": {
    "amount": 1250,
    "currency": "GBP"
  },
  "note": "string"
}'

Response

{
  "id": "0192f1e4-7c3a-7b2e-9f10-5d6c7e8f9a0b",
  "account_id": "0192f1e4-7c3a-7b2e-9f10-5d6c7e8f9a0b",
  "amount": {
    "amount": 1250,
    "currency": "GBP"
  },
  "note": "string",
  "recorded_at": "2026-09-11T09:30:00Z",
  "recorded_by": "string",
  "version": 0
}

GET/v1/customer-allergens

List the merchant's allergen vocabulary

No. listCustomerAllergensAuth customers:read

Returns the merchant's allergen vocabulary, cursor page first. Ordered by name, then id.

The vocabulary is the recognised allergens a guest may declare and a product may carry. It is seeded with the UK/EU fourteen of Regulation 1169/2011 Annex II; a merchant may add to it. A device may read it for the picker and never invents an allergen.

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 the allergen vocabulary.
CustomerAllergenPage · application/json
- has_moreboolean
  
  Required
  Whether another page follows.
- itemsarray of CustomerAllergen
  
  Required
  - idstring · uuid
    
    Required
  - namestring
    
    Required
    The allergen's name, unique per merchant.
    1–64 chars
  - created_atstring · date-time
    
    RequiredRead only
  - merchant_idstring · uuid
    
    RequiredRead only
  - updated_atstring · date-time
    
    RequiredRead only
  - versioninteger · int64
    
    Required
    Bumped on every rename; an update must be written from the version it was read at.
    ≥ 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.
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/customer-allergens' \
  -H "Authorization: Bearer $TOKEN"

Response

{
  "has_more": false,
  "items": [
    {
      "id": "0192f1e4-7c3a-7b2e-9f10-5d6c7e8f9a0b",
      "name": "string",
      "created_at": "2026-09-11T09:30:00Z",
      "merchant_id": "0192f1e4-7c3a-7b2e-9f10-5d6c7e8f9a0b",
      "updated_at": "2026-09-11T09:30:00Z",
      "version": 1
    }
  ],
  "next_cursor": "string"
}

POST/v1/customer-allergens/batch-upsert

Create or rename allergens

No. batchUpsertCustomerAllergensAuth customers:write

Creates allergen entries at client-minted ids, or renames existing ones at the version they were read at. A batch of one is how a single allergen is created.

Each item carries its own idempotency_key and stands or falls on its own: an invalid item, or one written from a stale version, fails in its result and every other item is still applied. Only a malformed envelope refuses the request as a whole.

Request body application/json · CustomerAllergenBatchUpsertRequest

itemsarray of CustomerAllergenBatchUpsertItem

Required
≥ 1 items · ≤ 500 items
- allergenCustomerAllergen
  
  Required
  One member of the merchant's allergen vocabulary: a recognised allergen a guest may declare or a product may carry.
  The vocabulary is seeded with the UK/EU fourteen of Regulation 1169/2011 Annex II, and a merchant may add to it. A guest's free-text "other" allergen is carried but never silently matched, because matching the wrong thing on an allergy line is worse than saying "ask".
  - idstring · uuid
    
    Required
  - namestring
    
    Required
    The allergen's name, unique per merchant.
    1–64 chars
  - versioninteger · int64
    
    Required
    Bumped on every rename; an update must be written from the version it was read at.
    ≥ 1
- idempotency_keyItemIdempotencyKey
  
  Required
  A key for one item in a batch, minted by the client when it queues the item and reused on every attempt to send it. The item, not the request, is the unit of work: a retried batch returns the stored result for every item already applied under its key. A fresh key per attempt defeats the whole mechanism.
  Scoped per merchant, so keys need only be unique within a merchant's own traffic.
  16–255 chars
- versioninteger · int64
  The version this write was made from. Required to rename one that exists, and refused as 412 when somebody else has written it 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/customer-allergens/batch-upsert' \
  -H "Authorization: Bearer $TOKEN" \
  -H 'Content-Type: application/json' \
  -d '{
  "items": [
    {
      "allergen": {
        "id": "0192f1e4-7c3a-7b2e-9f10-5d6c7e8f9a0b",
        "name": "string",
        "version": 1
      },
      "idempotency_key": "01J8ZK3QF7X2N5V9C4B1A6D8E0",
      "version": 1
    }
  ]
}'

Response

{
  "results": [
    {
      "id": "0192f1e4-7c3a-7b2e-9f10-5d6c7e8f9a0b",
      "idempotency_key": "string",
      "problem": {
        "type": "https://api.tenvelo.com/problems/version-conflict",
        "api_version": "2026-10-10",
        "detail": "The product has been modified since version 7 was read.",
        "instance": "/v1/products/0195f8c7-4a1e-7c3b-9f22-8d4e6a1b2c3d",
        "invalid_params": [
          {
            "code": "minimum",
            "pointer": "/line_items/0/quantity",
            "reason": "must be greater than or equal to 1"
          }
        ],
        "refusals": [
          {
            "kind": "devices",
            "count": 3
          }
        ],
        "status": 412,
        "title": "Version conflict",
        "trace_id": "4bf92f3577b34da6a3ce929d0e0e4736"
      },
      "status": "created",
      "version": 0
    }
  ]
}

GET/v1/customer-cards

Find the guest a card belongs to

No. getCustomerByCardAuth customers:read

Asks which guest a card fingerprint is attached to, so a till can greet a returning guest at tender without asking them anything.

A card nobody has linked answers 404, which is how a till knows it is a new guest and can offer to enrol them. So does a card whose guest has since been erased: erasure takes the person out of the directory, and a lookup that still named them would put them back.

The fingerprint is a query parameter rather than a path segment deliberately. It identifies a payment instrument, and the request log records url.path on every request — a fingerprint in the path would be written to the log of every till that ever served that guest.

Parameters

fingerprintquery · string
Required
The processor's fingerprint for the card, compared for equality.

Responses

200
The guest the card belongs to.
Customer · application/json
- idstring · uuid
  
  RequiredRead only
- namestring
  
  Required
  ≤ 200 chars
- allergiesarray of string
  
  RequiredRead only
  The allergies recorded on the guest's record, as free text.
- created_atstring · date-time
  
  RequiredRead only
- emailstring · email
  
  Nullable
- marketing_consentboolean
  
  NullableRead only
  The guest's latest word on marketing by email: granted, withdrawn, or null when never asked. Present on a guest read by its id.
- notestring
  A staff-only note about the guest, e.g. preferences or allergies.
- phonestring
  
  Nullable
  ≤ 64 chars
- preferencesarray of string
  
  RequiredRead only
  The preferences recorded on the guest's record, as free text.
- tagsarray of string
  
  RequiredRead only
  The labels the merchant files the guest under.
- text_marketing_consentboolean
  
  NullableRead only
  The guest's latest word on marketing by text, recorded separately from email: a guest may accept one and refuse the other. Present on a guest read by its id.
- updated_atstring · date-time
  
  RequiredRead only
- versioninteger · int64
  
  RequiredRead only
  The optimistic-concurrency version, used with If-Match.
400
The request could not be parsed. Malformed JSON, a bad query parameter, or a header that failed to decode, among them an API-Version later than the server speaks or not a date (api-version-unknown, with the server's own in api_version).
Distinct from 422: a 400 never reached validation, so invalid_params is absent. Retrying without changing the request will fail again, except that a request refused for its API-Version goes once the server is updated.
401
No credentials, or credentials that could not be verified — missing bearer token, malformed JWT, expired token, or a signature that failed against the issuer's JWKS.
Refresh the token and retry once. Repeated 401 after a refresh means the device needs to re-enrol.
403
Authenticated, but not permitted. The token is valid and its merchant was resolved, but the caller's role does not allow this operation, or the target belongs to a different merchant.
Cross-tenant access is reported as 403 on a resource the caller may not see, and as 404 where even confirming existence would leak information. Retrying will not help.
404
No such resource, or none visible to this caller.
Also returned instead of 403 where acknowledging existence would itself leak information — so a 404 does not prove the id is unused globally, only that it is not yours.
410
The request names an API-Version this server no longer serves (docs/decisions/0011). Nothing in it was read. api_version names the version the server speaks: the client is behind, and sends the request again once it is updated.
429
Rate limit exceeded. Honour Retry-After rather than applying your own backoff.
A fleet of tills coming back online together after an outage is the realistic cause, which is exactly when uncoordinated client-side retry turns a brief outage into a sustained one. The limit is per process, and per site for what records trade there — a request spends its site's budget, and a till's own smaller one inside it — and per (client, merchant) for everything else; no RateLimit field is sent, so this response and its Retry-After are the whole of the contract.
500
Something failed on our side. trace_id identifies the request in our tracing — quote it in a support ticket.
The body never carries internal detail: no SQL, no stack traces, no upstream error strings. Safe to retry with the same Idempotency-Key.

Request

curl -X GET 'https://api.tenvelo.com/v1/customer-cards?fingerprint=…' \
  -H "Authorization: Bearer $TOKEN"

Response

{
  "id": "0192f1e4-7c3a-7b2e-9f10-5d6c7e8f9a0b",
  "name": "string",
  "allergies": [
    "string"
  ],
  "created_at": "2026-09-11T09:30:00Z",
  "email": "ada@example.com",
  "marketing_consent": false,
  "note": "string",
  "phone": "string",
  "preferences": [
    "string"
  ],
  "tags": [
    "string"
  ],
  "text_marketing_consent": false,
  "updated_at": "2026-09-11T09:30:00Z",
  "version": 0
}

POST/v1/customer-cards/batch-create

Attach cards to guests

No. batchCreateCustomerCardsAuth customers:write

Attaches a card fingerprint to a guest so a till can recognise them at tender without asking. A batch of one is how a single card is linked.

Each item carries its own idempotency_key and stands or falls on its own: a fingerprint naming a guest that is not this merchant's fails in its result and every other item is still applied. Only a malformed envelope refuses the request as a whole.

A fingerprint already held by another guest moves to the one named here rather than being duplicated — one card belongs to one person.

Request body application/json · CustomerCardBatchLinkRequest

itemsarray of CustomerCardBatchLinkItem

Required
≥ 1 items · ≤ 500 items
- customer_idstring · uuid
  
  Required
  The guest the card belongs to. Must be this merchant's own.
- fingerprintstring
  
  Required
  The processor's fingerprint for the card. Opaque: compared for equality and never parsed. It is not a credential — it authorises nothing and cannot be charged — but it identifies a payment instrument, so it is treated as the guest's data.
  8–255 chars
- idempotency_keyItemIdempotencyKey
  
  Required
  A key for one item in a batch, minted by the client when it queues the item and reused on every attempt to send it. The item, not the request, is the unit of work: a retried batch returns the stored result for every item already applied under its key. A fresh key per attempt defeats the whole mechanism.
  Scoped per merchant, so keys need only be unique within a merchant's own traffic.
  16–255 chars

Responses

200
The batch was processed. results says what happened to each item.
BatchResponse · application/json
- resultsarray of BatchResult
  
  Required
  - idstring · uuid
    The resource the item created or changed. Absent when it failed.
  - idempotency_keystring
    
    Required
    The item's key, echoed so a result can be matched by key as well as position.
  - problemProblem
    
    Nullable
    Why the item failed, as an RFC 9457 problem. A 422 means the item is malformed and will never succeed — drop it and show it to staff rather than retrying for ever. A 409 or a 5xx means try again later.
    
    typestring · uri
    
    Required
    A stable URI identifying the problem kind. This is the field to branch on.
    default about:blank
    
    api_versionstring
    Present on an api-version-retired or api-version-unknown refusal: the API-Version this server speaks (docs/decisions/0011).
    
    detailstring
    A human-readable explanation specific to this occurrence. Safe to show to a developer; never contains internal state, SQL, or stack traces.
    
    instancestring · uri-reference
    A URI reference identifying the specific occurrence.
    
    invalid_paramsarray of InvalidParam
    
    Present on 422 responses. Lists every field that failed validation, rather than only the first, so a client can highlight an entire form in one pass.
    
    codestring
    Stable machine-readable code for this failure, for clients that localise their own messages rather than showing reason.
    
    pointerstring
    
    Required
    RFC 6901 JSON Pointer to the offending value within the request body. A pointer rather than a field name so that failures nested inside arrays — the third line item of an order — are addressable at all.
    
    reasonstring
    
    Required
    Why this value was rejected, in human-readable form.
    
    refusalsarray of Location refusal
    
    Present on 409 responses to a withdrawal refused by the state it depends on (deleting a location with tills still assigned, open orders, …). Lists every reason at once, each with how much stands in the way, so a client can say what to put right and link to it rather than walking a person through one refusal after another.
    
    kindstring
    
    Required
    A stable refusal kind — devices, open_orders, drawer_sessions, bookings or stock — that a client links to the screen that puts it right. Branch on this field, never on the surrounding prose.
    
    countinteger
    
    Required
    How many things stand in the way of the withdrawal, so a client can repeat the number rather than re-read prose.
    ≥ 1
    
    statusinteger
    
    Required
    The HTTP status code, repeated here so the body is self-contained.
    100–599
    
    titlestring
    
    Required
    A short, human-readable summary of the problem kind.
    
    trace_idstring
    The OpenTelemetry trace id for this request. Quote it in a support ticket and the whole request can be pulled up.
  - statusstring · enum
    
    Required
    created — the item made a new resource. updated — it changed an existing one.
    unchanged — this key was already applied and the original outcome stands. A success, not an error: it is what a client retrying a batch it was unsure landed should expect, and it clears the item from its queue exactly as created does.
    failed — the item was refused, and nothing else in the batch was affected. See problem.
    createdupdatedunchangedfailed
  - versioninteger · int64
    The resource's version after the item. Absent when it failed.
400
The request could not be parsed. Malformed JSON, a bad query parameter, or a header that failed to decode, among them an API-Version later than the server speaks or not a date (api-version-unknown, with the server's own in api_version).
Distinct from 422: a 400 never reached validation, so invalid_params is absent. Retrying without changing the request will fail again, except that a request refused for its API-Version goes once the server is updated.
401
No credentials, or credentials that could not be verified — missing bearer token, malformed JWT, expired token, or a signature that failed against the issuer's JWKS.
Refresh the token and retry once. Repeated 401 after a refresh means the device needs to re-enrol.
403
Authenticated, but not permitted. The token is valid and its merchant was resolved, but the caller's role does not allow this operation, or the target belongs to a different merchant.
Cross-tenant access is reported as 403 on a resource the caller may not see, and as 404 where even confirming existence would leak information. Retrying will not help.
410
The request names an API-Version this server no longer serves (docs/decisions/0011). Nothing in it was read. api_version names the version the server speaks: the client is behind, and sends the request again once it is updated.
422
The request parsed but failed validation.
invalid_params lists every failing field with a JSON Pointer, not just the first, so a client can mark up a whole form in one pass rather than making the user fix errors one round trip at a time.
Also returned when an Idempotency-Key is replayed with a different body, and when device-computed order totals disagree with the server's recomputation.
429
Rate limit exceeded. Honour Retry-After rather than applying your own backoff.
A fleet of tills coming back online together after an outage is the realistic cause, which is exactly when uncoordinated client-side retry turns a brief outage into a sustained one. The limit is per process, and per site for what records trade there — a request spends its site's budget, and a till's own smaller one inside it — and per (client, merchant) for everything else; no RateLimit field is sent, so this response and its Retry-After are the whole of the contract.
500
Something failed on our side. trace_id identifies the request in our tracing — quote it in a support ticket.
The body never carries internal detail: no SQL, no stack traces, no upstream error strings. Safe to retry with the same Idempotency-Key.

Request

curl -X POST 'https://api.tenvelo.com/v1/customer-cards/batch-create' \
  -H "Authorization: Bearer $TOKEN" \
  -H 'Content-Type: application/json' \
  -d '{
  "items": [
    {
      "customer_id": "0192f1e4-7c3a-7b2e-9f10-5d6c7e8f9a0b",
      "fingerprint": "string",
      "idempotency_key": "01J8ZK3QF7X2N5V9C4B1A6D8E0"
    }
  ]
}'

Response

{
  "results": [
    {
      "id": "0192f1e4-7c3a-7b2e-9f10-5d6c7e8f9a0b",
      "idempotency_key": "string",
      "problem": {
        "type": "https://api.tenvelo.com/problems/version-conflict",
        "api_version": "2026-10-10",
        "detail": "The product has been modified since version 7 was read.",
        "instance": "/v1/products/0195f8c7-4a1e-7c3b-9f22-8d4e6a1b2c3d",
        "invalid_params": [
          {
            "code": "minimum",
            "pointer": "/line_items/0/quantity",
            "reason": "must be greater than or equal to 1"
          }
        ],
        "refusals": [
          {
            "kind": "devices",
            "count": 3
          }
        ],
        "status": 412,
        "title": "Version conflict",
        "trace_id": "4bf92f3577b34da6a3ce929d0e0e4736"
      },
      "status": "created",
      "version": 0
    }
  ]
}

POST/v1/customer-consents/batch-create

Record guests' word on marketing

No. batchCreateCustomerConsentsAuth customers:write

Records what guests said about being marketed to: each item is one statement added to the guest's consent history, and their current word is the latest by occurred_at. Having an email is not consent to market, so consent is recorded apart from the guest's details.

A guest's rights over their own record stay with every merchant whatever they have bought, so this is open on every plan, as reading the directory and erasure are. An owner or a manager. Each item carries its own idempotency_key, under which a retry finds the statement already recorded.

Request body application/json · CustomerConsentBatchCreateRequest

itemsarray of CustomerConsentBatchCreateItem

Required
≥ 1 items · ≤ 500 items
- customer_idstring · uuid
  
  Required
  The guest it is about. A guest of another merchant, or one erased, is refused.
- expires_atstring · date-time
  When a grant lapses, on a grant; absent means until withdrawn. A later grant is the refresh.
- grantedboolean
  
  Required
- 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
- purposestring · enum
  marketingtext_marketing
  default marketing
- sourcestring
  
  Required
  How it was given, e.g. in_person or email.
  1–64 chars

Responses

200
The batch was processed. results says what happened to each item.
BatchResponse · application/json
- resultsarray of BatchResult
  
  Required
  - idstring · uuid
    The resource the item created or changed. Absent when it failed.
  - idempotency_keystring
    
    Required
    The item's key, echoed so a result can be matched by key as well as position.
  - problemProblem
    
    Nullable
    Why the item failed, as an RFC 9457 problem. A 422 means the item is malformed and will never succeed — drop it and show it to staff rather than retrying for ever. A 409 or a 5xx means try again later.
    
    typestring · uri
    
    Required
    A stable URI identifying the problem kind. This is the field to branch on.
    default about:blank
    
    api_versionstring
    Present on an api-version-retired or api-version-unknown refusal: the API-Version this server speaks (docs/decisions/0011).
    
    detailstring
    A human-readable explanation specific to this occurrence. Safe to show to a developer; never contains internal state, SQL, or stack traces.
    
    instancestring · uri-reference
    A URI reference identifying the specific occurrence.
    
    invalid_paramsarray of InvalidParam
    
    Present on 422 responses. Lists every field that failed validation, rather than only the first, so a client can highlight an entire form in one pass.
    
    codestring
    Stable machine-readable code for this failure, for clients that localise their own messages rather than showing reason.
    
    pointerstring
    
    Required
    RFC 6901 JSON Pointer to the offending value within the request body. A pointer rather than a field name so that failures nested inside arrays — the third line item of an order — are addressable at all.
    
    reasonstring
    
    Required
    Why this value was rejected, in human-readable form.
    
    refusalsarray of Location refusal
    
    Present on 409 responses to a withdrawal refused by the state it depends on (deleting a location with tills still assigned, open orders, …). Lists every reason at once, each with how much stands in the way, so a client can say what to put right and link to it rather than walking a person through one refusal after another.
    
    kindstring
    
    Required
    A stable refusal kind — devices, open_orders, drawer_sessions, bookings or stock — that a client links to the screen that puts it right. Branch on this field, never on the surrounding prose.
    
    countinteger
    
    Required
    How many things stand in the way of the withdrawal, so a client can repeat the number rather than re-read prose.
    ≥ 1
    
    statusinteger
    
    Required
    The HTTP status code, repeated here so the body is self-contained.
    100–599
    
    titlestring
    
    Required
    A short, human-readable summary of the problem kind.
    
    trace_idstring
    The OpenTelemetry trace id for this request. Quote it in a support ticket and the whole request can be pulled up.
  - statusstring · enum
    
    Required
    created — the item made a new resource. updated — it changed an existing one.
    unchanged — this key was already applied and the original outcome stands. A success, not an error: it is what a client retrying a batch it was unsure landed should expect, and it clears the item from its queue exactly as created does.
    failed — the item was refused, and nothing else in the batch was affected. See problem.
    createdupdatedunchangedfailed
  - versioninteger · int64
    The resource's version after the item. Absent when it failed.
400
The request could not be parsed. Malformed JSON, a bad query parameter, or a header that failed to decode, among them an API-Version later than the server speaks or not a date (api-version-unknown, with the server's own in api_version).
Distinct from 422: a 400 never reached validation, so invalid_params is absent. Retrying without changing the request will fail again, except that a request refused for its API-Version goes once the server is updated.
401
No credentials, or credentials that could not be verified — missing bearer token, malformed JWT, expired token, or a signature that failed against the issuer's JWKS.
Refresh the token and retry once. Repeated 401 after a refresh means the device needs to re-enrol.
403
Authenticated, but not permitted. The token is valid and its merchant was resolved, but the caller's role does not allow this operation, or the target belongs to a different merchant.
Cross-tenant access is reported as 403 on a resource the caller may not see, and as 404 where even confirming existence would leak information. Retrying will not help.
410
The request names an API-Version this server no longer serves (docs/decisions/0011). Nothing in it was read. api_version names the version the server speaks: the client is behind, and sends the request again once it is updated.
415
The request Content-Type is not supported. This API accepts application/json on all mutations.
422
The request parsed but failed validation.
invalid_params lists every failing field with a JSON Pointer, not just the first, so a client can mark up a whole form in one pass rather than making the user fix errors one round trip at a time.
Also returned when an Idempotency-Key is replayed with a different body, and when device-computed order totals disagree with the server's recomputation.
429
Rate limit exceeded. Honour Retry-After rather than applying your own backoff.
A fleet of tills coming back online together after an outage is the realistic cause, which is exactly when uncoordinated client-side retry turns a brief outage into a sustained one. The limit is per process, and per site for what records trade there — a request spends its site's budget, and a till's own smaller one inside it — and per (client, merchant) for everything else; no RateLimit field is sent, so this response and its Retry-After are the whole of the contract.
500
Something failed on our side. trace_id identifies the request in our tracing — quote it in a support ticket.
The body never carries internal detail: no SQL, no stack traces, no upstream error strings. Safe to retry with the same Idempotency-Key.

Request

curl -X POST 'https://api.tenvelo.com/v1/customer-consents/batch-create' \
  -H "Authorization: Bearer $TOKEN" \
  -H 'Content-Type: application/json' \
  -d '{
  "items": [
    {
      "customer_id": "0192f1e4-7c3a-7b2e-9f10-5d6c7e8f9a0b",
      "expires_at": "2026-09-11T09:30:00Z",
      "granted": false,
      "idempotency_key": "01J8ZK3QF7X2N5V9C4B1A6D8E0",
      "purpose": "marketing",
      "source": "string"
    }
  ]
}'

Response

{
  "results": [
    {
      "id": "0192f1e4-7c3a-7b2e-9f10-5d6c7e8f9a0b",
      "idempotency_key": "string",
      "problem": {
        "type": "https://api.tenvelo.com/problems/version-conflict",
        "api_version": "2026-10-10",
        "detail": "The product has been modified since version 7 was read.",
        "instance": "/v1/products/0195f8c7-4a1e-7c3b-9f22-8d4e6a1b2c3d",
        "invalid_params": [
          {
            "code": "minimum",
            "pointer": "/line_items/0/quantity",
            "reason": "must be greater than or equal to 1"
          }
        ],
        "refusals": [
          {
            "kind": "devices",
            "count": 3
          }
        ],
        "status": 412,
        "title": "Version conflict",
        "trace_id": "4bf92f3577b34da6a3ce929d0e0e4736"
      },
      "status": "created",
      "version": 0
    }
  ]
}

POST/v1/customer-sessions/current/revoke

Sign a guest out

No. revokeCustomerSessionAuth bearer

Ends the session whose token is sent, at once: it is kept hashed and looked up on every request. Signing out when already signed out answers the same.

Responses

204
Signed out.
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.
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.

GET/v1/customer-tags

List the merchant's tag set

No. listCustomerTagsAuth customers:read

Returns the merchant's tag set, cursor page first. Ordered by name, then id.

The set is the vocabulary guests are tagged with; the back office and a till offer it rather than free text. A device may read it for the picker and never invents a tag.

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 the tag set.
CustomerTagPage · application/json
- has_moreboolean
  
  Required
  Whether another page follows.
- itemsarray of CustomerTag
  
  Required
  - idstring · uuid
    
    Required
  - namestring
    
    Required
    The tag's name, unique per merchant.
    1–64 chars
  - created_atstring · date-time
    
    RequiredRead only
  - merchant_idstring · uuid
    
    RequiredRead only
  - updated_atstring · date-time
    
    RequiredRead only
  - versioninteger · int64
    
    Required
    Bumped on every rename; an update must be written from the version it was read at.
    ≥ 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.
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/customer-tags' \
  -H "Authorization: Bearer $TOKEN"

Response

{
  "has_more": false,
  "items": [
    {
      "id": "0192f1e4-7c3a-7b2e-9f10-5d6c7e8f9a0b",
      "name": "string",
      "created_at": "2026-09-11T09:30:00Z",
      "merchant_id": "0192f1e4-7c3a-7b2e-9f10-5d6c7e8f9a0b",
      "updated_at": "2026-09-11T09:30:00Z",
      "version": 1
    }
  ],
  "next_cursor": "string"
}

POST/v1/customer-tags/batch-upsert

Create or rename tags

No. batchUpsertCustomerTagsAuth customers:write

Creates tags at client-minted ids, or renames existing ones at the version they were read at. A batch of one is how a single tag is created.

Each item carries its own idempotency_key and stands or falls on its own: an invalid item, or one written from a stale version, fails in its result and every other item is still applied. Only a malformed envelope refuses the request as a whole.

Request body application/json · CustomerTagBatchUpsertRequest

itemsarray of CustomerTagBatchUpsertItem

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
- tagCustomerTag
  
  Required
  One member of the merchant's tag set: a name guests are labelled with.
  The set is what the back office and the till offer when a guest is tagged, so staff pick from it rather than typing free text into every record. Tags are merchant-named, never machine-coded — a coffee shop writes "regular", a dental practice writes "new patient" — and this is the record that names the vocabulary.
  - idstring · uuid
    
    Required
  - namestring
    
    Required
    The tag's name, unique per merchant.
    1–64 chars
  - versioninteger · int64
    
    Required
    Bumped on every rename; an update must be written from the version it was read at.
    ≥ 1
- versioninteger · int64
  The version this write was made from. Required to rename one that exists, and refused as 412 when somebody else has written it 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/customer-tags/batch-upsert' \
  -H "Authorization: Bearer $TOKEN" \
  -H 'Content-Type: application/json' \
  -d '{
  "items": [
    {
      "idempotency_key": "01J8ZK3QF7X2N5V9C4B1A6D8E0",
      "tag": {
        "id": "0192f1e4-7c3a-7b2e-9f10-5d6c7e8f9a0b",
        "name": "string",
        "version": 1
      },
      "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/customers

List customers

No. listCustomersAuth customers:read

Returns the merchant's guest directory, one page at a time.

A signed-in person or an integration with the customers:read scope may list the directory; a device token gets a 403, because the guest book is never pushed to a stolen till. As on the directory screen, q matches a fragment of a guest's name, phone or email, and % and _ in it match those characters literally rather than as wildcards.

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.
qquery · string
A name, phone or email fragment to match.

Responses

200
A page of guests.
CustomerPage · application/json
- has_moreboolean
  
  Required
  Whether another page follows.
- itemsarray of Customer
  
  Required
  - idstring · uuid
    
    RequiredRead only
  - namestring
    
    Required
    ≤ 200 chars
  - allergiesarray of string
    
    RequiredRead only
    The allergies recorded on the guest's record, as free text.
  - created_atstring · date-time
    
    RequiredRead only
  - emailstring · email
    
    Nullable
  - marketing_consentboolean
    
    NullableRead only
    The guest's latest word on marketing by email: granted, withdrawn, or null when never asked. Present on a guest read by its id.
  - notestring
    A staff-only note about the guest, e.g. preferences or allergies.
  - phonestring
    
    Nullable
    ≤ 64 chars
  - preferencesarray of string
    
    RequiredRead only
    The preferences recorded on the guest's record, as free text.
  - tagsarray of string
    
    RequiredRead only
    The labels the merchant files the guest under.
  - text_marketing_consentboolean
    
    NullableRead only
    The guest's latest word on marketing by text, recorded separately from email: a guest may accept one and refuse the other. Present on a guest read by its id.
  - updated_atstring · date-time
    
    RequiredRead only
  - versioninteger · int64
    
    RequiredRead only
    The optimistic-concurrency version, used with If-Match.
- 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/customers' \
  -H "Authorization: Bearer $TOKEN"

Response

{
  "has_more": false,
  "items": [
    {
      "id": "0192f1e4-7c3a-7b2e-9f10-5d6c7e8f9a0b",
      "name": "string",
      "allergies": [
        "string"
      ],
      "created_at": "2026-09-11T09:30:00Z",
      "email": "ada@example.com",
      "marketing_consent": false,
      "note": "string",
      "phone": "string",
      "preferences": [
        "string"
      ],
      "tags": [
        "string"
      ],
      "text_marketing_consent": false,
      "updated_at": "2026-09-11T09:30:00Z",
      "version": 0
    }
  ],
  "next_cursor": "string"
}

POST/v1/customers/batch-erase

Erase guests

No. batchEraseCustomersAuth customers:write

Erases guests under GDPR Art. 17, each item standing on its own: the personal fields are blanked, consents withdrawn, and the id kept so the orders and loyalty that referenced the guest stay attached to an anonymous record. An erased guest no longer appears in the directory or a device's loyalty search.

Each item carries its own idempotency_key; a retry of an applied key answers the stored outcome rather than erasing twice. Manager-scoped, as the back office erase is: an integration carrying customers:write is a manager's authorised tool.

Request body application/json · CustomerBatchEraseRequest

itemsarray of CustomerBatchEraseItem

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

Responses

200
The batch was processed. results says what happened to each item.
BatchResponse · application/json
- resultsarray of BatchResult
  
  Required
  - idstring · uuid
    The resource the item created or changed. Absent when it failed.
  - idempotency_keystring
    
    Required
    The item's key, echoed so a result can be matched by key as well as position.
  - problemProblem
    
    Nullable
    Why the item failed, as an RFC 9457 problem. A 422 means the item is malformed and will never succeed — drop it and show it to staff rather than retrying for ever. A 409 or a 5xx means try again later.
    
    typestring · uri
    
    Required
    A stable URI identifying the problem kind. This is the field to branch on.
    default about:blank
    
    api_versionstring
    Present on an api-version-retired or api-version-unknown refusal: the API-Version this server speaks (docs/decisions/0011).
    
    detailstring
    A human-readable explanation specific to this occurrence. Safe to show to a developer; never contains internal state, SQL, or stack traces.
    
    instancestring · uri-reference
    A URI reference identifying the specific occurrence.
    
    invalid_paramsarray of InvalidParam
    
    Present on 422 responses. Lists every field that failed validation, rather than only the first, so a client can highlight an entire form in one pass.
    
    codestring
    Stable machine-readable code for this failure, for clients that localise their own messages rather than showing reason.
    
    pointerstring
    
    Required
    RFC 6901 JSON Pointer to the offending value within the request body. A pointer rather than a field name so that failures nested inside arrays — the third line item of an order — are addressable at all.
    
    reasonstring
    
    Required
    Why this value was rejected, in human-readable form.
    
    refusalsarray of Location refusal
    
    Present on 409 responses to a withdrawal refused by the state it depends on (deleting a location with tills still assigned, open orders, …). Lists every reason at once, each with how much stands in the way, so a client can say what to put right and link to it rather than walking a person through one refusal after another.
    
    kindstring
    
    Required
    A stable refusal kind — devices, open_orders, drawer_sessions, bookings or stock — that a client links to the screen that puts it right. Branch on this field, never on the surrounding prose.
    
    countinteger
    
    Required
    How many things stand in the way of the withdrawal, so a client can repeat the number rather than re-read prose.
    ≥ 1
    
    statusinteger
    
    Required
    The HTTP status code, repeated here so the body is self-contained.
    100–599
    
    titlestring
    
    Required
    A short, human-readable summary of the problem kind.
    
    trace_idstring
    The OpenTelemetry trace id for this request. Quote it in a support ticket and the whole request can be pulled up.
  - statusstring · enum
    
    Required
    created — the item made a new resource. updated — it changed an existing one.
    unchanged — this key was already applied and the original outcome stands. A success, not an error: it is what a client retrying a batch it was unsure landed should expect, and it clears the item from its queue exactly as created does.
    failed — the item was refused, and nothing else in the batch was affected. See problem.
    createdupdatedunchangedfailed
  - versioninteger · int64
    The resource's version after the item. Absent when it failed.
400
The request could not be parsed. Malformed JSON, a bad query parameter, or a header that failed to decode, among them an API-Version later than the server speaks or not a date (api-version-unknown, with the server's own in api_version).
Distinct from 422: a 400 never reached validation, so invalid_params is absent. Retrying without changing the request will fail again, except that a request refused for its API-Version goes once the server is updated.
401
No credentials, or credentials that could not be verified — missing bearer token, malformed JWT, expired token, or a signature that failed against the issuer's JWKS.
Refresh the token and retry once. Repeated 401 after a refresh means the device needs to re-enrol.
403
Authenticated, but not permitted. The token is valid and its merchant was resolved, but the caller's role does not allow this operation, or the target belongs to a different merchant.
Cross-tenant access is reported as 403 on a resource the caller may not see, and as 404 where even confirming existence would leak information. Retrying will not help.
410
The request names an API-Version this server no longer serves (docs/decisions/0011). Nothing in it was read. api_version names the version the server speaks: the client is behind, and sends the request again once it is updated.
415
The request Content-Type is not supported. This API accepts application/json on all mutations.
422
The request parsed but failed validation.
invalid_params lists every failing field with a JSON Pointer, not just the first, so a client can mark up a whole form in one pass rather than making the user fix errors one round trip at a time.
Also returned when an Idempotency-Key is replayed with a different body, and when device-computed order totals disagree with the server's recomputation.
429
Rate limit exceeded. Honour Retry-After rather than applying your own backoff.
A fleet of tills coming back online together after an outage is the realistic cause, which is exactly when uncoordinated client-side retry turns a brief outage into a sustained one. The limit is per process, and per site for what records trade there — a request spends its site's budget, and a till's own smaller one inside it — and per (client, merchant) for everything else; no RateLimit field is sent, so this response and its Retry-After are the whole of the contract.
500
Something failed on our side. trace_id identifies the request in our tracing — quote it in a support ticket.
The body never carries internal detail: no SQL, no stack traces, no upstream error strings. Safe to retry with the same Idempotency-Key.
503
Temporarily unable to serve the request — a dependency is down or the service is shedding load.
Retry with the same Idempotency-Key after Retry-After. This is always safe: a request that did take effect before the failure will be recognised as a replay.

Request

curl -X POST 'https://api.tenvelo.com/v1/customers/batch-erase' \
  -H "Authorization: Bearer $TOKEN" \
  -H 'Content-Type: application/json' \
  -d '{
  "items": [
    {
      "id": "0192f1e4-7c3a-7b2e-9f10-5d6c7e8f9a0b",
      "idempotency_key": "01J8ZK3QF7X2N5V9C4B1A6D8E0"
    }
  ]
}'

Response

{
  "results": [
    {
      "id": "0192f1e4-7c3a-7b2e-9f10-5d6c7e8f9a0b",
      "idempotency_key": "string",
      "problem": {
        "type": "https://api.tenvelo.com/problems/version-conflict",
        "api_version": "2026-10-10",
        "detail": "The product has been modified since version 7 was read.",
        "instance": "/v1/products/0195f8c7-4a1e-7c3b-9f22-8d4e6a1b2c3d",
        "invalid_params": [
          {
            "code": "minimum",
            "pointer": "/line_items/0/quantity",
            "reason": "must be greater than or equal to 1"
          }
        ],
        "refusals": [
          {
            "kind": "devices",
            "count": 3
          }
        ],
        "status": 412,
        "title": "Version conflict",
        "trace_id": "4bf92f3577b34da6a3ce929d0e0e4736"
      },
      "status": "created",
      "version": 0
    }
  ]
}

POST/v1/customers/batch-merge

Merge duplicate guests

No. batchMergeCustomersAuth customers:write

Folds duplicate guests into survivors, each item standing on its own. A merge rewrites no sale: the duplicate's completed orders and loyalty movements keep the guest id they were recorded with, and the survivor's history and balance include them. Its bookings, waitlist entries, consents and card links move to the survivor. The duplicate is kept as a merged row, so a sale that names it still resolves, and reads of it answer 404.

Each item carries its own idempotency_key; a retry of an applied key answers the stored outcome rather than merging again. Manager-scoped, as the back office merge is: an integration carrying customers:write is a manager's authorised tool.

Request body application/json · CustomerBatchMergeRequest

itemsarray of CustomerBatchMergeItem

Required
≥ 1 items · ≤ 500 items
- duplicate_idstring · uuid
  
  Required
  The guest being folded away.
- 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
- survivor_idstring · uuid
  
  Required
  The guest everything is folded into.

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/customers/batch-merge' \
  -H "Authorization: Bearer $TOKEN" \
  -H 'Content-Type: application/json' \
  -d '{
  "items": [
    {
      "duplicate_id": "0192f1e4-7c3a-7b2e-9f10-5d6c7e8f9a0b",
      "idempotency_key": "01J8ZK3QF7X2N5V9C4B1A6D8E0",
      "survivor_id": "0192f1e4-7c3a-7b2e-9f10-5d6c7e8f9a0b"
    }
  ]
}'

Response

{
  "results": [
    {
      "id": "0192f1e4-7c3a-7b2e-9f10-5d6c7e8f9a0b",
      "idempotency_key": "string",
      "problem": {
        "type": "https://api.tenvelo.com/problems/version-conflict",
        "api_version": "2026-10-10",
        "detail": "The product has been modified since version 7 was read.",
        "instance": "/v1/products/0195f8c7-4a1e-7c3b-9f22-8d4e6a1b2c3d",
        "invalid_params": [
          {
            "code": "minimum",
            "pointer": "/line_items/0/quantity",
            "reason": "must be greater than or equal to 1"
          }
        ],
        "refusals": [
          {
            "kind": "devices",
            "count": 3
          }
        ],
        "status": 412,
        "title": "Version conflict",
        "trace_id": "4bf92f3577b34da6a3ce929d0e0e4736"
      },
      "status": "created",
      "version": 0
    }
  ]
}

POST/v1/customers/batch-upsert

Create or replace guests

No. batchUpsertCustomersAuth customers:write

Creates guests at client-minted ids, or replaces existing ones at the version they were read at. A batch of one is how a single guest is recorded.

Each item carries its own idempotency_key and stands or falls on its own: an invalid item, or one written from a stale version, fails in its result and every other item is still applied. Only a malformed envelope refuses the request as a whole.

Request body application/json · CustomerBatchUpsertRequest

itemsarray of CustomerBatchUpsertItem

Required
≥ 1 items · ≤ 500 items
- idstring · uuid
  
  Required
- namestring
  
  Required
  ≤ 200 chars
- allergiesarray of string
- consentCustomerConsentWrite
  
  A consent as a client records it: the purpose, whether granted, and how it was given. Marketing consent is recorded separately from contact details — having an email is not consent to market (docs/product/merchant/guest-record.md). Each write is one statement added to the guest's consent history; their current word is the latest by occurred_at.
  - expires_atstring · date-time
    When a grant lapses, on a grant: after it the guest is as if withdrawn, while the statement stays as what they said. Absent (or zero) means until withdrawn. A later grant is the refresh — a new statement, the old one above it in the history. An expiry must be after occurred_at.
  - grantedboolean
    
    Required
  - occurred_atstring · date-time
    When the guest said it, by the recording device's clock — not when the write arrives. A till queues its writes offline, so this is what orders a guest's statements: an opt-in given before a withdrawal stays behind it however late it syncs. Absent means now, as the server receives it; a time later than that is taken as now.
  - purposestring · enum
    What the guest was asked to agree to. marketing is news and offers by email; text_marketing the same by text — recorded separately, because a guest may accept one and refuse the other.
    marketingtext_marketing
    default marketing
  - sourcestring
    
    Required
    How it was given, e.g. till (the link dialog).
    ≤ 64 chars
- emailstring · email
  
  Nullable
- idempotency_keystring
  
  Required
  1–200 chars
- notestring
  A staff-only note about the guest, e.g. preferences or allergies.
- phonestring
  
  Nullable
  ≤ 64 chars
- preferencesarray of string
- tagsarray of string
- versioninteger · int64
  The version the guest was read at, when replacing. Absent means create.

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/customers/batch-upsert' \
  -H "Authorization: Bearer $TOKEN" \
  -H 'Content-Type: application/json' \
  -d '{
  "items": [
    {
      "id": "0192f1e4-7c3a-7b2e-9f10-5d6c7e8f9a0b",
      "name": "string",
      "allergies": [
        "string"
      ],
      "consent": {
        "expires_at": "2026-09-11T09:30:00Z",
        "granted": false,
        "occurred_at": "2026-09-11T09:30:00Z",
        "purpose": "marketing",
        "source": "string"
      },
      "email": "ada@example.com",
      "idempotency_key": "string",
      "note": "string",
      "phone": "string",
      "preferences": [
        "string"
      ],
      "tags": [
        "string"
      ],
      "version": 0
    }
  ]
}'

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/customers/search

Search customers for loyalty redemption

No. getCustomerMatchesAuth customers:read

Looks a guest up by name or phone so the till can offer to redeem their loyalty points.

This is the one thing a device may do to the guest book, and it stays a targeted query rather than the directory: identity, loyalty balance and the guest's labels, so a counter can offer a label as well as a redemption. No contact details, no note, no history — a stolen till gets a name, what they are owed, and how the merchant has labelled them, and nothing else.

The labels are the widest part of that. A merchant with a tag set is confined to its own vocabulary, but one without a set still keeps free text, so what a device sees is whatever has been typed. The note and allergies are deliberately not here: those need GET /v1/customers/{id}/serving-fields, which answers only for a guest the calling device's location has actually served.

A person signed in to the back office may call it too.

Parameters

qquery · string
A name or phone fragment to match.
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
Matching guests, with their loyalty balance.
CustomerSearch · application/json
- itemsarray of CustomerLoyalty
  
  Required
  - idstring · uuid
    
    Required
  - namestring
    
    Required
  - loyalty_pointsinteger · int64
    The guest's current loyalty balance, earned minus redeemed.
  - rewardsarray of Reward
    
    The reward catalogue entries this guest can afford, so a till can offer them at redemption. Server-computed from the balance; a guest not enrolled sees none.
    
    idstring · uuid
    
    Required
    
    namestring
    
    Required
    What the reward is called to the guest and on the receipt.
    
    cost_pointsinteger · int64
    
    Required
    What redeeming it costs, in points.
    
    discount_idstring · uuid
    
    Required
    The discount definition the reward is backed by.
  - tagsstring
    The guest's labels, carried so a counter can offer them; still no contact details and no note.
  - tierLoyaltyTierStatus
    
    A guest's standing in a loyalty programme's ladder at one moment (loyalty item 16): the tier they are on, the next tier above, and how much more they need to reach it.
    
    currentLoyaltyTier
    
    One named level in a loyalty programme's ladder (loyalty item 16). Exactly one of threshold_spend and threshold_visits is set; window_days is the rolling window over which the qualifying spend or visits are counted, and earn_rate_percentage is the multiplier on the programme's base earn rate (10000 is 1x).
    
    idstring · uuid
    
    Required
    
    namestring
    
    Required
    
    earn_rate_percentageRelativePercentage
    A percentage that may be negative or above 100, such as a change on a period before or a multiplier, in a decimal string with at most four decimal places: a fall of an eighth is "-12.5", and one and a half times is "150". Read and computed as a Percentage is, in parts per million.
    pattern ^-?(0|[1-9][0-9]{0,8})(\.[0-9]{1,4})?$
    
    threshold_spendMoney
    
    A monetary amount in a specific currency: Square's Money, and Stripe's amount beside its currency.
    The amount is always an integer count of the currency's minor unit — pence for GBP, cents for USD. Zero-decimal currencies such as JPY have a minor unit equal to their major unit, so {"amount": 500, "currency": "JPY"} is ¥500 while {"amount": 500, "currency": "GBP"} is £5.00.
    Floating point is never used for money anywhere in this API. Binary floats cannot represent most decimal fractions exactly, so accumulating them across the line items of an order produces totals that disagree with the printed receipt by a penny. Integer minor units make every arithmetic operation exact.
    
    amountinteger · int64
    
    Required
    The amount, as a whole number of the currency's minor unit. May be negative to express a refund, discount or credit.
    
    currencyCurrency
    
    Required
    ISO 4217 currency code.
    Determines the minor unit that Money.amount is expressed in. Zero-decimal currencies such as JPY have a minor unit equal to the major unit.
    One of 182 values; see the schema.
    
    threshold_visitsinteger · int64
    The number of completed linked orders that reaches the tier.
    
    window_daysinteger · int32
    
    nextLoyaltyTier
    
    One named level in a loyalty programme's ladder (loyalty item 16). Exactly one of threshold_spend and threshold_visits is set; window_days is the rolling window over which the qualifying spend or visits are counted, and earn_rate_percentage is the multiplier on the programme's base earn rate (10000 is 1x).
    
    idstring · uuid
    
    Required
    
    namestring
    
    Required
    
    earn_rate_percentageRelativePercentage
    A percentage that may be negative or above 100, such as a change on a period before or a multiplier, in a decimal string with at most four decimal places: a fall of an eighth is "-12.5", and one and a half times is "150". Read and computed as a Percentage is, in parts per million.
    pattern ^-?(0|[1-9][0-9]{0,8})(\.[0-9]{1,4})?$
    
    threshold_spendMoney
    
    A monetary amount in a specific currency: Square's Money, and Stripe's amount beside its currency.
    The amount is always an integer count of the currency's minor unit — pence for GBP, cents for USD. Zero-decimal currencies such as JPY have a minor unit equal to their major unit, so {"amount": 500, "currency": "JPY"} is ¥500 while {"amount": 500, "currency": "GBP"} is £5.00.
    Floating point is never used for money anywhere in this API. Binary floats cannot represent most decimal fractions exactly, so accumulating them across the line items of an order produces totals that disagree with the printed receipt by a penny. Integer minor units make every arithmetic operation exact.
    
    amountinteger · int64
    
    Required
    The amount, as a whole number of the currency's minor unit. May be negative to express a refund, discount or credit.
    
    currencyCurrency
    
    Required
    ISO 4217 currency code.
    Determines the minor unit that Money.amount is expressed in. Zero-decimal currencies such as JPY have a minor unit equal to the major unit.
    One of 182 values; see the schema.
    
    threshold_visitsinteger · int64
    The number of completed linked orders that reaches the tier.
    
    window_daysinteger · int32
    
    spend_neededMoney
    
    A monetary amount in a specific currency: Square's Money, and Stripe's amount beside its currency.
    The amount is always an integer count of the currency's minor unit — pence for GBP, cents for USD. Zero-decimal currencies such as JPY have a minor unit equal to their major unit, so {"amount": 500, "currency": "JPY"} is ¥500 while {"amount": 500, "currency": "GBP"} is £5.00.
    Floating point is never used for money anywhere in this API. Binary floats cannot represent most decimal fractions exactly, so accumulating them across the line items of an order produces totals that disagree with the printed receipt by a penny. Integer minor units make every arithmetic operation exact.
    
    amountinteger · int64
    
    Required
    The amount, as a whole number of the currency's minor unit. May be negative to express a refund, discount or credit.
    
    currencyCurrency
    
    Required
    ISO 4217 currency code.
    Determines the minor unit that Money.amount is expressed in. Zero-decimal currencies such as JPY have a minor unit equal to the major unit.
    One of 182 values; see the schema.
    
    visits_neededinteger · int64
    The visits still needed to reach next, when next is reached by visits.
  - versioninteger · int64
    
    Required
    The guest record's version, for the optimistic write a picker makes; it may be stale by the time the write lands, and the batch then refuses.
- location_participatesboolean
  Whether the calling site takes part in the programme (loyalty: a programme can leave a site out). False — when the site is left out, or when no programme is active — means a sale here neither earns points nor offers redemption, and the device should say why rather than offer rewards.
- offline_redemption_cap_pointsinteger · int64
  The most points one offline redemption may spend, on a points programme: the device honours the lesser of the guest's balance as this till last saw it and this cap, so a stale balance cannot be believed too far (loyalty item 13). Zero means the programme offers no offline redemption.
- ratesarray of LoyaltyRate
  
  The active points programme's rates, one per currency it trades in, carried here so a device can say what a sale against a guest earns and offer a redemption's value from one response. Empty when no points programme is active; a currency with no rate earns and redeems nothing.
  - point_valueMoney
    
    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.
  - pointsinteger · int64
    
    Required
    The points earned for every whole spend. Zero earns nothing.
    ≥ 0
  - spendMoney
    
    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.
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/customers/search' \
  -H "Authorization: Bearer $TOKEN"

Response

{
  "items": [
    {
      "id": "0192f1e4-7c3a-7b2e-9f10-5d6c7e8f9a0b",
      "name": "string",
      "loyalty_points": 0,
      "rewards": [
        {
          "id": "0192f1e4-7c3a-7b2e-9f10-5d6c7e8f9a0b",
          "name": "string",
          "cost_points": 0,
          "discount_id": "0192f1e4-7c3a-7b2e-9f10-5d6c7e8f9a0b"
        }
      ],
      "tags": "string",
      "tier": {
        "current": {
          "id": "0192f1e4-7c3a-7b2e-9f10-5d6c7e8f9a0b",
          "name": "string",
          "earn_rate_percentage": "-12.5",
          "threshold_spend": {
            "amount": 1250,
            "currency": "GBP"
          },
          "threshold_visits": 0,
          "window_days": 0
        },
        "next": {
          "id": "0192f1e4-7c3a-7b2e-9f10-5d6c7e8f9a0b",
          "name": "string",
          "earn_rate_percentage": "-12.5",
          "threshold_spend": {
            "amount": 1250,
            "currency": "GBP"
          },
          "threshold_visits": 0,
          "window_days": 0
        },
        "spend_needed": {
          "amount": 1250,
          "currency": "GBP"
        },
        "visits_needed": 0
      },
      "version": 0
    }
  ],
  "location_participates": false,
  "offline_redemption_cap_points": 0,
  "rates": [
    {
      "point_value": {
        "amount": 1250,
        "currency": "GBP"
      },
      "points": 0,
      "spend": {
        "amount": 1250,
        "currency": "GBP"
      }
    }
  ]
}

GET/v1/customers/{id}

Get a guest

No. getCustomerAuth customers:read

Returns one guest's full record. This is the whole guest book entry, including the staff note, so it is only available to a signed-in person — a device token gets a 403. A till that wants to offer a redemption uses the search projection instead.

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 guest.
Customer · application/json
- idstring · uuid
  
  RequiredRead only
- namestring
  
  Required
  ≤ 200 chars
- allergiesarray of string
  
  RequiredRead only
  The allergies recorded on the guest's record, as free text.
- created_atstring · date-time
  
  RequiredRead only
- emailstring · email
  
  Nullable
- marketing_consentboolean
  
  NullableRead only
  The guest's latest word on marketing by email: granted, withdrawn, or null when never asked. Present on a guest read by its id.
- notestring
  A staff-only note about the guest, e.g. preferences or allergies.
- phonestring
  
  Nullable
  ≤ 64 chars
- preferencesarray of string
  
  RequiredRead only
  The preferences recorded on the guest's record, as free text.
- tagsarray of string
  
  RequiredRead only
  The labels the merchant files the guest under.
- text_marketing_consentboolean
  
  NullableRead only
  The guest's latest word on marketing by text, recorded separately from email: a guest may accept one and refuse the other. Present on a guest read by its id.
- updated_atstring · date-time
  
  RequiredRead only
- versioninteger · int64
  
  RequiredRead only
  The optimistic-concurrency version, used with If-Match.
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/customers/0192f1e4-7c3a-7b2e-9f10-5d6c7e8f9a0b' \
  -H "Authorization: Bearer $TOKEN"

Response

{
  "id": "0192f1e4-7c3a-7b2e-9f10-5d6c7e8f9a0b",
  "name": "string",
  "allergies": [
    "string"
  ],
  "created_at": "2026-09-11T09:30:00Z",
  "email": "ada@example.com",
  "marketing_consent": false,
  "note": "string",
  "phone": "string",
  "preferences": [
    "string"
  ],
  "tags": [
    "string"
  ],
  "text_marketing_consent": false,
  "updated_at": "2026-09-11T09:30:00Z",
  "version": 0
}

GET/v1/customers/{id}/export

Export one guest's data

No. getCustomersIDExportAuth customers:read

Returns one guest's data as a single JSON document — their record, every consent, the bookings and waitlist entries that name them, their loyalty statement, every order that names them with its lines, the cards linked to them, and the merges that folded duplicates into them. It is the GDPR "data on request" answer for one person.

Contact details are confidential and exportable, so this is owner and manager only — the same gate as the directory export and an erasure. A staff member gets a 403.

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 guest's data.
CustomerDataExport · application/json
- idstring · uuid
  
  RequiredRead only
- bookingsarray of CustomerBookingSummary
  
  The reservations that name the guest.
  - namestring
    
    Required
  - booking_idstring · uuid
    
    Required
  - party_sizeinteger · int32
    
    Required
  - starts_atstring · date-time
    
    Required
  - statusstring · enum
    
    Required
    confirmedseatedfinishedcanceledno_show
- card_fingerprintsarray of CustomerDataExportCardFingerprint
  
  The cards linked to the guest, with when each was first seen.
  - idstring · uuid
    
    RequiredRead only
  - created_atstring · date-time
    
    RequiredRead only
  - customer_idstring · uuid
    
    RequiredRead only
  - fingerprintstring
    
    Required
    The processor's card-alias token, never the card number.
- completeboolean
  
  RequiredRead only
  Whether this document holds everything held about the guest. The order history and the loyalty statement are each read up to a bound, so a guest with a very long history could exceed it; false says so. A subject-access answer that is short and does not say it is short is worse than one that does, because the person reading it cannot tell.
- consentsarray of CustomerDataExportConsent
  
  Every statement the guest made about consent, granted or withdrawn, with how and when — the whole history, not the latest state.
  - idstring · uuid
    
    RequiredRead only
  - created_atstring · date-time
    
    RequiredRead only
  - customer_idstring · uuid
    
    RequiredRead only
  - expires_atstring · date-time
    
    Read only
    When a grant lapsed, when one did. A later grant above it in the history is the refresh.
  - grantedboolean
    
    Required
  - occurred_atstring · date-time
    
    RequiredRead only
    When the guest said it. For a till's write, the till's own time.
  - purposestring · enum
    
    Required
    marketingtext_marketing
  - sourcestring
    
    Required
    How it was given, e.g. in_person or checkout.
    ≤ 64 chars
  - updated_atstring · date-time
    
    RequiredRead only
- customerCustomer
  
  Required
  A guest of the merchant, as the back office and a CRM see them. This is the full record — identity, contact and the staff note — and it is only returned to a signed-in person, never to a device. See CustomerLoyalty for the limited projection a till gets when it looks a guest up to redeem points.
  - idstring · uuid
    
    RequiredRead only
  - namestring
    
    Required
    ≤ 200 chars
  - allergiesarray of string
    
    RequiredRead only
    The allergies recorded on the guest's record, as free text.
  - created_atstring · date-time
    
    RequiredRead only
  - emailstring · email
    
    Nullable
  - marketing_consentboolean
    
    NullableRead only
    The guest's latest word on marketing by email: granted, withdrawn, or null when never asked. Present on a guest read by its id.
  - notestring
    A staff-only note about the guest, e.g. preferences or allergies.
  - phonestring
    
    Nullable
    ≤ 64 chars
  - preferencesarray of string
    
    RequiredRead only
    The preferences recorded on the guest's record, as free text.
  - tagsarray of string
    
    RequiredRead only
    The labels the merchant files the guest under.
  - text_marketing_consentboolean
    
    NullableRead only
    The guest's latest word on marketing by text, recorded separately from email: a guest may accept one and refuse the other. Present on a guest read by its id.
  - updated_atstring · date-time
    
    RequiredRead only
  - versioninteger · int64
    
    RequiredRead only
    The optimistic-concurrency version, used with If-Match.
- loyaltyCustomerDataExportLoyalty
  
  A guest's points balance and the movements behind it.
  - balanceinteger · int64
    
    Required
    Points still held, computed from the ledger.
  - entriesarray of CustomerDataExportLoyaltyEntry
    
    Required
    The recent movements, newest first.
    
    idstring · uuid
    
    RequiredRead only
    
    typestring · enum
    
    Required
    Why the balance moved. It never says which way; the sign of points does.
    earnredeemreverseadjustexpiredemote
    
    created_atstring · date-time
    
    RequiredRead only
    
    customer_idstring · uuid
    
    Read only
    
    notestring
    Why a manual adjustment happened; empty for a movement from an order.
    
    order_idstring · uuid
    
    Nullable
    The order that earned or spent the points; null for a manual adjustment.
    
    pointsinteger · int64
    
    Required
    The signed movement — positive added points, negative took them away. A guest's balance is the sum.
- mergesarray of CustomerDataExportMerge
  
  The merges that folded a duplicate guest into this one, or this one into a survivor.
  - idstring · uuid
    
    RequiredRead only
  - created_atstring · date-time
    
    RequiredRead only
  - duplicate_idstring · uuid
    
    RequiredRead only
  - merged_bystring · uuid
    
    Nullable
  - survivor_idstring · uuid
    
    RequiredRead only
- ordersarray of CustomerDataExportOrder
  
  Every order that names the guest, with its lines. Reads over the ledger, never a copy.
  - idstring · uuid
    
    RequiredRead only
  - currencyCurrency
    
    Required
    ISO 4217 currency code.
    Determines the minor unit that Money.amount is 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 CustomerDataExportOrderLine
    
    Required
    
    idstring · uuid
    
    RequiredRead only
    
    namestring
    
    Required
    Product name as 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})?$
    
    totalMoney
    
    Required
    A monetary amount in a specific currency: Square's Money, and Stripe's amount beside its currency.
    The amount is always an integer count of the currency's minor unit — pence for GBP, cents for USD. Zero-decimal currencies such as JPY have a minor unit equal to their major unit, so {"amount": 500, "currency": "JPY"} is ¥500 while {"amount": 500, "currency": "GBP"} is £5.00.
    Floating point is never used for money anywhere in this API. Binary floats cannot represent most decimal fractions exactly, so accumulating them across the line items of an order produces totals that disagree with the printed receipt by a penny. Integer minor units make every arithmetic operation exact.
    
    amountinteger · int64
    
    Required
    The amount, as a whole number of the currency's minor unit. May be negative to express a refund, discount or credit.
    
    currencyCurrency
    
    Required
    ISO 4217 currency code.
    Determines the minor unit that Money.amount is expressed in. Zero-decimal currencies such as JPY have a minor unit equal to the major unit.
    One of 182 values; see the schema.
    
    unit_priceMoney
    
    Required
    A monetary amount in a specific currency: Square's Money, and Stripe's amount beside its currency.
    The amount is always an integer count of the currency's minor unit — pence for GBP, cents for USD. Zero-decimal currencies such as JPY have a minor unit equal to their major unit, so {"amount": 500, "currency": "JPY"} is ¥500 while {"amount": 500, "currency": "GBP"} is £5.00.
    Floating point is never used for money anywhere in this API. Binary floats cannot represent most decimal fractions exactly, so accumulating them across the line items of an order produces totals that disagree with the printed receipt by a penny. Integer minor units make every arithmetic operation exact.
    
    amountinteger · int64
    
    Required
    The amount, as a whole number of the currency's minor unit. May be negative to express a refund, discount or credit.
    
    currencyCurrency
    
    Required
    ISO 4217 currency code.
    Determines the minor unit that Money.amount is expressed in. Zero-decimal currencies such as JPY have a minor unit equal to the major unit.
    One of 182 values; see the schema.
  - location_idstring · uuid
    
    RequiredRead only
  - location_namestring
    
    RequiredRead only
  - occurred_atstring · date-time
    
    RequiredRead only
  - referencestring
    The reference staff quote to find the sale.
  - statestring · enum
    
    Required
    opencompletedcanceledvoided
  - totalMoney
    
    Required
    A monetary amount in a specific currency: Square's Money, and Stripe's amount beside its currency.
    The amount is always an integer count of the currency's minor unit — pence for GBP, cents for USD. Zero-decimal currencies such as JPY have a minor unit equal to their major unit, so {"amount": 500, "currency": "JPY"} is ¥500 while {"amount": 500, "currency": "GBP"} is £5.00.
    Floating point is never used for money anywhere in this API. Binary floats cannot represent most decimal fractions exactly, so accumulating them across the line items of an order produces totals that disagree with the printed receipt by a penny. Integer minor units make every arithmetic operation exact.
    
    amountinteger · int64
    
    Required
    The amount, as a whole number of the currency's minor unit. May be negative to express a refund, discount or credit.
    
    currencyCurrency
    
    Required
    ISO 4217 currency code.
    Determines the minor unit that Money.amount is expressed in. Zero-decimal currencies such as JPY have a minor unit equal to the major unit.
    One of 182 values; see the schema.
- waitlistarray of CustomerDataExportWaitlistEntry
  
  The queue entries that name the guest.
  - idstring · uuid
    
    RequiredRead only
  - namestring
    
    Required
  - created_atstring · date-time
    
    RequiredRead only
  - customer_idstring · uuid
    
    Nullable
  - location_idstring · uuid
    
    RequiredRead only
  - notestring
  - party_sizeinteger · int32
    
    Required
  - phonestring
  - statusstring · enum
    
    Required
    waitingseatedleft
  - updated_atstring · date-time
    
    Read only
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/customers/0192f1e4-7c3a-7b2e-9f10-5d6c7e8f9a0b/export' \
  -H "Authorization: Bearer $TOKEN"

Response

{
  "id": "0192f1e4-7c3a-7b2e-9f10-5d6c7e8f9a0b",
  "bookings": [
    {
      "name": "string",
      "booking_id": "0192f1e4-7c3a-7b2e-9f10-5d6c7e8f9a0b",
      "party_size": 0,
      "starts_at": "2026-09-11T09:30:00Z",
      "status": "confirmed"
    }
  ],
  "card_fingerprints": [
    {
      "id": "0192f1e4-7c3a-7b2e-9f10-5d6c7e8f9a0b",
      "created_at": "2026-09-11T09:30:00Z",
      "customer_id": "0192f1e4-7c3a-7b2e-9f10-5d6c7e8f9a0b",
      "fingerprint": "string"
    }
  ],
  "complete": false,
  "consents": [
    {
      "id": "0192f1e4-7c3a-7b2e-9f10-5d6c7e8f9a0b",
      "created_at": "2026-09-11T09:30:00Z",
      "customer_id": "0192f1e4-7c3a-7b2e-9f10-5d6c7e8f9a0b",
      "expires_at": "2026-09-11T09:30:00Z",
      "granted": false,
      "occurred_at": "2026-09-11T09:30:00Z",
      "purpose": "marketing",
      "source": "string",
      "updated_at": "2026-09-11T09:30:00Z"
    }
  ],
  "customer": {
    "id": "0192f1e4-7c3a-7b2e-9f10-5d6c7e8f9a0b",
    "name": "string",
    "allergies": [
      "string"
    ],
    "created_at": "2026-09-11T09:30:00Z",
    "email": "ada@example.com",
    "marketing_consent": false,
    "note": "string",
    "phone": "string",
    "preferences": [
      "string"
    ],
    "tags": [
      "string"
    ],
    "text_marketing_consent": false,
    "updated_at": "2026-09-11T09:30:00Z",
    "version": 0
  },
  "loyalty": {
    "balance": 0,
    "entries": [
      {
        "id": "0192f1e4-7c3a-7b2e-9f10-5d6c7e8f9a0b",
        "type": "earn",
        "created_at": "2026-09-11T09:30:00Z",
        "customer_id": "0192f1e4-7c3a-7b2e-9f10-5d6c7e8f9a0b",
        "note": "string",
        "order_id": "0192f1e4-7c3a-7b2e-9f10-5d6c7e8f9a0b",
        "points": 0
      }
    ]
  },
  "merges": [
    {
      "id": "0192f1e4-7c3a-7b2e-9f10-5d6c7e8f9a0b",
      "created_at": "2026-09-11T09:30:00Z",
      "duplicate_id": "0192f1e4-7c3a-7b2e-9f10-5d6c7e8f9a0b",
      "merged_by": "0192f1e4-7c3a-7b2e-9f10-5d6c7e8f9a0b",
      "survivor_id": "0192f1e4-7c3a-7b2e-9f10-5d6c7e8f9a0b"
    }
  ],
  "orders": [
    {
      "id": "0192f1e4-7c3a-7b2e-9f10-5d6c7e8f9a0b",
      "currency": "AED",
      "lines": [
        {
          "id": "0192f1e4-7c3a-7b2e-9f10-5d6c7e8f9a0b",
          "name": "string",
          "quantity": "3",
          "total": {
            "amount": 1250,
            "currency": "GBP"
          },
          "unit_price": {
            "amount": 1250,
            "currency": "GBP"
          }
        }
      ],
      "location_id": "0192f1e4-7c3a-7b2e-9f10-5d6c7e8f9a0b",
      "location_name": "string",
      "occurred_at": "2026-09-11T09:30:00Z",
      "reference": "string",
      "state": "open",
      "total": {
        "amount": 1250,
        "currency": "GBP"
      }
    }
  ],
  "waitlist": [
    {
      "id": "0192f1e4-7c3a-7b2e-9f10-5d6c7e8f9a0b",
      "name": "string",
      "created_at": "2026-09-11T09:30:00Z",
      "customer_id": "0192f1e4-7c3a-7b2e-9f10-5d6c7e8f9a0b",
      "location_id": "0192f1e4-7c3a-7b2e-9f10-5d6c7e8f9a0b",
      "note": "string",
      "party_size": 0,
      "phone": "string",
      "status": "waiting",
      "updated_at": "2026-09-11T09:30:00Z"
    }
  ]
}

GET/v1/customers/{id}/history

Get a guest's history

No. getCustomerHistoryAuth customers:read

Returns a guest's derived history: the sales that name them, the reservations they hold, and their lifetime totals per currency. The history is a read over the ledger and the book — never a copy that can drift — so it always agrees with the merchant's reports. Totals cover the guest's whole history, not just the page.

A signed-in person or an integration with the customers:read scope may read it; a device token gets a 403, because history carries the staff note and a till does not need the guest book.

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 guest's history.
CustomerHistory · application/json
- bookingsarray of CustomerBookingSummary
  
  Required
  The reservations the guest holds.
  - namestring
    
    Required
  - booking_idstring · uuid
    
    Required
  - party_sizeinteger · int32
    
    Required
  - starts_atstring · date-time
    
    Required
  - statusstring · enum
    
    Required
    confirmedseatedfinishedcanceledno_show
- customer_idstring · uuid
  
  Required
- last_no_show_atstring · date-time
  
  RequiredNullable
  When the guest last did not arrive, or null when they never have.
- no_show_countinteger · int64
  
  Required
  How many bookings the guest has not arrived for, which a host acts on.
  ≥ 0
- ordersarray of CustomerOrderSummary
  
  Required
  The guest's completed sales, newest first, over the whole ledger (capped at the page size; the totals below are never capped).
  - currencyCurrency
    
    Required
    ISO 4217 currency code.
    Determines the minor unit that Money.amount is expressed in. Zero-decimal currencies such as JPY have a minor unit equal to the major unit.
    One of 182 values; see the schema.
  - occurred_atstring · date-time
    
    Required
  - order_idstring · uuid
    
    Required
  - referencestring
    
    Required
    The reference staff quote to find the sale.
  - statestring · enum
    
    Required
    opencompletedcanceledvoided
  - totalMoney
    
    Required
    A monetary amount in a specific currency: Square's Money, and Stripe's amount beside its currency.
    The amount is always an integer count of the currency's minor unit — pence for GBP, cents for USD. Zero-decimal currencies such as JPY have a minor unit equal to their major unit, so {"amount": 500, "currency": "JPY"} is ¥500 while {"amount": 500, "currency": "GBP"} is £5.00.
    Floating point is never used for money anywhere in this API. Binary floats cannot represent most decimal fractions exactly, so accumulating them across the line items of an order produces totals that disagree with the printed receipt by a penny. Integer minor units make every arithmetic operation exact.
    
    amountinteger · int64
    
    Required
    The amount, as a whole number of the currency's minor unit. May be negative to express a refund, discount or credit.
    
    currencyCurrency
    
    Required
    ISO 4217 currency code.
    Determines the minor unit that Money.amount is expressed in. Zero-decimal currencies such as JPY have a minor unit equal to the major unit.
    One of 182 values; see the schema.
- totalsarray of CustomerTotal
  
  Required
  Lifetime totals per currency, computed in SQL over the whole ledger. Empty when the guest has no completed sales.
  - currencyCurrency
    
    Required
    ISO 4217 currency code.
    Determines the minor unit that Money.amount is expressed in. Zero-decimal currencies such as JPY have a minor unit equal to the major unit.
    One of 182 values; see the schema.
  - spendMoney
    
    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.
  - visitsinteger · int32
    
    Required
    The guest's lifetime number of completed sales in this currency.
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/customers/0192f1e4-7c3a-7b2e-9f10-5d6c7e8f9a0b/history' \
  -H "Authorization: Bearer $TOKEN"

Response

{
  "bookings": [
    {
      "name": "string",
      "booking_id": "0192f1e4-7c3a-7b2e-9f10-5d6c7e8f9a0b",
      "party_size": 0,
      "starts_at": "2026-09-11T09:30:00Z",
      "status": "confirmed"
    }
  ],
  "customer_id": "0192f1e4-7c3a-7b2e-9f10-5d6c7e8f9a0b",
  "last_no_show_at": "2026-09-11T09:30:00Z",
  "no_show_count": 0,
  "orders": [
    {
      "currency": "AED",
      "occurred_at": "2026-09-11T09:30:00Z",
      "order_id": "0192f1e4-7c3a-7b2e-9f10-5d6c7e8f9a0b",
      "reference": "string",
      "state": "open",
      "total": {
        "amount": 1250,
        "currency": "GBP"
      }
    }
  ],
  "totals": [
    {
      "currency": "AED",
      "spend": {
        "amount": 1250,
        "currency": "GBP"
      },
      "visits": 0
    }
  ]
}

POST/v1/customers/{id}/loyalty/link

Mint a guest's loyalty link

No. createCustomerLoyaltyLinkAuth customers:read

Mints a fresh unguessable link for the guest, for a receipt to carry. Only the hash is stored, so a database dump yields no usable links; the presented token resolves back to this guest on the public statement page.

A till calls this when it links a guest so the receipt can carry the link. A person signed in to the back office may call it too, to reprint a link for a guest.

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 token, in the form a receipt link carries it.
LoyaltyCustomerLink · application/json
- tokenstring
  
  Required
  The unguessable token the link carries, which proves the guest.
- urlstring · uri
  
  Required
  The statement page on the guest site, token included, ready to print. Built by the server, because the guest site's address is the deployment's and a till cannot know it.
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/customers/0192f1e4-7c3a-7b2e-9f10-5d6c7e8f9a0b/loyalty/link' \
  -H "Authorization: Bearer $TOKEN"

Response

{
  "token": "string",
  "url": "https://example.com"
}

POST/v1/customers/{id}/loyalty/link/revoke

Cut every loyalty link a guest has

No. revokeCustomerLoyaltyLinkAuth customers:write

Withdraws every live receipt link to the guest's statement, so a guest who asks, or a member tidying up, can have them all cut at once. A person signed in to the back office.

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
Every link is cut.
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.

GET/v1/customers/{id}/serving-fields

Get the serving fields for a guest at this till's location

No. getCustomerServingFieldsAuth customers:read

The note, allergies and preferences a worker serving this guest needs. It answers for a guest who has an order at the calling device's location, and — when the device names the open sale or tab it is serving via order_id — for a guest the till is linking now, even on a first visit to this site and before the server holds an order naming them: the read is what a counter needs the moment a declared allergy matters. A device gets the search projection only: identity and loyalty. This read widens that to the guests this location has actually served, and to the guest on the open sale the device names, and no further. The note, allergies and preferences are the staff fields of the guest record; contact details stay role-gated.

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.
order_idquery · string · uuid
The open sale or tab the calling till is serving, so a guest being linked now — a first visit, before the server holds an order naming them — can be read. Must be an open order at the calling device's location.

Responses

200
The serving fields.
CustomerServingFields · application/json
- allergen_idsarray of string · uuid
  
  Read only
  The allergen vocabulary rows the declared allergies name, parallel to allergies. Identity, so a till matches a product's allergens by id and a vocabulary rename cannot drift a match; the words are display only. A declared word outside the vocabulary has no id here, and matches by word as before.
- allergiesarray of string
  
  Required
  The allergies recorded on the guest's record, as free text. Empty when the guest has none recorded.
- last_visitstring · date-time
  
  Read only
  The most recent completed sale naming this guest, in the server's clock. Absent when the guest has never completed a sale — an honest "nothing on file", never a reassuring date.
- notestring
  
  Required
  The staff note, empty when there is none.
  ≤ 200 chars
- preferencesarray of string
  
  Required
  The preferences recorded on the guest's record, as free text. Empty when the guest has none recorded.
- visitsinteger · int64
  
  Read only
  How many completed sales name this guest, derived over the ledger on the read. The host stand at the door acts on it (profiles-and-crm item 16); the till serves on it and cannot read the full history.
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/customers/0192f1e4-7c3a-7b2e-9f10-5d6c7e8f9a0b/serving-fields' \
  -H "Authorization: Bearer $TOKEN"

Response

{
  "allergen_ids": [
    "0192f1e4-7c3a-7b2e-9f10-5d6c7e8f9a0b"
  ],
  "allergies": [
    "string"
  ],
  "last_visit": "2026-09-11T09:30:00Z",
  "note": "string",
  "preferences": [
    "string"
  ],
  "visits": 0
}

GET/v1/locations/{id}/customer

Get the signed-in guest's page

No. getSignedInCustomerAuth bearer

What the signed-in guest sees of their own record at this business: their points, their upcoming bookings, the gift cards sold to them, whether they take news and offers, and whether allergies are on file, never which. An address the business has no guest for signs in to an empty page: signing in never makes a record. Signed out is a 401.

Parameters

idpath · string · uuid
Required
The location, by its id.

Responses

200
The guest's page.
SignedInCustomer · application/json
- namestring
  Their name as the business records it. Absent when it has no record.
- allergensarray of string
  
  Required
  The business's own list a guest declares allergies from.
- allergies_on_fileboolean
  
  Required
  Whether any allergies are recorded. Which ones never leaves the business.
- bookingsarray of CustomerBooking
  
  Required
  Their upcoming bookings here, soonest first.
  - idstring · uuid
    
    Required
  - party_sizeinteger
    
    Required
    ≥ 1
  - starts_atstring · date-time
    
    Required
  - statusstring · enum
    
    Required
    confirmedseatedfinishedcanceledno_show
- emailstring
  
  Required
  The address they signed in with.
- gift_cardsarray of CustomerGiftCard
  
  Required
  The gift cards sold to them here.
  - activeboolean
    
    Required
    Whether it can be spent.
  - balanceMoney
    
    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.
  - code_tailstring
    
    Required
    The last characters of the card's code.
- knownboolean
  
  Required
  Whether the business has a record for that address. Signing in never makes one.
- locationOrderLocation
  
  Required
  The location an order is collected from.
  - namestring
    
    Required
  - addressAddress
    
    A postal address.
    The address_line_* fields carry the most specific part of the address — street number, street name, building name. Less specific detail belongs in locality, administrative_district_level_* and country.
    The administrative_district_level_* fields are deliberately generic because their meaning is country-dependent: in the US level 1 is the state and level 2 the county; in the UK level 1 is the county.
    
    address_line_1string
    
    Required
    First line of the address — street number, street name, building name.
    ≤ 255 chars
    
    address_line_2string
    Second line of the address, if any.
    ≤ 255 chars
    
    address_line_3string
    Third line of the address, if any.
    ≤ 255 chars
    
    administrative_district_level_1string
    A civil entity within the country. The state in the US; the county in the UK.
    ≤ 128 chars
    
    administrative_district_level_2string
    A civil entity within administrative_district_level_1.
    ≤ 128 chars
    
    countryCountry
    
    Required
    ISO 3166-1 alpha-2 country code.
    ZZ is the unknown/unspecified placeholder.
    One of 250 values; see the schema.
    
    localitystring
    The city or town.
    ≤ 128 chars
    
    postal_codestring
    The postal or ZIP code.
    ≤ 32 chars
    
    sublocalitystring
    A civil region within the locality, if any.
    ≤ 128 chars
  - business_namestring
    
    Required
  - currencyCurrency
    ISO 4217 currency code.
    Determines the minor unit that Money.amount is expressed in. Zero-decimal currencies such as JPY have a minor unit equal to the major unit.
    One of 182 values; see the schema.
  - phone_numberstring
  - timezonestring
    
    Required
    The location's IANA time zone, which its clock times are told in.
- marketing_consentboolean
  
  Required
  Whether they take news and offers from the business by email.
- pointsCustomerPoints
  
  The guest's points, where the business runs a points programme.
  - balanceinteger · int64
    
    Required
  - entriesarray of CustomerPointsEntry
    
    Required
    The recent movements, newest first.
    
    typestring · enum
    
    Required
    Why the points moved. A demote carries no points; it records the guest falling a tier.
    earnredeemexpirereverseadjustdemote
    
    created_atstring · date-time
    
    Required
    
    location_namestring
    Where the sale behind it was rung. Absent for a movement with no sale.
    
    pointsinteger · int64
    
    Required
    The change, signed.
    
    reward_namestring
    The reward the points were spent on, for a redeem.
  - expiryCustomerPointsExpiry
    
    Required
    How the guest's points can lapse, so the page says so before they do. Zero means that rule is off.
    
    inactivity_daysinteger
    
    Required
    The whole balance lapses after this many days without earning.
    ≥ 0
    
    per_earn_daysinteger
    
    Required
    Points lapse this many days after they were earned.
    ≥ 0
  - rewardsarray of LoyaltyRewardOffer
    
    Required
    The rewards the balance covers now, cheapest first.
    
    namestring
    
    Required
    
    affordableboolean
    
    Required
    Whether the balance covers it now.
    
    cost_pointsinteger · int64
    
    Required
  - worthMoney
    
    A monetary amount in a specific currency: Square's Money, and Stripe's amount beside its currency.
    The amount is always an integer count of the currency's minor unit — pence for GBP, cents for USD. Zero-decimal currencies such as JPY have a minor unit equal to their major unit, so {"amount": 500, "currency": "JPY"} is ¥500 while {"amount": 500, "currency": "GBP"} is £5.00.
    Floating point is never used for money anywhere in this API. Binary floats cannot represent most decimal fractions exactly, so accumulating them across the 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.
- text_marketing_consentboolean
  Whether they take news and offers from the business by text.
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.
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/locations/0192f1e4-7c3a-7b2e-9f10-5d6c7e8f9a0b/customer' \
  -H "Authorization: Bearer $TOKEN"

Response

{
  "name": "string",
  "allergens": [
    "string"
  ],
  "allergies_on_file": false,
  "bookings": [
    {
      "id": "0192f1e4-7c3a-7b2e-9f10-5d6c7e8f9a0b",
      "party_size": 1,
      "starts_at": "2026-09-11T09:30:00Z",
      "status": "confirmed"
    }
  ],
  "email": "string",
  "gift_cards": [
    {
      "active": false,
      "balance": {
        "amount": 1250,
        "currency": "GBP"
      },
      "code_tail": "string"
    }
  ],
  "known": false,
  "location": {
    "name": "string",
    "address": {
      "address_line_1": "12 Bridge Street",
      "address_line_2": "string",
      "address_line_3": "string",
      "administrative_district_level_1": "Somerset",
      "administrative_district_level_2": "string",
      "country": "ZZ",
      "locality": "Bristol",
      "postal_code": "BS1 4ST",
      "sublocality": "string"
    },
    "business_name": "string",
    "currency": "AED",
    "phone_number": "string",
    "timezone": "string"
  },
  "marketing_consent": false,
  "points": {
    "balance": 0,
    "entries": [
      {
        "type": "earn",
        "created_at": "2026-09-11T09:30:00Z",
        "location_name": "string",
        "points": 0,
        "reward_name": "string"
      }
    ],
    "expiry": {
      "inactivity_days": 0,
      "per_earn_days": 0
    },
    "rewards": [
      {
        "name": "string",
        "affordable": false,
        "cost_points": 0
      }
    ],
    "worth": {
      "amount": 1250,
      "currency": "GBP"
    }
  },
  "text_marketing_consent": false
}

PATCH/v1/locations/{id}/customer

Change what the guest's record says about them

No. updateSignedInCustomerAuth bearer

Whether the guest takes news and offers from this business, and the allergies on file, chosen from the business's own list and replacing what was there; the page never reads them back. If-Match carries the page's ETag, so a change made from a page that has since moved is a 412. A guest the business has no record of has nothing to change (404).

Parameters

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

Request body application/merge-patch+json · CustomerUpdate

allergiesarray of string
Their allergies, from the page's allergens, replacing what was on file. Empty clears them.
≤ 100 items
marketing_consentboolean
Whether the business may send them news and offers by email.
text_marketing_consentboolean
Whether the business may send them news and offers by text.

Responses

200
The guest's page, changed.
SignedInCustomer · application/json
- namestring
  Their name as the business records it. Absent when it has no record.
- allergensarray of string
  
  Required
  The business's own list a guest declares allergies from.
- allergies_on_fileboolean
  
  Required
  Whether any allergies are recorded. Which ones never leaves the business.
- bookingsarray of CustomerBooking
  
  Required
  Their upcoming bookings here, soonest first.
  - idstring · uuid
    
    Required
  - party_sizeinteger
    
    Required
    ≥ 1
  - starts_atstring · date-time
    
    Required
  - statusstring · enum
    
    Required
    confirmedseatedfinishedcanceledno_show
- emailstring
  
  Required
  The address they signed in with.
- gift_cardsarray of CustomerGiftCard
  
  Required
  The gift cards sold to them here.
  - activeboolean
    
    Required
    Whether it can be spent.
  - balanceMoney
    
    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.
  - code_tailstring
    
    Required
    The last characters of the card's code.
- knownboolean
  
  Required
  Whether the business has a record for that address. Signing in never makes one.
- locationOrderLocation
  
  Required
  The location an order is collected from.
  - namestring
    
    Required
  - addressAddress
    
    A postal address.
    The address_line_* fields carry the most specific part of the address — street number, street name, building name. Less specific detail belongs in locality, administrative_district_level_* and country.
    The administrative_district_level_* fields are deliberately generic because their meaning is country-dependent: in the US level 1 is the state and level 2 the county; in the UK level 1 is the county.
    
    address_line_1string
    
    Required
    First line of the address — street number, street name, building name.
    ≤ 255 chars
    
    address_line_2string
    Second line of the address, if any.
    ≤ 255 chars
    
    address_line_3string
    Third line of the address, if any.
    ≤ 255 chars
    
    administrative_district_level_1string
    A civil entity within the country. The state in the US; the county in the UK.
    ≤ 128 chars
    
    administrative_district_level_2string
    A civil entity within administrative_district_level_1.
    ≤ 128 chars
    
    countryCountry
    
    Required
    ISO 3166-1 alpha-2 country code.
    ZZ is the unknown/unspecified placeholder.
    One of 250 values; see the schema.
    
    localitystring
    The city or town.
    ≤ 128 chars
    
    postal_codestring
    The postal or ZIP code.
    ≤ 32 chars
    
    sublocalitystring
    A civil region within the locality, if any.
    ≤ 128 chars
  - business_namestring
    
    Required
  - currencyCurrency
    ISO 4217 currency code.
    Determines the minor unit that Money.amount is expressed in. Zero-decimal currencies such as JPY have a minor unit equal to the major unit.
    One of 182 values; see the schema.
  - phone_numberstring
  - timezonestring
    
    Required
    The location's IANA time zone, which its clock times are told in.
- marketing_consentboolean
  
  Required
  Whether they take news and offers from the business by email.
- pointsCustomerPoints
  
  The guest's points, where the business runs a points programme.
  - balanceinteger · int64
    
    Required
  - entriesarray of CustomerPointsEntry
    
    Required
    The recent movements, newest first.
    
    typestring · enum
    
    Required
    Why the points moved. A demote carries no points; it records the guest falling a tier.
    earnredeemexpirereverseadjustdemote
    
    created_atstring · date-time
    
    Required
    
    location_namestring
    Where the sale behind it was rung. Absent for a movement with no sale.
    
    pointsinteger · int64
    
    Required
    The change, signed.
    
    reward_namestring
    The reward the points were spent on, for a redeem.
  - expiryCustomerPointsExpiry
    
    Required
    How the guest's points can lapse, so the page says so before they do. Zero means that rule is off.
    
    inactivity_daysinteger
    
    Required
    The whole balance lapses after this many days without earning.
    ≥ 0
    
    per_earn_daysinteger
    
    Required
    Points lapse this many days after they were earned.
    ≥ 0
  - rewardsarray of LoyaltyRewardOffer
    
    Required
    The rewards the balance covers now, cheapest first.
    
    namestring
    
    Required
    
    affordableboolean
    
    Required
    Whether the balance covers it now.
    
    cost_pointsinteger · int64
    
    Required
  - worthMoney
    
    A monetary amount in a specific currency: Square's Money, and Stripe's amount beside its currency.
    The amount is always an integer count of the currency's minor unit — pence for GBP, cents for USD. Zero-decimal currencies such as JPY have a minor unit equal to their major unit, so {"amount": 500, "currency": "JPY"} is ¥500 while {"amount": 500, "currency": "GBP"} is £5.00.
    Floating point is never used for money anywhere in this API. Binary floats cannot represent most decimal fractions exactly, so accumulating them across the 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.
- text_marketing_consentboolean
  Whether they take news and offers from the business by text.
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.
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.
500
Something failed on our side. trace_id identifies the request in our tracing — quote it in a support ticket.
The body never carries internal detail: no SQL, no stack traces, no upstream error strings. Safe to retry with the same Idempotency-Key.
503
Temporarily unable to serve the request — a dependency is down or the service is shedding load.
Retry with the same Idempotency-Key after Retry-After. This is always safe: a request that did take effect before the failure will be recognised as a replay.

Request

curl -X PATCH 'https://api.tenvelo.com/v1/locations/0192f1e4-7c3a-7b2e-9f10-5d6c7e8f9a0b/customer' \
  -H "Authorization: Bearer $TOKEN" \
  -H 'If-Match: "3"' \
  -H 'Content-Type: application/merge-patch+json' \
  -d '{
  "allergies": [
    "string"
  ],
  "marketing_consent": false,
  "text_marketing_consent": false
}'

Response

{
  "name": "string",
  "allergens": [
    "string"
  ],
  "allergies_on_file": false,
  "bookings": [
    {
      "id": "0192f1e4-7c3a-7b2e-9f10-5d6c7e8f9a0b",
      "party_size": 1,
      "starts_at": "2026-09-11T09:30:00Z",
      "status": "confirmed"
    }
  ],
  "email": "string",
  "gift_cards": [
    {
      "active": false,
      "balance": {
        "amount": 1250,
        "currency": "GBP"
      },
      "code_tail": "string"
    }
  ],
  "known": false,
  "location": {
    "name": "string",
    "address": {
      "address_line_1": "12 Bridge Street",
      "address_line_2": "string",
      "address_line_3": "string",
      "administrative_district_level_1": "Somerset",
      "administrative_district_level_2": "string",
      "country": "ZZ",
      "locality": "Bristol",
      "postal_code": "BS1 4ST",
      "sublocality": "string"
    },
    "business_name": "string",
    "currency": "AED",
    "phone_number": "string",
    "timezone": "string"
  },
  "marketing_consent": false,
  "points": {
    "balance": 0,
    "entries": [
      {
        "type": "earn",
        "created_at": "2026-09-11T09:30:00Z",
        "location_name": "string",
        "points": 0,
        "reward_name": "string"
      }
    ],
    "expiry": {
      "inactivity_days": 0,
      "per_earn_days": 0
    },
    "rewards": [
      {
        "name": "string",
        "affordable": false,
        "cost_points": 0
      }
    ],
    "worth": {
      "amount": 1250,
      "currency": "GBP"
    }
  },
  "text_marketing_consent": false
}

POST/v1/locations/{id}/customer/bookings/{booking_id}/cancel

Cancel one of the signed-in guest's bookings

No. cancelCustomerBookingAuth bearer

Cancels an upcoming booking the signed-in guest holds here. One that isn't theirs, or isn't here, is a 404; one already seated can't be canceled (409).

Parameters

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

Responses

200
The booking, canceled.
CustomerBooking · application/json
- idstring · uuid
  
  Required
- party_sizeinteger
  
  Required
  ≥ 1
- starts_atstring · date-time
  
  Required
- statusstring · enum
  
  Required
  confirmedseatedfinishedcanceledno_show
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.
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/locations/0192f1e4-7c3a-7b2e-9f10-5d6c7e8f9a0b/customer/bookings/0192f1e4-7c3a-7b2e-9f10-5d6c7e8f9a0b/cancel' \
  -H "Authorization: Bearer $TOKEN" \
  -H 'Idempotency-Key: 01J8ZK3QF7X2N5V9C4B1A6D8E0'

Response

{
  "id": "0192f1e4-7c3a-7b2e-9f10-5d6c7e8f9a0b",
  "party_size": 1,
  "starts_at": "2026-09-11T09:30:00Z",
  "status": "confirmed"
}

POST/v1/locations/{id}/customer/bookings/{booking_id}/reschedule

Move one of the signed-in guest's bookings

No. rescheduleCustomerBookingAuth bearer

Moves an upcoming booking the signed-in guest holds here to another time or party size. The time is one GET /v1/booking-times offers for the size asked, checked again here, so one taken since the guest looked is a 422 on starts_at.

Parameters

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

Request body application/json · BookingReschedule

party_sizeinteger

Required
1–100
starts_atstring · date-time

Required
One of the times GET /v1/locations/{id}/booking-times offers for this party size.

Responses

200
The booking, moved.
CustomerBooking · application/json
- idstring · uuid
  
  Required
- party_sizeinteger
  
  Required
  ≥ 1
- starts_atstring · date-time
  
  Required
- statusstring · enum
  
  Required
  confirmedseatedfinishedcanceledno_show
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.
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.
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/locations/0192f1e4-7c3a-7b2e-9f10-5d6c7e8f9a0b/customer/bookings/0192f1e4-7c3a-7b2e-9f10-5d6c7e8f9a0b/reschedule' \
  -H "Authorization: Bearer $TOKEN" \
  -H 'Idempotency-Key: 01J8ZK3QF7X2N5V9C4B1A6D8E0' \
  -H 'Content-Type: application/json' \
  -d '{
  "party_size": 1,
  "starts_at": "2026-09-11T09:30:00Z"
}'

Response

{
  "id": "0192f1e4-7c3a-7b2e-9f10-5d6c7e8f9a0b",
  "party_size": 1,
  "starts_at": "2026-09-11T09:30:00Z",
  "status": "confirmed"
}

POST/v1/platform-unsubscribes

Stop the platform's own emails to an address

No. createPlatformUnsubscribeAuth no token

What the link at the foot of the platform's own email does: setup tips, reminders and the like stop going to that address, everywhere. A business's mail to its guests isn't the platform's and is untouched (0060). Public by design: the link is the credential, an address with the platform's signature over it, so a wrong or tampered one is a 404 that says nothing about the address. Asking again is the same answer.

Parameters

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

Request body application/json · PlatformUnsubscribeCreate

sigstring

Required
The platform's signature over the address, in hex.
≤ 128 chars
tostring

Required
The address the email went to.
≤ 254 chars

Responses

204
The address gets no more of the platform's own email.
400
The request could not be parsed. Malformed JSON, a bad query parameter, or a header that failed to decode, among them an API-Version later than the server speaks or not a date (api-version-unknown, with the server's own in api_version).
Distinct from 422: a 400 never reached validation, so invalid_params is absent. Retrying without changing the request will fail again, except that a request refused for its API-Version goes once the server is updated.
401
No credentials, or credentials that could not be verified — missing bearer token, malformed JWT, expired token, or a signature that failed against the issuer's JWKS.
Refresh the token and retry once. Repeated 401 after a refresh means the device needs to re-enrol.
403
Authenticated, but not permitted. The token is valid and its merchant was resolved, but the caller's role does not allow this operation, or the target belongs to a different merchant.
Cross-tenant access is reported as 403 on a resource the caller may not see, and as 404 where even confirming existence would leak information. Retrying will not help.
404
No such resource, or none visible to this caller.
Also returned instead of 403 where acknowledging existence would itself leak information — so a 404 does not prove the id is unused globally, only that it is not yours.
410
The request names an API-Version this server no longer serves (docs/decisions/0011). Nothing in it was read. api_version names the version the server speaks: the client is behind, and sends the request again once it is updated.
415
The request Content-Type is not supported. This API accepts application/json on all mutations.
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/platform-unsubscribes' \
  -H 'Idempotency-Key: 01J8ZK3QF7X2N5V9C4B1A6D8E0' \
  -H 'Content-Type: application/json' \
  -d '{
  "sig": "string",
  "to": "string"
}'

GET/v1/reports/customers.csv

Export the guest book as CSV

No. getReportsCustomersCSVAuth customers:read

Streams every guest with their contact details, note, tags, allergies and preferences. Contact details are confidential, so only an owner or a manager may export them.

Responses

200
The guest book, one row per guest.
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.

GET/v1/reports/lapsed-customers

List the regulars who have stopped coming

No. listLapsedCustomersAuth customers:read

Guests with at least min_visits completed sales whose last one is older than days, most recently seen first: who to welcome back. Derived over the ledger, never stored. A staff member sees the guests without their contact details. Paged with the cursor of the previous page.

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.
daysquery · integer · int32
How long since the last visit makes a regular lapsed, in days.
min_visitsquery · integer · int32
How many completed sales make a guest a regular.

Responses

200
A page of lapsed regulars.
LapsedCustomerPage · application/json
- has_moreboolean
  
  Required
  Whether another page may follow.
- itemsarray of LapsedCustomer
  
  Required
  - namestring
    
    Required
  - customer_idstring · uuid
    
    Required
  - emailstring
    
    RequiredNullable
    Null when there is none, or the caller may not see guests' contact details.
  - last_visit_atstring · date-time
    
    Required
  - phonestring
    
    RequiredNullable
    Null when there is none, or the caller may not see guests' contact details.
  - visitsinteger · int64
    
    Required
    Completed sales the guest has made.
- 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.

Request

curl -X GET 'https://api.tenvelo.com/v1/reports/lapsed-customers' \
  -H "Authorization: Bearer $TOKEN"

Response

{
  "has_more": false,
  "items": [
    {
      "name": "string",
      "customer_id": "0192f1e4-7c3a-7b2e-9f10-5d6c7e8f9a0b",
      "email": "string",
      "last_visit_at": "2026-09-11T09:30:00Z",
      "phone": "string",
      "visits": 0
    }
  ],
  "next_cursor": "string"
}

GET/v1/segments

List the guest segments

No. listSegmentsAuth customers:read

The business's saved segments by name, each with how many guests it matches now. A segment is a rule evaluated on read, never a stored list, so the count is shown before anything is done with it. An owner or a manager. Paged with the cursor of the previous page.

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 segments.
SegmentPage · application/json
- has_moreboolean
  
  Required
  Whether another page may follow.
- itemsarray of Segment
  
  Required
  - idstring · uuid
    
    Required
  - namestring
    
    Required
  - created_atstring · date-time
    
    Required
  - customer_countinteger · int64
    
    Required
    How many guests the rule matches now.
    ≥ 0
  - definitionSegmentDefinition
    
    Required
    The criteria a guest must meet to be in the segment, every one named. Only completed sales count, and spend is in the sale's currency with gift cards left out.
    
    allergen_idsarray of string · uuid
    The guest has declared these allergens.
    
    has_loyalty_balanceboolean
    The guest holds points.
    
    last_visit_older_than_daysinteger · int32
    The guest's last completed sale is older than this many days.
    ≥ 1
    
    location_idstring · uuid
    The guest has bought at this location.
    
    spendobject
    
    Completed sales in the last days totalling at least at_least, in its currency.
    
    at_leastMoney
    
    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.
    
    daysinteger · int32
    
    Required
    ≥ 1
    
    tagstring
    The guest is filed under this tag.
    ≥ 1 chars
    
    visitsobject
    
    At least at_least completed sales in the last days.
    
    at_leastinteger · int64
    
    Required
    ≥ 1
    
    daysinteger · int32
    
    Required
    ≥ 1
  - versioninteger · int64
    
    Required
    Always 1; a segment is never edited.
- 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.

Request

curl -X GET 'https://api.tenvelo.com/v1/segments' \
  -H "Authorization: Bearer $TOKEN"

Response

{
  "has_more": false,
  "items": [
    {
      "id": "0192f1e4-7c3a-7b2e-9f10-5d6c7e8f9a0b",
      "name": "string",
      "created_at": "2026-09-11T09:30:00Z",
      "customer_count": 0,
      "definition": {
        "allergen_ids": [
          "0192f1e4-7c3a-7b2e-9f10-5d6c7e8f9a0b"
        ],
        "has_loyalty_balance": false,
        "last_visit_older_than_days": 1,
        "location_id": "0192f1e4-7c3a-7b2e-9f10-5d6c7e8f9a0b",
        "spend": {
          "at_least": {
            "amount": 1250,
            "currency": "GBP"
          },
          "days": 1
        },
        "tag": "string",
        "visits": {
          "at_least": 1,
          "days": 1
        }
      },
      "version": 0
    }
  ],
  "next_cursor": "string"
}

POST/v1/segments/batch-create

Save guest segments

No. batchCreateSegmentsAuth customers:write

Saves segment definitions under the ids the caller minted: the criteria every guest in it must meet, at least one of them. A definition is never edited; a segment already saved under the id is unchanged. An owner or a manager.

Request body application/json · SegmentBatchCreateRequest

itemsarray of SegmentBatchCreateItem

Required
≥ 1 items · ≤ 50 items
- idstring · uuid
  
  Required
- namestring
  
  Required
  1–120 chars
- definitionSegmentDefinition
  
  Required
  The criteria a guest must meet to be in the segment, every one named. Only completed sales count, and spend is in the sale's currency with gift cards left out.
  - allergen_idsarray of string · uuid
    The guest has declared these allergens.
  - has_loyalty_balanceboolean
    The guest holds points.
  - last_visit_older_than_daysinteger · int32
    The guest's last completed sale is older than this many days.
    ≥ 1
  - location_idstring · uuid
    The guest has bought at this location.
  - spendobject
    
    Completed sales in the last days totalling at least at_least, in its currency.
    
    at_leastMoney
    
    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.
    
    daysinteger · int32
    
    Required
    ≥ 1
  - tagstring
    The guest is filed under this tag.
    ≥ 1 chars
  - visitsobject
    
    At least at_least completed sales in the last days.
    
    at_leastinteger · int64
    
    Required
    ≥ 1
    
    daysinteger · int32
    
    Required
    ≥ 1
- idempotency_keyItemIdempotencyKey
  
  Required
  A key for one item in a batch, minted by the client when it queues the item and reused on every attempt to send it. The item, not the request, is the unit of work: a retried batch returns the stored result for every item already applied under its key. A fresh key per attempt defeats the whole mechanism.
  Scoped per merchant, so keys need only be unique within a merchant's own traffic.
  16–255 chars

Responses

200
The batch was processed. results says what happened to each item.
BatchResponse · application/json
- resultsarray of BatchResult
  
  Required
  - idstring · uuid
    The resource the item created or changed. Absent when it failed.
  - idempotency_keystring
    
    Required
    The item's key, echoed so a result can be matched by key as well as position.
  - problemProblem
    
    Nullable
    Why the item failed, as an RFC 9457 problem. A 422 means the item is malformed and will never succeed — drop it and show it to staff rather than retrying for ever. A 409 or a 5xx means try again later.
    
    typestring · uri
    
    Required
    A stable URI identifying the problem kind. This is the field to branch on.
    default about:blank
    
    api_versionstring
    Present on an api-version-retired or api-version-unknown refusal: the API-Version this server speaks (docs/decisions/0011).
    
    detailstring
    A human-readable explanation specific to this occurrence. Safe to show to a developer; never contains internal state, SQL, or stack traces.
    
    instancestring · uri-reference
    A URI reference identifying the specific occurrence.
    
    invalid_paramsarray of InvalidParam
    
    Present on 422 responses. Lists every field that failed validation, rather than only the first, so a client can highlight an entire form in one pass.
    
    codestring
    Stable machine-readable code for this failure, for clients that localise their own messages rather than showing reason.
    
    pointerstring
    
    Required
    RFC 6901 JSON Pointer to the offending value within the request body. A pointer rather than a field name so that failures nested inside arrays — the third line item of an order — are addressable at all.
    
    reasonstring
    
    Required
    Why this value was rejected, in human-readable form.
    
    refusalsarray of Location refusal
    
    Present on 409 responses to a withdrawal refused by the state it depends on (deleting a location with tills still assigned, open orders, …). Lists every reason at once, each with how much stands in the way, so a client can say what to put right and link to it rather than walking a person through one refusal after another.
    
    kindstring
    
    Required
    A stable refusal kind — devices, open_orders, drawer_sessions, bookings or stock — that a client links to the screen that puts it right. Branch on this field, never on the surrounding prose.
    
    countinteger
    
    Required
    How many things stand in the way of the withdrawal, so a client can repeat the number rather than re-read prose.
    ≥ 1
    
    statusinteger
    
    Required
    The HTTP status code, repeated here so the body is self-contained.
    100–599
    
    titlestring
    
    Required
    A short, human-readable summary of the problem kind.
    
    trace_idstring
    The OpenTelemetry trace id for this request. Quote it in a support ticket and the whole request can be pulled up.
  - statusstring · enum
    
    Required
    created — the item made a new resource. updated — it changed an existing one.
    unchanged — this key was already applied and the original outcome stands. A success, not an error: it is what a client retrying a batch it was unsure landed should expect, and it clears the item from its queue exactly as created does.
    failed — the item was refused, and nothing else in the batch was affected. See problem.
    createdupdatedunchangedfailed
  - versioninteger · int64
    The resource's version after the item. Absent when it failed.
400
The request could not be parsed. Malformed JSON, a bad query parameter, or a header that failed to decode, among them an API-Version later than the server speaks or not a date (api-version-unknown, with the server's own in api_version).
Distinct from 422: a 400 never reached validation, so invalid_params is absent. Retrying without changing the request will fail again, except that a request refused for its API-Version goes once the server is updated.
401
No credentials, or credentials that could not be verified — missing bearer token, malformed JWT, expired token, or a signature that failed against the issuer's JWKS.
Refresh the token and retry once. Repeated 401 after a refresh means the device needs to re-enrol.
403
Authenticated, but not permitted. The token is valid and its merchant was resolved, but the caller's role does not allow this operation, or the target belongs to a different merchant.
Cross-tenant access is reported as 403 on a resource the caller may not see, and as 404 where even confirming existence would leak information. Retrying will not help.
410
The request names an API-Version this server no longer serves (docs/decisions/0011). Nothing in it was read. api_version names the version the server speaks: the client is behind, and sends the request again once it is updated.
415
The request Content-Type is not supported. This API accepts application/json on all mutations.
422
The request parsed but failed validation.
invalid_params lists every failing field with a JSON Pointer, not just the first, so a client can mark up a whole form in one pass rather than making the user fix errors one round trip at a time.
Also returned when an Idempotency-Key is replayed with a different body, and when device-computed order totals disagree with the server's recomputation.
429
Rate limit exceeded. Honour Retry-After rather than applying your own backoff.
A fleet of tills coming back online together after an outage is the realistic cause, which is exactly when uncoordinated client-side retry turns a brief outage into a sustained one. The limit is per process, and per site for what records trade there — a request spends its site's budget, and a till's own smaller one inside it — and per (client, merchant) for everything else; no RateLimit field is sent, so this response and its Retry-After are the whole of the contract.
500
Something failed on our side. trace_id identifies the request in our tracing — quote it in a support ticket.
The body never carries internal detail: no SQL, no stack traces, no upstream error strings. Safe to retry with the same Idempotency-Key.

Request

curl -X POST 'https://api.tenvelo.com/v1/segments/batch-create' \
  -H "Authorization: Bearer $TOKEN" \
  -H 'Content-Type: application/json' \
  -d '{
  "items": [
    {
      "id": "0192f1e4-7c3a-7b2e-9f10-5d6c7e8f9a0b",
      "name": "string",
      "definition": {
        "allergen_ids": [
          "0192f1e4-7c3a-7b2e-9f10-5d6c7e8f9a0b"
        ],
        "has_loyalty_balance": false,
        "last_visit_older_than_days": 1,
        "location_id": "0192f1e4-7c3a-7b2e-9f10-5d6c7e8f9a0b",
        "spend": {
          "at_least": {
            "amount": 1250,
            "currency": "GBP"
          },
          "days": 1
        },
        "tag": "string",
        "visits": {
          "at_least": 1,
          "days": 1
        }
      },
      "idempotency_key": "01J8ZK3QF7X2N5V9C4B1A6D8E0"
    }
  ]
}'

Response

{
  "results": [
    {
      "id": "0192f1e4-7c3a-7b2e-9f10-5d6c7e8f9a0b",
      "idempotency_key": "string",
      "problem": {
        "type": "https://api.tenvelo.com/problems/version-conflict",
        "api_version": "2026-10-10",
        "detail": "The product has been modified since version 7 was read.",
        "instance": "/v1/products/0195f8c7-4a1e-7c3b-9f22-8d4e6a1b2c3d",
        "invalid_params": [
          {
            "code": "minimum",
            "pointer": "/line_items/0/quantity",
            "reason": "must be greater than or equal to 1"
          }
        ],
        "refusals": [
          {
            "kind": "devices",
            "count": 3
          }
        ],
        "status": 412,
        "title": "Version conflict",
        "trace_id": "4bf92f3577b34da6a3ce929d0e0e4736"
      },
      "status": "created",
      "version": 0
    }
  ]
}

DELETE/v1/segments/{id}

Delete a guest segment

No. deleteSegmentAuth customers:write

Removes a saved definition. The guests it matched are untouched; the list was never stored. A segment is never edited, so its version is always 1. An owner or a manager.

Parameters

idpath · string · uuid
Required
UUIDv7 of the resource.
For resources a device can originate — orders, and their line items — this id is minted by the client before the record is ever synced, which is what makes an offline create idempotent.
If-Matchheader · string
Required
The ETag from the read that produced the value you are updating.
Required on updates, not optional, because "last write wins" is the wrong default for a catalogue two managers might edit at once. If anything has been written since your read, the request is rejected with 412 and you re-read and re-apply.
Use * to mean "write regardless of current version" — an explicit, greppable override rather than the silent default.

Responses

204
The segment is deleted.
400
The request could not be parsed. Malformed JSON, a bad query parameter, or a header that failed to decode, among them an API-Version later than the server speaks or not a date (api-version-unknown, with the server's own in api_version).
Distinct from 422: a 400 never reached validation, so invalid_params is absent. Retrying without changing the request will fail again, except that a request refused for its API-Version goes once the server is updated.
401
No credentials, or credentials that could not be verified — missing bearer token, malformed JWT, expired token, or a signature that failed against the issuer's JWKS.
Refresh the token and retry once. Repeated 401 after a refresh means the device needs to re-enrol.
403
Authenticated, but not permitted. The token is valid and its merchant was resolved, but the caller's role does not allow this operation, or the target belongs to a different merchant.
Cross-tenant access is reported as 403 on a resource the caller may not see, and as 404 where even confirming existence would leak information. Retrying will not help.
404
No such resource, or none visible to this caller.
Also returned instead of 403 where acknowledging existence would itself leak information — so a 404 does not prove the id is unused globally, only that it is not yours.
410
The request names an API-Version this server no longer serves (docs/decisions/0011). Nothing in it was read. api_version names the version the server speaks: the client is behind, and sends the request again once it is updated.
412
The If-Match version did not match the resource's current version: someone else wrote since you read.
This is the expected, healthy outcome of two clients editing the same record — not an error condition to suppress. Re-read the resource, re-apply your change on top of the new state, and retry with the fresh ETag.
429
Rate limit exceeded. Honour Retry-After rather than applying your own backoff.
A fleet of tills coming back online together after an outage is the realistic cause, which is exactly when uncoordinated client-side retry turns a brief outage into a sustained one. The limit is per process, and per site for what records trade there — a request spends its site's budget, and a till's own smaller one inside it — and per (client, merchant) for everything else; no RateLimit field is sent, so this response and its Retry-After are the whole of the contract.
500
Something failed on our side. trace_id identifies the request in our tracing — quote it in a support ticket.
The body never carries internal detail: no SQL, no stack traces, no upstream error strings. Safe to retry with the same Idempotency-Key.

POST/v1/sign-in-codes

Email a guest a sign-in code

No. createSignInCodeAuth no token

Emails a six-digit code to the address given, which proves the guest can read it: there is no password (0037 §3). The answer names the code to verify, and is the same whether or not the business knows the address, so it says nothing about who its guests are. Rate limited per client address and per email address.

Parameters

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

Request body application/json · SignInCodeCreate

emailstring · email

Required
≤ 254 chars
location_idstring · uuid

Required
The location the guest is signing in at; the session is its business's.

Responses

201
A code is on its way, if the address can take email.
SignInCode · application/json
- idstring · uuid
  
  Required
400
The request could not be parsed. Malformed JSON, a bad query parameter, or a header that failed to decode, among them an API-Version later than the server speaks or not a date (api-version-unknown, with the server's own in api_version).
Distinct from 422: a 400 never reached validation, so invalid_params is absent. Retrying without changing the request will fail again, except that a request refused for its API-Version goes once the server is updated.
401
No credentials, or credentials that could not be verified — missing bearer token, malformed JWT, expired token, or a signature that failed against the issuer's JWKS.
Refresh the token and retry once. Repeated 401 after a refresh means the device needs to re-enrol.
403
Authenticated, but not permitted. The token is valid and its merchant was resolved, but the caller's role does not allow this operation, or the target belongs to a different merchant.
Cross-tenant access is reported as 403 on a resource the caller may not see, and as 404 where even confirming existence would leak information. Retrying will not help.
404
No such resource, or none visible to this caller.
Also returned instead of 403 where acknowledging existence would itself leak information — so a 404 does not prove the id is unused globally, only that it is not yours.
410
The request names an API-Version this server no longer serves (docs/decisions/0011). Nothing in it was read. api_version names the version the server speaks: the client is behind, and sends the request again once it is updated.
415
The request Content-Type is not supported. This API accepts application/json on all mutations.
422
The request parsed but failed validation.
invalid_params lists every failing field with a JSON Pointer, not just the first, so a client can mark up a whole form in one pass rather than making the user fix errors one round trip at a time.
Also returned when an Idempotency-Key is replayed with a different body, and when device-computed order totals disagree with the server's recomputation.
429
Rate limit exceeded. Honour Retry-After rather than applying your own backoff.
A fleet of tills coming back online together after an outage is the realistic cause, which is exactly when uncoordinated client-side retry turns a brief outage into a sustained one. The limit is per process, and per site for what records trade there — a request spends its site's budget, and a till's own smaller one inside it — and per (client, merchant) for everything else; no RateLimit field is sent, so this response and its Retry-After are the whole of the contract.
500
Something failed on our side. trace_id identifies the request in our tracing — quote it in a support ticket.
The body never carries internal detail: no SQL, no stack traces, no upstream error strings. Safe to retry with the same Idempotency-Key.
503
Temporarily unable to serve the request — a dependency is down or the service is shedding load.
Retry with the same Idempotency-Key after Retry-After. This is always safe: a request that did take effect before the failure will be recognised as a replay.

Request

curl -X POST 'https://api.tenvelo.com/v1/sign-in-codes' \
  -H 'Idempotency-Key: 01J8ZK3QF7X2N5V9C4B1A6D8E0' \
  -H 'Content-Type: application/json' \
  -d '{
  "email": "ada@example.com",
  "location_id": "0192f1e4-7c3a-7b2e-9f10-5d6c7e8f9a0b"
}'

Response

{
  "id": "0192f1e4-7c3a-7b2e-9f10-5d6c7e8f9a0b"
}

POST/v1/sign-in-codes/{id}/verify

Sign a guest in with their code

No. verifySignInCodeAuth no token

Checks the code a guest was emailed and, if it matches and is still good, signs them in at the location's business: the answer is the session, a bearer token for the operations that name the customerSession scheme (docs/decisions/0113 §4). The guest site keeps it for the tab (§5). A wrong or expired code is a 422 on code. Rate limited per client address.

Parameters

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

Request body application/json · SignInCodeVerify

codestring

Required
1–12 chars
location_idstring · uuid

Required
The location the guest is signing in at; the session is its business's.

Responses

200
Signed in.
CustomerSession · application/json
- expires_atstring · date-time
  
  Required
  When the session ends unless the guest signs out first.
- tokenstring
  
  Required
  The session's bearer token. Opaque, and kept hashed, so ending the session ends it at once.
400
The request could not be parsed. Malformed JSON, a bad query parameter, or a header that failed to decode, among them an API-Version later than the server speaks or not a date (api-version-unknown, with the server's own in api_version).
Distinct from 422: a 400 never reached validation, so invalid_params is absent. Retrying without changing the request will fail again, except that a request refused for its API-Version goes once the server is updated.
401
No credentials, or credentials that could not be verified — missing bearer token, malformed JWT, expired token, or a signature that failed against the issuer's JWKS.
Refresh the token and retry once. Repeated 401 after a refresh means the device needs to re-enrol.
403
Authenticated, but not permitted. The token is valid and its merchant was resolved, but the caller's role does not allow this operation, or the target belongs to a different merchant.
Cross-tenant access is reported as 403 on a resource the caller may not see, and as 404 where even confirming existence would leak information. Retrying will not help.
404
No such resource, or none visible to this caller.
Also returned instead of 403 where acknowledging existence would itself leak information — so a 404 does not prove the id is unused globally, only that it is not yours.
410
The request names an API-Version this server no longer serves (docs/decisions/0011). Nothing in it was read. api_version names the version the server speaks: the client is behind, and sends the request again once it is updated.
415
The request Content-Type is not supported. This API accepts application/json on all mutations.
422
The request parsed but failed validation.
invalid_params lists every failing field with a JSON Pointer, not just the first, so a client can mark up a whole form in one pass rather than making the user fix errors one round trip at a time.
Also returned when an Idempotency-Key is replayed with a different body, and when device-computed order totals disagree with the server's recomputation.
429
Rate limit exceeded. Honour Retry-After rather than applying your own backoff.
A fleet of tills coming back online together after an outage is the realistic cause, which is exactly when uncoordinated client-side retry turns a brief outage into a sustained one. The limit is per process, and per site for what records trade there — a request spends its site's budget, and a till's own smaller one inside it — and per (client, merchant) for everything else; no RateLimit field is sent, so this response and its Retry-After are the whole of the contract.
500
Something failed on our side. trace_id identifies the request in our tracing — quote it in a support ticket.
The body never carries internal detail: no SQL, no stack traces, no upstream error strings. Safe to retry with the same Idempotency-Key.
503
Temporarily unable to serve the request — a dependency is down or the service is shedding load.
Retry with the same Idempotency-Key after Retry-After. This is always safe: a request that did take effect before the failure will be recognised as a replay.

Request

curl -X POST 'https://api.tenvelo.com/v1/sign-in-codes/0192f1e4-7c3a-7b2e-9f10-5d6c7e8f9a0b/verify' \
  -H 'Idempotency-Key: 01J8ZK3QF7X2N5V9C4B1A6D8E0' \
  -H 'Content-Type: application/json' \
  -d '{
  "code": "string",
  "location_id": "0192f1e4-7c3a-7b2e-9f10-5d6c7e8f9a0b"
}'

Response

{
  "expires_at": "2026-09-11T09:30:00Z",
  "token": "string"
}

POST/v1/suppression-lifts/batch-create

Record that guests asked to hear from the business again

No. batchCreateSuppressionLiftsAuth customers:write

Each item lifts the suppressions it names, the ones the manager was shown, and no others: one recorded since stands. Every suppression is kept; the lift is a fact beside it. It overrides what a guest said, so it is an owner's or a manager's decision. An item that names nothing still in force is unchanged.

Request body application/json · SuppressionLiftBatchCreateRequest

itemsarray of SuppressionLiftBatchCreateItem

Required
≥ 1 items · ≤ 100 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
- suppression_idsarray of string · uuid
  
  Required
  ≥ 1 items · ≤ 50 items

Responses

200
The batch was processed. results says what happened to each item.
BatchResponse · application/json
- resultsarray of BatchResult
  
  Required
  - idstring · uuid
    The resource the item created or changed. Absent when it failed.
  - idempotency_keystring
    
    Required
    The item's key, echoed so a result can be matched by key as well as position.
  - problemProblem
    
    Nullable
    Why the item failed, as an RFC 9457 problem. A 422 means the item is malformed and will never succeed — drop it and show it to staff rather than retrying for ever. A 409 or a 5xx means try again later.
    
    typestring · uri
    
    Required
    A stable URI identifying the problem kind. This is the field to branch on.
    default about:blank
    
    api_versionstring
    Present on an api-version-retired or api-version-unknown refusal: the API-Version this server speaks (docs/decisions/0011).
    
    detailstring
    A human-readable explanation specific to this occurrence. Safe to show to a developer; never contains internal state, SQL, or stack traces.
    
    instancestring · uri-reference
    A URI reference identifying the specific occurrence.
    
    invalid_paramsarray of InvalidParam
    
    Present on 422 responses. Lists every field that failed validation, rather than only the first, so a client can highlight an entire form in one pass.
    
    codestring
    Stable machine-readable code for this failure, for clients that localise their own messages rather than showing reason.
    
    pointerstring
    
    Required
    RFC 6901 JSON Pointer to the offending value within the request body. A pointer rather than a field name so that failures nested inside arrays — the third line item of an order — are addressable at all.
    
    reasonstring
    
    Required
    Why this value was rejected, in human-readable form.
    
    refusalsarray of Location refusal
    
    Present on 409 responses to a withdrawal refused by the state it depends on (deleting a location with tills still assigned, open orders, …). Lists every reason at once, each with how much stands in the way, so a client can say what to put right and link to it rather than walking a person through one refusal after another.
    
    kindstring
    
    Required
    A stable refusal kind — devices, open_orders, drawer_sessions, bookings or stock — that a client links to the screen that puts it right. Branch on this field, never on the surrounding prose.
    
    countinteger
    
    Required
    How many things stand in the way of the withdrawal, so a client can repeat the number rather than re-read prose.
    ≥ 1
    
    statusinteger
    
    Required
    The HTTP status code, repeated here so the body is self-contained.
    100–599
    
    titlestring
    
    Required
    A short, human-readable summary of the problem kind.
    
    trace_idstring
    The OpenTelemetry trace id for this request. Quote it in a support ticket and the whole request can be pulled up.
  - statusstring · enum
    
    Required
    created — the item made a new resource. updated — it changed an existing one.
    unchanged — this key was already applied and the original outcome stands. A success, not an error: it is what a client retrying a batch it was unsure landed should expect, and it clears the item from its queue exactly as created does.
    failed — the item was refused, and nothing else in the batch was affected. See problem.
    createdupdatedunchangedfailed
  - versioninteger · int64
    The resource's version after the item. Absent when it failed.
400
The request could not be parsed. Malformed JSON, a bad query parameter, or a header that failed to decode, among them an API-Version later than the server speaks or not a date (api-version-unknown, with the server's own in api_version).
Distinct from 422: a 400 never reached validation, so invalid_params is absent. Retrying without changing the request will fail again, except that a request refused for its API-Version goes once the server is updated.
401
No credentials, or credentials that could not be verified — missing bearer token, malformed JWT, expired token, or a signature that failed against the issuer's JWKS.
Refresh the token and retry once. Repeated 401 after a refresh means the device needs to re-enrol.
403
Authenticated, but not permitted. The token is valid and its merchant was resolved, but the caller's role does not allow this operation, or the target belongs to a different merchant.
Cross-tenant access is reported as 403 on a resource the caller may not see, and as 404 where even confirming existence would leak information. Retrying will not help.
410
The request names an API-Version this server no longer serves (docs/decisions/0011). Nothing in it was read. api_version names the version the server speaks: the client is behind, and sends the request again once it is updated.
415
The request Content-Type is not supported. This API accepts application/json on all mutations.
422
The request parsed but failed validation.
invalid_params lists every failing field with a JSON Pointer, not just the first, so a client can mark up a whole form in one pass rather than making the user fix errors one round trip at a time.
Also returned when an Idempotency-Key is replayed with a different body, and when device-computed order totals disagree with the server's recomputation.
429
Rate limit exceeded. Honour Retry-After rather than applying your own backoff.
A fleet of tills coming back online together after an outage is the realistic cause, which is exactly when uncoordinated client-side retry turns a brief outage into a sustained one. The limit is per process, and per site for what records trade there — a request spends its site's budget, and a till's own smaller one inside it — and per (client, merchant) for everything else; no RateLimit field is sent, so this response and its Retry-After are the whole of the contract.
500
Something failed on our side. trace_id identifies the request in our tracing — quote it in a support ticket.
The body never carries internal detail: no SQL, no stack traces, no upstream error strings. Safe to retry with the same Idempotency-Key.

Request

curl -X POST 'https://api.tenvelo.com/v1/suppression-lifts/batch-create' \
  -H "Authorization: Bearer $TOKEN" \
  -H 'Content-Type: application/json' \
  -d '{
  "items": [
    {
      "idempotency_key": "01J8ZK3QF7X2N5V9C4B1A6D8E0",
      "suppression_ids": [
        "0192f1e4-7c3a-7b2e-9f10-5d6c7e8f9a0b"
      ]
    }
  ]
}'

Response

{
  "results": [
    {
      "id": "0192f1e4-7c3a-7b2e-9f10-5d6c7e8f9a0b",
      "idempotency_key": "string",
      "problem": {
        "type": "https://api.tenvelo.com/problems/version-conflict",
        "api_version": "2026-10-10",
        "detail": "The product has been modified since version 7 was read.",
        "instance": "/v1/products/0195f8c7-4a1e-7c3b-9f22-8d4e6a1b2c3d",
        "invalid_params": [
          {
            "code": "minimum",
            "pointer": "/line_items/0/quantity",
            "reason": "must be greater than or equal to 1"
          }
        ],
        "refusals": [
          {
            "kind": "devices",
            "count": 3
          }
        ],
        "status": 412,
        "title": "Version conflict",
        "trace_id": "4bf92f3577b34da6a3ce929d0e0e4736"
      },
      "status": "created",
      "version": 0
    }
  ]
}

GET/v1/suppressions

List who asked not to be contacted

No. listSuppressionsAuth customers:read

The email addresses and mobile numbers the business may not message, newest first: each statement in force, how it arrived and who recorded it. Never the platform-wide half (undeliverable destinations), which is not the business's to read. Guests' contact details, so only a caller who may see those reads it. Paged with the cursor of the previous page.

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 suppressions.
SuppressionPage · application/json
- has_moreboolean
  
  Required
  Whether another page may follow.
- itemsarray of Suppression
  
  Required
  - idstring · uuid
    
    Required
  - channelstring · enum
    
    Required
    emailsms
  - destinationstring
    
    Required
    The canonical address, or the number in E.164.
  - recorded_atstring · date-time
    
    Required
  - recorded_bystring
    
    Required
    Who recorded it by hand; empty when it arrived any other way.
  - sourcestring
    
    Required
    How it arrived, such as back-office or a provider's report.
- 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.

Request

curl -X GET 'https://api.tenvelo.com/v1/suppressions' \
  -H "Authorization: Bearer $TOKEN"

Response

{
  "has_more": false,
  "items": [
    {
      "id": "0192f1e4-7c3a-7b2e-9f10-5d6c7e8f9a0b",
      "channel": "email",
      "destination": "string",
      "recorded_at": "2026-09-11T09:30:00Z",
      "recorded_by": "string",
      "source": "string"
    }
  ],
  "next_cursor": "string"
}

POST/v1/suppressions/batch-create

Record that guests asked not to be contacted

No. batchCreateSuppressionsAuth customers:write

Each item is a guest's word, at the counter or on the phone, that the business must stop emailing or texting them. A number written locally is read in the business's own country. Anyone who may record a guest may record this, and it is open on every plan: it is the guest's right over their own details.

Request body application/json · SuppressionBatchCreateRequest

itemsarray of SuppressionBatchCreateItem

Required
≥ 1 items · ≤ 100 items
- channelstring · enum
  
  Required
  emailsms
- destinationstring
  
  Required
  An email address, or a mobile number in E.164 or as written locally.
  1–320 chars
- idempotency_keyItemIdempotencyKey
  
  Required
  A key for one item in a batch, minted by the client when it queues the item and reused on every attempt to send it. The item, not the request, is the unit of work: a retried batch returns the stored result for every item already applied under its key. A fresh key per attempt defeats the whole mechanism.
  Scoped per merchant, so keys need only be unique within a merchant's own traffic.
  16–255 chars

Responses

200
The batch was processed. results says what happened to each item.
BatchResponse · application/json
- resultsarray of BatchResult
  
  Required
  - idstring · uuid
    The resource the item created or changed. Absent when it failed.
  - idempotency_keystring
    
    Required
    The item's key, echoed so a result can be matched by key as well as position.
  - problemProblem
    
    Nullable
    Why the item failed, as an RFC 9457 problem. A 422 means the item is malformed and will never succeed — drop it and show it to staff rather than retrying for ever. A 409 or a 5xx means try again later.
    
    typestring · uri
    
    Required
    A stable URI identifying the problem kind. This is the field to branch on.
    default about:blank
    
    api_versionstring
    Present on an api-version-retired or api-version-unknown refusal: the API-Version this server speaks (docs/decisions/0011).
    
    detailstring
    A human-readable explanation specific to this occurrence. Safe to show to a developer; never contains internal state, SQL, or stack traces.
    
    instancestring · uri-reference
    A URI reference identifying the specific occurrence.
    
    invalid_paramsarray of InvalidParam
    
    Present on 422 responses. Lists every field that failed validation, rather than only the first, so a client can highlight an entire form in one pass.
    
    codestring
    Stable machine-readable code for this failure, for clients that localise their own messages rather than showing reason.
    
    pointerstring
    
    Required
    RFC 6901 JSON Pointer to the offending value within the request body. A pointer rather than a field name so that failures nested inside arrays — the third line item of an order — are addressable at all.
    
    reasonstring
    
    Required
    Why this value was rejected, in human-readable form.
    
    refusalsarray of Location refusal
    
    Present on 409 responses to a withdrawal refused by the state it depends on (deleting a location with tills still assigned, open orders, …). Lists every reason at once, each with how much stands in the way, so a client can say what to put right and link to it rather than walking a person through one refusal after another.
    
    kindstring
    
    Required
    A stable refusal kind — devices, open_orders, drawer_sessions, bookings or stock — that a client links to the screen that puts it right. Branch on this field, never on the surrounding prose.
    
    countinteger
    
    Required
    How many things stand in the way of the withdrawal, so a client can repeat the number rather than re-read prose.
    ≥ 1
    
    statusinteger
    
    Required
    The HTTP status code, repeated here so the body is self-contained.
    100–599
    
    titlestring
    
    Required
    A short, human-readable summary of the problem kind.
    
    trace_idstring
    The OpenTelemetry trace id for this request. Quote it in a support ticket and the whole request can be pulled up.
  - statusstring · enum
    
    Required
    created — the item made a new resource. updated — it changed an existing one.
    unchanged — this key was already applied and the original outcome stands. A success, not an error: it is what a client retrying a batch it was unsure landed should expect, and it clears the item from its queue exactly as created does.
    failed — the item was refused, and nothing else in the batch was affected. See problem.
    createdupdatedunchangedfailed
  - versioninteger · int64
    The resource's version after the item. Absent when it failed.
400
The request could not be parsed. Malformed JSON, a bad query parameter, or a header that failed to decode, among them an API-Version later than the server speaks or not a date (api-version-unknown, with the server's own in api_version).
Distinct from 422: a 400 never reached validation, so invalid_params is absent. Retrying without changing the request will fail again, except that a request refused for its API-Version goes once the server is updated.
401
No credentials, or credentials that could not be verified — missing bearer token, malformed JWT, expired token, or a signature that failed against the issuer's JWKS.
Refresh the token and retry once. Repeated 401 after a refresh means the device needs to re-enrol.
403
Authenticated, but not permitted. The token is valid and its merchant was resolved, but the caller's role does not allow this operation, or the target belongs to a different merchant.
Cross-tenant access is reported as 403 on a resource the caller may not see, and as 404 where even confirming existence would leak information. Retrying will not help.
410
The request names an API-Version this server no longer serves (docs/decisions/0011). Nothing in it was read. api_version names the version the server speaks: the client is behind, and sends the request again once it is updated.
415
The request Content-Type is not supported. This API accepts application/json on all mutations.
422
The request parsed but failed validation.
invalid_params lists every failing field with a JSON Pointer, not just the first, so a client can mark up a whole form in one pass rather than making the user fix errors one round trip at a time.
Also returned when an Idempotency-Key is replayed with a different body, and when device-computed order totals disagree with the server's recomputation.
429
Rate limit exceeded. Honour Retry-After rather than applying your own backoff.
A fleet of tills coming back online together after an outage is the realistic cause, which is exactly when uncoordinated client-side retry turns a brief outage into a sustained one. The limit is per process, and per site for what records trade there — a request spends its site's budget, and a till's own smaller one inside it — and per (client, merchant) for everything else; no RateLimit field is sent, so this response and its Retry-After are the whole of the contract.
500
Something failed on our side. trace_id identifies the request in our tracing — quote it in a support ticket.
The body never carries internal detail: no SQL, no stack traces, no upstream error strings. Safe to retry with the same Idempotency-Key.

Request

curl -X POST 'https://api.tenvelo.com/v1/suppressions/batch-create' \
  -H "Authorization: Bearer $TOKEN" \
  -H 'Content-Type: application/json' \
  -d '{
  "items": [
    {
      "channel": "email",
      "destination": "string",
      "idempotency_key": "01J8ZK3QF7X2N5V9C4B1A6D8E0"
    }
  ]
}'

Response

{
  "results": [
    {
      "id": "0192f1e4-7c3a-7b2e-9f10-5d6c7e8f9a0b",
      "idempotency_key": "string",
      "problem": {
        "type": "https://api.tenvelo.com/problems/version-conflict",
        "api_version": "2026-10-10",
        "detail": "The product has been modified since version 7 was read.",
        "instance": "/v1/products/0195f8c7-4a1e-7c3b-9f22-8d4e6a1b2c3d",
        "invalid_params": [
          {
            "code": "minimum",
            "pointer": "/line_items/0/quantity",
            "reason": "must be greater than or equal to 1"
          }
        ],
        "refusals": [
          {
            "kind": "devices",
            "count": 3
          }
        ],
        "status": 412,
        "title": "Version conflict",
        "trace_id": "4bf92f3577b34da6a3ce929d0e0e4736"
      },
      "status": "created",
      "version": 0
    }
  ]
}