Skip to main content
A feature represents a capability or functionality that customers can access in your application. For example, advanced analytics, API access, or premium support are features. Features connect the following:
  • Pricing plans that define which features customers receive with their subscription.
  • Subscriptions that determine actual feature access based on their chosen plan.
Each feature can have multiple privileges that allow fine-grained control over its behavior. A privilege defines specific permissions, access levels, or configurable aspects within a feature. For example, a storage feature might have max_gb and retention_days privileges to control capacity and duration, while an API access feature might have rate_limit and endpoints privileges to control usage restrictions.

​
1. Understand feature configuration

Before you create a feature, plan these configuration details for your application. Then, use the Create feature API 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. This code must be 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.
  • Value type: Data type that the privilege accepts when assigned values in entitlements.

​
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 send a POST request to /v1/commerce/billing/features 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

Create a basic feature without any privileges: 
curl -X POST --location '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

Create a feature with associated privileges to enable fine-grained control. Basic privileges Use basic privileges when you want to define simple access controls for features. 
curl -X POST --location '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 Use SELECT privileges when you want customers to choose from a predefined list of options. 
curl -X POST --location '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, call the Get feature details 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