Entitlements

Overview

You use entitlements to control how much access your customers have to the features in your environment. Once you create the entitlement and assign it to your customer, it allows them to access or use those specific features or granular product functionality.

Within Recurly, entitlements are granted through one or more associations with recurring products such as Plans and Item Add-ons. You can create an unlimited number of entitlements in your Recurly account. For your convenience, you can easily set them up in the Recurly user interface.

Creating an Entitlement

You create entitlements entirely within the Recurly Admin user interface. To create a new association to an entitlement you’ll need to define the following attributes: Name, Code, Description, and Grantors. See below for more information about each.

Entitlement Name

This is the short name of the entitlement. It can be used to provide a summary of the feature functionality that the entitlement provides to your customers. The name will not appear on the subscribers invoice or on Hosted Payment Pages. It is limited to 255 characters.

Entitlement Code

This is the entitlement’s unique Recurly identifier. The entitlement code can be used to map the entitlement to the gated functionality within your application (for example feature flags).

Entitlement Description

This is a description of the entitlement that can be used to provide your customers with additional information about the gated feature.

Entitlement Grantors

These are the recurring products (for example, Plans, Items) that “grant” the entitlement when a customer purchases them through a subscription. An Entitlement can be associated with one or more products and a product can be associated with many different Entitlements.

Note: Although associations to recurring products are optional, if an entitlement does not have any product associations, it can not be used in practice.

If an entitlement is associated with a Plan, any “valid” subscriptions created from that Plan will grant the entitlement to customers who have purchased that subscription.

If an entitlement is associated with an Item, any “valid” subscriptions that have an Add-on based on that Item will grant the entitlement to the customer, even if the Plan is not associated with the entitlement.

📘

Entitlement grants are only available through recurring purchases (for example, subscriptions) and are not available via one time purchases. If you would like to see support for one time purchases, please send a feature request to the Recurly support team.

Updating Entitlements

Updates made to entitlements take effect immediately. Make any updates to any Plan or Item associations for the entitlement in the user interface. Any subsequent calls to the Entitlements API will reflect the new associations.

Deleting Entitlements

Deleting an entitlement will immediately remove the entitlement from the system and will not be returned in any subsequent Entitlement checks via the API. Make any updates in the user interface

Retrieving Entitlements via Recurly API

Entitlements are retrieved via Recurly API v3 by requesting any “active” entitlements for a specific customer account. Recurly API v2 is also supported.

An entitlement is granted if the following conditions are satisfied:

• The customer has a recurring purchase (for example, a subscription) of a Plan or Item Add-on that is associated with the entitlement
• The recurring purchase meets certain criteria (for example, the subscription is “active”)

Filtering criteria for subscription purchases

By default, the API will return all entitlements for a customer Account that are linked to subscriptions in an ‘active’ or ‘canceled’ state. The default filtering can be overridden by passing a parameter to the API denoting the valid states that you would prefer. This functionality provides the flexibility required for you to tailor “valid” purchases to your exact requirements.

Pricing and Availability

Entitlements are available to Elite plans only