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.
-
Create the product.
POST /productstakes atitleand acategory;GET /categorieslists the categories the store may use. Itssubtitleis the short line shown under the product’s title, at most 100 characters, and itsdescriptionthe page’s long rich text, here written in Markdown. A new product is adraft, and itsslugis made from the title unless you give one. Itspathis where the storefront serves it (/p/<slug>), and itsurlthat path on the store’s verified domain,nullwhile the store has none. A write answers without itsdescriptionandwhat_you_getunless you passfull: 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": [] } -
Add a tier.
POST /products/{product}/tiersadds a level of access beside theBasetier 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, insettings.software.features, and how many devices they activate, insettings.software.activation_limit: see verify licenses. An event’s tier is a ticket type, andsettings.event.capacitycaps 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" } -
Price it.
POST /products/{product}/pricesadds a price to the tier:amountin minor units ofcurrency,one_timeorrecurring.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,monthoryear, with an optionalmultiplier):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', }); -
Publish it.
POST /products/{product}/publishputs 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
409conflictwithcontext.current: "published"; the other moves (unpublish, discontinue, unlist) say the same when the product isn’t where they expect. GET /products/summariesnames up to 100 products by id in one read, each with itsstatusnow (draft,scheduled,publishedordiscontinued) and whether it isdeleted; a deleted product keeps its title there, but itsstatustells 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 itsauthor: 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 holdtagsits product’s lists filter by (visible text with no comma, its words parted by single spaces), which are a blog’s categories, and beunlisted: 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/tagsandGET /products/{product}/entries/sectionspage 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}/bodywrites it live, or withstaged: truewrites the unpublished next one, whichPOST /{kind}/{id}/body/publishpublishes. Until it has one, its page shows a default layout by category:GET /{kind}/{id}/bodyanswers it, and whether the page shows the product’sdescriptionandwhat_you_get(see layouts). - An entry goes live with
POST /products/{product}/entries/{entry}/publish. Published now, a series episode needs itsposterand a video among itsembedfiles, and a podcast episode its own audio: anembedaudio file its text doesn’t play (no poster needed). One missing is refused409conflictwithcontext.fieldnaming it (poster,videooraudio), 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.