Skip to content

Preview variant generation

POST
/stores/{storeRef}/variant-generation/preview
curl --request POST \
--url https://apibase.ecomweb.app/api/v1/stores/example/variant-generation/preview \
--header 'Content-Type: application/json' \
--header 'x-api-key: <x-api-key>' \
--data '{ "attributes": [ { "attribute_id": 12, "value_ids": [ 3, 4 ] }, { "custom_name": "Size", "custom_values": [ "S", "M" ] } ], "defaults": { "price": 199000, "inventory": 5, "min_stock_alert": 2 }, "sku_pattern": "{product}-{Color}-{Size}-{n}", "product_name": "Tee", "max": 100, "existing_product_id": 42 }'

Computes the variants that would result from crossing the given attributes and values, without saving anything. Existing variants of existing_product_id are skipped, SKUs are rendered from sku_pattern, and the result is capped at max (500 at most). Each generated variant lists its combinations with option_id and option_value_id, the names the variant create request expects.

Required scopes: write:products

storeRef
required
string

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

Media typeapplication/json
object
attributes
required

Axes to cross, in order. Each entry is either a library attribute (attribute_id + value_ids) or a local axis (custom_name + custom_values).

Array<object>
object
attribute_id

Library attribute id — its attribute_values become this axis. Mutually exclusive with custom_name.

number

Example

12
custom_name

Local (non-library) axis name, used with custom_values. Mutually exclusive with attribute_id.

string

Example

Size
value_ids

Selected attribute_values ids, for a library attribute_id axis

Array<number>

Example

[
3,
4
]
custom_values

Local axis values, for a custom_name axis

Array<string>

Example

[
"S",
"M"
]

Example

[
{
"attribute_id": 12,
"value_ids": [
3,
4
]
},
{
"custom_name": "Size",
"custom_values": [
"S",
"M"
]
}
]
defaults

Default values applied to every generated row

object
price

Default price applied to every generated row

number

Example

199000
inventory

Default inventory applied to every generated row

number

Example

5
min_stock_alert

Default low-stock alert threshold

number

Example

2
sku_pattern

SKU template. Supports {product}, {n} and each axis’s attribute/custom name as tokens.

string

Example

{product}-{Color}-{Size}-{n}
product_name

Product name used for the {product} SKU token. Falls back to the existing product’s name when existing_product_id is set.

string

Example

Tee
max

Maximum rows to generate, clamped to 500

number
>= 1 <= 500

Example

100
existing_product_id

Existing product to dedupe against — its saved variant combinations are excluded from the generated rows. Must belong to the same store.

number

Example

42
Media typeapplication/json
object
generated
required

The variants that would be created.

Array<object>
object
combinations
required

The attribute values that define the variant.

Array<object>
object
attribute_id
required

Library attribute ID, or null for a custom axis.

number
nullable
attribute_name
required

Attribute name.

string
value_key
required

Normalised key of the value.

string
value_display
required

Value as shown to shoppers.

string
attribute_value_id
required

Library attribute value ID, or null for a custom value.

number
nullable
option_id
required

Same as attribute_id, under the name the variant create request expects.

number
nullable
option_value_id
required

Same as attribute_value_id, under the name the variant create request expects.

number
nullable
price
required

Price from the defaults.

number
inventory
required

Stock from the defaults.

number
min_stock_alert

Low-stock threshold from the defaults.

number
seller_sku

SKU rendered from the SKU pattern.

string
total_combinations
required

Number of combinations the axes produce before any are skipped or cut off.

number
skipped_existing
required

Number of combinations skipped because the product already has them.

number
truncated
required

True when the result was cut off at the max limit.

boolean

Example generated

{
"generated": [
{
"combinations": [
{
"attribute_id": 1,
"attribute_name": "example",
"value_key": "example",
"value_display": "example",
"attribute_value_id": 1,
"option_id": 1,
"option_value_id": 1
}
],
"price": 1,
"inventory": 1,
"min_stock_alert": 1,
"seller_sku": "example"
}
],
"total_combinations": 1,
"skipped_existing": 1,
"truncated": 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"
}