Create pricing plans - Paypal Docs

A pricing plan connects the following entities:

Metrics that define what you charge for based on usage.
Pricing models that define how you calculate charges for metric usage.
Features through entitlements that define what capabilities customers can access.

How metrics, pricing models, features, entitlements, and plans work together

Your metric measures usage. For example, you create an API calls metric that counts the number of requests.
The pricing model determines how to charge for that usage. For example, you charge $0.10 per API call using the standard model.
Your features define capabilities. For example, you create an API access feature with a rate_limit privilege that controls the number of requests.
Entitlements assign specific values to feature privileges for each plan. 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.
The pricing plan combines metrics with their pricing models, features with their entitlements, and any fixed recurring fees.

Prerequisites

Create metrics that define what you charge for based on usage.
Create features that define what customers can access through entitlements.

1. Understand pricing models

Pricing models determine how you charge customers for their metric usage. Each metric in your plan can use a different pricing model based on your business needs. PayPal offers five pricing models:

Model	Description	Use case
STANDARD	Charge a fixed price per unit of usage.	API calls, storage GB.
GRADUATED	Apply different prices for different usage tiers.	Cloud hosting with cheaper rates for higher tiers.
VOLUME	Apply a single price to all units based on total volume.	Software licenses with bulk pricing.
PACKAGE	Charge a fixed price for bundles of units.	Email marketing credits in bundles of 10,000 emails.
PERCENTAGE	Charge a percentage of transaction value plus optional fixed fee.	Payment processing fees, marketplace commissions.

2. Decide your plan structure

Define the following components for your pricing plan before you create it. Then, you can make a POST call to the Create plan endpoint to send this information to PayPal. Plan identification

Name: Choose a human-readable identifier that describes your plan to customers.
Code: Create a unique alphanumeric identifier you use in API calls. Ensure this code is unique across all plans in your account.

Billing structure

Billing cycle: Set how often you charge recurring fees. Choose from WEEKLY, MONTHLY, QUARTERLY, or YEARLY. You cannot change this after customers subscribe to the plan.
Fixed recurring fee: Define the fixed recurring fee you charge each billing period.
Currency: Select a three-letter ISO currency code (for example, USD, EUR). See supported currencies. You cannot change this after you create the plan.
Payment timing: Decide whether you collect recurring charges in advance or at the end of the billing period.
Trial period: Set an optional free trial period in days. You do not charge customers the fixed recurring fee during this period, but usage-based charges may still apply.

Usage-based charges

Metric references: Link to your existing metrics by their metric IDs. You need to create metrics before you reference them in plans.
Charge models: Choose the pricing model to apply to each metric. Select from standard, graduated, volume, package, or percentage models.
Model properties: Configure pricing settings specific to each model. The structure varies based on the charge model you select.
Minimum amounts: Set minimum charges per metric. If usage-based charges are less than this amount, you charge the minimum instead.

Minimum commitment Plan-level minimum: Set an optimal minimum amount that customers pay each billing period. Customers pay this amount even if their actual usage costs less. This gives you a guaranteed baseline revenue for your plan. When usage-based charges are less than the minimum commitment, PayPal adds an extra fee to bring the total to the minimum committed value. You can also set a custom invoice display name to choose how this extra fee appears on customer invoices.

3. Create pricing plan

Use a valid access token and make a POST call to the /v1/commerce/billing/plans endpoint with all required request parameters including plan name, unique code, billing cycle, fixed recurring fee, and usage-based charges that reference existing metrics. On successful plan creation, the PayPal server returns a plan ID. The structure of your request depends on which pricing model you want to implement. The basic plan structure remains the same, but the usage_based_charges[].properties object varies based on your selected charge model.

Standard charge model example

This example shows the fundamental structure of a plan creation request using the standard charge model with an optional minimum commitment:

