Skip to content

List variants for pickers

GET
/stores/{storeRef}/products/variants/list
curl --request GET \
--url 'https://apibase.ecomweb.app/api/v1/stores/example/products/variants/list?store_id=1&ids=1&ids=2&ids=3&limit=20&offset=0&search=cotton%20shirt&keyword=cotton%20shirt&status=draft&inventory_status=in_stock&collection_id=12&sort_by=id&sort_order=asc&include_counts=true&include_variants=false&include_combinations=false&include_promotion=false&min_price=10&max_price=100&external_id_pattern=tiktok_%25&filters=%5B%7B%22field%22%3A%22status%22%2C%22operator%22%3A%22is_not%22%2C%22values%22%3A%5B%22draft%22%5D%7D%5D' \
--header 'x-api-key: <x-api-key>'

Returns a compact array of variants across products, each with its product name, a readable option label, price, promotion price and the full variant. It takes the same filters as the product list and returns the first 100 products’ variants when no limit is given. The filters parameter is a JSON array of clauses, each {"field", "operator", "values"}, with at most 10 clauses and 50 values per clause. Fields: status (is, is_not; draft, active or unlisted), category and product_type (is, is_not), tag and collection (is, is_not; numeric IDs), sales_channel (is; numeric IDs), inventory_status (is; in_stock, low_stock or out_of_stock) and price (gte, lte; an amount). sort_by accepts id, name, status, created_at, updated_at, min_price and max_price.

Required scopes: read:products

storeRef
required
string

The store’s ref, as returned by GET /stores.

store_id
number
>= 1

Example

1

Filter by store ID (required for store-specific queries)

ids
Array<number>

Example

[
1,
2,
3
]

Filter by multiple product IDs

limit
number
default: 20 >= 1 <= 10000

Example

20

Number of items per page

offset
number
0

Example

0

Number of items to skip

search
string

Example

cotton shirt

Free-text search over product name or description

keyword
deprecated
string

Example

cotton shirt

Deprecated alias for search, kept so existing callers keep working. search wins when both are sent. New callers should send search.

status
string
Allowed values: draft active unlisted

Example

active

Filter by product status

inventory_status
string
Allowed values: in_stock low_stock out_of_stock

Example

low_stock

Filter by inventory status (in_stock, low_stock, out_of_stock)

collection_id
number
>= 1

Example

12

Only products in this manual collection. A smart collection is refused (400): its products are chosen by its rules.

sort_by
string
default: created_at
Allowed values: id name status created_at updated_at min_price max_price

Example

created_at

Sort field. Any other value is rejected with a 400 error.

sort_order
string
default: desc
Allowed values: asc desc

Example

desc

Sort order

include_counts
boolean
default: true

Example

true

Include related counts (variants, inventory)

include_variants
boolean

Example

false

Include product variants in the response

include_combinations
boolean

Example

false

Include variant combinations (options and values) in the response

include_promotion
boolean

Example

false

Include promotion information in the response

min_price
number

Example

10

Filter by minimum price

max_price
number

Example

100

Filter by maximum price

external_id_pattern
string

Example

tiktok_%

Filter by external ID pattern (for bulk imports)

filters
string

Example

[{"field":"status","operator":"is_not","values":["draft"]}]

A JSON array of filter clauses, each {field, operator, values}. At most 10 clauses, at most 50 values each. Fields: status (is, is_not; draft, active, unlisted), category and product_type (is, is_not), tag and collection (is, is_not; numeric IDs), sales_channel (is; numeric IDs), inventory_status (is; in_stock, low_stock, out_of_stock) and price (gte, lte; an amount).

Media typeapplication/json
Array<object>
object
variant
required

The full variant, with combinations and promotion price.

object
inventory_policy
required

deny rejects checkout when stock is short; continue lets stock go negative.

string
Allowed values: deny continue
dimensions
required

Package dimensions, or null.

object
key
additional properties
any
images
required

Images for this variant.

Array<object>
object
id

Asset ID of the image. Omit it to have the asset looked up from url, which must then be a URL of an asset uploaded to this store.

string
url
required

Image URL: the asset’s public_url or cdn_url

string
design_id

Canva design ID

string
design_edit_url

Canva design edit URL

string
canva_asset_id

Canva asset ID

string
alt

Image alt text

string
caption

Image caption

string
sort_order

Sort order for image display

number
is_primary

Whether this is the primary image

boolean
combinations

Attribute values that define this variant. Present only when combinations are requested.

Array<object>
object
attributes
required

The attribute (axis), or null when it no longer exists.

object
id
required

Attribute ID.

number
name
required

Attribute name, such as “Color”.

string
slug
required

URL-safe identifier of the attribute, unique within the store.

string
type
required

How values are chosen, such as select.

string
order_by
required

How the values are ordered, such as manual.

string
sort_order
required

Position of the attribute among the store’s attributes.

number
nullable
created_at
required

When the attribute was created, as an ISO 8601 timestamp.

string
updated_at
required

When the attribute was last updated, as an ISO 8601 timestamp.

string
taxonomy_attribute_code
required

Code of the global taxonomy attribute this one maps to, or null for a local attribute.

string
nullable
attribute_values
required

The chosen value, or null when it no longer exists.

object
id
required

Attribute value ID.

number
attribute_id
required

ID of the attribute this value belongs to.

number
value
required

Stored value, such as “red”.

string
display_value
required

Value as shown to shoppers, such as “Red”.

string
swatch_type
required

Swatch kind: none, color or image.

string
swatch_value
required

Swatch content: a color code or an image URL. Empty when there is no swatch.

