API Reference

Billing and subscription routes

Use this reference to integrate supported billing flows: subscription state and subscription mutations, upgrade preview and checkout, overage checkout, billing portal access, invoice listing, and the signed public disable link confirmation flow for auto overage.

Machine-readable coverage for customer billing routes lives in /docs/account. This page is intentionally broader because it also explains the signed public disable-link flow, which is part of the user experience but intentionally excluded from the supported public OpenAPI surface.

Auth model

Account billing routes

Authorization: Bearer ACCESS_TOKEN

Subscription, checkout, overage, portal, and invoice endpoints are account-scoped and require bearer auth.

Public disable route

Signed token in query/body

The public disable flow does not use bearer auth. Trust is based on a signed token delivered in the link.

Subscription controls

Read state first, then change cancellation and auto overage settings from account routes.

Checkout split

Use /user/checkout for plan changes and /user/overage for one-time overage blocks.

Public disable safety

GET renders a safe confirmation page. State change is attempted only on POST with the signed token.

Review auth models Open account OpenAPI Open usage reference

Subscription state

Read the account's current subscription and auto-overage settings

Use this route to render account billing state and drive UI decisions for cancellation status, scheduled plan changes, and auto-overage controls.

GET/user/subscription

Request

Auth

bearer required

Returns billing state for the signed in account.

Response

status

string

Subscription lifecycle state such as none, active, or another billing status returned by this API.

plan

optional string

Current plan when a paid subscription exists.

currentPeriodEnd

optional ISO 8601 datetime

Current cycle end when available.

cancelAtPeriodEnd

optional boolean

Whether cancellation is already scheduled.

scheduledPlan

optional string

Target plan for a period-end downgrade when one is scheduled.

scheduledPlanEffectiveDate

optional ISO 8601 datetime

When scheduled plan change takes effect.

autoOverageEnabled

optional boolean

Whether automatic top-ups are enabled.

autoOverageBlockSize

optional number or null

Configured top-up size when enabled.

autoOverageCycleCapCents

optional number or null

Billing-cycle cap for automatic top-up spend.

200 OK401 Unauthorized

Subscription actions

Mutate cancellation and auto-overage behavior on the active subscription

These routes apply billing changes at the account level without launching checkout. Use them for cancel and resume controls and to configure automatic overage top-ups.

Route contracts

POST /user/subscription/cancel

bearer required, no body

Schedules cancellation at period end and returns updated subscription state.

POST /user/subscription/resume

bearer required, no body

Clears a scheduled cancellation when the current subscription can be resumed.

POST /user/subscription/auto-overage

bearer required, JSON body

Updates auto-overage policy with enabled and optional blockSize (1000, 5000, 10000) plus optional spendCapCents (100-10,000,000).

200 OK400 Bad Request401 Unauthorized429 Too Many Requests

Upgrade preview

Preview proration before creating an upgrade checkout session

Call this route when users choose a higher plan and you need a proration preview before starting checkout.

GET/user/subscription/upgrade-preview

Request

Use this route only for paid-plan upgrades. Downgrades are handled through checkout scheduling.

Auth

bearer required

Account-scoped billing preview.

plan

required query enum

Target plan: free, starter, professional, or business.

Response

This route is preview-only and never creates checkout sessions.

eligible

boolean

Whether preview data is available from current state.

currentPlan, targetPlan

optional string

Present when eligible is true and preview can be computed.

amountDueCents

optional number

Immediate prorated amount due in cents when eligible.

currency

optional string

Currency code used for preview totals.

periodStart, periodEnd

optional ISO 8601 datetime

Billing period used for proration math.

200 OK400 Bad Request401 Unauthorized

Checkout

Create plan checkout for new subscriptions and upgrades

Use this route to start a hosted checkout session for new paid subscriptions and upgrades. Downgrades are scheduled and may not include a checkout URL.

POST/user/checkout

Request

Auth

bearer required

Creates checkout in current account context.

plan

required body enum

starter, professional, or business.

Response

url

string

Checkout URL. May be empty when a downgrade is scheduled instead.

scheduledPlan, scheduledPlanEffectiveDate

optional

Present when downgrade is scheduled for period end.

200 OK400 Bad Request401 Unauthorized429 Too Many Requests

Overage

Create one-time checkout for overage block purchases

Use the overage route for one-time top-ups that increase available volume outside recurring plan checkout.

