PApaypal
Subscriptions

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.

post/subscriptions/{external_subscription_id}/cancel

Request

Path parameters

external_subscription_idstring required

The unique external identifier of the subscription

Request body

cancel_option'IMMEDIATE' | 'END_OF_PERIOD'

Option specifying how the subscription should be canceled

Example request

{
  "cancel_option": "IMMEDIATE"
}

Response

Updated subscription object

namestring

The name of the subscription.

start_datestring date-time

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

end_datestring date-time

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

external_customer_idstring required

External reference to the customer

external_idstring required

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

plan_codestring required

The plan code

billing_time'CALENDAR' | 'ANNIVERSARY'

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

idstring

Unique identifier for the subscription

status'PENDING' | 'ACTIVE' | 'TERMINATED' | 'CANCELED'

The status of the subscription

canceled_atstring date-time

The date at which a pending subscription is canceled.

terminated_atstring date-time

The date at which an active subscription is canceled.

current_period_startstring date-time

Start date of the current billing period

current_period_endstring date-time

Date and time in ISO 8601 format.

trial_ended_atstring date-time

The date when the free trial is ended, represented in ISO 8601 date format

Example response

{
  "name": "Subscription_1",
  "start_date": "2025-06-01T00:00:00Z",
  "end_date": "2028-01-01T00:00:00Z",
  "external_customer_id": "client-jkl101",
  "external_id": "SUB_1752779018503",
  "plan_code": "Plan-Code-1753840215",
  "billing_time": "CALENDAR",
  "id": "b71befc2-4799-402c-9d13-ca1f72759c64",
  "status": "ACTIVE",
  "plan_overrides": {
    "amount": {
      "value": 120.35,
      "currency_code": "USD"
    },
    "description": "Plan for early stage startups",
    "invoice_display_name": "Startup plan",
    "name": "Startup",
    "charges": [
      {
        "id": "1a901a90-1a90-1a90-1a90-1a901a901a90",
        "charge_model": "GRADUATED",
        "taxes": [
          {
            "name": "TVA",
            "rate": "20.00",
            "description": "French standard VAT",
            "code": "standard_vat",
            "id": "1a901a90-1a90-1a90-1a90-1a901a901a90",
            "created_at": "2025-06-01T00:00:00Z"
          }
        ],
        "min_amount": {
          "value": 120.35,
          "currency_code": "USD"
        }
      }
    ],
    "minimum_commitment": {
      "amount": {
        "value": 120.35,
        "currency_code": "USD"
      },
      "invoice_display_name": "Minimum Commitment (C1)",
      "taxes": [
        {
          "name": "TVA",
          "rate": "20.00",
          "description": "French standard VAT",
          "code": "standard_vat",
          "id": "1a901a90-1a90-1a90-1a90-1a901a901a90",
          "created_at": "2025-06-01T00:00:00Z"
        }
      ],
      "id": "1a901a90-1a90-1a90-1a90-1a901a901a90",
      "plan_code": "premium",
      "created_at": "2022-04-29T08:59:51Z",
      "updated_at": "2022-04-29T08:59:51Z"
    },
    "chargeUsage": [
      {
        "id": "545-1a90-1a90-1a90-1a90-1a901a901a90",
        "recurring": "true",
        "threshold_display_name": "Startup",
        "created_at": "2023-10-01T12:00:00Z",
        "updated_at": "2023-10-01T12:00:00Z",
        "amount": {
          "value": 120.35,
          "currency_code": "USD"
        }
      }
    ],
    "taxes": [
      {
        "name": "TVA",
        "rate": "20.00",
        "description": "French standard VAT",
        "code": "standard_vat",
        "id": "1a901a90-1a90-1a90-1a90-1a901a901a90",
        "created_at": "2025-06-01T00:00:00Z"
      }
    ],
    "trial_period": 5
  },
  "canceled_at": "2025-01-01T00:00:00Z",
  "terminated_at": "2025-01-01T00:00:00Z",
  "current_period_start": "2025-05-01T00:00:00Z",
  "current_period_end": "2023-10-01T12:00:00Z",
  "trial_ended_at": "2025-05-01T00:00:00Z"
}

Changes

No recorded changes to this operation across all 1 revision of this API.