API Reference accrue v#1.4.0

Accrue — billing state, modeled clearly.

Raised when a processor call fails for a reason that is neither a card error nor a rate limit (e.g., HTTP 500, unexpected payload). Pattern-match on %Accrue.APIError{} in retry logic.

Raised when a Stripe PaymentIntent or SetupIntent transitions to requires_action (SCA / 3DS). The :payment_intent field carries the full PaymentIntent payload so callers can extract client_secret and drive the Stripe.js confirmation flow on the frontend.

Process-dictionary-backed actor context for the Events ledger (D-15).

Analytics context for Dunning.

OTP Application module for Accrue — manages boot-time validation and the supervision tree.

Behaviour + facade for host-app auth integration.

Dev-permissive, prod-refuse-to-boot default Accrue.Auth adapter (D-40).

Process-local Accrue.Auth adapter for host test suites.

Raised when a destructive admin action requires step-up verification but the configured auth adapter does not implement the optional callbacks.

One-line macro that makes any host schema billable.

Primary context module for Accrue billing operations.

Ecto schema for the accrue_charges table.

Charge / payment intent / setup intent write surface.

Ecto schema for the accrue_coupons table.

Coupon and promotion-code write surface.

Ecto schema for the accrue_customers table.

Canonical local discount mapping for Braintree promotion-code resolution.

Local write/read/resolve helpers for Braintree discount mappings.

Pure policy module for dunning.

Ecto schema for accrue_entitlement_summaries (ENT-10).

Wraps Stripe intent-capable responses into the intent_result tagged union (D3-06..D3-08).

Ecto schema for the accrue_invoices table.

Invoice write surface.

Ecto schema for the accrue_invoice_coupons redemption link table (D3-16).

Ecto schema for the accrue_invoice_items table (D3-15).

Deterministic decomposition of a processor (Stripe- or Fake-shaped) invoice into a flat attrs map ready for Accrue.Billing.Invoice.changeset/2 plus a list of per-line attrs ready for Accrue.Billing.InvoiceItem.changeset/2.

Stripe-compatible metadata validation and merge helpers.

Accrue-owned billability contract for one raw usage event name.

Local write/read helpers for Braintree meter definitions.

Ecto schema for accrue_meter_events — the metered billing audit ledger and transactional outbox.

Metered billing write surface.

Helper for asynchronous meter-event state transitions driven by Stripe webhooks.

Durable settlement ledger for one metered renewal window.

Replay-safe settlement state transitions for one metered renewal window.

Immutable local renewal-window anchor for one metered billing period.

Opens immutable metered renewal windows from canonical Braintree renewal evidence.

Authors one canonical local invoice for a closed metered renewal window.

Ecto schema for the accrue_payment_methods table.

Payment method orchestration.

Ecto schema for the accrue_promotion_codes table.

Decomposes a processor promotion-code map (atom- or string-keyed) into a flat attrs map ready for Accrue.Billing.PromotionCode.changeset/2.

Composable Ecto.Query fragments mirroring the Accrue.Billing.Subscription predicates.

Ecto schema for the accrue_refunds table (D3-45).

Refund write surface.

Provides native PostgreSQL trigram similarity search for core billing objects.

Ecto schema for the accrue_subscriptions table.

Write surface for subscription lifecycle operations.

Ecto schema for the accrue_subscription_items table.

Multi-item subscription surface.

Translates a processor subscription response into local Ecto changesets.

Ecto schema for accrue_subscription_schedules.

Write surface for Stripe SubscriptionSchedules.

Decomposes a Stripe/Fake SubscriptionSchedule payload into the flat attrs map consumed by Accrue.Billing.SubscriptionSchedule.changeset/2 and force_status_changeset/2.

Trial end normalization (D3-38).

Non-persistent struct representing a proration preview.

A single line on an upcoming-invoice preview.

Customer Billing Portal context.

Stripe Customer Billing Portal session wrapper.

Raised when the processor rejects a card (declined, expired, insufficient funds, etc.). Mirrors Stripe's card-error shape 1:1.

Stripe Checkout integration facade.

Helpers for constructing Stripe Checkout line_items array entries.

Persisted local checkout sessions used by processors that route checkout through a first-party Accrue portal.

Checkout handoff wrapper.

