Skip to main content
POST
https://api.gtmapis.com
/
v1
/
subscriptions
/
create
curl -X POST https://api.gtmapis.com/v1/subscriptions/create \
  -H "Content-Type: application/json" \
  -H "X-API-Key: gtm_test_your_key_here" \
  -d '{
    "price_id": "price_1SlRyVHb8IrVorYVk6Hn17s7",
    "payment_method_id": "pm_card_visa"
  }'

{
  "subscription_id": "sub_1ABC123def456GHI",
  "status": "active",
  "included_credits": 20000,
  "current_period_start": "2026-01-07T00:00:00Z",
  "current_period_end": "2026-02-07T00:00:00Z",
  "cancel_at_period_end": false,
  "customer_id": "cus_ABC123def456"
}

​
Authentication

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

​
Request Body

​
price_id
string
required
Stripe price ID for the plan (Starter or Agency)
  • Starter Plan: 20,000 credits/month
  • Agency Plan: 50,000 credits/month
​
payment_method_id
string
required
Stripe payment method ID from client-side Stripe.jsExample: pm_card_visa (test mode) or pm_1ABC... (live mode)
​
customer_id
string
Optional existing Stripe customer ID. If not provided, a new customer will be created.

​
Response

​
subscription_id
string
Stripe subscription ID (format: sub_...)
​
status
string
Subscription status: active, trialing, past_due, canceled
​
included_credits
integer
Number of credits included in the plan (20,000 or 50,000)
​
current_period_start
string
ISO 8601 timestamp of current billing period start
​
current_period_end
string
ISO 8601 timestamp of current billing period end
​
cancel_at_period_end
boolean
Whether the subscription will cancel at the end of the current period
{
  "subscription_id": "sub_1ABC123def456GHI",
  "status": "active",
  "included_credits": 20000,
  "current_period_start": "2026-01-07T00:00:00Z",
  "current_period_end": "2026-02-07T00:00:00Z",
  "cancel_at_period_end": false,
  "customer_id": "cus_ABC123def456"
}

curl -X POST https://api.gtmapis.com/v1/subscriptions/create \
  -H "Content-Type: application/json" \
  -H "X-API-Key: gtm_test_your_key_here" \
  -d '{
    "price_id": "price_1SlRyVHb8IrVorYVk6Hn17s7",
    "payment_method_id": "pm_card_visa"
  }'

​
How It Works

  1. Customer Creation: If customer_id is not provided, a new Stripe customer is created using the user’s email from the API key.
  2. Payment Method Attachment: The provided payment_method_id is attached to the customer.
  3. Subscription Creation: A new Stripe subscription is created with the specified price_id.
  4. Credit Allocation: Credits are allocated to the user’s account based on the plan:
    • Starter: 20,000 credits
    • Agency: 50,000 credits
  5. Usage Tracking: As emails are validated, credits are consumed and usage is reported to Stripe for metered billing.

​
Credit Charging Logic

Only high-value emails are charged (our B2B outbound differentiator): ✅ Charged (1 credit):
  • Valid personal email (e.g., john@company.com)
  • b2b_outbound_quality: high
  • Not role-based, not catch-all, not invalid
🆓 FREE (0 credits):
  • Role-based emails (info@, support@) → Low B2B value
  • Catch-all domains → Unverifiable mailboxes
  • Invalid emails → Don’t exist
  • Admin users (matt@closedwonleads.com) → Unlimited credits
This means 1 credit = 20 HIGH-VALUE validations, not just any email verification.

​
Plans

​
Starter Plan

  • Price: $99/month
  • Credits: 20,000 high-value validations/month
  • Best for: Teams sending 50k-200k emails/month
  • Price ID: price_1SlRyVHb8IrVorYVk6Hn17s7 (test mode)

​
Agency Plan

  • Price: $199/month
  • Credits: 50,000 high-value validations/month
  • Best for: Agencies sending 200k-1M+ emails/month
  • Price ID: Contact support for Agency plan ID

​
Error Responses

​
400 Bad Request

Missing required fields or invalid input: 
{
  "error": "Bad Request",
  "message": "price_id is required"
}

​
402 Payment Required

Payment method declined or insufficient funds: 
{
  "error": "Payment Required",
  "message": "Your card was declined"
}

​
409 Conflict

User already has an active subscription: 
{
  "error": "Conflict",
  "message": "User already has an active subscription"
}

Get Current Subscription

Check subscription status and credit balance

Cancel Subscription

Cancel subscription at period end

​
Notes

  • Test Mode: Use Stripe test cards for testing (e.g., 4242 4242 4242 4242)
  • Webhook Events: Subscription creation triggers customer.subscription.created webhook
  • Credits Rollover: Credits do NOT roll over - they reset each billing period
  • Prorated Upgrades: Upgrading mid-period is prorated automatically by Stripe