Skip to content

A customer's library

Show a signed-in customer what they hold, their lessons and progress, quizzes, certificates, event tickets, orders, subscriptions and account.

Updated

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_...'
listEntitlements 200json
{
  "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
}
  • held is whether they hold it now. A product they held once and no longer do stays listed with held: false and tier_rank: 0; its expires_at may then be null, which on such a row means nothing.
  • On a held product, tier_rank is the rank of the highest tier they hold, until tier_expires_at, and expires_at is when all their access ends (null for never).
  • order is the order behind it, null for access the merchant granted by hand.
  • renews_at is when a subscription of the product next renews.
  • given_by names who bought the customer’s ticket to an event as their guest (name, null when they gave none); null otherwise.
  • attending is whether they’re going to an event, so a ticket shows even for access with no tier, which reads held: false and tier_rank: 0. It’s false for any other product. See Event tickets.
  • ticket is their ticket to an event as it stands now: status (going, pending, waitlisted or canceled), cancel_reason (refunded, revoked, expired, declined, or canceled when the seller canceled the event; null unless canceled) and its tier (id, name, rank; null for a ticket with no tier), so a list of events shows each ticket’s type without reading it on its own. It’s null for any other product, or an event they hold no ticket to. Right after a first ticket it can read null for a moment while attending is already true: 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 in requires: a tier of the product by its rank (that tier or a higher one), or nobody (no one can, for now), while everyone marks 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 in opens_at (timed release): show the time, and read it again then. For a product, compare its tiers with 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 '{}'
completeEntry 200json
{
  "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.

  1. Start an attempt

    POST /v1/stores/{store}/products/{product}/entries/{entry}/quizzes/{quiz}/attempts answers the attempt and its questions, and any answers saved before.

  2. Save as they go

    POST /v1/stores/{store}/products/{product}/attempts/{attempt}/save saves the answers given so far, replacing those saved before, so the attempt resumes on any device.

  3. Submit

    POST /v1/stores/{store}/products/{product}/attempts/{attempt}/submit grades it, answering the score, how many were correct of the total, each question’s result and any certificate it 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.

getOrder 200json
{
  "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_status is the status to show: cancelling for one still billing that is set to stop.
  • next_event is what happens at the end of the paid period (renews, ends or lapses, on a plan that doesn’t renew) and at when, or null when nothing is ahead.
  • next_charge is the next payment while the subscription renews: at, a day before the period ends, as every renewal is charged a day ahead, and amount, the plan it renews on less its price’s renewal discount, in its currency and exponent; null otherwise. A current_period whose lead_in is true is a first period a grant of the customer’s still covers, charged nothing, so next_charge is the subscription’s first payment.
  • actions says which of the writes below the store offers on it now (cancel.period_end, resume, change_plan), and cancel.now when 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_card says whether the store holds its saved card (instrument_id) for its renewals.
  • cancel_reason is why it stops or stopped in someone’s own words, the customer’s or the seller’s, and cancel_code how the store stopped it when no one gave a reason: refund, dispute, upgraded, account_erased or seller_ended. At most one of them is set.
  • plan_changes lists the plans a change may move to, each with the price_id to send, its name, tier, amount and period.

These need subscription:write:

  • POST /subscriptions/{subscription}/cancel cancels at the end of the paid period, or at once when actions.cancel.now says so, with an optional reason (up to 500 characters, in the customer’s own words: one that reads as a code the store writes itself, such as refund, is refused, as is a blank one (leave it out instead)).
  • POST /subscriptions/{subscription}/resume withdraws a scheduled cancellation. One whose saved card is gone renews on the default card, or the only one saved.
  • PUT /subscriptions/{subscription}/plan schedules it to renew on a lower tier, or a shorter period of the same tier, from the end of the paid period. Take the price from the subscription’s plan_changes. Its current price takes a scheduled change back. Moving up is a purchase: an upgrade offer 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}/default makes 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 refused conflict (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.

Type to search…

↑↓ navigate↵ selectEsc close