Skip to main content
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 features with or without privileges. The privileges[] array is optional - you can add privileges later by updating the feature. Use a valid access token and make a POST call to the /v1/commerce/billing/features endpoint with all required request parameters. On successful feature creation, the PayPal server returns the feature details including any privileges you created inline.

​
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"
  }'

​
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"
          }
      ]
  }'
SELECT privileges with options Set value_type to SELECT when you want customers to choose from a predefined list of options. When you use SELECT, you must 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"
          }
      ]
  }'

​
Request body parameters

Parameter nameDescription
code
Required, string		Unique identifier for the feature. Must be unique across all features in your account.
name
string		Human-readable name for the feature.
description
string		Description of what functionality the feature provides or restricts.
privileges[]
array		Optional array of privilege configurations. Each privilege defines specific access controls within the feature.
privileges[].code
Required when privileges[] provided, string		Unique identifier for the privilege within the feature.
privileges[].name
string		Human-readable name for the privilege.
privileges[].value_type
string		Data type that this privilege accepts when assigned values in entitlements.

Possible values:
INTEGER - Numeric limits
BOOLEAN - On/off toggles
SELECT - Predefined options
STRING - Text values
privileges[].config
Required for SELECT type, object		Configuration object for SELECT type privileges. Contains select_options array with available choices.

​
Response parameters

This section documents only the response parameters relevant for the next step. For the exhaustive list of response parameters, see API reference.
Parameter nameDescription and further action
code
string		Unique code for the created feature.
Use this code in future operations, such as managing the feature.
privileges[].code
string		Unique code for each privilege within the feature.
Use this code in future operations, such as deleting privileges.

​
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 attributeUpdatablePossible management optionsImpact on existing customers
Feature nameYesUpdate feature details - modify display nameNo impact - display only
Feature descriptionYesUpdate feature details - modify feature descriptionNo impact - display only
Feature privilegesYesUpdate feature details - modify privilege configurationAffects existing customer entitlements
Feature codeNoFeature cannot be modified - unique identifier remains permanentN/A - cannot be modified