Sign in
Subscriptions

Cancel a Subscription

Schedules a Subscription cancellation for the end of the current billing cycle (the default), for the end of the next one, or applies it immediately

post/subscriptions/{id}/cancel

Path parameters

idstring required

Request body

cancelImmediatelyboolean

Deprecated — use cancelAt instead. Whether to cancel the subscription immediately. If false, it will cancel at the end of the current period. Equivalent to cancelAt: "immediately" and cancelAt: "end_of_current_cycle" respectively.

cancelAt'immediately' | 'end_of_current_cycle' | 'end_of_next_cycle'

Which period boundary the cancellation lands on. end_of_next_cycle lets the upcoming renewal charge go through and cancels once that period ends. Takes precedence over the deprecated cancelImmediately; defaults to end_of_current_cycle.

Response

OK

createdAtstring date-time required

The date and time when the entity was created.

updatedAtstring date-time nullable required

The date and time when the entity was last updated.

metadataobject nullable

Metadata used by merchants to store additional information about the entity.

idstring required

The ID of the subscription

status'active' | 'cancelled' required

The status of the subscription

isRecoveringboolean required

Whether the subscription is recovering from a failed payment

autoBillingEnabledboolean required

Whether the subscription is going to be billed automatically

autoBillingDisabledAtstring date-time nullable required

The date when auto billing was disabled

autoBillingDisabledReason'recurring_payment_errored' | 'subscription_cancelled' | 'latest_invoice_retrying' | 'null' nullable required

The reason why auto billing was disabled

startDatestring date-time required

The start date of the subscription

endDatestring date-time nullable required

The end date of the subscription, if it has ended

cancelAtPeriodEndboolean required

Whether the subscription should be cancelled when current billing cycle ends

cancelAtCyclenumber nullable required

The cycle at whose end the subscription is scheduled to be cancelled, or absent when no cancellation is scheduled. Equals currentCycle once cancelAtPeriodEnd is true

currentCyclenumber required

The current cycle of the subscription, starting from 1

currentPeriodStartstring date-time required

The start date of the current billing period

currentPeriodEndstring date-time required

The end date of the current billing period

setupInvoicestring required

The ID of the invoice that set up the subscription

setupLineItemstring nullable required

The ID of the line item that set up the subscription

Example response

{
  "createdAt": "2024-02-18T12:00:00Z",
  "updatedAt": "2024-02-21T12:15:00Z",
  "metadata": {
    "key1": "value1",
    "key2": "value2"
  },
  "id": "sub_2QC7PqoUeOxQEWscJJt6B3PkvyL",
  "status": "active",
  "autoBillingEnabled": true,
  "autoBillingDisabledReason": "subscription_cancelled",
  "cancelAtPeriodEnd": true,
  "cancelAtCycle": 2,
  "currentCycle": 1,
  "billingSettings": {
    "captureDelay": 3
  },
  "upcomingInvoice": {
    "amount": 1500,
    "currency": "usd",
    "periodStart": "2023-01-01T00:00:00Z",
    "periodEnd": "2023-01-31T23:59:59Z",
    "statementDescriptor": "SUBSCRIPTION",
    "comment": "Invoice for subscription 123, period January 2023"
  },
  "customer": {
    "createdAt": "2024-02-18T12:00:00Z",
    "updatedAt": "2024-02-21T12:15:00Z",
    "metadata": {
      "key1": "value1",
      "key2": "value2"
    },
    "id": "cus_2QC7PqoUeOxQEWscJJt6B3PkvyL",
    "email": "user@gmail.com",
    "name": "John Doe",
    "phoneNumber": "+1234567890",
    "dateOfBirth": "2020-01-01",
    "gender": "male",
    "restrictReason": "Customer restricted due to suspicious activity",
    "isRestricted": true
  },
  "price": {
    "createdAt": "2024-02-18T12:00:00Z",
    "updatedAt": "2024-02-21T12:15:00Z",
    "metadata": {
      "key1": "value1",
      "key2": "value2"
    },
    "id": "price_2R4e2xDqbww8ewmkIYWE1A6Zcfp",
    "type": "recurring",
    "active": true,
    "name": "My Digital Subscription",
    "amount": 1500,
    "quantity": 1,
    "currency": "usd",
    "product": {
      "createdAt": "2024-02-18T12:00:00Z",
      "updatedAt": "2024-02-21T12:15:00Z",
      "metadata": {
        "key1": "value1",
        "key2": "value2"
      },
      "id": "prod_2QC7PqoUeOxQEWscJJt6B3PkvyL",
      "active": true,
      "name": "My product",
      "description": "Best selling product",
      "statementDescriptor": "Face Yoga subscription",
      "category": "digital",
      "sku": "FY-YOGA-MAT-01"
    },
    "billingSchedule": {
      "createdAt": "2024-02-18T12:00:00Z",
      "updatedAt": "2024-02-21T12:15:00Z",
      "metadata": {
        "key1": "value1",
        "key2": "value2"
      },
      "id": "bsch_2QC7PqoUeOxQEWscJJt6B3PkvyL",
      "currency": "usd",
      "cycleDefinitions": [
        {
          "createdAt": "2024-02-18T12:00:00Z",
          "updatedAt": "2024-02-21T12:15:00Z",
          "metadata": {
            "key1": "value1",
            "key2": "value2"
          },
          "position": 1,
          "amount": 1500,
          "currency": "usd"
        }
      ]
    },
    "recurringSchedule": {
      "intervalUnit": "month",
      "intervalCount": 1,
      "trial": {
        "intervalUnit": "day",
        "intervalCount": 7,
        "amount": 199
      }
    }
  },
  "invoices": [
    {
      "createdAt": "2024-02-18T12:00:00Z",
      "updatedAt": "2024-02-21T12:15:00Z",
      "metadata": {
        "key1": "value1",
        "key2": "value2"
      },
      "status": "open",
      "voidedReason": "Grace period expired",
      "comment": "This is a comment for the invoice",
      "amount": 999,
      "currency": "usd",
      "type": "setup",
      "number": "2W12-1004",
      "customer": {
        "createdAt": "2024-02-18T12:00:00Z",
        "updatedAt": "2024-02-21T12:15:00Z",
        "metadata": {
          "key1": "value1",
          "key2": "value2"
        },
        "id": "cus_2QC7PqoUeOxQEWscJJt6B3PkvyL",
        "email": "user@gmail.com",
        "name": "John Doe",
        "phoneNumber": "+1234567890",
        "dateOfBirth": "2020-01-01",
        "gender": "male",
        "restrictReason": "Customer restricted due to suspicious activity",
        "isRestricted": true
      }
    }
  ]
}

Changes

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