Accrue

Copy Markdown View Source

Billing state, modeled clearly.

Accrue is the billing library. Your Phoenix app owns the generated MyApp.Billing facade, router mounts, runtime config, and auth/session boundary. Start with the host-first First Hour guide, then keep the checked-in examples/accrue_host demo nearby for command parity and the canonical local proof path.

Start Here

The compact adoption path is:

  1. Install accrue in your Phoenix app.
  2. Follow the First Hour guide for runtime config, migrations, Oban, use Accrue.Webhook.Handler, and accrue_admin "/billing".
  3. Compare that setup with the checked-in examples/accrue_host demo path.

Install

Add Accrue to deps/0 and fetch dependencies:

defp deps do
  [
    {:accrue, "~> 0.2.0"}
  ]
end
mix deps.get
mix accrue.install

Use the First Hour guide for the full tutorial story. Keep the checked-in examples/accrue_host app nearby when you want the canonical local demo path and command parity.

The canonical verification labels are:

  • mix verify for the focused tutorial proof suite
  • mix verify.full for the CI-equivalent local gate
  • bash scripts/ci/accrue_host_uat.sh for the repo-root wrapper around that full gate

What ships

  • Billing facades for customers, subscriptions, invoices, charges, refunds, coupons, promotion codes, and metered usage.
  • Checkout, billing portal, and Connect helpers on top of the Stripe-backed processor contract.
  • Webhook ingest, async dispatch, replay tooling, event-ledger history, and operational telemetry.
  • Transactional email, invoice PDF rendering, installer tasks, and a Fake-first test surface.

Public API stability

The supported public setup surface for first-time integration is:

  • your generated MyApp.Billing
  • use Accrue.Webhook.Handler
  • use Accrue.Test
  • AccrueAdmin.Router.accrue_admin/2
  • Accrue.Auth
  • Accrue.ConfigError for setup failures

Breaking changes for that facade layer follow the deprecation cycle documented in guides/upgrade.md. Accrue deprecates public APIs before removal instead of silently changing behavior in place.

Generated files are host-owned after install. Accrue may refresh pristine stamped files on installer reruns, but user-edited generated files are not silently managed. Internal schemas, webhook/event structs, reducer modules, worker internals, and demo-only helpers are not first-time integration APIs.

Guides

Security

Use runtime-only secrets for Stripe credentials, keep webhook signing secrets out of source control, and review the repository SECURITY.md before production rollout or vulnerability reporting.

Project policies