Billing

The billing API exposes read-only views of your subscription, usage, and invoice history. State changes (upgrade, downgrade, cancel, reactivate) go through Stripe's hosted checkout / portal flows; SimplyFill returns the URLs you redirect users to.

All routes are under /api/v1/billing and require an API key with read scope (write scope for the mutation endpoints).

Get current subscription

GET /api/v1/billing/subscription

Returns the current Stripe subscription, plan, status, and renewal date:

{
  "plan": "PRO",
  "status": "active",
  "trial_ends_at": null,
  "current_period_start": "2026-05-01T00:00:00Z",
  "current_period_end": "2026-06-01T00:00:00Z",
  "cancel_at_period_end": false,
  "stripe_customer_id": "cus_2nB9d4Z..."
}

List available plans

GET /api/v1/billing/plans

Returns metadata for every plan you could subscribe to, including features and Stripe price IDs.

Read current-period usage

GET /api/v1/billing/usage/current-period

The most useful endpoint for in-app quota banners. Returns the running counters for the current calendar month:

{
  "period_start": "2026-05-01T00:00:00Z",
  "period_end": "2026-06-01T00:00:00Z",
  "pdf_generations": { "used": 814, "limit": 1000, "remaining": 186 },
  "ai_generations": { "used": 7, "limit": 100, "remaining": 93 },
  "overage_pdfs": 0
}

Read usage history

GET /api/v1/billing/usage/history

Returns month-by-month historical counters. Use this to surface trend graphs in your dashboard.

GET /api/v1/billing/usage

Returns the most-recent N records of raw usage events (one per generation). Useful for reconciliation against your own logs.

Open Stripe Checkout

POST /api/v1/billing/checkout

Body:

{ "plan": "PRO", "interval": "month" }

Returns a Stripe Checkout session URL. Redirect the user there to upgrade.

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

Open the Stripe Customer Portal

GET /api/v1/billing/portal

Returns a one-time URL to Stripe's customer portal, where the user can change cards, view invoices, and cancel.

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

Upgrade / downgrade / cancel / reactivate

Each returns the updated Subscription body shown above. Body parameters mirror the Stripe Subscription Update API where applicable.

List invoices

GET /api/v1/billing/invoices

Returns paginated invoice history:

{
  "invoices": [
    {
      "id": "in_2nB9d4Z...",
      "amount_due": 4900,
      "currency": "usd",
      "status": "paid",
      "period_start": "2026-04-01T00:00:00Z",
      "period_end": "2026-05-01T00:00:00Z",
      "invoice_pdf": "https://pay.stripe.com/invoice/...",
      "created": "2026-05-01T00:01:11Z"
    }
  ],
  "total": 12
}

GET /api/v1/billing/invoices/{invoice_id}

Returns one invoice by ID.

Errors

Related

• Quotas concept — where the limits in usage/current-period come from
• Pricing page — marketing view of the same plan tiers