curl -X POST -L 'https://api-m.sandbox.paypal.com/v1/commerce/billing/plans' \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer <ACCESS-TOKEN>' \
  -d '{
      "name": "Premium Analytics Plan",
      "code": "ANALYTICS-PLAN-1753083766",
      "description": "Comprehensive analytics plan with advanced features and usage tracking",
      "billing_cycle": "WEEKLY",
      "amount": {
          "value": 160.00,
          "currency_code": "USD"
      },
      "trial_period": 0,
      "pay_in_advance": true,
      "tax_codes": [
          "standard_vat"
      ],
      "usage_based_charges": [
          {
              "metric_id": "92c9175c-31a6-4d74-b607-ac3915796ab9",
              "charge_model": "STANDARD",
              "properties": {
                  "amount": "1.00"
              },
              "min_amount": {
                  "value": 1.00
              },
              "tax_codes": [
                  "standard_vat"
              ]
          }
      ],
      "minimum_commitment": {
          "amount": {
              "value": 100.00
          },
          "invoice_display_name": "Minimum Commitment",
          "tax_codes": [
              "standard_vat"
          ]
      }
  }'

Charge model variations

Each pricing model requires different properties within the usage_based_charges[].properties object. The following examples show how to configure each model:

Graduated charge model

Use the graduated model when you want to incentivize higher usage by offering lower unit prices as customers use more. Unlike the standard model’s fixed per-unit rate, graduated pricing applies different rates to different usage tiers - you charge customers the tier-specific rate for each range of usage.

curl -X POST -L 'https://api-m.sandbox.paypal.com/v1/commerce/billing/plans' \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer <ACCESS-TOKEN>' \
  -d '{
      "name": "Cloud Storage Tiered Plan",
      "code": "STORAGE-TIERED-PLAN-1754320623",
      "description": "Tiered storage plan with graduated pricing",
      "billing_cycle": "MONTHLY",
      "amount": {
          "value": 160.00,
          "currency_code": "USD"
      },
      "trial_period": 0,
      "pay_in_advance": true,
      "usage_based_charges": [
          {
              "metric_id": "92c9175c-31a6-4d74-b607-ac3915796ab9",
              "charge_model": "GRADUATED",
              "properties": {
                  "graduated_ranges": [
                      {
                          "from_value": 0,
                          "to_value": 1000000,
                          "per_unit_amount": "10",
                          "flat_amount": "0"
                      },
                      {
                          "from_value": 1000001,
                          "to_value": 2000000,
                          "per_unit_amount": "8",
                          "flat_amount": "0"
                      },
                      {
                          "from_value": 2000001,
                          "to_value": 3000000,
                          "per_unit_amount": "6",
                          "flat_amount": "0"
                      },
                      {
                          "from_value": 3000001,
                          "to_value": null,
                          "per_unit_amount": "4",
                          "flat_amount": "0"
                      }
                  ]
              },
              "min_amount": {
                  "value": 1.00
              }
          }
      ]
  }'

Volume charge model

Choose the volume model for bulk pricing where the total usage volume determines the rate you apply to all units. This model differs from graduated pricing by applying a single rate to the entire usage amount rather than different rates per tier.

curl -X POST -L 'https://api-m.sandbox.paypal.com/v1/commerce/billing/plans' \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer <ACCESS-TOKEN>' \
  -d '{
      "name": "Software License Volume Plan",
      "code": "LICENSE-VOLUME-PLAN-1754320623",
      "description": "Volume-based pricing for software licenses",
      "billing_cycle": "MONTHLY",
      "amount": {
          "value": 160.00,
          "currency_code": "USD"
      },
      "trial_period": 0,
      "pay_in_advance": true,
      "usage_based_charges": [
          {
              "metric_id": "92c9175c-31a6-4d74-b607-ac3915796ab9",
              "charge_model": "VOLUME",
              "properties": {
                  "volume_ranges": [
                      {
                          "from_value": 0,
                          "to_value": 10000,
                          "flat_amount": "10",
                          "per_unit_amount": "0.0010"
                      },
                      {
                          "from_value": 10001,
                          "to_value": 50000,
                          "flat_amount": "10",
                          "per_unit_amount": "0.0008"
                      },
                      {
                          "from_value": 50001,
                          "to_value": null,
                          "flat_amount": "10",
                          "per_unit_amount": "0.0006"
                      }
                  ]
              },
              "min_amount": {
                  "value": 1.00
              }
          }
      ]
  }'

