Skip to main content
Early access. Write to 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

​
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

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

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.

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

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