Billing API Overview

Complete guide to managing subscriptions, usage, and billing with the CallCov API.

Billing Tiers

CallCov offers three tiers:

Tier	Price	Minutes	Analysis	Best For
Free	$0/month	500	Transcription only	Testing
Starter	$49/month	1,000	16-point compliance	Small teams
Growth	$199/month	5,000	Advanced AI analysis	Growing businesses

Quick Links

• Get Subscription - View current subscription
• Billing Summary - Usage and costs
• Available Tiers - Pricing information
• Create Checkout - Subscribe to paid tier
• Customer Portal - Manage billing
• Cancel Subscription - Cancel plan
• Reactivate - Undo cancellation
• Upgrade - Move to higher tier
• Downgrade - Move to lower tier
• Invoice History - View past invoices

---

Get Subscription

Get current subscription details including usage and limits.

Endpoint

GET /api/v1/billing/subscription

Authentication

JWT token or API key

Response

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "user_id": "660f9511-f3ac-52e5-b827-557766551111",
  "tier": "starter",
  "status": "active",
  "minutes_included": 1000,
  "minutes_used": 245.5,
  "minutes_remaining": 754.5,
  "overage_minutes": 0,
  "current_period_start": "2024-01-01T00:00:00Z",
  "current_period_end": "2024-02-01T00:00:00Z",
  "created_at": "2024-01-01T00:00:00Z",
  "tier_info": {
    "name": "Starter",
    "price_monthly": 49,
    "minutes_included": 1000,
    "overage_rate": 0.05,
    "features": ["16-Point Compliance Analysis", "Email Support"]
  }
}

---

Billing Summary

Get comprehensive billing summary with usage statistics.

Endpoint

GET /api/v1/billing/subscription/summary

Authentication

JWT token or API key

Response

{
  "subscription": { /* Same as Get Subscription */ },
  "usage": {
    "total_minutes_used": 245.5,
    "analysis_count": 82,
    "minutes_remaining": 754.5,
    "usage_percentage": 24.55
  },
  "estimated_overage_cost": 0.00
}

---

Get Tiers

Get information about all available billing tiers.

Endpoint

GET /api/v1/billing/tiers

Authentication

None required (public endpoint)

Response

{
  "tiers": [
    {
      "tier": "free",
      "name": "Free",
      "price_monthly": 0,
      "minutes_included": 500,
      "overage_allowed": false,
      "features": ["Transcription Only", "500 minutes/month"]
    },
    {
      "tier": "starter",
      "name": "Starter",
      "price_monthly": 49,
      "minutes_included": 1000,
      "overage_rate": 0.05,
      "overage_allowed": true,
      "features": ["16-Point Compliance Analysis", "1,000 minutes/month", "Email Support"]
    },
    {
      "tier": "growth",
      "name": "Growth",
      "price_monthly": 199,
      "minutes_included": 5000,
      "overage_rate": 0.04,
      "overage_allowed": true,
      "features": ["Advanced AI Analysis", "5,000 minutes/month", "Priority Support"]
    }
  ]
}

---

Create Checkout

Create Stripe Checkout session to subscribe to a paid tier.

Endpoint

POST /api/v1/billing/checkout

Authentication

JWT token only

Request Body

{
  "tier": "starter",
  "success_url": "https://your-app.com/success",
  "cancel_url": "https://your-app.com/cancel"
}

Response

{
  "checkout_url": "https://checkout.stripe.com/c/pay/...",
  "session_id": "cs_test_..."
}

Example

response = requests.post(
    "https://api.callcov.com/api/v1/billing/checkout",
    headers={"Authorization": f"Bearer {access_token}"},
    json={
        "tier": "starter",
        "success_url": "https://myapp.com/success",
        "cancel_url": "https://myapp.com/cancel"
    }
)

# Redirect user to checkout_url
checkout_url = response.json()['checkout_url']

---

Customer Portal

Create Stripe Customer Portal session for managing billing.

Endpoint

POST /api/v1/billing/portal

Authentication

JWT token only

Request Body

{
  "return_url": "https://your-app.com/settings"
}

Response

{
  "portal_url": "https://billing.stripe.com/p/session/..."
}

What Users Can Do in Portal

• Update payment method
• View billing history
• Download invoices
• Cancel subscription
• Update subscription

---

Cancel Subscription

Cancel the current paid subscription.

Endpoint

POST /api/v1/billing/subscription/cancel

Authentication

JWT token only

Query Parameters

Parameter	Type	Default	Description
at_period_end	boolean	true	Cancel at period end (true) or immediately (false)

Response

{
  "message": "Subscription will be canceled at the end of the current billing period",
  "subscription_id": "550e8400-e29b-41d4-a716-446655440000"
}

Example

# Cancel at period end (default)
response = requests.post(
    "https://api.callcov.com/api/v1/billing/subscription/cancel",
    headers={"Authorization": f"Bearer {access_token}"}
)

# Cancel immediately
response = requests.post(
    "https://api.callcov.com/api/v1/billing/subscription/cancel?at_period_end=false",
    headers={"Authorization": f"Bearer {access_token}"}
)

---

Reactivate Subscription

Reactivate a subscription scheduled for cancellation.

Endpoint

POST /api/v1/billing/subscription/reactivate

Authentication

JWT token only

Response