Package charge model

Implement the package model when you sell usage in predetermined bundles or blocks. Instead of charging per individual unit like the standard model, this approach groups units into packages with a fixed price per package, and can include free units as an allowance.

curl -X POST -L 'https://api-m.sandbox.paypal.com/v1/commerce/billing/plans' \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer <ACCESS-TOKEN>' \
  -d '{
      "name": "Email Marketing Package Plan",
      "code": "EMAIL-PACKAGE-PLAN-1754320623",
      "description": "Package pricing for email marketing credits",
      "billing_cycle": "MONTHLY",
      "amount": {
          "value": 160.00,
          "currency_code": "USD"
      },
      "trial_period": 0,
      "pay_in_advance": true,
      "usage_based_charges": [
          {
              "metric_id": "92c9175c-31a6-4d74-b607-ac3915796ab9",
              "charge_model": "PACKAGE",
              "properties": {
                  "amount": "0.15",
                  "filters": [
                      {
                          "key": "usage_type",
                          "values": [
                              "character_processing"
                          ]
                      }
                  ],
                  "package_size": 1000,
                  "free_units": 500000
              },
              "min_amount": {
                  "value": 1.00
              }
          }
      ]
  }'

Percentage charge model

Apply the percentage model when you want charges proportional to transaction values rather than usage volume. This model calculates fees as a percentage of the measured value, making it ideal for commission-based or value-based billing scenarios.

curl -X POST -L 'https://api-m.sandbox.paypal.com/v1/commerce/billing/plans' \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer <ACCESS-TOKEN>' \
  -d '{
      "name": "Marketplace Commission Plan",
      "code": "MARKETPLACE-PERCENT-PLAN-1753826420",
      "description": "Percentage-based pricing for marketplace transactions",
      "billing_cycle": "WEEKLY",
      "amount": {
          "value": 160.00,
          "currency_code": "USD"
      },
      "trial_period": 14,
      "pay_in_advance": true,
      "usage_based_charges": [
          {
              "metric_id": "92c9175c-31a6-4d74-b607-ac3915796ab9",
              "charge_model": "PERCENTAGE",
              "properties": {
                  "rate": "1"
              },
              "min_amount": {
                  "value": 1.00
              }
          }
      ]
  }'

Request body parameters

