Skip to main content
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:
ParameterAction
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"
  }'

​
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"
          }
      ]
  }'
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"
          }
      ]
  }'
A successful call returns a 201 Created response. The response includes the following parameters:
ParameterDescriptionFurther 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 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