---
title: "Building a storefront"
description: "Show the store, its catalog, product pages, custom pages and reviews, before and after a customer signs in."
---

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

# Building a storefront

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](/customer-api/self-hosted#a-minimal-client).

## The store

[`GET /v1/stores/{store}`](/customer-api/reference/get-store) reads the store's name, branding and settings, for your header, footer and page titles.

```bash
curl 'https://api.sherpo.io/customer/v1/stores/yourstore.sherpo.io' \
  --header 'Publishable-Key: <publishable key>'
```

```json title="getStore 200"
{
  "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](/customer-api/files) `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](/customer-api/rich-text#default-layouts), with [`GET /body`](/customer-api/rich-text#bodies) 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`](/customer-api/reference/list-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](#a-products-page).

```ts
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',
);
```

```json title="listProducts 200"
{
  "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](/customer-api/feeds#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](/customer-api/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](/customer-api/checkout#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](/customer-api/feeds#the-public-feed)).

[`GET /v1/stores/{store}/products/{product}`](/customer-api/reference/get-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](/customer-api/rich-text#default-layouts) without one.

```ts
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](/customer-api/rich-text#rich-text));
- `body`, the page's layout when asked for, and `files` and `attachments`, what it shows ([Files and media](/customer-api/files));
- `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](/overview/categories#event));
- `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](/customer-api/library#reviews)).

`access` is `unlocked` once the customer may reach the product, `locked` before. A buy button for a `locked` product starts a [checkout](/customer-api/checkout) with the offer's `id` as its price.

## Lessons and articles

[`GET /v1/stores/{store}/products/{product}/entries`](/customer-api/reference/list-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](/overview/categories#entries-and-timed-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`](/customer-api/reference/list-entry-tags) and [`GET /v1/stores/{store}/products/{product}/entries/sections`](/customer-api/reference/list-entry-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](/customer-api/files) `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}`](/customer-api/reference/get-entry) reads one, with `include=body` for its layout; an entry of another product answers [`not_found`](/customer-api/errors#not_found). A free lesson's video plays for anyone: see [Files and media](/customer-api/files#with-a-publishable-key).

## Custom pages

[`GET /v1/stores/{store}/pages`](/customer-api/reference/list-pages) pages the store's custom pages. For your header's menu, ask for the ones in it, in its order:

```bash
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}`](/customer-api/reference/get-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`](/customer-api/reference/list-reviews) pages its reviews, newest first or by `rating`, and filters by stars (`filter[rating][gte]=4`).

```json title="listReviews 200"
{
  "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](/customer-api/library#reviews).

## Prompts

A product may offer prompts, which the store's [customer MCP server](/customer-mcp/prompts) serves too. [`GET /v1/stores/{store}/products/{product}/prompts`](/customer-api/reference/list-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`](/customer-api/reference/list-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}`](/customer-api/reference/get-product-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`](/customer-api/errors#not_found); [`GET /v1/stores/{store}/prompts/{prompt}`](/customer-api/reference/get-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`](/customer-api/reference/verify-certificate) 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.

```json title="verifyCertificate 200"
{
  "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`](/customer-api/reference/record-visit) 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](/customer-api/limits#per-visitor) like any other. [Customer analytics](/overview/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.

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

Source: https://docs.sherpo.io/customer-api/storefront/index.mdx