Parameter name	Description
`name` Required, string	Human-readable name for the plan. Use this name to display the plan to customers.
`code` Required, string	Unique alphanumeric identifier for the plan. Use this code in API calls. Must be unique across all plans in your account.
`description` string	Description of plan that explains services or features included.
`billing_cycle` Required, string	Determines the frequency for charging recurring fees. Possible values: `WEEKLY` - Recurring billing occurs every week `MONTHLY` - Recurring billing occurs every month `QUARTERLY` - Recurring billing occurs every three months `YEARLY` - Recurring billing occurs once a year Note: You cannot change this after customers are assigned to the plan.
`amount` Required, object	Fixed recurring fee to charge each billing cycle.
`amount.value` Required, number	Monetary amount as number. Example: 49.99 for $49.99.
`amount.currency_code` Required, string	Three-letter ISO currency code. Example: `USD`. See supported currencies.
`trial_period` integer	Free trial period in days. During this period, customers are not charged the fixed recurring fee. Usage-based charges may still apply.
`pay_in_advance` boolean	Determines when to collect recurring charges. Set to `true` to charge at the beginning of the billing period or `false` to charge at the end of the billing period.
`tax_codes` array	List of unique codes used to identify taxes to be applied at the plan level. Example: `["standard_vat"]`.
`usage_based_charges` array	Array of usage-based charge configurations. Each charge tracks different metric and applies own pricing model.
`usage_based_charges[].metric_id` Required, string	Unique identifier that identifies the metric. Use the `id` returned when you created the metric.
`usage_based_charges[].charge_model` Required, string	Pricing model to use for this charge. Possible values: `STANDARD` - Fixed price per unit `GRADUATED` - Pricing tiers based on usage levels `VOLUME` - Bulk pricing based on total usage `PACKAGE` - Pricing for usage packages `PERCENTAGE` - Percentage-based pricing See Pricing models for more details.
`usage_based_charges[].properties` Required, object	Model-specific pricing configuration. Structure varies based on selected charge model.
`usage_based_charges[].properties.amount` string STANDARD and PACKAGE models only	Fixed amount to charge per unit for STANDARD model, or fixed amount per package for PACKAGE model.
`usage_based_charges[].properties.rate` string PERCENTAGE model only	Percentage rate applied to the total amount. Specify as a string. Example: “1.2” for 1.2% charge on transactions.
`usage_based_charges[].properties.fixed_amount` string PERCENTAGE model only	Fixed fee applied to each event ingested during the billing period. Example: “0.10” for $0.10 per transaction.
`usage_based_charges[].properties.free_units_per_events` integer PERCENTAGE model only	Number of events not subject to the fixed fee.
`usage_based_charges[].properties.free_units_per_total_aggregation` string PERCENTAGE model only	Amount not subject to the charge rate.
`usage_based_charges[].properties.per_transaction_min_amount` string PERCENTAGE model only	Sets minimum amount of spending required for each individual transaction.
`usage_based_charges[].properties.per_transaction_max_amount` string PERCENTAGE model only	Sets maximum amount of spending required for each individual transaction.
`usage_based_charges[].properties.graduated_ranges` array GRADUATED model only	Array of pricing tiers for GRADUATED model. Each tier applies its specific rate to units within that tier range.
`usage_based_charges[].properties.graduated_ranges[].from_value` integer GRADUATED model only	Starting value for this pricing tier range (inclusive).
`usage_based_charges[].properties.graduated_ranges[].to_value` integer or null GRADUATED model only	Ending value for this pricing tier range (inclusive). Use `null` for the final tier to indicate no upper limit.
`usage_based_charges[].properties.graduated_ranges[].per_unit_amount` string GRADUATED model only	Price per unit for usage within this tier range.
`usage_based_charges[].properties.graduated_ranges[].flat_amount` string GRADUATED model only	Fixed amount charged for this tier range regardless of usage volume.
`usage_based_charges[].properties.volume_ranges` array VOLUME model only	Array of volume-based pricing tiers for VOLUME model. The pricing from the tier matching total usage applies to all units.
`usage_based_charges[].properties.volume_ranges[].from_value` integer VOLUME model only	Starting value for this volume tier range (inclusive).
`usage_based_charges[].properties.volume_ranges[].to_value` integer or null VOLUME model only	Ending value for this volume tier range (inclusive). Use `null` for the final tier to indicate no upper limit.
`usage_based_charges[].properties.volume_ranges[].flat_amount` string VOLUME model only	Fixed amount charged when total usage falls within this volume tier.
`usage_based_charges[].properties.volume_ranges[].per_unit_amount` string VOLUME model only	Price per unit applied to all units when total usage falls within this volume tier.
`usage_based_charges[].properties.package_size` integer PACKAGE model only	Number of units included in each package. Usage is divided into packages of this size, with each package charged at the fixed amount. Example: “100” for packages of 100 units.
`usage_based_charges[].properties.free_units` integer PACKAGE model only	Number of free units included before package charges apply. Initial units not charged. Example: “100” to offer first 100 units free.
`usage_based_charges[].properties.filters` array PACKAGE model only, optional	Array of filters to apply to usage data before charging.
`usage_based_charges[].properties.filters[].key` string PACKAGE model only, when filters is used	Filter key name to match against usage data properties.
`usage_based_charges[].properties.filters[].values` array PACKAGE model only, when filters is used	Array of values to match for the specified filter key.
`usage_based_charges[].min_amount` object	Minimum charge amount for the metric. If the billable usage-based `amount` is less than the minimum amount, the minimum is charged instead.
`usage_based_charges[].min_amount.value` number	Minimum monetary amount as number. Minimum value is 0.
`usage_based_charges[].tax_codes` array	List of unique codes used to identify taxes to be applied to this charge. Example: `["standard_vat"]`.
`minimum_commitment` object	Optional plan-level minimum commitment. Ensures customers pay at least this amount each billing period regardless of actual usage.
`minimum_commitment.amount` Required when minimum_commitment is used, object	The minimum commitment amount to charge.
`minimum_commitment.amount.value` Required when minimum_commitment is used, number	Minimum commitment monetary amount as number (example: 100.0 for $100.00).
`minimum_commitment.amount.currency_code` string	Three-letter ISO currency code for the minimum commitment amount. See supported currencies.
`minimum_commitment.invoice_display_name` string	Display name for the minimum commitment on customer invoices.
`minimum_commitment.tax_codes` array	List of unique codes used to identify taxes to be applied to the minimum commitment. Example: `["standard_vat"]`.

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 name	Description and further action
`code` string	Unique code for the pricing plan. Use this `code` in future operations, such as when managing the plan or creating subscriptions.

