Write surface for subscription lifecycle operations.

Every function here is exposed on Accrue.Billing — you rarely call this module directly. Use Accrue.Billing.subscribe/3, Accrue.Billing.cancel/2, etc. instead.

When you reach for this module

If you need to go deeper than Accrue.Billing exposes — for example, to call a function in a context where defdelegate wrapping is in the way — these are the underlying implementations.

Lifecycle groups

Create

• subscribe/3 — subscribe a billable to a price; returns an intent result (SCA-safe: may return {:ok, :requires_action, payment_intent})
• comp_subscription/3 — create a 100%-off comped subscription

Manage plan

• swap_plan/3 — replace the current price with a new one (proration required)
• update_quantity/3 — change the quantity on a single-item subscription
• preview_upcoming_invoice/2 — fetch the next invoice before it's finalized

Pause and resume

• pause/2 — pause collection (void, mark_uncollectible, or keep_as_draft)
• unpause/2 — resume a paused subscription
• resume/2 — cancel a pending cancellation (undo cancel_at_period_end)

Cancel

• cancel/2 — cancel immediately
• cancel_at_period_end/2 — schedule cancellation at the end of the billing period

Read

• get_subscription/2 — fetch a local subscription row by id

Return types

Operations that involve a PaymentIntent (subscribe, swap_plan, cancel with invoice_now: true) return intent_result(Subscription.t()):

{:ok, %Subscription{}}
| {:ok, :requires_action, payment_intent_map}
| {:error, term()}

All other operations return {:ok, %Subscription{}} | {:error, term()}.

Atomicity

Every write atomically persists the local row change and appends an event to accrue_events inside the same Repo.transact/1 call.