---
title: "Concepts"
description: "How accounts, businesses, stores, products, customers and sales fit together, and how the apps and APIs name them."
---

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

# Concepts

Everything in Sherpo hangs off a business. A business has its stores, its team, its plan and its payouts; each store has its own products, pages, customers and sales.

```txt
Your account
└── Business: plan, payouts, members, API tokens
    └── Store: address, settings, website
        ├── Products: tiers, prices, entries
        ├── Pages
        ├── Customers: orders, subscriptions, reviews
        └── Discounts
```

## Your account

You sign in to the merchant app with your email, by a code we send you, or with Google. One account can belong to several businesses, each with its own access. Your customers never need a Sherpo account: they sign in to your store.

## Business

A business is who sells. It holds:

- **Its stores**, as many as its [plan](/overview/plans) pays for.
- **Its plan**, billed per store, and its usage across stores.
- **Its payouts**: one Stripe account in the business's name that every store's sales go to. See [Payments and payouts](/overview/payments).
- **Its members** and their access, and the API tokens and AI connections they make.
- Its name, short name and logo.

In the APIs and MCP servers, the business is the `organization`, and its scopes are `organization:read` and `organization:write`.

### Members and access

One member is the business's owner, who can hand it over to another member. Every member, the owner included, has a seat with its access to the business. There are no fixed roles: a seat is either full access or a set of scopes, each a domain and an action such as `product:read` or `customer:write`, and an action that can't be undone needs `:delete`. Only members with full access can choose or change the plan, set up payouts and open Stripe. Lite seats one member; Pro seats up to 200.

The scopes are: `affiliate`, `apitoken`, `attendee` (only `attendee:checkin`), `automation`, `certificate`, `client`, `custompage`, `customer`, `discount`, `entry`, `file`, `integration`, `member`, `organization`, `portfolio`, `price`, `product`, `quiz`, `revenue`, `review` (also `review:moderate`), `site`, `subscription`, `transaction` and `user`. Each endpoint of the [merchant API reference](/merchant-api/reference) names the scope it needs.

## Stores

A store is what customers see: a website with its products, at its own address. A store has:

- **A name**, an icon and a description.
- **An address**: its Sherpo address, and on Pro its own domain. See [Store address and custom domains](/overview/domains).
- **Settings**: its language, time zone, currency, refund rules, theme and what customers are emailed about.
- **A website**: its homepage, custom pages on Pro, menu and redirects.

The merchant API names a store by its ID (`/v1/stores/{store}`, where `{store}` is the ID); the customer API and the customer MCP server name it by one of its hostnames, such as `your-store.sherpo.io`.

## Products

A product is anything a store sells: a course, files, software, calls, an event, a series, a blog, a podcast, a portfolio, thank-yous or a goal. Its [category](/overview/categories) decides what it holds. Each product has a title, a `slug` for its address in the store, a description, and a status:

| Status | Meaning |
| --- | --- |
| `draft` | Not published yet. |
| `scheduled` | Published from a date still to come. |
| `published` | On sale and in the store. |
| `discontinued` | No longer sold. Customers who have it keep it. |

A product can also be **unlisted**: on sale to anyone with its link, but left out of the store's lists, search and feeds.

### Tiers and prices

A product's **tiers** are its levels of access, ranked, such as Basic and Premium. A higher tier includes what a lower one unlocks, so a customer moving up is an upgrade.

Each tier has one or more **prices**, each in one currency, such as a monthly and a yearly price in US dollars:

- **One-time**, paid once for access that lasts.
- **Recurring**, a subscription billed every day, week, month or year, or a multiple of one, until the customer cancels.

A price can have its own refund policy, and a recurring one a discount on renewals.

### Entries

A course, a series, a blog, a podcast or an event holds **entries**: its lessons, episodes, posts or an event's pages, such as its stream and recordings. Each entry is a page of the product, with a body of text, video, files and embeds, and its own `slug`. A course groups its lessons in sections.

### Addresses

