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 send a PUT request to /v1/commerce/billing/subscriptions/{id} with the modified request parameters such as external customer ID, plan code, billing time, auto-renew setting, and metadata. Path parameter: id is the subscription ID returned when you created the subscription. On successful request processing, PayPal returns the updated subscription details.
Important: When updating subscription charges in plan_overrides.charges[], ensure you include both the id and metric_id fields for each charge you want to modify. The id identifies the specific charge to update and metric_id identifies the metric associated with that charge. Both fields are required. 
curl -X PUT --location 'https://api-m.sandbox.paypal.com/v1/commerce/billing/subscriptions/b71befc2-4799-402c-9d13-ca1f72759c64' \
  -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",
                  "metric_id": "2e097d19-1350-4baf-8add-5d19ecef8113",
                  "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"
  }'
Note: 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 send a POST request to /v1/commerce/billing/subscriptions/{id}/cancel with cancel_option set to IMMEDIATE. Path parameter: id is the subscription ID returned when you created the subscription. On successful request processing, PayPal returns the subscription details with status changed to CANCELED. 
curl -X POST --location '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"
  }'
Note: For the exhaustive list of request and response parameter descriptions, see API reference.

​
Cancel at period end

Use a valid access token and send a POST request to /v1/commerce/billing/subscriptions/{id}/cancel with cancel_option set to END_OF_PERIOD. Path parameter: id is the subscription ID returned 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 will end. 
curl -X POST --location '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"
  }'
Note: 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 send a PATCH request to /v1/commerce/billing/subscriptions/{external_id}/entitlements with the entitlements to update. Path parameter: external_id is the external subscription ID 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 --location '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"
              }
          }
      ]
  }'
Notes:
  • 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 send a GET request to /v1/commerce/billing/subscriptions/{external_id}/entitlements to retrieve all entitlements for a specific subscription. Path parameter: external_id is the external subscription ID 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 --location 'https://api-m.sandbox.paypal.com/v1/commerce/billing/subscriptions/SUB_1752779018503/entitlements' \
  -H 'Authorization: Bearer <ACCESS-TOKEN>'
Note: For the exhaustive list of response parameter descriptions, see API reference.

​
Remove privilege overrides

To remove a privilege override for a subscription and revert to the plan default, send a DELETE request to /v1/commerce/billing/subscriptions/{external_id}/entitlements/{feature_code}/privileges/{privilege_code}. Path parameters: 
curl -X DELETE --location 'https://api-m.sandbox.paypal.com/v1/commerce/billing/subscriptions/SUB_1752779018503/entitlements/seats/privileges/guest_access' \
  -H 'Authorization: Bearer <ACCESS-TOKEN>'
Note: For the exhaustive list of response parameter descriptions, see API reference.

​
Remove subscription entitlement overrides

To remove all overrides for a specific subscription and revert to plan defaults, use a valid access token and send a DELETE request to /v1/commerce/billing/subscriptions/{external_id}/entitlements/{feature_code}. Path parameters: 
curl -X DELETE --location 'https://api-m.sandbox.paypal.com/v1/commerce/billing/subscriptions/SUB_1752779018503/entitlements/api_access' \
  -H 'Authorization: Bearer <ACCESS-TOKEN>'
Note: For the exhaustive list of response parameter descriptions, see API reference.
⌘I