PlatformMarketplacesPricingDashboardStart for free
Listings

Update variant binding

Adjusts one offer line without replacing the whole map.

PATCH
/v1/listings/{listingId}/variant-bindings/{bindingId}

Use it to change one offer line without resending the map via Replace bindings. The binding id stays the same. Send at least one field.

  • desired.offer is merged key by key over the line's current override.
  • Changed externalId, externalSku, or the variant? The link becomes linkSource: manual and matchedBy: null.
  • It never calls the marketplace. The Listing becomes publicationState: dirty and emits listing.updated.

Common errors

  • 404 NOT_FOUND: the binding does not exist or belongs to another Listing.
  • 400 VALIDATION_ERROR: details.field is marketplaceProductVariantId (variant from another MarketplaceProduct, or already linked to another line) or externalId/externalSku (identity already used by another line of the Listing).
  • 409 CONFLICT with details.reason equal to variant_archived: the Variant is archived.

Authorization

api_key
headerAuthorizationBearer <token>

API key (mk_...)

Path Parameters

listingId*string
Match^([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)$
Formatuuid
bindingId*string
Match^([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)$
Formatuuid

Request Body

application/json
  1. body

Fields of one offer line to change. This operation never publishes; the listing becomes dirty.

marketplaceProductVariantId?string

Another variation of the listing marketplace product for this line to sell. The line keeps its id.

Match^([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)$
Formatuuid
externalId?|

Marketplace identity of the line; null clears it.

Length1 <= length <= 300
externalSku?|

Marketplace SKU of the line; null clears it.

Length1 <= length <= 300
inventoryEligible?boolean

Whether this line may receive inventory publication.

desired?

Offer override of this line, merged key by key over the current one.

Response Body

The binding after the change, with the same id. The listing becomes dirty; nothing is published.

application/json
  1. response

One offer line: a marketplace product variation sold by this listing.

id*string

Binding identifier.

Match^([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)$
Formatuuid
listingId*string

Listing that owns this binding.

Match^([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)$
Formatuuid
marketplaceProductVariantId*string

Marketplace product variation this offer line sells.

Match^([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)$
Formatuuid
variantId*string

Local Variant of the marketplace product variation. Read-only: it follows the variation.

Match^([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)$
Formatuuid
externalId*|

Marketplace identity of this offer line (Mercado Livre item id per User Product; Shopee model_id; TikTok sku_id), if known.

externalSku*|

Marketplace SKU identity, if known.

inventoryEligible*boolean

Whether this binding may receive inventory publication.

linkSource*string

How this local binding was chosen.

Value in"manual""imported_match""imported_create"
matchedBy*|

Exact identifier used by an imported match.

desired*

Offer override of this line.

marketplaceStatus*|

Normalized marketplace lifecycle state of the line; null until the marketplace reports it.

Value in"draft""active""paused""under_review""scheduled""suppressed""frozen""closed""deleted""rejected""unknown"null
buyable*|

Whether the marketplace lets buyers purchase it now; null when not known.

discoverable*|

Whether the marketplace shows it in search and browse; null when not known.

pendingRevision*|

Revision under marketplace review alongside the active one.

statusReasons*array<>

Normalized reasons for the current marketplace state.

lastPublishedAt*|

When this binding last confirmed a remote publication.

Match^(?:(?:\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))$
Formatdate-time
curl -X PATCH "https://example.com/v1/listings/497f6eca-6276-4993-bfeb-53cbbbba6f08/variant-bindings/497f6eca-6276-4993-bfeb-53cbbbba6f08" \  -H "Content-Type: application/json" \  -d '{    "desired": {      "offer": {        "priceInCents": 489900      }    }  }'
{  "id": "cb064b64-2f63-4c3e-aa42-f11ea0f82b17",  "listingId": "0e2ce906-a6ab-4101-9461-4168c8b6b902",  "marketplaceProductVariantId": "5b2d7e9a-1c4f-4e6b-8a3d-2f9c0b7e6d41",  "variantId": "47c9f819-fcf6-4478-b21a-678ecc594a11",  "externalId": "MLB123",  "externalSku": "IP16-BLK-128",  "inventoryEligible": true,  "linkSource": "manual",  "matchedBy": null,  "desired": {},  "marketplaceStatus": null,  "buyable": null,  "discoverable": null,  "pendingRevision": null,  "statusReasons": [],  "lastPublishedAt": null}

Replace variant bindings PUT

Atomically replaces the complete binding map.

Remove variant binding DELETE

Removes one offer line, local record only.