> ## Documentation Index
> Fetch the complete documentation index at: https://docs.paypal.ai/llms.txt
> Use this file to discover all available pages before exploring further.
# Create features
Limited Release
A feature defines what customers can access and do in your application. Each feature connects the following:
* Pricing plans through entitlements that assign privilege values for each plan level.
* Subscriptions through entitlement overrides that customize access for individual customers.
**How features, privileges, and entitlements work together**
* Your feature defines what customers can access. For example, you create an API access feature.
* Privileges set specific limits and permissions within each feature. For example, you add a `rate_limit` privilege to the API access feature to control the number of requests.
* When you add a feature to a plan, you set specific values for each privilege. These values are called entitlements. For example, you set the `rate_limit` privilege to 1,000 requests per day in your Basic plan and 100,000 requests per day in your Premium plan.
* Subscription entitlements override plan entitlements for individual customers. For example, you set a specific customer's `rate_limit` to 50,000 requests per day even though they are on the Basic plan.
## 1. Understand feature configuration
Before you create a feature, you can plan these configuration details for your application. Then, you can make a POST call to the Create feature endpoint to send the information to PayPal.
**Feature identification**
* **Name**: Choose a human-readable identifier that describes the feature.
* **Code**: Create a unique identifier you use in API calls. Ensure this code is unique across all features in your account.
* **Description**: Provide details about what the feature enables or restricts.
**Privilege identification**
* **Name**: Choose a human-readable identifier that describes the privilege.
* **Code**: Create a unique identifier for the privilege within the feature.
## 2. Create features
You can create a basic feature, or include [privileges](#feature-with-privileges) to define specific access controls.
Use a valid access token and make a POST call to the `/v1/commerce/billing/features` endpoint. Include the following parameters:
| Parameter | Action |
| ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------- |
| `code`
Required, string | Set a unique code to identify this feature. |
| `name`
string | Provide a human-readable name for the feature. |
| `description`
string | Provide a description of what functionality the feature provides or restricts. |
| `privileges[]`
array | Add privilege configurations to define specific access controls within the feature. |
| `privileges[].code`
Required when privileges\[] provided, string | Set a unique code to identify this privilege within the feature. |
| `privileges[].name`
string | Provide a human-readable name for the privilege. |
| `privileges[].value_type`
string | Set to `INTEGER` for numeric limits, `BOOLEAN` for on/off toggles, `SELECT` for predefined options, or `STRING` for text values. |
| `privileges[].config`
Required for SELECT type, object | Provide a `select_options` array with the available choices for SELECT type privileges. |
For information on all parameters, see API reference.
### Feature without privileges
You can create a basic feature without any privileges.
```shell lines title="Sample request" theme={null}
curl -X POST -L 'https://api-m.sandbox.paypal.com/v1/commerce/billing/features' \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer ' \
-d '{
"name": "API access",
"code": "api_access",
"description": "Access to REST API endpoints"
}'
```
```json lines title="Sample response" theme={null}
{
"code": "api_access",
"name": "API access",
"description": "Access to REST API endpoints",
"created_at": "2025-01-28T10:00:00Z"
}
```
### Feature with privileges
You can create a feature with associated privileges to enable fine-grained control.
**Basic privileges**
You can use basic privilege types when you want to define simple access controls for features.
```shell lines expandable title="Sample request" theme={null}
curl -X POST -L 'https://api-m.sandbox.paypal.com/v1/commerce/billing/features' \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer ' \
-d '{
"code": "seats",
"name": "Number of seats",
"description": "Number of users allowed in the account",
"privileges": [
{
"code": "max",
"name": "Maximum seats",
"value_type": "INTEGER"
},
{
"code": "max_admins",
"name": "Maximum admin users",
"value_type": "INTEGER"
},
{
"code": "root",
"name": "Allow root user",
"value_type": "BOOLEAN"
}
]
}'
```
```json lines title="Sample response" theme={null}
{
"code": "seats",
"name": "Number of seats",
"description": "Number of users allowed in the account",
"privileges": [
{
"code": "max",
"name": "Maximum seats",
"value_type": "INTEGER"
},
{
"code": "max_admins",
"name": "Maximum admin users",
"value_type": "INTEGER"
},
{
"code": "root",
"name": "Allow root user",
"value_type": "BOOLEAN"
}
],
"created_at": "2025-01-28T10:00:00Z"
}
```
**Fixed-option privileges**
Set `value_type` to `SELECT` when you want customers to choose from a predefined list of options. When you use `SELECT`, ensure you also provide a `config.select_options` array with the available choices.
```shell lines expandable title="Sample request" theme={null}
curl -X POST -L 'https://api-m.sandbox.paypal.com/v1/commerce/billing/features' \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer ' \
-d '{
"code": "sso",
"name": "Single Sign-On",
"description": "SSO authentication configuration",
"privileges": [
{
"code": "provider",
"name": "SSO Provider",
"value_type": "SELECT",
"config": {
"select_options": [
"google",
"okta",
"azure",
"saml"
]
}
},
{
"code": "enabled",
"name": "SSO Enabled",
"value_type": "BOOLEAN"
}
]
}'
```
```json lines expandable title="Sample response" theme={null}
{
"code": "sso",
"name": "Single Sign-On",
"description": "SSO authentication configuration",
"privileges": [
{
"code": "provider",
"name": "SSO Provider",
"value_type": "SELECT",
"config": {
"select_options": [
"google",
"okta",
"azure",
"saml"
]
}
},
{
"code": "enabled",
"name": "SSO Enabled",
"value_type": "BOOLEAN"
}
],
"created_at": "2025-01-28T10:00:00Z"
}
```
A successful call returns a `201 Created` response. The response includes the following parameters:
| Parameter | Description | Further action |
| -------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `code`
string | Unique code for the created feature. | Use this `code` when managing the feature. |
| `privileges[].code`
string | Unique code for each privilege within the feature. | Use this `privileges[].code` when deleting privileges. |
For information on all parameters, see API reference.
## 3. Manage features
You can update feature configurations when adding new privileges, modifying existing privilege settings, or changing feature descriptions. To review a feature's current configuration, make a GET call to the /v1/commerce/billing/features/{code} endpoint.
| Feature attribute | Updatable | Possible management options | Impact on existing customers |
| ----------------------- | --------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------- |
| **Feature name** | Yes | Update feature details - modify display name | No impact - display only |
| **Feature description** | Yes | Update feature details - modify feature description | No impact - display only |
| **Feature privileges** | Yes | Update feature details - modify privilege configuration | Affects existing customer entitlements |
| **Feature code** | No | Feature cannot be modified - unique identifier remains permanent | N/A - cannot be modified |