Skip to main content
Limited Release
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 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 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 aren’t updated even with cascading_updates set to true. For these two parameters, only the unmodified values from the original plan receive updates.
For information on all parameters, see API reference. 
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"
          ]
      }
  }'
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 valid access token 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 created the plan. 
curl -X GET -L 'https://api-m.sandbox.paypal.com/v1/commerce/billing/plans/ubb_plan_1753837176/entitlements' \
  -H 'Authorization: Bearer <ACCESS-TOKEN>'
A successful call returns a 200 OK response with the plan entitlements.

​
Update plan entitlements

Use a valid access token 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 created the plan. For information on all parameters, see API reference. 
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
              }
          }
      ]
  }'
A successful call returns a 200 OK response with the updated plan entitlements.

​
Remove privilege from feature entitlement

Use a valid access token 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: 
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>'
A successful call returns a 204 No Content response.

​
Remove feature entitlement from plan

Use a valid access token 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: 
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>'
A successful call returns a 204 No Content response.