Skip to content

Customer API

Build your own storefront, checkout and customer library on the customer REST API.

Updated

The customer API serves a store to a front end of your own: its catalog, pages and reviews to anyone, and a signed-in customer’s account, purchases and library to that customer. It is what you build on when your store’s website or app is your own code rather than the site Sherpo hosts for it.

Using it from your store’s own front end needs the Pro plan or Sherpo One; see Your own front end.

Base URL

Every call goes to https://api.sherpo.io/customer.

Every endpoint is under /v1/stores/{store}, where {store} is one of the store’s hostnames: its Sherpo subdomain (yourstore.sherpo.io) or a domain of its own, written in lower case. The same store answers under any of its hostnames. A hostname spelled otherwise (in upper case, or with a trailing dot) redirects (308) to its lower-case spelling.

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

The OpenAPI document of the whole API is at https://api.sherpo.io/customer/openapi.json, and the reference renders it, one page per endpoint.

Credentials

Each call carries one credential, never both:

  • A publishable key, in a Publishable-Key header, for what anyone visiting the store sees: the store, its products, entries, pages, reviews and files open to visitors, and recording the pages a visitor saw. It is public by design and reads alone, but for that record.
  • A customer’s access token, as Authorization: Bearer ctk_..., for everything a signed-in customer does: their library, progress, checkout, orders, subscriptions and account. The store’s authorization server issues it once the customer signs in and grants your app what it asks for.

Authentication covers both. Reads that take a publishable key answer the same endpoint with a token too, adding what that customer holds.

Conventions

  • Bodies are JSON (Content-Type: application/json), and keys are snake_case.
  • Times are ISO 8601 strings in UTC, such as 2026-11-03T09:30:00.000Z.
  • Amounts are integers in the currency’s minor unit, with the currency’s exponent beside them: 4900 with exponent: 2 is 49.00. An exponent of null means the currency isn’t known to have one; show the amount as it is.
  • An enum may gain values. Treat a value you don’t know as you would the closest one you do, never as an error.
  • A reference to another object is its id; where the kind has slugs, slug:<slug> works too, as in /products/slug:intro-course.
  • Reads go in the query string and writes in a JSON body; Paging and search has the rules for both.
  • A failure is an RFC 9457 problem, described in Errors. Limits covers rate limits and quotas.

Guides

  • Building a storefront: the store, its catalog, product pages, custom pages and reviews.
  • Checkout: from a cart to a paid order, with Stripe.js in your page.
  • A customer’s library: what the customer holds, their lessons and progress, quizzes, certificates, orders, subscriptions and account.
  • Files and media: images, downloads and videos, in a browser or a player.
  • Rich text: the format of products’, lessons’ and pages’ bodies.
  • Notifications: what’s new for a customer, the types they hear about, and browser notifications.
  • Feeds: a blog’s or a podcast’s public RSS feed, and a customer’s own private one.
  • Licenses: the license keys of a customer’s software, the devices each runs on, and a new key when theirs leaks.

Endpoints

Every endpoint, by what it serves. Those marked key also take a publishable key.

Store and catalog

Endpoint
GET /v1/stores/{store} Read the store key
GET /v1/stores/{store}/products List products key
GET /v1/stores/{store}/products/{product} Read a product key
GET /v1/stores/{store}/products/{product}/entries List a product’s entries key
GET /v1/stores/{store}/products/{product}/entries/sections List a product’s entry sections key
GET /v1/stores/{store}/products/{product}/entries/tags List a product’s entry tags key
GET /v1/stores/{store}/products/{product}/entries/{entry} Read an entry key
GET /v1/stores/{store}/pages List custom pages key
GET /v1/stores/{store}/pages/{page} Read a custom page key
GET /v1/stores/{store}/body Read a body key
GET /v1/stores/{store}/products/{product}/reviews List a product’s reviews key
GET /v1/stores/{store}/prompts List prompts across products key
GET /v1/stores/{store}/products/{product}/prompts List a product’s prompts key
GET /v1/stores/{store}/prompts/{prompt} Read a prompt
GET /v1/stores/{store}/products/{product}/prompts/{prompt} Read a product’s prompt
GET /v1/stores/{store}/certificates/{certificate}/verify Check a certificate key
GET /v1/stores/{store}/license_signing_keys List the keys offline license tokens are checked against key
POST /v1/stores/{store}/visits Record a page shown key

Files

Endpoint
POST /v1/stores/{store}/attachments/url Get a file’s URL key
GET /v1/stores/{store}/files/{capability} Fetch a private file key
GET /v1/stores/{store}/media_outputs Read a video’s or audio file’s chapters, summary and transcript key

Library and progress

Endpoint
GET /v1/stores/{store}/entitlements List what the customer may reach
GET /v1/stores/{store}/grants List the customer’s grants of access
POST /v1/stores/{store}/products/{product}/entries/{entry}/complete Mark an entry complete
GET /v1/stores/{store}/completions List completed entries across products
GET /v1/stores/{store}/products/{product}/completions List a product’s completed entries

Quizzes and certificates

Reviews

Checkout

Orders and subscriptions

Account

Notifications

Feeds

Endpoint
GET /v1/stores/{store}/products/{product}/answers Read the customer’s answers to a product’s questions
PUT /v1/stores/{store}/products/{product}/answers Answer a product’s questions in checkout
GET /v1/stores/{store}/products/{product}/feeds Read a blog’s or a podcast’s feeds
POST /v1/stores/{store}/products/{product}/feeds/private Get a private feed, or a new address for it
DELETE /v1/stores/{store}/products/{product}/feeds/private Turn it off

Event guests

Endpoint
GET /v1/stores/{store}/products/{product}/guests List the guests the customer bought tickets for
PUT /v1/stores/{store}/products/{product}/guests/{guest} Hand a ticket to someone else
POST /v1/stores/{store}/products/{product}/guests/{guest}/resend Send a guest their ticket again

Licenses

Event tickets

Endpoint
GET /v1/stores/{store}/products/{product}/ticket Read the customer’s ticket to an event, with its code for the door

Portfolios

Software

Endpoint
GET /v1/stores/{store}/products/{product}/activity List its releases and notes

Type to search…

↑↓ navigate↵ selectEsc close