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 promotions

GET
/v1/catalog/promotions

Filterable list of customer-facing, external-safe promotions for the authenticated tenant and allowed stores. Not paginated. Coupon, staff-discount and manual-discount promotion types, POS-only system-generated presets, and DRAFT/ARCHIVED promotions are never returned by this endpoint, regardless of filters. Required scope: catalog.promotions.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.

activeAt
string format: date-time
Example
2026-08-27T18:00:00.000Z

Return promotions active at this instant (status ACTIVE and inside [startsAt, endsAt]). Forces the same status+window restriction as activeOnly=true regardless of the activeOnly value passed alongside it.

type
string
Example
MEAL_DEAL

Exact match on promotion type. A type outside the customer-facing allow-list simply returns an empty array.

activeOnly
boolean
default: true

When true (default), only ACTIVE promotions currently inside their active window are returned. When false, PAUSED promotions are also included (still never DRAFT/ARCHIVED).

Responses

Section titled “ Responses ”

200

Section titled “200 ”
Array<object>
object
id
required
string
Example
clx1promo00000001
storeId
required
string
Example
clx1store0000001
name
required
string
Example
Meal Deal: Main + Snack + Drink = £3.50
description
required
object
type
required

Customer-facing promotion type. Coupon, staff-discount and manual-discount promotion types are never returned by this API - see the API reference’s Promotions section.

string
Allowed values: MEAL_DEAL MULTIBUY_SAME_PRODUCT ANY_N_FIXED_PRICE MIX_MATCH_FIXED_PRICE MULTIBUY_FIXED_PRICE PRICE_CUT_FIXED_PRICE PRICE_CUT_PERCENT PRICE_CUT_FIXED TIMED_REDUCTION_PERCENT TIMED_REDUCTION_FIXED LOYALTY_PRICE
Example
MEAL_DEAL
startsAt
required
object
endsAt
required
object
isActive
required

True when status is ACTIVE and the current time is inside [startsAt, endsAt]. Computed independently of the activeOnly/activeAt query filters.

boolean
eligibilitySummary
required

Plain-language description of who/what qualifies. Never the raw internal conditions JSON.

string
Example
Buy one qualifying item from each of the Main, Snack and Drink groups
offerSummary
required

Plain-language description of the discount. Never the raw internal actions JSON.

string
Example
Fixed price £3.50
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