Skip to content

Building a storefront

Show the store, its catalog, product pages, custom pages and reviews, before and after a customer signs in.

Updated

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>'
getStore 200json
{
  "id": "<store id>",
  "name": "Your Store",
  "locale": "en",
  "currency": "usd",
  "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 }
}
  • tint and tint_dark are the store’s accent colors in light and dark mode; settings.storefront.theme says whether it shows light, dark or both.
  • icon, favicon, apple_touch_icon, icon_96, icon_192 and icon_512 are its icons, and placeholder_icon stands in when it has none. icon_96 is a small copy for a header, null when the icon is animated. icon ends in #v=<version> once the icon’s smaller sizes are made, as a public file’s url does. icon and icon_96 name copies of the icon’s current bytes, which a browser may keep for a year: they change when the icon does, and the copies before stop being served a day later, so read them again rather than storing them.
  • unlocks_paused is true while the store takes no new purchases: show the catalog, but not the buy buttons.
  • body is the store home’s body, if it has one; read the layout the home renders, its body or the default home, with GET /body and target[kind]=store.
  • categories lists the product categories a product’s category names, and what each offers. currencies gives each currency’s exponent, by its lower-case code.
  • currency is the store’s own currency, by its lower-case code, or null until it picks one. Amounts in two currencies never compare, so when a product sells in several, show its starting price among its offers in this currency, as the storefront does.
  • integrations lists the integrations the store turned on, each with the script tags it asks a page to add. sets_cookies says whether those tags set cookies in the visitor’s browser, and cookie_consent is true when at least one of them does and has a tag to load. Then hold those tags until the visitor accepts wherever your visitors’ law asks for consent, as the storefront does with its cookie banner and the Cookie preferences entry in its Legal menu; tags with sets_cookies: false can load at once.

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;
  feed_url: 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',
);
listProducts 200json
{
  "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",
      "feed_url": null,
      "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
}

An event product’s row also carries event, so a listing shows its dates and place without reading each product (null for any other product):

  • format, reveal_location, location, map and location_hidden, as a visitor reads them on the product’s page (below);
  • sessions, the next sessions not yet ended, earliest first, at most 5, each with its id, starts_at, ends_at, time_zone, venue (null while the location is kept to ticket holders), online_label and add_to_calendar, its Google Calendar and Outlook links as the product read answers them;
  • ics, the event’s iCalendar file, its path and url (see Events);
  • session_count, every session, ended ones included, and upcoming_count, the sessions not yet ended, past the 5 listed too;
  • capacity, spots_left and sold_out, the event’s seats as its product read answers them: how many guests it takes in all and how many places it still takes, each null for no limit, and whether none is left;
  • first_starts_at, when the first session starts, and last_session, the one ending last with its starts_at, ends_at and time_zone, each null with no session.

An event whose last session has ended has no sessions left in its row and is no longer for sale: its product reads answer no offers, and a checkout refuses its prices, adding one with invalid and freezing a cart holding one with conflict on items, either with the reason the event has ended.

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 product whose settings.approval is required lets each buyer in once the seller approves them, and request is the signed-in customer’s latest request for it or their place on an event’s waitlist, null for none and for a visitor: see Approval and waitlists.

