Skip to main content
POST
Cancel Subscription
Cancel the authenticated user’s active subscription. Can cancel immediately or at the end of the current billing period.

Authentication

This endpoint requires end user authentication via HTTP Bearer Token with project scope.

Query Parameters

test_mode
boolean
default:"true"
Use test mode credentials. Set to false for production.

Request Body

cancel_immediately
boolean
default:"false"
If true, cancels the subscription immediately and revokes access. If false, cancels at the end of the current billing period (user retains access until then).

Response

subscription_id
string
Stripe subscription ID
status
string
New subscription status: canceled or active (will cancel at period end)
cancel_at
datetime
When the subscription will be canceled (if scheduled)
cancelled_at
datetime
When the cancellation was processed
message
string
Human-readable confirmation message

Example Request

Cancel Immediately

Example Response

Cancel at Period End

Immediate Cancellation

Cancellation Options

Best Practice: Default to cancel_immediately: false to give users time to reconsider or allow continued access until they’ve been billed for.

Integration Example

Handling Scheduled Cancellations

When a subscription is scheduled to cancel, update your UI accordingly:

Reactivating Canceled Subscriptions

To reactivate a subscription scheduled for cancellation, users should use the Customer Portal or start a new checkout.

Error Responses

StatusDescription
401Unauthorized - Invalid or missing authentication
404No active subscription to cancel
404Project not found or Stripe not configured

Get My Subscription

Check subscription status

Update Subscription

Change plans instead

Customer Portal

Let user manage cancellation

Authorizations

Authorization
string
header
required

Bearer authentication header of the form Bearer <token>, where <token> is your auth token.

Query Parameters

test_mode
boolean
default:true

Use test mode

Body

application/json

Request to cancel a subscription.

cancel_immediately
boolean
default:false

If true, cancels immediately. Otherwise cancels at period end.

Response

Successful Response

Cancel subscription response.

subscription_id
string
required
status
string
required
message
string
required
cancel_at
string<date-time> | null
cancelled_at
string<date-time> | null