Skip to content

List a product's variants

GET
/stores/{storeRef}/products/{productId}/variants
curl --request GET \
--url 'https://apibase.ecomweb.app/api/v1/stores/example/products/1/variants?attribute_value_ids=3%2C4' \
--header 'x-api-key: <x-api-key>'

Returns every variant of the product, ordered by ID, with its option values. Filter by SKU text with search, or by option values with attribute_value_ids. Variant cost_per_item is returned only when the key holds the read:inventory scope.

Required scopes: read:products

productId
required
integer

The product ID.

storeRef
required
string

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

search
string

Return only variants whose SKU contains this text, ignoring case.

attribute_value_ids
string

Example

3,4

Comma-separated attribute value IDs. Returns variants that use at least one of them.

Media typeapplication/json
Array<object>
object
images
required

Variant images.

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
required

Attribute values that define the variant.

Array<object>
object
attribute_id
required

Attribute ID.

number
attribute_name
required

Attribute name.

string
attribute_value_id
required

Attribute value ID.

number
value_display
required

Value as shown to shoppers.

string
id
required

Variant ID.

number
seller_sku
required

Merchant-assigned SKU, or null.

string
nullable
price
required

Selling price.

number
inventory
required

Units in stock.

number
track_inventory
required

Whether stock is tracked.

boolean
inventory_policy
required

deny or continue.

string
cost_per_item

Unit cost. Present only when the key holds the read:inventory scope; null when no cost is recorded.

number
nullable
status
required

Variant status.

string
nullable

Example

[
{
"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 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"
}

The resource does not exist in this store.

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"
}