---
title: "Merchant API"
description: "Build on your store with the merchant REST API, with tokens scoped to what they need."
---

> Documentation Index
> Fetch the complete documentation index at: https://docs.sherpo.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Merchant API

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](/merchant-mcp) 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](/merchant-api/authentication) and [scopes](/merchant-api/scopes).
- **One store per call.** Store operations live under `/v1/stores/{store}`; the business itself is under `/v1/merchants`. See [requests](/merchant-api/requests).
- **Lists page with a cursor**, and take filters, sorts, search and facets. See [pagination](/merchant-api/pagination).
- **Failures are problems** (`application/problem+json`) with a stable `type` and `code`. See [errors](/merchant-api/errors).
- **Writes can be repeated safely** with an `Idempotency-Key`. See [idempotency](/merchant-api/idempotency).
- **Calls are metered** per token, on each store on its own. See [rate limits](/merchant-api/rate-limits).
- **Events reach you** as signed webhook deliveries. See [webhooks](/merchant-api/webhooks).
- **The API grows without breaking** within `/v1`. See [versioning](/merchant-api/versioning).

## A first call

With a token in `SHERPO_TOKEN`, list the business the token belongs to and the stores it may act on:

```bash
curl 'https://api.sherpo.io/merchant/v1/merchants' \
  -H "Authorization: Bearer $SHERPO_TOKEN"
```

```js
const answer = await sherpo('GET', '/v1/merchants');
```

Answers `200`, abridged:

```json
{
  "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](/merchant-api/first-call) sets up a small JavaScript client the other examples use.

## Every endpoint

The [reference](/merchant-api/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](/merchant-api/first-call): create a token, set up a client and read your stores.
- [Products and prices](/merchant-api/guides/products-and-prices): create a product, give it a tier and a price, and publish it.
- [Upload a file](/merchant-api/guides/upload-a-file): upload a file and attach it to a product as a download.
- [Customers' access](/merchant-api/guides/customer-access): grant a customer a product, and take it back.
- [Keep orders in sync](/merchant-api/guides/sync-orders): copy your orders into your own system and keep them current.
- [Receive webhooks](/merchant-api/guides/receive-webhooks): create an endpoint, verify each delivery and act on it once.

Source: https://docs.sherpo.io/merchant-api/index.mdx
