Update listing intent
Updates only the listing's desired local data.
Use this PATCH to adjust the offer deliberately, and publish only when you are satisfied. It never calls the marketplace; every change marks local intent as dirty.
Only the offer (desired.offer) changes here. Title, description, media, and attributes belong to the MarketplaceProduct: use its PATCH. Sending content, attributes, or fulfillment returns 400.
desired uses deep merge, key by key. For offer, provide the required priceInCents (price in cents) and currency pair. Besides price, the offer accepts quantity tiers, scheduled prices, audience, minimum purchase, handling time, warranty, and fulfillment channels.
marketplaceOptions no longer goes through here: sending the field returns 400. Use Get and Update marketplace options. For an exception in a single publication, use oneTimeMarketplaceOptions in publish.
api_keyAuthorizationBearer <token>API key (mk_...)
listingId*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
Local listing fields to change. This operation never publishes.
desired?Local offer intent. Content (title, pictures, attributes) belongs to the MarketplaceProduct.
The changed local listing. It was not published.
application/json- response
A marketplace offer. Its content is the marketplace product it points at; its Variants come through the bindings.
id*stringListing 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)$uuidsellerId*stringSeller that owns this listing.
^([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)$uuidconnectionId*stringMarketplace connection that owns this listing.
^([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)$uuidmarketplaceProductId*stringMarketplace product whose shared content this offer sells.
^([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)$uuiddesired*Persisted local offer intent.
observed*|Last observed marketplace state.
marketplaceOptions*Persistent marketplace-specific options.
marketplaceStatus*stringNormalized marketplace lifecycle state.
"draft""active""paused""under_review""scheduled""suppressed""frozen""closed""deleted""rejected""unknown"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.
publicationState*stringLocal publication work state. never_published: no publication yet. dirty: local changes (desired data or bindings) not published. pending: a publish or remove Job is queued or running. clean: the last publication succeeded and nothing changed locally since. failed: the last publish or remove Job failed; publish again to retry. A local change while a Job runs keeps dirty.
"never_published""clean""dirty""pending""failed"linkState*stringWhether the listing variations are bound to local Variants. linked: at least one binding. unlinked: none. ambiguous: an import matched more than one Variant for at least one variation and bound none of them; resolve it with PUT variant-bindings.
"unlinked""linked""ambiguous"syncPolicy*Effective synchronization policy.
createdAt*stringWhen the listing 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 listing 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/listings/497f6eca-6276-4993-bfeb-53cbbbba6f08" \ -H "Content-Type: application/json" \ -d '{ "desired": { "offer": { "priceInCents": 489900, "currency": "BRL" } } }'{ "id": "0e2ce906-a6ab-4101-9461-4168c8b6b902", "sellerId": "3d1c8a52-7f0e-4b0a-8a65-9c1b2f6d7e01", "connectionId": "3f7d8a57-3e44-4c91-bbf1-02d9f4e4e5b0", "marketplaceProductId": "8a6f0c55-6a1e-4c55-9b0a-3b1f2d9e4c10", "desired": { "offer": { "priceInCents": 499900, "currency": "BRL" } }, "observed": null, "marketplaceOptions": {}, "marketplaceStatus": "draft", "buyable": null, "discoverable": null, "pendingRevision": null, "statusReasons": [], "publicationState": "never_published", "linkState": "unlinked", "syncPolicy": { "inbound": { "mode": "active" }, "outbound": { "enabled": true }, "inventory": { "mode": "manual", "eligibleBindingIds": [] } }, "createdAt": "2026-10-10T12:00:00.000Z", "updatedAt": "2026-10-10T12:00:00.000Z"}