Create features - Paypal Docs

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 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.

curl -X POST -L 'https://api-m.sandbox.paypal.com/v1/commerce/billing/features' \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer <ACCESS-TOKEN>' \
  -d '{
      "name": "API access",
      "code": "api_access",
      "description": "Access to REST API endpoints"
  }'

{
    "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.

curl -X POST -L 'https://api-m.sandbox.paypal.com/v1/commerce/billing/features' \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer <ACCESS-TOKEN>' \
  -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"
          }
      ]
  }'

{
    "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.

curl -X POST -L 'https://api-m.sandbox.paypal.com/v1/commerce/billing/features' \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer <ACCESS-TOKEN>' \
  -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"
          }
      ]
  }'

{
    "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/ 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

​1. Understand feature configuration

​2. Create features

​Feature without privileges

​Feature with privileges

​3. Manage features

1. Understand feature configuration

2. Create features

Feature without privileges

Feature with privileges

3. Manage features