Skip to content

Products and prices

Create a product, give it a tier and a price, and publish it.

Updated

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 and a token with product:read (for the categories), product:write and price:write.

  1. Create the product. POST /products takes a title and a category; GET /categories 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, 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.

    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
    }'
    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:

    {
      "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. POST /products/{product}/tiers 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. An event’s tier is a ticket type, and settings.event.capacity caps how many guests it takes: see Event.

    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"
    }'
    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:

    {
      "id": "b2d4f6a8-1c3e-4a5b-8d7f-9e0a1b2c3d4e",
      "product_id": "6f1c2a9e-4b7d-4e2a-9c51-0d3e8b7a1f42",
      "rank": 2,
      "name": "Full course"
    }
  3. Price it. POST /products/{product}/prices adds a price to the tier: amount in minor units of currency, one_time or recurring.

    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"
    }'
    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:

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

    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"
    }'
    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. POST /products/{product}/publish puts it on sale now:

    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'
    const answer = await sherpo('POST', '/v1/stores/STORE_ID/products/6f1c2a9e-4b7d-4e2a-9c51-0d3e8b7a1f42/publish', {
      key: 'publish-watercolor-basics',
    });

    Answers 200, abridged:

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

    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"
    }'
    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 with context.current: "published"; the other moves (unpublish, discontinue, unlist) say the same when the product isn’t where they expect.
  • GET /products/summaries 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.
  • PATCH /products/{product} changes its title, texts, listing and settings; its slug and category are fixed at creation.
  • Its lessons and articles are entries: POST /products/{product}/entries. 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. GET /products/{product}/entries/tags and GET /products/{product}/entries/sections 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: PUT /{kind}/{id}/body writes it live, or with staged: true writes the unpublished next one, which POST /{kind}/{id}/body/publish publishes. Until it has one, its page shows a default layout by category: GET /{kind}/{id}/body answers it, and whether the page shows the product’s description and what_you_get (see layouts).
  • An entry goes live with POST /products/{product}/entries/{entry}/publish. 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 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.
  • Many products at once: bulk changes.

Type to search…

↑↓ navigate↵ selectEsc close