Once a customer signs in, their token reaches everything they hold in the store. Everything here needs a token (Authentication): reads take read, and each write names its own scope. The examples use the client from Your own front end.
What they hold
GET /v1/stores/{store}/entitlements lists the products the customer holds or held, one item per product, with the tier they hold and until when.
curl 'https://api.sherpo.io/customer/v1/stores/yourstore.sherpo.io/entitlements?sort=title' \
--header 'Authorization: Bearer ctk_...'{
"items": [
{
"product_id": "<product id>",
"tier_rank": 1,
"tier_expires_at": null,
"expires_at": null,
"held": true,
"order": { "id": "<order id>", "number": 1042 },
"renews_at": null,
"given_by": null,
"attending": false,
"ticket": null
},
{
"product_id": "<event id>",
"tier_rank": 2,
"tier_expires_at": null,
"expires_at": null,
"held": true,
"order": { "id": "<order id>", "number": 1043 },
"renews_at": null,
"given_by": null,
"attending": true,
"ticket": {
"status": "going",
"cancel_reason": null,
"tier": { "id": "<tier id>", "name": "In person", "rank": 2 }
}
}
],
"cursor": null
}heldis whether they hold it now. A product they held once and no longer do stays listed withheld: falseandtier_rank: 0; itsexpires_atmay then benull, which on such a row means nothing.- On a held product,
tier_rankis the rank of the highest tier they hold, untiltier_expires_at, andexpires_atis when all their access ends (nullfor never). orderis the order behind it,nullfor access the merchant granted by hand.renews_atis when a subscription of the product next renews.given_bynames who bought the customer’s ticket to an event as their guest (name,nullwhen they gave none);nullotherwise.attendingis whether they’re going to an event, so a ticket shows even for access with no tier, which readsheld: falseandtier_rank: 0. It’sfalsefor any other product. See Event tickets.ticketis their ticket to an event as it stands now:status(going,pending,waitlistedorcanceled),cancel_reason(refunded,revoked,expired,declined, orcanceledwhen the seller canceled the event;nullunless canceled) and itstier(id,name,rank;nullfor a ticket with no tier), so a list of events shows each ticket’s type without reading it on its own. It’snullfor any other product, or an event they hold no ticket to. Right after a first ticket it can readnullfor a moment whileattendingis alreadytrue: read again shortly.
Read each product with GET /products/{product} for its title, poster and entries: with a token, its owned and access are the customer’s own. GET /grants lists the grants behind the entitlements one by one, each with where it came from (source_kind), when it started (valid_from) and ended (ends_at, end_reason), and where it stands now (status: scheduled, active, expired, revoked, refunded or ended).
Access
Products, entries, pages, bodies, files, quizzes and quiz attempts carry an access:
unlocked: the customer may reach it;locked: they may not yet. An entry or a body says what unlocks it inrequires: atierof the product by itsrank(that tier or a higher one), ornobody(no one can, for now), whileeveryonemarks what is open to anyone. An event’s entry that hasn’t opened yet is locked to everyone, ticket holders too, and says when it opens inopens_at(timed release): show the time, and read it again then. For a product, compare itstierswith what the customer holds (owned);bypassed: reached past its gate by the store’s own team, as a customer never is.
A locked read still answers 200 with what a visitor sees, such as an entry’s title and preview, or a body’s requires and words with content: null, so your page can show what buying unlocks. Opening a file the customer may not reach answers 403 not_entitled.
Lessons and progress
A product’s entries are its lessons in their order, or a blog’s posts and a podcast’s episodes newest first, each with its access, completed_at (when the customer finished it, or null), whether it has_quiz or has_certificate, and its media (duration in seconds, slides, files, links). Read one with GET /products/{product}/entries/{entry}?include=body, render its body, and play its video as Files and media shows.
Mark it done with POST /v1/stores/{store}/products/{product}/entries/{entry}/complete (progress:write):
curl --request POST 'https://api.sherpo.io/customer/v1/stores/yourstore.sherpo.io/products/<product id>/entries/<entry id>/complete' \
--header 'Authorization: Bearer ctk_...' \
--header 'Content-Type: application/json' \
--data '{}'{
"entry_id": "<entry id>",
"product_id": "<product id>",
"completed_at": "2026-11-03T09:42:10.000Z",
"certificates": []
}certificates lists any certificate finishing it issued. GET /products/{product}/completions lists what they finished in one product, for a progress bar, and GET /completions what they finished across every product.
Quizzes
An entry with a quiz has a quiz: its settings (attempts_allowed, pass_mark, show_answers), whether a certificate requires_passing it, and its access. Taking it needs quiz:write. Every route below names the product, and a quiz’s routes its entry too; an entry, quiz, attempt or certificate of another product answers not_found.
Start an attempt
POST /v1/stores/{store}/products/{product}/entries/{entry}/quizzes/{quiz}/attemptsanswers theattemptand itsquestions, and any answers saved before.Save as they go
POST /v1/stores/{store}/products/{product}/attempts/{attempt}/savesaves the answers given so far, replacing those saved before, so the attempt resumes on any device.Submit
POST /v1/stores/{store}/products/{product}/attempts/{attempt}/submitgrades it, answering thescore, how many werecorrectof thetotal, each question’s result and anycertificateit issued.
answers is an object from each question’s id to its answer, by the question’s type:
type |
Answer |
|---|---|
multiple_choice |
The chosen option’s id. |
true_false |
true or false. |
scale |
A number between the question’s min and max. |
short_text |
A string, at most 4000 characters, graded against the accepted answers. |
free_text |
A string, at most 4000 characters, not graded. |
static_text |
None: it’s text to read, its content in rich text. |
curl --request POST 'https://api.sherpo.io/customer/v1/stores/yourstore.sherpo.io/products/<product id>/attempts/<attempt id>/submit' \
--header 'Authorization: Bearer ctk_...' \
--header 'Content-Type: application/json' \
--data '{ "answers": { "q1": "<option id>", "q2": true, "q3": 7 } }'POST .../quizzes/{quiz}/forfeit gives the quiz up: the open attempt, or the attempts left. A quiz is over once it is given up, its attempts are used, or an attempt scores 100: from then on starting, resuming, saving or submitting an attempt answers conflict on attempts, and so does giving up, unless an attempt is still open. GET /attempts lists their attempts across every product, and GET /products/{product}/attempts those in one (filter either by entry_id across a quiz’s versions, or status); GET /products/{product}/attempts/{attempt} reads one to review, with each result and, where the quiz shows them, the right answers.
An attempt stays on the version of the quiz it started on, so each one carries the access of its own version: an open attempt resumes, and a finished one is reviewed, while its own access isn’t locked, even where a newer version’s is. The quiz’s access is the latest version’s, which a new attempt starts on. Giving up acts on the open attempt’s version, or the latest when none is open.
Certificates
GET /v1/stores/{store}/certificates lists the certificates issued to the customer across every product, GET /products/{product}/certificates those of one, and GET /products/{product}/certificates/{certificate} reads one, with its holder, score and the certificate it’s one of. A course’s are earned with a quiz or by finishing it, and an event’s by being checked in at any of its sessions, with no score; the merchant may issue either by hand. Anyone can check one they’re shown with the verify endpoint, so link it from the certificate’s page.
Reviews
A customer granted a product, by a purchase or by the merchant, may review it (review:write), while they hold it or after it lapsed, though not after a refund or a revoke (else 403 not_entitled), where its category is reviewable and the merchant keeps its reviews on (else 422 invalid at ["args", "product"]): PUT /v1/stores/{store}/products/{product}/review writes or updates their review, a rating from 1 to 5, optional notes (up to 4000 characters) and the username it shows under (up to 120).
The product read answers whether that write would take their review now as can_review, so a page offers the form only where it would: false with no signed-in customer, or for a token whose scopes leave out review:write.
curl --request PUT 'https://api.sherpo.io/customer/v1/stores/yourstore.sherpo.io/products/slug:intro-course/review' \
--header 'Authorization: Bearer ctk_...' \
--header 'Content-Type: application/json' \
--data '{ "rating": 5, "notes": "Clear and to the point.", "username": "Ada" }'GET .../review reads theirs, with the merchant’s reply, and DELETE .../review deletes it. A review the merchant hid has a hidden_at.
Portfolios
A portfolio product shares a book of holdings. With access, GET /products/{product}/portfolio reads its holdings and performance, GET .../portfolio/valuation values it at live quotes and prices its watchlist, and GET .../portfolio/events and GET .../portfolio/snapshots page its trades and its daily values.
Software activity
A software product’s releases and notes are its holders’ to read. GET /products/{product}/activity pages them, newest first, and filters by type (release or note). A release carries its version, its notes in body and the files the customer may download, opened as any download is; current marks the product’s current download, its newest release that ships files, and locked a release whose files a higher tier downloads. Every product read carries release, the newest release overall (with or without files): its id, version and occurred_at, so a card can say what’s new without reading the activity; it is null for any other product.
Orders
GET /v1/stores/{store}/orders lists the customer’s orders, newest first; GET /orders/{order} reads one with its lines and refunds, and GET /orders/{order}/items and /refunds page them when there are many.
{
"id": "<order id>",
"number": 1042,
"currency": "eur",
"exponent": 2,
"amount": 4900,
"discount": 490,
"total": 4410,
"source": "checkout",
"has_receipt": true,
"item_count": 1,
"refunded": 0,
"refund_status": "none",
"refund_count": 0,
"occurred_at": "2026-11-03T09:01:44.000Z"
}Where has_receipt is true, GET /orders/{order}/receipt answers a url to the payment processor’s receipt. The link expires and shows the card and the buyer’s address, so ask for it when the customer opens it, and never store it.
Subscriptions
GET /v1/stores/{store}/subscriptions lists the customer’s subscriptions: their status (active, past_due, paused, cancelled, ended or unpaid), plan, current_period (whose end is when the next payment is due), the saved card they renew on (instrument_id), whether they cancel_at_period_end, and a scheduled_change of plan. Each also answers what to show and offer, so you never work it out from the status:
display_statusis the status to show:cancellingfor one still billing that is set to stop.next_eventis what happens at the end of the paid period (renews,endsorlapses, on a plan that doesn’t renew) andatwhen, ornullwhen nothing is ahead.next_chargeis the next payment while the subscription renews:at, a day before the period ends, as every renewal is charged a day ahead, andamount, the plan it renews on less its price’s renewal discount, in itscurrencyandexponent;nullotherwise. Acurrent_periodwhoselead_inistrueis a first period a grant of the customer’s still covers, charged nothing, sonext_chargeis the subscription’s first payment.actionssays which of the writes below the store offers on it now (cancel.period_end,resume,change_plan), andcancel.nowwhen a cancel ends it at once, every payment of it refunded; a write can still be refused, for example to an app the store hasn’t verified.renews_on_cardsays whether the store holds its saved card (instrument_id) for its renewals.cancel_reasonis why it stops or stopped in someone’s own words, the customer’s or the seller’s, andcancel_codehow the store stopped it when no one gave a reason:refund,dispute,upgraded,account_erasedorseller_ended. At most one of them is set.plan_changeslists the plans a change may move to, each with theprice_idto send, itsname,tier,amountandperiod.
These need subscription:write:
POST /subscriptions/{subscription}/cancelcancels at the end of the paid period, or at once whenactions.cancel.nowsays so, with an optionalreason(up to 500 characters, in the customer’s own words: one that reads as a code the store writes itself, such asrefund, is refused, as is a blank one (leave it out instead)).POST /subscriptions/{subscription}/resumewithdraws a scheduled cancellation. One whose saved card is gone renews on the default card, or the only one saved.PUT /subscriptions/{subscription}/planschedules it to renew on a lower tier, or a shorter period of the same tier, from the end of the paid period. Take thepricefrom the subscription’splan_changes. Its current price takes a scheduled change back. Moving up is a purchase: anupgradeoffer in a checkout.
Resuming and changing a plan are refused to an app the store hasn’t verified: send the customer to /account/subscriptions on the store’s site (Authentication).
Account
Profile
GET /v1/stores/{store}/profile reads the customer’s name, locale, country and email address. PATCH /profile (profile:write) changes their display_name (up to 120 characters) and locale (a language tag, up to 35); null clears either.
Email address
A customer holds one email address, listed at GET /contacts. Changing it takes two steps, both contact:write, which only a client the merchant created holds, so run them from your backend:
curl --request POST 'https://api.sherpo.io/customer/v1/stores/yourstore.sherpo.io/contacts/change' \
--header 'Authorization: Bearer ctk_...' \
--header 'Content-Type: application/json' \
--data '{ "kind": "email", "value": "ada@example.org" }'This mails a code to the new address and answers when it expires_at. Then POST /contacts/verify with the value and the code proves it, and it replaces the old address. Until then the old one stays and still signs the customer in, and asking for another address replaces the one waiting for its code. Codes are limited per customer and per store.
Saved cards
GET /v1/stores/{store}/billing_profile lists the customer’s saved payment methods, each with its display (brand, last4, expiration) and whether it is_default, the one their subscriptions renew on. With checkout:write:
PUT /payment_methods/{instrument}/defaultmakes one the default, and moves the customer’s subscriptions in every store of the business onto it (a store that can’t take it right away is moved again shortly, renewing on the old card until then). It’s refusedconflict(status,busy) while the card is being removed or the customer’s saved details are being dropped: try again shortly;DELETE /payment_methods/{instrument}removes one, never one a subscription still renews on. A subscription of a store the business deleted doesn’t hold it: it moves to the default card, if one is left.
Both are refused to an app the store hasn’t verified: send the customer to /account/payment-methods on the store’s site.
Signing out
Revoke the token at the authorization server when the customer signs out of your app: see Refresh and revoke.