Skip to main content
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 valid access token and send a PUT request to /v1/commerce/billing/plans/{plan_code} with the modified request parameters such as plan name, description, fixed recurring fee, and usage-based charges. Path parameter: plan_code is the code you provided when you created the plan.
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.
If a subscription’s plan override specifically modified the base plan fee (amount{}) or usage-based charges (usage_based_charges[]), those customized values won’t be updated even with cascading_updates set to true. For these two parameters, only the unmodified values from the original plan will receive updates.
On successful request processing, PayPal returns the updated plan configuration and the plan id. Use this ID for future plan-related operations. 
curl -X PUT --location '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"
          ]
      }
  }'
For the exhaustive list of request and response parameter descriptions, see API reference.

​
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 valid access token and send a GET request to /v1/commerce/billing/plans/{plan_code}/entitlements to retrieve all entitlements assigned to a specific plan. Path parameter: plan_code is the code you provided when you created the plan. 
curl -X GET --location 'https://api-m.sandbox.paypal.com/v1/commerce/billing/plans/ubb_plan_1753837176/entitlements' \
  -H 'Authorization: Bearer <ACCESS-TOKEN>'
For the exhaustive list of request and response parameter descriptions, see API reference.

​
Update plan entitlements

Use a valid access token and send a PATCH request to /v1/commerce/billing/plans/{plan_code}/entitlements with the entitlements to update. Path parameter: plan_code is the code you provided when you created the plan. On successful request processing, PayPal updates values for the specified entitlements. New privileges or features are added, existing values are overwritten if duplicates are found, and items not included remain unchanged. 
curl -X PATCH --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": 150,
                  "max_admins": 15
              }
          }
      ]
  }'
For the exhaustive list of request and response parameter descriptions, see API reference.

​
Remove privilege from feature entitlement

To remove a specific privilege from a feature entitlement, send a DELETE request to /v1/commerce/billing/plans/{plan_code}/entitlements/{feature_code}/privileges/{privilege_code}. Path parameters: 
curl -X DELETE --location 'https://api-m.sandbox.paypal.com/v1/commerce/billing/plans/ubb_plan_1753837176/entitlements/seats/privileges/guest_access' \
  -H 'Authorization: Bearer <ACCESS-TOKEN>'
For the exhaustive list of request and response parameter descriptions, see API reference.

​
Remove feature entitlement from plan

To remove a specific feature entitlement from a plan, use a valid access token and send a DELETE request to /v1/commerce/billing/plans/{plan_code}/entitlements/{feature_code}. Path parameters: 
curl -X DELETE --location 'https://api-m.sandbox.paypal.com/v1/commerce/billing/plans/ubb_plan_1753837176/entitlements/api_access' \
  -H 'Authorization: Bearer <ACCESS-TOKEN>'
For the exhaustive list of request and response parameter descriptions, see API reference.