POS True Retail Operations Suite API overview

All API endpoints are served by the Cloudflare Worker at the app’s base URL. Authenticated endpoints require a Shopify session token in the Authorization header.

Read-only request

curl --fail-with-body https://pos.shpfy.pndsvcs.com/healthz

Authentication

Authorization: Bearer <shopify-session-token>

The session token is a JWT signed with HMAC-SHA256 using the app secret. The Worker validates exp, nbf (with clock-skew tolerance), iss, the dest shop domain, and the signature. An ID token proves identity but not permission. Privileged routes exchange it for an expiring online access token and verify the staff member’s scopes. Shopify may omit a read_<resource> grant when the matching write_<resource> is present, so either satisfies that read requirement; a write requirement or an unprefixed scope still requires an exact match. Location settings and billing mutations are account-owner only. Requests never fall back to a shop-wide offline token.

Failure	Response
Missing, expired, or invalid token	`401` with `X-Shopify-Retry-Invalid-Session-Request: 1`
Authenticated but missing user permission	`403` with `USER_PERMISSION_REQUIRED`
Installation missing a required scope	`403` with `REAUTHORIZATION_REQUIRED`, `reauthUrl`, and `missingScopes`

Rate limiting

Mutation endpoints (POST, PUT, PATCH, DELETE) are limited to 50 requests per minute per shop using atomic D1 counters. The response is 429 Too Many Requests.

Response format

{
  "success": true,
  "data": {}
}

{
  "success": false,
  "error": "Human-readable error message"
}

Code	Meaning
`200`	Success
`204`	Success with no content (OPTIONS preflight)
`302`	Redirect (OAuth)
`400`	Validation error
`401`	Unauthorized
`402`	Billing required
`403`	Forbidden (permission, entitlement, or reauthorization)
`409`	Conflict (stale or reused idempotency state)
`429`	Rate limited
`502`	Shopify or configured upstream temporarily failed
`503`	Required external integration not configured
`500`	Internal server error

OAuth

Method	Endpoint	Description
`GET`	`/auth`	Initiate the Shopify OAuth 2.0 installation flow
`GET`	`/auth/callback`	Handle the OAuth callback and store the session

Health and setup

Method	Endpoint	Description
`GET`	`/healthz`	Public liveness check
`GET`	`/release.json`	Public deployed release metadata
`GET`	`/api/health`	Authenticated app health, recent activity, storefront identity, and subscription
`GET`	`/api/setup-status`	Owner-aware effective Home setup state
`POST`	`/api/setup-status/skip`	Owner defers setup for this install

Settings

Method	Endpoint	Description
`GET`	`/api/settings/locations`	List locations with feature flags
`GET`	`/api/settings/location/:locationId`	Single location settings
`PUT`	`/api/settings/locations`	Update location settings (owner only)

Audit

Method	Endpoint	Description
`GET`	`/api/audit`	Paginated audit events with filters
`GET`	`/api/audit/recent`	Recent audit events

Operations

Method	Endpoint	Description
`POST`	`/api/price-edits/log`	Log a price edit (idempotent)
`GET`	`/api/voids/eligible`	List voidable transactions for an order
`POST`	`/api/voids`	Void a transaction (idempotent)
`POST`	`/api/store-credit/issue`	Issue store credit (idempotent)

Billing and entitlements

Billing uses Shopify’s app-managed Billing API. Plans are Starter $8.99/$89.90, Professional $24.99/$249.90, and Enterprise $49.99/$499.90 for 30-day/annual billing; annual is ten 30-day charges, with one 14-day trial per eligible shop.

Method	Endpoint	Description
`GET`	`/api/billing/status`	Subscription status, reconciled with Shopify, plus the plan catalog
`POST`	`/api/billing/select`	Start app-managed plan selection
`POST`	`/api/billing/cancel`	Cancel and revoke current entitlements
`GET`	`/api/entitlements`	Current feature flags and plan-rank limit
`GET`	`/app/billing/confirmed`	Post-checkout embedded-app redirect

Premium routes call a server-side minimum-plan guard; an insufficient limit returns 402 (BILLING_REQUIRED) for retail-data routes or 403 (EntitlementError) for gap-feature routes.

Retail data

