---
title: "Products and prices"
description: "Create a product, give it a tier and a price, and publish it."
---

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

# Products and prices

A product is what you sell: a course, a membership, coaching, a download. It sells through its tiers (levels of access, such as "Full course" or "Course and coaching") and each tier's prices. This guide creates a course with one tier and one price, and publishes it. It uses the `sherpo` helper from [your first call](/merchant-api/first-call) and a token with `product:read` (for the categories), `product:write` and `price:write`.

1. **Create the product.** <a href="/merchant-api/reference/create-product/">`POST /products`</a> takes a `title` and a `category`; <a href="/merchant-api/reference/list-categories/">`GET /categories`</a> lists the categories the store may use. Its `subtitle` is the short line shown under the product's title, at most 100 characters, and its `description` the page's long [rich text](/merchant-api/rich-text), here written in Markdown. A new product is a `draft`, and its `slug` is made from the title unless you give one. Its `path` is where the storefront serves it (`/p/<slug>`), and its `url` that path on the store's verified domain, `null` while the store has none. A write answers without its `description` and `what_you_get` unless you pass `full: true`, as here to show the description stored; see [short answers](/merchant-api/requests#short-answers).

   ```bash
   curl -X POST 'https://api.sherpo.io/merchant/v1/stores/STORE_ID/products' \
     -H "Authorization: Bearer $SHERPO_TOKEN" \
     -H 'Idempotency-Key: create-watercolor-basics' \
     -H 'Content-Type: application/json' \
     -d '{
     "title": "Watercolor basics",
     "category": "course",
     "subtitle": "Paint your first landscape in six short lessons.",
     "text_format": "markdown",
     "description": "## What you learn\n\n- Mixing a palette\n- Wet on wet washes\n- **Layering** without mud",
     "listing": "primary",
     "settings": {
       "refund_policy": "14d",
       "reviews_enabled": true
     },
     "full": true
   }'
   ```

   ```js
   const answer = await sherpo('POST', '/v1/stores/STORE_ID/products', {
     body: {
       "title": "Watercolor basics",
       "category": "course",
       "subtitle": "Paint your first landscape in six short lessons.",
       "text_format": "markdown",
       "description": "## What you learn\n\n- Mixing a palette\n- Wet on wet washes\n- **Layering** without mud",
       "listing": "primary",
       "settings": {
         "refund_policy": "14d",
         "reviews_enabled": true
       },
       "full": true
     },
     key: 'create-watercolor-basics',
   });
   ```

   Answers `201`, abridged:

   ```json
   {
     "id": "6f1c2a9e-4b7d-4e2a-9c51-0d3e8b7a1f42",
     "slug": "watercolor-basics",
     "title": "Watercolor basics",
     "category": "course",
     "status": "draft",
     "description": "<rich-text version=\"1\"><h2>What you learn</h2><ul><li><p>Mixing a palette</p></li><li><p>Wet on wet washes</p></li><li><p><strong>Layering</strong> without mud</p></li></ul></rich-text>",
     "tiers": [
       {
         "id": "a1c3e5f7-0b2d-4f6a-8c9e-1d3f5b7a9c0e",
         "product_id": "6f1c2a9e-4b7d-4e2a-9c51-0d3e8b7a1f42",
         "rank": 1,
         "name": "Base"
       }
     ],
     "prices": []
   }
   ```

