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-Keyheader, 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 aresnake_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
exponentbeside them:4900withexponent: 2is 49.00. Anexponentofnullmeans 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
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
| Endpoint | |
|---|---|
POST /v1/stores/{store}/products/{product}/entries/{entry}/quizzes/{quiz}/attempts |
Start an attempt |
POST /v1/stores/{store}/products/{product}/attempts/{attempt}/save |
Save answers so far |
POST /v1/stores/{store}/products/{product}/attempts/{attempt}/submit |
Submit an attempt |
POST /v1/stores/{store}/products/{product}/entries/{entry}/quizzes/{quiz}/forfeit |
Give up the quiz |
GET /v1/stores/{store}/attempts |
List attempts across products |
GET /v1/stores/{store}/products/{product}/attempts |
List a product’s attempts |
GET /v1/stores/{store}/products/{product}/attempts/{attempt} |
Read an attempt |
GET /v1/stores/{store}/certificates |
List certificates across products |
GET /v1/stores/{store}/products/{product}/certificates |
List a product’s certificates |
GET /v1/stores/{store}/products/{product}/certificates/{certificate} |
Read a certificate |
Reviews
| Endpoint | |
|---|---|
GET /v1/stores/{store}/products/{product}/review |
Read the customer’s review |
PUT /v1/stores/{store}/products/{product}/review |
Write or update it |
DELETE /v1/stores/{store}/products/{product}/review |
Delete it |
Checkout
| Endpoint | |
|---|---|
POST /v1/stores/{store}/checkouts |
Open a cart |
GET /v1/stores/{store}/checkouts |
List carts |
GET /v1/stores/{store}/checkouts/{checkout} |
Read a cart |
PUT /v1/stores/{store}/checkouts/{checkout}/items |
Set a line |
PUT /v1/stores/{store}/checkouts/{checkout}/coupon |
Apply or remove a coupon |
POST /v1/stores/{store}/checkouts/{checkout}/freeze |
Present it for payment |
POST /v1/stores/{store}/checkouts/{checkout}/pay |
Start paying |
POST /v1/stores/{store}/checkouts/{checkout}/confirm |
Confirm the payment |
POST /v1/stores/{store}/checkouts/{checkout}/abandon |
Give it up |
POST /v1/stores/{store}/products/{product}/waitlist |
Join a full event’s waitlist |
POST /v1/stores/{store}/products/{product}/waitlist/card |
Save the card a paid waitlist place is charged on |
Orders and subscriptions
| Endpoint | |
|---|---|
GET /v1/stores/{store}/orders |
List orders |
GET /v1/stores/{store}/orders/{order} |
Read an order |
GET /v1/stores/{store}/orders/{order}/items |
List an order’s lines |
GET /v1/stores/{store}/orders/{order}/refunds |
List an order’s refunds |
GET /v1/stores/{store}/orders/{order}/receipt |
Link an order’s receipt |
GET /v1/stores/{store}/subscriptions |
List subscriptions |
GET /v1/stores/{store}/subscriptions/{subscription} |
Read a subscription |
POST /v1/stores/{store}/subscriptions/{subscription}/cancel |
Cancel at the period’s end |
POST /v1/stores/{store}/subscriptions/{subscription}/resume |
Withdraw a cancellation |
PUT /v1/stores/{store}/subscriptions/{subscription}/plan |
Change the plan from the next period |
Account
| Endpoint | |
|---|---|
GET /v1/stores/{store}/profile |
Read the profile |
PATCH /v1/stores/{store}/profile |
Update the name and locale |
GET /v1/stores/{store}/contacts |
List the email address |
POST /v1/stores/{store}/contacts/change |
Ask to change it |
POST /v1/stores/{store}/contacts/verify |
Prove the new one |
GET /v1/stores/{store}/billing_profile |
List saved payment methods |
PUT /v1/stores/{store}/payment_methods/{instrument}/default |
Make one the default |
DELETE /v1/stores/{store}/payment_methods/{instrument} |
Remove one |
Notifications
| Endpoint | |
|---|---|
GET /v1/stores/{store}/notifications |
List notifications |
POST /v1/stores/{store}/notifications/read |
Mark them read |
POST /v1/stores/{store}/notifications/delete |
Delete them |
GET /v1/stores/{store}/notification_settings |
Read which types notify |
PATCH /v1/stores/{store}/notification_settings |
Turn types on or off |
GET /v1/stores/{store}/push_key |
Read the browser push key |
POST /v1/stores/{store}/push_subscriptions |
Allow a browser |
POST /v1/stores/{store}/push_subscriptions/renew |
Move a renewed one |
POST /v1/stores/{store}/push_subscriptions/delete |
Stop pushing to one |
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
| Endpoint | |
|---|---|
GET /v1/stores/{store}/products/{product}/licenses |
List a customer’s licenses of a product |
GET /v1/stores/{store}/products/{product}/licenses/{license} |
Read one |
POST /v1/stores/{store}/products/{product}/licenses/{license}/rotate |
Get a new key |
GET /v1/stores/{store}/products/{product}/licenses/{license}/activations |
List a license’s devices |
POST /v1/stores/{store}/products/{product}/licenses/{license}/activations/{activation}/deactivate |
Free a device |
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
| Endpoint | |
|---|---|
GET /v1/stores/{store}/products/{product}/portfolio |
Read a portfolio |
GET /v1/stores/{store}/products/{product}/portfolio/valuation |
Value it at live quotes |
GET /v1/stores/{store}/products/{product}/portfolio/events |
List its events |
GET /v1/stores/{store}/products/{product}/portfolio/snapshots |
List its daily snapshots |
Software
| Endpoint | |
|---|---|
GET /v1/stores/{store}/products/{product}/activity |
List its releases and notes |