DZBuild POS

DZBuild POS is the free Windows till for shops that also sell online. It keeps working offline and, once linked, stays in sync with one or more DZBuild stores. This page lists the calls a linked till makes, so support staff and partners can see what a till can and cannot do.

These endpoints answer only tokens issued to the till. A personal API key or an app token gets 403 on the POS-only paths, and a till token gets 403 on every path outside its list.

Who it is for

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

How a till links

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

The 19 scopes

The till always asks for all 19, and DZBuild always grants all 19.

Scopes	What the till can do
openid, profile, offline_access	Know who linked it and stay linked
store:read	Read the stores of the link, their language, plan and product cap
products:read, products:write	Read products, create and update them in batches, add photos
inventory:read, inventory:write	Read and adjust product stock
orders:read, orders:write	Receive the store's orders, claim one, move it, cancel it
customers:read	Check one phone number before a sale
pos:sales:read, pos:sales:write	Record sales, refunds and Z closures
locations:read, locations:write	Register the shop the till sits in
backups:read, backups:write	Reserved: backups are not offered
devices:self	Register the till, send heartbeats, unlink
events:read	Read the change feed

Endpoints

Method and path	What it does
GET /v1/me	The owner and the stores of the link
GET /v1/store	The chosen store: name, language, currency DZD, stock timing, plan and product cap
POST /v1/devices, GET /v1/devices	Register the till (one row per till and store), list the tills
POST /v1/devices/{id}/heartbeat	Every 15 minutes: version, pending and failed uploads
DELETE /v1/devices/{id}	Unlink this till
GET /v1/locations, POST /v1/locations	The shop the till sits in
POST /v1/products/batch	Create or update up to 100 products
GET /v1/products, GET /v1/products/{id}	Products changed since a date, one product
POST /v1/media/uploads, POST /v1/products/{id}/images	Photo ticket, then attach the uploaded photo
POST /v1/inventory/adjustments/batch	Up to 500 stock sets or changes
POST /v1/pos/sales, POST /v1/pos/sales/{sale_id}/refunds, POST /v1/pos/closures	Sales, refunds, Z closures
GET /v1/orders, GET /v1/orders/{id}	The store's orders in the till's shape
POST /v1/orders/{id}/claim, PATCH /v1/orders/{id}, POST /v1/orders/{id}/cancel	Take an order, move it, cancel it
GET /v1/customers?phone=	Flags for one phone number
GET /v1/events	The change feed

Some paths are shared with API keys (products, orders, customers). A till gets the shapes on this page; an API key keeps the shapes in Resources.

Products batch

POST /v1/products/batch takes items, up to 100. Each item has the till's own external_id, name, an optional sku and barcode, pricing.price as a string with two decimals ("4500.00"), inventory.track_stock, status (active, draft or archived) and an optional category with its own external_id and name.

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

Photos

1. POST /v1/media/uploads with filename, content_type (image/jpeg, image/png or image/webp), size (up to 8 MiB) and sha256. The answer carries media_id and a signed upload_url that works for 10 minutes.
2. The till sends the raw bytes with PUT to upload_url, without the DZBuild headers.
3. POST /v1/products/{id}/images with media_id and position attaches the photo. The size and the sha256 must match the ticket, or the call answers 422 media_mismatch. An unknown or expired ticket answers 404 media_not_found. A product holds up to 20 photos.

Stock

POST /v1/inventory/adjustments/batch takes up to 500 items. Each item names product_external_id, target: "product", either set (whole pieces) or delta, a reason (pos_sale, pos_return, restock, count or loss) and a unique ref.

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

POS documents

POST /v1/pos/sales records a ticket, an invoice or a delivery note; POST /v1/pos/sales/{sale_id}/refunds a return note or a credit note against that sale; POST /v1/pos/closures a Z closure with its totals and hash anchors.

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

Orders

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

Customers

GET /v1/customers?phone=0550123456 answers a page with at most one item: id, is_banned and fraud_score. It looks only at the store's own customers, accepts the phone with or without +213, and gives no name, address or history. An unknown number gives an empty page.

Events

GET /v1/events?wait=25&limit=200&cursor=... returns items, next_cursor and has_more. next_cursor is always present, also on an empty page; the till sends it back on the next call.

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

Backups

DZBuild does not store till backups. GET /v1/backups, POST /v1/backups, POST /v1/backups/{id}/complete and GET /v1/backups/{id}/download always answer 501 not_implemented, and the till keeps its backups on the PC.

Error codes

Status	code	When
400	bad_request	A wrong updated_since or a cursor this API did not issue
401	unauthorized	Token missing, wrong or expired, or the link was ended
402	product_limit_reached	A batch would create a product past the plan's cap
403	forbidden	A path outside the till's list, or a store the owner did not pick
404	not_found	Product, sale or order not on this store
404	device_not_found	A till id that is not this till on this store
404	media_not_found	Photo ticket unknown or expired
409	already_exists	A document with this external_id is recorded; its id is in details.id
409	order_claimed	Another till claimed the order
409	claim_required	Moving an order this till has not claimed
409	transition_not_allowed	The move is not allowed from the order's status
410	device_revoked	The till was disconnected
413	payload_too_large	Body larger than 1 MiB
422	validation_error	A field is wrong; details.field names it
422	media_mismatch	The uploaded photo does not match its ticket
422	idempotency_key_reuse	Same Idempotency-Key with a different body
429	rate_limited	Over a limit; wait for Retry-After
501	not_implemented	The backup paths
503	storage_unavailable	Photo storage is not reachable; retry later