Skip to main content
POST
/
api
/
v1
/
payments
/
stripe
/
cancel-subscription
Cancel Subscription
curl --request POST \
  --url https://api.devkit4ai.com/api/v1/payments/stripe/cancel-subscription \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "cancel_immediately": false
}
'
{
  "subscription_id": "<string>",
  "status": "<string>",
  "message": "<string>",
  "cancel_at": "2023-11-07T05:31:56Z",
  "cancelled_at": "2023-11-07T05:31:56Z"
}
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

curl -X POST "https://api.devkit4ai.com/api/v1/payments/stripe/cancel-subscription?test_mode=true" \
  -H "Authorization: Bearer {end_user_jwt}" \
  -H "Content-Type: application/json" \
  -d '{
    "cancel_immediately": false
  }'

​
Cancel Immediately

curl -X POST "https://api.devkit4ai.com/api/v1/payments/stripe/cancel-subscription?test_mode=true" \
  -H "Authorization: Bearer {end_user_jwt}" \
  -H "Content-Type: application/json" \
  -d '{
    "cancel_immediately": true
  }'

​
Example Response

​
Cancel at Period End

{
  "subscription_id": "sub_1ABC123def456",
  "status": "active",
  "cancel_at": "2026-02-01T00:00:00Z",
  "cancelled_at": "2026-01-24T15:30:00Z",
  "message": "Subscription will be canceled at the end of the current billing period."
}

​
Immediate Cancellation

{
  "subscription_id": "sub_1ABC123def456",
  "status": "canceled",
  "cancel_at": null,
  "cancelled_at": "2026-01-24T15:30:00Z",
  "message": "Subscription has been canceled immediately."
}

​
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

// Cancel subscription with confirmation
async function cancelSubscription(immediately: boolean = false) {
  const confirmed = await showConfirmDialog(
    immediately 
      ? 'Cancel immediately? You will lose access now.'
      : 'Cancel at period end? You will retain access until your next billing date.'
  );
  
  if (!confirmed) return;
  
  const response = await fetch('/api/cancel-subscription', {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify({ cancel_immediately: immediately })
  });
  
  const result = await response.json();
  showToast(result.message);
  refreshSubscriptionStatus();
}

​
Handling Scheduled Cancellations

When a subscription is scheduled to cancel, update your UI accordingly: 
function SubscriptionStatus({ subscription }) {
  if (subscription.cancel_at) {
    return (
      <div className="warning">
        <p>Your subscription will end on {formatDate(subscription.cancel_at)}</p>
        <button onClick={reactivateSubscription}>Keep Subscription</button>
      </div>
    );
  }
  
  return <p>Active until {formatDate(subscription.current_period_end)}</p>;
}

​
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