🚧

Beta — subject to change. This endpoint is publicly available, but its request/response shape may evolve before General Availability as we incorporate early feedback.

Searches variants using a structured filter body with nested logical operators (and, or) and per-field comparators. Use this when the flat query parameters on GET /variants aren’t expressive enough.

Only the fields listed in the request schema may appear in filter and order; unknown fields return 422. Custom field values are addressable via custom_fields.<uuid> nested paths, whichever representation the account returns them in — <uuid> is always the custom field definition id. The values on each returned variant follow the account’s representation, so the X-Custom-Fields-Format header applies here as well.

The response differs from GET /variants: the item reference is a single item_id with an item_type discriminator (rather than separate product_id/material_id), and the optional enriched item is returned under item. Use the include array to opt into item enrichment and to widen the result set to archived and/or deleted variants (both are excluded by default).