Shop owners who sell in a physical shop and on their DZBuild store. Only the store owner can link a till; team members cannot.

Every plan. A till is not an API key, so it needs no Enterprise plan and takes no key slot.

Once the first till registers, the DZBuild POS extension appears in the dashboard with the linked tills, a disconnect button and the latest sales, refunds and Z closures. https://dzbuild.com/dashboard/connected-devices opens that page.

Discovery: GET https://dzbuild.com/.well-known/oauth-authorization-server (RFC 8414).

The till is a public OAuth 2.0 client, dzbuild-pos-windows, with no secret. Only PKCE S256 is accepted, and the redirect is http://127.0.0.1:PORT/oauth/callback on any port.

The owner signs in in the system browser and picks the stores the till may use, up to 10. A till can also link with a code: it shows one, and the owner types it at https://dzbuild.com/device from a phone.

The access token starts with dzpos_ and lasts 15 minutes. The refresh token is replaced on every use and ends after 30 days without use or 180 days in all. Sending an old refresh token again ends the link.

Every call carries X-DZ-Store with the store id, except GET /v1/me. A store the owner did not pick answers 403.

Every POST, PATCH and DELETE carries an Idempotency-Key, with the rules in Idempotency.

Limits: 120 requests a minute per till and 600 per store. The monthly API quota does not apply to tills.

Disconnecting the till in the dashboard ends the link: the next refresh answers 400 invalid_grant and the next heartbeat 410 device_revoked.

An item updates the product already linked to its external_id. Failing that, it adopts a product without variants that has the same sku and no link yet. Failing that, it creates a product with 0 in stock.

A category is found by its external_id, or created from its name.

The answer lists every item: external_id, id, status (created or updated) and error: null. A refused item has an error object and no id or status.

Plan cap: when the store already has as many active products as its plan allows, a batch that would create a product, draft or not, answers 402 product_limit_reached. Items before that one stay written. Switching an existing product to active past the cap is an error on that item only.

The batch never sets stock. Stock goes through the adjustments call.

Only products that track stock at the product level can be adjusted. A product with stock per variant answers the item error variant_product, one that does not track stock not_tracked, a product that no longer exists unknown_product.

The answer lists every item by ref with status ok or error.

Till stock changes never appear in the dashboard's change history and never offer an undo.

Documents are kept as sent and never change: there is no update or delete path.

A sale answers 201 with {"id": 99120, "stock_applied": false}. Stock moves through the adjustments call, never through a document.

POS documents live apart from orders. They do not count toward the store's monthly order limit, do not notify anyone, and never reach Google Sheets or webhooks.

Money is a string with two decimals, quantities a number with up to 3 decimals, up to 500 lines and 20 payments per document.

Sending a document whose external_id is already recorded answers 409 already_exists with the recorded id in error.details.id. The till reads that as success.

A refund for a sale of another store answers 404 not_found.

GET /v1/orders?updated_since=... and GET /v1/orders/{id} give the store's orders in the till's shape, with their items. order_number is the store's short number when it has one.

POST /v1/orders/{id}/claim with device_id and terminal: the first till wins. The same till claiming again gets 200; another till gets 409 order_claimed.

PATCH /v1/orders/{id} with status needs the claim (409 claim_required otherwise). Allowed moves: from pending or confirmed to processing, shipped or delivered, from processing to shipped or delivered, and from shipped to delivered. Any other move answers 409 transition_not_allowed.

POST /v1/orders/{id}/cancel takes reason (out_of_stock, customer_unreachable, duplicate or other) and an optional note up to 500 characters. Stock comes back under the store's own stock rules. If another till holds the claim, cancel answers 409 order_claimed.

A status change from the till runs the same follow-up as one made in the dashboard, notifications and the Google Sheets update included.

The edge holds the call up to 25 seconds and answers as soon as something changed.

The first call, without a cursor, starts with order.updated for every pending, confirmed and processing order.

Types: order.created, order.updated, product.updated, product.deleted, inventory.level_changed, customer.updated and device.revoked. Every event has a stable id, so the till can ignore repeats.

inventory.level_changed carries old, new, delta and a source: order when an order moved the stock (with the order number), dashboard for any other change made outside the till, and pos when another till of the same store changed it (the till ignores that source).

The till's own product and stock writes are not sent back to it.

device.revoked carries device_id as a string, once, after the till is disconnected.

A cursor this API did not issue answers 400 bad_request.