Skip to content
DEV preview — API version 1.0.0 — not the public production site — Development API: dev-api.theprioryshop.co.uk
EPOS Developer API

List catalog categories

GET
/v1/catalog/categories

Filterable list of external-safe product categories for the authenticated tenant and allowed stores. Not paginated. Required scope: catalog.categories.read.

Authorizations

Section titled “Authorizations ”

Parameters

Section titled “ Parameters ”

Header Parameters

Section titled “Header Parameters ”
X-Request-Id
string

Optional client-supplied request ID (^[A-Za-z0-9_.:-]{1,80}$). Echoed back on the X-Request-Id response header and inside any error body’s requestId field. If omitted or invalid, the server generates one (req_...).

Query Parameters

Section titled “Query Parameters ”
storeId
string
Example
clx1store0000001

Restrict to one store. Must be a store this IntegrationClient is allowed to access; otherwise 404.

parentCategoryId
string
Example
clx1category000001
activeOnly
boolean
default: true

When true (default), only active categories are returned. Archived categories are always excluded.

sortBy
string
Allowed values: name sortOrder
Example
sortOrder

Sort order. Defaults to sortOrder, then name.

Responses

Section titled “ Responses ”

200

Section titled “200 ”
Array<object>
object
id
required
string
Example
clx1category000001
storeId
required
string
Example
clx1store0000001
parentCategoryId
required
object
name
required
string
Example
Bakery
code
required
object
Example
BAKE
description
required
object
sortOrder
required
number
Example
1
isActive
required
boolean
updatedAt
required
string format: date-time
Example
2026-08-27T17:51:41.976Z

400

Section titled “400 ”

Validation_failed - the request query/params failed validation.

object
error
required
object
code
required

Stable machine-readable error code. See the Error codes table in the API reference.

string
Allowed values: validation_failed unauthorized scope_denied not_found payload_too_large rate_limited internal_error
Example
validation_failed
message
required

Human-readable message. Safe to show to a developer, not localized, not guaranteed to be stable text - match on code, not this string.

string
Example
Request validation failed.
details
required

Additional machine-readable detail, shape depends on code (e.g. validation errors, required scopes). Empty object when there is nothing more to add.

object
key
additional properties
any
Example
{}
requestId
required

Request ID for this response - same value as the X-Request-Id response header. Include this when reporting a problem.

string
Example
req_AbCdEfGh12345678

401

Section titled “401 ”

Unauthorized - missing, malformed, expired or revoked API key, or the owning IntegrationClient is disabled/revoked.

object
error
required
object
code
required

Stable machine-readable error code. See the Error codes table in the API reference.

string
Allowed values: validation_failed unauthorized scope_denied not_found payload_too_large rate_limited internal_error
Example
validation_failed
message
required

Human-readable message. Safe to show to a developer, not localized, not guaranteed to be stable text - match on code, not this string.

string
Example
Request validation failed.
details
required

Additional machine-readable detail, shape depends on code (e.g. validation errors, required scopes). Empty object when there is nothing more to add.

object
key
additional properties
any
Example
{}
requestId
required

Request ID for this response - same value as the X-Request-Id response header. Include this when reporting a problem.

string
Example
req_AbCdEfGh12345678

403

Section titled “403 ”

Scope_denied - the API key is valid but the IntegrationClient does not hold the scope this route requires.

object
error
required
object
code
required

Stable machine-readable error code. See the Error codes table in the API reference.

string
Allowed values: validation_failed unauthorized scope_denied not_found payload_too_large rate_limited internal_error
Example
validation_failed
message
required

Human-readable message. Safe to show to a developer, not localized, not guaranteed to be stable text - match on code, not this string.

string
Example
Request validation failed.
details
required

Additional machine-readable detail, shape depends on code (e.g. validation errors, required scopes). Empty object when there is nothing more to add.

object
key
additional properties
any
Example
{}
requestId
required

Request ID for this response - same value as the X-Request-Id response header. Include this when reporting a problem.

string
Example
req_AbCdEfGh12345678

404

Section titled “404 ”

Not_found - the resource does not exist, or exists but is outside the IntegrationClient’s tenant/allowed stores. Both cases return the same generic 404 deliberately, to avoid confirming a resource exists to a caller not allowed to see it.

object
error
required
object
code
required

Stable machine-readable error code. See the Error codes table in the API reference.

string
Allowed values: validation_failed unauthorized scope_denied not_found payload_too_large rate_limited internal_error
Example
validation_failed
message
required

Human-readable message. Safe to show to a developer, not localized, not guaranteed to be stable text - match on code, not this string.

string
Example
Request validation failed.
details
required

Additional machine-readable detail, shape depends on code (e.g. validation errors, required scopes). Empty object when there is nothing more to add.

object
key
additional properties
any
Example
{}
requestId
required

Request ID for this response - same value as the X-Request-Id response header. Include this when reporting a problem.

string
Example
req_AbCdEfGh12345678

413

Section titled “413 ”

Payload_too_large - request exceeded the configured body size limit.

object
error
required
object
code
required

Stable machine-readable error code. See the Error codes table in the API reference.

string
Allowed values: validation_failed unauthorized scope_denied not_found payload_too_large rate_limited internal_error
Example
validation_failed
message
required

Human-readable message. Safe to show to a developer, not localized, not guaranteed to be stable text - match on code, not this string.

string
Example
Request validation failed.
details
required

Additional machine-readable detail, shape depends on code (e.g. validation errors, required scopes). Empty object when there is nothing more to add.

object
key
additional properties
any
Example
{}
requestId
required

Request ID for this response - same value as the X-Request-Id response header. Include this when reporting a problem.

string
Example
req_AbCdEfGh12345678

429

Section titled “429 ”

Rate_limited - too many requests. See the Retry-After response header. Current numeric limits are an operational policy, not a contractual guarantee, and may change - implement retry/backoff rather than hardcoding a specific limit.

object
error
required
object
code
required

Stable machine-readable error code. See the Error codes table in the API reference.

string
Allowed values: validation_failed unauthorized scope_denied not_found payload_too_large rate_limited internal_error
Example
validation_failed
message
required

Human-readable message. Safe to show to a developer, not localized, not guaranteed to be stable text - match on code, not this string.

string
Example
Request validation failed.
details
required

Additional machine-readable detail, shape depends on code (e.g. validation errors, required scopes). Empty object when there is nothing more to add.

object
key
additional properties
any
Example
{}
requestId
required

Request ID for this response - same value as the X-Request-Id response header. Include this when reporting a problem.

string
Example
req_AbCdEfGh12345678

Headers

Section titled “Headers ”
Retry-After
integer
Example
42

Seconds to wait before retrying.

500

Section titled “500 ”

Internal_error - unexpected server error. The response body is deliberately generic; use requestId when reporting the problem.

object
error
required
object
code
required

Stable machine-readable error code. See the Error codes table in the API reference.

string
Allowed values: validation_failed unauthorized scope_denied not_found payload_too_large rate_limited internal_error
Example
validation_failed
message
required

Human-readable message. Safe to show to a developer, not localized, not guaranteed to be stable text - match on code, not this string.

string
Example
Request validation failed.
details
required

Additional machine-readable detail, shape depends on code (e.g. validation errors, required scopes). Empty object when there is nothing more to add.

object
key
additional properties
any
Example
{}
requestId
required

Request ID for this response - same value as the X-Request-Id response header. Include this when reporting a problem.

string
Example
req_AbCdEfGh12345678