Create pricing plans - Paypal Docs

A pricing plan connects the following entities:

A plan that you offer to your customer.
The metrics for the plan. These define the items you charge for in a plan.
The pricing models. These define how metric usage is charged.

How do metrics, pricing models, and plans work together

Your metric measures usage. For example, API calls counted.
The pricing model determines how to charge for that usage. For example, $0.10 per API call for standard model.
The pricing plan combines multiple metrics with their respective pricing models and includes any fixed recurring fees.

To create and configure pricing plans:

Understand pricing models
Decide your plan structure
Create pricing plan
Create plan entitlements
Manage plans

Prerequisite

Ensure to create and configure all metrics that your plans use.

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 send this information to PayPal using a Create plan call. 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. This code must be 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 must 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 fall below this amount, you charge the minimum instead.

Minimum commitment Plan-level minimum: Set an optimal minimum amount that customers must 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 fall below 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 send a POST request to /v1/commerce/billing/plans 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 --location '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 --location '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 --location '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 --location '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 --location '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 of the metric to track. You must create the metric before you reference it in the plan.
`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 to charge for PERCENTAGE model. Specify as a string (example: “2.9” for 2.9%).
`usage_based_charges[].properties.graduated_ranges` array GRADUATED model only	Array of pricing tiers for GRADUATED model. Each tier applies different pricing to different usage ranges.
`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 for PACKAGE model.
`usage_based_charges[].properties.free_units` integer PACKAGE model only	Number of free units included before package charges apply.
`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 below 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

Note: 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
`id` string	Unique identifier for the created plan. Use this ID for future operations, such as linking subscriptions or updating/deleting the plan.
`code` string	Unique code for the created plan. Use this code to reference the plan when 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 send a POST request to /v1/commerce/billing/plans/{code}/entitlements with the entitlements configuration. Path parameter: code is the plan code returned when you created the plan.

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

curl -X POST --location '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"
              }
          }
      ]
  }'

Note: 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, call the Get plan details endpoint and review the plan properties. The plan’s modifiable attributes determine which management actions you can perform, ensuring proper plan handling.

Tip: 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

​Prerequisite

​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