Core Resources

Entitlements

A Customer Entitlement represents access to a specific entitlement feature granted to a customer, typically driven by an active subscription. While you own and host your content, Recharge provides the logic engine that determines a customer's real-time access status based on their active subscriptions.

12 additions in V2, marked New

Everything marked New also works when you send X-Recharge-Version: 2021-11.

Endpoints

GET/customer_entitlements
POST/customer_entitlements
PUT/customer_entitlements/{id}
DELETE/customer_entitlements/{id}

#The customer entitlement object

A Customer Entitlement represents access to a specific entitlement feature granted to a customer, typically driven by an active subscription.

Attributes

idinteger
Unique numeric identifier for the customer entitlement.
customer_idinteger
Unique numeric identifier for the customer associated with this entitlement.
entitlement_feature_idinteger
Unique numeric identifier for the entitlement feature being granted.
granted_by_idstring
The ID of the entity that granted this entitlement (e.g. the purchase item ID or API token ID).
granted_by_typestring
How the entitlement was granted to the customer.
Possible values
purchase_itemapiuserstore_ownerrecharge_staff_user_emailinternal
expires_atdatetime
The date and time at which the entitlement expires. If null, the entitlement does not expire.
created_atdatetime
The date and time at which the customer entitlement was created.
updated_atdatetime
The date and time at which the customer entitlement was last updated.
deleted_atdatetime
The date and time at which the customer entitlement was deleted. If null, the entitlement has not been deleted.
includeobjectNew
An object containing the related resources requested with the include query parameter.
Only returned when the include query parameter is passed.
Show child attributesHide child attributes18 new
- entitlement_featureobjectNew
  The entitlement feature granted by the customer entitlement.
  Only returned when include=entitlement_feature is passed.
  Show child attributesHide child attributes77 new
  - idintegerNew
    Unique numeric identifier for the entitlement feature.
  - lookup_keystringNew
    A unique key that identifies the entitlement feature.
  - namestringNew
    The name of the entitlement feature.
  - descriptionstring · nullableNew
    The description of the entitlement feature.
  - created_atdatetimeNew
    The date and time at which the entitlement feature was created.
  - updated_atdatetimeNew
    The date and time at which the entitlement feature was last updated.
  - deleted_atdatetime · nullableNew
    The date and time at which the entitlement feature was deleted. If null, the entitlement feature has not been deleted.

The customer entitlement object

{
  "customer_entitlement": {
    "id": 72,
    "customer_id": 226536730,
    "entitlement_feature_id": 21,
    "granted_by_id": "747832689",
    "granted_by_type": "purchase_item",
    "expires_at": "2026-02-06T05:59:59+00:00",
    "created_at": "2026-01-05T15:11:23+00:00",
    "deleted_at": null,
    "updated_at": "2026-01-05T15:11:23+00:00"
  }
}

#List customer entitlements

GET/customer_entitlements

Retrieve all entitlements for a customer.

Scoperead_customers

Deleted customer entitlements are not returned. Results are sorted by id in descending order.

Query parameters

cursorstringNew
Return either the next or previous page of customer entitlements using the next_cursor or previous_cursor value from a previous response. Only limit can be passed together with cursor.
customer_idstring
The ID of the customer to retrieve entitlements for.
includestring
Optionally include related resources. Use include=entitlement_feature to embed the entitlement feature details (name, id, lookup_key, etc.) in each result.
Possible values
entitlement_feature
limitstringNew
The amount of results. Default is 50 while the maximum is 250.
pagestringNew
The page to show. Cursor pagination is recommended instead.

GET/customer_entitlements

curl 'https://api.rechargeapps.com/customer_entitlements?customer_id=226536730' \
  -H 'X-Recharge-Version: v2' \
  -H 'X-Recharge-Access-Token: your_api_token'

Response

[
  {
    "id": 72,
    "customer_id": 226536730,
    "entitlement_feature_id": 21,
    "granted_by_id": "747832689",
    "granted_by_type": "purchase_item",
    "expires_at": "2026-02-06T05:59:59+00:00",
    "created_at": "2026-01-05T15:11:23+00:00",
    "deleted_at": null,
    "updated_at": "2026-01-05T15:11:23+00:00"
  }
]

#Create a customer entitlement

POST/customer_entitlements

Create a new entitlement for a customer.

Scopewrite_customer_entitlements

The expires_at key must be present in the request; send null for an entitlement that does not expire. A date-only value (for example 2027-12-31) expires at the end of that day in the store's timezone.

The write_customer_entitlements scope cannot be selected when creating an API token or app. Contact Recharge to have it enabled.

Body parameters

customer_idintegerRequired
The ID of the customer to grant the entitlement to.
entitlement_feature_idintegerRequired
The ID of the entitlement feature to grant.
expires_atdatetimeRequired
The date and time at which the entitlement expires. If null or omitted, the entitlement does not expire.

POST/customer_entitlements

curl -X POST 'https://api.rechargeapps.com/customer_entitlements' \
  -H 'X-Recharge-Version: v2' \
  -H 'Content-Type: application/json' \
  -H 'X-Recharge-Access-Token: your_api_token' \
  -d '{
  "customer_id": 12345,
  "entitlement_feature_id": 56789,
  "expires_at": "2026-06-30T00:00:00+00:00"
}'

Response

{
  "customer_entitlement": {
    "id": 74,
    "customer_id": 12345,
    "entitlement_feature_id": 56789,
    "granted_by_id": "385088",
    "granted_by_type": "api",
    "expires_at": "2026-07-01T04:59:59+00:00",
    "created_at": "2026-01-07T04:20:40+00:00",
    "deleted_at": null,
    "updated_at": "2026-01-07T04:20:40+00:00"
  }
}

#Update a customer entitlement

PUT/customer_entitlements/{id}

Update the expiration date of a customer's entitlement.

Scopewrite_customer_entitlements

The write_customer_entitlements scope cannot be selected when creating an API token or app. Contact Recharge to have it enabled.

Body parameters

expires_atdatetimeRequired
The updated date and time at which the entitlement expires. Set to null to make the entitlement non-expiring.

PUT/customer_entitlements/{id}

curl -X PUT 'https://api.rechargeapps.com/customer_entitlements/74' \
  -H 'X-Recharge-Version: v2' \
  -H 'Content-Type: application/json' \
  -H 'X-Recharge-Access-Token: your_api_token' \
  -d '{
  "expires_at": "2026-12-31T00:00:00+00:00"
}'

Response

{
  "customer_entitlement": {
    "id": 74,
    "customer_id": 210979738,
    "entitlement_feature_id": 21,
    "granted_by_id": "385088",
    "granted_by_type": "api",
    "expires_at": "2026-12-31T04:59:59+00:00",
    "created_at": "2026-01-07T04:20:40+00:00",
    "deleted_at": null,
    "updated_at": "2026-01-07T04:31:14+00:00"
  }
}

#Delete a customer entitlement

DELETE/customer_entitlements/{id}

Delete a customer's entitlement.

Scopewrite_customer_entitlements

The write_customer_entitlements scope cannot be selected when creating an API token or app. Contact Recharge to have it enabled.

DELETE/customer_entitlements/{id}

curl -X DELETE 'https://api.rechargeapps.com/customer_entitlements/74' \
  -H 'X-Recharge-Version: v2' \
  -H 'X-Recharge-Access-Token: your_api_token'

Response

{}