---
title: "Categories"
description: "The eleven kinds of product a store sells, from courses and files to software, events, portfolios, blogs and podcasts, and what each one holds."
---

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

# Categories

Every [product](/overview/concepts#products) 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](/merchant-api/reference/list-categories) endpoint of the merchant API:

```sh
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 <a href="/merchant-api/reference/list-product-questions/">list</a>, <a href="/merchant-api/reference/create-product-question/">add</a>, <a href="/merchant-api/reference/update-product-question/">change</a> and <a href="/merchant-api/reference/delete-product-question/">remove</a> them: see [Ask buyers questions](/merchant-api/guides/registration-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](/merchant-api/guides/approvals-and-waitlists).

## 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](/overview/concepts#tiers-and-prices), 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](/overview/concepts#tiers-and-prices) 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](/overview/licenses) for how a license follows access, and [Migrate from Gumroad](/merchant-api/guides/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](/merchant-app/content#calendar), 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](/overview/concepts#tiers-and-prices) 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](/overview/migrate-from-luma).

Its `event` settings hold:

- `format`: `in_person`, `online` or `hybrid` (in person when left out);
- `location`: where an in-person event takes place, as `venue`, `address`, `city`, `region`, `postal_code`, `country` (an upper case ISO 3166-1 alpha-2 code, such as `IT`), `latitude` and `longitude` (decimal degrees, set together) and `map_url` (an `https` link to a map);
- `reveal_location`: `everyone`, or `holders` to show the location only to people holding a ticket;
- `waitlist`: `true` to 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](/customer-api/checkout) 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`](/customer-api/errors#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](/merchant-api/guides/sync-orders) 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 <a href="/merchant-api/reference/list-event-sessions/">list</a>, <a href="/merchant-api/reference/create-event-session/">add</a>, <a href="/merchant-api/reference/update-event-session/">move</a> and <a href="/merchant-api/reference/delete-event-session/">remove</a> 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](/customer-api/feeds#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](/merchant-api/guides/cancel-an-event). A guest whose request waits for your [approval](#requiring-approval) is `pending`, and one on the waitlist is `waitlisted`. The merchant API and MCP server <a href="/merchant-api/reference/list-event-attendees/">list</a> and <a href="/merchant-api/reference/event-attendee-stats/">count</a> it against the event's capacity: see [Read an event's guest list](/merchant-api/guides/event-guest-lists).

### 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](/merchant-api/guides/approvals-and-waitlists#run-an-events-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](/customer-api/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](/merchant-api/guides/event-check-in). A check-in can run [automations](/merchant-api/guides/event-check-in#automations-on-check-in), once per guest, and on Pro and Sherpo One issues the event's [certificates of attendance](/merchant-api/guides/event-check-in#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 <a href="/merchant-api/reference/create-entry/">create</a> or <a href="/merchant-api/reference/update-entry/">update</a> 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](/overview/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](/merchant-app/ai#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](/overview/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 `notify` to notify everyone with access, in their notifications and in their browser ([Notifications](/customer-api/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](/merchant-api/reference/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](/customer-api/reference/get-portfolio), [list portfolio events](/customer-api/reference/list-portfolio-events), [list portfolio snapshots](/customer-api/reference/list-portfolio-snapshots) and [get portfolio valuation](/customer-api/reference/get-portfolio-valuation).

```sh title="Record a buy"
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 10<sup>8</sup>, 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`.

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