API Reference accrue v#1.0.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).

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.

Pure policy module for dunning.

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.

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.

Ecto schema for the accrue_payment_methods table.

Payment method write surface.

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.

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 Stripe subscription API 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.

Stripe Checkout Session 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.

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.

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.

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).

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.

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.

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).

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 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 :chromic_pdf_not_started). 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).

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].

The adapter contract between Accrue and payment processors.

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.

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.