PlatformMarketplacesPricingDashboardStart for free
Listings

Clone listing for A/B

Creates a local draft with no external identity.

POST
/v1/listings/{listingId}/clone

Cloning is the safe way to start an A/B experiment. The copy uses the source Listing's Connection, policy, and local Variants, but receives a new listingId and does not copy observed, externalMarketplaceId, or the external identities of the lines. It therefore never accidentally points at the published ad.

The marketplaceProduct field picks the kind of test:

ValueTestWhat happens
same (default)pricethe clone uses the same MarketplaceProduct; bindings point at the same variations
copycontentcreates another MarketplaceProduct with the same local content (externalId and catalogReference empty) and equivalent variations; bindings point at them

The clone already has bindings, but every binding has no externalId and no externalSku: that identity will be created or discovered during the new publication. It is not published automatically.

Body overrides are applied by top-level field. If you send desired.offer or marketplaceOptions.mercadolivre, send the complete object you intend to retain at that level; it replaces the corresponding source Listing object. With copy, change the copy's content on the MarketplaceProduct. Then review resolved and publish the clone as a new offer.

Common errors

  • 422 CAPABILITY_UNSUPPORTED: with same, the marketplace accepts only one offer per MarketplaceProduct. Use copy.
  • 409 CONFLICT with details.reason equal to variant_archived or product_archived: a binding of the source listing points at an archived Variant (or one active in an archived product). Nothing is cloned.

Authorization

api_key
headerAuthorizationBearer <token>

API key (mk_...)

Path Parameters

listingId*string
Match^([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)$
Formatuuid

Header Parameters

Idempotency-Key?string

Optional. 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.

Length1 <= length <= 255

Request Body

application/json
  1. body

Local overrides for a clone. The clone never copies observed external identity and is not published automatically.

desired?

Local offer intent. Content (title, pictures, attributes) belongs to the MarketplaceProduct.

marketplaceOptions?

Namespaced persistent options validated against the connected marketplace capability.

marketplaceProduct?string

same sells the same marketplace product (a price A/B test); copy creates another marketplace product with the same content (a content A/B test).

Default"same"
Value in"same""copy"

Response Body

The local clone. It has no external marketplace identity and no remote call was made.

application/json
  1. response

A marketplace offer. Its content is the marketplace product it points at; its Variants come through the bindings.

id*string

Listing identifier.

Match^([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)$
Formatuuid
sellerId*string

Seller that owns this listing.

Match^([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)$
Formatuuid
connectionId*string

Marketplace connection that owns this listing.

Match^([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)$
Formatuuid
marketplaceProductId*string

Marketplace product whose shared content this offer sells.

Match^([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)$
Formatuuid
desired*

Persisted local offer intent.

observed*|

Last observed marketplace state.

marketplaceOptions*

Persistent marketplace-specific options.

marketplaceStatus*string

Normalized marketplace lifecycle state.

Value in"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*string

Local 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.

Value in"never_published""clean""dirty""pending""failed"
linkState*string

Whether 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.

Value in"unlinked""linked""ambiguous"
syncPolicy*

Effective synchronization policy.

createdAt*string

When the listing was created.

Match^(?:(?:\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))$
Formatdate-time
updatedAt*string

When the listing was last changed.

Match^(?:(?:\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))$
Formatdate-time
curl -X POST "https://example.com/v1/listings/497f6eca-6276-4993-bfeb-53cbbbba6f08/clone" \  -H "Content-Type: application/json" \  -d '{    "desired": {      "offer": {        "priceInCents": 479900,        "currency": "BRL"      }    },    "marketplaceProduct": "same"  }'
{  "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"}

Remove listing DELETE

Removes local data or explicitly requests remote removal.

Publish listing POST

Queues an explicit marketplace publication.