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

# Billing

> API endpoints for subscription management and Stripe integration

## Create Checkout Session

Initiates a Stripe Checkout session for plan selection. Returns a URL to redirect the user to Stripe.

```
POST /api/billing/checkout-session
```

### Request Body

```json theme={null}
{
  "plan": "pro",
  "cycle": "monthly"
}
```

| Field   | Type   | Description                     |
| ------- | ------ | ------------------------------- |
| `plan`  | string | `basic`, `pro`, or `enterprise` |
| `cycle` | string | `monthly` or `annual`           |

### Response

```json theme={null}
{
  "url": "https://checkout.stripe.com/..."
}
```

Redirect the user to `url` to complete payment.

***

## Open Billing Portal

Returns a Stripe Customer Portal URL where the user can manage their subscription, update payment methods, and download invoices.

```
POST /api/billing/portal
```

### Response

```json theme={null}
{
  "url": "https://billing.stripe.com/..."
}
```

***

## Stripe Webhook

Receives Stripe webhook events. This endpoint must be configured as the webhook destination in the Stripe dashboard.

```
POST /api/billing/webhook
```

<Note>
  This endpoint verifies the `Stripe-Signature` header against your `STRIPE_WEBHOOK_SECRET`. Do not call this endpoint directly — it is for Stripe's servers only.
</Note>

### Handled Events

| Event                           | Action                                  |
| ------------------------------- | --------------------------------------- |
| `checkout.session.completed`    | Activates the subscription              |
| `invoice.payment_succeeded`     | Renews the subscription period          |
| `invoice.payment_failed`        | Triggers a payment failure notification |
| `customer.subscription.deleted` | Marks the subscription as canceled      |