Every product has a category, picked when you create it, that decides what it holds and how people use it. The category can’t be changed later.
| Category | ID | What people get |
|---|---|---|
| Course | course |
Lessons people take at their own pace. |
| Files | files |
Downloads people keep, such as e-books, templates or presets. |
| Software | software |
Apps, plugins and tools people activate with a license. |
| Calendar | calendar |
Calls and appointments people book on your availability. |
| Event | event |
Gatherings at set times, in person, online or both, with tickets. |
| Series | series |
Episodes people catch up on as you release them. |
| Blog | blog |
Posts and articles people read as you publish them. |
| Podcast | podcast |
Episodes people listen to as you release them, on your store or in their podcast app. |
| Portfolio | portfolio |
Holdings and trades people follow as you invest. |
| Coffee | coffee |
Thank-yous people send for your work. |
| Goals | fundraising |
A goal people help you reach, step by step. |
The ID is what the APIs and MCP servers use, in a product’s category and in filters such as filter[category]=course.
What each category allows
A category also sets what its products can do: whether they can have recurring prices, take discounts, collect reviews, or be bought again and again (a coffee, a contribution to a goal). The merchant app shows these as you pick one, such as “one-off prices only” or “no reviews”.
Which categories a store can sell in, and what each allows, is in the list categories endpoint of the merchant API:
curl "https://api.sherpo.io/merchant/v1/stores/$STORE_ID/categories" \
-H "Authorization: Bearer $SHERPO_TOKEN"Each item carries id, label, enabled (whether this store can create products in it), and subscribable, discountable, reviewable and repeatable.
Whatever the category, a product can ask its buyers questions in checkout, before payment: a text (checked against a pattern if you set one), a choice of options or a box to tick, each required or not, including standard details such as a phone number, up to 20. None is asked unless you add it. The merchant API and MCP server list, add, change and remove them: see Ask buyers questions.
Requiring approval
A product of any category can require your approval: its settings.approval is none (the default) or required. A buyer’s get of it then waits as a request you approve or decline, and they hold the product only once you approve. A product that requires approval sells one-time prices only; at a paid one, checkout saves the buyer’s card and your approval charges it. An event keeps a buyer’s seats while their request waits. See Approve requests and run a waitlist.
Course
A course holds lessons, grouped in sections you order. Each lesson is a page of the product: a body of text, video, files and embeds, with a teaser people see before they buy, and lessons you mark as previews open to everyone. Customers mark lessons complete, or the course does it as they open or finish one, and on Pro a lesson can carry quizzes, with a certificate at the end.
Files
A files product delivers downloads and links: what people buy is what they keep. Each file can be limited to a tier, so a higher tier unlocks more of them.
Software
A software product sells a license to your app, plugin or tool: every customer who holds it gets a license key your software checks, and it sells once or on a recurring price. Files are optional: attach them when people download your software from your store, each one limited to a tier if you like, or leave them out when they get it from an app store or your own site. Its software settings hold key_prefix, the letters and digits its license keys start with (up to 16, with single hyphens or underscores between them), and activation_limit, how many devices a license is activated on at once by default (1 to 10,000; left out, there is no limit).
Each customer holding a software product has one license key for it, valid as long as their access. They find it in their library, on the product’s page and on their order page, and in the access granted and subscription started emails. From the library and the product’s page they see the devices it activates, free one to make room for another, and get a new key when theirs leaks, which stops the old key at once. See Licenses for how a license follows access, and Migrate from Gumroad to bring keys you sold there.
Its activity is the product’s own feed of releases and notes, newest first, which holders read on its page and in their library. A release names its version, what changed and its files, which become the current download: older versions leave the product’s downloads and stay in their own release, and a release without files leaves the download as it is. It can be limited to a tier, which limits its files, and it can tell holders who can download it with a push notification, once. A note is your own update; holders read it and don’t reply. Through the API and MCP, the activity is at /products/{product}/activity.
Calendar
A calendar product sells calls and appointments booked on your availability through your Cal.com event: you set its username and event, and a host card shows who people meet. The API and the MCP tools check the username, the event and the host card against the merchant app’s limits, and take the username and the event only together. The host card’s identity names a teammate ({ "kind": "member", "user": { "id": "..." } }), the business or the store by id, and customers see that party’s current name as the card’s title; a typed title and an identity replace each other.
Only someone who may open the product books it. Everyone who reads it sees settings.calendar.can_schedule, whether it books through a Cal.com event, but only someone holding it reads the username and the event in settings.calendar.calcom, as does anyone when its gate opens it to everyone, or through a preview link of the product. Anyone else gets it first: while it’s on sale and your store takes new unlocks, its Schedule button leads them to checkout, a free call included. Cal.com still books whoever reaches its own page, so a call you sell is safest on a hidden Cal.com event that asks for your confirmation.
Event
An event is a gathering at set times that people buy tickets for: a workshop, a meetup, a conference, a live class. Its tiers are its ticket types, and a higher tier holds what a lower one does, so an in-person ticket can include what an online one gets. It sells once or on a recurring price. Someone buying several tickets at a one-time price names a guest for each one past their own (or for every one), and each guest gets a ticket, an email and a place on the guest list of their own. To bring events you run on Luma, see Migrate from Luma.
Its event settings hold:
format:in_person,onlineorhybrid(in person when left out);location: where an in-person event takes place, asvenue,address,city,region,postal_code,country(an upper case ISO 3166-1 alpha-2 code, such asIT),latitudeandlongitude(decimal degrees, set together) andmap_url(anhttpslink to a map);reveal_location:everyone, orholdersto show the location only to people holding a ticket;waitlist:trueto let guests join a waitlist for a free ticket once the seats they ask for are gone;capacity: how many guests it takes in all, 1 to 1,000,000 (left out, there is no limit).
A tier’s own event settings take capacity too: how many guests that ticket type takes, 1 to 1,000,000, within the event’s. A guest counts once per ticket, so a line of three tickets takes three seats.
A checkout never takes an event past its capacity. A cart frozen for payment holds its seats until it’s paid or closes, and a cart that would take more seats than are left is refused, when a line is added and again when it freezes, as 409 conflict on items with current the fewest seats left. A purchase takes a seat of its ticket type and of the event; an upgrade takes a seat of its new ticket type alone, since the guest already holds one of the event’s, and frees the seat they bought on the type they leave once paid (a guest who got their ticket as a grant frees none), and a renewal takes none. An order you record takes its seats even past capacity, as the sale already happened; a grant you give takes none. A refund that ends a ticket frees its seat: a guest’s ticket named in the refund, or a whole payment’s when refunds remove access. Any other refund keeps it, so raise the capacity to sell it again. A cart that closed and gave its seats back, then is paid anyway, still sells them, even past capacity, since the money came.
Its schedule is a list of sessions, one for a single evening or several for a series or a multi-day event, up to 100. Each session has its starts_at and ends_at, the time_zone it’s shown in (an IANA name, such as Europe/Rome), and where it happens: a venue in person, an online_label online (a label everyone sees, such as Zoom, never the join link), or both. The merchant API and MCP server list, add, move and remove them under the product.
A product’s page reads its event: the format, the settings above and every session, earliest first, with spots_left (null when nothing limits it), sold_out, and each ticket type’s capacity, spots_left and sold_out in tickets, a ticket type never reading more than the event has left. The merchant API’s product, and each row of its product list, answers the same as seats, with what frozen carts held and orders sold (null for any other category). With reveal_location set to holders, someone without a ticket reads only the location’s city, region and country (none at all when those are empty), each session’s venue as null, and location_hidden as true. The store’s product lists carry each event’s format, place, map, capacity, spots_left, sold_out and next five sessions, so a listing shows its dates without opening every event.
Once its last session has ended, an event stops selling: its page, the API and the MCP server offer no tickets, and a checkout refuses them. An event with no sessions yet keeps selling.
An in-person or hybrid event whose location has a latitude and longitude gets a map of the venue, drawn by Sherpo from OpenStreetMap data a short while after you set or move the point: event.map holds a light and a dark image, each with its url, width, height and smaller sizes (resized), centred on the point with no pin, so your page draws its own in your store’s color. Show attribution over the map, linking attribution_url. It’s null until the map is drawn, while the location is hidden, and for an online event. The merchant API’s product, and each row of its product list, carries the same as event_map, whoever the location is shown to. A list row on the storefront carries event.map only while the location is shown to everyone.
Every event has an iCalendar file of its sessions, each session has links that add it to Google Calendar and Outlook, the store has a schedule of its listed events, and a ticket holder can get a private calendar feed that carries the location: see Events. Its feeds settings take private alone, which turns those private calendar feeds off.
Guest list
Everyone who gets a ticket is on the event’s guest list once, going while a ticket holds and canceled once none does, with why: refunded, revoked, expired, declined, or canceled when you cancel the event. A guest whose request waits for your approval is pending, and one on the waitlist is waitlisted. The merchant API and MCP server list and count it against the event’s capacity: see Read an event’s guest list.
Waitlist
With waitlist on, a guest who asks for a one-time ticket once the seats they ask for are gone joins the event’s waitlist instead, holding no seat. Once seats free, you promote them: an order takes their seats and they’re granted a free ticket at once, or a paid one once their saved card is charged or they pay for it. See Run an event’s waitlist.
On the store, each guest finds their ticket on the event’s card in their library: Ticket opens its QR code and the code under it to read out at the door, with their ticket type and the session’s time and place. Once they’re checked in at the event’s last session the code greys out as Checked in; with a later session still to come it stays scannable, marked with the time they were let in today. A canceled ticket shows why (refunded, revoked or expired) instead of a code. Your own front end reads the same ticket: see Event tickets.
Check-in and certificates
At the door, guests are checked in at each session by their ticket’s code, and online guests from the guest list: see Check attendees in at the door. A check-in can run automations, once per guest, and on Pro and Sherpo One issues the event’s certificates of attendance: one check-in at any session is attendance. Undoing a guest’s last check-in takes back the certificate it issued, until they’re checked in again.
Entries and timed release
An online or hybrid event gives its guests access through its entries: a page for the stream (an embedded live video or a meeting link), notes, files, and recordings afterwards. There is no streaming of its own: a stream goes in an entry as an embed.
An entry can open relative to one of the event’s sessions: its release names the session, the anchor it counts from (start or end) and offset_minutes (negative before the anchor, within 30 days either way). The Join entry might open 15 minutes before the start (start, -15), and a recording an hour after the end (end, 60). The moment follows the session, so moving the session moves it, though an entry that has opened stays open wherever the session goes (its released_at says since when a later release no longer locks it); release: null opens the entry as soon as it’s published, and a release you set again after that counts afresh. Set it when you create or update the entry. A session an entry opens relative to can’t be removed until the entry lets go of it.
Until that moment the entry is listed, with its title, subtitle, abstract, preview and poster, but its body, files and quiz stay locked to everyone, ticket holders included, and so do preview links you share, and its read answers opens_at, the moment it opens. Keep the join link in the body, never the subtitle, the abstract or the preview, which everyone can read. Once it opens, the entry is gated by its tiers as any other, and it never locks again, even when you unpublish it or the event for a while, unless you clear its release and set a new one. An entry that hasn’t opened still counts toward completing the event.
Series
A series holds episodes you release over time. People catch up on what’s out and follow along as you publish more, often on a recurring price.
Blog
A blog holds posts, listed by the date you publish them, with no sections. Each post is a page of the product, like a lesson. Sell it on a recurring price for a paid newsletter or publication, or keep some posts free with previews.
People follow a blog in their feed reader: its public RSS feed lists up to the 50 newest posts with their abstracts, and each customer who holds it can get a private feed carrying the newest posts they may read in full. See Feeds.
Podcast
A podcast holds episodes, listed newest first like a blog’s posts. Each episode leads with its audio, with square artwork beside it, and can carry a body, files and, on Pro and Sherpo One, a transcript and chapters made with AI for media. Listeners pick up where they stopped on any device. Keep some episodes free, and sell the rest once, on a recurring price or inside a tier.
People listen on your store or in their podcast app, such as Apple Podcasts, Spotify, Overcast or Pocket Casts: a podcast’s public feed, with the episodes anyone may listen to, is what you submit to directories, and each customer who holds it can get a private feed of their own. See Feeds.
Portfolio
A portfolio product sells access to an investment portfolio you run and record in Sherpo. Its subscribers follow:
- Holdings: each stock or crypto position, with its shares, value and your note.
- Events: every buy, sell, dividend, deposit and withdrawal, plus comments, the symbols you watch or stop watching, and files you attach to a holding. Record a trade with
notifyto notify everyone with access, in their notifications and in their browser (Notifications). - Snapshots: the portfolio’s value, cash and return for each trading day, measured against the S&P 500, the Nasdaq, ACWI and gold.
- Valuation: what the holdings are worth now, at the latest prices.
You record events in the merchant app, through the record portfolio event endpoint, or with your AI through the merchant MCP server. Customers and your own front end read them through the customer API: get portfolio, list portfolio events, list portfolio snapshots and get portfolio valuation.
curl -X POST "https://api.sherpo.io/merchant/v1/stores/$STORE_ID/products/$PRODUCT_ID/portfolio/events" \
-H "Authorization: Bearer $SHERPO_TOKEN" \
-H "Content-Type: application/json" \
-d '{ "type": "buy", "symbol": "AAPL", "symbol_type": "stock", "shares": 1000000000 }'Shares are scaled by 108, so 1000000000 is 10 shares. Left out, the price is the symbol’s latest quote.
Coffee
A coffee product takes thank-yous, which people send as often as they like. You set its emoji and what each one is called, such as “a coffee”.
Goals
A goal raises money toward a target you set, in a currency of its own, and shows how much is raised as people contribute. Its ID is fundraising.