> ## Documentation Index
> Fetch the complete documentation index at: https://docs.paypal.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Create pricing plans

<div className="m-badge-page-wrapper">
  <Badge stroke color="orange" size="sm">Limited Release</Badge>
</div>

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
  <a href="/limited-release/usage-based-billing/set-up-billing-process/create-metrics" target="_blank" rel="noopener noreferrer">metrics</a>
  that define what you charge for based on usage.
* Create
  <a href="/limited-release/usage-based-billing/set-up-billing-process/create-features" target="_blank" rel="noopener noreferrer">features</a>
  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 <a href="/reference/api/rest/plans/create-a-new-plan" target="_blank" rel="noopener noreferrer">Create plan</a> 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 <a href="https://developer.paypal.com/docs/reports/reference/paypal-supported-currencies/" target="_blank" rel="noopener noreferrer">supported currencies</a>. 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 <a href="/developer/how-to/api/get-started#2-get-an-access-token" target="_blank" rel="noopener noreferrer">valid access token</a> and make a POST call to the `/v1/commerce/billing/plans` endpoint. Include the following parameters:

| <span style={{textAlign: 'left', display: 'block'}}>Parameter</span>                                                                                                                                                                    | <span style={{textAlign: 'left', display: 'block'}}>Description</span>                                                                                                                                                                                                                                                                                               | <span style={{textAlign: 'left', display: 'block'}}>Action</span>                                                                                                                        |
| --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `name`<br /><span style={{color: 'red', fontSize: 'smaller'}}>Required</span>, <span style={{color: '#95a5a6', fontSize: 'smaller'}}>string</span>                                                                                      | Human-readable name displayed to customers.                                                                                                                                                                                                                                                                                                                          | Provide a descriptive name for the plan.                                                                                                                                                 |
| `code`<br /><span style={{color: 'red', fontSize: 'smaller'}}>Required</span>, <span style={{color: '#95a5a6', fontSize: 'smaller'}}>string</span>                                                                                      | Unique alphanumeric identifier used in API calls.                                                                                                                                                                                                                                                                                                                    | Set a code that is unique across all plans in your account.                                                                                                                              |
| `description`<br /><span style={{color: '#95a5a6', fontSize: 'smaller'}}>string</span>                                                                                                                                                  | Explains services or features included in the plan.                                                                                                                                                                                                                                                                                                                  | Provide details about what the plan offers.                                                                                                                                              |
| `billing_cycle`<br /><span style={{color: 'red', fontSize: 'smaller'}}>Required</span>, <span style={{color: '#95a5a6', fontSize: 'smaller'}}>string</span>                                                                             | Frequency for charging recurring fees.<br /><br /><b>Possible values:</b><br />`WEEKLY` - Recurring billing every week<br />`MONTHLY` - Recurring billing every month<br />`QUARTERLY` - Recurring billing every three months<br />`YEARLY` - Recurring billing once a year<br /><br /><b>Note:</b> You cannot change this after customers are assigned to the plan. | Set to `WEEKLY`, `MONTHLY`, `QUARTERLY`, or `YEARLY`.                                                                                                                                    |
| `amount`<br /><span style={{color: 'red', fontSize: 'smaller'}}>Required</span>, <span style={{color: '#95a5a6', fontSize: 'smaller'}}>object</span>                                                                                    | Fixed recurring fee charged each billing cycle.                                                                                                                                                                                                                                                                                                                      | Include the `value` and `currency_code`.                                                                                                                                                 |
| `amount.value`<br /><span style={{color: 'red', fontSize: 'smaller'}}>Required</span>, <span style={{color: '#95a5a6', fontSize: 'smaller'}}>number</span>                                                                              | Monetary amount as a number (for example, `49.99` for \$49.99).                                                                                                                                                                                                                                                                                                      | Set the fee amount.                                                                                                                                                                      |
| `amount.currency_code`<br /><span style={{color: 'red', fontSize: 'smaller'}}>Required</span>, <span style={{color: '#95a5a6', fontSize: 'smaller'}}>string</span>                                                                      | Three-letter ISO currency code (for example, `USD`). See <a href="https://developer.paypal.com/docs/reports/reference/paypal-supported-currencies/" target="_blank" rel="noopener noreferrer">supported currencies</a>.                                                                                                                                              | Set the currency.                                                                                                                                                                        |
| `trial_period`<br /><span style={{color: '#95a5a6', fontSize: 'smaller'}}>integer</span>                                                                                                                                                | 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`<br /><span style={{color: '#95a5a6', fontSize: 'smaller'}}>boolean</span>                                                                                                                                              | 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`<br /><span style={{color: '#95a5a6', fontSize: 'smaller'}}>array</span>                                                                                                                                                     | Tax codes to apply at the plan level (for example, `["standard_vat"]`).                                                                                                                                                                                                                                                                                              | Provide an array of tax codes.                                                                                                                                                           |
| `usage_based_charges`<br /><span style={{color: '#95a5a6', fontSize: 'smaller'}}>array</span>                                                                                                                                           | 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`<br /><span style={{color: 'red', fontSize: 'smaller'}}>Required</span>, <span style={{color: '#95a5a6', fontSize: 'smaller'}}>string</span>                                                           | References the metric to track for this charge.                                                                                                                                                                                                                                                                                                                      | Set to the `id` returned when you <a href="/limited-release/usage-based-billing/set-up-billing-process/create-metrics" target="_blank" rel="noopener noreferrer">created the metric</a>. |
| `usage_based_charges[].charge_model`<br /><span style={{color: 'red', fontSize: 'smaller'}}>Required</span>, <span style={{color: '#95a5a6', fontSize: 'smaller'}}>string</span>                                                        | Pricing model for this charge.<br /><br /><b>Possible values:</b><br />`STANDARD` - Fixed price per unit<br />`GRADUATED` - Pricing tiers based on usage levels<br />`VOLUME` - Bulk pricing based on total usage<br />`PACKAGE` - Pricing for usage packages<br />`PERCENTAGE` - Percentage-based pricing                                                           | Set to `STANDARD`, `GRADUATED`, `VOLUME`, `PACKAGE`, or `PERCENTAGE`. See [Pricing models](#1-understand-pricing-models) for details.                                                    |
| `usage_based_charges[].properties`<br /><span style={{color: 'red', fontSize: 'smaller'}}>Required</span>, <span style={{color: '#95a5a6', fontSize: 'smaller'}}>object</span>                                                          | Model-specific pricing configuration. Structure varies based on selected charge model.                                                                                                                                                                                                                                                                               | Configure based on the selected `charge_model`.                                                                                                                                          |
| `usage_based_charges[].properties.amount`<br /><span style={{color: '#95a5a6', fontSize: 'smaller'}}>string</span><br /><span style={{color: '#2980b9', fontSize: 'smaller'}}>STANDARD and PACKAGE models only</span>                   | Fixed amount per unit (`STANDARD`) or per package (`PACKAGE`).                                                                                                                                                                                                                                                                                                       | Set the amount to charge.                                                                                                                                                                |
| `usage_based_charges[].properties.rate`<br /><span style={{color: '#95a5a6', fontSize: 'smaller'}}>string</span><br /><span style={{color: '#2980b9', fontSize: 'smaller'}}>PERCENTAGE model only</span>                                | Percentage rate applied to the total amount (for example, `"1.2"` for 1.2%).                                                                                                                                                                                                                                                                                         | Set the percentage rate.                                                                                                                                                                 |
| `usage_based_charges[].properties.fixed_amount`<br /><span style={{color: '#95a5a6', fontSize: 'smaller'}}>string</span><br /><span style={{color: '#2980b9', fontSize: 'smaller'}}>PERCENTAGE model only</span>                        | 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`<br /><span style={{color: '#95a5a6', fontSize: 'smaller'}}>integer</span><br /><span style={{color: '#2980b9', fontSize: 'smaller'}}>PERCENTAGE model only</span>              | Number of events not subject to the fixed fee.                                                                                                                                                                                                                                                                                                                       | Set the free event count.                                                                                                                                                                |
| `usage_based_charges[].properties.free_units_per_total_aggregation`<br /><span style={{color: '#95a5a6', fontSize: 'smaller'}}>string</span><br /><span style={{color: '#2980b9', fontSize: 'smaller'}}>PERCENTAGE model only</span>    | Amount not subject to the charge rate.                                                                                                                                                                                                                                                                                                                               | Set the free amount threshold.                                                                                                                                                           |
| `usage_based_charges[].properties.per_transaction_min_amount`<br /><span style={{color: '#95a5a6', fontSize: 'smaller'}}>string</span><br /><span style={{color: '#2980b9', fontSize: 'smaller'}}>PERCENTAGE model only</span>          | Minimum charge applied to each transaction.                                                                                                                                                                                                                                                                                                                          | Set the minimum per-transaction amount.                                                                                                                                                  |
| `usage_based_charges[].properties.per_transaction_max_amount`<br /><span style={{color: '#95a5a6', fontSize: 'smaller'}}>string</span><br /><span style={{color: '#2980b9', fontSize: 'smaller'}}>PERCENTAGE model only</span>          | Maximum charge applied to each transaction.                                                                                                                                                                                                                                                                                                                          | Set the maximum per-transaction amount.                                                                                                                                                  |
| `usage_based_charges[].properties.graduated_ranges`<br /><span style={{color: '#95a5a6', fontSize: 'smaller'}}>array</span><br /><span style={{color: '#2980b9', fontSize: 'smaller'}}>GRADUATED model only</span>                      | 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`<br /><span style={{color: '#95a5a6', fontSize: 'smaller'}}>integer</span><br /><span style={{color: '#2980b9', fontSize: 'smaller'}}>GRADUATED model only</span>       | Starting value for this tier range (inclusive).                                                                                                                                                                                                                                                                                                                      | Set the tier start value.                                                                                                                                                                |
| `usage_based_charges[].properties.graduated_ranges[].to_value`<br /><span style={{color: '#95a5a6', fontSize: 'smaller'}}>integer or null</span><br /><span style={{color: '#2980b9', fontSize: 'smaller'}}>GRADUATED model only</span> | 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`<br /><span style={{color: '#95a5a6', fontSize: 'smaller'}}>string</span><br /><span style={{color: '#2980b9', fontSize: 'smaller'}}>GRADUATED model only</span>   | Price charged per unit within this tier.                                                                                                                                                                                                                                                                                                                             | Set the per-unit price.                                                                                                                                                                  |
| `usage_based_charges[].properties.graduated_ranges[].flat_amount`<br /><span style={{color: '#95a5a6', fontSize: 'smaller'}}>string</span><br /><span style={{color: '#2980b9', fontSize: 'smaller'}}>GRADUATED model only</span>       | Fixed amount charged for this tier regardless of usage volume.                                                                                                                                                                                                                                                                                                       | Set the flat amount.                                                                                                                                                                     |
| `usage_based_charges[].properties.volume_ranges`<br /><span style={{color: '#95a5a6', fontSize: 'smaller'}}>array</span><br /><span style={{color: '#2980b9', fontSize: 'smaller'}}>VOLUME model only</span>                            | 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`<br /><span style={{color: '#95a5a6', fontSize: 'smaller'}}>integer</span><br /><span style={{color: '#2980b9', fontSize: 'smaller'}}>VOLUME model only</span>             | Starting value for this volume tier (inclusive).                                                                                                                                                                                                                                                                                                                     | Set the tier start value.                                                                                                                                                                |
| `usage_based_charges[].properties.volume_ranges[].to_value`<br /><span style={{color: '#95a5a6', fontSize: 'smaller'}}>integer or null</span><br /><span style={{color: '#2980b9', fontSize: 'smaller'}}>VOLUME model only</span>       | 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`<br /><span style={{color: '#95a5a6', fontSize: 'smaller'}}>string</span><br /><span style={{color: '#2980b9', fontSize: 'smaller'}}>VOLUME model only</span>             | Fixed amount charged when total usage falls within this tier.                                                                                                                                                                                                                                                                                                        | Set the flat amount.                                                                                                                                                                     |
| `usage_based_charges[].properties.volume_ranges[].per_unit_amount`<br /><span style={{color: '#95a5a6', fontSize: 'smaller'}}>string</span><br /><span style={{color: '#2980b9', fontSize: 'smaller'}}>VOLUME model only</span>         | 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`<br /><span style={{color: '#95a5a6', fontSize: 'smaller'}}>integer</span><br /><span style={{color: '#2980b9', fontSize: 'smaller'}}>PACKAGE model only</span>                          | 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`<br /><span style={{color: '#95a5a6', fontSize: 'smaller'}}>integer</span><br /><span style={{color: '#2980b9', fontSize: 'smaller'}}>PACKAGE model only</span>                            | Number of free units before package charges apply.                                                                                                                                                                                                                                                                                                                   | Set the count (for example, `100` for first 100 units free).                                                                                                                             |
| `usage_based_charges[].properties.filters`<br /><span style={{color: '#95a5a6', fontSize: 'smaller'}}>array</span><br /><span style={{color: '#2980b9', fontSize: 'smaller'}}>PACKAGE model only, optional</span>                       | Filters to apply to usage data before charging.                                                                                                                                                                                                                                                                                                                      | Add filter objects if needed.                                                                                                                                                            |
| `usage_based_charges[].properties.filters[].key`<br /><span style={{color: '#95a5a6', fontSize: 'smaller'}}>string</span><br /><span style={{color: '#2980b9', fontSize: 'smaller'}}>PACKAGE model only, when filters is used</span>    | Property name to filter on from usage data.                                                                                                                                                                                                                                                                                                                          | Set the filter key.                                                                                                                                                                      |
| `usage_based_charges[].properties.filters[].values`<br /><span style={{color: '#95a5a6', fontSize: 'smaller'}}>array</span><br /><span style={{color: '#2980b9', fontSize: 'smaller'}}>PACKAGE model only, when filters is used</span>  | Values to match for the specified filter key.                                                                                                                                                                                                                                                                                                                        | Provide the values to match.                                                                                                                                                             |
| `usage_based_charges[].min_amount`<br /><span style={{color: '#95a5a6', fontSize: 'smaller'}}>object</span>                                                                                                                             | 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`<br /><span style={{color: '#95a5a6', fontSize: 'smaller'}}>number</span>                                                                                                                       | Minimum monetary amount (minimum value is `0`).                                                                                                                                                                                                                                                                                                                      | Set the minimum charge amount.                                                                                                                                                           |
| `usage_based_charges[].tax_codes`<br /><span style={{color: '#95a5a6', fontSize: 'smaller'}}>array</span>                                                                                                                               | Tax codes to apply to this charge (for example, `["standard_vat"]`).                                                                                                                                                                                                                                                                                                 | Provide an array of tax codes.                                                                                                                                                           |
| `minimum_commitment`<br /><span style={{color: '#95a5a6', fontSize: 'smaller'}}>object</span>                                                                                                                                           | Guarantees customers pay at least this amount each billing period regardless of actual usage.                                                                                                                                                                                                                                                                        | Include the `amount` object.                                                                                                                                                             |
| `minimum_commitment.amount`<br /><span style={{color: 'red', fontSize: 'smaller'}}>Required when minimum\_commitment is used</span>, <span style={{color: '#95a5a6', fontSize: 'smaller'}}>object</span>                                | The minimum amount customers pay each billing period.                                                                                                                                                                                                                                                                                                                | Include the `value`.                                                                                                                                                                     |
| `minimum_commitment.amount.value`<br /><span style={{color: 'red', fontSize: 'smaller'}}>Required when minimum\_commitment is used</span>, <span style={{color: '#95a5a6', fontSize: 'smaller'}}>number</span>                          | Monetary amount (for example, `100.0` for \$100.00).                                                                                                                                                                                                                                                                                                                 | Set the minimum commitment amount.                                                                                                                                                       |
| `minimum_commitment.amount.currency_code`<br /><span style={{color: '#95a5a6', fontSize: 'smaller'}}>string</span>                                                                                                                      | Three-letter ISO currency code. See <a href="https://developer.paypal.com/docs/reports/reference/paypal-supported-currencies/" target="_blank" rel="noopener noreferrer">supported currencies</a>.                                                                                                                                                                   | Set the currency.                                                                                                                                                                        |
| `minimum_commitment.invoice_display_name`<br /><span style={{color: '#95a5a6', fontSize: 'smaller'}}>string</span>                                                                                                                      | Text shown on customer invoices for the minimum commitment fee.                                                                                                                                                                                                                                                                                                      | Provide a display name.                                                                                                                                                                  |
| `minimum_commitment.tax_codes`<br /><span style={{color: '#95a5a6', fontSize: 'smaller'}}>array</span>                                                                                                                                  | Tax codes to apply to the minimum commitment (for example, `["standard_vat"]`).                                                                                                                                                                                                                                                                                      | Provide an array of tax codes.                                                                                                                                                           |

For information on all parameters, see <a href="/reference/api/rest/plans/create-a-new-plan" target="_blank" rel="noopener noreferrer">API reference</a>.

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:

<CodeGroup>
  ```shell lines expandable title="Sample request" theme={null}
  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"
            ]
        }
    }'
  ```

  ```json lines expandable title="Sample response" theme={null}
  {
      "name": "Premium Analytics Plan",
      "code": "ANALYTICS-PLAN-1753083705",
      "description": "Comprehensive analytics plan with advanced features and usage tracking",
      "billing_cycle": "WEEKLY",
      "amount": {
          "value": 160.00,
          "currency_code": "USD"
      },
      "taxes": [
          {
              "id": "1a901a90-1a90-1a90-1a90-1a901a901a90",
              "name": "TVA",
              "code": "standard_vat",
              "description": "French standard VAT",
              "rate": "20.00",
              "created_at": "2023-07-06T14:35:58Z"
          }
      ],
      "trial_period": 0,
      "pay_in_advance": true,
      "usage_based_charges": [
          {
              "id": "99fa7a6b-d005-43a5-8bab-0df7a2a721fb",
              "metric_id": "92c9175c-31a6-4d74-b607-ac3915796ab9",
              "charge_model": "STANDARD",
              "properties": {
                  "amount": "1.00"
              },
              "min_amount": {
                  "value": 1.00,
                  "currency_code": "USD"
              },
              "taxes": [
                  {
                      "id": "1a901a90-1a90-1a90-1a90-1a901a901a90",
                      "name": "TVA",
                      "code": "standard_vat",
                      "description": "French standard VAT",
                      "rate": "20.00",
                      "created_at": "2023-07-06T14:35:58Z"
                  }
              ]
          }
      ],
      "minimum_commitment": {
          "amount": {
              "value": 100.00,
              "currency_code": "USD"
          },
          "invoice_display_name": "Minimum Commitment",
          "id": "cc82edfd-8198-4942-bed8-fcd7afb5191e",
          "plan_code": "ANALYTICS-PLAN-1753083705",
          "created_at": "2025-07-31T08:41:19Z",
          "updated_at": "2025-07-31T08:41:19Z",
          "taxes": [
              {
                  "id": "1a901a90-1a90-1a90-1a90-1a901a901a90",
                  "name": "TVA",
                  "code": "standard_vat",
                  "description": "French standard VAT",
                  "rate": "20.00",
                  "created_at": "2023-07-06T14:35:58Z"
              }
          ]
      },
      "created_at": "2025-07-30T00:59:35Z",
      "id": "95de3538-3827-496b-89a0-120745360830"
  }
  ```
</CodeGroup>

### 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.

<CodeGroup>
  ```shell lines expandable title="Sample request" theme={null}
  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
                }
            }
        ]
    }'
  ```

  ```json lines expandable title="Sample response" theme={null}
  {
      "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,
                  "currency_code": "USD"
              }
          }
      ],
      "created_at": "2025-07-29T22:00:19Z",
      "id": "113adfe7-5d09-42f9-94c1-b5c8a7dcd55c"
  }
  ```
</CodeGroup>

#### 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.

<CodeGroup>
  ```shell lines expandable title="Sample request" theme={null}
  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
                }
            }
        ]
    }'
  ```

  ```json lines expandable title="Sample response" theme={null}
  {
      "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,
                  "currency_code": "USD"
              }
          }
      ],
      "created_at": "2025-07-29T22:00:19Z",
      "id": "113adfe7-5d09-42f9-94c1-b5c8a7dcd55c"
  }
  ```
</CodeGroup>

#### 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.

<CodeGroup>
  ```shell lines expandable title="Sample request" theme={null}
  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
                }
            }
        ]
    }'
  ```

  ```json lines expandable title="Sample response" theme={null}
  {
      "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,
                  "currency_code": "USD"
              }
          }
      ],
      "created_at": "2025-07-29T22:00:19Z",
      "id": "113adfe7-5d09-42f9-94c1-b5c8a7dcd55c"
  }
  ```
</CodeGroup>

#### 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.

<CodeGroup>
  ```shell lines expandable title="Sample request" theme={null}
  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
                }
            }
        ]
    }'
  ```

  ```json lines expandable title="Sample response" theme={null}
  {
      "name": "Marketplace Commission Plan",
      "code": "MARKETPLACE-PERCENT-PLAN-1753826420",
      "billing_cycle": "WEEKLY",
      "description": "Percentage-based pricing for marketplace transactions",
      "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,
                  "currency_code": "USD"
              }
          }
      ],
      "created_at": "2025-07-29T22:00:19Z",
      "id": "113adfe7-5d09-42f9-94c1-b5c8a7dcd55c"
  }
  ```
</CodeGroup>

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

| <span style={{textAlign: 'left', display: 'block'}}>Parameter</span>            | <span style={{textAlign: 'left', display: 'block'}}>Description</span> | <span style={{textAlign: 'left', display: 'block'}}>Further action</span>                                                                                                                                                                                                                                                                    |
| ------------------------------------------------------------------------------- | ---------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `code`<br /><span style={{color: '#95A5A6', fontSize: 'smaller'}}>string</span> | Unique code for the pricing plan.                                      | Use this `code` when <a href="/limited-release/usage-based-billing/manage-entities/manage-pricing-plans" target="_blank" rel="noopener noreferrer">managing the plan</a> or <a href="/limited-release/usage-based-billing/set-up-billing-process/create-subscriptions" target="_blank" rel="noopener noreferrer">creating subscriptions</a>. |

For information on all parameters, see <a href="/reference/api/rest/plans/create-a-new-plan" target="_blank" rel="noopener noreferrer">API reference</a>.

## 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 <a href="/developer/how-to/api/get-started#2-get-an-access-token" target="_blank" rel="noopener noreferrer">valid access token</a> 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 <a href="#3-create-pricing-plan">created the plan</a>.

For information on all parameters, see <a href="/reference/api/rest/entitlements/create-an-entitlement" target="_blank" rel="noopener noreferrer">API reference</a>.

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

<CodeGroup>
  ```shell lines title="Sample request" theme={null}
  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"
                }
            }
        ]
    }'
  ```

  ```json lines expandable title="Sample response" theme={null}
  {
      "entitlements": [
          {
              "feature_code": "seats",
              "name": "Number of seats",
              "description": "Number of users of the account",
              "feature_privileges": [
                  {
                      "code": "max",
                      "name": "Maximum",
                      "value_type": "INTEGER",
                      "value": 100
                  },
                  {
                      "code": "max_admins",
                      "name": "Max Admins",
                      "value_type": "INTEGER",
                      "value": 10
                  },
                  {
                      "code": "root",
                      "name": "Allow root user",
                      "value_type": "BOOLEAN",
                      "value": true
                  },
                  {
                      "code": "guest_access",
                      "name": "Guest Access",
                      "value_type": "BOOLEAN",
                      "value": false
                  }
              ]
          },
          {
              "feature_code": "api_access",
              "name": "API Access",
              "description": "Access to API endpoints",
              "feature_privileges": [
                  {
                      "code": "rate_limit",
                      "name": "Rate Limit",
                      "value_type": "INTEGER",
                      "value": 10000
                  },
                  {
                      "code": "endpoints",
                      "name": "Endpoints",
                      "value_type": "STRING",
                      "value": "all"
                  }
              ]
          }
      ]
  }
  ```
</CodeGroup>

## 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 <a href="/reference/api/rest/plans/get-a-plan-by-id" target="_blank" rel="noopener noreferrer">/v1/commerce/billing/plans/{id}</a> 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.
</Tip>

| Plan attribute          | Updatable | Possible management options                                                                                                                                                                                                             | Impact on existing subscriptions                                |
| ----------------------- | --------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------- |
| **Plan identification** | Yes       | <a href="/limited-release/usage-based-billing/manage-entities/manage-pricing-plans#update-plan-details" target="_blank" rel="noopener noreferrer">Update plan details</a> - name and description for customer-facing display            | No impact - display only                                        |
| **Base pricing**        | Yes       | <a href="/limited-release/usage-based-billing/manage-entities/manage-pricing-plans#update-plan-details" target="_blank" rel="noopener noreferrer">Update plan details</a> - fixed recurring amounts charged each billing cycle          | Modifies current subscriptions if `cascading_updates` is `true` |
| **Usage charges**       | Yes       | <a href="/limited-release/usage-based-billing/manage-entities/manage-pricing-plans#update-plan-details" target="_blank" rel="noopener noreferrer">Update plan details</a> - pricing models, amounts, and minimum charges for metrics    | Modifies current subscriptions if `cascading_updates` is `true` |
| **Plan entitlements**   | Yes       | <a href="/limited-release/usage-based-billing/manage-entities/manage-pricing-plans#manage-plan-entitlements" target="_blank" rel="noopener noreferrer">Manage plan entitlements</a> - 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                                        |