Jump to Content

Discover catalog filters and product counts

get

https://myapi.xegora.com/api/v1/products/filters

Returns public filter choices and the matching product count before pagination, scoped to the authenticated workspace and the same availability rules as product listing. All supplied filters apply to every facet (conjunctive counts). To discover alternatives to a selected facet, omit that facet's filter. Counts represent products, not variants. categories and publicCategories both list the public categories the matching products sit on, in display order, a product counted once per category (so counts can overlap). Blank or unavailable public metadata is omitted. productTypes, countryCodes and currencies each contain at most 200 entries, ordered by value; isTruncated=true means choices may be incomplete and the caller should narrow filters. There is no facet-pagination cursor. totalCount still counts all matching products. The total, each facet, and a subsequent list are separate live reads, not one transaction snapshot. Requires the products.read scope.

Recent Requests

Log in to see full request history

Time	Status	User Agent
Retrieving recent requests…

Loading…

Query Params

query

string

length ≤ 200

Free-text search. Control characters are rejected.

countryCode

string

length ≤ 16

Two-letter country code, trimmed and uppercased (for example US). An invalid normalized two-letter code returns an empty result. Inputs over 16 characters or containing control characters return 400.

category

string

length ≤ 100

The older name of publicCategory: it takes only the same public category keys, in any case. Anything else — a key that is not a public category, a product type such as gift-card (use productType), or popular (use sort=popular) — returns 400. If publicCategory is sent too, both must name the same category or the request is 400.

publicCategory

string

length ≤ 40

A public category key as returned by GET /api/v1/categories and in publicCategories (for example travel), trimmed and case-insensitive. Unknown keys return an empty result. Control characters are rejected.

productType

string

enum

length ≤ 30

Canonical product kind; trimmed and case-insensitive. Unsupported values and control characters return 400.

Allowed:

currency

string

length ≤ 16

Three ASCII letters, trimmed and uppercased (for example USD). Filters the product denomination currency, not settlement currency or checkout price. Required when either minimumValue or maximumValue is supplied. Malformed values and control characters return 400.

isFeatured

boolean

True selects featured products, false selects non-featured products; omit for both.

minimumValue

number

≤ 100000000000

Inclusive lower face-value bound, not a sell-price bound. Requires currency and must not exceed maximumValue. Matches available variant denominations, default denominations, or overlap with a published product range. A quote validates exact purchasability.

maximumValue

number

≤ 100000000000

Inclusive upper face-value bound, not a sell-price bound. Requires currency and must not be less than minimumValue. Range overlap does not guarantee a purchasable amount on every increment; create a quote for the intended value.

ids

string

Comma-separated product ids, 1–100 of them: read exactly these products — the way to refresh the selection you sell. Every other filter still applies; a product not listable now is simply absent. A malformed or empty id returns 400.

amountType

string

enum

fixed matches products that can be bought in a listed denomination (variants); custom matches products that can be bought for an amount of the caller's choosing (customAmount). A product offering both matches both.

Allowed:

Headers

X-Correlation-Id

string

length ≤ 128

^[A-Za-z0-9._:-]{1,128}$

Your own correlation id, carried through Xegora's logs and audit records and returned in correlationId. Kept when it is 1–128 characters of ASCII letters, digits, ., _, : and -; anything else is replaced by an id of Xegora's.

X-Language

string

enum

The language an error's message, title and detail are written in; without it, Accept-Language decides, then English. Successful responses are not translated.

accept

string

enum

Defaults to application/json

Generated from available response content types

Allowed:

Responses

Language

Credentials

Header

Loading…

Response

Click Try It! to start a request and see the response here! Or choose an example:

application/json

application/problem+json