Provides the core functions to retrieve and manage the CLDR data that supports formatting and localisation.

Parses HTTP Accept-Language header values as defined in rfc2616.

Backend module that provides functions to define new locales and display human-readable locale names for presentation purposes.

A backend module for Money.

Formats numbers and currencies based upon CLDR's decimal formats specification.

Implements cardinal plural rules for numbers.

Functions to manage the collection of number patterns defined in Cldr.

Implements ordinal plural rules for numbers.

Implements plural rules for ranges

Transliteration for digits and separators.

Functions to implement the number system rule-based-number-format rules of CLDR.

Functions to implement the ordinal rule-based-number-format rules of CLDR.

Functions to implement the spellout rule-based-number-format rules of CLDR.

Canonical time source for Accrue.

Runtime configuration schema for Accrue, backed by NimbleOptions.

Raised when Accrue.Config validation fails, or when a key is looked up that is neither set at runtime nor has a schema default.

Stripe Connect domain facade.

Ecto schema for accrue_connect_accounts — the local projection of a Stripe Connected Account (D5-02, CONN-01/03).

Onboarding/update bearer credential for a connected account.

Express dashboard return credential for a connected account.

Pure Accrue.Money math for platform fee computation.

Decomposes a processor-shaped (Stripe- or Fake-produced) Connected Account payload into a flat attrs map ready for Accrue.Connect.Account.changeset/2 (D5-02).

Raised when a processor response body cannot be decoded (malformed JSON, unexpected shape). The payload field holds the raw binary for debugging — treat as sensitive; do not log verbatim.

Public API for checking dunning state, enabling host applications to display in-app banners or alerts for active dunning campaigns without false positives from projection lag.

Pure step resolver for the built-in dunning campaign (DUN-02, D-11).

Behaviour for dunning campaign orchestration engines (DUN-03, D-01).

Built-in dunning engine backed by Oban (DUN-03, D-02).

Two storage shapes for %Accrue.Money{} in Ecto schemas — both shipped in Phase 1 per D-02 and RESEARCH Open Question 5.

Card-expiring-soon reminder email.

Coupon applied notification.

Dunning step-2 ("action required") email — D-01, D-02.

Dunning step-3 ("final notice") email — D-01, D-02.

Canned assigns for every Accrue.Emails.* type.

Invoice finalized notification.

Invoice paid confirmation.

Invoice payment-failed notification.

Canonical payment-failed email.

Receipt-style confirmation for a successful payment.

Canonical receipt email.

Refund issued notification.

Subscription cancellation confirmation.

Subscription-paused notification.

Subscription-resumed notification.

Trial-ended notification email.

Trial-ending reminder email.

Public, fail-closed entitlement gate API.

Internal read-only diagnostic seam for the accrue_admin entitlements tab (ENT-11).

The always-compiled, LiveView-runtime-free decision engine shared by both enforcement surfaces (Accrue.Plug.RequireEntitlement and the cond-compiled Accrue.Live.Entitlements on_mount guard).

Pure, clock-driven past-due grace-window check (ENT-09, D-17).

Pure value struct for a resolved entitlement plan.

Behaviour + runtime-dispatch seam for entitlement resolution.

Default entitlement resolver — derives a billable's entitlements from local subscription state only, with zero processor calls.

Read-only observational seam over the optional Stripe-native entitlement-summary cache (accrue_entitlement_summaries, ENT-10).

Raised when a stored local discount mapping is present but cannot be resolved safely because the canonical local row has drifted into an invalid state.

Raised when a state-machine transition is attempted from an illegal source state (e.g., pay_invoice/2 on a :void invoice, resume/2 on an :active subscription).

Returned when the explicitly configured invoice renderer cannot run due to a stable host misconfiguration.

Raised when a metered renewal attempts to create a second settlement unit for a period that already has a canonical charge attempt.

Raised when a metered renewal settlement is attempted before the renewal has the local billing truth required for money movement.

Raised when a legacy convenience call (e.g., update_quantity/3) is made against a subscription that has more than one SubscriptionItem. Multi-item subscriptions require Accrue.Billing.update_items/3; the convenience helpers enforce a single-item invariant.

Raised when a charge or subscription call requires a default payment method and the customer has none set. Callers should surface a user-facing "add a payment method" prompt.