POST/user/overage

Request

Auth

bearer required

Account-scoped purchase flow.

blockSize

required body enum

One of 1000, 5000, or 10000 PDFs.

Response

url

string

Hosted checkout URL to complete payment.

200 OK400 Bad Request401 Unauthorized429 Too Many Requests

Billing portal

Generate a hosted billing portal URL for self-service billing tasks

Use this route when users need card updates or invoice access in the billing portal your API provisions for the current account.

GET/user/billing-portal

Request

Auth

bearer required

Account-level portal session request.

Response

url

string

Hosted portal URL for the current customer record.

200 OK400 Bad Request401 Unauthorized429 Too Many Requests

Invoices

List invoice and receipt records for the account

Use filters and sort fields for statement pages, reconciliation tools, and finance exports.

GET/user/invoices

Request

Auth

bearer required

Lists invoice records for the signed in account.

limit, offset

optional pagination

Window controls: limit 1-100, offset 0+.

status

optional enum

all, draft, open, paid, void.

optional string

Find by invoice number/title text.

from, to

optional date strings

Date range filter. from must be before to.

sort

optional enum

Sort by created date, amount paid, number, or status.

Response

invoices[]

array<object>

Each row includes amount, status, created date, and hosted invoice/receipt URL.

invoices[].pdfUrl

optional string

Present when a downloadable PDF version of the invoice or receipt is available.

total, limit, offset

number

Pagination metadata for current query window.

statusOptions

string[]

Allowed status filters for this API.

200 OK400 Bad Request401 Unauthorized

Stripe webhook

Accept signed Stripe billing events

This endpoint is called by Stripe, not by an authenticated customer. Send the unmodified JSON request body with Stripe's stripe-signature header so the API can verify the event before processing it.

POST/webhooks/stripe

Request

Auth

Stripe signature required

Do not send bearer auth. The API verifies the stripe-signature header with the configured webhook secret.

Content-Type

application/json

The raw request bytes must reach the API unchanged; parsing or re-serializing the event can invalidate its signature.

Response

received

boolean

Confirms that a verified event was accepted or safely recognized as already processed.

200 OK400 Bad Request

Public disable flow

Handle signed auto-overage disable links safely

The email link opens a confirmation page with no immediate state change. Only POST attempts the disable action, then redirects to billing settings with a success or failure query flag.

Flow contract

GET /public/auto-overage/disable

token query required

Returns a noindex HTML confirmation page. Invalid tokens still return a safe informational page.

POST /public/auto-overage/disable

token form/body required

Attempts disable action then redirects to /dashboard/billing?autoOverageDisabled=1 on success or autoOverageDisabled=0 when disable was not applied.

Next steps

Connect billing state to usage and auth behavior

Continue with the pages below to implement entitlement checks and account level controls end to end.

Need usage + limits?

Open usage reference

Read usage summary and logs with billing-aware account context.

Reference

Need auth split clarity?

Open auth models concept

Confirm bearer versus public signed-flow behavior across routes.

Concept

Need failure semantics?

Open error model

Use shared status and retry guidance when billing calls fail.

Reference

Billing overview

GET

curl "https://api.solidrelay.io/user/subscription" \
  -H "Authorization: Bearer ACCESS_TOKEN"

200 OK

{
  "status": "active",
  "plan": "professional",
  "currentPeriodEnd": "2026-05-01T00:00:00.000Z",
  "cancelAtPeriodEnd": false,
  "scheduledPlan": null,
  "scheduledPlanEffectiveDate": null,
  "autoOverageEnabled": true,
  "autoOverageBlockSize": 1000,
  "autoOverageCycleCapCents": 15000
}

GET /user/subscription

GET

curl "https://api.solidrelay.io/user/subscription" \
  -H "Authorization: Bearer ACCESS_TOKEN"

200 OK

{
  "status": "active",
  "plan": "professional",
  "currentPeriodEnd": "2026-05-01T00:00:00.000Z",
  "cancelAtPeriodEnd": false,
  "scheduledPlan": null,
  "scheduledPlanEffectiveDate": null,
  "autoOverageEnabled": true,
  "autoOverageBlockSize": 1000,
  "autoOverageCycleCapCents": 15000
}

Subscription action routes

POST

curl -X POST "https://api.solidrelay.io/user/subscription/cancel" \
  -H "Authorization: Bearer ACCESS_TOKEN"

