---
title: "Cancel subscription"
method: PATCH
path: "/subscriptions/{id}/cancel"
tags: ["Subscriptions"]
---

# Cancel subscription

`PATCH /subscriptions/{id}/cancel`

Cancels a subscription using the supplied cancellation request.

Supported cancellation types:
* PeriodEnd - Cancel subscription at the end of the billing cycle
* Immediate - Cancel subscription immediately
* Date - Cancel at specified 'CancelAt' date

If not supplied, PeriodEnd is used and the subscription is cancelled at the end of the billing cycle.

Default behaviour:
* If the subscription is trialing a tier, the tier is reverted to the previous tier at the end of the trials duration. This is only supported with PeriodEnd CancellationType.
* If the subscription is trialing add-on(s), the add-on is removed at the end of the trials duration. This is only supported with PeriodEnd CancellationType.

Important considerations:
* If 'cancelSubscription' is specified and set to 'true', the default behaviour specified above is ignored and the cancellation is applied directly on the subscription.

## Path parameters

- `id` string, required

## Request body

- CancelSubscriptionRequest
  - `cancellationType` string — The subscription cancellation type. * None - No cancellation type has been set. * PeriodEnd - Cancel subscription at the end of the billing cycle. * Immediate - Cancel subscription immediately. * Date - Cancel at specified date - see 'CancelAt'.
  - `cancelAt` string, date-time, nullable — Optional date used to cancel at the supplied date. Will only be used if CancellationType is set to 'Date'. If set to a date before the current period ends, this will cause a proration if prorations have been enabled. If set during a future period, this will always cause a proration for that period.
  - `cancelSubscription` boolean, nullable — Optional flag to force cancellation of a subscription. When set to `true`, immediately cancels the subscription and bypasses any configured cancellation behaviour. For example, if cancellation would normally trigger trial-specific cancellation handling such as revoking a trial, setting this flag to `true` cancels the subscription directly instead.
  - `reason` string, nullable — Optional reason for cancellation of the subscription.
  - `preview` boolean — Optional flag to preview cancellation request. If 'true', the Subscription is not cancelled and the CancellationType and CancellationDate are returned.

## Response `200`

When request is successful. Returns a 'CancellationResponse' object.

- CancellationResponse
  - `preview` boolean — True if this is a cancellation preview.
  - `cancellationType` string — The subscription cancellation type. * None - No cancellation type has been set. * PeriodEnd - Cancel subscription at the end of the billing cycle. * Immediate - Cancel subscription immediately. * Date - Cancel at specified date - see 'CancelAt'.
  - `cancellationBehaviour` string — The subscription cancellation behaviour. * Cancel - Standard behaviour. The subscription will be canceled as normal. * CancelTrials - Any trials applied to the subscription will be canceled.
  - `cancelAt` string, date-time, nullable — The date the subscription will be cancelled.
  - `reason` string, nullable — The reason for cancellation.
  - `tier` Tier
    - `id` string, uuid — Unique identifier of the tier.
    - `href` string, nullable
    - `relation` string, nullable
    - `method` string, nullable
    - `self` Link
      - `id` string, nullable
      - `href` string, nullable
      - `relation` string, nullable
      - `method` string, nullable
    - `smokeballId` string, nullable — Unique Smokeball identifier of the tier. This identifier convenience purposes only and should not be used to interact with the subscriptions API.
    - `productSuite` string, nullable — The product suite that this tier belongs to.
    - `name` string, nullable — The display name of the tier.
    - `description` string, nullable — The description of the tier. Can be used to describe the tier to a customer.
    - `trialPeriodDays` integer, nullable — The number of days the tier can be trialed for. Cannot be trialed if zero or missing.
    - `prices` Price[], nullable — The price options for the tier.
      - `id` string, nullable — The internal price id.
      - `externalPriceId` string, nullable — The external price id.
      - `default` boolean — Returns `true` if the price is the default price.
      - `active` boolean — Returns `true` if the Price is active.
      - `type` string — The type of price.
      - `name` string, nullable — The price display name.
      - `amount` number, double, nullable — The per unit amount for this pricing option for the specified interval (in cents).
      - `interval` string — Recurring payment interval type.
    - `createdDate` string, date-time — The created date of the tier.
    - `updatedDate` string, date-time — The updated date of the tier.
  - `addOns` AddOn[], nullable — The add-ons that will be set at the as a result of the cancellation.
    - `id` string, uuid — Unique identifier of the add-on.
    - `href` string, nullable
    - `relation` string, nullable
    - `method` string, nullable
    - `self` Link
      - `id` string, nullable
      - `href` string, nullable
      - `relation` string, nullable
      - `method` string, nullable
    - `smokeballId` string, nullable — Unique Smokeball identifier of the add-on. This identifier convenience purposes only and should not be used to interact with the subscriptions API.
    - `productSuite` string, nullable — The product suite that this add-on belongs to.
    - `name` string, nullable — The display name of the add-on.
    - `description` string, nullable — The description of the add-on. Can be used to describe the add-on to a customer.
    - `trialPeriodDays` integer, nullable — The number of days the add-on can be trialed for. Cannot be trialed if zero or missing.
    - `prices` Price[], nullable — The price options for the add-on.
      - `id` string, nullable — The internal price id.
      - `externalPriceId` string, nullable — The external price id.
      - `default` boolean — Returns `true` if the price is the default price.
      - `active` boolean — Returns `true` if the Price is active.
      - `type` string — The type of price.
      - `name` string, nullable — The price display name.
      - `amount` number, double, nullable — The per unit amount for this pricing option for the specified interval (in cents).
      - `interval` string — Recurring payment interval type.
    - `createdDate` string, date-time — The created date of the add-on.
    - `updatedDate` string, date-time — The updated date of the add-on.

## Other responses

- `400` — When an unsupported request is made.
- `404` — When subscription with specified id does not exist.
- `500` — When an error occurs while canceling the subscription.

---

[API](https://skmtc.net/smokeball/apis/api.md) · [All operations](https://skmtc.net/smokeball/apis/api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/smokeball/api/versions/197984da9b42/schema)