Publish listings

A listing has two parts. The content (MarketplaceProduct) is what the buyer sees: title, description, photos, attributes and variations. The offer (Listing) is what they pay: price, handling time, warranty and quantity. One line of the offer, the binding, links each variation to a Variant of the catalog. The full model: Connections and listings.

Keeping the two parts apart lets you test price with two offers on the same content, or test a title with two contents.

1. Find out what the marketplace asks forCopy Anchor Link

Each marketplace has its own categories and asks for different fields. Before building the listing, ask the Connection for:

• the right category and its requirements: which attributes are required, and when;
• the brands, product types, size chart and shipping options it accepts;
• whether a marketplace catalog product already exists for the item. Linking to it makes the listing stronger, and some fields start coming from the catalog.

These reads answer right away, with no job.

2. Build the listingCopy Anchor Link

1. Create the offer. The Listing starts as a local draft and creates the content with it. Nothing goes to the marketplace yet.
2. Fill in the content on the MarketplaceProduct. What you leave empty is inherited from the Product and the Variant.
3. Link the variations to the Variants: the black and the white iPhone become two lines of the same offer.
4. Set the offer: priceInCents, reference price, quantity tiers, scheduled prices, handling time and warranty. A line can have its own price.
5. Check the result. resolved shows the final value of each field and where it came from.

Options only one marketplace understands go in marketplaceOptions, kept per marketplace.

3. Validate and publishCopy Anchor Link

• Validate asks the marketplace whether the listing would pass, without publishing. Pending items show up in issues.
• Publish sends the content and the offer. If the content was never published, it goes along.
• Publish in batch sends many listings in one job, one item per listing.

All of these answer 202 with a job. When publishing takes several calls, the job item keeps each step, and a new attempt goes on from where it stopped. At the end, the Listing keeps the marketplace ids and observed with what is there.

4. Already selling there? ImportCopy Anchor Link

If Acme Store already has listings on Mercado Livre, import them instead of building them again. The Connection's import policy decides what to do with each listing:

Matching never uses the title. If two Variants match, nothing is linked, and the listing stays ambiguous until you fix the map.

5. After publishingCopy Anchor Link

• Marketplace actions: pause, activate, close or relist. Relisting creates a new Listing, linked to the old one.
• Remove: publication=delete takes the listing off the marketplace; keep deletes it here only.
• Clone: copies an offer as a draft, to test price or content.

Endpoints in this phaseCopy Anchor Link

Webhooks in this phase: listing.created, listing.updated, listing.deleted, listing.status_changed, marketplace_product.created, marketplace_product.updated and job.completed.