Skip to content

Concepts

How accounts, businesses, stores, products, customers and sales fit together, and how the apps and APIs name them.

Updated

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.

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 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.
  • 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 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.
  • 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 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, and can connect their own AI to it through the customer MCP server.

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 Your own scripts and tools, as a member of the business. An API token, Authorization: Bearer ucn_..., made in the merchant app.
Merchant MCP Your AI, working on your stores. You sign in and approve access when your AI connects.
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 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.

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 lists them all.

{
  "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:

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.

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.

Type to search…

↑↓ navigate↵ selectEsc close