Skip to content

Merchant API

Build on your store with the merchant REST API, with tokens scoped to what they need.

Updated

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 stable type and code. 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

Type to search…

↑↓ navigate↵ selectEsc close