Cancel a subscription

This endpoint allows you to cancel an existing subscription. You can either cancel immediately or set it to cancel at the end of the current billing period.

Authorization

AuthorizationBearer <token>

Use the /v1/oauth2/token endpoint to obtain an access token and pass it as a Bearer token in the Authorization header.

FlowClient CredentialsToken URLhttps://api-m.sandbox.paypal.com/v1/oauth2/tokenInheader

Scopes

Read accessread
Write accesswrite

Path Parameters

external_subscription_id*string

The unique external identifier of the subscription

Request Body

application/json

TypeScript Definitions

Use the request body type in TypeScript.

Response Body

`application/json`

curl -X POST "https://api-m.sandbox.paypal.com/subscriptions/5eb02857-a71e-4ea2-bcf9-57d3a41bc6ba/cancel" \  -H "Content-Type: application/json" \  -d '{    "cancel_option": "END_OF_PERIOD"  }'

{
  "name": "Subscription-008",
  "external_customer_id": "5eb02857-a71e-4ea2-bcf9-1754931701",
  "external_id": "Subscription-008",
  "plan_code": "Plan-Code-343435-1754679147",
  "billing_time": "ANNIVERSARY",
  "status": "ACTIVE",
  "plan_overrides": {
    "amount": {
      "value": 50,
      "currency_code": "USD"
    },
    "name": "Storage usage plan",
    "trial_period": 14,
    "charges": [
      {
        "id": "1a901a90-1a90-1a90-1a90-1a901a901a90",
        "metric_id": "1a901a90-1a90-1a90-1a90-1a901a901a90",
        "properties": {
          "amount": "1.11"
        }
      }
    ]
  },
  "start_date": "2025-08-01T00:00:00Z",
  "end_date": "2025-08-14T23:59:59Z",
  "current_period_start": "2025-08-08T00:00:00Z",
  "current_period_end": "2025-08-14T23:59:59Z",
  "id": "464a77f7-3905-4717-a669-255febedb524"
}

{
  "name": "INVALID_REQUEST",
  "debug_id": "a109791e6c096bcaa74a45d27630d3e4",
  "message": "Request is not well-formed, syntactically incorrect, or violates schema.",
  "details": [
    {
      "field": "cancel_option",
      "location": "body",
      "issue": "INVALID_PARAMETER_VALUE",
      "description": "A parameter value is not valid."
    }
  ]
}

{
  "name": "NOT_AUTHORIZED",
  "message": "Authorization failed due to insufficient permissions.",
  "debug_id": "565f78f101498",
  "details": [
    {
      "issue": "PERMISSION_DENIED",
      "description": "You do not have permission to access or perform operations on this resource."
    }
  ]
}

{
  "name": "string",
  "debug_id": "string",
  "message": "string",
  "details": [
    {
      "field": "string",
      "value": "string",
      "location": "string",
      "issue": "string",
      "description": "string"
    }
  ]
}

{
  "name": "UNPROCESSABLE_ENTITY",
  "debug_id": "162925068ef2df7a6adb93b3a4d7869d",
  "message": "The requested action could not be performed, semantically incorrect, or failed business validation.",
  "details": [
    {
      "issue": "CANCEL_OPTION_NOT_SUPPORTED",
      "description": "Pending subscriptions can be cancelled only with cancel option as IMMEDIATE."
    }
  ]
}

{
  "name": "INTERNAL_SERVER_ERROR",
  "message": "An internal server error has occurred.",
  "debug_id": "90957fca61718"
}

Path Parameters

external_subscription_id*string

The unique external identifier of the subscription

Request Body

application/json

TypeScript Definitions

Use the request body type in TypeScript.

cancel_option?CancelOption

Option specifying how the subscription should be canceled

Default"IMMEDIATE"

Value in"IMMEDIATE" | "END_OF_PERIOD"

{ "name": "Subscription-008", "external_customer_id": "5eb02857-a71e-4ea2-bcf9-1754931701", "external_id": "Subscription-008", "plan_code": "Plan-Code-343435-1754679147", "billing_time": "ANNIVERSARY", "status": "ACTIVE", "plan_overrides": { "amount": { "value": 50, "currency_code": "USD" }, "name": "Storage usage plan", "trial_period": 14, "charges": [ { "id": "1a901a90-1a90-1a90-1a90-1a901a901a90", "metric_id": "1a901a90-1a90-1a90-1a90-1a901a901a90", "properties": { "amount": "1.11" } } ] }, "start_date": "2025-08-01T00:00:00Z", "end_date": "2025-08-14T23:59:59Z", "current_period_start": "2025-08-08T00:00:00Z", "current_period_end": "2025-08-14T23:59:59Z", "id": "464a77f7-3905-4717-a669-255febedb524" }

{ "name": "INVALID_REQUEST", "debug_id": "a109791e6c096bcaa74a45d27630d3e4", "message": "Request is not well-formed, syntactically incorrect, or violates schema.", "details": [ { "field": "cancel_option", "location": "body", "issue": "INVALID_PARAMETER_VALUE", "description": "A parameter value is not valid." } ] }

{ "name": "NOT_AUTHORIZED", "message": "Authorization failed due to insufficient permissions.", "debug_id": "565f78f101498", "details": [ { "issue": "PERMISSION_DENIED", "description": "You do not have permission to access or perform operations on this resource." } ] }

{ "name": "string", "debug_id": "string", "message": "string", "details": [ { "field": "string", "value": "string", "location": "string", "issue": "string", "description": "string" } ] }

{ "name": "UNPROCESSABLE_ENTITY", "debug_id": "162925068ef2df7a6adb93b3a4d7869d", "message": "The requested action could not be performed, semantically incorrect, or failed business validation.", "details": [ { "issue": "CANCEL_OPTION_NOT_SUPPORTED", "description": "Pending subscriptions can be cancelled only with cancel option as IMMEDIATE." } ] }

Cancel a subscription

200application/json

400application/json

403application/json

404application/json

422application/json

500application/json

An Active subscription canceled at end of period

An Active subscription canceled immediately

Pending subscription canceled immediately

Active subscription canceled with out passing cancel option in request

Cancel pending subscription with cancel option as end of period

Subscription already cancelled

On this page

If you accept cookies, we’ll use them to improve and customize your experience and enable our partners to show you personalized PayPal ads when you visit other sites. Manage cookies and learn more

Cancel a subscription

200application/json

400application/json

403application/json

404application/json

422application/json

500application/json

An Active subscription canceled at end of period

An Active subscription canceled immediately

Pending subscription canceled immediately

Active subscription canceled with out passing cancel option in request

Cancel pending subscription with cancel option as end of period

Subscription already cancelled

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`