Billing API

Overview

The Billing API allows you to manage your subscription, view invoices, and update payment methods programmatically. All billing is handled securely through Stripe.

Plans & Pricing

Plan	Price	API Requests/Month	Features
Free	$0	100 (lifetime)	Basic prices
Hobby	$9/mo	10,000	All commodities
Starter	$29/mo	50,000	+ Webhooks
Professional	$79/mo	100,000	+ SMS Alerts
Business	$199/mo	200,000	+ Team seats
Enterprise	Custom	500,000+	Custom SLA

Endpoints

Get Available Plans

GET /billing/plans

Response:

{
  "plans": [
    {
      "id": "hobby",
      "name": "Hobby",
      "price_monthly": 900,
      "price_yearly": 9000,
      "currency": "usd",
      "request_limit": 10000,
      "features": ["all_commodities", "historical_data"]
    }
  ]
}

Get Current Subscription

GET /billing/subscriptions/current

Response:

{
  "subscription": {
    "id": "sub_123",
    "plan": "professional",
    "status": "active",
    "current_period_start": "2025-01-01T00:00:00Z",
    "current_period_end": "2025-02-01T00:00:00Z",
    "cancel_at_period_end": false,
    "usage": {
      "requests_used": 45000,
      "requests_limit": 100000,
      "percent_used": 45
    }
  }
}

Create Subscription

POST /billing/subscriptions

Request Body:

{
  "plan_id": "professional",
  "billing_period": "monthly"
}

Change Plan

POST /billing/subscriptions/change_plan

Request Body:

{
  "new_plan_id": "business"
}

Plan changes are prorated. Upgrades take effect immediately; downgrades take effect at the next billing period.

Cancel Subscription

POST /billing/subscriptions/cancel

Cancels at end of current billing period. You retain access until then.

Reactivate Subscription

POST /billing/subscriptions/reactivate

Reactivates a subscription scheduled for cancellation.

Payment Methods

List Payment Methods

GET /billing/payment_methods

Update Payment Method

PATCH /billing/payment_methods/update

Request Body:

{
  "payment_method_id": "pm_card_visa_123"
}

Create Setup Intent

POST /billing/intents/setup

Returns a Stripe Setup Intent for adding a new payment method.

Invoices

List Invoices

GET /billing/invoices

Response:

{
  "invoices": [
    {
      "id": "inv_123",
      "amount": 7900,
      "currency": "usd",
      "status": "paid",
      "period_start": "2025-01-01",
      "period_end": "2025-01-31",
      "pdf_url": "https://invoice.stripe.com/..."
    }
  ]
}

Usage Tracking

Get Current Usage

GET /billing/usage

Response:

{
  "period": {
    "start": "2025-01-01T00:00:00Z",
    "end": "2025-02-01T00:00:00Z"
  },
  "requests": {
    "used": 45000,
    "limit": 100000,
    "remaining": 55000
  },
  "daily_breakdown": [
    {"date": "2025-01-15", "requests": 1500},
    {"date": "2025-01-16", "requests": 1800}
  ]
}

Customer Portal

For self-service billing management, redirect users to Stripe's Customer Portal:

POST /billing/customer-portal/sessions

Response:

{
  "url": "https://billing.stripe.com/session/..."
}

Redirect users to this URL for:

Update payment method
View invoice history
Download invoices
Cancel subscription

Credit Packs (Pay-as-you-go)

For users who exceed their monthly limits:

List Available Credit Packs

GET /billing/credit_packs

Purchase Credits

POST /billing/credit_purchases

Request Body:

{
  "pack_id": "10k_requests",
  "quantity": 1
}

Webhook Events

Subscribe to billing webhooks for real-time updates:

Event	Description
`subscription.created`	New subscription started
`subscription.updated`	Plan changed
`subscription.cancelled`	Subscription cancelled
`invoice.paid`	Payment successful
`invoice.payment_failed`	Payment failed
`usage.limit_warning`	80% of limit reached
`usage.limit_exceeded`	100% of limit reached

Questions?

Contact [email protected] for billing questions or custom Enterprise pricing.