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.

Get Billing Status

GET /api/billing

Requires an admin session cookie.

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

Response

{
  "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/..."
    }
  ]
}

Start Billing Setup

POST /api/billing/setup

Requires an owner/admin session cookie.

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.

Response

{ "url": "https://checkout.stripe.com/c/pay/cs_test_..." }

Open the Billing Portal

POST /api/billing/portal

Requires an owner/admin session cookie.

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

Response

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

Update the Billing Email

PATCH /api/billing/email

Requires an owner/admin session cookie.

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).

Request

{ "email": "billing@acme.com" }

Response

{ "ok": true }

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.

​Billing

​Get Billing Status

​Start Billing Setup

​Open the Billing Portal

​Update the Billing Email

​Stripe Webhook

Billing

Get Billing Status

Start Billing Setup

Open the Billing Portal

Update the Billing Email

Stripe Webhook