---
title: "Your first call"
description: "Create an API token, set up a small client and read the stores your token reaches."
---

> 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.

# Your first call

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](/merchant-api/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:

   ```bash
   export SHERPO_TOKEN='ucn_...'
   ```

3. **Make a call.** List the businesses the token reaches 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
   }
   ```

   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](/merchant-api/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](/merchant-api/errors) 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`):

```js
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:

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

## Next

- Read a list a page at a time: [pagination](/merchant-api/pagination).
- Create something: [products and prices](/merchant-api/guides/products-and-prices).
- Hear about what happens: [receive webhooks](/merchant-api/guides/receive-webhooks).
- Any other call: the [reference](/merchant-api/reference).

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