The merchant API lets your own code run your business and its stores as the merchant app does: products, prices, content, files, customers, orders, subscriptions, discounts, affiliates, reviews, quizzes, certificates, webhooks and the store’s settings. What is decided in person stays in the app: your plan and billing, the business’s members, API tokens, and deleting a store or the business. It is a JSON API over HTTPS at https://api.sherpo.io/merchant, and every path in these docs is under that base: GET /v1/merchants is a GET of https://api.sherpo.io/merchant followed by /v1/merchants. The OpenAPI 3.1 document of the whole API is at https://api.sherpo.io/merchant/openapi.json, open to anyone, so you can generate a client from it.
The merchant API, its webhooks and the merchant MCP server are on every plan.
How it works
- A token acts as you. You create an API token in the merchant app, pick what it may do, and send it as a bearer. A call may do what both your seat in the business and the token allow. See authentication and scopes.
- One store per call. Store operations live under
/v1/stores/{store}; the business itself is under/v1/merchants. See requests. - Lists page with a cursor, and take filters, sorts, search and facets. See pagination.
- Failures are problems (
application/problem+json) with a stabletypeandcode. See errors. - Writes can be repeated safely with an
Idempotency-Key. See idempotency. - Calls are metered per token, on each store on its own. See rate limits.
- Events reach you as signed webhook deliveries. See webhooks.
- The API grows without breaking within
/v1. See versioning.
A first call
With a token in SHERPO_TOKEN, list the business the token belongs to and the stores it may act on:
curl 'https://api.sherpo.io/merchant/v1/merchants' \
-H "Authorization: Bearer $SHERPO_TOKEN"const answer = await sherpo('GET', '/v1/merchants');Answers 200, abridged:
{
"items": [
{
"id": "1f2e3d4c-5b6a-4978-8a1b-2c3d4e5f6a7b",
"name": "Ada Studio",
"short_name": "ada",
"created_at": "2026-03-02T09:14:00.000Z",
"scopes": null,
"stores": {
"items": [
{
"id": "STORE_ID",
"name": "Ada Studio"
}
],
"total": 1
}
}
],
"total": 1
}The first call guide sets up a small JavaScript client the other examples use.
Every endpoint
The reference lists every operation, generated from the API’s own OpenAPI document on every build, with its scope, parameters, body and answers. The guides here link to it wherever an operation comes up.
Guides
- Your first call: create a token, set up a client and read your stores.
- Products and prices: create a product, give it a tier and a price, and publish it.
- Upload a file: upload a file and attach it to a product as a download.
- Customers’ access: grant a customer a product, and take it back.
- Keep orders in sync: copy your orders into your own system and keep them current.
- Receive webhooks: create an endpoint, verify each delivery and act on it once.