2. **Add a tier.** <a href="/merchant-api/reference/create-tier/">`POST /products/{product}/tiers`</a> adds a level of access beside the `Base` tier every product starts with. A product's tiers are ranked in the order they were added, and a customer's access is to a tier. A software product's tier can also list the features its licenses unlock, in `settings.software.features`, and how many devices they activate, in `settings.software.activation_limit`: see [verify licenses](/merchant-api/guides/verify-licenses#say-what-each-tier-unlocks). An event's tier is a ticket type, and `settings.event.capacity` caps how many guests it takes: see [Event](/overview/categories#event).

   ```bash
   curl -X POST 'https://api.sherpo.io/merchant/v1/stores/STORE_ID/products/6f1c2a9e-4b7d-4e2a-9c51-0d3e8b7a1f42/tiers' \
     -H "Authorization: Bearer $SHERPO_TOKEN" \
     -H 'Idempotency-Key: tier-watercolor-basics' \
     -H 'Content-Type: application/json' \
     -d '{
     "name": "Full course"
   }'
   ```

   ```js
   const answer = await sherpo('POST', '/v1/stores/STORE_ID/products/6f1c2a9e-4b7d-4e2a-9c51-0d3e8b7a1f42/tiers', {
     body: {
       "name": "Full course"
     },
     key: 'tier-watercolor-basics',
   });
   ```

   Answers `201`, abridged:

   ```json
   {
     "id": "b2d4f6a8-1c3e-4a5b-8d7f-9e0a1b2c3d4e",
     "product_id": "6f1c2a9e-4b7d-4e2a-9c51-0d3e8b7a1f42",
     "rank": 2,
     "name": "Full course"
   }
   ```

3. **Price it.** <a href="/merchant-api/reference/create-price/">`POST /products/{product}/prices`</a> adds a price to the tier: `amount` in minor units of `currency`, `one_time` or `recurring`.

   ```bash
   curl -X POST 'https://api.sherpo.io/merchant/v1/stores/STORE_ID/products/6f1c2a9e-4b7d-4e2a-9c51-0d3e8b7a1f42/prices' \
     -H "Authorization: Bearer $SHERPO_TOKEN" \
     -H 'Idempotency-Key: price-watercolor-basics-eur' \
     -H 'Content-Type: application/json' \
     -d '{
     "tier": {
       "id": "b2d4f6a8-1c3e-4a5b-8d7f-9e0a1b2c3d4e"
     },
     "currency": "eur",
     "amount": 4900,
     "kind": "one_time"
   }'
   ```

   ```js
   const answer = await sherpo('POST', '/v1/stores/STORE_ID/products/6f1c2a9e-4b7d-4e2a-9c51-0d3e8b7a1f42/prices', {
     body: {
       "tier": {
         "id": "b2d4f6a8-1c3e-4a5b-8d7f-9e0a1b2c3d4e"
       },
       "currency": "eur",
       "amount": 4900,
       "kind": "one_time"
     },
     key: 'price-watercolor-basics-eur',
   });
   ```

   Answers `201`, abridged:

   ```json
   {
     "id": "0a9b8c7d-6e5f-4a3b-9c2d-1e0f9a8b7c6d",
     "product_id": "6f1c2a9e-4b7d-4e2a-9c51-0d3e8b7a1f42",
     "tier_id": "b2d4f6a8-1c3e-4a5b-8d7f-9e0a1b2c3d4e",
     "currency": "eur",
     "exponent": 2,
     "amount": 4900,
     "kind": "one_time",
     "period": null,
     "highlighted": false
   }
   ```

   A recurring price takes a `period` (`day`, `week`, `month` or `year`, with an optional `multiplier`):

   ```bash
   curl -X POST 'https://api.sherpo.io/merchant/v1/stores/STORE_ID/products/6f1c2a9e-4b7d-4e2a-9c51-0d3e8b7a1f42/prices' \
     -H "Authorization: Bearer $SHERPO_TOKEN" \
     -H 'Idempotency-Key: price-watercolor-basics-monthly' \
     -H 'Content-Type: application/json' \
     -d '{
     "tier": {
       "id": "b2d4f6a8-1c3e-4a5b-8d7f-9e0a1b2c3d4e"
     },
     "currency": "eur",
     "amount": 900,
     "kind": "recurring",
     "period": {
       "unit": "month"
     },
     "title": "Monthly"
   }'
   ```

   ```js
   const answer = await sherpo('POST', '/v1/stores/STORE_ID/products/6f1c2a9e-4b7d-4e2a-9c51-0d3e8b7a1f42/prices', {
     body: {
       "tier": {
         "id": "b2d4f6a8-1c3e-4a5b-8d7f-9e0a1b2c3d4e"
       },
       "currency": "eur",
       "amount": 900,
       "kind": "recurring",
       "period": {
         "unit": "month"
       },
       "title": "Monthly"
     },
     key: 'price-watercolor-basics-monthly',
   });
   ```

4. **Publish it.** <a href="/merchant-api/reference/publish-product/">`POST /products/{product}/publish`</a> puts it on sale now:

   ```bash
   curl -X POST 'https://api.sherpo.io/merchant/v1/stores/STORE_ID/products/6f1c2a9e-4b7d-4e2a-9c51-0d3e8b7a1f42/publish' \
     -H "Authorization: Bearer $SHERPO_TOKEN" \
     -H 'Idempotency-Key: publish-watercolor-basics'
   ```

   ```js
   const answer = await sherpo('POST', '/v1/stores/STORE_ID/products/6f1c2a9e-4b7d-4e2a-9c51-0d3e8b7a1f42/publish', {
     key: 'publish-watercolor-basics',
   });
   ```

   Answers `200`, abridged:

   ```json
   {
     "id": "6f1c2a9e-4b7d-4e2a-9c51-0d3e8b7a1f42",
     "status": "published",
     "published_at": "2026-11-03T10:00:00.000Z"
   }
   ```

   or at a later time, with `at`. A product may also be named by its slug:

   ```bash
   curl -X POST 'https://api.sherpo.io/merchant/v1/stores/STORE_ID/products/slug:watercolor-basics/publish' \
     -H "Authorization: Bearer $SHERPO_TOKEN" \
     -H 'Content-Type: application/json' \
     -d '{
     "at": "2026-12-01T08:00:00Z"
   }'
   ```

   ```js
   const answer = await sherpo('POST', '/v1/stores/STORE_ID/products/slug:watercolor-basics/publish', {
     body: {
       "at": "2026-12-01T08:00:00Z"
     },
   });
   ```

## Then

- Publishing a product that is already published answers `409` [`conflict`](/merchant-api/errors#conflict) with `context.current: "published"`; the other moves (<a href="/merchant-api/reference/unpublish-product/">unpublish</a>, <a href="/merchant-api/reference/discontinue-product/">discontinue</a>, <a href="/merchant-api/reference/unlist-product/">unlist</a>) say the same when the product isn't where they expect.
- <a href="/merchant-api/reference/product-summaries/">`GET /products/summaries`</a> names up to 100 products by id in one read, each with its `status` now (`draft`, `scheduled`, `published` or `discontinued`) and whether it is `deleted`; a deleted product keeps its title there, but its `status` tells nothing.
- <a href="/merchant-api/reference/update-product/">`PATCH /products/{product}`</a> changes its title, texts, listing and settings; its slug and category are fixed at creation.
- Its lessons and articles are entries: <a href="/merchant-api/reference/create-entry/">`POST /products/{product}/entries`</a>. An entry is signed by its `author`: a team member (`{ "kind": "member", "user": { "id": "..." } }`, someone holding a seat on the business now), the business (`{ "kind": "business" }`), the store (`{ "kind": "store" }`) or nobody (`null`). A new entry is signed by the member whose token creates it unless you name another author. An entry may also hold `tags` its product's lists filter by (visible text with no comma, its words parted by single spaces), which are a blog's categories, and be `unlisted`: it still opens at its address, but stays out of the product's lists, the sitemap, progress and notifications, and relisting it sends none. <a href="/merchant-api/reference/list-entry-tags/">`GET /products/{product}/entries/tags`</a> and <a href="/merchant-api/reference/list-entry-sections/">`GET /products/{product}/entries/sections`</a> page the distinct tags and sections its entries hold, each with how many entries hold it, drafts included, from values kept as entries change, so they never read every entry. Its page's layout is its body: <a href="/merchant-api/reference/set-body/">`PUT /{kind}/{id}/body`</a> writes it live, or with `staged: true` writes the unpublished next one, which <a href="/merchant-api/reference/publish-body/">`POST /{kind}/{id}/body/publish`</a> publishes. Until it has one, its page shows a default layout by category: <a href="/merchant-api/reference/read-body/">`GET /{kind}/{id}/body`</a> answers it, and whether the page shows the product's `description` and `what_you_get` (see [layouts](/merchant-api/rich-text#layouts)).
- An entry goes live with <a href="/merchant-api/reference/publish-entry/">`POST /products/{product}/entries/{entry}/publish`</a>. Published now, a series episode needs its `poster` and a video among its `embed` files, and a podcast episode its own audio: an `embed` audio file its text doesn't play (no poster needed). One missing is refused `409` [`conflict`](/merchant-api/errors#conflict) with `context.field` naming it (`poster`, `video` or `audio`), and so is a change that takes it from a live one; a scheduled publish waits for it.
- Its download: [upload a file](/merchant-api/guides/upload-a-file).
- Many products at once: [bulk changes](/merchant-api/bulk).

Source: https://docs.sherpo.io/merchant-api/guides/products-and-prices/index.mdx
