> ## Documentation Index
> Fetch the complete documentation index at: https://docs.bouclay.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Entitlements

> Gate features on what a customer pays for, without writing billing logic in your app

> [!NOTE]
>
> Early access. Write to [hello@bouclay.com](mailto:hello@bouclay.com) to have it turned on for your account.

An **entitlement** is something a customer can do because of what they pay for: "export PDFs", "up to 5 projects". You attach entitlements to plans and products once. Your app then asks Bouclay one question: can this customer do this right now?

This keeps billing rules out of your code. When a customer upgrades, pauses or stops paying, the answer changes on its own.

## Two kinds

| Type | Answers | Example |
| - | - | - |
| `feature` | Yes or no. | `pdf_export` |
| `limit` | Yes or no, plus a number, and how much is used when a meter backs it. | `projects`, up to 5 |

## Set them up

In the dashboard, open **Catalog → Entitlements**, create each one with a code (such as `pdf_export`), and grant it to the plans or products that include it. A plan's grant can carry a different number for a limit, so "Starter" can allow 5 projects and "Team" 50.

## Check one entitlement

```bash theme={null}
curl https://bouclay.com/api/v1/customers/ctm_…/entitlements/pdf_export \
  -H "Authorization: Bearer $BOUCLAY_KEY"
```

`data.granted` is `true` or `false`. A code the customer doesn't hold is a `200` with `granted: false`, not a `404`, so "no" never looks like a missing customer.

To get everything at once, call `GET /customers/{id}/entitlements`.

> [!WARNING]
>
> Check on your server, not in the browser. A check in the browser can be skipped by anyone who opens the developer tools.

## Which subscriptions grant access

| Subscription status | Grants access |
| - | - |
| `trialing` | Yes |
| `active` | Yes |
| `past_due` | Yes. A failed renewal is a payment problem; locking out a paying customer while Bouclay retries turns a recoverable decline into a cancellation. |
| `paused` | No. That is what pausing is for, including a suspension for an overdue invoice. |
| `incomplete`, `incomplete_expired`, `canceled` | No |

Entitlements never look at invoices or payments directly. An unpaid invoice doesn't revoke access by itself: failed-payment recovery does, by moving the subscription's status. See [Failed payments](https://docs.bouclay.com/billing/failed-payments.md).

## Keep a cache in step

Calling Bouclay on every page view is fine for low traffic. For more, cache the answer and refresh it from webhooks: every `subscription.*` event carries `data.object.customer.entitlements`, the codes the customer holds right now. See [Webhooks](https://docs.bouclay.com/integrate/webhooks.md).

## Limits backed by a meter

A `limit` with a meter reports how much is used this period, so you can show "3 of 5 projects" and refuse the sixth. `GET /customers/{id}/usage` shows each meter's `limit` and `remaining` too. Bouclay never blocks usage itself: your app decides when to say no.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.