Create Subscription

Create a new Stripe subscription for email validation credits

POST /v1/subscriptions/create

cURL

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"
  }'

Response

{
  "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.js

Example: 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

Response

{
  "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

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., [e-mail])
• 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 ([e-mail]) → 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"
}

Related Endpoints

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