Skip to main content
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 external customer ID, plan code, billing time, auto-renew setting, and metadata. Path parameter: external_subscription_id is the external_id you provided when you created the subscription. On successful request processing, PayPal returns the updated subscription details.
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).
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"
  }'
For the exhaustive list of request and response parameter descriptions, see API reference.

​
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. On successful request processing, PayPal returns the subscription details with status changed to CANCELED. 
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"
  }'
For the exhaustive list of request and response parameter descriptions, see API reference.

​
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. On successful request processing, PayPal returns the subscription details. The status remains ACTIVE until cancellation date. The response includes cancel_at_period_end set to true and cancellation_date showing when the subscription ends. 
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"
  }'
For the exhaustive list of request and response parameter descriptions, see API reference.

​
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. On successful request processing, PayPal updates privilege 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. These updates override the default plan entitlements for this specific subscription. 
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"
              }
          }
      ]
  }'
For the exhaustive list of request and response parameter descriptions, see API reference.
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. On successful request processing, PayPal returns the subscription’s entitlements, showing both plan defaults and any subscription-specific overrides. 
curl -X GET -L 'https://api-m.sandbox.paypal.com/v1/commerce/billing/subscriptions/SUB_1752779018503/entitlements' \
  -H 'Authorization: Bearer <ACCESS-TOKEN>'
For the exhaustive list of response parameter descriptions, see API reference.

​
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>'
For the exhaustive list of response parameter descriptions, see API reference.

​
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>'
For the exhaustive list of response parameter descriptions, see API reference.