Getting started

Mint a credential in the app, exchange it for a token with client_credentials, and make your first authenticated call. Includes the full scope list.

The MarketplaceHub API is a server-to-server REST API over your own account's data. It exposes your orders, your catalogue and the health of your marketplace connections. It does not proxy the marketplaces themselves and never exposes their credentials.

1. Mint a credential

In the app, open the account menu, then API → Credentials. Give the credential a name, tick the permissions it needs, and create it.

The secret is shown once. It is stored hashed, so nobody — including us — can recover it afterwards. Copy it somewhere safe before you leave the page; if you lose it, create a new credential and delete the old one.

Grant only the permissions the integration actually uses. A system that reads orders and never writes should hold OrdersRead and nothing else — that way a leaked credential cannot cancel anybody's order.

2. Get a token

The API uses OAuth 2.0 client_credentials. There is no user, no browser and no redirect — your server exchanges the credential for a token directly.

curl -X POST https://identity.marketplacehub.com/connect/token \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "grant_type=client_credentials" \
  -d "client_id=mh_YourClientId" \
  -d "client_secret=YourSecret" \
  -d "scope=OrdersRead OrdersWrite"

Ask for the scopes you need, space-separated. The response carries an access_token and an expires_in. Cache the token until shortly before it expires rather than fetching one per request.

3. Call the API

The base URL is https://api.marketplacehub.com. Send the token as a bearer credential.

curl -X POST https://api.marketplacehub.com/api/orders/List \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"Limit": 25}'

That is the whole handshake. If it returns orders, you are integrated.

Permissions

Scope	Grants
`OrdersRead`	List and read orders
`OrdersWrite`	Confirm, cancel, refund and update orders
`InventoryRead`	Read products, their listings, and job status
`InventoryWrite`	Push price and quantity changes
`MarketplacesRead`	Read marketplace connections and their health
`WebhooksWrite`	Reserved. Outbound webhooks are not available yet — nothing is delivered and there is no endpoint to subscribe with. Granting it today does nothing.

Try it interactively

Swagger UI is a live console against the same API, with the full machine-readable schema behind it. Use it to poke at a request shape; use these pages to understand what the endpoints mean.

What is not here

Connecting and disconnecting marketplaces stays in the app. Those are OAuth journeys with consent screens and redirects, which is not something an API can carry. You can read the state of a connection through the API — see Marketplaces and jobs — but you authorise it in the app.