Create variant
Creates a sellable combination, such as color and storage.
Create one Variant for each combination that may have its own SKU, GTIN, availability, cost, or content. options identifies that combination within the Product, for example { "color": "black", "storage": "128GB" }. The same option combination cannot be created twice in one Product.
SKU and GTIN are particularly important when importing listings: automatic linking uses exact identifiers only and never uses a title. Choose the inventory authority before you start moving quantity. If you provide cost, send costInCents (cost in cents) and costCurrency together. In physical, weight goes in grams (weightInGrams) and dimensions in millimeters (dimensionsInMm), always as integers; the package has its own (packageWeightInGrams, packageDimensionsInMm). Variant attributes use the same typed format as the Product and win over it on the same key.
Creating a Variant remains a local operation. It does not create a marketplace variation yet: use bindings to associate it with a listing and explicit publication to send it to the channel.
api_keyAuthorizationBearer <token>API key (mk_...)
productId*string^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$uuidIdempotency-Key?stringOptional. A unique value (for example a UUID), 1 to 255 characters, that makes the request safe to retry: repeating it with the same body within 24h returns the original response with Idempotency-Replayed: true instead of running the operation again. Scoped to your account. Reusing it with a different body returns 409.
1 <= length <= 255application/json- body
One sellable combination of a product.
sku?stringSeller SKU for exact import matching.
1 <= length <= 200gtin?stringGTIN or EAN for exact import matching.
1 <= length <= 64externalIdentifiers?Other customer-known identifiers for this variant.
{}options?Option name/value combination, unique within its Product.
{}content?Variant-specific content overrides.
attributes?array<>Typed attributes specific to this variant.
items <= 200physical?Variant-level dimensions, weight and package quantity.
costInCents?integerUnit cost in cents; requires costCurrency.
0 <= value <= 9007199254740991costCurrency?stringISO 4217 currency of costInCents; requires costInCents.
^[A-Z]{3}$inventoryAuthority?stringSystem that is authoritative for this variant stock.
"disabled""managed_externally""marketapi""derived""disabled"allowBackorder?booleanWhether MarketAPI may keep a negative available balance.
falsemedia?array<>Ordered references to variant media assets.
items <= 100[]metadata?Customer-owned variant metadata that MarketAPI does not interpret.
{}The created variant.
application/json- response
A sellable product variant with its own inventory identity.
id*stringVariant identifier.
^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$uuidproductId*stringProduct that owns this variant.
^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$uuidsellerId*stringSeller that owns this variant.
^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$uuidstatus*stringLifecycle state of the variant.
"active""archived"sku*|Seller SKU, if set.
gtin*|GTIN/EAN, if set.
externalIdentifiers*Known external identifiers.
options*Unique option combination within the product.
content*|Variant-specific content overrides.
attributes*array<>Variant attributes.
items <= 200physical*|Variant physical overrides.
costInCents*|Unit cost in cents.
-9007199254740991 <= value <= 9007199254740991costCurrency*|ISO 4217 currency of costInCents.
inventoryAuthority*stringWho is authoritative for this variant stock.
"managed_externally""marketapi""derived""disabled"allowBackorder*booleanWhether the variant may have negative available stock.
media*array<>Ordered variant media.
metadata*Customer-owned variant metadata.
createdAt*stringWhen the variant was created.
^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d:[0-5]\d(?:\.\d+)?(?:Z))$date-timeupdatedAt*stringWhen the variant was last changed.
^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d:[0-5]\d(?:\.\d+)?(?:Z))$date-timecurl -X POST "https://example.com/v1/products/497f6eca-6276-4993-bfeb-53cbbbba6f08/variants" \ -H "Content-Type: application/json" \ -d '{ "sku": "IP16-BLK-128", "options": { "color": "black", "storage": "128GB" }, "inventoryAuthority": "marketapi" }'{ "id": "47c9f819-fcf6-4478-b21a-678ecc594a11", "productId": "a0f0ce59-5d17-49bf-8b45-d1dc057daab4", "sellerId": "3d1c8a52-7f0e-4b0a-8a65-9c1b2f6d7e01", "status": "active", "sku": "IP16-BLK-128", "gtin": null, "externalIdentifiers": {}, "options": { "color": "black", "storage": "128GB" }, "content": null, "attributes": [], "physical": null, "costInCents": null, "costCurrency": null, "inventoryAuthority": "marketapi", "allowBackorder": false, "media": [], "metadata": {}, "createdAt": "2026-10-10T12:00:00.000Z", "updatedAt": "2026-10-10T12:00:00.000Z"}