> ## Documentation Index
> Fetch the complete documentation index at: https://docs.hookstream.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Billing

Check usage, create checkout sessions, manage subscriptions, and view invoices.

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:

| Plan | Events/mo | Sources | Destinations | Retention |
| --- | --- | --- | --- | --- |
| **Free** | 50,000 | 10 | 5 | 7 days |
| **Pro** | 1,000,000 | unlimited | unlimited | 30 days |
| **Enterprise** | 10,000,000 | unlimited | unlimited | 90 days |

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
curl https://hookstream.io/v1/billing/usage \
  -H "X-API-Key: $HOOKSTREAM_API_KEY"
```

```json 200 OK
{
  "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

Plan to subscribe to: `pro` or `enterprise`.

Billing interval: `monthly` or `annual`.

Stripe coupon ID to apply.

```bash cURL
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 200 OK
{
  "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
curl -X POST https://hookstream.io/v1/billing/portal \
  -H "X-API-Key: $HOOKSTREAM_API_KEY"
```

```json 200 OK
{
  "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 200 OK
{
  "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 200 OK
{
  "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"
    }
  ]
}
```