---
title: "Billing & Subscriptions"
description: "Plans, checkout, subscription state, usage against plan limits, add-ons and billing invoices for your own BareLedger subscription."
url: "https://bareledger.app/guides/api-billing"
category: "Developers & API"
updated: "2026-10-22"
publisher: "BareLedger (Syneria Technologies OPC)"
---

# Billing & Subscriptions

> Plans, checkout, subscription state, usage against plan limits, add-ons and billing invoices for your own BareLedger subscription.

Most read endpoints have no explicit permission (any tenant member can see their own plan/usage); management actions require `billing.manage` or `billing.view`.

| Method & Path | Permission | Purpose | Side effects |
|---|---|---|---|
| `GET billing/plans` | — | Plans with FX-resolved pricing | — |
| `GET billing/subscription` | — | Active subscription + entitlements | — |
| `GET billing/usage` | — | Usage vs plan caps | — |
| `GET billing/transactions` | `billing.view` | Billing transaction history | — |
| `GET billing/invoices` / `GET billing/invoices/{uuid}` | `billing.view` | List / detail | — |
| `GET billing/invoices/{uuid}/pdf` / `/receipt` | `billing.view` | Stream invoice PDF / payment receipt PDF (paid only) | — |
| `POST billing/invoices/{uuid}/retry` | `billing.manage` | Reopen checkout for an outstanding invoice | Calls gateway checkout |
| `POST billing/discount/preview` | `billing.manage` | Preview a promo code (never throws) | — |
| `POST billing/quote` | `billing.manage` | Build a server-authoritative, time-locked checkout quote | Persists a `BillingQuote`; 422 if live FX is unavailable |
| `POST billing/subscribe` | `billing.manage` | Subscribe or change plan | Requires TOTP for paid plans; identity step-up for a paid→free downgrade |
| `POST billing/checkout/sync` | `billing.manage` | Verify a pending checkout with the gateway directly | Webhook-loss fallback; idempotent against the webhook path |
| `GET billing/addons` | — | Add-on catalogue (extra users; transaction blocks on Growth) — add-ons recur with the plan | — |
| `POST billing/addons` | `billing.manage` | Set add-on quantities | Decreases apply immediately; increases return a checkout URL for a prorated charge, after which the add-ons recur on every renewal invoice |
| `POST billing/subscription/{subscription}/cancel` | `billing.manage` | Cancel (immediate or at period end) | — |

## Platform admin billing

| Method & Path | Purpose |
|---|---|
| `GET admin/plans`, `POST admin/plans`, `PATCH admin/plans/{plan}` | Plan CRUD |
| `DELETE admin/plans/{plan}` | Delete (or deactivate if in use) |
| `POST/PATCH/DELETE admin/plans/{plan}/prices/{price}` | Per-country/interval price rows |
| `GET admin/billing/reconciliation` | Cross-tenant invoice ↔ payment ↔ gateway settlement matching |
| `GET/POST/PATCH/DELETE admin/discounts` | Promo code CRUD |

All `/admin/*` routes require the `platform` middleware, independent of tenant RBAC. See API — Platform Admin.