---
title: "Customers' access"
description: "Grant a customer a product without a purchase, see what they hold, and take it back, for cause too."
---

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

# Customers' access

A customer reaches a product through a grant: a purchase makes one, and so can you, for a workshop attendee, a partner or a refund made outside Sherpo. This guide grants, lists and revokes access. It uses the `sherpo` helper from [your first call](/merchant-api/first-call) and a token with `customer:read` and `customer:write`, and `transaction:write` to revoke for cause.

## Grant access

<a href="/merchant-api/reference/grant-access/">`POST /grants`</a> grants a product's tier to a customer, named by id or by email:

```bash
curl -X POST 'https://api.sherpo.io/merchant/v1/stores/STORE_ID/grants' \
  -H "Authorization: Bearer $SHERPO_TOKEN" \
  -H 'Idempotency-Key: grant-ada-watercolor' \
  -H 'Content-Type: application/json' \
  -d '{
  "customer": {
    "email": "ada@example.com"
  },
  "product": {
    "slug": "watercolor-basics"
  },
  "tier": {
    "id": "b2d4f6a8-1c3e-4a5b-8d7f-9e0a1b2c3d4e"
  },
  "ends_at": "2027-11-03T00:00:00Z",
  "reason": "Workshop attendee"
}'
```

```js
const answer = await sherpo('POST', '/v1/stores/STORE_ID/grants', {
  body: {
    "customer": {
      "email": "ada@example.com"
    },
    "product": {
      "slug": "watercolor-basics"
    },
    "tier": {
      "id": "b2d4f6a8-1c3e-4a5b-8d7f-9e0a1b2c3d4e"
    },
    "ends_at": "2027-11-03T00:00:00Z",
    "reason": "Workshop attendee"
  },
  key: 'grant-ada-watercolor',
});
```

Answers `200`, abridged:

```json
{
  "id": "4b3a2918-0f7e-4d6c-9b5a-4c3b2a190807",
  "customer": {
    "id": "7e6d5c4b-3a29-4180-9f7e-6d5c4b3a2918",
    "name": "Ada Lovelace",
    "email": "ada@example.com",
    "phone": null,
    "erased": false
  },
  "product": {
    "id": "6f1c2a9e-4b7d-4e2a-9c51-0d3e8b7a1f42",
    "slug": "watercolor-basics",
    "path": "/p/watercolor-basics",
    "url": "https://shop.example.com/p/watercolor-basics",
    "title": "Watercolor basics",
    "category": "course",
    "deleted": false
  },
  "tier": {
    "id": "b2d4f6a8-1c3e-4a5b-8d7f-9e0a1b2c3d4e",
    "name": "Full course"
  },
  "source_kind": "manual",
  "grant_reason": "Workshop attendee",
  "ends_at": "2027-11-03T00:00:00.000Z",
  "end_reason": "lapse",
  "status": "active",
  "revocable": true
}
```

