Create local listing
Creates a listing draft in an active Connection.
This endpoint creates only the local offer record. The Connection must belong to the same Seller and be active, but the API does not call the marketplace, create an external item, or reserve inventory. The Listing starts without an external identity and without bindings until you define them.
The content lives on the MarketplaceProduct. Pick one path:
marketplaceProductId: reuses a MarketplaceProduct from the same Connection. This is the price A/B test: two offers, same content.marketplaceProduct: { desired }: creates a new MarketplaceProduct with that content.- Neither: creates an empty MarketplaceProduct that you fill in later with the PATCH.
Sending both returns 400. A marketplaceProductId from another Connection also returns 400.
desired carries only the offer, in desired.offer (price, reference price, purchase limit). content, attributes, and fulfillment return 400: they belong to the MarketplaceProduct. marketplaceOptions is persistent and must be namespaced by marketplace, such as mercadolivre; do not use it for common data that the API already normalizes.
The default policy accepts inbound, permits explicit outbound commands, and keeps automatic inventory off. Create the Listing, add bindings, review resolved, and only then publish.
Common errors
422 CAPABILITY_UNSUPPORTED: the marketplace accepts only one offer per MarketplaceProduct (listings.offersPerMarketplaceProduct: one) and themarketplaceProductIdalready has a Listing.404 NOT_FOUND: themarketplaceProductIddoes not exist or belongs to another account.
api_keyAuthorizationBearer <token>API key (mk_...)
sellerId*stringSeller the new resource belongs to.
^([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
A local offer draft for one connected marketplace account, with the marketplace product it sells.
connectionId*stringActive marketplace 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?stringExisting marketplace product of the same connection whose content this offer sells: a price A/B test. Send this or marketplaceProduct, not both.
^([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)$uuidmarketplaceProduct?Content of a new marketplace product created with this offer. Without marketplaceProductId an empty one is created even when this is omitted.
desired?Local offer intent. Content (title, pictures, attributes) belongs to the MarketplaceProduct.
{}marketplaceOptions?Namespaced persistent options validated against the connected marketplace capability.
{}syncPolicy?Independent inbound, outbound, and inventory synchronization decisions.
{ "inbound": { "mode": "active" }, "outbound": { "enabled": true }, "inventory": { "mode": "manual", "eligibleBindingIds": [] }}The created local offer draft, with marketplaceProductId. No marketplace call was made.
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 POST "https://example.com/v1/sellers/b6a1c0de-3f0c-4f53-9c6e-2a1d7d3b9e10/listings" \ -H "Content-Type: application/json" \ -d '{ "connectionId": "3f7d8a57-3e44-4c91-bbf1-02d9f4e4e5b0", "marketplaceProduct": { "desired": { "content": { "title": "iPhone 16" } } }, "desired": { "offer": { "priceInCents": 499900, "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"}