Staff · Tenvelo API

GET/v1/announcement-acknowledgments

List who has got an announcement

No. listAnnouncementAcknowledgmentsAuth members:read

Returns who has acknowledged an announcement on a till, earliest first. Tills learn of them from the change feed.

Parameters

announcement_idquery · string · uuid
Required
The announcement whose acknowledgments to list.
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 acknowledgments.
AnnouncementAcknowledgmentPage · application/json
- has_moreboolean
  
  Required
  Whether another page follows.
- itemsarray of AnnouncementAcknowledgment
  
  Required
  - idstring · uuid
    
    RequiredRead only
  - acknowledged_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.
  - announcement_idstring · uuid
    
    Required
  - member_idstring · uuid
    
    Required
    The roster's id — the member's user id.
- next_cursorstring
  
  Nullable
  Opaque cursor for the next page, or null on the last page. Pass it back verbatim as the cursor query parameter; its contents are not part of this contract.
400
The request could not be parsed. Malformed JSON, a bad query parameter, or a header that failed to decode, among them an API-Version later than the server speaks or not a date (api-version-unknown, with the server's own in api_version).
Distinct from 422: a 400 never reached validation, so invalid_params is absent. Retrying without changing the request will fail again, except that a request refused for its API-Version goes once the server is updated.
401
No credentials, or credentials that could not be verified — missing bearer token, malformed JWT, expired token, or a signature that failed against the issuer's JWKS.
Refresh the token and retry once. Repeated 401 after a refresh means the device needs to re-enrol.
403
Authenticated, but not permitted. The token is valid and its merchant was resolved, but the caller's role does not allow this operation, or the target belongs to a different merchant.
Cross-tenant access is reported as 403 on a resource the caller may not see, and as 404 where even confirming existence would leak information. Retrying will not help.
404
No such resource, or none visible to this caller.
Also returned instead of 403 where acknowledging existence would itself leak information — so a 404 does not prove the id is unused globally, only that it is not yours.
410
The request names an API-Version this server no longer serves (docs/decisions/0011). Nothing in it was read. api_version names the version the server speaks: the client is behind, and sends the request again once it is updated.
422
The request parsed but failed validation.
invalid_params lists every failing field with a JSON Pointer, not just the first, so a client can mark up a whole form in one pass rather than making the user fix errors one round trip at a time.
Also returned when an Idempotency-Key is replayed with a different body, and when device-computed order totals disagree with the server's recomputation.
429
Rate limit exceeded. Honour Retry-After rather than applying your own backoff.
A fleet of tills coming back online together after an outage is the realistic cause, which is exactly when uncoordinated client-side retry turns a brief outage into a sustained one. The limit is per process, and per site for what records trade there — a request spends its site's budget, and a till's own smaller one inside it — and per (client, merchant) for everything else; no RateLimit field is sent, so this response and its Retry-After are the whole of the contract.
500
Something failed on our side. trace_id identifies the request in our tracing — quote it in a support ticket.
The body never carries internal detail: no SQL, no stack traces, no upstream error strings. Safe to retry with the same Idempotency-Key.

Request

curl -X GET 'https://api.tenvelo.com/v1/announcement-acknowledgments?announcement_id=…' \
  -H "Authorization: Bearer $TOKEN"

Response

{
  "has_more": false,
  "items": [
    {
      "id": "0192f1e4-7c3a-7b2e-9f10-5d6c7e8f9a0b",
      "acknowledged_at": "2026-09-08T09:41:12Z",
      "announcement_id": "0192f1e4-7c3a-7b2e-9f10-5d6c7e8f9a0b",
      "member_id": "0192f1e4-7c3a-7b2e-9f10-5d6c7e8f9a0b"
    }
  ],
  "next_cursor": "string"
}

POST/v1/announcement-acknowledgments/batch-create

Record that members have got announcements

No. batchCreateAnnouncementAcknowledgmentsAuth members:write

Records that a member said "got it" to an announcement on a till. A till records one only when the person does so, never because the announcement was shown. A person acknowledges an announcement once: recording it again, from any till, is unchanged and keeps the first one's time. One that arrives after the announcement has ended is still recorded.

Each item carries its own idempotency_key and stands or falls on its own: an item naming a member who is not on this merchant's roster, or an announcement there is none of, fails in its result and every other item is still applied.

Request body application/json · AnnouncementAcknowledgmentBatchCreateRequest

itemsarray of AnnouncementAcknowledgmentBatchCreateItem

Required
≥ 1 items · ≤ 500 items
- announcement_idstring · uuid
  
  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
- member_idstring · uuid
  
  Required
  The roster's id — the member's user id.

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

Response

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

GET/v1/announcements

List announcements

No. listAnnouncementsAuth members:read

Returns the announcements written for the business's locations, newest first, those that have ended as well as those still showing. A person scoped to locations sees the ones for a location they hold. Tills learn of them from the change feed.

Parameters

location_idquery · string · uuid
Only the announcements for this location. Absent means every location's.
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 announcements.
AnnouncementPage · application/json
- has_moreboolean
  
  Required
  Whether another page follows.
- itemsarray of Announcement
  
  Required
  - idstring · uuid
    
    Required
  - bodystring
    
    Required
    What it says, in the writer's words. Short enough to read on a handheld.
    1–280 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.
  - ends_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.
  - location_idsarray of string · uuid
    
    Required
    The locations whose tills show it.
    ≥ 1 items
  - member_idstring · uuid
    
    RequiredNullable
    The member who wrote it, or null when an integration did.
  - rolesarray of string · enum
    The roles it is for, when it is not for everyone at the locations: a till shows it to each person as they sign in only when the person holds one of these roles. Empty means everyone at the locations, as before.
  - 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
  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.

Request

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

Response

{
  "has_more": false,
  "items": [
    {
      "id": "0192f1e4-7c3a-7b2e-9f10-5d6c7e8f9a0b",
      "body": "string",
      "created_at": "2026-09-08T09:41:12Z",
      "ends_at": "2026-09-08T09:41:12Z",
      "location_ids": [
        "0192f1e4-7c3a-7b2e-9f10-5d6c7e8f9a0b"
      ],
      "member_id": "0192f1e4-7c3a-7b2e-9f10-5d6c7e8f9a0b",
      "roles": [
        "owner"
      ],
      "updated_at": "2026-09-08T09:41:12Z",
      "version": 7
    }
  ],
  "next_cursor": "string"
}

POST/v1/announcements/batch-upsert

Write announcements for the tills

No. batchUpsertAnnouncementsAuth members:write

Writes an announcement for the tills at some locations, or changes one. Without version an item writes a new announcement under its id; with it, the item changes the one read at that version. Ending an announcement early is changing its ends_at to now.

Each item carries its own idempotency_key and stands or falls on its own. Writing to the tills is an owner's or a manager's, for the locations they hold.

Request body application/json · AnnouncementBatchUpsertRequest

itemsarray of AnnouncementBatchUpsertItem

Required
≥ 1 items · ≤ 500 items
- idstring · uuid
  
  Required
  The announcement's id, a UUIDv7 the client mints when it writes a new one.
- bodystring
  
  Required
  1–280 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
- location_idsarray of string · uuid
  
  Required
  ≥ 1 items · ≤ 500 items
- rolesarray of string · enum
  The roles it is for, when it is not for everyone at the locations: a till shows it to each person as they sign in only when the person holds one of these roles. Empty means everyone at the locations, as before.
- versioninteger · int64
  The version this write was made from. Required to change an announcement 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.

Request

curl -X POST 'https://api.tenvelo.com/v1/announcements/batch-upsert' \
  -H "Authorization: Bearer $TOKEN" \
  -H 'Content-Type: application/json' \
  -d '{
  "items": [
    {
      "id": "0192f1e4-7c3a-7b2e-9f10-5d6c7e8f9a0b",
      "body": "string",
      "idempotency_key": "01J8ZK3QF7X2N5V9C4B1A6D8E0",
      "location_ids": [
        "0192f1e4-7c3a-7b2e-9f10-5d6c7e8f9a0b"
      ],
      "roles": [
        "owner"
      ],
      "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/custom-roles

List custom roles

No. listCustomRolesAuth members:read

Returns the caller's merchant's custom roles, active first and then withdrawn, each newest first — what the team page's Roles tab and a member's role picker read.

Parameters

cursorquery · string
Opaque cursor from a previous page's next_cursor. Omit to start from the beginning.
Pass it back exactly as received. It is base64 and its structure is not part of this contract — decoding it, or constructing one by hand, will break without notice.
limitquery · integer · int32
Maximum items to return. The server may return fewer, so always drive the loop from has_more rather than from the size of the page you got back.

Responses

200
The roles.
CustomRolePage · application/json
- has_moreboolean
  
  Required
  Whether another page follows.
- itemsarray of CustomRole
  
  Required
  - idstring · uuid
    
    RequiredRead only
  - namestring
    
    Required
    ≤ 50 chars
  - created_atstring · date-time
    
    Read only
  - deleted_atstring · date-time
    
    NullableRead only
    When the merchant withdrew the role. A withdrawn role still answers, and grants nothing.
  - grantsarray of string
    
    Required
    The permission names this role grants, from the same table the server enforces (see GET /v1/roles).
    ≤ 200 items
  - updated_atstring · date-time
    
    Read only
  - versioninteger · int64
    
    RequiredRead only
    Sent as If-Match to change or withdraw the role.
    ≥ 0
- 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.
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/custom-roles' \
  -H "Authorization: Bearer $TOKEN"

Response

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

POST/v1/custom-roles/batch-upsert

Create or update custom roles

No. batchUpsertCustomRolesAuth pos:staff:manage

Names sets of permissions a membership may carry in addition to its role, or replaces one already standing. Each item carries its own idempotency_key; an item without version creates, one with it replaces only if that is still the role's current version, and a stale version is refused with 409 in that item's result. A role never grants what nothing checks: every grant must be one the server enforces. Only an owner or a manager may, and items succeed or fail on their own.

Request body application/json · CustomRoleBatchUpsertRequest

itemsarray of CustomRoleBatchUpsertItem

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
- roleCustomRoleInput
  
  Required
  A custom role's name and the permissions it grants, with the role's own id where the item updates one it already has (absent creates).
  - idstring · uuid
    The role's own id. Absent creates a role; present, with a version, updates that one.
  - namestring
    
    Required
    1–50 chars
  - grantsarray of string
    
    Required
    The permission names this role grants, from the same table the server enforces (see GET /v1/roles).
    ≤ 200 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.
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/custom-roles/batch-upsert' \
  -H "Authorization: Bearer $TOKEN" \
  -H 'Content-Type: application/json' \
  -d '{
  "items": [
    {
      "idempotency_key": "01J8ZK3QF7X2N5V9C4B1A6D8E0",
      "role": {
        "id": "0192f1e4-7c3a-7b2e-9f10-5d6c7e8f9a0b",
        "name": "string",
        "grants": [
          "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
    }
  ]
}

PATCH/v1/custom-roles/{id}

Change a custom role

No. updateCustomRoleAuth pos:staff:manage

Changes a custom role's name or grants (a merge patch, RFC 7396, not a replacement). Guarded by If-Match: a change made against a version somebody has since changed is refused with 412. A member already carrying the role is answered by the new grants on their next request; a withdrawn role may be revived by naming it again. Only an owner or a manager may.

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

namestring
The role's new name.
1–50 chars
grantsarray of string
The permission names this role grants, from the same table the server enforces (see GET /v1/roles).
≤ 200 items

Responses

200
The role as changed.
CustomRole · application/json
- idstring · uuid
  
  RequiredRead only
- namestring
  
  Required
  ≤ 50 chars
- created_atstring · date-time
  
  Read only
- deleted_atstring · date-time
  
  NullableRead only
  When the merchant withdrew the role. A withdrawn role still answers, and grants nothing.
- grantsarray of string
  
  Required
  The permission names this role grants, from the same table the server enforces (see GET /v1/roles).
  ≤ 200 items
- updated_atstring · date-time
  
  Read only
- versioninteger · int64
  
  RequiredRead only
  Sent as If-Match to change or withdraw the role.
  ≥ 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.
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.
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/custom-roles/0192f1e4-7c3a-7b2e-9f10-5d6c7e8f9a0b' \
  -H "Authorization: Bearer $TOKEN" \
  -H 'If-Match: "3"' \
  -H 'Content-Type: application/merge-patch+json' \
  -d '{
  "name": "string",
  "grants": [
    "string"
  ]
}'

Response

{
  "id": "0192f1e4-7c3a-7b2e-9f10-5d6c7e8f9a0b",
  "name": "string",
  "created_at": "2026-09-11T09:30:00Z",
  "deleted_at": "2026-09-11T09:30:00Z",
  "grants": [
    "string"
  ],
  "updated_at": "2026-09-11T09:30:00Z",
  "version": 0
}

DELETE/v1/custom-roles/{id}

Withdraw a custom role

No. deleteCustomRoleAuth pos:staff:manage

Withdraws a custom role. It is kept, not destroyed: a membership that named it is answered with the role withdrawn, and the member stands at their role alone. A member's next request reads no grants from it. Guarded by If-Match. Only an owner or a manager may.

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

POST/v1/help-request-responses/batch-create

Answer help from the tills

No. batchCreateHelpRequestResponsesAuth members:write

Records that the manager signed in at a till has taken a help request: "on my way" is the whole answer. A till records one only when the manager says so. Only an owner or a manager answers; a second manager answering answers nothing new and keeps the first's.

Each item carries its own idempotency_key and stands or falls on its own.

Request body application/json · HelpRequestResponseBatchCreateRequest

itemsarray of HelpRequestResponseBatchCreateItem

Required
≥ 1 items · ≤ 500 items
- help_request_idstring · uuid
  
  Required
  The request being taken.
- 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
- member_idstring · uuid
  
  Required
  The manager taking it, the roster's id. Only an owner or a manager may answer.

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

Response

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

GET/v1/help-requests

List help requests

No. listHelpRequestsAuth members:read

The help requests at the locations the caller holds, newest first. An owner or a manager reads them, in the back office's bell; a till does not need the list — the change feed brings each one as it happens.

Parameters

location_idquery · string · uuid
statusquery · string · enum
Only the requests still waiting for a manager, or only those taken. Absent returns both.
cursorquery · string
Opaque cursor from a previous page's next_cursor. Omit to start from the beginning.
Pass it back exactly as received. It is base64 and its structure is not part of this contract — decoding it, or constructing one by hand, will break without notice.
limitquery · integer · int32
Maximum items to return. The server may return fewer, so always drive the loop from has_more rather than from the size of the page you got back.

Responses

200
The page, newest first.
HelpRequestPage · application/json
- has_moreboolean
  
  Required
- itemsarray of HelpRequest
  
  Required
  - idstring · uuid
    
    Required
  - answered_atTimestamp
    
    Nullable
    When it was taken, absent while it is open.
  - answered_bystring · uuid
    
    Nullable
    The manager who took it, absent while it is open.
  - bodystring
    
    Required
    What they need, in their words. Short enough to read on a handheld.
    1–140 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.
  - location_idstring · uuid
    
    Required
    The location whose tills show it, and whose managers may answer.
  - member_idstring · uuid
    
    Required
    Who asked; the till records it for whoever is signed in to it.
  - member_namestring
    
    Read only
    The name of who asked, as they go by now.
  - 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
  Present when there is more; pass it back as cursor.
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.
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/help-requests' \
  -H "Authorization: Bearer $TOKEN"

Response

{
  "has_more": false,
  "items": [
    {
      "id": "0192f1e4-7c3a-7b2e-9f10-5d6c7e8f9a0b",
      "answered_at": "2026-09-08T09:41:12Z",
      "answered_by": "0192f1e4-7c3a-7b2e-9f10-5d6c7e8f9a0b",
      "body": "string",
      "created_at": "2026-09-08T09:41:12Z",
      "location_id": "0192f1e4-7c3a-7b2e-9f10-5d6c7e8f9a0b",
      "member_id": "0192f1e4-7c3a-7b2e-9f10-5d6c7e8f9a0b",
      "member_name": "string",
      "updated_at": "2026-09-08T09:41:12Z",
      "version": 7
    }
  ],
  "next_cursor": "string"
}

POST/v1/help-requests/batch-create

Ask for help from the tills

No. batchCreateHelpRequestsAuth members:write

Records that the member signed in at a till wants a manager, at that till's location. The request reaches the other tills at the location through the change feed, and stays open until a manager answers it. A till records one only when the person asks, never because it might be useful.

Each item carries its own idempotency_key and stands or falls on its own: an item naming a member who is not on this merchant's roster fails in its result and every other item is still applied.

Request body application/json · HelpRequestBatchCreateRequest

itemsarray of HelpRequestBatchCreateItem

Required
≥ 1 items · ≤ 500 items
- idstring · uuid
  
  Required
  The request's id, a UUIDv7 the till mints when the person asks.
- bodystring
  
  Required
  What they need, in their words.
  1–140 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
- member_idstring · uuid
  
  Required
  Who asked, the roster's id — the till records it for whoever is signed in.

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/help-requests/batch-create' \
  -H "Authorization: Bearer $TOKEN" \
  -H 'Content-Type: application/json' \
  -d '{
  "items": [
    {
      "id": "0192f1e4-7c3a-7b2e-9f10-5d6c7e8f9a0b",
      "body": "string",
      "idempotency_key": "01J8ZK3QF7X2N5V9C4B1A6D8E0",
      "member_id": "0192f1e4-7c3a-7b2e-9f10-5d6c7e8f9a0b"
    }
  ]
}'

Response

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

GET/v1/invitations/lookup

Look an invitation up by its link

No. getInvitationByTokenAuth no token

What an invitation's link offers, for whoever holds the link: the business, the role and the address it was sent to, and whether that address has an account, which says whether the app asks the issuer to sign the person in or to make their account (Prompt Create 1.0). The token is the credential, so an unknown, expired, withdrawn or spent one is a 404 in every case, and says nothing about which tokens exist. Public, and rate limited per client address.

Parameters

tokenquery · string
Required
The token the invitation's link carries.

Responses

200
What the invitation offers.
InvitationOffer · application/json
- idstring · uuid
  
  Required
- business_namestring
  
  Required
- emailstring
  
  Required
  The address it was sent to, which the person must sign in with.
- has_accountboolean
  
  Required
  Whether that address has an account, so whether the person signs in or makes one.
- rolestring · enum
  
  Required
  ownermanagerstaff
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/invitations/lookup?token=…'

Response

{
  "id": "0192f1e4-7c3a-7b2e-9f10-5d6c7e8f9a0b",
  "business_name": "string",
  "email": "string",
  "has_account": false,
  "role": "owner"
}

POST/v1/invitations/{id}/accept

Accept an invitation

No. acceptInvitationAuth bearer

Makes the signed-in person a member of the business the invitation is for, in its role. It takes a token for the person and no business (0107), and the invitation's own token, which is the credential. The invitation is for one address, so somebody signed in with another is a 403; and since the link was mailed there, accepting it also proves the address is theirs. Somebody already a member is a 409. Once accepted, the app asks the issuer for a token for the business.

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

tokenstring

Required
1–200 chars

Responses

200
The person is a member.
InvitationAccepted · application/json
- merchant_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.
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.
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/invitations/0192f1e4-7c3a-7b2e-9f10-5d6c7e8f9a0b/accept' \
  -H "Authorization: Bearer $TOKEN" \
  -H 'Idempotency-Key: 01J8ZK3QF7X2N5V9C4B1A6D8E0' \
  -H 'Content-Type: application/json' \
  -d '{
  "token": "string"
}'

Response

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

GET/v1/invites

List staff invitations

No. listInvitesAuth bearer

Returns invitations for this merchant. An invitation's link is only ever emailed to the invited address.

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.
statusquery · string · enum

Responses

200
A page of invitations.
InvitePage · application/json
- has_moreboolean
  
  Required
  Whether another page follows.
- itemsarray of Invite
  
  Required
  - idstring · uuid
    
    Required
  - created_atTimestamp
    
    RequiredRead only
    Server-assigned RFC 3339 timestamp, always UTC.
    Server-assigned because device clocks drift and cannot be trusted for ordering — a till that has been powered off for a week may come back with a clock hours out. Where the device's own view of time matters it is carried separately in client_created_at.
  - emailstring · email
    
    Required
    ≤ 320 chars
  - expires_atstring · date-time
    
    Required
    After this, redemption is refused. Invitations expire because a stale one is a standing grant of access to an account.
  - location_idsarray of string · uuid
    Locations the invitee will have access to. Empty means all.
  - merchant_idstring · uuid
    
    RequiredRead only
  - rolestring · enum
    
    Required
    ownermanagerstaff
  - statusstring · enum
    
    Required
    pendingacceptedrevokedexpired
  - 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
  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/invites' \
  -H "Authorization: Bearer $TOKEN"

Response

{
  "has_more": false,
  "items": [
    {
      "id": "0192f1e4-7c3a-7b2e-9f10-5d6c7e8f9a0b",
      "created_at": "2026-09-08T09:41:12Z",
      "email": "ada@example.com",
      "expires_at": "2026-09-11T09:30:00Z",
      "location_ids": [
        "0192f1e4-7c3a-7b2e-9f10-5d6c7e8f9a0b"
      ],
      "merchant_id": "0192f1e4-7c3a-7b2e-9f10-5d6c7e8f9a0b",
      "role": "owner",
      "status": "pending",
      "updated_at": "2026-09-08T09:41:12Z",
      "version": 7
    }
  ],
  "next_cursor": "string"
}

POST/v1/invites

Invite a member of staff

No. createInviteAuth bearer

Creates an invitation and asks for the email that carries its link. The link is minted as the email is sent and goes to the invited address alone; only its hash is stored.

Email delivery is queued rather than sent inline: a mail provider being slow or down must not fail the invitation that was already durably created.

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

idstring · uuid

Required
emailstring · email

Required
≤ 320 chars
expires_atstring · date-time

Required
After this, redemption is refused. Invitations expire because a stale one is a standing grant of access to an account.
location_idsarray of string · uuid
Locations the invitee will have access to. Empty means all.
rolestring · enum

Required
ownermanagerstaff
statusstring · enum

Required
pendingacceptedrevokedexpired

Responses

201
The invitation was created, and its email asked for.
Invite · application/json
- idstring · uuid
  
  Required
- created_atTimestamp
  
  RequiredRead only
  Server-assigned RFC 3339 timestamp, always UTC.
  Server-assigned because device clocks drift and cannot be trusted for ordering — a till that has been powered off for a week may come back with a clock hours out. Where the device's own view of time matters it is carried separately in client_created_at.
- emailstring · email
  
  Required
  ≤ 320 chars
- expires_atstring · date-time
  
  Required
  After this, redemption is refused. Invitations expire because a stale one is a standing grant of access to an account.
- location_idsarray of string · uuid
  Locations the invitee will have access to. Empty means all.
- merchant_idstring · uuid
  
  RequiredRead only
- rolestring · enum
  
  Required
  ownermanagerstaff
- statusstring · enum
  
  Required
  pendingacceptedrevokedexpired
- 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.
409
The request conflicts with current state — a uniqueness constraint, or an attempt to mutate an order that is already completed or voided.
Unlike 412, re-reading and retrying unchanged will not resolve it; the request itself has to change.
410
The request names an API-Version this server no longer serves (docs/decisions/0011). Nothing in it was read. api_version names the version the server speaks: the client is behind, and sends the request again once it is updated.
415
The request Content-Type is not supported. This API accepts application/json on all mutations.
422
The request parsed but failed validation.
invalid_params lists every failing field with a JSON Pointer, not just the first, so a client can mark up a whole form in one pass rather than making the user fix errors one round trip at a time.
Also returned when an Idempotency-Key is replayed with a different body, and when device-computed order totals disagree with the server's recomputation.
429
Rate limit exceeded. Honour Retry-After rather than applying your own backoff.
A fleet of tills coming back online together after an outage is the realistic cause, which is exactly when uncoordinated client-side retry turns a brief outage into a sustained one. The limit is per process, and per site for what records trade there — a request spends its site's budget, and a till's own smaller one inside it — and per (client, merchant) for everything else; no RateLimit field is sent, so this response and its Retry-After are the whole of the contract.
500
Something failed on our side. trace_id identifies the request in our tracing — quote it in a support ticket.
The body never carries internal detail: no SQL, no stack traces, no upstream error strings. Safe to retry with the same Idempotency-Key.
503
Temporarily unable to serve the request — a dependency is down or the service is shedding load.
Retry with the same Idempotency-Key after Retry-After. This is always safe: a request that did take effect before the failure will be recognised as a replay.

Request

curl -X POST 'https://api.tenvelo.com/v1/invites' \
  -H "Authorization: Bearer $TOKEN" \
  -H 'Idempotency-Key: 01J8ZK3QF7X2N5V9C4B1A6D8E0' \
  -H 'Content-Type: application/json' \
  -d '{
  "id": "0192f1e4-7c3a-7b2e-9f10-5d6c7e8f9a0b",
  "email": "ada@example.com",
  "expires_at": "2026-09-11T09:30:00Z",
  "location_ids": [
    "0192f1e4-7c3a-7b2e-9f10-5d6c7e8f9a0b"
  ],
  "role": "owner",
  "status": "pending"
}'

Response

{
  "id": "0192f1e4-7c3a-7b2e-9f10-5d6c7e8f9a0b",
  "created_at": "2026-09-08T09:41:12Z",
  "email": "ada@example.com",
  "expires_at": "2026-09-11T09:30:00Z",
  "location_ids": [
    "0192f1e4-7c3a-7b2e-9f10-5d6c7e8f9a0b"
  ],
  "merchant_id": "0192f1e4-7c3a-7b2e-9f10-5d6c7e8f9a0b",
  "role": "owner",
  "status": "pending",
  "updated_at": "2026-09-08T09:41:12Z",
  "version": 7
}

GET/v1/invites/{id}

Get an invitation

No. getInviteAuth bearer

Returns a single invitation, without its token.

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 invitation.
Invite · application/json
- idstring · uuid
  
  Required
- created_atTimestamp
  
  RequiredRead only
  Server-assigned RFC 3339 timestamp, always UTC.
  Server-assigned because device clocks drift and cannot be trusted for ordering — a till that has been powered off for a week may come back with a clock hours out. Where the device's own view of time matters it is carried separately in client_created_at.
- emailstring · email
  
  Required
  ≤ 320 chars
- expires_atstring · date-time
  
  Required
  After this, redemption is refused. Invitations expire because a stale one is a standing grant of access to an account.
- location_idsarray of string · uuid
  Locations the invitee will have access to. Empty means all.
- merchant_idstring · uuid
  
  RequiredRead only
- rolestring · enum
  
  Required
  ownermanagerstaff
- statusstring · enum
  
  Required
  pendingacceptedrevokedexpired
- updated_atTimestamp
  
  RequiredRead only
  Server-assigned RFC 3339 timestamp, always UTC.
  Server-assigned because device clocks drift and cannot be trusted for ordering — a till that has been powered off for a week may come back with a clock hours out. Where the device's own view of time matters it is carried separately in client_created_at.
- versionVersion
  
  RequiredRead only
  Optimistic concurrency version, raised by the server on every write. A version is never lower than one already returned for the resource, though it may rise by more than one.
  Returned in the ETag response header as well as in the body. Send it back in If-Match on an update and the write is rejected with 412 if anyone else has written since — which is what stops two tills silently overwriting each other's edit to the same product when both come back online at once.
  ≥ 1
400
The request could not be parsed. Malformed JSON, a bad query parameter, or a header that failed to decode, among them an API-Version later than the server speaks or not a date (api-version-unknown, with the server's own in api_version).
Distinct from 422: a 400 never reached validation, so invalid_params is absent. Retrying without changing the request will fail again, except that a request refused for its API-Version goes once the server is updated.
401
No credentials, or credentials that could not be verified — missing bearer token, malformed JWT, expired token, or a signature that failed against the issuer's JWKS.
Refresh the token and retry once. Repeated 401 after a refresh means the device needs to re-enrol.
403
Authenticated, but not permitted. The token is valid and its merchant was resolved, but the caller's role does not allow this operation, or the target belongs to a different merchant.
Cross-tenant access is reported as 403 on a resource the caller may not see, and as 404 where even confirming existence would leak information. Retrying will not help.
404
No such resource, or none visible to this caller.
Also returned instead of 403 where acknowledging existence would itself leak information — so a 404 does not prove the id is unused globally, only that it is not yours.
410
The request names an API-Version this server no longer serves (docs/decisions/0011). Nothing in it was read. api_version names the version the server speaks: the client is behind, and sends the request again once it is updated.
429
Rate limit exceeded. Honour Retry-After rather than applying your own backoff.
A fleet of tills coming back online together after an outage is the realistic cause, which is exactly when uncoordinated client-side retry turns a brief outage into a sustained one. The limit is per process, and per site for what records trade there — a request spends its site's budget, and a till's own smaller one inside it — and per (client, merchant) for everything else; no RateLimit field is sent, so this response and its Retry-After are the whole of the contract.
500
Something failed on our side. trace_id identifies the request in our tracing — quote it in a support ticket.
The body never carries internal detail: no SQL, no stack traces, no upstream error strings. Safe to retry with the same Idempotency-Key.
503
Temporarily unable to serve the request — a dependency is down or the service is shedding load.
Retry with the same Idempotency-Key after Retry-After. This is always safe: a request that did take effect before the failure will be recognised as a replay.

Request

curl -X GET 'https://api.tenvelo.com/v1/invites/0192f1e4-7c3a-7b2e-9f10-5d6c7e8f9a0b' \
  -H "Authorization: Bearer $TOKEN"

Response

{
  "id": "0192f1e4-7c3a-7b2e-9f10-5d6c7e8f9a0b",
  "created_at": "2026-09-08T09:41:12Z",
  "email": "ada@example.com",
  "expires_at": "2026-09-11T09:30:00Z",
  "location_ids": [
    "0192f1e4-7c3a-7b2e-9f10-5d6c7e8f9a0b"
  ],
  "merchant_id": "0192f1e4-7c3a-7b2e-9f10-5d6c7e8f9a0b",
  "role": "owner",
  "status": "pending",
  "updated_at": "2026-09-08T09:41:12Z",
  "version": 7
}

DELETE/v1/invites/{id}

Revoke an invitation

No. revokeInviteAuth bearer

Revokes an invitation so its token can no longer be redeemed.

The record moves to revoked rather than being erased, so the audit trail shows that someone was invited and the invitation was withdrawn.

If-Match is required even though revoking is idempotent, because the state you read matters: revoking an invitation that has been accepted since you looked at it is a different act from revoking a pending one — the person already has access. The 412 forces you to re-read and see that before deciding.

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

GET/v1/manager-log-entries

List a location's manager-log notes

No. listManagerLogEntriesAuth members:read

Returns the notes the managers of a location left one another, newest first. A person scoped to locations sees the notes for a location they hold. The tills never see these; an announcement is how the tills are told.

Parameters

location_idquery · string · uuid
Only this location's notes. Absent means every location the caller holds.
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 notes.
ManagerLogPage · application/json
- has_moreboolean
  
  Required
- itemsarray of ManagerLogEntry
  
  Required
  - idstring · uuid
    
    RequiredRead only
  - created_atstring · date-time
    
    RequiredRead only
  - location_idstring · uuid
    
    Required
    The location the note is for.
  - member_idstring · uuid
    
    Nullable
    Who wrote it, the roster's id. Absent for an integration, which is not a person.
  - member_namestring
    
    NullableRead only
    Who wrote it, read from the roster at read time.
  - notestring
    
    Required
    ≤ 500 chars
  - updated_atstring · date-time
    
    RequiredRead only
  - versioninteger · int64
    
    RequiredRead only
- next_cursorstring
  Present when there is more; pass it back as cursor.
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/manager-log-entries' \
  -H "Authorization: Bearer $TOKEN"

Response

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

POST/v1/manager-log-entries/batch-create

Add notes to a location's manager log

No. batchCreateManagerLogEntriesAuth members:write

Adds notes a manager leaves for the managers of the same location, from one shift to the next. A note is added and never edited.

Each item carries its own idempotency_key and stands or falls on its own: an item for a location the writer does not hold, or naming a manager-log note id already used with another key, fails in its result and every other item is still applied.

Request body application/json · ManagerLogBatchCreateRequest

itemsarray of ManagerLogBatchCreateItem

Required
≥ 1 items · ≤ 500 items
- idstring · uuid
  
  Required
  The note's id, a UUIDv7 the caller mints when it is written.
- idempotency_keyItemIdempotencyKey
  
  Required
  A key for one item in a batch, minted by the client when it queues the item and reused on every attempt to send it. The item, not the request, is the unit of work: a retried batch returns the stored result for every item already applied under its key. A fresh key per attempt defeats the whole mechanism.
  Scoped per merchant, so keys need only be unique within a merchant's own traffic.
  16–255 chars
- location_idstring · uuid
  
  Required
  The location the note is for; the writer must hold it.
- notestring
  
  Required
  What the next shift should know, in the writer's words.
  1–500 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/manager-log-entries/batch-create' \
  -H "Authorization: Bearer $TOKEN" \
  -H 'Content-Type: application/json' \
  -d '{
  "items": [
    {
      "id": "0192f1e4-7c3a-7b2e-9f10-5d6c7e8f9a0b",
      "idempotency_key": "01J8ZK3QF7X2N5V9C4B1A6D8E0",
      "location_id": "0192f1e4-7c3a-7b2e-9f10-5d6c7e8f9a0b",
      "note": "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/member-milestone-facts/batch-create

Record practice facts

No. batchCreateMemberMilestoneFactsAuth members:write

Records that members completed a practice track. Only the fact crosses the wire — never a practice sale: a practice store syncs nothing, and this is the one row a completed practice contributes. A batch of one is how a single till reports its operator.

Each item carries its own idempotency_key and stands or falls on its own: an item naming a member who is not on this merchant's roster, or a key that is not a practice question, fails in its result and every other item is still applied. Only a malformed envelope refuses the request as a whole.

Cover: staff-training item 5.

Request body application/json · MemberMilestoneFactBatchCreateRequest

itemsarray of MemberMilestoneFactBatchCreateItem

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
- keystring
  
  Required
  The practice key, e.g. practised_first_shift.
- member_idstring · uuid
  
  Required
  The roster's id — the member's user id.

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/member-milestone-facts/batch-create' \
  -H "Authorization: Bearer $TOKEN" \
  -H 'Content-Type: application/json' \
  -d '{
  "items": [
    {
      "idempotency_key": "01J8ZK3QF7X2N5V9C4B1A6D8E0",
      "key": "string",
      "member_id": "0192f1e4-7c3a-7b2e-9f10-5d6c7e8f9a0b"
    }
  ]
}'

Response

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

GET/v1/members

List the team

No. listMembersAuth members:read

Returns the caller's merchant roster — who can act, and with what role.

The roster is server-authoritative. A till reads it so it can offer a clock-in choice; the back office manages who is on it.

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 roster.
MemberPage · application/json
- has_moreboolean
  
  Required
  Whether another page follows.
- itemsarray of Member
  
  Required
  - idstring · uuid
    
    RequiredRead only
    The person's user id.
  - namestring
    
    Required
    The person's display name.
  - card_saltstring
    
    Read only
    The base64 per-member salt for the sign-on card's offline verifier, present only when a card is enrolled. A registered till caches the roster and, without a connection, checks sha256(salt + card code) against card_verifier to sign a member on; the server re-checks the SHA-256 hash online. Only ever sent to a device that may read the roster, so it must not be treated as a password.
  - card_verifierstring
    
    Read only
    The base64 sha256(salt + card code) offline verifier for the sign-on card, present only when a card is enrolled. The device compares this to the hash of the code a card reader emitted; absent on a member with no card. Never a substitute for the server's SHA-256 check.
  - custom_role_idstring · uuid
    
    Nullable
    The merchant's custom role this member carries, if any: a set of permissions granted IN ADDITION to their role (accounts-and-access item 4). A device never sees it; the server's checks do. null clears it — the member stands at their role alone. A role the merchant withdrew stays named; its grants are no longer answered.
  - emailstring · email
    
    Required
  - has_cardboolean
    
    Read only
    Whether this member has a till sign-on card enrolled. A till offers a card prompt when a member has one; the card code itself never leaves the server.
  - has_pinboolean
    
    Read only
    Whether this member has a till sign-on PIN set. A till offers a PIN prompt only for members who have one; the PIN itself never leaves the server.
  - languagestring
    The person's language for user-facing text, BCP 47 primary language and territory (the launch set: en-US, en-GB, es, de, fr, ja, it, nl, pt, sv, pl, da, nb, fi). The till reads in the language of whoever is signed in (0017); a Spanish-speaking kitchen and an English-speaking floor sharing one device each read it in their own language. Defaults to en-US.
    pattern ^[a-z]{2}(-[A-Z]{2})?$
  - location_idsarray of string · uuid
    
    RequiredRead only
    The locations this member may act in, copied from the invitation that created the membership. Empty means unrestricted: the member may act at every location in the merchant. A till offers a member's sign-on or clock-in only at their locations.
  - merchant_idstring · uuid
    
    RequiredRead only
  - pin_saltstring
    
    Read only
    The base64 per-member salt for the sign-on PIN's offline verifier, present only when a PIN is set. A registered till caches the roster and, without a connection, checks sha256(salt + pin) against pin_verifier to sign a member on; the server re-checks the argon2id hash online. Only ever sent to a device that may read the roster, so it must not be treated as a password.
  - pin_verifierstring
    
    Read only
    The base64 sha256(salt + pin) offline verifier for the sign-on PIN, present only when a PIN is set. The device compares this to the hash of what a person typed; present and empty on a member with no PIN. Never a substitute for the server's argon2id check.
  - rolestring · enum
    
    Required
    What the person may do in this merchant.
    ownermanagerstaff
  - statusstring · enum
    
    Required
    Whether the person may still act here.
    activeinactive
  - versioninteger · int64
    
    Read only
    The version of the person's role, locations and standing, sent as If-Match to change or remove them. Their PIN, card and language do not move it. One person read on their own carries it; the roster does not.
    ≥ 0
- 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/members' \
  -H "Authorization: Bearer $TOKEN"

Response

{
  "has_more": false,
  "items": [
    {
      "id": "0192f1e4-7c3a-7b2e-9f10-5d6c7e8f9a0b",
      "name": "string",
      "card_salt": "AAAAAAAAAAAAAAAAAAAAAA==",
      "card_verifier": "string",
      "custom_role_id": "0192f1e4-7c3a-7b2e-9f10-5d6c7e8f9a0b",
      "email": "ada@example.com",
      "has_card": false,
      "has_pin": false,
      "language": "string",
      "location_ids": [
        "0192f1e4-7c3a-7b2e-9f10-5d6c7e8f9a0b"
      ],
      "merchant_id": "0192f1e4-7c3a-7b2e-9f10-5d6c7e8f9a0b",
      "pin_salt": "AAAAAAAAAAAAAAAAAAAAAA==",
      "pin_verifier": "string",
      "role": "owner",
      "status": "active",
      "version": 0
    }
  ],
  "next_cursor": "string"
}

GET/v1/members/me

Get the current member

No. getCurrentMemberAuth members:read

Returns the person the caller's token acts as, in the merchant it names: who they are, their role there, and what a screen may offer them.

A person's, so a token that acts as nobody on the roster, a till's or an integration's, is refused. Like /v1/merchants/me, it has no id to get wrong: the person is the token's.

Responses

200
The current member.
CurrentMember · application/json
- idstring · uuid
  
  RequiredRead only
  The person's user id.
- namestring
  
  RequiredRead only
  The person's display name.
- emailstring · email
  
  RequiredRead only
- email_verifiedboolean
  
  RequiredRead only
  Whether the person has proved the email is theirs. Inviting a team waits until they have.
- languagestring
  
  RequiredRead only
  The person's language for user-facing text, BCP 47 primary language and territory (the launch set: en-US, en-GB, es, de, fr, ja, it, nl, pt, sv, pl, da, nb, fi).
  pattern ^[a-z]{2}(-[A-Z]{2})?$
- location_idsarray of string · uuid
  
  RequiredRead only
  The locations the person may act in. Empty means unrestricted: every location in the merchant.
- merchant_idstring · uuid
  
  RequiredRead only
- permissionsarray of string · enum
  
  RequiredRead only
  What the person may do that a screen offers only to some: read the audit log, read what hours cost and pay, and void or exchange an order.
- rolestring · enum
  
  RequiredRead only
  ownermanagerstaff
- versioninteger · int64
  
  RequiredRead only
  The version of the person's language, sent as If-Match to change it. Only another choice of theirs moves it: their role, locations and standing do not.
  ≥ 0
400
The request could not be parsed. Malformed JSON, a bad query parameter, or a header that failed to decode, among them an API-Version later than the server speaks or not a date (api-version-unknown, with the server's own in api_version).
Distinct from 422: a 400 never reached validation, so invalid_params is absent. Retrying without changing the request will fail again, except that a request refused for its API-Version goes once the server is updated.
401
No credentials, or credentials that could not be verified — missing bearer token, malformed JWT, expired token, or a signature that failed against the issuer's JWKS.
Refresh the token and retry once. Repeated 401 after a refresh means the device needs to re-enrol.
403
Authenticated, but not permitted. The token is valid and its merchant was resolved, but the caller's role does not allow this operation, or the target belongs to a different merchant.
Cross-tenant access is reported as 403 on a resource the caller may not see, and as 404 where even confirming existence would leak information. Retrying will not help.
410
The request names an API-Version this server no longer serves (docs/decisions/0011). Nothing in it was read. api_version names the version the server speaks: the client is behind, and sends the request again once it is updated.
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/members/me' \
  -H "Authorization: Bearer $TOKEN"

Response

{
  "id": "0192f1e4-7c3a-7b2e-9f10-5d6c7e8f9a0b",
  "name": "string",
  "email": "ada@example.com",
  "email_verified": false,
  "language": "string",
  "location_ids": [
    "0192f1e4-7c3a-7b2e-9f10-5d6c7e8f9a0b"
  ],
  "merchant_id": "0192f1e4-7c3a-7b2e-9f10-5d6c7e8f9a0b",
  "permissions": [
    "read_audit_log"
  ],
  "role": "owner",
  "version": 0
}

PATCH/v1/members/me

Change the current member's own language

No. updateCurrentMemberAuth members:write

Applies a JSON Merge Patch (RFC 7396) to the person the caller's token acts as: their language for user-facing text (0017), which follows them to the back office and every till.

Anybody on the roster may choose their own. Choosing it for somebody else is managing staff, on the member themselves. A token that acts as nobody on the roster is refused.

Guarded by If-Match on the version of the language GET /v1/members/me answered, which only another choice of theirs moves.

Parameters

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

languagestring · enum
Their language for user-facing text, in the back office and at every till (0017).
en-USen-GBesdefrjaitnlptsvpldanbfi

Responses

200
The current member as changed.
CurrentMember · application/json
- idstring · uuid
  
  RequiredRead only
  The person's user id.
- namestring
  
  RequiredRead only
  The person's display name.
- emailstring · email
  
  RequiredRead only
- email_verifiedboolean
  
  RequiredRead only
  Whether the person has proved the email is theirs. Inviting a team waits until they have.
- languagestring
  
  RequiredRead only
  The person's language for user-facing text, BCP 47 primary language and territory (the launch set: en-US, en-GB, es, de, fr, ja, it, nl, pt, sv, pl, da, nb, fi).
  pattern ^[a-z]{2}(-[A-Z]{2})?$
- location_idsarray of string · uuid
  
  RequiredRead only
  The locations the person may act in. Empty means unrestricted: every location in the merchant.
- merchant_idstring · uuid
  
  RequiredRead only
- permissionsarray of string · enum
  
  RequiredRead only
  What the person may do that a screen offers only to some: read the audit log, read what hours cost and pay, and void or exchange an order.
- rolestring · enum
  
  RequiredRead only
  ownermanagerstaff
- versioninteger · int64
  
  RequiredRead only
  The version of the person's language, sent as If-Match to change it. Only another choice of theirs moves it: their role, locations and standing do not.
  ≥ 0
400
The request could not be parsed. Malformed JSON, a bad query parameter, or a header that failed to decode, among them an API-Version later than the server speaks or not a date (api-version-unknown, with the server's own in api_version).
Distinct from 422: a 400 never reached validation, so invalid_params is absent. Retrying without changing the request will fail again, except that a request refused for its API-Version goes once the server is updated.
401
No credentials, or credentials that could not be verified — missing bearer token, malformed JWT, expired token, or a signature that failed against the issuer's JWKS.
Refresh the token and retry once. Repeated 401 after a refresh means the device needs to re-enrol.
403
Authenticated, but not permitted. The token is valid and its merchant was resolved, but the caller's role does not allow this operation, or the target belongs to a different merchant.
Cross-tenant access is reported as 403 on a resource the caller may not see, and as 404 where even confirming existence would leak information. Retrying will not help.
410
The request names an API-Version this server no longer serves (docs/decisions/0011). Nothing in it was read. api_version names the version the server speaks: the client is behind, and sends the request again once it is updated.
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/members/me' \
  -H "Authorization: Bearer $TOKEN" \
  -H 'If-Match: "3"' \
  -H 'Content-Type: application/merge-patch+json' \
  -d '{
  "language": "en-US"
}'

Response

{
  "id": "0192f1e4-7c3a-7b2e-9f10-5d6c7e8f9a0b",
  "name": "string",
  "email": "ada@example.com",
  "email_verified": false,
  "language": "string",
  "location_ids": [
    "0192f1e4-7c3a-7b2e-9f10-5d6c7e8f9a0b"
  ],
  "merchant_id": "0192f1e4-7c3a-7b2e-9f10-5d6c7e8f9a0b",
  "permissions": [
    "read_audit_log"
  ],
  "role": "owner",
  "version": 0
}

GET/v1/members/{id}

Get a team member

No. getMemberAuth members:read

Returns one person on the caller's merchant roster, by their user id, with their role, where they work and how they sign in at a till. A person removed from the team is still answered, as inactive, so what was rung up under them stays attributable.

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 team member.
Member · application/json
- idstring · uuid
  
  RequiredRead only
  The person's user id.
- namestring
  
  Required
  The person's display name.
- card_saltstring
  
  Read only
  The base64 per-member salt for the sign-on card's offline verifier, present only when a card is enrolled. A registered till caches the roster and, without a connection, checks sha256(salt + card code) against card_verifier to sign a member on; the server re-checks the SHA-256 hash online. Only ever sent to a device that may read the roster, so it must not be treated as a password.
- card_verifierstring
  
  Read only
  The base64 sha256(salt + card code) offline verifier for the sign-on card, present only when a card is enrolled. The device compares this to the hash of the code a card reader emitted; absent on a member with no card. Never a substitute for the server's SHA-256 check.
- custom_role_idstring · uuid
  
  Nullable
  The merchant's custom role this member carries, if any: a set of permissions granted IN ADDITION to their role (accounts-and-access item 4). A device never sees it; the server's checks do. null clears it — the member stands at their role alone. A role the merchant withdrew stays named; its grants are no longer answered.
- emailstring · email
  
  Required
- has_cardboolean
  
  Read only
  Whether this member has a till sign-on card enrolled. A till offers a card prompt when a member has one; the card code itself never leaves the server.
- has_pinboolean
  
  Read only
  Whether this member has a till sign-on PIN set. A till offers a PIN prompt only for members who have one; the PIN itself never leaves the server.
- languagestring
  The person's language for user-facing text, BCP 47 primary language and territory (the launch set: en-US, en-GB, es, de, fr, ja, it, nl, pt, sv, pl, da, nb, fi). The till reads in the language of whoever is signed in (0017); a Spanish-speaking kitchen and an English-speaking floor sharing one device each read it in their own language. Defaults to en-US.
  pattern ^[a-z]{2}(-[A-Z]{2})?$
- location_idsarray of string · uuid
  
  RequiredRead only
  The locations this member may act in, copied from the invitation that created the membership. Empty means unrestricted: the member may act at every location in the merchant. A till offers a member's sign-on or clock-in only at their locations.
- merchant_idstring · uuid
  
  RequiredRead only
- pin_saltstring
  
  Read only
  The base64 per-member salt for the sign-on PIN's offline verifier, present only when a PIN is set. A registered till caches the roster and, without a connection, checks sha256(salt + pin) against pin_verifier to sign a member on; the server re-checks the argon2id hash online. Only ever sent to a device that may read the roster, so it must not be treated as a password.
- pin_verifierstring
  
  Read only
  The base64 sha256(salt + pin) offline verifier for the sign-on PIN, present only when a PIN is set. The device compares this to the hash of what a person typed; present and empty on a member with no PIN. Never a substitute for the server's argon2id check.
- rolestring · enum
  
  Required
  What the person may do in this merchant.
  ownermanagerstaff
- statusstring · enum
  
  Required
  Whether the person may still act here.
  activeinactive
- versioninteger · int64
  
  Read only
  The version of the person's role, locations and standing, sent as If-Match to change or remove them. Their PIN, card and language do not move it. One person read on their own carries it; the roster does not.
  ≥ 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.
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/members/0192f1e4-7c3a-7b2e-9f10-5d6c7e8f9a0b' \
  -H "Authorization: Bearer $TOKEN"

Response

{
  "id": "0192f1e4-7c3a-7b2e-9f10-5d6c7e8f9a0b",
  "name": "string",
  "card_salt": "AAAAAAAAAAAAAAAAAAAAAA==",
  "card_verifier": "string",
  "custom_role_id": "0192f1e4-7c3a-7b2e-9f10-5d6c7e8f9a0b",
  "email": "ada@example.com",
  "has_card": false,
  "has_pin": false,
  "language": "string",
  "location_ids": [
    "0192f1e4-7c3a-7b2e-9f10-5d6c7e8f9a0b"
  ],
  "merchant_id": "0192f1e4-7c3a-7b2e-9f10-5d6c7e8f9a0b",
  "pin_salt": "AAAAAAAAAAAAAAAAAAAAAA==",
  "pin_verifier": "string",
  "role": "owner",
  "status": "active",
  "version": 0
}

PATCH/v1/members/{id}

Change a team member

No. updateMemberAuth pos:staff:manage

Applies a JSON Merge Patch (RFC 7396) to a team member: their role and where they work, their till language, and the PIN and card they sign in at a till with.

Only an owner may, and never to their own role or locations: an owner cannot demote themselves out of their own back office. A PIN or card code is write-only. It is hashed on arrival and the member answers only whether one is set, and null clears it so the person can no longer sign in that way.

Guarded by If-Match: a change made against a role or locations somebody has since changed is refused with 412, to be re-read and decided again.

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

card_codestring

NullableWrite only
The code a sign-in card's reader emits, or null to take card sign-in away.
1–100 chars
custom_role_idstring · uuid

Nullable
The custom role the member carries, or null to take it away (they stand at their role alone).
languagestring · enum
The till's language while they are signed in (0017).
en-USen-GBesdefrjaitnlptsvpldanbfi
location_idsarray of string · uuid
Where they may act. Empty means every location.
≤ 500 items
pinstring

NullableWrite only
A new till sign-in PIN, 4 to 8 digits, or null to take PIN sign-in away.
pattern ^[0-9]{4,8}$
rolestring · enum
ownermanagerstaff

Responses

200
The changed team member.
Member · application/json
- idstring · uuid
  
  RequiredRead only
  The person's user id.
- namestring
  
  Required
  The person's display name.
- card_saltstring
  
  Read only
  The base64 per-member salt for the sign-on card's offline verifier, present only when a card is enrolled. A registered till caches the roster and, without a connection, checks sha256(salt + card code) against card_verifier to sign a member on; the server re-checks the SHA-256 hash online. Only ever sent to a device that may read the roster, so it must not be treated as a password.
- card_verifierstring
  
  Read only
  The base64 sha256(salt + card code) offline verifier for the sign-on card, present only when a card is enrolled. The device compares this to the hash of the code a card reader emitted; absent on a member with no card. Never a substitute for the server's SHA-256 check.
- custom_role_idstring · uuid
  
  Nullable
  The merchant's custom role this member carries, if any: a set of permissions granted IN ADDITION to their role (accounts-and-access item 4). A device never sees it; the server's checks do. null clears it — the member stands at their role alone. A role the merchant withdrew stays named; its grants are no longer answered.
- emailstring · email
  
  Required
- has_cardboolean
  
  Read only
  Whether this member has a till sign-on card enrolled. A till offers a card prompt when a member has one; the card code itself never leaves the server.
- has_pinboolean
  
  Read only
  Whether this member has a till sign-on PIN set. A till offers a PIN prompt only for members who have one; the PIN itself never leaves the server.
- languagestring
  The person's language for user-facing text, BCP 47 primary language and territory (the launch set: en-US, en-GB, es, de, fr, ja, it, nl, pt, sv, pl, da, nb, fi). The till reads in the language of whoever is signed in (0017); a Spanish-speaking kitchen and an English-speaking floor sharing one device each read it in their own language. Defaults to en-US.
  pattern ^[a-z]{2}(-[A-Z]{2})?$
- location_idsarray of string · uuid
  
  RequiredRead only
  The locations this member may act in, copied from the invitation that created the membership. Empty means unrestricted: the member may act at every location in the merchant. A till offers a member's sign-on or clock-in only at their locations.
- merchant_idstring · uuid
  
  RequiredRead only
- pin_saltstring
  
  Read only
  The base64 per-member salt for the sign-on PIN's offline verifier, present only when a PIN is set. A registered till caches the roster and, without a connection, checks sha256(salt + pin) against pin_verifier to sign a member on; the server re-checks the argon2id hash online. Only ever sent to a device that may read the roster, so it must not be treated as a password.
- pin_verifierstring
  
  Read only
  The base64 sha256(salt + pin) offline verifier for the sign-on PIN, present only when a PIN is set. The device compares this to the hash of what a person typed; present and empty on a member with no PIN. Never a substitute for the server's argon2id check.
- rolestring · enum
  
  Required
  What the person may do in this merchant.
  ownermanagerstaff
- statusstring · enum
  
  Required
  Whether the person may still act here.
  activeinactive
- versioninteger · int64
  
  Read only
  The version of the person's role, locations and standing, sent as If-Match to change or remove them. Their PIN, card and language do not move it. One person read on their own carries it; the roster does not.
  ≥ 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.
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/members/0192f1e4-7c3a-7b2e-9f10-5d6c7e8f9a0b' \
  -H "Authorization: Bearer $TOKEN" \
  -H 'If-Match: "3"' \
  -H 'Content-Type: application/merge-patch+json' \
  -d '{
  "card_code": "string",
  "custom_role_id": "0192f1e4-7c3a-7b2e-9f10-5d6c7e8f9a0b",
  "language": "en-US",
  "location_ids": [
    "0192f1e4-7c3a-7b2e-9f10-5d6c7e8f9a0b"
  ],
  "pin": "string",
  "role": "owner"
}'

Response

{
  "id": "0192f1e4-7c3a-7b2e-9f10-5d6c7e8f9a0b",
  "name": "string",
  "card_salt": "AAAAAAAAAAAAAAAAAAAAAA==",
  "card_verifier": "string",
  "custom_role_id": "0192f1e4-7c3a-7b2e-9f10-5d6c7e8f9a0b",
  "email": "ada@example.com",
  "has_card": false,
  "has_pin": false,
  "language": "string",
  "location_ids": [
    "0192f1e4-7c3a-7b2e-9f10-5d6c7e8f9a0b"
  ],
  "merchant_id": "0192f1e4-7c3a-7b2e-9f10-5d6c7e8f9a0b",
  "pin_salt": "AAAAAAAAAAAAAAAAAAAAAA==",
  "pin_verifier": "string",
  "role": "owner",
  "status": "active",
  "version": 0
}

DELETE/v1/members/{id}

Remove someone from the team

No. deleteMemberAuth pos:staff:manage

Signs a person out of every till and the back office for this merchant. The membership is kept as inactive, so their shifts, sales and tips stay on the record.

Only an owner may, and never themselves. Removing an owner tells the other owners. Guarded by If-Match, so removing someone whose role changed since it was read is refused with 412.

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

GET/v1/members/{id}/milestones

What a staff member can do

No. getMemberMilestonesAuth members:read

Answers the adoption-style questions about one member, derived at read time: work facts from the ledger (a completed sale or a cash sale rung under their sign-on), practice facts from the one row the till recorded when the first-shift track completed. Only the fact crosses the wire — never a practice sale.

Cover: staff-training item 5.

Parameters

idpath · string · uuid
Required
The roster's id — the member's user id.

Responses

200
The member's milestones, in the order the roster screen asks them.
array of MemberMilestone · application/json
- evidencestring
  The case in the merchant's own numbers, so the reason is theirs.
- keystring
  
  Required
  The catalogue key.
- metboolean
  
  Required
  Whether the member has done it.
- met_atstring · date-time
  When, where the question can know it — a practice fact carries its date.
- practiceboolean
  
  Required
  Whether this question can only ever be answered in practice.
- titlestring
  
  Required
  What the thing is, in the words the roster screen uses.
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 member at this merchant.
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/members/0192f1e4-7c3a-7b2e-9f10-5d6c7e8f9a0b/milestones' \
  -H "Authorization: Bearer $TOKEN"

Response

[
  {
    "evidence": "string",
    "key": "string",
    "met": false,
    "met_at": "2026-09-11T09:30:00Z",
    "practice": false,
    "title": "string"
  }
]

POST/v1/members/{id}/verify

Verify a staff member's sign-on PIN

No. verifyMemberPinAuth members:read

Checks a staff member's till sign-on PIN for the caller's merchant.

A till calls this when an operator picks their name and enters a PIN, so the device knows who is operating it without the PIN ever being stored on the device. The PIN is a short credential a manager sets; it is per-membership, so the same person may have a different one at another merchant.

Parameters

idpath · string · uuid
Required
The roster's id — the member's user 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 · MemberVerifyPinRequest

pinstring

Required
The member's sign-on PIN.
4–8 chars

Responses

204
The PIN is correct.
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 POST 'https://api.tenvelo.com/v1/members/0192f1e4-7c3a-7b2e-9f10-5d6c7e8f9a0b/verify' \
  -H "Authorization: Bearer $TOKEN" \
  -H 'Idempotency-Key: 01J8ZK3QF7X2N5V9C4B1A6D8E0' \
  -H 'Content-Type: application/json' \
  -d '{
  "pin": "string"
}'

GET/v1/notes

List notes from Tenvelo

No. listNotesAuth members:read

Returns what Tenvelo has told the people who run this business, newest first, each with whether the caller has said they got it. A note is acknowledged once per person; their own got-it rides the item so the list can show it without a second read.

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 notes.
NotePage · application/json
- has_moreboolean
  
  Required
  Whether a further page exists.
- itemsarray of Note
  
  Required
  - idstring · uuid
    
    Required
    The note's own id.
  - bodystring
    
    Required
    What Tenvelo is telling them.
    ≤ 500 chars
  - created_atstring · date-time
    
    Required
    When the note was written.
  - member_acknowledgedboolean
    
    Required
    Whether the caller has said they got it.
  - titlestring
    
    Required
    The line that tells a person at a glance what Tenvelo is saying.
    ≤ 120 chars
  - updated_atstring · date-time
    
    Required
    When the note was last written.
  - versioninteger · int64
    
    Required
    The version the caller last saw, for optimistic concurrency.
- next_cursorstring
  
  Nullable
  The 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/notes' \
  -H "Authorization: Bearer $TOKEN"

Response

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

POST/v1/notes/{id}/acknowledge

Say you got a note

No. acknowledgeNoteAuth members:write

Records that the caller said "got it" to a note from Tenvelo, once. Calling it again is still 204 — the person got it, and the first time stands.

Parameters

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

Responses

204
The acknowledgment is recorded — or was already.
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/notes/0192f1e4-7c3a-7b2e-9f10-5d6c7e8f9a0b/acknowledge' \
  -H "Authorization: Bearer $TOKEN" \
  -H 'Idempotency-Key: 01J8ZK3QF7X2N5V9C4B1A6D8E0'

POST/v1/practice/card-charges/calculate

Take a keyed card in training

No. calculatePracticeCardChargeAuth terminal-checkouts:write

Runs the card-not-present seam's simulator against a card a trainee keyed in, so the training till can take a card the way a real sale would — and never charge one: no order, no payment account and no merchant sits behind a request like this, and nothing is recorded. The answer is all there is; the practice store keeps the fact on the device, and the one thing a completed practice contributes to the shop is the milestone fact member-milestone-facts already carries (staff-training item 7).

calculate because it stores nothing: the simulator answers as the processor would, and a retry is harmless, so there is nothing for an idempotency key to guard. The card's last three digits script the outcome exactly as the processor simulator does in development, because this is that seam.

A practice charge is refused only on shape: no amount or a non-positive one, or card details a processor would refuse. It is never refused because the order is already settled or the merchant cannot take cards — none of those exist here.

Request body application/json · PracticeCardChargeRequest

idstring · uuid

Required
Minted by the till as a UUIDv7; a retry names the same practice charge.
amountMoney

Required
What the practice sale is to collect, tip included if one was added.
- amountinteger · int64
  
  Required
  The amount, as a whole number of the currency's minor unit. May be negative to express a refund, discount or credit.
- currencyCurrency
  
  Required
  ISO 4217 currency code.
  Determines the minor unit that Money.amount is expressed in. Zero-decimal currencies such as JPY have a minor unit equal to the major unit.
  One of 182 values; see the schema.
card_detailsCard details

Required
A card keyed in rather than tokenised: what somebody reads off a card and types at the till or over the phone. The details travel to the processor the payment account names and are never stored by the API — no card number is written down, logged or returned (one of card and card_details is required on a charge; a card read by a terminal or a guest page arrives as a token instead).
- cvcstring
  
  Required
  The card verification code on the back.
  3–4 chars
- expiry_monthinteger
  
  Required
  The month the card expires, 1-12.
  1–12
- expiry_yearinteger
  
  Required
  The year the card expires, as two or four digits (26 or 2026).
  ≥ 0
- holder_namestring
  The name as it appears on the card, when the processor wants it.
  ≤ 255 chars
- numberstring
  
  Required
  The card number, digits only; the server checks Luhn before the processor is asked.
  12–19 chars
tipMoney

Nullable
A tip the trainee added on top of the goods; part of amount.
- amountinteger · int64
  
  Required
  The amount, as a whole number of the currency's minor unit. May be negative to express a refund, discount or credit.
- currencyCurrency
  
  Required
  ISO 4217 currency code.
  Determines the minor unit that Money.amount is expressed in. Zero-decimal currencies such as JPY have a minor unit equal to the major unit.
  One of 182 values; see the schema.

Responses

200
The simulator's answer, as a real card would have answered.
PracticeCardCharge · application/json
- idstring · uuid
  
  Required
  Minted by the till; a retry names the same practice charge.
- amountMoney
  
  Required
  What was asked for, before any partial approval.
  - amountinteger · int64
    
    Required
    The amount, as a whole number of the currency's minor unit. May be negative to express a refund, discount or credit.
  - currencyCurrency
    
    Required
    ISO 4217 currency code.
    Determines the minor unit that Money.amount is expressed in. Zero-decimal currencies such as JPY have a minor unit equal to the major unit.
    One of 182 values; see the schema.
- card_brandstring
  
  Read only
  The card's scheme, as the simulator reported it. Empty when it reports none.
- card_last4string
  
  Read only
  The last four digits of the number keyed in, for the take to show.
  4–4 chars
- reasonstring
  
  Read only
  Why the simulator refused the card, for the trainee to read.
- referencestring
  
  Read only
  The simulator's reference for the practice charge, once approved.
  ≤ 128 chars
- statusstring · enum
  
  RequiredRead only
  approved — the simulator said the card would be taken. Final; reference is the fake reference a receipt would carry. declined — the card was refused. Final; reason says why. failed — the ask never got an answer (a scripted refusal, a lost response). The sale is untouched and the card was never charged.
  approveddeclinedfailed
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/practice/card-charges/calculate' \
  -H "Authorization: Bearer $TOKEN" \
  -H 'Content-Type: application/json' \
  -d '{
  "id": "0192f1e4-7c3a-7b2e-9f10-5d6c7e8f9a0b",
  "amount": {
    "amount": 1250,
    "currency": "GBP"
  },
  "card_details": {
    "cvc": "123",
    "expiry_month": 12,
    "expiry_year": 2026,
    "holder_name": "Nia Rowland",
    "number": "4111111111111111"
  },
  "tip": {
    "amount": 1250,
    "currency": "GBP"
  }
}'

Response

{
  "id": "0192f1e4-7c3a-7b2e-9f10-5d6c7e8f9a0b",
  "amount": {
    "amount": 1250,
    "currency": "GBP"
  },
  "card_brand": "string",
  "card_last4": "string",
  "reason": "string",
  "reference": "string",
  "status": "approved"
}

GET/v1/push-tokens

List the phones a person is pushed on

No. listPushTokensAuth members:read

Returns the phones the caller has registered to be pushed what needs them at this business, newest first, each with the kinds it is pushed (docs/decisions/0118). A person sees only their own.

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 caller's push tokens.
PushTokenPage · application/json
- has_moreboolean
  
  Required
  Whether another page follows.
- itemsarray of PushToken
  
  Required
  - idstring · uuid
    
    Required
    Minted by the app when it first registers the phone, and kept with it.
  - 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.
  - kindsarray of PushKind
    
    Required
    What the phone is pushed. Empty pushes nothing; a kind the person may not read is never pushed.
  - platformPushPlatform
    
    Required
    The push service a phone's token is for: Apple's (apns, a device token) or Google's Firebase Cloud Messaging (fcm, a registration token).
    apnsfcm
  - tokenstring
    
    Required
    The token the push service gave the app on this phone.
    1–4096 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
  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.

Request

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

Response

{
  "has_more": false,
  "items": [
    {
      "id": "0192f1e4-7c3a-7b2e-9f10-5d6c7e8f9a0b",
      "created_at": "2026-09-08T09:41:12Z",
      "kinds": [
        "dispute_due"
      ],
      "platform": "apns",
      "token": "string",
      "updated_at": "2026-09-08T09:41:12Z",
      "version": 7
    }
  ],
  "next_cursor": "string"
}

POST/v1/push-tokens/batch-upsert

Register a phone to be pushed, or change what it is pushed

No. batchUpsertPushTokensAuth members:write

Registers the caller's phone with the token its platform's push service gave it, and the kinds of Needs you item it is pushed, or changes either (docs/decisions/0118). The phone names its registration with an id it mints and keeps: without version an item registers it, and with it the item changes the registration read at that version. A registration another person made on the same phone is taken over by whoever signs in next, so a phone is pushed for the person using it.

A person is pushed a kind only where they may read it: a dispute is never pushed to somebody who may not see disputes, whatever their phone asks for. Each item carries its own idempotency_key and stands or falls on its own. A device or an integration is refused: a push is to a person.

Request body application/json · PushTokenBatchUpsertRequest

itemsarray of PushTokenBatchUpsertItem

Required
≥ 1 items · ≤ 500 items
- idstring · uuid
  
  Required
  The registration's id, a UUIDv7 the app mints the first time and keeps.
- 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
- kindsarray of PushKind
  
  Required
- platformPushPlatform
  
  Required
  The push service a phone's token is for: Apple's (apns, a device token) or Google's Firebase Cloud Messaging (fcm, a registration token).
  apnsfcm
- tokenstring
  
  Required
  1–4096 chars
- versioninteger · int64
  The version this write was made from. Required to change a registration that exists, and refused as 412 when it has been written 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.

Request

curl -X POST 'https://api.tenvelo.com/v1/push-tokens/batch-upsert' \
  -H "Authorization: Bearer $TOKEN" \
  -H 'Content-Type: application/json' \
  -d '{
  "items": [
    {
      "id": "0192f1e4-7c3a-7b2e-9f10-5d6c7e8f9a0b",
      "idempotency_key": "01J8ZK3QF7X2N5V9C4B1A6D8E0",
      "kinds": [
        "dispute_due"
      ],
      "platform": "apns",
      "token": "string",
      "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
    }
  ]
}

DELETE/v1/push-tokens/{id}

Stop pushing a phone

No. deletePushTokenAuth members:write

Removes the caller's registration of a phone, guarded by If-Match, as signing out of the app does. The phone is pushed nothing more for this business.

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 phone is no longer pushed.
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/roles

What each role may do

No. getRoleTableAuth members:read

Each role's summary and every permission the server enforces, with the roles it is granted to, generated from the rules the server checks. Knowing the rules is not a secret: any signed-in person may read them.

Responses

200
The table.
RoleTable · application/json
- permissionsarray of RolePermission
  
  Required
  Every permission, grouped and in the order a table reads them.
  - namestring
    
    Required
    The rule's own name, stable for a client to key on.
  - conditionalboolean
    
    Required
    Whether the answer depends on the thing acted on rather than the role alone.
  - granted_toarray of string · enum
    
    Required
    The roles it is granted to; empty when it depends on the thing acted on.
  - groupstring · enum
    
    Required
    Where a person reading the table looks for it.
    sellingcatalog_and_inventorykitchen_and_floorteam_and_paycustomersmoneybusinessdevelopers
  - whatstring
    
    Required
    What it lets a person do, in a sentence.
- rolesarray of RoleSummary
  
  Required
  - rolestring · enum
    
    Required
    ownermanagerstaff
  - summarystring
    
    Required
    What the role is for, in a sentence.
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/roles' \
  -H "Authorization: Bearer $TOKEN"

Response

{
  "permissions": [
    {
      "name": "string",
      "conditional": false,
      "granted_to": [
        "owner"
      ],
      "group": "selling",
      "what": "string"
    }
  ],
  "roles": [
    {
      "role": "owner",
      "summary": "string"
    }
  ]
}

GET/v1/scim-token

Read the directory's SCIM token

No. getSCIMTokenAuth sign-in-policy:write

When the organisation's directory's SCIM token was made, and the base URL it calls (docs/decisions/0125 §3). The token itself is shown only when it is made. An owner's alone.

Responses

200
The token as it stands.
SCIMToken · application/json
- made_atstring · date-time
  
  RequiredNullable
  When the token in use was made, or null when the directory has none.
- urlstring · uri
  
  Required
  The SCIM base URL the directory calls, its "tenant URL".
  ≤ 2048 chars
400
The request could not be parsed. Malformed JSON, a bad query parameter, or a header that failed to decode, among them an API-Version later than the server speaks or not a date (api-version-unknown, with the server's own in api_version).
Distinct from 422: a 400 never reached validation, so invalid_params is absent. Retrying without changing the request will fail again, except that a request refused for its API-Version goes once the server is updated.
401
No credentials, or credentials that could not be verified — missing bearer token, malformed JWT, expired token, or a signature that failed against the issuer's JWKS.
Refresh the token and retry once. Repeated 401 after a refresh means the device needs to re-enrol.
403
Authenticated, but not permitted. The token is valid and its merchant was resolved, but the caller's role does not allow this operation, or the target belongs to a different merchant.
Cross-tenant access is reported as 403 on a resource the caller may not see, and as 404 where even confirming existence would leak information. Retrying will not help.
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.

POST/v1/scim-token/revoke

Take the directory's SCIM token away

No. revokeSCIMTokenAuth sign-in-policy:write

Withdraws the token in use, so the directory reaches nothing. One already gone is no error. An owner's alone.

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.

Responses

204
Done.
400
The request could not be parsed. Malformed JSON, a bad query parameter, or a header that failed to decode, among them an API-Version later than the server speaks or not a date (api-version-unknown, with the server's own in api_version).
Distinct from 422: a 400 never reached validation, so invalid_params is absent. Retrying without changing the request will fail again, except that a request refused for its API-Version goes once the server is updated.
401
No credentials, or credentials that could not be verified — missing bearer token, malformed JWT, expired token, or a signature that failed against the issuer's JWKS.
Refresh the token and retry once. Repeated 401 after a refresh means the device needs to re-enrol.
403
Authenticated, but not permitted. The token is valid and its merchant was resolved, but the caller's role does not allow this operation, or the target belongs to a different merchant.
Cross-tenant access is reported as 403 on a resource the caller may not see, and as 404 where even confirming existence would leak information. Retrying will not help.
409
The request conflicts with current state — a uniqueness constraint, or an attempt to mutate an order that is already completed or voided.
Unlike 412, re-reading and retrying unchanged will not resolve it; the request itself has to change.
410
The request names an API-Version this server no longer serves (docs/decisions/0011). Nothing in it was read. api_version names the version the server speaks: the client is behind, and sends the request again once it is updated.
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/scim-token/rotate

Make the directory a new SCIM token

No. rotateSCIMTokenAuth sign-in-policy:write

Makes a new token in place of any in use, which stops working at once, and answers it this once. An owner's alone.

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.

Responses

200
Done.
SCIMTokenMade · application/json
- made_atstring · date-time
  
  Required
- tokenstring
  
  Required
  The bearer token the directory calls SCIM with.
  ≤ 100 chars
- urlstring · uri
  
  Required
  The SCIM base URL the directory calls.
  ≤ 2048 chars
400
The request could not be parsed. Malformed JSON, a bad query parameter, or a header that failed to decode, among them an API-Version later than the server speaks or not a date (api-version-unknown, with the server's own in api_version).
Distinct from 422: a 400 never reached validation, so invalid_params is absent. Retrying without changing the request will fail again, except that a request refused for its API-Version goes once the server is updated.
401
No credentials, or credentials that could not be verified — missing bearer token, malformed JWT, expired token, or a signature that failed against the issuer's JWKS.
Refresh the token and retry once. Repeated 401 after a refresh means the device needs to re-enrol.
403
Authenticated, but not permitted. The token is valid and its merchant was resolved, but the caller's role does not allow this operation, or the target belongs to a different merchant.
Cross-tenant access is reported as 403 on a resource the caller may not see, and as 404 where even confirming existence would leak information. Retrying will not help.
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.

Request

curl -X POST 'https://api.tenvelo.com/v1/scim-token/rotate' \
  -H "Authorization: Bearer $TOKEN" \
  -H 'Idempotency-Key: 01J8ZK3QF7X2N5V9C4B1A6D8E0'

Response

{
  "made_at": "2026-09-11T09:30:00Z",
  "token": "string",
  "url": "https://example.com"
}

GET/v1/sign-in-policy

Read the sign-in policy

No. getSignInPolicyAuth members:read

What the business asks of its people's sign-ins, on top of the platform's floor (docs/decisions/0123 §3). Anybody in the business may read it.

Responses

200
The sign-in policy.
SignInPolicy · application/json
- second_stepsstring · enum
  
  Required
  Which second steps count: a passkey, a security key or an authenticator app's code, or only a passkey or a security key, which a fake page cannot catch.
  anypasskeys_and_security_keys
- social_sign_inboolean
  
  Required
  Whether Google and Microsoft may sign people in to this business.
- text_messageboolean
  
  Required
  Whether a code sent by text message counts as a second step for this business's work. Off unless the business turns it on: a number can be taken over by a SIM swap (NIST SP 800-63B-4 §3.1.3.3, restricted), and it is never phishing-resistant, so it never counts where only passkeys and security keys do.
- two_steps_forstring · enum
  
  Required
  Who signs in with two steps: owners alone, owners and managers, or everyone in the back office. Owners alone need them only once the business has a payment account; the others from the start. A till keeps its PIN or card whatever this says.
  ownersowners_and_managerseveryone
- 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.
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/sign-in-policy' \
  -H "Authorization: Bearer $TOKEN"

Response

{
  "second_steps": "any",
  "social_sign_in": false,
  "text_message": false,
  "two_steps_for": "owners",
  "version": 7
}

PATCH/v1/sign-in-policy

Change the sign-in policy

No. updateSignInPolicyAuth sign-in-policy:write

Applies a JSON Merge Patch (RFC 7396) to the sign-in policy, guarded by If-Match on the version read. An owner's act alone: it decides who can reach the business, so an integration holding sign-in-policy:write is refused, as is a support visit or a partner working in the business. Each person is held to it from their next sign-in.

Parameters

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

second_stepsstring · enum
anypasskeys_and_security_keys
social_sign_inboolean
text_messageboolean
two_steps_forstring · enum
ownersowners_and_managerseveryone

Responses

200
The changed sign-in policy.
SignInPolicy · application/json
- second_stepsstring · enum
  
  Required
  Which second steps count: a passkey, a security key or an authenticator app's code, or only a passkey or a security key, which a fake page cannot catch.
  anypasskeys_and_security_keys
- social_sign_inboolean
  
  Required
  Whether Google and Microsoft may sign people in to this business.
- text_messageboolean
  
  Required
  Whether a code sent by text message counts as a second step for this business's work. Off unless the business turns it on: a number can be taken over by a SIM swap (NIST SP 800-63B-4 §3.1.3.3, restricted), and it is never phishing-resistant, so it never counts where only passkeys and security keys do.
- two_steps_forstring · enum
  
  Required
  Who signs in with two steps: owners alone, owners and managers, or everyone in the back office. Owners alone need them only once the business has a payment account; the others from the start. A till keeps its PIN or card whatever this says.
  ownersowners_and_managerseveryone
- 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.
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/sign-in-policy' \
  -H "Authorization: Bearer $TOKEN" \
  -H 'If-Match: "3"' \
  -H 'Content-Type: application/merge-patch+json' \
  -d '{
  "second_steps": "any",
  "social_sign_in": false,
  "text_message": false,
  "two_steps_for": "owners"
}'

Response

{
  "second_steps": "any",
  "social_sign_in": false,
  "text_message": false,
  "two_steps_for": "owners",
  "version": 7
}

GET/v1/sign-on/card

Identify the member a sign-on card belongs to

No. getMemberByCardAuth members:read

Returns the member a sign-on card belongs to.

The till reads the card's code (whatever the reader emits) — a magstripe, a printed code, an RFID UID — and sends it here, so the device knows who is operating it without the code being stored on the device. The code is SHA-256 hashed and matched against the merchant the caller token belongs to, so a card enrolled at another merchant answers as not found. A member signs on with a card the way they do with a PIN: this is a short credential on an existing membership, not a second identity.

Parameters

card_codequery · string
Required
The card's code, as read from the card.

Responses

200
The member the card belongs to.
Member · application/json
- idstring · uuid
  
  RequiredRead only
  The person's user id.
- namestring
  
  Required
  The person's display name.
- card_saltstring
  
  Read only
  The base64 per-member salt for the sign-on card's offline verifier, present only when a card is enrolled. A registered till caches the roster and, without a connection, checks sha256(salt + card code) against card_verifier to sign a member on; the server re-checks the SHA-256 hash online. Only ever sent to a device that may read the roster, so it must not be treated as a password.
- card_verifierstring
  
  Read only
  The base64 sha256(salt + card code) offline verifier for the sign-on card, present only when a card is enrolled. The device compares this to the hash of the code a card reader emitted; absent on a member with no card. Never a substitute for the server's SHA-256 check.
- custom_role_idstring · uuid
  
  Nullable
  The merchant's custom role this member carries, if any: a set of permissions granted IN ADDITION to their role (accounts-and-access item 4). A device never sees it; the server's checks do. null clears it — the member stands at their role alone. A role the merchant withdrew stays named; its grants are no longer answered.
- emailstring · email
  
  Required
- has_cardboolean
  
  Read only
  Whether this member has a till sign-on card enrolled. A till offers a card prompt when a member has one; the card code itself never leaves the server.
- has_pinboolean
  
  Read only
  Whether this member has a till sign-on PIN set. A till offers a PIN prompt only for members who have one; the PIN itself never leaves the server.
- languagestring
  The person's language for user-facing text, BCP 47 primary language and territory (the launch set: en-US, en-GB, es, de, fr, ja, it, nl, pt, sv, pl, da, nb, fi). The till reads in the language of whoever is signed in (0017); a Spanish-speaking kitchen and an English-speaking floor sharing one device each read it in their own language. Defaults to en-US.
  pattern ^[a-z]{2}(-[A-Z]{2})?$
- location_idsarray of string · uuid
  
  RequiredRead only
  The locations this member may act in, copied from the invitation that created the membership. Empty means unrestricted: the member may act at every location in the merchant. A till offers a member's sign-on or clock-in only at their locations.
- merchant_idstring · uuid
  
  RequiredRead only
- pin_saltstring
  
  Read only
  The base64 per-member salt for the sign-on PIN's offline verifier, present only when a PIN is set. A registered till caches the roster and, without a connection, checks sha256(salt + pin) against pin_verifier to sign a member on; the server re-checks the argon2id hash online. Only ever sent to a device that may read the roster, so it must not be treated as a password.
- pin_verifierstring
  
  Read only
  The base64 sha256(salt + pin) offline verifier for the sign-on PIN, present only when a PIN is set. The device compares this to the hash of what a person typed; present and empty on a member with no PIN. Never a substitute for the server's argon2id check.
- rolestring · enum
  
  Required
  What the person may do in this merchant.
  ownermanagerstaff
- statusstring · enum
  
  Required
  Whether the person may still act here.
  activeinactive
- versioninteger · int64
  
  Read only
  The version of the person's role, locations and standing, sent as If-Match to change or remove them. Their PIN, card and language do not move it. One person read on their own carries it; the roster does not.
  ≥ 0
400
The request could not be parsed. Malformed JSON, a bad query parameter, or a header that failed to decode, among them an API-Version later than the server speaks or not a date (api-version-unknown, with the server's own in api_version).
Distinct from 422: a 400 never reached validation, so invalid_params is absent. Retrying without changing the request will fail again, except that a request refused for its API-Version goes once the server is updated.
401
No credentials, or credentials that could not be verified — missing bearer token, malformed JWT, expired token, or a signature that failed against the issuer's JWKS.
Refresh the token and retry once. Repeated 401 after a refresh means the device needs to re-enrol.
403
Authenticated, but not permitted. The token is valid and its merchant was resolved, but the caller's role does not allow this operation, or the target belongs to a different merchant.
Cross-tenant access is reported as 403 on a resource the caller may not see, and as 404 where even confirming existence would leak information. Retrying will not help.
410
The request names an API-Version this server no longer serves (docs/decisions/0011). Nothing in it was read. api_version names the version the server speaks: the client is behind, and sends the request again once it is updated.
422
The request parsed but failed validation.
invalid_params lists every failing field with a JSON Pointer, not just the first, so a client can mark up a whole form in one pass rather than making the user fix errors one round trip at a time.
Also returned when an Idempotency-Key is replayed with a different body, and when device-computed order totals disagree with the server's recomputation.
429
Rate limit exceeded. Honour Retry-After rather than applying your own backoff.
A fleet of tills coming back online together after an outage is the realistic cause, which is exactly when uncoordinated client-side retry turns a brief outage into a sustained one. The limit is per process, and per site for what records trade there — a request spends its site's budget, and a till's own smaller one inside it — and per (client, merchant) for everything else; no RateLimit field is sent, so this response and its Retry-After are the whole of the contract.
500
Something failed on our side. trace_id identifies the request in our tracing — quote it in a support ticket.
The body never carries internal detail: no SQL, no stack traces, no upstream error strings. Safe to retry with the same Idempotency-Key.
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/sign-on/card?card_code=…' \
  -H "Authorization: Bearer $TOKEN"

Response

{
  "id": "0192f1e4-7c3a-7b2e-9f10-5d6c7e8f9a0b",
  "name": "string",
  "card_salt": "AAAAAAAAAAAAAAAAAAAAAA==",
  "card_verifier": "string",
  "custom_role_id": "0192f1e4-7c3a-7b2e-9f10-5d6c7e8f9a0b",
  "email": "ada@example.com",
  "has_card": false,
  "has_pin": false,
  "language": "string",
  "location_ids": [
    "0192f1e4-7c3a-7b2e-9f10-5d6c7e8f9a0b"
  ],
  "merchant_id": "0192f1e4-7c3a-7b2e-9f10-5d6c7e8f9a0b",
  "pin_salt": "AAAAAAAAAAAAAAAAAAAAAA==",
  "pin_verifier": "string",
  "role": "owner",
  "status": "active",
  "version": 0
}

GET/v1/sso-connection

Read the business's SSO connection

No. getSSOConnectionAuth members:read

The business's own identity provider, the domains it claims and the validation record each needs (docs/decisions/0123 §5). An owner's alone to read, as to change.

Responses

200
The SSO connection; one never set up is kept off.
SSOConnection · application/json
- client_idstring
  
  Required
  The client id the provider registered the organisation's sign-in under; empty until set.
  ≤ 255 chars
- domainsarray of SSODomain
  
  Required
  ≤ 20 items
  - namestring
    
    Required
    The domain, lower case, in its ASCII form.
    ≤ 253 chars
  - record_namestring
    
    Required
    Where the TXT record goes.
    ≤ 300 chars
  - tokenstring
    
    Required
    What the TXT record holds. Claiming the domain again asks for a new one.
    ≤ 64 chars
  - verified_atstring · date-time
    
    RequiredNullable
    When the record was found, or null while it is awaited.
- enforcementSsoEnforcement
  
  Required
  How the organisation's people use its SSO connection (docs/decisions/0123 §5). off keeps it without offering it; optional offers it beside every other way in; required gives somebody with an address in a verified domain the organisation's work only through it, but for the owners' or admins' break-glass route.
  offoptionalrequired
- has_client_secretboolean
  
  Required
  Whether a client secret is held, sealed.
- issuerstring
  
  Required
  The OpenID issuer, as its discovery document names it, or the SAML entity ID the metadata names; empty until set.
  ≤ 1024 chars
- joinSSOJoin
  
  RequiredNullable
  How somebody the connection signs in joins the organisation there and then, without an invitation (docs/decisions/0125 §2); null when people join by invitation alone.
  - location_idsarray of string · uuid
    
    Required
    A business's locations they work at; empty for every one, and for a partner.
    ≤ 100 items
  - rolestring · enum
    
    Required
    Staff or a manager in a business; a member of a partner.
    staffmanagermember
- protocolSSOProtocol
  
  Required
  How the organisation's own sign-in works: OpenID Connect, or SAML 2.0's Web Browser SSO profile (docs/decisions/0125 §1).
  oidcsaml
- samlSSOSAML
  
  Required
  What each side of a SAML connection gives the other (docs/decisions/0125 §1): the service provider the organisation registers at its own sign-in, and what the metadata it gave back says.
  - acs_urlstring · uri
    
    Required
    The assertion consumer service, where answers are posted.
  - certificate_expires_atstring · date-time
    
    RequiredNullable
    When the first certificate it signs with runs out; null until metadata is given.
  - entity_idstring · uri
    
    Required
    Our entity ID for the organisation, where our metadata for it is served.
  - sign_in_urlstring · uri
    
    RequiredNullable
    Where the organisation's metadata sends people to sign in; null until metadata is given.
- trusts_two_stepboolean
  
  Required
  Whether a sign-in the provider says took two steps counts as two (NIST SP 800-63C). When off, or when the provider says nothing, the second step is ours.
- versioninteger · int64
  
  Required
  The version a change names in 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.
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/sso-connection' \
  -H "Authorization: Bearer $TOKEN"

Response

{
  "client_id": "string",
  "domains": [
    {
      "name": "string",
      "record_name": "string",
      "token": "string",
      "verified_at": "2026-09-11T09:30:00Z"
    }
  ],
  "enforcement": "off",
  "has_client_secret": false,
  "issuer": "string",
  "join": {
    "location_ids": [
      "0192f1e4-7c3a-7b2e-9f10-5d6c7e8f9a0b"
    ],
    "role": "staff"
  },
  "protocol": "oidc",
  "saml": {
    "acs_url": "https://example.com",
    "certificate_expires_at": "2026-09-11T09:30:00Z",
    "entity_id": "https://example.com",
    "sign_in_url": "https://example.com"
  },
  "trusts_two_step": false,
  "version": 0
}

PATCH/v1/sso-connection

Change the business's SSO connection

No. updateSSOConnectionAuth sign-in-policy:write

Applies a JSON Merge Patch (RFC 7396) to the SSO connection, guarded by If-Match on the version read. An owner's act alone, as for the sign-in policy. It is turned on only once it has an issuer, a client id, a secret and a verified domain. A single Microsoft tenant's issuer names its tenant; Microsoft's endpoints for every tenant are social sign-in and refused.

Parameters

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

client_idstring
≤ 255 chars
client_secretstring

Write only
A new client secret, sealed as it is saved; empty keeps the one held.
≤ 1024 chars
domainsarray of string
Every domain claimed. One kept keeps its record and whether it was verified; a new one is asked for a record of its own.
≤ 20 items
enforcementSsoEnforcement
How the organisation's people use its SSO connection (docs/decisions/0123 §5). off keeps it without offering it; optional offers it beside every other way in; required gives somebody with an address in a verified domain the organisation's work only through it, but for the owners' or admins' break-glass route.
offoptionalrequired
issuerstring
≤ 255 chars
joinSSOJoin

Nullable
How newcomers join, or null for by invitation alone.
- location_idsarray of string · uuid
  
  Required
  A business's locations they work at; empty for every one, and for a partner.
  ≤ 100 items
- rolestring · enum
  
  Required
  Staff or a manager in a business; a member of a partner.
  staffmanagermember
protocolSSOProtocol
How the organisation's own sign-in works: OpenID Connect, or SAML 2.0's Web Browser SSO profile (docs/decisions/0125 §1).
oidcsaml
saml_metadatastring

Write only
The SAML metadata the organisation's sign-in publishes, which names its entity ID, where it signs people in and the certificates it signs with.
≤ 262144 chars
trusts_two_stepboolean

Responses

200
The changed SSO connection.
SSOConnection · application/json
- client_idstring
  
  Required
  The client id the provider registered the organisation's sign-in under; empty until set.
  ≤ 255 chars
- domainsarray of SSODomain
  
  Required
  ≤ 20 items
  - namestring
    
    Required
    The domain, lower case, in its ASCII form.
    ≤ 253 chars
  - record_namestring
    
    Required
    Where the TXT record goes.
    ≤ 300 chars
  - tokenstring
    
    Required
    What the TXT record holds. Claiming the domain again asks for a new one.
    ≤ 64 chars
  - verified_atstring · date-time
    
    RequiredNullable
    When the record was found, or null while it is awaited.
- enforcementSsoEnforcement
  
  Required
  How the organisation's people use its SSO connection (docs/decisions/0123 §5). off keeps it without offering it; optional offers it beside every other way in; required gives somebody with an address in a verified domain the organisation's work only through it, but for the owners' or admins' break-glass route.
  offoptionalrequired
- has_client_secretboolean
  
  Required
  Whether a client secret is held, sealed.
- issuerstring
  
  Required
  The OpenID issuer, as its discovery document names it, or the SAML entity ID the metadata names; empty until set.
  ≤ 1024 chars
- joinSSOJoin
  
  RequiredNullable
  How somebody the connection signs in joins the organisation there and then, without an invitation (docs/decisions/0125 §2); null when people join by invitation alone.
  - location_idsarray of string · uuid
    
    Required
    A business's locations they work at; empty for every one, and for a partner.
    ≤ 100 items
  - rolestring · enum
    
    Required
    Staff or a manager in a business; a member of a partner.
    staffmanagermember
- protocolSSOProtocol
  
  Required
  How the organisation's own sign-in works: OpenID Connect, or SAML 2.0's Web Browser SSO profile (docs/decisions/0125 §1).
  oidcsaml
- samlSSOSAML
  
  Required
  What each side of a SAML connection gives the other (docs/decisions/0125 §1): the service provider the organisation registers at its own sign-in, and what the metadata it gave back says.
  - acs_urlstring · uri
    
    Required
    The assertion consumer service, where answers are posted.
  - certificate_expires_atstring · date-time
    
    RequiredNullable
    When the first certificate it signs with runs out; null until metadata is given.
  - entity_idstring · uri
    
    Required
    Our entity ID for the organisation, where our metadata for it is served.
  - sign_in_urlstring · uri
    
    RequiredNullable
    Where the organisation's metadata sends people to sign in; null until metadata is given.
- trusts_two_stepboolean
  
  Required
  Whether a sign-in the provider says took two steps counts as two (NIST SP 800-63C). When off, or when the provider says nothing, the second step is ours.
- versioninteger · int64
  
  Required
  The version a change names in 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.
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/sso-connection' \
  -H "Authorization: Bearer $TOKEN" \
  -H 'If-Match: "3"' \
  -H 'Content-Type: application/merge-patch+json' \
  -d '{
  "client_id": "string",
  "client_secret": "string",
  "domains": [
    "string"
  ],
  "enforcement": "off",
  "issuer": "string",
  "join": {
    "location_ids": [
      "0192f1e4-7c3a-7b2e-9f10-5d6c7e8f9a0b"
    ],
    "role": "staff"
  },
  "protocol": "oidc",
  "saml_metadata": "string",
  "trusts_two_step": false
}'

Response

{
  "client_id": "string",
  "domains": [
    {
      "name": "string",
      "record_name": "string",
      "token": "string",
      "verified_at": "2026-09-11T09:30:00Z"
    }
  ],
  "enforcement": "off",
  "has_client_secret": false,
  "issuer": "string",
  "join": {
    "location_ids": [
      "0192f1e4-7c3a-7b2e-9f10-5d6c7e8f9a0b"
    ],
    "role": "staff"
  },
  "protocol": "oidc",
  "saml": {
    "acs_url": "https://example.com",
    "certificate_expires_at": "2026-09-11T09:30:00Z",
    "entity_id": "https://example.com",
    "sign_in_url": "https://example.com"
  },
  "trusts_two_step": false,
  "version": 0
}

POST/v1/sso-connection/verify

Check the business's domains for their validation records

No. verifySSOConnectionAuth sign-in-policy:write

Looks up the TXT record each domain still waiting was asked to publish, and records the ones found as verified, guarded by If-Match on the version read. A record is believed from a resolver that validated it with DNSSEC, or else from every resolver the deployment asks agreeing (draft-ietf-dnsop-domain-verification-techniques §9.7). A domain whose record is not there yet stays waiting; a resolver that cannot be reached is a 503. An owner's act alone.

Parameters

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 SSO connection, each domain found now verified.
SSOConnection · application/json
- client_idstring
  
  Required
  The client id the provider registered the organisation's sign-in under; empty until set.
  ≤ 255 chars
- domainsarray of SSODomain
  
  Required
  ≤ 20 items
  - namestring
    
    Required
    The domain, lower case, in its ASCII form.
    ≤ 253 chars
  - record_namestring
    
    Required
    Where the TXT record goes.
    ≤ 300 chars
  - tokenstring
    
    Required
    What the TXT record holds. Claiming the domain again asks for a new one.
    ≤ 64 chars
  - verified_atstring · date-time
    
    RequiredNullable
    When the record was found, or null while it is awaited.
- enforcementSsoEnforcement
  
  Required
  How the organisation's people use its SSO connection (docs/decisions/0123 §5). off keeps it without offering it; optional offers it beside every other way in; required gives somebody with an address in a verified domain the organisation's work only through it, but for the owners' or admins' break-glass route.
  offoptionalrequired
- has_client_secretboolean
  
  Required
  Whether a client secret is held, sealed.
- issuerstring
  
  Required
  The OpenID issuer, as its discovery document names it, or the SAML entity ID the metadata names; empty until set.
  ≤ 1024 chars
- joinSSOJoin
  
  RequiredNullable
  How somebody the connection signs in joins the organisation there and then, without an invitation (docs/decisions/0125 §2); null when people join by invitation alone.
  - location_idsarray of string · uuid
    
    Required
    A business's locations they work at; empty for every one, and for a partner.
    ≤ 100 items
  - rolestring · enum
    
    Required
    Staff or a manager in a business; a member of a partner.
    staffmanagermember
- protocolSSOProtocol
  
  Required
  How the organisation's own sign-in works: OpenID Connect, or SAML 2.0's Web Browser SSO profile (docs/decisions/0125 §1).
  oidcsaml
- samlSSOSAML
  
  Required
  What each side of a SAML connection gives the other (docs/decisions/0125 §1): the service provider the organisation registers at its own sign-in, and what the metadata it gave back says.
  - acs_urlstring · uri
    
    Required
    The assertion consumer service, where answers are posted.
  - certificate_expires_atstring · date-time
    
    RequiredNullable
    When the first certificate it signs with runs out; null until metadata is given.
  - entity_idstring · uri
    
    Required
    Our entity ID for the organisation, where our metadata for it is served.
  - sign_in_urlstring · uri
    
    RequiredNullable
    Where the organisation's metadata sends people to sign in; null until metadata is given.
- trusts_two_stepboolean
  
  Required
  Whether a sign-in the provider says took two steps counts as two (NIST SP 800-63C). When off, or when the provider says nothing, the second step is ours.
- versioninteger · int64
  
  Required
  The version a change names in 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.
410
The request names an API-Version this server no longer serves (docs/decisions/0011). Nothing in it was read. api_version names the version the server speaks: the client is behind, and sends the request again once it is updated.
412
The If-Match version did not match the resource's current version: someone else wrote since you read.
This is the expected, healthy outcome of two clients editing the same record — not an error condition to suppress. Re-read the resource, re-apply your change on top of the new state, and retry with the fresh ETag.
429
Rate limit exceeded. Honour Retry-After rather than applying your own backoff.
A fleet of tills coming back online together after an outage is the realistic cause, which is exactly when uncoordinated client-side retry turns a brief outage into a sustained one. The limit is per process, and per site for what records trade there — a request spends its site's budget, and a till's own smaller one inside it — and per (client, merchant) for everything else; no RateLimit field is sent, so this response and its Retry-After are the whole of the contract.
500
Something failed on our side. trace_id identifies the request in our tracing — quote it in a support ticket.
The body never carries internal detail: no SQL, no stack traces, no upstream error strings. Safe to retry with the same Idempotency-Key.
503
Temporarily unable to serve the request — a dependency is down or the service is shedding load.
Retry with the same Idempotency-Key after Retry-After. This is always safe: a request that did take effect before the failure will be recognised as a replay.

Request

curl -X POST 'https://api.tenvelo.com/v1/sso-connection/verify' \
  -H "Authorization: Bearer $TOKEN" \
  -H 'If-Match: "3"' \
  -H 'Idempotency-Key: 01J8ZK3QF7X2N5V9C4B1A6D8E0'

Response

{
  "client_id": "string",
  "domains": [
    {
      "name": "string",
      "record_name": "string",
      "token": "string",
      "verified_at": "2026-09-11T09:30:00Z"
    }
  ],
  "enforcement": "off",
  "has_client_secret": false,
  "issuer": "string",
  "join": {
    "location_ids": [
      "0192f1e4-7c3a-7b2e-9f10-5d6c7e8f9a0b"
    ],
    "role": "staff"
  },
  "protocol": "oidc",
  "saml": {
    "acs_url": "https://example.com",
    "certificate_expires_at": "2026-09-11T09:30:00Z",
    "entity_id": "https://example.com",
    "sign_in_url": "https://example.com"
  },
  "trusts_two_step": false,
  "version": 0
}

POST/v1/visit-tokens

Open a support visit

No. createVisitTokenAuth no token

Spends the handoff the operator's partners app was given for a visit (0046), once and within its minute, for the visit's own token: what the office app reads the business with for the visit's hour. It acts for the business as its owner would read it, with the visiting member of the operator's team as the actor (RFC 8693's act), so it writes nothing and takes no copy of the business's data away. A handoff that is unknown, spent or stale is a 401.

Public: the handoff is the credential. Rate limited per client 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 · VisitTokenCreate

handoffstring

Required
Good once, for a minute after the visit was opened.
1–128 chars

Responses

201
The visit is open, and this is its token.
VisitToken · application/json
- access_tokenstring
  
  RequiredRead only
  Sent as a bearer token on every call of the visit.
- expires_atstring · date-time
  
  RequiredRead only
  When the visit's hour is up; it is not renewed.
- merchant_idstring · uuid
  
  RequiredRead only
- token_typestring · enum
  
  RequiredRead only
  Bearer
- visitor_namestring
  
  RequiredRead only
  The member of the operator's team who is visiting, as the business is told.
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/visit-tokens' \
  -H 'Idempotency-Key: 01J8ZK3QF7X2N5V9C4B1A6D8E0' \
  -H 'Content-Type: application/json' \
  -d '{
  "handoff": "string"
}'

Response

{
  "access_token": "string",
  "expires_at": "2026-09-11T09:30:00Z",
  "merchant_id": "0192f1e4-7c3a-7b2e-9f10-5d6c7e8f9a0b",
  "token_type": "Bearer",
  "visitor_name": "string"
}

POST/v1/visit-tokens/current/revoke

End a support visit

No. revokeCurrentVisitTokenAuth bearer

Ends the visit the token is on, before its hour is up: its token stops reading the business on the next request. The one write a visit may make.

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.

Responses

204
The visit is over.
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/visits

List support visits

No. listVisitsAuth audit:read

Returns every time the operator's support team has visited the caller's business, newest first: who, why, when it started and for how long. A visit needs no permission from the business, but it is never unseen: this is the record of each one.

An owner or a manager reads them.

Parameters

cursorquery · string
Opaque cursor from a previous page's next_cursor. Omit to start from the beginning.
Pass it back exactly as received. It is base64 and its structure is not part of this contract — decoding it, or constructing one by hand, will break without notice.
limitquery · integer · int32
Maximum items to return. The server may return fewer, so always drive the loop from has_more rather than from the size of the page you got back.

Responses

200
A page of visits.
VisitPage · application/json
- has_moreboolean
  
  Required
- itemsarray of Visit
  
  Required
  - idstring · uuid
    
    Required
  - created_atstring · date-time
    
    Required
  - ended_atstring · date-time
    When the visitor ended it. Absent if it ran out or is still open.
  - expires_atstring · date-time
    
    Required
    When the visit runs out if nobody ends it first.
  - minutesinteger
    How long the visitor was in, from opening to ending, running out, or now. Absent for a visit never opened.
    ≥ 0
  - reasonstring
    
    Required
    Why the visit was opened, as the visitor wrote it.
  - started_atstring · date-time
    When the visitor opened the business. Absent if they never did.
  - statestring · enum
    
    Required
    opening has been granted and not yet opened; never_opened ran out unopened; open is in the business now; ran_out lasted until its hour was up; ended was ended early.
    openingnever_openedopenran_outended
  - visitor_namestring
    
    Required
    The support team member who visited, as the operator names them.
- next_cursorstring
  
  Nullable
  Opaque cursor for the next page, or null on the last page.
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/visits' \
  -H "Authorization: Bearer $TOKEN"

Response

{
  "has_more": false,
  "items": [
    {
      "id": "0192f1e4-7c3a-7b2e-9f10-5d6c7e8f9a0b",
      "created_at": "2026-09-11T09:30:00Z",
      "ended_at": "2026-09-11T09:30:00Z",
      "expires_at": "2026-09-11T09:30:00Z",
      "minutes": 0,
      "reason": "string",
      "started_at": "2026-09-11T09:30:00Z",
      "state": "opening",
      "visitor_name": "string"
    }
  ],
  "next_cursor": "string"
}