Skip to main content
POST
https://api.gtmapis.com
/
v1
/
subscriptions
/
cancel
curl -X POST https://api.gtmapis.com/v1/subscriptions/cancel \
  -H "X-API-Key: gtm_test_your_key_here"

{
  "subscription_id": "sub_1ABC123def456GHI",
  "status": "active",
  "cancel_at_period_end": true,
  "current_period_end": "2026-02-07T00:00:00Z",
  "message": "Subscription will cancel on 2026-02-07"
}

​
Authentication

​
X-API-Key
string
required
Your API key (format: gtm_test_... or gtm_live_...)

​
Behavior

  • Immediate Effect: Sets cancel_at_period_end=true immediately
  • Service Continuity: You can still validate emails until period ends
  • Credit Access: Full credit balance remains available until period end
  • Billing: No future charges after current period

​
Response

​
subscription_id
string
Stripe subscription ID
​
status
string
Subscription status (still active until period ends)
​
cancel_at_period_end
boolean
Set to true after successful cancellation
​
current_period_end
string
When the subscription will actually end (ISO 8601 timestamp)
{
  "subscription_id": "sub_1ABC123def456GHI",
  "status": "active",
  "cancel_at_period_end": true,
  "current_period_end": "2026-02-07T00:00:00Z",
  "message": "Subscription will cancel on 2026-02-07"
}

curl -X POST https://api.gtmapis.com/v1/subscriptions/cancel \
  -H "X-API-Key: gtm_test_your_key_here"

​
What Happens After Cancellation

​
Immediate (after API call)

  • ✅ cancel_at_period_end flag set to true
  • ✅ Stripe webhook customer.subscription.updated triggered
  • ✅ You receive confirmation message

​
Until Period End (e.g., Jan 7 - Feb 7)

  • ✅ Subscription remains active
  • ✅ All credits still available
  • ✅ Email validation works normally
  • ✅ No additional charges

​
At Period End (e.g., Feb 7 00:00 UTC)

  • ❌ Subscription status changes to canceled
  • ❌ Credits set to 0
  • ❌ Email validation blocked (402 Payment Required)
  • ❌ No future billing

​
Changed Your Mind?

You can reactivate before the period ends: 
// Reactivate before cancellation takes effect
await fetch('https://api.gtmapis.com/v1/subscriptions/reactivate', {
  method: 'POST',
  headers: { 'X-API-Key': apiKey }
});
See Reactivate Subscription for details.

​
Error Responses

​
404 Not Found

No active subscription to cancel: 
{
  "error": "Not Found",
  "message": "No active subscription found"
}

​
409 Conflict

Subscription already set to cancel: 
{
  "error": "Conflict",
  "message": "Subscription is already set to cancel at period end"
}

​
Best Practices

​
Before Canceling

  1. Download Validation History: Export your validation results
  2. Check Credits Remaining: Use up remaining credits before period ends
  3. Note Period End Date: Plan accordingly if you need to reactivate

​
For Temporary Pauses

If you just need a break, consider:
  • Using up remaining credits
  • Canceling a few days before period end
  • Reactivating when needed (instant credit restoration)

Reactivate Subscription

Undo cancellation before period ends

Get Current Subscription

Check cancellation status