Reconcile listings
Queues a new external read to check observed state.
Import listings
- MockDevelopment only
- Mercado LivreNot supported
- MagaluPlanned
- AmazonPlanned
- TikTok ShopPlanned
- ShopeePlanned
Reconciliation performs the same safe external read as import, but its operational intent is to compare again the marketplace with known state. Use it after an outage, suspected missed notification, manual store review, or a window when your application was offline.
The call is external-read-only: it does not publish desired, deliver inventory, or replace Product/Variant with marketplace data. The response is a Job, and each offer's normalized snapshot is updated in observed. The Connection import policy decides only how new bindings are handled; it does not turn Product or Variant into marketplace data.
Do not use reconciliation as high-frequency polling. Prefer inbound notifications for normal changes and use this endpoint as a verifiable repair operation, tracking the Job and then synchronization state.
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 reconciliation job.
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-reconciliations"{ "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"}