Cancel a subscription

Cancels a subscription and returns the attempt this request recorded. mode decides when it ends: at_period_end lets the period the buyer has already paid for run out, immediate ends it now. A subscription in trial can only be cancelled immediate.

Nothing is refunded or prorated, in either mode. To return money to the buyer, refund the payment through POST /v1/commerce/payments/{id}/refunds.

A 200 means the cancellation was accepted, not that the subscription has ended. It moves to canceling — never straight to cancelled — and cancel_at carries when it ends: the end of the paid period for at_period_end, the moment of the request for immediate. It reads cancelled once the payment provider has actually ended it.

subscription.cancelled is not sent when you call this. That event is written when the provider ends the subscription — for at_period_end, at the end of the paid period rather than now — and it carries cancellation_reason business_cancel.

Refused with 422 subscription_not_eligible when the subscription is already ending (already_canceling), is not one a cancel can end (not_active: only active, overdue, paused and trial can be), is in trial and was sent at_period_end (trial_requires_immediate), has no subscription at the payment provider (missing_processor_subscription), or has another change still processing (change_in_flight). An at_period_end cancel of an active or overdue subscription is also refused inside the 60 minutes before its renewal (too_close_to_renewal, a 422 of its own) or when no renewal date is known (renewal_date_unknown) — the renewal it would stop may already be billing. Neither can reach an immediate cancel or a paused subscription.

The body is optional and carries one member: reason, your own note, recorded on the attempt and returned with it. Text longer than 500 characters is truncated. mode is required.