An offer’s discount is the one that takes something off its price, automatic or a coupon’s, null when none does. It names the discount’s id and code (null for one without a code), and starts_at and ends_at, when it started applying and the moment it stops, each null when it has none. Show ends_at beside the price to say when the sale ends. A discount that hasn’t started yet is never answered.

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. Reading one product also names it in coupon, its id and code, even where it takes nothing off; null for a coupon naming no discount, or one that hasn’t started yet.

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. A blog or a podcast also names its public feed in feed_url, on the store’s verified domain, so your pages can link it for feed readers and podcast apps: null for any other product, and while it is unlisted or the store has no verified domain (see Feeds).

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:

  • description and what_you_get, rich texts for the page (Bodies and rich text);
  • body, the page’s layout when asked for, and files and attachments, what it shows (Files and media);
  • entries, its lessons in their order, or a blog’s posts and a podcast’s episodes newest first, each with its access;
  • tiers, and owned: the tier the signed-in customer holds (tier_rank), whether through a subscription or a grant, and until when;
  • calendar_events, the events a booking product offers to pick from;
  • event, an event’s format, location, schedule (sessions), how it takes guests and the seats it has left (spots_left, sold_out, and each ticket type’s in tickets), null for any other product; with the location kept to ticket holders, someone without one reads only the city, region and country of location (every other field null, and location itself null when none of the three is set), each session’s venue as null and location_hidden as true, and map, the venue’s light and dark map images once drawn, is null with it (Categories);
  • category, whose reviewable, subscribable and repeatable say 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), or a blog’s posts and a podcast’s episodes newest first (published), unless you pass sort, each with its access, what it requires (everyone, a tier of the product by its rank, or nobody), when an event’s entry opens_at while it waits on its release, 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. Both filters together list the entries holding both. To show the choices, GET /v1/stores/{store}/products/{product}/entries/tags and GET /v1/stores/{store}/products/{product}/entries/sections page the distinct tags and sections the product’s listed entries hold once one of them is published, sorted by value, so a filter bar never reads every entry; a list with no items means the product’s entries hold none, and its filter has nothing to offer.

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, null when there is none), or null when it is unsigned and shows no byline. Like a public file’s url, an image ends in #v=<version> once its smaller sizes are made. 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}/products/{product}/entries/{entry} reads one, with include=body for its layout; an entry of another product answers not_found. 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).

listReviews 200json
{
  "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}/products/{product}/prompts lists a product’s prompts, with what each asks and the tier it requires, without their text. Signed in, GET /v1/stores/{store}/prompts lists the prompts of every product the customer holds; add runnable=true to either for those they may run. The list isn’t paged: truncated: true says it was cut short, so narrow it to a product. GET /v1/stores/{store}/products/{product}/prompts/{prompt}, with a token, reads one with its text filled in from arguments (arguments[topic]=pricing), and a prompt of another product answers not_found; GET /v1/stores/{store}/prompts/{prompt} reads one by its id or name alone.

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.

verifyCertificate 200json
{
  "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 }
}

Visits

Your pages aren’t counted in the store’s analytics until you tell the store about them: POST /v1/stores/{store}/visits records one page you showed, by what it shows (kind: home, page with the page’s id, product with the product’s id, or entry with the entry’s id and its product’s), and answers 201 with null. An id the store doesn’t hold records nothing. Call it from the visitor’s browser with the publishable key, or with a signed-in customer’s token, once per page shown: the store tells visitors apart by their address and browser for a day, without cookies, so a call from your own server would count every visitor as one. Each call counts against the key’s limit per visitor like any other. Customer analytics says what the store keeps of each visit, for your own privacy policy.

On a visit’s first page, add landing to say where the visitor came from: referrer (the page that linked to yours, as a URL or its host, of which only the host is kept), the landing URL’s utm_source, utm_medium, utm_campaign and ref, each up to 100 characters (a longer one refuses the call with 422) and kept in lowercase, and device: mobile for a phone, or desktop for a computer or a tablet (tablet counts as desktop), which the store reads from the browser’s user agent and mobile hint when you leave it out. Leave landing out on every later page of the visit, and on a reload or a link from your own site.

const query = new URL(location.href).searchParams;
const tag = (name: string) => [...(query.get(name) ?? '').trim()].slice(0, 100).join('');
await sherpo('/visits', {
  method: 'POST',
  body: {
    kind: 'product',
    product: '<product id>',
    landing: {
      referrer: document.referrer === '' ? '' : new URL(document.referrer).host,
      utm_source: tag('utm_source'),
      utm_medium: tag('utm_medium'),
      utm_campaign: tag('utm_campaign'),
      ref: tag('ref'),
    },
  },
});

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.

Type to search…

↑↓ navigate↵ selectEsc close