Get Current Subscription

Retrieve the current user subscription status and credit balance

GET /v1/subscriptions/current

cURL

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

Active Subscription

{
  "subscription_id": "sub_1ABC123def456GHI",
  "status": "active",
  "plan_name": "starter",
  "included_credits": 20000,
  "credits_used": 1250,
  "credits_remaining": 18750,
  "current_period_start": "2026-01-07T00:00:00Z",
  "current_period_end": "2026-02-07T00:00:00Z",
  "cancel_at_period_end": false
}

Authentication

X-API-Key · string · required

Your API key (format: gtm_test_... or gtm_live_...)

Response

subscription_id · string

Stripe subscription ID (format: sub_...)

status · string

Current subscription status:

• active: Subscription is active and credits available
• trialing: In trial period
• past_due: Payment failed, retrying
• canceled: Subscription canceled
• incomplete: Awaiting payment confirmation

plan_name · string

Plan name: starter or agency

included_credits · integer

Total credits included in current billing period (20,000 or 50,000)

credits_used · integer

Number of credits consumed in current period

credits_remaining · integer

Remaining credits for current period (calculated: included_credits - credits_used)

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 is set to cancel at the end of the current period

Active Subscription

{
  "subscription_id": "sub_1ABC123def456GHI",
  "status": "active",
  "plan_name": "starter",
  "included_credits": 20000,
  "credits_used": 1250,
  "credits_remaining": 18750,
  "current_period_start": "2026-01-07T00:00:00Z",
  "current_period_end": "2026-02-07T00:00:00Z",
  "cancel_at_period_end": false
}

cURL

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

Usage Notes

Credit Tracking

Credits are tracked per billing period:

• Reset: Credits reset to full amount at period start (e.g., Jan 7 → Feb 7)
• No Rollover: Unused credits do NOT carry over to next period
• Real-time Deduction: Credits deducted immediately after validation

Checking Before Validation

Before running large bulk validations, check your remaining credits:

// Check credits before validation
const subscription = await fetch('/v1/subscriptions/current', {
  headers: { 'X-API-Key': apiKey }
}).then(r => r.json());

if (subscription.credits_remaining < emailList.length) {
  console.warn(`Insufficient credits: ${subscription.credits_remaining} remaining`);
  // Upgrade plan or wait for period reset
}

Status Interpretations

Status	Meaning	Can Validate?
active	All good, credits available	✅ Yes
trialing	Free trial period	✅ Yes
past_due	Payment retry in progress	✅ Yes (grace period)
canceled	Subscription ended	❌ No
incomplete	Awaiting payment confirmation	❌ No

Error Responses

404 Not Found

User has no subscription:

{
  "error": "Not Found",
  "message": "No active subscription found for this user"
}

401 Unauthorized

Invalid or missing API key:

{
  "error": "Unauthorized",
  "message": "Invalid API key"
}

Related Endpoints

Create Subscription

Start a new subscription plan

Cancel Subscription

Cancel at end of current period