Raised when a payment method is referenced for a customer it is not attached to (e.g., set_default_payment_method/3 with a pm_id that belongs to a different customer).

Raised / returned when the configured PDF adapter is Accrue.PDF.Null. Expected and terminal — callers MUST pattern-match and fall through to a non-PDF path (e.g., link to hosted_invoice_url instead of attaching a rendered binary). Oban workers MUST NOT treat this as a transient retry; it is a stable adapter configuration, not a failure.

Raised when a caller attempts to UPDATE or DELETE a row in accrue_events. The append-only guarantee is enforced in two places

Tamper-evident audit ledger for Accrue billing events.

Ecto schema for a row in the append-only accrue_events table.

Registry mapping Phase 3 event atoms to their canonical schema modules (D3-66, D3-68).

Payload schema for :"card.expiring_soon" events (D3-66).

Payload schema for :"invoice.paid" events (D3-66).

Payload schema for :"refund.created" events (D3-66).

Payload schema for :"subscription.canceled" events (D3-66).

Payload schema for :"subscription.created" events (D3-66).

Payload schema for :"subscription.plan_swapped" events (D3-66).

Payload schema for :"subscription.updated" events (D3-66).

Upcaster behaviour for event schema_version evolution (D3-69).

Chain composition for event schema-version upcasting.

Example upcaster from schema_version: 1 to schema_version: 2.

Raised when the processor rejects an idempotency key replay (e.g., same key used for a different request body). Pattern-match on %Accrue.IdempotencyError{} to surface a user-facing "this request was already processed" message.

No-clobber primitives for Accrue-generated host files.

Strict option parsing for mix accrue.install.

Safe host-file patch builders and manual snippets for Accrue installs.

Phoenix host project discovery for mix accrue.install.

Renders host-owned installer templates.

Off-by-default Chimeway dunning engine adapter for Accrue (DUN-03).

Bundled Chimeway.Notifier implementation for Accrue dunning notifications.

Behaviour + facade for invoice-specific PDF rendering.

Invoice renderer that preserves the existing HEEx-to-ChromicPDF path.

Null invoice renderer for Chrome-hostile or PDF-disabled deploys.

Native Rendro-backed invoice renderer.

Invoice facade (D6-04). Owns lazy PDF rendering + storage delegation.

Phoenix.Component function components shared by email and PDF.

HEEx layout wrappers for PDF (and optionally, shared email shells).

Invoice render orchestration — builds a single RenderContext and exposes format-helper functions shared by the email + PDF pipelines.

Format-neutral hydrated invoice payload (D6-04).

Static branding-aware inline-CSS lookup used by Accrue.Invoices.Components to stamp style="..." attributes on every structural element.

Scheduled Oban worker for expiring-card detection.

Oban cron worker for the dunning grace-period overlay.

Metered billing outbox reconciler.

Narrow scheduled backstop for stale Braintree renewal windows.

Worker-owned BT-06 aggregation path for one metered renewal window.

Daily backstop Oban worker for charge fees that weren't populated at create time (D3-46).

Daily backstop Oban worker for refund fees that weren't populated at create time (D3-46).

on_mount/4 entitlement guard for host LiveViews (ENT-07).

Behaviour + facade for the Accrue transactional email pipeline.

Default Accrue.Mailer adapter — enqueues an Oban job on the :accrue_mailers queue that a worker later turns into a delivered email.

Swoosh-backed delivery module for Accrue's transactional emails.

Test adapter for Accrue.Mailer (D6-05). Replaces Accrue.Mailer.Default at the behaviour layer — intercepts Accrue.Mailer.deliver/2 BEFORE Oban enqueue. Sends the intent tuple to the calling test pid and returns immediately.

Accrue's canonical money value type — a thin, opinionated wrapper over the :ex_money currency table.

Raised when Accrue.Money arithmetic is attempted across two different currencies. Per D-04, cross-currency math never silently coerces or returns a tagged tuple — it raises at the call site so the bug surfaces immediately.

Helper for setting Accrue.Actor operation_id from an Oban job (D3-63).

Behaviour + facade for legacy HTML-to-PDF rendering.

ChromicPDF adapter for Accrue.PDF (D-32, D-33).

Null Accrue.PDF adapter for Chrome-hostile deploys (D6-06).