- **By email**, the grant reaches whoever signs in with that address. Someone who isn't a customer yet becomes one, invited, and finds the product when they first sign in.
- **`tier`** is the tier the grant opens, or `null` for a product without tiers.
- **`ends_at`** ends the grant at that time; leave it out for access that lasts.
- A customer who already holds that tier or a higher one, for at least as long, answers `409` [`conflict`](/merchant-api/errors#conflict) on `tier`.

While the business is paused for its plan, every grant is refused with the reason `paused` (see [errors](/merchant-api/errors#not_permitted)).

## See what a customer holds

<a href="/merchant-api/reference/list-grants/">`GET /grants`</a> lists grants, filtered by customer, product, source or whether they are live:

```bash
curl -g 'https://api.sherpo.io/merchant/v1/stores/STORE_ID/grants?filter[customer_id]=7e6d5c4b-3a29-4180-9f7e-6d5c4b3a2918&filter[product_id]=6f1c2a9e-4b7d-4e2a-9c51-0d3e8b7a1f42' \
  -H "Authorization: Bearer $SHERPO_TOKEN"
```

```js
const answer = await sherpo('GET', '/v1/stores/STORE_ID/grants', {
  query: [
    ['filter[customer_id]', '7e6d5c4b-3a29-4180-9f7e-6d5c4b3a2918'],
    ['filter[product_id]', '6f1c2a9e-4b7d-4e2a-9c51-0d3e8b7a1f42'],
  ],
});
```

Each grant answers its `status`: `scheduled` before it begins, `active` while it lets the customer in, then `expired`, `revoked`, `refunded` or `ended` once it's over. `revocable` says whether you can still revoke it.

<a href="/merchant-api/reference/list-entitlements/">`GET /entitlements`</a> answers what each customer may reach now, from all their grants together, within a customer or a product.

## Take it back

<a href="/merchant-api/reference/revoke-grant/">`POST /grants/{grant}/revoke`</a> ends a grant now, with a reason:

```bash
curl -X POST 'https://api.sherpo.io/merchant/v1/stores/STORE_ID/grants/4b3a2918-0f7e-4d6c-9b5a-4c3b2a190807/revoke' \
  -H "Authorization: Bearer $SHERPO_TOKEN" \
  -H 'Idempotency-Key: revoke-4b3a2918-0f7e-4d6c-9b5a-4c3b2a190807' \
  -H 'Content-Type: application/json' \
  -d '{
  "reason": "Asked to leave the course"
}'
```

```js
const answer = await sherpo('POST', '/v1/stores/STORE_ID/grants/4b3a2918-0f7e-4d6c-9b5a-4c3b2a190807/revoke', {
  body: {
    "reason": "Asked to leave the course"
  },
  key: 'revoke-4b3a2918-0f7e-4d6c-9b5a-4c3b2a190807',
});
```

Answers `200`, abridged:

```json
{
  "id": "4b3a2918-0f7e-4d6c-9b5a-4c3b2a190807",
  "end_reason": "manual",
  "status": "revoked",
  "revocable": false
}
```

The grant ends at once, a purchase's grant too, and answers `status: "revoked"`. The `grant.revoked` webhook says so with the cause `merchant`. No email goes to the customer. They keep what their other grants open: <a href="/merchant-api/reference/list-entitlements/">`GET /entitlements`</a> shows what is left.

Refunding money is another thing: <a href="/merchant-api/reference/record-refund/">`POST /orders/{order}/refunds`</a> records a refund, and it ends the access the purchase gave once refunds cover its whole payment, unless the store's `refund_revokes_access` setting is off. A partial refund leaves access as it is, until you revoke the grant.

## Revoke for cause

For a customer who broke your terms, committed fraud, lost you a dispute or abused the product, <a href="/merchant-api/reference/create-revocation/">`POST /revocations`</a> takes their access away and tells them. Name a purchase as `order` or a single grant as `grant`, and the `cause`. It needs `transaction:write`:

```bash
curl -X POST 'https://api.sherpo.io/merchant/v1/stores/STORE_ID/revocations' \
  -H "Authorization: Bearer $SHERPO_TOKEN" \
  -H 'Idempotency-Key: revoke-9a8b7c6d-5e4f-4321-8a9b-0c1d2e3f4a5b' \
  -H 'Content-Type: application/json' \
  -d '{
  "order": {
    "id": "9a8b7c6d-5e4f-4321-8a9b-0c1d2e3f4a5b"
  },
  "cause": "terms_violation",
  "note": "Course shared in a public group",
  "message": "<p>Your purchase was shared publicly, which our terms forbid.</p>",
  "refund": {
    "amount": 2000,
    "via": "stripe"
  }
}'
```

```js
const answer = await sherpo('POST', '/v1/stores/STORE_ID/revocations', {
  body: {
    "order": {
      "id": "9a8b7c6d-5e4f-4321-8a9b-0c1d2e3f4a5b"
    },
    "cause": "terms_violation",
    "note": "Course shared in a public group",
    "message": "<p>Your purchase was shared publicly, which our terms forbid.</p>",
    "refund": {
      "amount": 2000,
      "via": "stripe"
    }
  },
  key: 'revoke-9a8b7c6d-5e4f-4321-8a9b-0c1d2e3f4a5b',
});
```

Answers `201`, abridged:

```json
{
  "id": "6d5e4f3a-2b1c-4d0e-9f8a-7b6c5d4e3f2a",
  "customer_id": "7e6d5c4b-3a29-4180-9f7e-6d5c4b3a2918",
  "order_id": "9a8b7c6d-5e4f-4321-8a9b-0c1d2e3f4a5b",
  "grant_id": null,
  "product_ids": [
    "6f1c2a9e-4b7d-4e2a-9c51-0d3e8b7a1f42"
  ],
  "cause": "terms_violation",
  "refund": {
    "via": "stripe",
    "amount": 2000,
    "currency": "eur",
    "exponent": 2,
    "settlement_id": "2e3f4a5b-6c7d-4e8f-9a0b-1c2d3e4f5a6b",
    "refund_id": null,
    "status": "pending"
  }
}
```

- **`cause`** is `terms_violation`, `fraud`, `chargeback`, `abuse` or `other`. **`note`** is for your team, up to 500 characters, and never reaches the customer.
- **Access ends at once, everywhere.** Every grant the customer holds on the products ends, not only the one you named, and their subscriptions to them end now instead of renewing. Revoking a purchase also ends the tickets its buyer got for guests. Each grant sends `grant.revoked` with the cause `merchant`, and the revocation sends `access.revoked`.
- **The customer is always emailed** that their access was revoked, whatever the store's customer messages say. The email goes about two minutes later, so a Stripe refund that goes through at once reads as made rather than on its way. It closes with your business's contact address, the one your legal pages name, and says they can write to it within 30 days about any claim; without an address it names none. **`message`** adds your own words to that email, in [rich text](/merchant-api/rich-text) with no blocks: formatting, colors, links, lists, code, quotes and tables, but no images, media, products or files. A message nested more than 8 levels deep or made of more than 2,000 parts (each paragraph, list item, table cell and run of text counts) answers `400` [`invalid`](/merchant-api/errors#invalid) on `message`, since the email couldn't show it whole.
- **`refund`** gives money back with it, off the payment behind the order or grant. Leave it out and no money moves. `via: "stripe"` sends it through Stripe, for a payment taken at checkout on Stripe, as one Stripe refund per revoked product; `via: "recorded"` records money you already gave back elsewhere, with its `processor_ref` if you have one. Name the payment as `settlement` when the order has more than one. `amount` can't exceed what is left on the payment for the revoked products, and an order with no room left for every refund it makes answers `409` on `items`.
- A Stripe refund still on its way for one of the products on that payment answers `409` on `status` as `refund_owed`, and one that failed and waits for a retry as `refund_failed`: retry or settle it first.
- A guest's ticket was paid for by its buyer, so revoking a guest's grant takes no refund (`400` `invalid` on `refund`), and the revocation names no order: the buyer's order and their own access stay as they are.
- A `chargeback` takes no refund: the lost dispute is recorded as one already.
- A customer with nothing left to end on the products answers `409` [`conflict`](/merchant-api/errors#conflict) on `status`.

The order stays, and its `revocation` names the latest one. Its `failed_revocations` lists, latest first, up to 5 of its revocations whose Stripe refund failed, with their `total`, so an earlier failure stays in sight after a later revocation. <a href="/merchant-api/reference/list-revocations/">`GET /revocations`</a> lists them all, newest first, of one `customer` or one `order` when named. A refund through Stripe reads `pending` until Stripe confirms it, then `refunded`, or `failed`: <a href="/merchant-api/reference/retry-revocation-refund/">`POST /revocations/{revocation}/refund/retry`</a> sends a failed one again, answering the revocation, whose refund still reads `failed` while a part of it that can't go yet stays failed. A refund that failed because the payment no longer has its amount left, as when money went back on it meanwhile, sends only once that amount is there again, and a retry before then answers `409` on `status` as `nothing_left`. A refund that failed because the order holds as many refunds as it can reads `nothing_left` too. A recorded refund the processor later failed reads `taken_back`, and the email, if it hasn't gone yet, names no refund; neither does it while a Stripe refund failed.

The revocation's email tells the refund as it stands when the email goes. A refund the revocation made waits for that email, and one it tells as made sends no `refund.processed` email of its own. One it tells as on its way, or doesn't tell, because a Stripe refund had failed then or the email didn't go, sends its own `refund.processed` email once it lands, as any refund does.

Each line of <a href="/merchant-api/reference/get-order/">`GET /orders/{order}`</a> and <a href="/merchant-api/reference/list-order-items/">`GET /orders/{order}/items`</a> carries `revocable`: whether revoking the order would end anything on that line, its customer's grant or running subscription of the line's product or a guest's ticket to it. The order itself, in <a href="/merchant-api/reference/get-order/">`GET /orders/{order}`</a> and <a href="/merchant-api/reference/list-orders/">`GET /orders`</a>, carries `revocable`: whether revoking it would end anything, its customer's grants or running subscriptions on its products or its guests' tickets. While it reads `false`, a revocation of the order answers `409` on `status` as `revoked`.

Source: https://docs.sherpo.io/merchant-api/guides/customer-access/index.mdx