Method	Endpoint	Min plan	Description
`POST`	`/api/catalog/retail-definitions/ensure`	starter	Provision metafield and metaobject definitions
`PUT`	`/api/catalog/retail-attributes`	starter	Set product/variant retail metafields
`PUT`	`/api/metaobjects/location-config`	starter	Upsert location operating config
`PUT`	`/api/metaobjects/rule-set`	professional	Upsert retail rule-set metaobject

Operations tools

Method	Endpoint	Min plan	Description
`POST`	`/api/inventory-audit/log`	professional	Log a per-staff inventory audit event
`GET`	`/api/inventory-audit/export`	professional	Export inventory audit history
`GET`	`/api/inventory-audit/recent`	professional	Recent inventory audit activity
`POST`	`/api/sell-by-weight/calculate`	professional	Weighted-sale subtotal
`GET`	`/api/audit/export`	professional	Perpetual audit export
`GET`	`/api/fiscal/export/:provider`	enterprise	Fiscal export for `tse`, `rksv`, or `dsfinvk`

Inventory export returns JSON by default and CSV when format=csv. The operations audit export returns Professional JSON by default; its accounting-ready format=csv output requires Enterprise.

Retail workflows

Method	Endpoint	Min plan	Purpose
`GET`	`/api/retail/capabilities`	authenticated	Effective tier, enabled keys, counts, OIDC readiness, webhook SLA
`GET`	`/api/retail/records`	capability tier	Recent authorized records for one capability
`POST`	`/api/retail/workflows/:capability`	capability tier	Execute a validated action for one of the 16 retail capabilities
`GET`	`/api/retail/receipts/current`	professional	Active print-receipt configuration for an authorized POS location
`POST`	`/api/retail/sso/start`	enterprise + owner	Begin Enterprise OIDC authorization
`GET`	`/api/retail/webhooks`	enterprise + owner	List webhook subscriptions and delivery SLA
`POST`	`/api/retail/webhooks`	enterprise + owner	Create a signed webhook subscription
`POST`	`/api/retail/webhooks/:id/test`	enterprise + owner	Queue a test delivery
`DELETE`	`/api/retail/webhooks/:id`	enterprise + owner	Deactivate a subscription

POS callers bind the requested location to the signed user and tenant role; the generic workflow route applies the capability’s minimum plan before enforcing the caller context. Invalid input returns 400, a missing record returns 404, a stale transition returns 409, and a Shopify upstream failure returns 502.

Public capability routes

Method	Endpoint	Authentication	Purpose
`GET`	`/api/retail/display/:token`	24-hour HMAC capability token	Read the active second-screen cart projection
`GET`	`/api/retail/sso/callback`	One-time OIDC state + code	Complete OIDC code exchange and return to App Home

Enterprise OIDC identity verification returns 503 SSO_CONFIGURATION_REQUIRED until the OIDC issuer, client ID, and client secret are all configured.

Webhooks

Six webhook routes verify the HMAC signature before processing. See Webhooks.

Idempotency

Mutation endpoints (POST /api/voids, POST /api/store-credit/issue, POST /api/price-edits/log) accept an idempotencyKey. A duplicate request returns the cached response; keys are stored in D1 with seven-day retention and removed by the daily cron. Pcnaid Documentation › Shopify Ecosystem › POS True Retail Operations Suite › Developer

Start here

Documentation hubs

Legal

Shared legal

POS True Retail Operations Suite API overview

POS True Retail Operations Suite API overview

Read-only request

Authentication

Rate limiting

Response format

OAuth

Health and setup

Settings

Audit

Operations

Billing and entitlements

Retail data

Operations tools

Retail workflows

Public capability routes

Webhooks

Idempotency

​POS True Retail Operations Suite API overview

​Read-only request

​Authentication

​Rate limiting

​Response format

​OAuth

​Health and setup

​Settings

​Audit

​Operations

​Billing and entitlements

​Retail data

​Operations tools

​Retail workflows

​Public capability routes

​Webhooks

​Idempotency

POS True Retail Operations Suite API overview

Read-only request

Authentication

Rate limiting

Response format

OAuth

Health and setup

Settings

Audit

Operations

Billing and entitlements

Retail data

Operations tools

Retail workflows

Public capability routes

Webhooks

Idempotency