4. Create plan entitlements

Entitlements control the features and capabilities customers receive with their pricing plans. You can configure feature access, usage limits, and permissions through entitlements. Each entitlement consists of a feature and its associated privileges. Use a valid access token and make a POST call to the /v1/commerce/billing/plans/{plan_code}/entitlements endpoint with the entitlements configuration. Path parameter: plan_code is the code returned when you created the plan.

This operation replaces all existing entitlements. To retain existing entitlements while adding new ones, use the PATCH method instead.

curl -X POST -L 'https://api-m.sandbox.paypal.com/v1/commerce/billing/plans/ubb_plan_1753837176/entitlements' \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer <ACCESS-TOKEN>' \
  -d '{
      "entitlements": [
          {
              "feature_code": "seats",
              "feature_privilege_values": {
                  "max": 100,
                  "max_admins": 10,
                  "root": true,
                  "guest_access": false
              }
          },
          {
              "feature_code": "api_access",
              "feature_privilege_values": {
                  "rate_limit": 10000,
                  "endpoints": "all"
              }
          }
      ]
  }'

For the exhaustive list of request and response parameter descriptions, see API reference.

5. Manage plans

You can modify plan configurations to reflect changing business requirements, but certain limitations ensure billing consistency for existing customers. To review a plan’s current configuration and available management options, make a GET call to the /v1/commerce/billing/plans/ endpoint and review the plan properties. The plan’s modifiable attributes determine which management actions you can perform, ensuring proper plan handling.

When updating a plan, you can use the cascading_updates parameter in your update request to apply changes to subscriptions that have overridden plan values. This ensures that updates to the original plan are reflected in all associated subscriptions, if necessary.

Plan attribute	Updatable	Possible management options	Impact on existing subscriptions
Plan identification	Yes	Update plan details - name and description for customer-facing display	No impact - display only
Base pricing	Yes	Update plan details - fixed recurring amounts charged each billing cycle	Modifies current subscriptions if `cascading_updates` is `true`
Usage charges	Yes	Update plan details - pricing models, amounts, and minimum charges for metrics	Modifies current subscriptions if `cascading_updates` is `true`
Plan entitlements	Yes	Manage plan entitlements - feature access and privilege values for customers	Modifies current customer feature access
Plan code	No	Plan cannot be modified - unique identifier remains permanent	N/A - cannot be modified
Billing cycle	No	Plan cannot be modified - frequency of recurring charges (WEEKLY, MONTHLY, QUARTERLY, YEARLY)	N/A - cannot be modified
Currency	No	Plan cannot be modified - currency code cannot be changed after creation	N/A - cannot be modified
Trial period	No	Plan cannot be modified - free trial duration is fixed at creation time	N/A - cannot be modified

Usage-based Billing

​Prerequisites

​1. Understand pricing models

​2. Decide your plan structure

​3. Create pricing plan

​Standard charge model example

​Charge model variations

​Graduated charge model

​Volume charge model

​Package charge model

​Percentage charge model

​Request body parameters

​Response parameters

​4. Create plan entitlements

​5. Manage plans

Prerequisites

1. Understand pricing models

2. Decide your plan structure

3. Create pricing plan

Standard charge model example

Charge model variations

Graduated charge model

Volume charge model

Package charge model

Percentage charge model

Request body parameters

Response parameters

4. Create plan entitlements

5. Manage plans