Every product, entry and page read the APIs and MCP servers answer carries its `path` on the store, such as `/p/watercolor-basics` for a product and `/p/watercolor-basics/first-strokes` for one of its lessons, and its `url`: the same path on the store's verified domain, or `null` while the store has none. A product an order, subscription, grant, certificate or webhook event names carries them too, both `null` once the product is deleted. Link to these rather than building an address from a `slug`.

### Access

What a customer can open is decided by what they hold: a purchase, a subscription, or access you grant them. You can gate a product, an entry, a page or a file to some tiers, and decide whether it's open on the web, through the APIs, through the MCP servers or in feeds.

## Pages

A store's website has its homepage and, on Pro, up to 30 custom pages, each built from blocks such as images, video, product cards, pricing tables and FAQs. Up to four pages sit in the store's menu.

## Customers

A customer belongs to one store: someone who signed up, bought or subscribed there. The same person in two of your stores is two customers, each with what they hold in that store. Customers sign in to your store, never to Sherpo, with a code by email, Google or a [passkey](/overview/passkeys), and can connect their own AI to it through the [customer MCP server](/customer-mcp).

## Sales

- **Orders** record each purchase, with a number per store, its items, what was paid and any refunds.
- **Subscriptions** follow each recurring price a customer pays, through renewals, upgrades, cancellations and resumes.
- **Discounts** take an amount or a percentage off, for the whole store, a product, a tier or a price, optionally limited in uses or to some customers, and can pay an affiliate a commission.
- **Reviews** rate a product from 1 to 5, with your reply.

## Reaching your store from code

The same store is reachable four ways, each with its own credentials:

| Surface | For | Credentials |
| --- | --- | --- |
| [Merchant API](/merchant-api) | Your own scripts and tools, as a member of the business. | An API token, `Authorization: Bearer ucn_...`, made in the merchant app. |
| [Merchant MCP](/merchant-mcp) | Your AI, working on your stores. | You sign in and approve access when your AI connects. |
| [Customer API](/customer-api) | Your own website or app in front of the store, on Pro. | A customer's token, `Authorization: Bearer ctk_...`, from the store's sign-in, or the store's publishable key. |
| [Customer MCP](/customer-mcp) | Your customers' AI, reaching what they bought. | The customer signs in to your store and approves access. |

### Listing a store's products

With the merchant API, as a member with `product:read`:

Filters go in brackets, so `curl` needs `-g` to send them as they are.

```sh
curl -g "https://api.sherpo.io/merchant/v1/stores/$STORE_ID/products?filter[status]=published&limit=2" \
  -H "Authorization: Bearer $SHERPO_TOKEN"
```

The answer is a page of products, with a `cursor` for the next page while there is one. Each product here is cut to a few of its fields; [list products](/merchant-api/reference/list-products) lists them all.

```json
{
  "items": [
    {
      "id": "7c1e2a6b-3f0d-4c8e-9a51-2b6d0e4f8a13",
      "slug": "watercolor-basics",
      "title": "Watercolor basics",
      "category": "course",
      "listing": "primary",
      "status": "published",
      "unlisted": false,
      "published_at": "2026-09-14T08:00:00.000Z",
      "sales": 128,
      "rating": { "count": 23, "average": 4.8 }
    }
  ],
  "cursor": "eyJvIjoyfQ"
}
```

With the customer API, the same store's catalog as a visitor sees it, read with its publishable key:

```sh
curl "https://api.sherpo.io/customer/v1/stores/your-store.sherpo.io/products" \
  -H "Publishable-Key: $PUBLISHABLE_KEY"
```

Each product there carries what a customer needs: its `offers` with their prices, its `access` (`locked` or `unlocked`) and, once signed in, what the customer `owned`. See [list products](/customer-api/reference/list-products).

A failed call answers a problem document (`application/problem+json`) with a `type` and a `status`, and the merchant API's writes that list an `Idempotency-Key` header in the reference take one, so a retry within 24 hours answers the first result instead of acting twice.

Source: https://docs.sherpo.io/overview/concepts/index.mdx
