Preview variant generation
const url = 'https://apibase.ecomweb.app/api/v1/stores/example/variant-generation/preview';const options = { method: 'POST', headers: {'x-api-key': '<x-api-key>', 'Content-Type': 'application/json'}, body: '{"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}'};
try { const response = await fetch(url, options); const data = await response.json(); console.log(data);} catch (error) { console.error(error);}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
Authorizations
Section titled “Authorizations”Parameters
Section titled “Parameters”Path Parameters
Section titled “Path Parameters”The store’s ref, as returned by GET /stores.
Request Bodyrequired
Section titled “Request Bodyrequired”object
Axes to cross, in order. Each entry is either a library attribute (attribute_id + value_ids) or a local axis (custom_name + custom_values).
object
Library attribute id — its attribute_values become this axis. Mutually exclusive with custom_name.
Example
12Local (non-library) axis name, used with custom_values. Mutually exclusive with attribute_id.
Example
SizeSelected attribute_values ids, for a library attribute_id axis
Example
[ 3, 4]Local axis values, for a custom_name axis
Example
[ "S", "M"]Example
[ { "attribute_id": 12, "value_ids": [ 3, 4 ] }, { "custom_name": "Size", "custom_values": [ "S", "M" ] }]Default values applied to every generated row
object
Default price applied to every generated row
Example
199000Default inventory applied to every generated row
Example
5Default low-stock alert threshold
Example
2SKU template. Supports {product}, {n} and each axis’s attribute/custom name as tokens.
Example
{product}-{Color}-{Size}-{n}Product name used for the {product} SKU token. Falls back to the existing product’s name when existing_product_id is set.
Example
TeeMaximum rows to generate, clamped to 500
Example
100Existing product to dedupe against — its saved variant combinations are excluded from the generated rows. Must belong to the same store.
Example
42Responses
Section titled “Responses”object
The variants that would be created.
object
The attribute values that define the variant.
object
Library attribute ID, or null for a custom axis.
Attribute name.
Normalised key of the value.
Value as shown to shoppers.
Library attribute value ID, or null for a custom value.
Same as attribute_id, under the name the variant create request expects.
Same as attribute_value_id, under the name the variant create request expects.
Price from the defaults.
Stock from the defaults.
Low-stock threshold from the defaults.
SKU rendered from the SKU pattern.
Number of combinations the axes produce before any are skipped or cut off.
Number of combinations skipped because the product already has them.
True when the result was cut off at the max limit.
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.
object
The HTTP status code.
What went wrong; validation failures list one message per problem.
The HTTP status text, such as Bad Request.
object
A stable, machine-readable error code.
A human-readable explanation.
Extra context about the error, when there is any.
object
When the error happened, as an ISO 8601 timestamp.
Example generated
{ "statusCode": 1, "message": [ "example" ], "error": "example"}The key is missing, invalid, revoked or expired.
object
The HTTP status code.
What went wrong; validation failures list one message per problem.
The HTTP status text, such as Bad Request.
object
A stable, machine-readable error code.
A human-readable explanation.
Extra context about the error, when there is any.
object
When the error happened, as an ISO 8601 timestamp.
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.
object
The HTTP status code.
What went wrong; validation failures list one message per problem.
The HTTP status text, such as Bad Request.
object
A stable, machine-readable error code.
A human-readable explanation.
Extra context about the error, when there is any.
object
When the error happened, as an ISO 8601 timestamp.
Example generated
{ "statusCode": 1, "message": [ "example" ], "error": "example"}