Quickstart

1. Receive an Integration API key

An EPOS owner/administrator creates an IntegrationClient for you in Back Office Developer Tools, grants it exactly the scopes your integration needs, and issues a credential. The full API key secret is shown once, at creation time. There is no way to retrieve it again later - see API Keys.

2. Store it securely

Treat the key like a password: environment variable or secret manager, never committed to source control, never sent to a browser/frontend. See Security.

3. Send it as a Bearer token

Every request to /v1/* requires the key in the Authorization header:

Authorization: Bearer epos_dev_sk_example_not_real

(That value is a fake example - see API Keys for the real format.)

4. Make your first request

curl "https://dev-api.theprioryshop.co.uk/v1/catalog/products?pageSize=5" \
  -H "Authorization: Bearer epos_dev_sk_example_not_real"

A successful response looks like:

{
  "rows": [
    {
      "id": "clx1product000001",
      "storeId": "clx1store0000001",
      "categoryId": "clx1category000001",
      "name": "Alpha Bread 800g",
      "sku": "SKU-ALPHA-BREAD",
      "barcode": "5000000000001",
      "brand": "Priory",
      "size": "800g",
      "unitType": "item",
      "sellingPriceGross": "1.25",
      "sellingPriceNet": "1.04",
      "taxCategory": "STANDARD",
      "vatRate": { "id": "clx1vatrate000001", "code": "STD", "name": "Standard Rate", "percentage": "20.00" },
      "isActive": true,
      "variablePrice": false,
      "ageRestricted": false,
      "alcoholRestricted": false,
      "tobaccoRestricted": false,
      "vapeRestricted": false,
      "updatedAt": "2026-08-27T17:51:41.976Z"
    }
  ],
  "page": 1,
  "pageSize": 5,
  "total": 479,
  "totalPages": 96
}

See First API Request for a walkthrough of what each field means, and the API Reference for the exact, generated schema.

5. Handle the common error cases

Status	error.code	What it means
401	unauthorized	Missing, malformed, expired or revoked key, or the client is disabled.
403	scope_denied	Valid key, but missing the scope this route needs.
404	not_found	Doesn’t exist, or exists outside your tenant/allowed stores.
429	rate_limited	Too many requests - check Retry-After and back off.

See Errors for the full contract and Rate Limits for retry guidance.

6. Use the request ID when reporting a problem

Every response - success or error - carries an X-Request-Id header, and every error body includes the same value as error.requestId. Include it when asking for help. See Request IDs.

Next steps

• Environments - DEV vs Production, and what “not publicly launched” means for Production today.
• Scopes - request exactly the access your integration needs.
• Integrations - patterns for keeping your own data in sync.