Primary context module for Accrue billing operations.
All write operations for billable entities live here, following
conventional Phoenix context boundaries. Host schemas gain access to
these operations via use Accrue.Billable, which injects a
convenience customer/1 that delegates here.
Customer lifecycle
customer/1— lazy fetch-or-create. First call auto-creates anaccrue_customersrow via the configured processor; subsequent calls return the cached row.create_customer/1— explicit create, always hits the processor.customer!/1andcreate_customer!/1— raising variants following the same{:ok, _} | {:error, _}vs!naming convention as the rest of Accrue.
All writes use Ecto.Multi to ensure the customer row and the
corresponding accrue_events entry are committed atomically.
Summary
Functions
Explicitly creates a Customer for the given billable struct.
Raising variant of create_customer/1. Returns the Customer
directly or raises on error.
Lazily fetches or creates a Customer for the given billable struct.
Raising variant of customer/1. Returns the Customer directly or
raises on error.
Shallow-merges partial_data into the existing data column (D2-08).
Fully replaces the data jsonb column on a billing record (D2-08).
Updates a Customer with the given attributes.
Updates a processor-backed customer's tax location with immediate validation.
Raising variant of update_customer_tax_location/2.
Functions
@spec create_customer(struct()) :: {:ok, Accrue.Billing.Customer.t()} | {:error, term()}
Explicitly creates a Customer for the given billable struct.
Uses Ecto.Multi to atomically:
- Create the customer on the processor side (Fake or Stripe)
- Insert the
accrue_customersrow with the processor-assigned ID - Record a
"customer.created"event (EVT-04)
Returns {:ok, %Customer{}} on success or {:error, reason} on
failure. The entire transaction rolls back if any step fails.
Examples
{:ok, customer} = Accrue.Billing.create_customer(user)
customer.processor_id #=> "cus_fake_00001"@spec create_customer!(struct()) :: Accrue.Billing.Customer.t()
Raising variant of create_customer/1. Returns the Customer
directly or raises on error.
@spec customer(struct()) :: {:ok, Accrue.Billing.Customer.t()} | {:error, term()}
Lazily fetches or creates a Customer for the given billable struct.
If a customer row already exists for the billable's owner_type and
owner_id, returns it. Otherwise, creates one via the configured
processor and persists it atomically with an event record.
Examples
{:ok, customer} = Accrue.Billing.customer(user)
{:ok, ^customer} = Accrue.Billing.customer(user) # same row@spec customer!(struct()) :: Accrue.Billing.Customer.t()
Raising variant of customer/1. Returns the Customer directly or
raises on error.
@spec patch_data(Ecto.Schema.t(), map()) :: {:ok, Ecto.Schema.t()} | {:error, term()}
Shallow-merges partial_data into the existing data column (D2-08).
Used when a partial event carries only a delta. Applies optimistic
locking via lock_version.
Examples
{:ok, patched} = Accrue.Billing.patch_data(customer, %{"balance" => 100})@spec put_data(Ecto.Schema.t(), map()) :: {:ok, Ecto.Schema.t()} | {:error, term()}
Fully replaces the data jsonb column on a billing record (D2-08).
Used by webhook reconcile paths that receive the whole object (e.g.
customer.updated). Applies optimistic locking via lock_version.
Examples
{:ok, updated} = Accrue.Billing.put_data(customer, %{"balance" => 0})@spec update_customer( %Accrue.Billing.Customer{ __meta__: term(), charges: term(), data: term(), default_payment_method: term(), default_payment_method_id: term(), email: term(), id: term(), inserted_at: term(), invoices: term(), last_stripe_event_id: term(), last_stripe_event_ts: term(), lock_version: term(), metadata: term(), name: term(), owner_id: term(), owner_type: term(), payment_methods: term(), preferred_locale: term(), preferred_timezone: term(), processor: term(), processor_id: term(), subscriptions: term(), updated_at: term() }, map() ) :: {:ok, Accrue.Billing.Customer.t()} | {:error, term()}
Updates a Customer with the given attributes.
Uses Ecto.Multi to atomically update the customer and record a
"customer.updated" event (EVT-04). Metadata is validated per D2-07
(flat string map, max 50 keys, etc.). Optimistic locking via
lock_version prevents torn writes (D2-09).
Examples
{:ok, customer} = Accrue.Billing.update_customer(customer, %{metadata: %{"tier" => "pro"}})@spec update_customer_tax_location( %Accrue.Billing.Customer{ __meta__: term(), charges: term(), data: term(), default_payment_method: term(), default_payment_method_id: term(), email: term(), id: term(), inserted_at: term(), invoices: term(), last_stripe_event_id: term(), last_stripe_event_ts: term(), lock_version: term(), metadata: term(), name: term(), owner_id: term(), owner_type: term(), payment_methods: term(), preferred_locale: term(), preferred_timezone: term(), processor: term(), processor_id: term(), subscriptions: term(), updated_at: term() }, map() ) :: {:ok, Accrue.Billing.Customer.t()} | {:error, term()}
Updates a processor-backed customer's tax location with immediate validation.
This public path is distinct from update_customer/2, which remains a
local-only row update for non-processor customer maintenance.
@spec update_customer_tax_location!( %Accrue.Billing.Customer{ __meta__: term(), charges: term(), data: term(), default_payment_method: term(), default_payment_method_id: term(), email: term(), id: term(), inserted_at: term(), invoices: term(), last_stripe_event_id: term(), last_stripe_event_ts: term(), lock_version: term(), metadata: term(), name: term(), owner_id: term(), owner_type: term(), payment_methods: term(), preferred_locale: term(), preferred_timezone: term(), processor: term(), processor_id: term(), subscriptions: term(), updated_at: term() }, map() ) :: Accrue.Billing.Customer.t()
Raising variant of update_customer_tax_location/2.