Update variant
Updates local data for a sellable unit.
Use this endpoint to change the data that differentiates a combination: SKU, GTIN, options, cost, media, specific attributes, or inventory authority. The change is local; it does not automatically update marketplace title, price, variation, or quantity.
PATCH preserves top-level fields that you omit. When you send content, it becomes the Variant's override over the Product. Send content: {} when the Variant should stop overriding content and inherit the base again. Cost requires costInCents (in cents) and costCurrency together when created; keep the pair consistent in updates.
Do not change inventoryAuthority as a shortcut to correct quantity. First reconcile the system that will be the source of truth. A Variant also cannot be archived while bound to a Listing; remove or replace those bindings first.
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)$uuidvariantId*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)$uuidapplication/json- body
Fields to change in a variant. Omitted fields stay unchanged.
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.
"managed_externally""marketapi""derived""disabled"allowBackorder?booleanWhether MarketAPI may keep a negative available balance.
media?array<>Ordered references to variant media assets.
items <= 100metadata?Customer-owned variant metadata that MarketAPI does not interpret.
status?stringNew variant lifecycle state.
"active""archived"The variant after the local change.
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 PATCH "https://example.com/v1/products/497f6eca-6276-4993-bfeb-53cbbbba6f08/variants/497f6eca-6276-4993-bfeb-53cbbbba6f08" \ -H "Content-Type: application/json" \ -d '{}'{ "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"}