> ## Documentation Index
> Fetch the complete documentation index at: https://docs.pcnaid.com/llms.txt
> Use this file to discover all available pages before exploring further.

# POS True Retail Operations Suite API overview

> Authentication, rate limiting, the externally reachable endpoints, and response format for the POS True Retail Operations Worker API.

# 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

```bash theme={null}
curl --fail-with-body https://pos.shpfy.pndsvcs.com/healthz
```

## Authentication

```text theme={null}
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

```json theme={null}
{
  "success": true,
  "data": {}
}
```

```json theme={null}
{
  "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](https://docs.pcnaid.com/nodes/shopify/pos-true-retail-operations/developer/webhooks/index.md).

## 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](https://docs.pcnaid.com/namespace/index.md) › [Shopify Ecosystem](https://docs.pcnaid.com/hubs/shopify-ecosystem/index.md) › [POS True Retail Operations Suite](https://docs.pcnaid.com/nodes/shopify/pos-true-retail-operations/index.md) › [Developer](https://docs.pcnaid.com/nodes/shopify/pos-true-retail-operations/developer/index)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.