---
title: "Entitlements"
permalink: "/docs/api-v1/entitlements"
description: "RevenueCat API v1 endpoint reference for Entitlements."
original_source: "openapi-spec/api-v1.yaml"
---
> **AI agents:** This is the Markdown version of a RevenueCat documentation page. For the complete documentation index, see [llms.txt](https://www.revenuecat.com/docs/llms.txt).
# Entitlements | REST API v1 Reference (1.0)
Download OpenAPI specification:[Download](https://www.revenuecat.com/docs/redocusaurus/openapi-v1-entitlements.yaml)
RevenueCat API v1 endpoint reference for Entitlements.
## Entitlements
Part of the [REST API v1 Reference](/docs/api-v1).
Operations about entitlements.
#### Endpoints
- [Grant an Entitlement](#tag/entitlements/operation/grant-a-promotional-entitlement) — `POST /subscribers/{app_user_id}/entitlements/{entitlement_identifier}/promotional`
- [Revoke Granted Entitlements](#tag/entitlements/operation/revoke-promotional-entitlements) — `POST /subscribers/{app_user_id}/entitlements/{entitlement_identifier}/revoke_promotionals`
## Grant an Entitlement
post/subscribers/{app_user_id}/entitlements/{entitlement_identifier}/promotional
https://api.revenuecat.com/v1/subscribers/{app_user_id}/entitlements/{entitlement_identifier}/promotional
Grants a Customer an entitlement. Does not override or defer a store transaction, applied simultaneously.
> Note: Requests with an `end_time_ms` within 2 hours of an active promotional entitlement’s expiration are treated as duplicates and won't extend it. This is common in sandbox renewal testing.
##### Authorizations:
_BearerAuth_
##### path Parameters
- `app_user_id` (required): string — The App User ID of the Customer.
- `entitlement_identifier` (required): string — The identifier for the entitlement you want to grant to the Customer.
##### Request Body schema: application/json
- `end_time_ms`: integer `int64` — A Unix epoch in milliseconds for when the entitlement should expire. The entitlement will always be granted immediately. If not provided then `duration` must be provided.
- `duration`: string Deprecated Enum: "daily" "three_day" "weekly" "two_week" "monthly" "two_month" "three_month" "six_month" "yearly" "lifetime" — How long of a duration to grant the entitlement for. If not provided then `end_time_ms` must be provided.
- `start_time_ms`: integer `int64` Deprecated — A Unix epoch in milliseconds used to determine the expiration date, by adding `duration` to `start_time_ms`. Regardless of what `start_time_ms` is set to, the entitlement will always be granted immediately. If `start_time_ms` is not provided, the `duration` will be added to the current time to determine the expiration date.
### Responses
**201**
Entitlement was successfully granted.
Returns the updated [Customer Info](/docs/api-v1/customer-info-model#tag/customer_info_model) for the Customer.
### Request samples
Content type
application/json
```json
{
"start_time_ms": 1709195668093,
"end_time_ms": 1709196532093
}
```
### Response samples
Content type
application/json
```json
{
"value": {
"request_date": "2019-07-26T17:40:10Z",
"request_date_ms": 1564162810884,
"subscriber": {
"entitlements": {
"pro_cat": {
"expires_date": null,
"grace_period_expires_date": null,
"product_identifier": "onetime",
"purchase_date": "2019-04-05T21:52:45Z"
}
},
"first_seen": "2019-02-21T00:08:41Z",
"management_url": "https://apps.apple.com/account/subscriptions",
"non_subscriptions": {
"onetime": [
{
"id": "cadba0c81b",
"is_sandbox": true,
"purchase_date": "2019-04-05T21:52:45Z",
"store": "app_store"
}
]
},
"original_app_user_id": "XXX-XXXXX-XXXXX-XX",
"original_application_version": "1.0",
"original_purchase_date": "2019-01-30T23:54:10Z",
"other_purchases": { },
"subscriptions": {
"annual": {
"auto_resume_date": null,
"billing_issues_detected_at": null,
"expires_date": "2019-08-14T21:07:40Z",
"grace_period_expires_date": null,
"is_sandbox": true,
"original_purchase_date": "2019-02-21T00:42:05Z",
"ownership_type": "PURCHASED",
"period_type": "normal",
"purchase_date": "2019-07-14T20:07:40Z",
"refunded_at": null,
"store": "play_store",
"store_transaction_id": "GPA.6801-7988-0152-76034..5",
"unsubscribe_detected_at": "2019-07-17T22:48:38Z"
},
"onemonth": {
"auto_resume_date": null,
"billing_issues_detected_at": null,
"expires_date": "2019-06-17T22:47:55Z",
"grace_period_expires_date": null,
"is_sandbox": true,
"original_purchase_date": "2019-02-21T00:42:05Z",
"ownership_type": "PURCHASED",
"period_type": "normal",
"purchase_date": "2019-06-17T22:42:55Z",
"refunded_at": null,
"store": "app_store",
"store_transaction_id": 1000000652379790,
"unsubscribe_detected_at": "2019-06-17T22:48:38Z"
},
"rc_promo_pro_cat_monthly": {
"auto_resume_date": null,
"billing_issues_detected_at": null,
"expires_date": "2019-08-26T01:02:16Z",
"grace_period_expires_date": null,
"is_sandbox": false,
"original_purchase_date": "2019-07-26T01:02:16Z",
"ownership_type": "FAMILY_SHARED",
"period_type": "normal",
"purchase_date": "2019-07-26T01:02:16Z",
"refunded_at": null,
"store": "promotional",
"store_transaction_id": "a42db3af39530cb82b17eaf9c6576393",
"unsubscribe_detected_at": null
}
}
}
}
}
```
## Revoke Granted Entitlements
post/subscribers/{app_user_id}/entitlements/{entitlement_identifier}/revoke_promotionals
https://api.revenuecat.com/v1/subscribers/{app_user_id}/entitlements/{entitlement_identifier}/revoke_promotionals
Revokes all granted entitlements for a given entitlement identifier and App User ID.
##### Authorizations:
_BearerAuth_
##### path Parameters
- `app_user_id` (required): string — The App User ID of the Customer.
- `entitlement_identifier` (required): string — The identifier for the entitlement you want to revoke from the Customer.
### Responses
**200**
Entitlement was successfully revoked.
Returns the updated [Customer Info](/docs/api-v1/customer-info-model#tag/customer_info_model) for the Customer.
### Response samples
Content type
application/json
```json
{
"value": {
"request_date": "2019-07-26T17:40:10Z",
"request_date_ms": 1564162810884,
"subscriber": {
"entitlements": {
"pro_cat": {
"expires_date": null,
"grace_period_expires_date": null,
"product_identifier": "onetime",
"purchase_date": "2019-04-05T21:52:45Z"
}
},
"first_seen": "2019-02-21T00:08:41Z",
"management_url": "https://apps.apple.com/account/subscriptions",
"non_subscriptions": {
"onetime": [
{
"id": "cadba0c81b",
"is_sandbox": true,
"purchase_date": "2019-04-05T21:52:45Z",
"store": "app_store"
}
]
},
"original_app_user_id": "XXX-XXXXX-XXXXX-XX",
"original_application_version": "1.0",
"original_purchase_date": "2019-01-30T23:54:10Z",
"other_purchases": { },
"subscriptions": {
"annual": {
"auto_resume_date": null,
"billing_issues_detected_at": null,
"expires_date": "2019-08-14T21:07:40Z",
"grace_period_expires_date": null,
"is_sandbox": true,
"original_purchase_date": "2019-02-21T00:42:05Z",
"ownership_type": "PURCHASED",
"period_type": "normal",
"purchase_date": "2019-07-14T20:07:40Z",
"refunded_at": null,
"store": "play_store",
"store_transaction_id": "GPA.6801-7988-0152-76034..5",
"unsubscribe_detected_at": "2019-07-17T22:48:38Z"
},
"onemonth": {
"auto_resume_date": null,
"billing_issues_detected_at": null,
"expires_date": "2019-06-17T22:47:55Z",
"grace_period_expires_date": null,
"is_sandbox": true,
"original_purchase_date": "2019-02-21T00:42:05Z",
"ownership_type": "PURCHASED",
"period_type": "normal",
"purchase_date": "2019-06-17T22:42:55Z",
"refunded_at": null,
"store": "app_store",
"store_transaction_id": 1000000652379790,
"unsubscribe_detected_at": "2019-06-17T22:48:38Z"
},
"rc_promo_pro_cat_monthly": {
"auto_resume_date": null,
"billing_issues_detected_at": null,
"expires_date": "2019-08-26T01:02:16Z",
"grace_period_expires_date": null,
"is_sandbox": false,
"original_purchase_date": "2019-07-26T01:02:16Z",
"ownership_type": "FAMILY_SHARED",
"period_type": "normal",
"purchase_date": "2019-07-26T01:02:16Z",
"refunded_at": null,
"store": "promotional",
"store_transaction_id": "a42db3af39530cb82b17eaf9c6576393",
"unsubscribe_detected_at": null
}
}
}
}
}
```
## Endpoint Reference
All API v1 resources, one page each. General concepts (authentication, request format, URL parameters) live on the [API v1 overview](/docs/api-v1).
- [Customer Info Model](/docs/api-v1/customer-info-model) — full schema reference
- [Customers](/docs/api-v1/customers) — 4 endpoints
- [Entitlements](/docs/api-v1/entitlements) — 2 endpoints
- [Offerings](/docs/api-v1/offerings) — 3 endpoints
- [Offerings Model](/docs/api-v1/offerings-model) — full schema reference
- [Transactions](/docs/api-v1/transactions) — 6 endpoints
## Response schema reference
Response examples above mirror the rendered API reference. These field definitions come from the same OpenAPI specification.
### Subscriber
- Used by `POST /subscribers/{app_user_id}/entitlements/{entitlement_identifier}/promotional (201) — Grant an Entitlement`
- Used by `POST /subscribers/{app_user_id}/entitlements/{entitlement_identifier}/revoke_promotionals (200) — Revoke Granted Entitlements`
- `request_date`: string — Date of the request in ISO 8601 format.
- `request_date_ms`: integer (format: `int64`) — Date of the request in milliseconds since Epoch.
- `subscriber`: object — Information about the Customer.
- `entitlements`: object — Dictionary of the entitlements of this Customer (including any expired entitlements).
- `first_seen`: string — The ISO 8601 datetime string corresponding to when the Customer was first seen by RevenueCat.
- `last_seen`: string — The ISO 8601 datetime string corresponding to when the Customer was last seen by RevenueCat.
- `management_url`: string — URL to manage the active subscription of the Customer. If the Customer has an active App Store subscription, this will point to the App Store. If the Customer has an active Play Store subscription, it will point there. Amazon subscriptions point to the Amazon subscription management page, Paddle subscriptions point to the Paddle Customer Portal, and RevenueCat Web Billing subscriptions point to the RevenueCat Web Billing Customer Portal. For Stripe Billing subscriptions, this returns the configured Stripe Customer Portal URL or a custom URL. If no Stripe Customer Portal URL is configured, this will be null. If there are no active subscriptions it will be null. If the Customer has multiple active subscriptions for different platforms, this will take the value of the OS in the `X-Platform` header into consideration: - If the request was made on an OS for which there are active subscriptions, this will return the URL for the store that matches the header. - If the request was made on a different OS or the OS was not included in the X-Platform header, this will return the URL for the store of the subscription with the farthest future expiration date.
- `non_subscriptions`: object — Non-subscription purchases of the Customer, keyed by the product identifier.
- `original_app_user_id`: string — The App User ID under which this Customer was first known to RevenueCat.
- `original_application_version`: string — *Only available on iOS*. This will be `null` until an iOS receipt is sent for the Customer. After a receipt has been sent, it will indicate the first App Store version of your app that the Customer installed.
- `original_purchase_date`: string — **Only available on iOS**. The date that the app was first purchased/downloaded by the Customer. Will be `null` if no receipt is recorded for the Customer. Useful for [Migrating Subscriptions](/docs/migrating-to-revenuecat/migrating-existing-subscriptions).
- `other_purchases`: object
- `subscriber_attributes`: object — A dictionary of any Attributes set on this Customer. **Only included in responses to requests made with a secret API key**.
- `subscriptions`: object — Subscription purchases of the Customer, keyed by the product identifier.