POS True Retail Operations Suite architecture
Runtime components
The Worker also exposes public release-identity endpoints (
/healthz, /release.json) and permanent redirects from the old /privacy and /terms app-host paths to the shared documentation site.
Request flow
Every authenticated API request follows the same middleware pipeline:dest claim; a query-string shop is never trusted. Mutation endpoints are rate-limited per shop at 50 requests per minute using atomic D1 counters. Privileged routes exchange the session token for an expiring online access token and enforce the acting staff member’s scopes; account-wide settings and billing mutations are account-owner only. Anonymous or invalid identity returns 401; an authenticated user without permission returns 403.
Mutating operations accept an idempotency key. The key and its response are stored in D1, and a duplicate request returns the cached response; keys expire after seven days.
Data storage
D1 holds the application’s tenant-scoped tables, includingaudit_events, idempotency_keys, sessions, location_configs, rate_limit_counters, the billing tables (shop_subscriptions, shop_entitlements, shop_trial_history), the inventory-audit table, and the retail-workflow tables (retail_workflow_records, retail_feature_settings, retail_webhook_subscriptions, retail_webhook_deliveries). Every tenant table uses shop as the leading primary-key column, preserving cross-shop isolation.
Workers KV is limited to OAuth/dev state and legacy location-read fallbacks. Canonical location configuration lives in D1.
Shopify metafields (via the $app namespace) hold catalog attributes on products and variants, while metaobjects hold stable retail policies.
POS extensions
Four production POS UI extensions use the current POS UI extension runtime (Preact TSX modules, POS web components,shopify.extension.toml with type = "ui_extension", api_version = "2026-10"):
Each extension calls the location settings or retail capabilities endpoint and fails closed when it cannot verify access. Backend authorization is repeated before every operation.
A fifth package, the receipt-footer renderer, is built and typechecked but excluded from the production app configuration because Shopify classifies
pos.receipt-footer.block.render as developer preview. It is not part of a production Shopify app version.
Webhooks
The app declares six Shopify webhook subscriptions inshopify.app.toml: app/uninstalled, app_subscriptions/update, shop/update, and the three mandatory GDPR compliance topics customers/data_request, customers/redact, and shop/redact. Every route verifies the HMAC-SHA256 signature over the raw body before processing and claims the delivery ID in D1 to suppress duplicates. See Webhooks for topics and handling.