Billing

The Billing API lets you check your plan's usage, create Stripe Checkout sessions to upgrade, open the Stripe Customer Portal to manage your subscription, view current subscription details, and list invoices. All billing endpoints require authentication.

Plan limits

Each plan includes specific resource limits:

Paid plans have a soft limit — events are accepted up to 120% of the monthly quota before returning 429. The Free plan has a hard cutoff at 100%.

Get Usage

GET /v1/billing/usage

Get current usage vs plan limits for the authenticated organization.

Authentication: API key or session cookie.

bash
curl https://hookstream.io/v1/billing/usage \
  -H "X-API-Key: $HOOKSTREAM_API_KEY"

json
{
  "plan": "pro",
  "events": { "used": 42531, "limit": 1000000, "percentage": 4 },
  "sources": { "used": 3, "limit": null },
  "destinations": { "used": 2, "limit": null },
  "retention_days": 30
}

Create Checkout Session

POST /v1/billing/checkout

Create a Stripe Checkout session. Returns a URL to redirect the user to.

Authentication: API key or session cookie.

Body Parameters

bash
curl -X POST https://hookstream.io/v1/billing/checkout \
  -H "X-API-Key: $HOOKSTREAM_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"plan": "pro", "interval": "annual"}'

json
{
  "checkout_url": "https://checkout.stripe.com/c/pay/..."
}

Open Customer Portal

POST /v1/billing/portal

Create a Stripe Customer Portal session for subscription management. Redirect the user to portal_url to update payment methods, cancel, or view invoices.

Authentication: API key or session cookie.

bash
curl -X POST https://hookstream.io/v1/billing/portal \
  -H "X-API-Key: $HOOKSTREAM_API_KEY"

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

Get Subscription

GET /v1/billing/subscription

Get current subscription details.

Authentication: API key or session cookie.

json
{
  "subscription": {
    "id": "sub_abc123",
    "plan": "pro",
    "status": "active",
    "current_period_start": "2026-03-01T00:00:00Z",
    "current_period_end": "2026-04-01T00:00:00Z",
    "cancel_at_period_end": 0
  }
}

List Invoices

GET /v1/billing/invoices

List recent invoices from Stripe (up to 12). Invoices are fetched from the Stripe API on demand rather than cached in D1, so there's no sync lag.

Authentication: API key or session cookie.

json
{
  "invoices": [
    {
      "id": "in_abc123",
      "number": "INV-0001",
      "status": "paid",
      "amount_due": 1900,
      "amount_paid": 1900,
      "currency": "usd",
      "period_start": "2026-03-01T00:00:00Z",
      "period_end": "2026-04-01T00:00:00Z",
      "hosted_invoice_url": "https://invoice.stripe.com/i/...",
      "created": "2026-03-01T00:00:00Z"
    }
  ]
}