POST

curl -X POST "https://api.solidrelay.io/user/subscription/resume" \
  -H "Authorization: Bearer ACCESS_TOKEN"

POST

curl -X POST "https://api.solidrelay.io/user/subscription/auto-overage" \
  -H "Authorization: Bearer ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "enabled": true,
    "blockSize": 1000,
    "spendCapCents": 10000
  }'

200 OK

{
  "status": "active",
  "plan": "professional",
  "autoOverageEnabled": true,
  "autoOverageBlockSize": 1000,
  "autoOverageCycleCapCents": 10000
}

GET /user/subscription/upgrade-preview

GET

curl "https://api.solidrelay.io/user/subscription/upgrade-preview?plan=business" \
  -H "Authorization: Bearer ACCESS_TOKEN"

200 OK

{
  "eligible": true,
  "currentPlan": "professional",
  "targetPlan": "business",
  "currency": "USD",
  "amountDueCents": 1200,
  "periodStart": "2026-04-01T00:00:00.000Z",
  "periodEnd": "2026-05-01T00:00:00.000Z"
}

POST /user/checkout

POST

curl -X POST "https://api.solidrelay.io/user/checkout" \
  -H "Authorization: Bearer ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "plan": "business"
  }'

200 OK

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

POST /user/overage

POST

curl -X POST "https://api.solidrelay.io/user/overage" \
  -H "Authorization: Bearer ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "blockSize": 1000
  }'

200 OK

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

GET /user/billing-portal

GET

curl "https://api.solidrelay.io/user/billing-portal" \
  -H "Authorization: Bearer ACCESS_TOKEN"

200 OK

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

GET /user/invoices

GET

curl "https://api.solidrelay.io/user/invoices?limit=20&offset=0&status=paid&sort=createdAt_desc" \
  -H "Authorization: Bearer ACCESS_TOKEN"

200 OK

{
  "invoices": [
    {
      "number": "A13B-0001",
      "status": "paid",
      "amountPaid": 4900,
      "amountDue": 0,
      "currency": "usd",
      "createdAt": "2026-04-01T00:00:00.000Z",
      "hostedInvoiceUrl": "https://invoice.stripe.com/i/acct_123/A13B-0001",
      "pdfUrl": "https://pay.stripe.com/invoice/acct_123/A13B-0001/pdf"
    }
  ],
  "total": 1,
  "limit": 20,
  "offset": 0,
  "statusOptions": ["draft", "open", "paid", "void"]
}

POST /webhooks/stripe

POST

curl -X POST "https://api.solidrelay.io/webhooks/stripe" \
  -H "Content-Type: application/json" \
  -H "stripe-signature: STRIPE_GENERATED_SIGNATURE" \
  --data-binary @stripe-event.json

200 OK

{
  "received": true
}

Public disable confirmation flow

GET

curl -i "https://api.solidrelay.io/public/auto-overage/disable?token=SIGNED_DISABLE_TOKEN"

200 HTML

HTTP/1.1 200 OK
Content-Type: text/html; charset=utf-8
X-Robots-Tag: noindex, nofollow
Content-Security-Policy: default-src 'none'; style-src 'unsafe-inline'; img-src data:; form-action 'self'

<!doctype html>
<html>
  <body>
    <h1>Confirm auto-overage disable</h1>
    <form method="post" action="/public/auto-overage/disable">
      <input type="hidden" name="token" value="SIGNED_DISABLE_TOKEN" />
      <button type="submit">Disable auto-overage</button>
    </form>
  </body>
</html>

POST

curl -i -X POST "https://api.solidrelay.io/public/auto-overage/disable" \
  -H "Content-Type: application/x-www-form-urlencoded" \
  --data "token=SIGNED_DISABLE_TOKEN"

302 Found

HTTP/1.1 302 Found
Location: https://app.solidrelay.io/dashboard/billing?autoOverageDisabled=1

Update auto-overage settings

POST

curl -X POST "https://api.solidrelay.io/user/subscription/auto-overage" \
  -H "Authorization: Bearer ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "enabled": true,
    "blockSize": 1000,
    "spendCapCents": 10000
  }'

200 OK

{
  "status": "active",
  "plan": "professional",
  "autoOverageEnabled": true,
  "autoOverageBlockSize": 1000,
  "autoOverageCycleCapCents": 10000
}