Using the API: credentials, quotas and webhooks

Mint and rotate API credentials, read your request quota, check the call log, register signed webhooks, and see which AI assistants are connected.

The MarketplaceHub API lets your own systems read and write your catalog, listings, price, quantity and orders without going through the app. You manage it from the sidebar under API, which has five pages: Logs, Request Throttling, Credentials, Webhooks and Assistants.

This page covers those screens. For endpoints, request and response shapes, and the interactive explorer, see the API reference.

Create a credential

Open API → Credentials and fill in Create a credential:

1. Give it a Name you'll recognise later — e.g. "Warehouse sync". It is a label for you; it has no effect on access.
2. Tick the Permissions it needs. Grant only what that integration uses:
   • OrdersRead — Read orders
   • OrdersWrite — Confirm, cancel, refund and update orders
   • InventoryRead — Read products and listings
   • PricingWrite — Set price and quantity
   • CatalogWrite — Create and update products and listings
   • InventoryWrite — Both of the above (the original permission)
   • MarketplacesRead — Read marketplace connections and their health
   • AdsRead — Read advertising (it cannot change an ad)
   • WebhooksWrite — Manage webhook subscriptions
3. Click Create credential.

Copy the client secret before you close the panel. It is shown once and never again — we store only a hash of it. If you lose it, rotate the credential to get a new one.

Only an account administrator can create, rotate or revoke credentials, and you may be asked to sign in again first. Other team members can see the list, so they can tell whether an integration exists, but cannot change it.

Rotate and revoke

Every credential row has two actions:

• Rotate issues a new secret and gives the old one a 7-day overlap — the row shows the exact cutoff, e.g. "Previous secret for mh_… stops working at … UTC". Both secrets work during the overlap, so you can deploy the new one on your own schedule instead of racing a cutover. Rotate on a schedule, and whenever a secret may have been exposed.
• Revoke switches the credential off immediately. Its status changes to Revoked and calls using it start failing at once. Revoked rows stay in the list as a record; they cannot be re-enabled, so create a new credential instead.

Request Throttling

Calls are rate limited per account. API → Request Throttling shows one row per endpoint you've called:

• Available Request Count — how much budget is left right now.
• Maximum Quota — the ceiling that budget refills toward.
• Restore Rate — how quickly it refills.
• Last Request Time — when you last called it.

One credential or assistant may use at most half of an endpoint's allowance, so one integration stuck in a loop cannot use up what your others need. The page shows the whole account's budget.

The page is empty until your credentials have made some calls. Go over the limit and the API answers 429; back off and retry rather than looping, and the budget restores on its own.

Logs

API → Logs records the calls your credentials made — version, URL, content type, status and time. Filter by any column, and expand a row to see the request and the response it got back. This is the first place to look when an integration behaves unexpectedly: it shows what actually arrived, which is often not what the integration meant to send.

Webhooks

Webhooks push events to your systems as they happen, so you don't have to poll. Open API → Webhooks, enter an https:// URL reachable from the internet, tick the events you want, and click Add endpoint. As with credentials, this is administrator-only, and the signing secret is shown once — copy it before closing the panel.

The events available today:

• OrdersDownloaded — New orders were pulled from a marketplace
• ListingPublished — A batch of products finished publishing to a marketplace
• FeedOutcome — A marketplace reported problems processing a feed
• MarketplaceUnhealthy — A marketplace connection stopped working
• MarketplaceRestored — A marketplace connection started working again

Verifying a delivery

Every delivery is signed. Check the signature before you trust the body — your endpoint is a public URL, and anyone can post to it. Each request carries:

• X-MH-Signature — the signature to verify
• X-MH-Timestamp — when it was sent
• X-MH-Event — which event this is
• X-MH-Delivery-Id — a stable id for the delivery
• X-MH-Attempt — which attempt this is, from 1

The signature covers the timestamp and the body, so a captured delivery cannot be replayed later. Reject anything whose timestamp is more than 5 minutes old. The webhook reference has the exact scheme and a worked example.

When an endpoint stops responding

A failed delivery is retried six times, backing off 1 minute, 5 minutes, 15 minutes, 1 hour, 3 hours, 6 hours — roughly half a day in total. The row shows Failing (n/6) while that plays out, so you can see how close it is to being switched off.

After six consecutive failures the endpoint is Disabled and the row explains why. Fix the endpoint, then delete it and add it again — a disabled endpoint cannot be re-enabled in place. Deliveries on any row opens its recent attempts with the response each one got, which is usually enough to tell a wrong URL from an outage on your side.

Assistants

API → Assistants lists the AI assistants connected to your account — Claude, ChatGPT or anything else that speaks the Model Context Protocol. An assistant is not a credential and does not appear under Credentials: it signs in the way a person does and asks you to approve what it may do, so there is no secret to mint for it.

Each row shows what the assistant was allowed to do and who approved it. Disconnect removes it, and it must ask for your approval again before it can read anything. A token it already holds keeps working until it expires, up to an hour.

The list belongs to the account rather than to one person, so a colleague can disconnect an assistant you connected. An assistant's calls draw on the same request allowance as your credentials and appear in the same Logs page — it does not get a second allowance for speaking a different protocol.

Full setup steps are in Connect an AI assistant.

Where to go next

• Getting started — exchange your credential for a token and make a first call.
• Conventions — paging, errors, idempotency.
• Full reference — orders, inventory, marketplaces and jobs, webhooks.
• MCP server — the tools an assistant gets, and what it cannot do.