string
sort_order
required

Position of the value within its attribute.

number
nullable
created_at
required

When the value was created, as an ISO 8601 timestamp.

string
updated_at
required

When the value was last updated, as an ISO 8601 timestamp.

string
taxonomy_value_code
required

Code of the global taxonomy value this one maps to, or null.

string
nullable
promotions

Active promotions on this variant. Present only when promotions are requested on a single product.

Array<object>
object
id
required

Promotion ID.

number
name
required

Promotion name.

string
description

Promotion description.

string
mode
required

How the promotion is applied, such as automatic or code.

string
code

Discount code, for code promotions.

string
type
required

Promotion type.

string
condition_type
required

What the promotion targets, such as product or variant.

string
discount_method

How the discount is computed, such as PERCENTAGE or FIXED_AMOUNT.

string
discount_value

Discount amount or percentage.

number
max_discount_amount

Upper bound on the discount amount.

number
fixed_price

Fixed price the item is sold at, for fixed-price promotions.

number
min_amount

Minimum order amount for the promotion to apply.

number
min_quantity

Minimum quantity for the promotion to apply.

number
start_at
required

When the promotion starts, as an ISO 8601 timestamp.

string
end_at

When the promotion ends, as an ISO 8601 timestamp.

string
promotion_price
required

Price after the promotion.

number
original_price
required

Price before the promotion.

number
discount_amount
required

Amount taken off the original price.

number
best_promotion

The promotion giving the lowest price, or null. Present only when promotions are requested on a single product.

object
id
required

Promotion ID.

number
name
required

Promotion name.

string
description

Promotion description.

string
mode
required

How the promotion is applied, such as automatic or code.

string
code

Discount code, for code promotions.

string
type
required

Promotion type.

string
condition_type
required

What the promotion targets, such as product or variant.

string
discount_method

How the discount is computed, such as PERCENTAGE or FIXED_AMOUNT.

string
discount_value

Discount amount or percentage.

number
max_discount_amount

Upper bound on the discount amount.

number
fixed_price

Fixed price the item is sold at, for fixed-price promotions.

number
min_amount

Minimum order amount for the promotion to apply.

number
min_quantity

Minimum quantity for the promotion to apply.

number
start_at
required

When the promotion starts, as an ISO 8601 timestamp.

string
end_at

When the promotion ends, as an ISO 8601 timestamp.

string
promotion_price
required

Price after the promotion.

number
original_price
required

Price before the promotion.

number
discount_amount
required

Amount taken off the original price.

number
id
required

Variant ID.

number
product_id
required

ID of the product this variant belongs to.

number
sku_id
required

Store-wide numeric SKU identifier, assigned automatically.

number
seller_sku
required

Merchant-assigned SKU, or null.

string
nullable
external_id
required

The variant’s ID in an external system, or null.

string
nullable
price
required

Selling price in the store’s currency.

number
inventory
required

Units available across all locations.

number
nullable
inventory_version
required

Counter that increases on every stock change.

number
min_stock_alert
required

Stock level at or below which the variant counts as low stock.

number
nullable
track_inventory
required

Whether stock is tracked. When false the variant never runs out.

boolean
cost_per_item

Unit cost to the store. Present only when the key holds the read:inventory scope. Null when no cost is recorded.

number
nullable
weight
required

Weight, in the store’s weight unit, or null.

number
nullable
is_default
required

Whether this is the product’s default variant.

boolean
nullable
status
required

Variant status, such as active or inactive.

string
nullable
created_at
required

When the variant was created, as an ISO 8601 timestamp.

string
updated_at
required

When the variant was last updated, as an ISO 8601 timestamp.

string
promotion_price

Price after the best active promotion. Present only when promotions are requested; null when none applies.

number
nullable
id
required

Variant ID.

number
product_name
required

Name of the product the variant belongs to.

string
variant_display
required

Readable label of the variant’s options, such as “Color: Red, Size: M”, or “Default”.

string
price
required

Variant price.

number
promotion_price
required

Price after promotion, or null.

number
nullable
image_url
required

URL of the product’s first image, or null.

string
nullable

Example

[
{
"variant": {
"inventory_policy": "deny",
"images": [
{
"id": "550e8400-e29b-41d4-a716-446655440000",
"url": "https://example.com/image.jpg",
"design_id": "DABCdefg123",
"design_edit_url": "https://canva.com/design/edit/123",
"canva_asset_id": "asset123",
"alt": "Product image",
"caption": "Main product view",
"sort_order": 1,
"is_primary": true
}
]
}
}
]

The request is malformed or failed validation.

Media typeapplication/json
One of:
object
statusCode
required

The HTTP status code.

number
message
required

What went wrong; validation failures list one message per problem.

One of:
string
error

The HTTP status text, such as Bad Request.

string

Example generated

{
"statusCode": 1,
"message": [
"example"
],
"error": "example"
}

The key is missing, invalid, revoked or expired.

Media typeapplication/json
One of:
object
statusCode
required

The HTTP status code.

number
message
required

What went wrong; validation failures list one message per problem.

One of:
string
error

The HTTP status text, such as Bad Request.

string

Example generated

{
"statusCode": 1,
"message": [
"example"
],
"error": "example"
}

The key may not do this: a missing scope, a readonly key, a publishable key on a Store API route, or a disallowed origin.

Media typeapplication/json
One of:
object
statusCode
required

The HTTP status code.

number
message
required

What went wrong; validation failures list one message per problem.

One of:
string
error

The HTTP status text, such as Bad Request.

string

Example generated

{
"statusCode": 1,
"message": [
"example"
],
"error": "example"
}