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

# Billing

> Pay-as-you-go billing status, setup, and Stripe portal

# Billing

Gradient billing is pay as you go: you pay per completed assessment session,
billed monthly on the 1st for the period it was completed in (not when the
candidate was invited). Assessment sessions completed by candidates whose
email uses your company's domain or contains the word `test` are excluded.
For enterprise pricing and plans, contact
[hi@trygradient.ai](mailto:hi@trygradient.ai).

## Get Billing Status

```
GET /api/billing
```

<Info>Requires an admin session cookie.</Info>

Returns setup state, the current period's usage, and past invoices.

<Accordion title="Response">
  ```json theme={null}
  {
    "stripeEnabled": true,
    "configured": true,
    "hasCustomer": true,
    "paymentMethod": { "brand": "visa", "last4": "4242" },
    "billingEmail": "billing@acme.com",
    "period": { "start": "2026-07-01T00:00:00.000Z", "end": "2026-08-01T00:00:00.000Z" },
    "usage": { "billableCount": 4, "exemptCount": 2, "amountCents": 10000 },
    "pricePerAssessmentCents": 2500,
    "invoices": [
      {
        "id": "in_123",
        "number": "ACME-0001",
        "created": "2026-07-01T06:00:00.000Z",
        "amountDueCents": 7500,
        "status": "paid",
        "hostedInvoiceUrl": "https://invoice.stripe.com/i/..."
      }
    ]
  }
  ```
</Accordion>

## Start Billing Setup

```
POST /api/billing/setup
```

<Info>Requires an owner/admin session cookie.</Info>

Creates the organization's Stripe customer if needed and returns a hosted
Stripe Checkout (setup-mode) URL where the card is added. Card details never
touch Gradient servers.

<Accordion title="Response">
  ```json theme={null}
  { "url": "https://checkout.stripe.com/c/pay/cs_test_..." }
  ```
</Accordion>

## Open the Billing Portal

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

<Info>Requires an owner/admin session cookie.</Info>

Returns a Stripe Billing Portal URL for updating payment info and browsing
invoices on Stripe's hosted pages.

<Accordion title="Response">
  ```json theme={null}
  { "url": "https://billing.stripe.com/p/session/..." }
  ```
</Accordion>

## Update the Billing Email

```
PATCH /api/billing/email
```

<Info>Requires an owner/admin session cookie.</Info>

Updates the email Stripe sends invoices to. The change is pushed straight to
the Stripe customer (Stripe is the source of truth for it). Requires billing
to be set up (a Stripe customer must exist).

<Accordion title="Request">
  ```json theme={null}
  { "email": "billing@acme.com" }
  ```
</Accordion>

<Accordion title="Response">
  ```json theme={null}
  { "ok": true }
  ```
</Accordion>

## Stripe Webhook

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

Receiver for Stripe events (signature-verified with `STRIPE_WEBHOOK_SECRET`).
Billing state is also reconciled on-read and by the monthly invoicing cron, so
webhook delivery is an accelerator rather than a dependency.