Skip to main content
Limited Release
Subscription management helps you update existing subscriptions when your business requirements change. You can modify subscription details, change plan assignments, and cancel subscriptions when necessary. This ability ensures appropriate billing and customer satisfaction with flexible options for immediate and delayed cancellations.

​
Update subscription details

Use a valid access token and make a PUT call to the /v1/commerce/billing/subscriptions/{external_subscription_id} endpoint with the modified request parameters such as name, plan overrides, start date, and end date. Path parameter: external_subscription_id is the external_id you provided when you created the subscription.
When updating subscription charges in plan_overrides.charges[], use the id field to identify which charge to override. The id should match a charge from the plan’s usage_based_charges array. In the response, PayPal returns both id (charge identifier) and metric_id (the metric the charge applies to).
For information on all parameters, see API reference. 
curl -X PUT -L 'https://api-m.sandbox.paypal.com/v1/commerce/billing/subscriptions/Subscription_External_1' \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer <ACCESS-TOKEN>' \
  -d '{
      "name": "Updated Subscription Name",
      "status": "ACTIVE",
      "plan_overrides": {
          "amount": {
              "value": 25.00
          },
          "name": "Updated Plan Name",
          "trial_period": 7,
          "tax_codes": [
              "standard_vat"
          ],
          "charges": [
              {
                  "id": "99fa7a6b-d005-43a5-8bab-0df7a2a721fb",
                  "properties": {
                      "amount": "0.50"
                  },
                  "min_amount": {
                      "value": 5.00
                  },
                  "tax_codes": [
                      "standard_vat"
                  ]
              }
          ]
      },
      "start_date": "2025-07-30T01:54:40Z",
      "end_date": "2025-09-09T04:26:24Z"
  }'
A successful call returns a 200 OK response with the updated subscription details.

​
Cancel a subscription

Subscription cancellation provides flexible options for ending billing relationships. You can cancel:
  • Active subscriptions: Subscriptions currently in effect. Can be cancelled immediately or scheduled for the end of the current billing period.
  • Pending subscriptions: Subscriptions scheduled to start in the future or new plans from downgrades waiting to take effect at the end of the billing period. Can only be cancelled immediately.

​
Cancel immediately

Use a valid access token and make a POST call to the /v1/commerce/billing/subscriptions/{external_subscription_id}/cancel endpoint with cancel_option set to IMMEDIATE. Path parameter: external_subscription_id is the external_id you provided when you created the subscription. For information on all parameters, see API reference. 
curl -X POST -L 'https://api-m.sandbox.paypal.com/v1/commerce/billing/subscriptions/SUB_1752779018503/cancel' \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer <ACCESS-TOKEN>' \
  -d '{
      "cancel_option": "IMMEDIATE"
  }'
A successful call returns a 200 OK response with the subscription details showing status changed to CANCELED.

​
Cancel at period end

Use a valid access token and make a POST call to the /v1/commerce/billing/subscriptions/{external_subscription_id}/cancel endpoint with cancel_option set to END_OF_PERIOD. Path parameter: external_subscription_id is the external_id you provided when you created the subscription. For information on all parameters, see API reference. 
curl -X POST -L 'https://api-m.sandbox.paypal.com/v1/commerce/billing/subscriptions/SUB_1752779018503/cancel' \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer <ACCESS-TOKEN>' \
  -d '{
      "cancel_option": "END_OF_PERIOD"
  }'
A successful call returns a 200 OK response with the subscription details. The status remains ACTIVE until the cancellation date. The response includes cancel_at_period_end set to true and cancellation_date showing when the subscription ends.

​
Manage subscription entitlements

Subscription entitlements allow you to customize feature access and capabilities for individual subscriptions, overriding the default plan entitlements. This provides flexibility to offer tailored features, limits, and permissions to specific customers based on their needs or negotiated agreements.

​
Update subscription entitlements

Use a valid access token and make a PATCH call to the /v1/commerce/billing/subscriptions/{external_subscription_id}/entitlements endpoint with the entitlements to update. Path parameter: external_subscription_id is the external_id you provided when you created the subscription. For information on all parameters, see API reference. 
curl -X PATCH -L 'https://api-m.sandbox.paypal.com/v1/commerce/billing/subscriptions/SUB_1752779018503/entitlements' \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer <ACCESS-TOKEN>' \
  -d '{
      "entitlements": [
          {
              "feature_code": "seats",
              "feature_privilege_values": {
                  "max": 200,
                  "max_admins": 20,
                  "root": true,
                  "guest_access": true
              }
          },
          {
              "feature_code": "api_access",
              "feature_privilege_values": {
                  "rate_limit": 50000,
                  "endpoints": "premium"
              }
          }
      ]
  }'
A successful call returns a 200 OK response with the updated subscription entitlements. New privileges or features are added, existing values are overwritten if duplicates are found, and items not included remain unchanged.
The response includes both plan_value and override_value parameters. The plan_value shows the default value from the plan, while override_value shows the customized value for this subscription.

​
List subscription entitlements

Use a valid access token and make a GET call to the /v1/commerce/billing/subscriptions/{external_subscription_id}/entitlements endpoint to retrieve all entitlements for a specific subscription. Path parameter: external_subscription_id is the external_id you provided when you created the subscription. 
curl -X GET -L 'https://api-m.sandbox.paypal.com/v1/commerce/billing/subscriptions/SUB_1752779018503/entitlements' \
  -H 'Authorization: Bearer <ACCESS-TOKEN>'
A successful call returns a 200 OK response with the subscription entitlements, showing both plan defaults and any subscription-specific overrides.

​
Remove privilege overrides

Use a valid access token and make a DELETE call to the /v1/commerce/billing/subscriptions/{external_subscription_id}/entitlements/{feature_code}/privileges/{privilege_code} endpoint to remove a privilege override for a subscription and revert to the plan default. Path parameters: 
curl -X DELETE -L 'https://api-m.sandbox.paypal.com/v1/commerce/billing/subscriptions/SUB_1752779018503/entitlements/seats/privileges/guest_access' \
  -H 'Authorization: Bearer <ACCESS-TOKEN>'
A successful call returns a 204 No Content response.

​
Remove subscription entitlement overrides

Use a valid access token and make a DELETE call to the /v1/commerce/billing/subscriptions/{external_subscription_id}/entitlements/{feature_code} endpoint to remove all overrides for a specific subscription and revert to plan defaults. Path parameters: 
curl -X DELETE -L 'https://api-m.sandbox.paypal.com/v1/commerce/billing/subscriptions/SUB_1752779018503/entitlements/api_access' \
  -H 'Authorization: Bearer <ACCESS-TOKEN>'
A successful call returns a 204 No Content response.