Skip to content

Customers' access

Grant a customer a product without a purchase, see what they hold, and take it back, for cause too.

Updated

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 and a token with customer:read and customer:write, and transaction:write to revoke for cause.

Grant access

POST /grants grants a product’s tier to a customer, named by id or by email:

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"
}'
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:

{
  "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 on tier.

While the business is paused for its plan, every grant is refused with the reason paused (see errors).

See what a customer holds

GET /grants lists grants, filtered by customer, product, source or whether they are live:

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

GET /entitlements answers what each customer may reach now, from all their grants together, within a customer or a product.

Take it back

POST /grants/{grant}/revoke ends a grant now, with a reason:

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"
}'
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:

{
  "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: GET /entitlements shows what is left.

Refunding money is another thing: POST /orders/{order}/refunds 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, POST /revocations 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:

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"
  }
}'
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:

{
  "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 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 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 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. GET /revocations 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: POST /revocations/{revocation}/refund/retry 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 GET /orders/{order} and GET /orders/{order}/items 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 GET /orders/{order} and GET /orders, 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.

Type to search…

↑↓ navigate↵ selectEsc close