Get listing
Gets a local listing by id.
This is the main read of an offer record: it shows the Connection, marketplaceProductId, the local offer (desired.offer), stored external state, policy, and the three lifecycle states. Use it to load the screen or cache for one specific listing.
The content (title, attributes, catalogReference) is not here: read the MarketplaceProduct. The response also does not calculate inheritance or return bindings. To prepare publication, read resolved; to edit inventory/variation association, read bindings; to show only the most recent external fact, read observed.
externalMarketplaceId exists only after confirmed import or publication. Do not use its absence to conclude that the base record or Variant does not exist — it only indicates that this offer is still a local draft.
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)$uuidThe requested listing.
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 GET "https://example.com/v1/listings/497f6eca-6276-4993-bfeb-53cbbbba6f08"{ "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"}