Listings

A Listing is the offer in a Connection: price, inventory, and commercial rules of an ad on Mercado Livre, Amazon, TikTok Shop, or another channel. The content the marketplace displays (title, description, attributes, media, variations) lives on the MarketplaceProduct, which the Listing points to with marketplaceProductId.

The Listing does not replace the local Product and is not the source of truth for your items. One Product and its Variants can supply N Listings.

Price A/B × content A/BCopy Anchor Link

Changing a MarketplaceProduct's title changes all of its offers. To test a title, create another MarketplaceProduct with clone.

Some marketplaces accept only one offer per MarketplaceProduct. There, a price A/B test returns 422 CAPABILITY_UNSUPPORTED; use a content A/B test.

The full model of Listing and binding, and where each published field comes from, with diagrams: Connections and listings.

The three representationsCopy Anchor Link

The Listing's desired has only offer. Sending content, attributes, or fulfillment returns 400: those fields belong to the MarketplaceProduct.

Offer precedence is: line override (binding, desired.offer) → Listing.desired.offer. For content, see the MarketplaceProduct inheritance. Absence means “inherit”; it does not mean delete a marketplace value. Read resolved data before publishing.

End-to-end flow: from catalog to published offerCopy Anchor Link

1. Check the Connection's Connection capabilities. The API can perform an external operation only when the connected adapter implements it.
2. Create or import Products and Variants. Define SKUs/GTINs and inventory at the Variant level.
3. Create the local Listing. It creates the MarketplaceProduct with it, or reuses one you pass. No external call exists at this stage.
4. Fill in the content on the MarketplaceProduct and, if needed, its variations.
5. Replace the binding map, linking each offer line to a MarketplaceProduct variation.
6. Read resolved, edit desired as many times as needed, and configure the sync policy.
7. Publish explicitly. The response is a Job; track it until it reaches a final result.
8. For an offer that already exists in a marketplace, use Connection import/reconciliation. External changes arrive in observed and in webhooks without changing Product or Variant.

Mercado Livre: the title comes from the MarketplaceProductCopy Anchor Link

Mercado Livre generates the ad title from family_name. So the MarketplaceProduct's desired.content.title is sent as family_name, and the title the channel generated shows in observed, not in what you sent. The title is shared by every offer on the same MarketplaceProduct.

States that must not be confusedCopy Anchor Link

• marketplaceStatus: lifecycle reported by the channel, such as active, paused, closed, deleted, scheduled, suppressed, or frozen. Layered next to it: buyable and discoverable (true, false, or null when unknown), pendingRevision (revision under review), and statusReasons (code, message, and externalCode from the channel). The Listing and each binding have their own; a line with no layer of its own inherits the offer's.
• publicationState: state of local intent, such as never_published, dirty, pending, clean, or failed. How each one changes: States and events.
• linkState: quality of the local link, linked with at least one binding, unlinked with none, ambiguous when an import found more than one Variant for a variation.

What is stuckCopy Anchor Link

When a listing does not publish, or is not the way you expected, ask in this order:

All five only read what MarketAPI already stores. None of them calls the marketplace.

ConflictsCopy Anchor Link

A conflict is not just desired differing from observed: the two almost always differ, because the marketplace adds fields you never sent. There is a conflict when you have a local change not yet published and the marketplace changed the same group. A change on one side only is a pending item of yours or a change of theirs, not a conflict.

Each group (content, catalog, offer, inventory, status) keeps what the last publication confirmed. The diff compares both sides with that base and gives one state per group:

A group that was never published is never_published. Only content and offer become conflict and open a conflict record. In catalog and inventory, with both sides changed, the state is pending_publication: the next publication sends your value. status has no local value.

The record is born when the two sides meet: a notification or reconciliation arrives with inbound active and your edit already pending, or you edit after the outside change had already arrived. MarketAPI keeps your desired, publishes nothing and sends listing.conflict_created. You resolve it with one of four resolutions:

• keep_local: your value stays.
• accept_external: the marketplace value becomes yours.
• inherit: your override goes away, and the field inherits again.
• manual: you send the value in value.

Resolving never publishes. It only changes the local desired; for the marketplace to follow, publish afterwards.

Current supportCopy Anchor Link

The indicators are a static product overview. Read the complete marketplace matrix and, before showing an action in your app, read the Connection capabilities for the Connection that will receive the command.

Read listing

• MockDevelopment only
• Mercado LivreNot supported
• MagaluPlanned
• AmazonPlanned
• TikTok ShopPlanned
• ShopeePlanned

Publish listing

• MockDevelopment only
• Mercado LivreNot supported
• MagaluPlanned
• AmazonPlanned
• TikTok ShopPlanned
• ShopeePlanned

Remove listing

• MockDevelopment only
• Mercado LivreNot supported
• MagaluPlanned
• AmazonPlanned
• TikTok ShopPlanned
• ShopeePlanned

External catalogCopy Anchor Link

The catalogReference lives on the MarketplaceProduct, not on the Listing: it records that the content is associated with an external catalog product and the fields that catalog blocks. It does not become the local Product: your base is still required for SKU, inventory, kits, audit history, and multiple offers. Use marketplace-specific options only in that marketplace's namespace, in marketplaceOptions, or in oneTimeMarketplaceOptions for a single publication.