v2

latestOpenAPI 3.0.12026-07-262352981007.0 KB

Subscriptions

Cancel subscription

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.

patch/subscriptions/{id}/cancel

Path parameters

idstring required

The unique identifier of the subscription

Request body

cancellationTypestring

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'.

cancelAtstring 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.

cancelSubscriptionboolean 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.

reasonstring nullable

Optional reason for cancellation of the subscription.

previewboolean

Optional flag to preview cancellation request.

If 'true', the Subscription is not cancelled and the CancellationType and CancellationDate are returned.

Example request

{
  "preview": true
}

Response

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

previewboolean

True if this is a cancellation preview.

cancellationTypestring

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'.

cancellationBehaviourstring

The subscription cancellation behaviour.

Cancel - Standard behaviour. The subscription will be canceled as normal.
CancelTrials - Any trials applied to the subscription will be canceled.

cancelAtstring date-time nullable

The date the subscription will be cancelled.

reasonstring nullable

The reason for cancellation.

Example response

{
  "tier": {
    "id": "b471682e-fa17-4e46-b7fe-9b2b8fdcb3c2",
    "name": "Intake",
    "prices": [
      {
        "default": true,
        "active": true,
        "type": "Recurring",
        "name": "\"$109 per user/month\"",
        "amount": 5900,
        "interval": "Monthly"
      }
    ],
    "createdDate": "2022-04-23T14:00:00Z",
    "updatedDate": "2022-04-23T14:00:00Z"
  },
  "addOns": [
    {
      "id": "b471682e-fa17-4e46-b7fe-9b2b8fdcb3c2",
      "name": "Intake",
      "prices": [
        {
          "default": true,
          "active": true,
          "type": "Recurring",
          "name": "\"$109 per user/month\"",
          "amount": 5900,
          "interval": "Monthly"
        }
      ],
      "createdDate": "2022-04-23T14:00:00Z",
      "updatedDate": "2022-04-23T14:00:00Z"
    }
  ]
}