Import listings
Queues a complete read of a Connection's external offers.
Import listings
- MockDevelopment only
- Mercado LivreNot supported
- MagaluPlanned
- AmazonPlanned
- TikTok ShopPlanned
- ShopeePlanned
Use import to bring offers that already exist in the marketplace into MarketAPI. The Connection must be active and announce import: true. The 202 response creates a Job; it does not mean every listing is already locally available. Track items in Jobs and Listing webhooks.
The worker enumerates external offers, records each normalized snapshot in observed, updates marketplaceStatus, and applies the current import policy to decide bindings. External data does not overwrite existing Product or Variant records; marketplace titles are not used for linking.
An imported Listing starts with outbound off and manual inventory so nothing is republished accidentally. Review unlinked Listings or imported bases, associate Variants when needed, and enable each Listing policy only after that review.
Common errors
409 CONFLICTwithdetails.reason = "connection_inactive": the Connection is not active (for example, it was revoked). Ask the seller to connect again.
api_keyAuthorizationBearer <token>API key (mk_...)
id*stringIdentifier of the resource, as returned by the API.
^([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 <= 255The queued import job. Matching follows this connection import policy.
application/json- response
A job: an operation that runs in the background, tracked by id.
id*stringOpaque unique identifier of the job, generated by the API. Use it in the /v1/jobs/{id} routes.
^([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*|The seller the job works for. null for a job of the whole account.
^([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)$uuidtype*stringWhat the job does. connection.sync: first sync of a new connection. listing.publish and listing.remove: publish a listing to the marketplace or remove it there. listing.import and listing.reconcile: read the listings of a connection from the marketplace into their observed state. inventory.publish: send stock quantities to the marketplace. marketplace_product.publish: publish the content of a marketplace product alone, without any offer field. order.import and order.reconcile: read the orders of a connection from the marketplace into marketapi.
"connection.sync""listing.publish""listing.remove""listing.import""listing.reconcile""inventory.publish""marketplace_product.publish""order.import""order.reconcile"status*stringState of the job. queued: waiting. running: in progress. completed: every item succeeded. partial: some items failed. failed: no item succeeded.
"queued""running""completed""partial""failed"total*integerItems in the job.
0 <= value <= 9007199254740991processed*integerItems already processed, succeeded or failed.
0 <= value <= 9007199254740991succeeded*integerItems that succeeded.
0 <= value <= 9007199254740991failed*integerItems that failed.
0 <= value <= 9007199254740991input*What the job was asked to do, by type. connection.sync, listing.import and listing.reconcile: { connectionId }. listing.publish: { listingId, mode }. listing.remove: { listingId, publication }. inventory.publish: { source }. marketplace_product.publish: { marketplaceProductId, mode }. order.import: { connectionId, placedFrom, placedTo }, with the period resolved to instants even when the request gave none. order.reconcile: { connectionId }.
result*|Summary of the outcome, when the type has one. null otherwise.
error*|Why the job failed, when it failed as a whole. null otherwise; the error of each item is in its items.
startedAt*|When it started running, in ISO-8601 (UTC). null while queued.
^(?:(?:\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-timefinishedAt*|When it finished, in ISO-8601 (UTC). null while queued or running.
^(?:(?:\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-timecreatedAt*stringWhen the job was created, in ISO-8601 (UTC).
^(?:(?:\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 job last changed, in ISO-8601 (UTC).
^(?:(?:\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/connections/3d1c8a52-7f0e-4b0a-8a65-9c1b2f6d7e01/listing-imports"{ "id": "7c6b5a49-3827-4615-a0b9-c8d7e6f5a4b3", "sellerId": "3d1c8a52-7f0e-4b0a-8a65-9c1b2f6d7e01", "type": "connection.sync", "status": "completed", "total": 1, "processed": 1, "succeeded": 1, "failed": 0, "input": { "connectionId": "9a1b2c3d-4e5f-4a6b-8c7d-0e1f2a3b4c5d" }, "result": null, "error": null, "startedAt": "2026-10-06T14:32:01.000Z", "finishedAt": "2026-10-06T14:32:01.500Z", "createdAt": "2026-10-06T14:32:00.000Z", "updatedAt": "2026-10-06T14:32:01.500Z"}