A storefront reads everything with the store’s publishable key, so a visitor sees it before signing in. Once a customer signs in, send their token instead: the same reads then add what that customer holds, such as their tier of a product and the lessons it unlocks. The examples use the client from Your own front end.
The store
GET /v1/stores/{store} reads the store’s name, branding and settings, for your header, footer and page titles.
curl 'https://api.sherpo.io/customer/v1/stores/yourstore.sherpo.io' \
--header 'Publishable-Key: <publishable key>'{
"id": "<store id>",
"name": "Your Store",
"locale": "en",
"hostname": "yourstore.sherpo.io",
"served_hostname": "yourstore.sherpo.io",
"served_hostnames": ["yourstore.sherpo.io"],
"unlocks_paused": false,
"description": "Courses for curious people.",
"tint": "#047857",
"tint_dark": "#34d399",
"icon": "<icon URL>",
"favicon": "<favicon URL>",
"settings": {
"storefront": {
"external_site": "https://www.example.com",
"socials": ["https://www.instagram.com/yourstore"],
"theme": "both",
"no_index": false,
"powered_by": true,
"animated_background": false,
"header_hidden": false,
"footer_hidden": false
}
},
"currencies": { "eur": 2, "jpy": 0, "usd": 2 }
}tintandtint_darkare the store’s accent colors in light and dark mode;settings.storefront.themesays whether it showslight,darkorboth.icon,favicon,apple_touch_icon,icon_192andicon_512are its icons, andplaceholder_iconstands in when it has none.unlocks_pausedistruewhile the store takes no new purchases: show the catalog, but not the buy buttons.bodyis the store home’s body, if it has one; read the layout the home renders, its body or the default home, withGET /bodyandtarget[kind]=store.categorieslists the product categories a product’scategorynames, and what each offers.currenciesgives each currency’sexponent, by its lower-case code.
The catalog
GET /v1/stores/{store}/products pages the store’s products, in the store’s own order unless you sort by published or title. listing is primary for the main catalog and secondary for the rest, such as support products. Each product’s subtitle is the short line shown under its title; its long description comes only with the product’s page.
type Product = {
id: string;
slug: string;
path: string;
url: string | null;
title: string;
subtitle: string | null;
offers: Offer[];
};
type Offer = {
id: string;
currency: string;
exponent: number | null;
amount: number;
discounted: number;
charge: number;
kind: 'one_time' | 'recurring';
period: { unit: 'day' | 'week' | 'month' | 'year'; multiplier: number } | null;
};
const catalog = await sherpo<{ items: Product[]; cursor: string | null }>(
'/products?filter[listing]=primary&limit=24',
);{
"items": [
{
"id": "<product id>",
"slug": "intro-course",
"path": "/p/intro-course",
"url": "https://yourstore.sherpo.io/p/intro-course",
"title": "Intro course",
"subtitle": "Everything you need to start.",
"listing": "primary",
"access": "locked",
"owned": null,
"rating": { "count": 12, "average": 4.6, "histogram": { "1": 0, "2": 0, "3": 1, "4": 3, "5": 8 }, "summary": null },
"offers": [
{
"id": "<price id>",
"tier": { "id": "<tier id>", "rank": 1, "name": "Standard" },
"currency": "eur",
"exponent": 2,
"amount": 4900,
"discounted": 4900,
"charge": 4900,
"highlighted": false,
"title": null,
"description": null,
"kind": "one_time",
"period": null,
"mode": "purchase"
}
]
}
],
"cursor": null
}Show charge, what the customer pays now, next to amount, the list price, when they differ. A product may have several tiers, each with its offers; highlighted marks the one the merchant wants to stand out. A recurring offer renews every period ({ "unit": "month", "multiplier": 1 } is monthly).
A product’s settings.refund_policy and an offer’s are the refund window each sets (none, 24h, 72h, 7d, 14d or 30d), null when it sets none. An offer with null sells under its product’s policy, which is what its checkout line answers.
A coupon in the URL, such as an affiliate link’s, goes in coupon on the product reads: the offers then come back priced with it, its discount named on each offer it applies to.
A product’s page
Each product, like each entry and page, names where the storefront serves it: path on the store, and url on the store’s verified domain (null while it has none). Link to path from a front-end of your own on the store’s domain.
GET /v1/stores/{store}/products/{product} reads one product, by id or by slug:<slug>. include=body adds its page’s layout in the same call: its body, or its default without one.
const product = await sherpo<Product & { body: unknown; description: string | null }>(
'/products/slug:intro-course?include=body',
);Beside the list’s fields, it answers:
descriptionandwhat_you_get, rich texts for the page (Bodies and rich text);body, the page’s layout when asked for, andfilesandattachments, what it shows (Files and media);entries, its lessons or articles in order, each with itsaccess;tiers, andowned: the tier the signed-in customer holds (tier_rank), whether through asubscriptionor agrant, and until when;calendar_events, the events a booking product offers to pick from;category, whosereviewable,subscribableandrepeatablesay what the product’s page offers;can_review, whether the signed-in customer may write their review of it now (Reviews).
access is unlocked once the customer may reach the product, locked before. A buy button for a locked product starts a checkout with the offer’s id as its price.
Lessons and articles
GET /v1/stores/{store}/products/{product}/entries pages a product’s entries in their order (position), each with its access, what it requires (everyone, a tier of the product by its rank, or nobody), its media and whether it has_quiz. A visitor sees them all, locked where they need a purchase, so your page can show what the product holds. Filter by section to show one part of a course, or by tag to show a blog’s category: an entry may hold several tags, and filter[tag]=guests lists those holding it, ignoring case.
Each entry names who signs it in author: its kind (member for one of the store’s team, business or store), the name to show and an image (the member’s avatar, the business’s logo or the store’s icon), or null when it is unsigned and shows no byline. A member who set no name answers name: null: show the store instead. An entry with an unlisted_at is left out of every list, the product’s entries and the sitemap, but still opens by its id or slug: keep it out of search engines (noindex) and your own lists.
GET /v1/stores/{store}/entries/{entry} reads one, with include=body for its layout. A free lesson’s video plays for anyone: see Files and media.
Custom pages
GET /v1/stores/{store}/pages pages the store’s custom pages. For your header’s menu, ask for the ones in it, in its order:
curl --globoff 'https://api.sherpo.io/customer/v1/stores/yourstore.sherpo.io/pages?filter[in_menu]=true&sort=menu' \
--header 'Publishable-Key: <publishable key>'GET /v1/stores/{store}/pages/{page} reads one by id or slug:<slug>, with include=body for its layout, its default hero without a body.
Reviews
A product’s rating gives its review count, average, a histogram by stars and, where the merchant shows it, a written summary of what reviews say. GET /v1/stores/{store}/products/{product}/reviews pages its reviews, newest first or by rating, and filters by stars (filter[rating][gte]=4).
{
"items": [
{
"id": "<review id>",
"product_id": "<product id>",
"rating": 5,
"username": "Ada",
"notes": "Clear and to the point.",
"reply": "Thank you, Ada!",
"mine": false,
"created_at": "2026-10-28T18:02:11.000Z"
}
],
"cursor": null
}A signed-in customer who holds the product may write theirs, which the product read’s can_review tells: see A customer’s library.
Prompts
A product may offer prompts, which the store’s customer MCP server serves too. GET /v1/stores/{store}/prompts?product=<product> lists a product’s prompts, with what each asks and the tier it requires, without their text. Signed in, leave product out to list the prompts of every product the customer holds, and add runnable=true for those they may run. The list isn’t paged: truncated: true says it was cut short, so narrow it with product. GET /v1/stores/{store}/prompts/{prompt}, with a token, reads one with its text filled in from arguments (arguments[topic]=pricing).
Checking a certificate
A certificate a customer shares can be checked by anyone: GET /v1/stores/{store}/certificates/{certificate}/verify answers who holds it, when it was issued and for what, as long as it was issued and isn’t revoked. Add of=<certificate id> to check it’s one of that certificate.
{
"id": "<issued certificate id>",
"certificate_id": "<certificate id>",
"issued_at": "2026-10-30T12:00:00.000Z",
"score": 92,
"holder": "Ada Lovelace",
"headline_copy": "Certificate of completion",
"title_copy": "Intro course",
"product": { "id": "<product id>", "slug": "intro-course", "title": "Intro course", "category": "course", "deleted": false }
}Previews
A seller can make a preview token for the store’s home, a page, a product or an entry, to see it before it’s published. Pass it as preview to the read of what it was made for (the store, the page, the product or the entry, and the body, file and video output reads under them): it opens that target unpublished, with its staged body shown past its gate, so treat a preview link as you would the content itself. A product’s token also opens the product’s published entries, their quizzes and its portfolio, gated as ever. An entry’s token also opens its product unpublished, with its live body, its portfolio and its other published entries and their quizzes, gated as ever; the entry’s own quiz and files open under it gated as ever too. Passed to anything it doesn’t open (the store, a page, a product or an entry it wasn’t made for and doesn’t open beside its target, or their bodies or quizzes), a token answers 404 not_found. A file read opens with it only the files of what it opens, gated as ever; any other file answers as it would without the token. An expired or unknown token, or one whose product or entry was deleted, answers 404 not_found on every read that takes preview, files included, and a read that doesn’t list preview among its arguments refuses it as 422 invalid.