Skip to content

Your first call

Create an API token, set up a small client and read the stores your token reaches.

Updated

This guide takes you from no token to a working client in a few minutes. The other guides build on the client it sets up.

  1. Create a token. In the merchant app, open Account settings, then API tokens, and choose New token. Name it after what will use it, pick how long it works, the businesses and stores it reaches and what it may do in each, then copy it: it is shown once. Authentication explains each choice.

  2. Keep it out of your code. Put it in an environment variable, a secret store or your platform’s secrets, never in a repository:

    export SHERPO_TOKEN='ucn_...'
  3. Make a call. List the businesses the token reaches 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
    }

    Each store’s id is the {store} every store path takes. An account token may always make this call, whatever access you gave it, so it can find where it works; an older utk_ token not yet listed with your account tokens needs organization:read (see scopes).

A small client

The JavaScript examples in these docs call a helper, sherpo, that adds the token, sends JSON, passes an Idempotency-Key when you give one, and throws the API’s problem on a failure. It runs on Node 20 and later, Deno, Bun and Workers (where you read the token from your environment instead of process.env):

const BASE = 'https://api.sherpo.io/merchant';
const TOKEN = process.env.SHERPO_TOKEN;

// Calls the merchant API: answers the parsed JSON, or throws the problem it answered.
async function sherpo(method, path, { query = [], body, key } = {}) {
  const url = new URL(BASE + path);
  url.search = new URLSearchParams(query).toString();
  const headers = { Authorization: `Bearer ${TOKEN}` };
  if (body !== undefined) headers['Content-Type'] = 'application/json';
  if (key !== undefined) headers['Idempotency-Key'] = key;
  const response = await fetch(url, {
    method,
    headers,
    body: body === undefined ? undefined : JSON.stringify(body),
  });
  if (response.status === 204) return null;
  if (response.ok) return response.json();
  const problem = await response.json().catch(() => ({}));
  const error = new Error(problem.detail ?? `The API answered ${response.status}.`);
  error.status = response.status;
  error.problem = problem;
  error.retryAfter = Number(response.headers.get('Retry-After') ?? NaN);
  throw error;
}

query takes pairs, so a parameter can repeat ([['filter[status][in]', 'draft'], ['filter[status][in]', 'scheduled']]). With it, the call above is:

const { items } = await sherpo('GET', '/v1/merchants');
const store = items[0].stores.items[0].id;

Next

Type to search…

↑↓ navigate↵ selectEsc close