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

# Billing API overview

> Endpoints to read subscription state, open Stripe sessions, and pull credit-ledger usage.

All billing routes live under `/v1/billing/`. They are organization-scoped and require an API key with `billing:read` or `billing:write`.

| Endpoint                       | Method | Scope         | Purpose                                                                |
| ------------------------------ | ------ | ------------- | ---------------------------------------------------------------------- |
| `/v1/billing/plans`            | GET    | public        | List public plan catalog                                               |
| `/v1/billing/subscription`     | GET    | billing:read  | Current org subscription + credit balance                              |
| `/v1/billing/checkout-session` | POST   | billing:write | Open Stripe Checkout for the requested plan (used when org is on Free) |
| `/v1/billing/portal-session`   | POST   | billing:write | Open Stripe Customer Portal (optionally pre-targeted)                  |
| `/v1/billing/usage`            | GET    | billing:read  | Paginated credit-ledger entries; supports `?format=csv`                |

## Webhook

Stripe events POST to `/v1/internal/stripe-webhook`. The handler verifies the signature against `STRIPE_WEBHOOK_SECRET`, deduplicates via the `stripe_event` table, and processes:

* `customer.subscription.created`, `customer.subscription.updated`, `customer.subscription.deleted`
* `invoice.paid`, `invoice.payment_failed`

## Credit formula

`credits = ceil(conversation_seconds × BILLING_CREDITS_PER_SECOND)` (default coefficient `10`). The agent runtime may suggest a `cost_credits` value on `recordMetrics`, but the API clamps and recomputes.