Entitlements

Overview

Entitlements connect features to plans, defining what customers get access to based on their subscription. A feature represents a capability (like API access or storage), and an entitlement maps that feature to a specific plan with a value. When a customer subscribes to a plan, they inherit all its entitlements.

How entitlements work

Define features (code + type)
        │
        ▼
Create entitlements ──► link feature to plan
        │                with a value
        ▼
Customer subscribes to plan
        │
        ▼
Query subscription entitlements
to check access and limits

Feature properties

Features are the building blocks of entitlements. Each feature has a type that determines how its value is interpreted.

Field	Type	Description
id	uuid	Unique feature identifier
code	string	Unique feature code (max 100 chars)
name	string	Display name (max 255 chars)
description	string?	Optional description
feature_type	string	One of: boolean, quantity, custom
created_at	datetime	Creation timestamp
updated_at	datetime	Last update timestamp

Feature types

Type	Use case	Example value
boolean	On/off feature flags	"true" or "false"
quantity	Numeric limits	"100" (e.g., 100 API calls)
custom	Freeform values	"premium", "us-east-1"

Create a feature

curl -X POST /v1/features/ \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "code": "api_access",
    "name": "API Access",
    "description": "Access to the REST API",
    "feature_type": "boolean"
  }'

Response (201):

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "code": "api_access",
  "name": "API Access",
  "description": "Access to the REST API",
  "feature_type": "boolean",
  "created_at": "2026-03-08T10:00:00Z",
  "updated_at": "2026-03-08T10:00:00Z"
}

The code must be unique across all features. Use descriptive codes like api_access, storage_gb, or support_tier.

Update a feature

curl -X PATCH /v1/features/api_access \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "REST API Access",
    "description": "Full access to the REST API"
  }'

Only name and description can be updated. The code and feature_type are immutable after creation.

Get a feature

curl /v1/features/api_access \
  -H "Authorization: Bearer $API_KEY"

Delete a feature

curl -X DELETE /v1/features/api_access \
  -H "Authorization: Bearer $API_KEY"

Returns 204 No Content on success.

List features

curl /v1/features/ \
  -H "Authorization: Bearer $API_KEY"

Supports pagination with skip and limit query parameters.

Feature plan counts

Get a summary of how many plans each feature is entitled to.

curl /v1/features/plan_counts \
  -H "Authorization: Bearer $API_KEY"

Entitlement properties

Entitlements map a feature to a plan with a specific value.

Field	Type	Description
id	uuid	Unique entitlement identifier
plan_id	uuid	The plan this entitlement belongs to
feature_id	uuid	The feature being entitled
value	string	The entitlement value (interpreted by feature type)
created_at	datetime	Creation timestamp
updated_at	datetime	Last update timestamp

Create an entitlement

curl -X POST /v1/entitlements/ \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "plan_id": "plan-uuid",
    "feature_id": "feature-uuid",
    "value": "true"
  }'

Response (201):

{
  "id": "660e8400-e29b-41d4-a716-446655440000",
  "plan_id": "plan-uuid",
  "feature_id": "feature-uuid",
  "value": "true",
  "created_at": "2026-03-08T11:00:00Z",
  "updated_at": "2026-03-08T11:00:00Z"
}

The value is always a string. For boolean features, use "true" or "false". For quantity features, use a numeric string like "100".

Update an entitlement

curl -X PATCH /v1/entitlements/{entitlement_id} \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "value": "false"
  }'

Only the value can be updated. To change the plan or feature mapping, delete and recreate the entitlement.

Delete an entitlement

curl -X DELETE /v1/entitlements/{entitlement_id} \
  -H "Authorization: Bearer $API_KEY"

Returns 204 No Content on success.

List entitlements

curl /v1/entitlements/ \
  -H "Authorization: Bearer $API_KEY"

Supports pagination with skip and limit query parameters.

Copy entitlements between plans

Copy all entitlements from one plan to another. This is useful when creating a new plan tier that builds on an existing one.

curl -X POST /v1/entitlements/copy \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "source_plan_id": "source-plan-uuid",
    "target_plan_id": "target-plan-uuid"
  }'

Response (201):

Returns an array of the newly created entitlements on the target plan. Existing entitlements on the target plan are not affected — duplicates may result if the target already has entitlements for the same features.

Check subscription entitlements

Query what a specific subscription is entitled to based on its plan.

curl /v1/subscriptions/{external_id}/entitlements \
  -H "Authorization: Bearer $API_KEY"

Response (200):

[
  {
    "id": "660e8400-e29b-41d4-a716-446655440000",
    "plan_id": "plan-uuid",
    "feature_id": "feature-uuid",
    "value": "true",
    "created_at": "2026-03-08T11:00:00Z",
    "updated_at": "2026-03-08T11:00:00Z"
  }
]

Use this endpoint in your application to check whether a customer has access to a feature or what their usage limits are.

Entity relationships

• Plans — entitlements belong to a plan and define what the plan includes
• Features — entitlements reference a feature and assign it a value
• Subscriptions — customers inherit entitlements through their active subscription’s plan

API endpoints

Method	Path	Description
POST	/v1/features/	Create a feature
GET	/v1/features/	List features
GET	/v1/features/{code}	Get a feature by code
PATCH	/v1/features/{code}	Update a feature
DELETE	/v1/features/{code}	Delete a feature
GET	/v1/features/plan_counts	Get feature plan counts
POST	/v1/entitlements/	Create an entitlement
GET	/v1/entitlements/	List entitlements
PATCH	/v1/entitlements/{entitlement_id}	Update an entitlement
DELETE	/v1/entitlements/{entitlement_id}	Delete an entitlement
POST	/v1/entitlements/copy	Copy entitlements between plans
GET	/v1/subscriptions/{external_id}/entitlements	Get subscription entitlements