---
title: "A customer's library"
description: "Show a signed-in customer what they hold, their lessons and progress, quizzes, certificates, event tickets, orders, subscriptions and account."
---

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

# A customer's library

Once a customer signs in, their token reaches everything they hold in the store. Everything here needs a token ([Authentication](/customer-api/authentication)): reads take `read`, and each write names its own scope. The examples use the client from [Your own front end](/customer-api/self-hosted#a-minimal-client).

## What they hold

[`GET /v1/stores/{store}/entitlements`](/customer-api/reference/list-entitlements) lists the products the customer holds or held, one item per product, with the tier they hold and until when.

```bash
curl 'https://api.sherpo.io/customer/v1/stores/yourstore.sherpo.io/entitlements?sort=title' \
  --header 'Authorization: Bearer ctk_...'
```

```json title="listEntitlements 200"
{
  "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](/customer-api/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}`](/customer-api/reference/get-product) for its title, poster and entries: with a token, its `owned` and `access` are the customer's own. [`GET /grants`](/customer-api/reference/list-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 {#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](/overview/categories#entries-and-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`](/customer-api/errors#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`](/customer-api/reference/get-entry), render its [body](/customer-api/rich-text#bodies), and play its video as [Files and media](/customer-api/files) shows.

Mark it done with [`POST /v1/stores/{store}/products/{product}/entries/{entry}/complete`](/customer-api/reference/complete-entry) (`progress:write`):

```bash
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 '{}'
```

```json title="completeEntry 200"
{
  "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`](/customer-api/reference/list-product-completions) lists what they finished in one product, for a progress bar, and [`GET /completions`](/customer-api/reference/list-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`](/customer-api/errors#not_found).

1. **Start an attempt**

   [`POST /v1/stores/{store}/products/{product}/entries/{entry}/quizzes/{quiz}/attempts`](/customer-api/reference/start-attempt) 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`](/customer-api/reference/save-attempt) 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`](/customer-api/reference/submit-attempt) 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](/customer-api/rich-text#rich-text). |

```bash
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`](/customer-api/reference/forfeit-quiz) 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`](/customer-api/errors#conflict) on `attempts`, and so does giving up, unless an attempt is still open. [`GET /attempts`](/customer-api/reference/list-attempts) lists their attempts across every product, and [`GET /products/{product}/attempts`](/customer-api/reference/list-product-attempts) those in one (filter either by `entry_id` across a quiz's versions, or `status`); [`GET /products/{product}/attempts/{attempt}`](/customer-api/reference/get-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`](/customer-api/reference/list-certificates) lists the certificates issued to the customer across every product, [`GET /products/{product}/certificates`](/customer-api/reference/list-product-certificates) those of one, and [`GET /products/{product}/certificates/{certificate}`](/customer-api/reference/get-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](/customer-api/storefront#checking-a-certificate), so link it from the certificate's page.

## Reviews {#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`](/customer-api/errors#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`](/customer-api/reference/write-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`.

```bash
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`](/customer-api/reference/get-review) reads theirs, with the merchant's `reply`, and [`DELETE .../review`](/customer-api/reference/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`](/customer-api/reference/get-portfolio) reads its holdings and performance, [`GET .../portfolio/valuation`](/customer-api/reference/get-portfolio-valuation) values it at live quotes and prices its watchlist, and [`GET .../portfolio/events`](/customer-api/reference/list-portfolio-events) and [`GET .../portfolio/snapshots`](/customer-api/reference/list-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`](/customer-api/reference/list-software-events) 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`](/customer-api/reference/list-orders) lists the customer's orders, newest first; [`GET /orders/{order}`](/customer-api/reference/get-order) reads one with its lines and refunds, and [`GET /orders/{order}/items`](/customer-api/reference/list-order-items) and [`/refunds`](/customer-api/reference/list-order-refunds) page them when there are many.

```json title="getOrder 200"
{
  "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`](/customer-api/reference/get-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`](/customer-api/reference/list-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`](/customer-api/reference/cancel-subscription) 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`](/customer-api/reference/resume-subscription) withdraws a scheduled cancellation. One whose saved card is gone renews on the default card, or the only one saved.
- [`PUT /subscriptions/{subscription}/plan`](/customer-api/reference/change-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](/customer-api/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](/customer-api/authentication#apps-the-store-hasnt-verified)).

## Account

### Profile

[`GET /v1/stores/{store}/profile`](/customer-api/reference/get-profile) reads the customer's name, locale, country and email address. [`PATCH /profile`](/customer-api/reference/update-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`](/customer-api/reference/list-contacts). Changing it takes two steps, both `contact:write`, which only a client the merchant created holds, so run them from your backend:

```bash
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`](/customer-api/reference/verify-contact) 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](/customer-api/limits#email-codes) per customer and per store.

### Saved cards

[`GET /v1/stores/{store}/billing_profile`](/customer-api/reference/get-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`](/customer-api/reference/set-default-payment-method) 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}`](/customer-api/reference/remove-payment-method) 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](/customer-api/authentication#refresh-and-revoke).

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