Skip to main content

​
Cancellation lifecycle

A regular cancellation is scheduled for the end of the current billing period. Two events fire at different moments:

​
Immediate terminations

Some terminations skip the schedule: subscription.canceled arrives right away, with no prior subscription.updated, and endDate is the moment of termination — not a billing period boundary.
  • POST /subscriptions/{id}/cancel with immediate: true. Cancellations of free plans and of subscriptions in pending_payment or past_due also settle immediately — canceling inside the dunning grace window voids the unpaid renewal.
  • Exhausted dunning retries: fires with cancelReason: "dunning_exhausted", alongside payment.retry_failed.
  • A trial without a payment method that ends without a card: fires with cancelReason: "trial_ended_without_payment_method".
When the plan group has a default plan, exhausted dunning retries and a trial that ends without a card move the subscription to that plan instead, and subscription.plan_changed fires. Refunding a payment does not cancel its subscription. If you want both outcomes, request a cancellation separately. Older cancellation events triggered by refunds may have cancelReason: "refund".

Body

application/json
​
id
string
required
​
event
string
required
Allowed value: "subscription.canceled"
​
timestamp
string
required
​
organizationId
string
required
​
mode
enum<string>
required
Available options:
live,
sandbox
​
apiVersion
string
required
​
data
object
required

Response

200

Return any 2xx status code to acknowledge receipt of the event.