Two contracts and access scopes
Workspace routes live on the signed-in shop origin under /api/v1 and use an unlocked staff session or owner-issued, location-scoped shop API key. Inventory and shop projections exclude customer details, costs and payment data. The private Workbench journal requires current owner/manager audit_read access; cashiers cannot read it. Only owners manage shop keys and event destinations. Shop keys do not grant Workbench management.
Market routes live on the separate API origin under /v1 and use account credentials. Neither credential grants the other product’s access. Open /api/v1/openapi for the current Workspace contract. A hosted or synthetic response is not evidence of approved merchant transactions.
Start in Workbench
Open Developers at the bottom of the shop workspace. Overview contains Summary and Health, with actionable issues and recent requests first. Activity contains requests, errors, events and logs; Integrations contains webhooks and shop keys; Tools contains the read-only Inspector and Market data. Trends are collapsed initially, and each chart has an expandable table of exact bucket values. Integration steps and documentation links remain available on mobile.
Start by reading the Workspace contract and sending an Inspector GET. Inventory offers page sizes 5, 25, 50 and 100, an available-stock filter and links.next. Following a page preserves the submitted search/location/filter/page-size scope. The response labels its submitted path; edited inputs are marked unsent. Cancel or retry reads that exceed the 12-second client deadline. Pages are current reads rather than a frozen export. Inspector browser round-trip time differs from the journal’s server processing time. Request IDs correlate a response with best-effort persisted metadata; query values and response bodies are not logged.
Signed shop events
system.test is an owner-requested connection test. shop.profile.updated reports a committed profile revision and changed field names, without profile values. Add a public HTTPS receiver on port 443 without URL credentials, query parameters or fragments; redirects are not followed. Save its signing secret before leaving the view.
Verify CardCounterPOS-Signature over timestamp + dot + raw request body using HMAC-SHA256 and the endpoint secret. The header format is t=timestamp,v1=hex-signature. Compare signatures in constant time, reject timestamps outside your tolerance (for example five minutes), and deduplicate event IDs before processing. Return 2xx promptly. The legacy PokePOS-Signature and delivery-ID aliases remain compatible.
Delivery is at least once. Event creation, an attempt starting and receiver acceptance are distinct outcomes. Failed attempts retry with backoff up to five automatic attempts; an owner can retry terminal failures within the supported attempt limit. A timeout can occur after a receiver accepted the event, so deduplication remains necessary.
Uncertain actions and one-time secrets
Reuse the same command ID for retries of one attempted create/test/state-change/retry or endpoint edit/rotate/retire operation. A lost response or browser cancellation does not prove the server rolled back. Reconcile the persisted endpoint, key, event or delivery before intentionally starting a new command. Changing a command’s payload requires a new intent. Process due deliveries is a queue-processing pass rather than a journaled command: review the queue after an uncertain response before deliberately starting another pass; resending a command ID does not deduplicate passes.
Creation secrets are returned once; command replay never returns the original secret. Save the secret before leaving, acknowledge it explicitly and keep it in server secret storage. If a key creation response was lost, reconcile and revoke the issued key before creating a replacement. For a lost endpoint secret, reconcile the endpoint then intentionally rotate to a new secret. Do not create another endpoint merely to recover the original secret. A list response never reveals existing secrets.
Endpoint changes and retirement
Owners can edit an endpoint name, URL and supported topics, rotate its secret or retire it using the current endpoint revision. A stale revision or active delivery lease requires refreshing before a change. Rotation atomically pauses the endpoint: save the new secret, update your receiver, then resume delivery. There is no overlap period with the old secret, and it cannot be retrieved after rotation.
Retirement cancels pending or expired-leased work, excludes the endpoint from the nonretired endpoint limit and preserves event/attempt history. It is permanent for that endpoint; create a new destination for a new intent. An actively leased delivery prevents endpoint changes until its lease completes or expires.
History and worker truth
Request-history filters affect recorded activity; present webhook backlog and worker health are independent of that reporting period. Requests and Errors show 50-row cursor pages; their search matches the loaded page only. Events and Logs search up to 100 recent records without exhaustive history paging or share links. List times use the labelled browser timezone. Webhooks offer 25-row recent or all-time unresolved delivery pages. Delivery details fetch independent, all-time attempt history in 10-row pages rather than interpreting absence from a capped global list as no attempts. Attempt latency measures completed attempts by attempt time; no observations are distinct from zero milliseconds.
Activity, webhook and worker feeds refresh independently with 12-second client deadlines, individual retry controls and labelled last successful data only for the same query. Active visible feeds poll every 30 seconds. A configured minute schedule is a configuration fact. Inspect the last completed scheduled run to establish execution. Scheduled heartbeats become overdue after three minutes and unfinished runs become interrupted after 65 seconds. Manual checks have separate timestamps and cannot clear an overdue scheduled heartbeat. Disabled queues are explicit no-ops, not accepted provider connections. Worker alert delivery remains off; Health is not a platform-wide uptime monitor.
Market access in the shop
Entitled market lookups use database-bound server-side receipts and staff authorization. Receipts are internal capabilities, not reusable public API keys. A temporary upstream credential failure is translated into a workspace service error. Confirm printing, condition, finish, language, section status and observation time before using an observation as pricing context.