API referenceTenvelo API
https://api.tenvelo.com The contract, as OpenAPI

Contract 2026-10-10. Every path below carries its own major version.

POS · Reference

Printers

The printers a shop owns. Server-authoritative — devices pull printers, and a till resolves which one a document goes to from its role and location.

Operations
5
Base
https://api.tenvelo.com

  1. GET/v1/printers

    List printers

    No. listPrintersAuth pos:printers:read

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

    Devices should not call this to sync — use listChanges, which returns only what has changed. This is the dashboard's printer 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.

    • location_idquery · string · uuid

      Only printers at this location.

    Responses

    • 200

      A page of printers.

      PrinterPage · application/json
      • has_moreboolean

        Required

        Whether another page follows.

      • itemsarray of Printer

        Required

        • idstring · uuid

          Required

        • namestring

          Required

          1–255 chars

        • auto_printboolean

          Required

          Whether a completed sale prints automatically on this printer, or is merely offered.

        • command_setstring · enum

          The command set the printer speaks, so a till encodes the bytes it can render. escpos is the Epson dialect the till uses by default on every transport; star_line_mode is Star's own text command set, for a Star printer that does not emulate ESC/POS. A till reaches the printer the same way regardless and renders the same receipt, bill, kitchen ticket and drawer kick in the chosen bytes.

          escposstar_line_mode

          default escpos

        • connectionobject

          Required

          How the till reaches the printer.

          • typestring · enum

            Required

            The transport. network is a printer on the shop's LAN reached by TCP; bluetooth is one a till pairs with; usb is one plugged into the till.

            networkbluetoothusb

          • hoststring

            Required

            Where the printer is — an IP address or host name for a network printer, a Bluetooth address for one a till pairs with, or a device path for a USB printer.

            1–255 chars

          • portinteger

            The raw ESC/POS socket port; 9100 is the usual one. Used only for a network printer; a Bluetooth or USB printer leaves it 0.

            0–65535

        • created_atTimestamp

          RequiredRead only

          Server-assigned RFC 3339 timestamp, always UTC.

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

        • device_idstring · uuid

          Nullable

          The single device this printer is bound to. A receipt printer that belongs to one counter till is bound to it; a printer shared by a whole location is not. A device resolves its own receipt printer from this first, then the location's.

        • location_idstring · uuid

          Required

          The room or site the printer is installed in. A printer is only offered to devices at its own location.

        • merchant_idstring · uuid

          RequiredRead only

        • paper_width_mminteger · enum

          Required

          The paper roll width, in millimetres. It decides the column width a receipt is rendered at; 40 is the narrow roll a smart-pos terminal's built-in printer takes, 58 the receipt printers a counter till pairs with, 80 the standard roll kitchen and receipt printers take.

          405880

        • rolestring · enum

          Required

          What the printer is for. A receipt printer takes the document a customer is handed; a kitchen printer takes kitchen tickets; a drawer_kick printer only opens the cash drawer, on a cash tender and on a recorded no-sale. A device resolves which of the location's printers a particular document goes to from this role.

          receiptkitchendrawer_kick

        • station_idstring · uuid

          Nullable

          The station a kitchen printer is bound to, so a ticket for the grill prints at the grill: a ticket is routed to the printer bound to its station first, then to a station-less kitchen printer. A receipt or drawer printer is never station-bound.

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

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

  2. POST/v1/printers/batch-upsert

    Create or replace printers

    No. batchUpsertPrintersAuth pos:printers:write

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

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

    Request body application/json · PrinterBatchUpsertRequest

    • itemsarray of PrinterBatchUpsertItem

      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

      • printerPrinter

        Required

        A printer a shop owns, owned by a merchant and standing in one of its locations. Server-authoritative: a till pulls printers from the change feed and never invents one, because a printer a manager did not record is one a device at another branch cannot reach. A printer is withdrawn rather than deleted, and a receipt printer can be bound to a single device (device_id) so a counter till prints on its own printer and leaves the others alone.

        • idstring · uuid

          Required

        • namestring

          Required

          1–255 chars

        • auto_printboolean

          Required

          Whether a completed sale prints automatically on this printer, or is merely offered.

        • command_setstring · enum

          The command set the printer speaks, so a till encodes the bytes it can render. escpos is the Epson dialect the till uses by default on every transport; star_line_mode is Star's own text command set, for a Star printer that does not emulate ESC/POS. A till reaches the printer the same way regardless and renders the same receipt, bill, kitchen ticket and drawer kick in the chosen bytes.

          escposstar_line_mode

          default escpos

        • connectionobject

          Required

          How the till reaches the printer.

          • typestring · enum

            Required

            The transport. network is a printer on the shop's LAN reached by TCP; bluetooth is one a till pairs with; usb is one plugged into the till.

            networkbluetoothusb

          • hoststring

            Required

            Where the printer is — an IP address or host name for a network printer, a Bluetooth address for one a till pairs with, or a device path for a USB printer.

            1–255 chars

          • portinteger

            The raw ESC/POS socket port; 9100 is the usual one. Used only for a network printer; a Bluetooth or USB printer leaves it 0.

            0–65535

        • device_idstring · uuid

          Nullable

          The single device this printer is bound to. A receipt printer that belongs to one counter till is bound to it; a printer shared by a whole location is not. A device resolves its own receipt printer from this first, then the location's.

        • location_idstring · uuid

          Required

          The room or site the printer is installed in. A printer is only offered to devices at its own location.

        • paper_width_mminteger · enum

          Required

          The paper roll width, in millimetres. It decides the column width a receipt is rendered at; 40 is the narrow roll a smart-pos terminal's built-in printer takes, 58 the receipt printers a counter till pairs with, 80 the standard roll kitchen and receipt printers take.

          405880

        • rolestring · enum

          Required

          What the printer is for. A receipt printer takes the document a customer is handed; a kitchen printer takes kitchen tickets; a drawer_kick printer only opens the cash drawer, on a cash tender and on a recorded no-sale. A device resolves which of the location's printers a particular document goes to from this role.

          receiptkitchendrawer_kick

        • station_idstring · uuid

          Nullable

          The station a kitchen printer is bound to, so a ticket for the grill prints at the grill: a ticket is routed to the printer bound to its station first, then to a station-less kitchen printer. A receipt or drawer printer is never station-bound.

      • versioninteger · int64

        The version this write was made from. Required to replace one that exists, and refused as 412 when somebody else has written it since.

        ≥ 1

    Responses

    • 200

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

      BatchResponse · application/json
      • resultsarray of BatchResult

        Required

        • idstring · uuid

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

        • idempotency_keystring

          Required

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

        • problemProblem

          Nullable

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

          • typestring · uri

            Required

            A stable URI identifying the problem kind. This is the field to branch on.

            default about:blank

          • api_versionstring

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

          • detailstring

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

          • instancestring · uri-reference

            A URI reference identifying the specific occurrence.

          • invalid_paramsarray of InvalidParam

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

            • codestring

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

            • pointerstring

              Required

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

            • reasonstring

              Required

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

          • refusalsarray of Location refusal

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

            • kindstring

              Required

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

            • countinteger

              Required

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

              ≥ 1

          • statusinteger

            Required

            The HTTP status code, repeated here so the body is self-contained.

            100–599

          • titlestring

            Required

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

          • trace_idstring

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

        • statusstring · enum

          Required

          created — the item made a new resource. updated — it changed an existing one.

          unchanged — this key was already applied and the original outcome stands. A success, not an error: it is what a client retrying a batch it was unsure landed should expect, and it clears the item from its queue exactly as created does.

          failed — the item was refused, and nothing else in the batch was affected. See problem.

          createdupdatedunchangedfailed

        • versioninteger · int64

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

    • 400

      The request could not be parsed. Malformed JSON, a bad query parameter, or a header that failed to decode, among them an API-Version later than the server speaks or not a date (api-version-unknown, with the server's own in api_version).

      Distinct from 422: a 400 never reached validation, so invalid_params is absent. Retrying without changing the request will fail again, except that a request refused for its API-Version goes once the server is updated.

    • 401

      No credentials, or credentials that could not be verified — missing bearer token, malformed JWT, expired token, or a signature that failed against the issuer's JWKS.

      Refresh the token and retry once. Repeated 401 after a refresh means the device needs to re-enrol.

    • 403

      Authenticated, but not permitted. The token is valid and its merchant was resolved, but the caller's role does not allow this operation, or the target belongs to a different merchant.

      Cross-tenant access is reported as 403 on a resource the caller may not see, and as 404 where even confirming existence would leak information. Retrying will not help.

    • 410

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

    • 415

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

    • 422

      The request parsed but failed validation.

      invalid_params lists every failing field with a JSON Pointer, not just the first, so a client can mark up a whole form in one pass rather than making the user fix errors one round trip at a time.

      Also returned when an Idempotency-Key is replayed with a different body, and when device-computed order totals disagree with the server's recomputation.

    • 429

      Rate limit exceeded. Honour Retry-After rather than applying your own backoff.

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

    • 500

      Something failed on our side. trace_id identifies the request in our tracing — quote it in a support ticket.

      The body never carries internal detail: no SQL, no stack traces, no upstream error strings. Safe to retry with the same Idempotency-Key.

    • 503

      Temporarily unable to serve the request — a dependency is down or the service is shedding load.

      Retry with the same Idempotency-Key after Retry-After. This is always safe: a request that did take effect before the failure will be recognised as a replay.

  3. GET/v1/printers/{id}

    Get a printer

    No. getPrinterAuth pos:printers:read

    Returns a single printer.

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

      Printer · application/json
      • idstring · uuid

        Required

      • namestring

        Required

        1–255 chars

      • auto_printboolean

        Required

        Whether a completed sale prints automatically on this printer, or is merely offered.

      • command_setstring · enum

        The command set the printer speaks, so a till encodes the bytes it can render. escpos is the Epson dialect the till uses by default on every transport; star_line_mode is Star's own text command set, for a Star printer that does not emulate ESC/POS. A till reaches the printer the same way regardless and renders the same receipt, bill, kitchen ticket and drawer kick in the chosen bytes.

        escposstar_line_mode

        default escpos

      • connectionobject

        Required

        How the till reaches the printer.

        • typestring · enum

          Required

          The transport. network is a printer on the shop's LAN reached by TCP; bluetooth is one a till pairs with; usb is one plugged into the till.

          networkbluetoothusb

        • hoststring

          Required

          Where the printer is — an IP address or host name for a network printer, a Bluetooth address for one a till pairs with, or a device path for a USB printer.

          1–255 chars

        • portinteger

          The raw ESC/POS socket port; 9100 is the usual one. Used only for a network printer; a Bluetooth or USB printer leaves it 0.

          0–65535

      • created_atTimestamp

        RequiredRead only

        Server-assigned RFC 3339 timestamp, always UTC.

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

      • device_idstring · uuid

        Nullable

        The single device this printer is bound to. A receipt printer that belongs to one counter till is bound to it; a printer shared by a whole location is not. A device resolves its own receipt printer from this first, then the location's.

      • location_idstring · uuid

        Required

        The room or site the printer is installed in. A printer is only offered to devices at its own location.

      • merchant_idstring · uuid

        RequiredRead only

      • paper_width_mminteger · enum

        Required

        The paper roll width, in millimetres. It decides the column width a receipt is rendered at; 40 is the narrow roll a smart-pos terminal's built-in printer takes, 58 the receipt printers a counter till pairs with, 80 the standard roll kitchen and receipt printers take.

        405880

      • rolestring · enum

        Required

        What the printer is for. A receipt printer takes the document a customer is handed; a kitchen printer takes kitchen tickets; a drawer_kick printer only opens the cash drawer, on a cash tender and on a recorded no-sale. A device resolves which of the location's printers a particular document goes to from this role.

        receiptkitchendrawer_kick

      • station_idstring · uuid

        Nullable

        The station a kitchen printer is bound to, so a ticket for the grill prints at the grill: a ticket is routed to the printer bound to its station first, then to a station-less kitchen printer. A receipt or drawer printer is never station-bound.

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

  4. PATCH/v1/printers/{id}

    Change a printer

    No. updatePrinterAuth pos:printers:write

    Applies a JSON Merge Patch (RFC 7396) to a printer, guarded by If-Match.

    Send only the fields that change. The patch is refused with 412 if the printer has changed since the version you read: re-read, re-apply your change on top of the current state, and retry. A device-bound receipt printer can be un-bound by setting device_id to null.

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

    • namestring

      1–255 chars

    • auto_printboolean
    • command_setstring · enum

      Change which command set the printer speaks. escpos is the Epson dialect; star_line_mode is Star's own text command set, for a Star printer that does not emulate ESC/POS.

      escposstar_line_mode

    • connectionobject

      Replaces the whole connection.

      • typestring · enum

        Required

        networkbluetoothusb

      • hoststring

        Required

        1–255 chars

      • portinteger

        0–65535

    • device_idstring · uuid

      Nullable

      Bind the printer to a device, or set it to null to un-bind and let the location's devices share it. kitchen printers are never device-bound.

    • location_idstring · uuid

      Moving a printer to another location.

    • paper_width_mminteger · enum

      405880

    • rolestring · enum

      receiptkitchendrawer_kick

    • station_idstring · uuid

      Nullable

      Bind a kitchen printer to a station, or set it to null to take any kitchen ticket at its location. A receipt or drawer printer is never station-bound.

    Responses

    • 200

      The changed printer.

      Printer · application/json
      • idstring · uuid

        Required

      • namestring

        Required

        1–255 chars

      • auto_printboolean

        Required

        Whether a completed sale prints automatically on this printer, or is merely offered.

      • command_setstring · enum

        The command set the printer speaks, so a till encodes the bytes it can render. escpos is the Epson dialect the till uses by default on every transport; star_line_mode is Star's own text command set, for a Star printer that does not emulate ESC/POS. A till reaches the printer the same way regardless and renders the same receipt, bill, kitchen ticket and drawer kick in the chosen bytes.

        escposstar_line_mode

        default escpos

      • connectionobject

        Required

        How the till reaches the printer.

        • typestring · enum

          Required

          The transport. network is a printer on the shop's LAN reached by TCP; bluetooth is one a till pairs with; usb is one plugged into the till.

          networkbluetoothusb

        • hoststring

          Required

          Where the printer is — an IP address or host name for a network printer, a Bluetooth address for one a till pairs with, or a device path for a USB printer.

          1–255 chars

        • portinteger

          The raw ESC/POS socket port; 9100 is the usual one. Used only for a network printer; a Bluetooth or USB printer leaves it 0.

          0–65535

      • created_atTimestamp

        RequiredRead only

        Server-assigned RFC 3339 timestamp, always UTC.

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

      • device_idstring · uuid

        Nullable

        The single device this printer is bound to. A receipt printer that belongs to one counter till is bound to it; a printer shared by a whole location is not. A device resolves its own receipt printer from this first, then the location's.

      • location_idstring · uuid

        Required

        The room or site the printer is installed in. A printer is only offered to devices at its own location.

      • merchant_idstring · uuid

        RequiredRead only

      • paper_width_mminteger · enum

        Required

        The paper roll width, in millimetres. It decides the column width a receipt is rendered at; 40 is the narrow roll a smart-pos terminal's built-in printer takes, 58 the receipt printers a counter till pairs with, 80 the standard roll kitchen and receipt printers take.

        405880

      • rolestring · enum

        Required

        What the printer is for. A receipt printer takes the document a customer is handed; a kitchen printer takes kitchen tickets; a drawer_kick printer only opens the cash drawer, on a cash tender and on a recorded no-sale. A device resolves which of the location's printers a particular document goes to from this role.

        receiptkitchendrawer_kick

      • station_idstring · uuid

        Nullable

        The station a kitchen printer is bound to, so a ticket for the grill prints at the grill: a ticket is routed to the printer bound to its station first, then to a station-less kitchen printer. A receipt or drawer printer is never station-bound.

      • updated_atTimestamp

        RequiredRead only

        Server-assigned RFC 3339 timestamp, always UTC.

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

      • versionVersion

        RequiredRead only

        Optimistic concurrency version, raised by the server on every write. A version is never lower than one already returned for the resource, though it may rise by more than one.

        Returned in the ETag response header as well as in the body. Send it back in If-Match on an update and the write is rejected with 412 if anyone else has written since — which is what stops two tills silently overwriting each other's edit to the same product when both come back online at once.

        ≥ 1

    • 400

      The request could not be parsed. Malformed JSON, a bad query parameter, or a header that failed to decode, among them an API-Version later than the server speaks or not a date (api-version-unknown, with the server's own in api_version).

      Distinct from 422: a 400 never reached validation, so invalid_params is absent. Retrying without changing the request will fail again, except that a request refused for its API-Version goes once the server is updated.

    • 401

      No credentials, or credentials that could not be verified — missing bearer token, malformed JWT, expired token, or a signature that failed against the issuer's JWKS.

      Refresh the token and retry once. Repeated 401 after a refresh means the device needs to re-enrol.

    • 403

      Authenticated, but not permitted. The token is valid and its merchant was resolved, but the caller's role does not allow this operation, or the target belongs to a different merchant.

      Cross-tenant access is reported as 403 on a resource the caller may not see, and as 404 where even confirming existence would leak information. Retrying will not help.

    • 404

      No such resource, or none visible to this caller.

      Also returned instead of 403 where acknowledging existence would itself leak information — so a 404 does not prove the id is unused globally, only that it is not yours.

    • 409

      The request conflicts with current state — a uniqueness constraint, or an attempt to mutate an order that is already completed or voided.

      Unlike 412, re-reading and retrying unchanged will not resolve it; the request itself has to change.

    • 410

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

    • 412

      The If-Match version did not match the resource's current version: someone else wrote since you read.

      This is the expected, healthy outcome of two clients editing the same record — not an error condition to suppress. Re-read the resource, re-apply your change on top of the new state, and retry with the fresh ETag.

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

  5. DELETE/v1/printers/{id}

    Delete a printer

    No. deletePrinterAuth pos:printers:write

    Soft-deletes a printer and emits a deleted change so devices stop offering it.

    The row is retained rather than erased, because a sale may still be waiting to print on it and a device should not lose the printer it is talking to mid-shift.

    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 printer was deleted.

    • 400

      The request could not be parsed. Malformed JSON, a bad query parameter, or a header that failed to decode, among them an API-Version later than the server speaks or not a date (api-version-unknown, with the server's own in api_version).

      Distinct from 422: a 400 never reached validation, so invalid_params is absent. Retrying without changing the request will fail again, except that a request refused for its API-Version goes once the server is updated.

    • 401

      No credentials, or credentials that could not be verified — missing bearer token, malformed JWT, expired token, or a signature that failed against the issuer's JWKS.

      Refresh the token and retry once. Repeated 401 after a refresh means the device needs to re-enrol.

    • 403

      Authenticated, but not permitted. The token is valid and its merchant was resolved, but the caller's role does not allow this operation, or the target belongs to a different merchant.

      Cross-tenant access is reported as 403 on a resource the caller may not see, and as 404 where even confirming existence would leak information. Retrying will not help.

    • 404

      No such resource, or none visible to this caller.

      Also returned instead of 403 where acknowledging existence would itself leak information — so a 404 does not prove the id is unused globally, only that it is not yours.

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