{
  "message": "Subscription reactivated successfully",
  "subscription_id": "550e8400-e29b-41d4-a716-446655440000"
}

Only Works for Scheduled Cancellations

This only works if the subscription is scheduled to cancel at period end. Cannot reactivate an already-canceled subscription.

---

Upgrade Subscription

Upgrade to a higher tier.

Endpoint

POST /api/v1/billing/subscription/upgrade

Authentication

JWT token only

Request Body

{
  "tier": "growth"
}

Response

Returns updated subscription (same format as Get Subscription).

Upgrade Paths

• Free → Starter ✅
• Free → Growth ✅
• Starter → Growth ✅

How Upgrades Work

1. Immediate effect: Usage limits updated immediately
2. Pro-rated billing: Charged pro-rated amount for remainder of period
3. Minutes rollover: Unused minutes from old tier are lost
4. New billing cycle: Next charge will be for full new tier price

Example

response = requests.post(
    "https://api.callcov.com/api/v1/billing/subscription/upgrade",
    headers={"Authorization": f"Bearer {access_token}"},
    json={"tier": "growth"}
)

subscription = response.json()
print(f"Upgraded to {subscription['tier']}")
print(f"New limit: {subscription['minutes_included']} minutes")

---

Downgrade Subscription

Downgrade to a lower tier (scheduled for end of period).

Endpoint

POST /api/v1/billing/subscription/downgrade

Authentication

JWT token only

Request Body

{
  "tier": "starter"
}

Response

{
  "message": "Subscription will be downgraded to starter tier at the end of the current billing period",
  "current_period_end": "2024-02-01T00:00:00Z",
  "subscription_id": "550e8400-e29b-41d4-a716-446655440000"
}

Downgrade Paths

• Growth → Starter ✅
• Growth → Free ✅
• Starter → Free ✅

How Downgrades Work

1. End of period: Takes effect at end of current billing cycle
2. No refunds: Continue using current tier until period end
3. New limits apply: Lower limits start at next billing cycle
4. Downgrade to Free: Cancels Stripe subscription

---

Get Invoices

Get billing invoice history from Stripe.

Endpoint

GET /api/v1/billing/invoices

Authentication

JWT token only

Query Parameters

Parameter	Type	Default	Description
limit	integer	12	Number of invoices to return

Response

{
  "invoices": [
    {
      "id": "in_1234567890",
      "invoice_number": "ABC-1234",
      "status": "paid",
      "amount_due": 49.00,
      "amount_paid": 49.00,
      "total": 49.00,
      "currency": "USD",
      "created": 1704067200,
      "period_start": 1704067200,
      "period_end": 1706745600,
      "invoice_pdf": "https://pay.stripe.com/invoice/.../pdf",
      "hosted_invoice_url": "https://invoice.stripe.com/i/...",
      "description": "Monthly subscription",
      "lines": [
        {
          "description": "Starter Plan × 1",
          "amount": 49.00,
          "quantity": 1,
          "period_start": 1704067200,
          "period_end": 1706745600
        }
      ]
    }
  ],
  "has_more": false
}

---

Common Workflows

First-Time Subscription

# 1. Get available tiers
tiers = requests.get("https://api.callcov.com/api/v1/billing/tiers").json()

# 2. Create checkout session
checkout = requests.post(
    "https://api.callcov.com/api/v1/billing/checkout",
    headers={"Authorization": f"Bearer {access_token}"},
    json={
        "tier": "starter",
        "success_url": "https://myapp.com/success",
        "cancel_url": "https://myapp.com/cancel"
    }
).json()

# 3. Redirect user to checkout_url
redirect_to(checkout['checkout_url'])

# 4. After successful payment, user is redirected to success_url
# 5. Check subscription status
subscription = requests.get(
    "https://api.callcov.com/api/v1/billing/subscription",
    headers={"Authorization": f"Bearer {access_token}"}
).json()

Monitor Usage

# Get billing summary
summary = requests.get(
    "https://api.callcov.com/api/v1/billing/subscription/summary",
    headers={"Authorization": f"Bearer {access_token}"}
).json()

usage_pct = summary['usage']['usage_percentage']
remaining = summary['usage']['minutes_remaining']

if usage_pct > 80:
    print(f"⚠️  Warning: {usage_pct}% of minutes used")
    print(f"Remaining: {remaining} minutes")

Change Subscription

# Upgrade immediately
requests.post(
    "https://api.callcov.com/api/v1/billing/subscription/upgrade",
    headers={"Authorization": f"Bearer {access_token}"},
    json={"tier": "growth"}
)

# Downgrade at period end
requests.post(
    "https://api.callcov.com/api/v1/billing/subscription/downgrade",
    headers={"Authorization": f"Bearer {access_token}"},
    json={"tier": "starter"}
)

---

Error Codes

Status	Error	Solution
400	Cannot create checkout for free tier	Use upgrade endpoint instead
400	Already have active subscription	Use upgrade/downgrade endpoints
400	Cannot upgrade to same/lower tier	Check current tier first
400	No Stripe customer found	Subscribe to paid plan first
402	Usage limit exceeded	Upgrade plan or wait for next billing cycle
500	Stripe operation failed	Retry or contact support

---

Related

• Create Analysis - Submit audio for analysis (consumes minutes)
• API Keys - Create API keys for programmatic access
• Quickstart Guide - Complete setup guide