Accrue

Copy Markdown View Source

Billing state, modeled clearly.

Accrue is a Phoenix-era billing library: subscriptions, invoices, checkout, webhooks, and the rest of the Stripe-shaped surface as plain Elixir—not a pile of controllers you fork forever. You keep auth, routes, and product code; Accrue models money and lifecycle and ships a Fake processor so tests and CI stay offline.

If you ship a SaaS on Elixir and want documentation you can hand to a teammate, plus a straight path from “runs on my laptop” to “looks like how we run in prod,” you are in the right place.

Start here

  • Organization billing (non-Sigra) — session→billable org path when the Stripe Customer should follow an organization, not only the signed-in user.
  • Testing — Fake-first verification posture for host billing flows.
  • First Hour — one sitting from deps to a working billing slice.
  • Production readiness — ordered checklist before promoting billing to production or live Stripe (webhooks, tenancy, observability, CI vs live lanes).
  • Maturity and maintenance — when Accrue is “done enough” for the pre-1.0 line, how friction enters planning, and how Hex publishes trigger contract passes.
  • Troubleshooting — when something already wired misbehaves.
  • Webhooks — signing, retries, and operational notes.
  • Quickstart — smallest possible skim.
  • Demo app README — command parity with Accrue’s CI host gate.
  • Release notes and Upgrade — what changed, in plain language, then the formal contract.
  • HexDocs — every guide and API page together; use the Guides section as the full index.

Install

Hex vs main: The {:accrue, "~> …"} line below tracks accrue/mix.exs @version on the branch you are reading (typically main on GitHub). Hex.pm publishes that train after release; use HexDocs for API docs matched to the Hex version you resolved.

If you also pull accrue_admin, match its ~> to the same train, and rely on a resolved mix.lock in production while Accrue is pre-1.0.

In mix.exs:

defp deps do
  [
    {:accrue, "~> 1.0.0"}
  ]
end

Then:

mix deps.get
mix accrue.install

After install, pick up the walkthrough from Start here (First Hour) above—no need to duplicate those steps here.

Optional checks from the host app:

  • mix verify — short “tutorial proof” suite
  • mix verify.full — closer to what CI runs
  • From the repo root: bash scripts/ci/accrue_host_uat.sh — full host integration gate

What you get

  • Billing domain: customers, subscriptions, invoices, charges, refunds, coupons, promotion codes, metered usage.
  • Money paths: Checkout, billing portal, Connect helpers behind one processor contract (Stripe in production, Fake in test).
  • Operations: webhook ingest, async dispatch, replay, event history, telemetry.
  • Product polish: transactional email, invoice PDFs, installer tasks.

The LiveView dashboard ships as the sibling Hex package accrue_admin; pin it to the same version family as accrue when you add the operator UI.

Stability

Your supported integration surface—generated MyApp.Billing, use Accrue.Webhook.Handler, use Accrue.Test, AccrueAdmin.Router, Accrue.Auth, Accrue.ConfigError—is spelled out in Upgrade. Breaking changes on that surface go through deprecation, not silent reshuffles, including while public SemVer is still 0.x. Internal schemas, workers, and demo helpers are not that contract. 0.x may still ship additive work and proof tightening, but it does not promise an ever-growing feature roadmap—see Maturity and maintenance. When you are ready to coordinate a 1.0.0 pair on Hex, maintainers follow repository root RELEASING.md (Appendix: Same-day 1.0.0 bootstrap).

Generated files are yours after install. Accrue only refreshes pristine stamped copies on installer reruns; it does not stomp files you have edited.

Community

Contributing · Code of Conduct · Security

Keep Stripe credentials and webhook signing secrets in runtime configuration, not in the repo. Use Security for vulnerability reports.