Create pricing plans - Paypal Docs

Limited Release

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. Include the following parameters:

Parameter	Description	Action
`name` Required, string	Human-readable name displayed to customers.	Provide a descriptive name for the plan.
`code` Required, string	Unique alphanumeric identifier used in API calls.	Set a code that is unique across all plans in your account.
`description` string	Explains services or features included in the plan.	Provide details about what the plan offers.
`billing_cycle` Required, string	Frequency for charging recurring fees. Possible values: `WEEKLY` - Recurring billing every week `MONTHLY` - Recurring billing every month `QUARTERLY` - Recurring billing every three months `YEARLY` - Recurring billing once a year Note: You cannot change this after customers are assigned to the plan.	Set to `WEEKLY`, `MONTHLY`, `QUARTERLY`, or `YEARLY`.
`amount` Required, object	Fixed recurring fee charged each billing cycle.	Include the `value` and `currency_code`.
`amount.value` Required, number	Monetary amount as a number (for example, `49.99` for $49.99).	Set the fee amount.
`amount.currency_code` Required, string	Three-letter ISO currency code (for example, `USD`). See supported currencies.	Set the currency.
`trial_period` integer	Number of free trial days. During this period, customers are not charged the fixed recurring fee. Usage-based charges may still apply.	Set to `0` for no trial or specify the number of days.
`pay_in_advance` boolean	Determines when to collect recurring charges.	Set to `true` to charge at the start of the billing period or `false` to charge at the end.
`tax_codes` array	Tax codes to apply at the plan level (for example, `["standard_vat"]`).	Provide an array of tax codes.
`usage_based_charges` array	Usage-based charge configurations. Each charge tracks a different metric and applies its own pricing model.	Add one or more charge configurations.
`usage_based_charges[].metric_id` Required, string	References the metric to track for this charge.	Set to the `id` returned when you created the metric.
`usage_based_charges[].charge_model` Required, string	Pricing model 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	Set to `STANDARD`, `GRADUATED`, `VOLUME`, `PACKAGE`, or `PERCENTAGE`. See Pricing models for details.
`usage_based_charges[].properties` Required, object	Model-specific pricing configuration. Structure varies based on selected charge model.	Configure based on the selected `charge_model`.
`usage_based_charges[].properties.amount` string STANDARD and PACKAGE models only	Fixed amount per unit (`STANDARD`) or per package (`PACKAGE`).	Set the amount to charge.
`usage_based_charges[].properties.rate` string PERCENTAGE model only	Percentage rate applied to the total amount (for example, `"1.2"` for 1.2%).	Set the percentage rate.
`usage_based_charges[].properties.fixed_amount` string PERCENTAGE model only	Fixed fee applied to each event (for example, `"0.10"` for $0.10 per transaction).	Set the fixed fee per event.
`usage_based_charges[].properties.free_units_per_events` integer PERCENTAGE model only	Number of events not subject to the fixed fee.	Set the free event count.
`usage_based_charges[].properties.free_units_per_total_aggregation` string PERCENTAGE model only	Amount not subject to the charge rate.	Set the free amount threshold.
`usage_based_charges[].properties.per_transaction_min_amount` string PERCENTAGE model only	Minimum charge applied to each transaction.	Set the minimum per-transaction amount.
`usage_based_charges[].properties.per_transaction_max_amount` string PERCENTAGE model only	Maximum charge applied to each transaction.	Set the maximum per-transaction amount.
`usage_based_charges[].properties.graduated_ranges` array GRADUATED model only	Pricing tiers where each tier applies its specific rate to units within that range.	Add one or more tier ranges.
`usage_based_charges[].properties.graduated_ranges[].from_value` integer GRADUATED model only	Starting value for this tier range (inclusive).	Set the tier start value.
`usage_based_charges[].properties.graduated_ranges[].to_value` integer or null GRADUATED model only	Ending value for this tier range (inclusive).	Set the tier end value or `null` for no upper limit.
`usage_based_charges[].properties.graduated_ranges[].per_unit_amount` string GRADUATED model only	Price charged per unit within this tier.	Set the per-unit price.
`usage_based_charges[].properties.graduated_ranges[].flat_amount` string GRADUATED model only	Fixed amount charged for this tier regardless of usage volume.	Set the flat amount.
`usage_based_charges[].properties.volume_ranges` array VOLUME model only	Volume-based pricing tiers. The tier matching total usage applies its pricing to all units.	Add one or more volume ranges.
`usage_based_charges[].properties.volume_ranges[].from_value` integer VOLUME model only	Starting value for this volume tier (inclusive).	Set the tier start value.
`usage_based_charges[].properties.volume_ranges[].to_value` integer or null VOLUME model only	Ending value for this volume tier (inclusive).	Set the tier end value or `null` for no upper limit.
`usage_based_charges[].properties.volume_ranges[].flat_amount` string VOLUME model only	Fixed amount charged when total usage falls within this tier.	Set the flat amount.
`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 tier.	Set the per-unit price.
`usage_based_charges[].properties.package_size` integer PACKAGE model only	Number of units per package. Usage is divided into packages of this size.	Set the size (for example, `100` for packages of 100 units).
`usage_based_charges[].properties.free_units` integer PACKAGE model only	Number of free units before package charges apply.	Set the count (for example, `100` for first 100 units free).
`usage_based_charges[].properties.filters` array PACKAGE model only, optional	Filters to apply to usage data before charging.	Add filter objects if needed.
`usage_based_charges[].properties.filters[].key` string PACKAGE model only, when filters is used	Property name to filter on from usage data.	Set the filter key.
`usage_based_charges[].properties.filters[].values` array PACKAGE model only, when filters is used	Values to match for the specified filter key.	Provide the values to match.
`usage_based_charges[].min_amount` object	Minimum charge for this metric. If billable usage is less than the minimum, the minimum is charged instead.	Include the `value`.
`usage_based_charges[].min_amount.value` number	Minimum monetary amount (minimum value is `0`).	Set the minimum charge amount.
`usage_based_charges[].tax_codes` array	Tax codes to apply to this charge (for example, `["standard_vat"]`).	Provide an array of tax codes.
`minimum_commitment` object	Guarantees customers pay at least this amount each billing period regardless of actual usage.	Include the `amount` object.
`minimum_commitment.amount` Required when minimum_commitment is used, object	The minimum amount customers pay each billing period.	Include the `value`.
`minimum_commitment.amount.value` Required when minimum_commitment is used, number	Monetary amount (for example, `100.0` for $100.00).	Set the minimum commitment amount.
`minimum_commitment.amount.currency_code` string	Three-letter ISO currency code. See supported currencies.	Set the currency.
`minimum_commitment.invoice_display_name` string	Text shown on customer invoices for the minimum commitment fee.	Provide a display name.
`minimum_commitment.tax_codes` array	Tax codes to apply to the minimum commitment (for example, `["standard_vat"]`).	Provide an array of tax codes.

For information on all parameters, see API reference. 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
              }
          }
      ]
  }'

A successful call returns a 201 Created response. The response includes the following parameter:

Parameter	Description	Further action
`code` string	Unique code for the pricing plan.	Use this `code` when managing the plan or creating subscriptions.

For information on all parameters, see API reference.

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. For information on all parameters, see API reference.

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

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

​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

4. Create plan entitlements

5. Manage plans