MarketplaceHub Docs Docs

Marketplaces and jobs

Read the health of your marketplace connections and find out why a push failed, and follow the asynchronous jobs that endpoints hand back.

GET /api/marketplaces

Your active marketplace connections and the health of each. Needs MarketplacesRead.

Anything that reaches a marketplace runs on the worker pipeline, so the endpoint hands back a job id: poll IsComplete to know it finished, then read IsSuccessful to know whether it worked — they are separate because a failed job is also complete AN ENDPOINT THAT REACHES A MARKETPLACE HANDS BACK A JOB ID NotStarted accepted Published queued InProcess running Completed Failed / Cancelled All three are IsComplete Finished is not the same as worked. Poll IsComplete, then decide on IsSuccessful They are two fields on purpose. A failed job is complete, so “finished” never means “worked” on its own. Progress is optional ProgressDone and ProgressTotal are null for jobs that do not count rows. Absent means “does not apply”, not zero. When a push did not do what you expected, read the connection first GET /api/marketplaces reports each connection's health. RequiresReauthorization is the one state retrying never clears — a person has to reconnect.
Finished and succeeded are two different fields, on purpose.

This is the endpoint to call when a push did not do what you expected. It tells you whether the connection is working, and if not, what the marketplace said.

{
  "Marketplaces": [
    {
      "MarketplaceId": "6a73...",
      "Platform": "Amazon",
      "Country": "UnitedKingdom",
      "HealthStatus": "UnAuthorized",
      "HealthStatusMessage": "The marketplace revoked our authorisation.",
      "IsHealthy": false,
      "RequiresReauthorization": true,
      "LastPull": { "Status": "MarketplaceProductPullCompleted", "TotalSkus": 120, "CurrentSku": 120 }
    }
  ]
}

RequiresReauthorization is the one failure retrying will never clear. Somebody has to reconnect the marketplace in the app. Every other unhealthy state is worth waiting out; this one needs a person. Treat the two differently or your integration will retry forever against a connection that is never coming back on its own.

Only active connections are listed. A connection the merchant has paused is omitted — a paused marketplace is not one to push to.

A connection that has never reported a state comes back with a null HealthStatus. That means "nothing known yet", not "broken".

GET /api/jobs/{id}

The state of one asynchronous job. Needs InventoryRead.

Anything that reaches a marketplace happens on our worker pipeline, so endpoints that trigger one hand you a job id instead of blocking. This is how you follow it.

{
  "JobId": "6a73...",
  "Type": "EbayInventorySubmit",
  "Status": "InProcess",
  "IsComplete": false,
  "IsSuccessful": false,
  "StartedAt": "2026-08-05T10:00:00Z",
  "ProgressDone": 120,
  "ProgressTotal": 400,
  "RecoveryCount": 0
}
  • Poll IsComplete; decide on IsSuccessful. They are separate on purpose — a failed job is complete. Treating "finished" as "worked" is the mistake this shape exists to prevent.
  • Status is one of NotStarted, Published (queued), InProcess, Completed, Failed, Cancelled.
  • ProgressDone and ProgressTotal are null for jobs that do not count rows — absent means "does not report progress", not "zero done".
  • RecoveryCount above zero means the job was picked up again after a worker restarted. Not a failure, but worth knowing when one is slow.

Poll at a sensible interval — the rate limit applies here too. The failure reason is not returned; open the job in the app to read it.