Cancel Subscription
Cancel a subscription with optional timing and refund handling.
Supports three timing options via the `cancel_timing` field:
- **immediately** (default): Cancel the subscription now.
- **at_period_end**: Schedule cancellation for end of current billing period.
- **on_date**: Schedule cancellation for a specific date (requires `cancel_at`).
Supports four refund options via the `refund_option` field:
- **none** (default): Cancel with no refund. Open invoices are voided.
- **full**: Refund the full paid amount for the current billing period.
- **prorated**: Refund the unused portion of the current period based on
cancellation date. Uses seconds-based proration for precision.
- **cancel_unpaid**: Void all open/draft invoices without issuing refunds.
For scheduled cancellations (at_period_end or on_date):
- The refund option is stored and applied when cancellation is executed.
- Response includes `cancel_at` showing when cancellation will occur.
- Preview mode shows what the refund would be at the scheduled time.
Works for User, API Key, and Restate workflow authentication.
Account access is automatically validated via endpoint dependency.
Authentication
AuthorizationBearer
Bearer authentication of the form Bearer <token>, where token is your auth token.
Path parameters
subscription_id
account_id
Headers
X-Restate-Secret-Key
X-System-Reason
Request
This endpoint expects a nullable object.
cancel_timing
When to cancel the subscription
cancel_at
Specific datetime for cancellation. Required when cancel_timing is ON_DATE.
refund_option
Refund option for cancellation
is_preview
If true, returns preview without making changes
cancellation_details
Optional details about why the subscription is being cancelled (comment, feedback, reason)
Response
Successful Response
SubscriptionResponse
OR
CancelSubscriptionWithRefundResponse
Errors
422
Unprocessable Entity Error