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

# Manage pricing plans

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

Plan management helps you update existing pricing plans when your business requirements change. You can modify plan details, pricing models, and usage charges while keeping existing customer subscriptions active. This ensures new customers get appropriate pricing and existing customers keep their current billing.

## Update plan details

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 PUT call to the `/v1/commerce/billing/plans/{plan_code}` endpoint with the modified request parameters such as name, description, fixed recurring fee, and usage-based charges.

**Path parameter**: `plan_code` is the `code` you provided when you <a href="/limited-release/usage-based-billing/set-up-billing-process/create-pricing-plans" target="_blank" rel="noopener noreferrer">created the plan</a>.

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

<Warning>
  If a subscription's plan override specifically modified the base plan fee (`amount{}`) or usage-based charges (`usage_based_charges[]`), those customized values aren't updated even with `cascading_updates` set to `true`. For these two parameters, only the unmodified values from the original plan receive updates.
</Warning>

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

<CodeGroup>
  ```shell lines expandable title="Sample request" theme={null}
  curl -X PUT -L 'https://api-m.sandbox.paypal.com/v1/commerce/billing/plans/ubb_plan_1753837176' \
    -H 'Content-Type: application/json' \
    -H 'Authorization: Bearer <ACCESS-TOKEN>' \
    -d '{
        "name": "Premium Analytics Plan - Updated",
        "code": "ubb_plan_1753837176",
        "billing_cycle": "WEEKLY",
        "description": "Comprehensive analytics plan with advanced features and updated pricing",
        "amount": {
            "value": 170.00,
            "currency_code": "USD"
        },
        "trial_period": 0,
        "pay_in_advance": true,
        "cascading_updates": true,
        "tax_codes": [
            "standard_vat"
        ],
        "usage_based_charges": [
            {
                "id": "fggdgd5c-31a6-4d74-b607-ac3915796ab9",
                "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 - Updated",
      "code": "ubb_plan_1753837176",
      "billing_cycle": "WEEKLY",
      "description": "Comprehensive analytics plan with advanced features and updated pricing",
      "amount": {
          "value": 170.00,
          "currency_code": "USD"
      },
      "trial_period": 0,
      "pay_in_advance": true,
      "cascading_updates": true,
      "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"
          }
      ],
      "usage_based_charges": [
          {
              "id": "fggdgd5c-31a6-4d74-b607-ac3915796ab9",
              "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": "ubb_plan_1753837176",
          "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",
      "updated_at": "2025-07-31T08:41:19Z",
      "id": "113adfe7-5d09-42f9-94c1-b5c8a7dcd55c"
  }
  ```
</CodeGroup>

A successful call returns a `200 OK` response with the updated plan configuration.

## Manage plan entitlements

Plan entitlements define which features and capabilities customers can access based on their pricing plan. You can list existing entitlements, update entitlement configurations, and remove entitlements.

### List plan entitlements

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 GET call to the `/v1/commerce/billing/plans/{plan_code}/entitlements` endpoint to retrieve all entitlements assigned to a specific plan.

**Path parameter**: `plan_code` is the `code` you provided when you <a href="/limited-release/usage-based-billing/set-up-billing-process/create-pricing-plans" target="_blank" rel="noopener noreferrer">created the plan</a>.

<CodeGroup>
  ```shell lines title="Sample request" theme={null}
  curl -X GET -L 'https://api-m.sandbox.paypal.com/v1/commerce/billing/plans/ubb_plan_1753837176/entitlements' \
    -H 'Authorization: Bearer <ACCESS-TOKEN>'
  ```

  ```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": 150
                  },
                  {
                      "code": "max_admins",
                      "name": "Max Admins",
                      "value_type": "INTEGER",
                      "value": 15
                  },
                  {
                      "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>

A successful call returns a `200 OK` response with the plan entitlements.

### Update plan entitlements

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 PATCH call to the `/v1/commerce/billing/plans/{plan_code}/entitlements` endpoint with the entitlements to update.

**Path parameter**: `plan_code` is the `code` you provided when you <a href="/limited-release/usage-based-billing/set-up-billing-process/create-pricing-plans" target="_blank" rel="noopener noreferrer">created the plan</a>.

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

<CodeGroup>
  ```shell lines title="Sample request" theme={null}
  curl -X PATCH -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": 150,
                    "max_admins": 15
                }
            }
        ]
    }'
  ```

  ```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": 150
                  },
                  {
                      "code": "max_admins",
                      "name": "Max Admins",
                      "value_type": "INTEGER",
                      "value": 15
                  },
                  {
                      "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>

A successful call returns a `200 OK` response with the updated plan entitlements.

### Remove privilege from feature entitlement

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 DELETE call to the `/v1/commerce/billing/plans/{plan_code}/entitlements/{feature_code}/privileges/{privilege_code}` endpoint to remove a specific privilege from a feature entitlement.

**Path parameters**:

* `plan_code` is the `code` you provided when you <a href="/limited-release/usage-based-billing/set-up-billing-process/create-pricing-plans" target="_blank" rel="noopener noreferrer">created the plan</a>.
* `feature_code` is the `code` you provided when you <a href="/limited-release/usage-based-billing/set-up-billing-process/create-features" target="_blank" rel="noopener noreferrer">created the feature</a>.
* `privilege_code`is the `code` you provided when you <a href="/limited-release/usage-based-billing/set-up-billing-process/create-features#feature-with-privileges" target="_blank" rel="noopener noreferrer">created the privilege</a>.

<CodeGroup>
  ```shell lines title="Sample request" theme={null}
  curl -X DELETE -L 'https://api-m.sandbox.paypal.com/v1/commerce/billing/plans/ubb_plan_1753837176/entitlements/seats/privileges/guest_access' \
    -H 'Authorization: Bearer <ACCESS-TOKEN>'
  ```
</CodeGroup>

A successful call returns a `204 No Content` response.

### Remove feature entitlement from 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 DELETE call to the `/v1/commerce/billing/plans/{plan_code}/entitlements/{feature_code}` endpoint to remove a specific feature entitlement from a plan.

**Path parameters**:

* `plan_code` is the `code` you provided when you <a href="/limited-release/usage-based-billing/set-up-billing-process/create-pricing-plans" target="_blank" rel="noopener noreferrer">created the plan</a>.
* `feature_code` is the `code` you provided when you <a href="/limited-release/usage-based-billing/set-up-billing-process/create-features" target="_blank" rel="noopener noreferrer">created the feature</a>.

<CodeGroup>
  ```shell lines title="Sample request" theme={null}
  curl -X DELETE -L 'https://api-m.sandbox.paypal.com/v1/commerce/billing/plans/ubb_plan_1753837176/entitlements/api_access' \
    -H 'Authorization: Bearer <ACCESS-TOKEN>'
  ```
</CodeGroup>

A successful call returns a `204 No Content` response.