Skip to content

Introduction

Cbox Billing

cboxdk/laravel-billing is the billing engine for Laravel: a gateway-agnostic library of billing primitives you compose into a billing product. It is the framework peer to cboxdk/laravel-id — UI-free and domain-free. Every capability sits behind a contract you bind, mock, or replace.

This is the package, not the product. The deployable, self-hostable billing app built on it — with an admin console and customer portal — is the separate cboxdk/cbox-billing application, exactly as cbox-id is the app built on laravel-id. Reach for the app if you don't want to build the UI and hosting layer yourself; reach for this package to embed billing in your own Laravel app.

The mental model: three separate concerns

Real-time enforcement, metering truth, and money are three separate layers. The invoice is computed from the immutable event log, never read from a counter. Keeping these apart is the load-bearing decision the whole library is built around.

Layer Question it answers Store Authority
1 · Enforcement May this request proceed? (sub-ms) App-local counter (Laravel cache, atomic increment) none — eventually consistent, small bounded drift
2 · Metering truth What actually happened? Immutable append-only usage event log metering source of truth
3 · Money What is owed / paid / owned? Double-entry ledger, balances derived from postings money source of truth

Hard limits are enforced locally per node against a leased slice of the org's allowance — no shared or co-located Redis required. A small, bounded, backfillable drift is accepted by design, and reconciliation trues the ledger up from the event log. The full rationale is in Architecture & foundation contracts.

Sections

  • Getting started — install, the three-layer architecture, and the module map.
  • Core concepts — one page per module: metering, wallets, ledger, reconciliation, subscriptions, entitlements, accounts, catalog, quotes and invoicing, payments, refunds.
  • Cookbook — task-first recipes: enforce a hard limit, grant and burn credits, reconcile usage, preview a plan change, ingest a payment webhook, roll out a plan entitlement.
  • Licensing — the on-prem license issuer: mint a signed, offline-verifiable license from an enterprise plan, renew it on subscription renewal, and revoke it (verifier lives in the consuming app).
  • Extension points — the contracts you bind, storage adapters, gateway adapters, and the dogfooded testing seams.
  • Configuration — every config/billing.php key.
  • Security — an honest threat model and the app-layer vs library boundary.

Design decisions (ADRs)

The decisions that hardened the surface are recorded as ADRs, linked inline from the relevant concept pages:

Next → Quick start