Raised from Accrue.Workers.Mailer.perform/1 when Accrue.Billing.render_invoice_pdf/2 returns a non-terminal {:error, reason} (i.e., not %Accrue.Error.PdfDisabled{} and not %Accrue.Error.InvoiceRendererUnavailable{}). Raising this exception lets Oban backoff handle transient render failures — the mailer job is retried per its max_attempts setting.

Chrome-free Accrue.PDF adapter for test environments (D-34).

Host-owned resolver for plan metadata that the shared price_id facade does not carry by itself.

Stashes a per-request Connect stripe_account id into the process dictionary for the lifetime of the request.

Sets Accrue.Actor operation_id from conn.assigns[:request_id].

A controller-pipeline guard that halts a request unless the resolved billable is entitled to a feature: (or holds an active plan:).

Asynchronously records and reduces the synthetic local-portal checkout completion event after a successful Braintree subscribe handoff.

The adapter contract between Accrue and payment processors.

Production Braintree adapter for the gateway subscription core slice.

Capability map for bounded processor slices.

Deterministic in-memory Accrue.Processor adapter for tests and demos.

Internal state struct for Accrue.Processor.Fake.

Deterministic idempotency key and subject UUID derivation for Phase 3 processor operations (D3-60, D3-61, D3-64).

Production Stripe adapter — wires all Accrue.Processor callbacks to :lattice_stripe.

Translates raw LatticeStripe error shapes into Accrue.Error subtypes.

Raised when the processor returns a rate-limit response (HTTP 429). The retry_after field carries the server's suggested backoff in seconds.

Thin facade over the host-configured Ecto.Repo.

Router helpers for mounting Accrue webhook endpoints.

Shared setup-diagnostic carrier for first-hour host misconfiguration.

Raised when a webhook signature fails verification. This is NEVER returned as a tuple — a bad signature is either a misconfiguration or an attacker, and neither is recoverable at the call site. The webhook plug translates this raise into an HTTP 400.

Behaviour + facade for pluggable PDF / asset storage.

No-op Accrue.Storage adapter — the v1.0 default (D6-04).

Stripe-specific helpers for host applications (D2-15).

Telemetry conventions and helpers for Accrue.

Default Telemetry.Metrics recipe for SRE teams.

Optional OpenTelemetry bridge for Accrue telemetry spans.

Ops-grade telemetry emit helper.

Public test helper facade for host applications.

Deterministic clock helpers for host tests.

ExUnit-style assertions for Accrue's append-only event ledger.

Phase 3 test factories (D3-79..85).

StreamData generators for Phase 3 property tests (D3-81).

ExUnit-style assertions for Accrue.Mailer.Test intent captures (D6-05). Symmetric with Accrue.Test.PdfAssertions.

ExUnit-style assertions for Accrue.PDF.Test render captures (D-34). Symmetric with Accrue.Test.MailerAssertions.

Synthetic webhook helpers for host tests.

Custom body reader for Plug.Parsers that tees the raw body into conn.assigns[:raw_body] for webhook signature verification.

Webhook handler for events arriving on the :connect endpoint.

Non-disableable default handler for built-in state reconciliation.

Oban worker for async webhook handler dispatch.

Lean event struct passed to webhook handlers.

Behaviour for webhook event handlers (D2-27).

Transactional webhook event persistence and Oban job dispatch (D2-24).

Core webhook ingestion plug.

Oban cron worker for webhook event retention (D2-34).

Webhook signature verification. Delegates entirely to LatticeStripe.Webhook.construct_event!/4 (D2-22).

Ecto schema for the accrue_webhook_events table.

Dead-letter queue replay and retention for webhook events.

Durable, cancel-guarded, Oban-unique dunning-campaign step worker (DUN-02, DUN-05; D-10, D-11, D-16).

Oban worker that delivers a transactional email asynchronously.

Generates a host-owned Accrue webhook handler scaffold. Generated files are stamped with # accrue:generated by Accrue.Install.Fingerprints.

Generates host-owned Accrue wiring.

Manually trigger the same retention sweep that Accrue.Webhook.Pruner runs on its Oban cron schedule. Useful for ops engineers who want to reclaim DB space without waiting for the next scheduled run.

Requeue dead-lettered webhook events from the command line.