An entitlement is what a buyer organization's plan lets it do: which capabilities it has, and how much of each is left. Your backend asks the Server SDK before it does the work, and gets a ruling back within your own process, with no network call.
Ask before you do the work
const ruling = shiprev.adjudicate({
organization_id: claims.organization_id, // from the verified session token only
capability_key: 'report_exports',
quantity: 1,
operation: 'write',
});
if (!ruling.allowed) return { status: 403, reason: ruling.reason };The organization always comes from the verified session token, never from a header, parameter or body field the caller controls. With NestJS, two guards and one decorator do the same on each route; Protect routes shows both ways.
What a ruling tells you
| Field | What it tells you |
|---|---|
allowed | Whether to go ahead |
remaining | What is left of the allowance in the current period, before this call |
limit | The allowance of the current period |
reason | Why the call was refused, such as quota_exhausted |
source | Where the ruling came from: the local mirror, the region, the last snapshot while offline, or a default when there was no basis |
Rulings covers how to read each field and answer each refusal.
When the allowance runs out
Each capability has an overage policy, as part of its definition. Beyond the allowance, adjudicate() refuses with quota_exhausted whatever the policy, because whether an overage can be paid for is known only to your application's region; adjudicateAsync() asks the region in that case. The region rules by the policy:
| Overage policy | Beyond the allowance |
|---|---|
| Block | Refused with quota_exhausted, unless the capability has an overage price and the organization's wallet balance covers the cost; then allowed, with remaining at 0, and the cost is taken from the wallet when the usage is reported |
| Prompt to upgrade | The same as Block |
| Allow and bill | Allowed, with remaining at 0, when the capability has an overage price and the organization's wallet balance covers the cost; the cost is taken from the wallet when the usage is reported. Otherwise refused with quota_exhausted |
With Block and Prompt to upgrade, the region also refuses a write with quota_exhausted, even within the allowance, while usage of the capability in the current period has been left unpaid; this stops once credits are next added to the wallet. Overage policies covers the overage price and how to set the policy.
Read or write
Every ruling names an operation. Anything that consumes quota, changes state or costs money is a write; a check that only needs the capability granted can be a read with quantity: 0. The two differ when the client cannot reach your application's region: reads keep working from the last snapshot, writes are refused with disconnected_write. Snapshot, mirror and offline covers each client state, how plan changes reach your process without a restart, and how to choose the operation route by route.
Show it in your frontend
The React components PricingTable and UsageMeter show an end user the plans they can choose and what is left of their allowance. They only display: the decision is always your backend's. See Show it in your frontend.
Where to go from here
Protect routes
Watch the allowance run out
Rulings reference
Client state
The objects of this product, and how they meet the other three on one buyer organization, are in How ShipRev works. The product page is Entitlements.