Skip to main content
POST
/
subscriptions
/
{id}
/
cancel
curl --request POST \
  --url https://api-m.paypal.com/v1/commerce/billing/subscriptions/{id}/cancel \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{
  "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"
}

Authorizations

​
Authorization
string
header
required

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

Path Parameters

​
external_subscription_id
string
required

The unique external identifier of the subscription

Body

application/json

Cancel request for a subscription.

​
cancel_option
enum<string>
default:IMMEDIATE

Option specifying how the subscription should be canceled

Available options:
IMMEDIATE,
END_OF_PERIOD
Example:

"IMMEDIATE"

Response

Updated subscription object

​
external_customer_id
string
required

External reference to the customer

Example:

"client-jkl101"

​
external_id
string
required

The subscription external unique identifier supplied by client. Must contain only alphanumeric characters, underscores, and hyphens.

Example:

"SUB_1752779018503"

​
plan_code
string
required

The plan code

Example:

"Plan-Code-1753840215"

​
id
string

Unique identifier for the subscription

Example:

"b71befc2-4799-402c-9d13-ca1f72759c64"

​
status
enum<string>

The status of the subscription

Available options:
PENDING,
ACTIVE,
TERMINATED,
CANCELED
Example:

"ACTIVE"

​
plan_overrides
object
​
canceled_at
string<date-time>

Date and time in ISO 8601 format. The date at which a pending subscription is canceled.

Example:

"2025-01-01T00:00:00Z"

​
terminated_at
string<date-time>

Date and time in ISO 8601 format. The date at which an active subscription is canceled.

Example:

"2025-01-01T00:00:00Z"

​
current_period_start
string<date-time>

Date and time in ISO 8601 format. Start date of the current billing period

Example:

"2025-05-01T00:00:00Z"

​
current_period_end
string<date-time>

End date of the current billing period Date and time in ISO 8601 format.

Example:

"2023-10-01T12:00:00Z"

​
trial_ended_at
string<date-time>

Date and time in ISO 8601 format. The date when the free trial is ended, represented in ISO 8601 date format

Example:

"2025-05-01T00:00:00Z"

​
name
string

The name of the subscription.

Example:

"Subscription_1"

​
start_date
string<date-time>

Date and time in ISO 8601 format. The effective start date of the subscription; can be past, current, or future. Date must be provided in ISO 8601 format

Example:

"2025-06-01T00:00:00Z"

​
end_date
string<date-time>

Date and time in ISO 8601 format. The subscription will terminate on this date without renewal. Date must be provided in ISO 8601 format

Example:

"2028-01-01T00:00:00Z"

​
billing_time
enum<string>
default:CALENDAR

The billing time for the subscription, which can be set as either anniversary or calendar

Available options:
CALENDAR,
ANNIVERSARY
Example:

"CALENDAR"

⌘I