Operations on Stripe Invoice objects.
An Invoice is the document Stripe generates when it is time to bill a customer. Invoices track charges, taxes, discounts, and payment lifecycle. They can be created manually or automatically by subscriptions.
Lifecycle
draft --> (finalize) --> open --> (pay) --> paid
|
(void) --> void
|
(mark_uncollectible) --> uncollectibleCommon Workflow
For manually managed invoices:
# 1. Create a draft invoice (auto_advance: false prevents automatic finalization)
{:ok, invoice} = LatticeStripe.Invoice.create(client, %{
"customer" => customer_id,
"auto_advance" => false
})
# 2. Add InvoiceItems to the invoice
{:ok, _item} = LatticeStripe.InvoiceItem.create(client, %{
"customer" => customer_id,
"invoice" => invoice.id,
"amount" => 5000,
"currency" => "usd",
"description" => "Professional services"
})
# 3. Finalize the invoice (locks line items, moves to open)
{:ok, open_invoice} = LatticeStripe.Invoice.finalize(client, invoice.id)
# 4. Pay the invoice
{:ok, paid_invoice} = LatticeStripe.Invoice.pay(client, open_invoice.id)auto_advance
When auto_advance is true (the default for subscription invoices), Stripe
automatically finalizes the draft invoice after approximately 1 hour. Set
auto_advance: false when creating invoices manually so you can add line items
before finalization.
Stripe API Reference
See the Stripe Invoice API for the full object reference and available parameters.
Summary
Functions
Creates a new Invoice.
Like create/3 but raises LatticeStripe.Error on failure.
Creates an invoice preview.
Like create_preview/3 but raises LatticeStripe.Error on failure.
Retrieves line items for a create_preview invoice.
Deletes a draft Invoice by ID.
Like delete/3 but raises LatticeStripe.Error on failure.
Finalizes a draft invoice, transitioning it to open status.
Like finalize/4 but raises LatticeStripe.Error on failure.
Converts a decoded Stripe API map to a %Invoice{} struct.
Lists Invoices with optional filters.
Like list/3 but raises LatticeStripe.Error on failure.
Lists line items for a specific invoice.
Like list_line_items/4 but raises LatticeStripe.Error on failure.
Marks an open invoice as uncollectible. Only callable on open invoices.
Like mark_uncollectible/4 but raises LatticeStripe.Error on failure.
Pays an open invoice.
Like pay/4 but raises LatticeStripe.Error on failure.
Retrieves an Invoice by ID.
Like retrieve/3 but raises LatticeStripe.Error on failure.
Searches for invoices matching a query.
Returns a lazy stream of all invoices matching a search query (auto-pagination).
Sends an invoice to the customer via email.
Like send_invoice/4 but raises LatticeStripe.Error on failure.
Returns a lazy stream of all Invoices matching the given params (auto-pagination).
Returns a lazy stream of all line items for a specific invoice (auto-pagination).
Retrieves an upcoming invoice preview.
Like upcoming/3 but raises LatticeStripe.Error on failure.
Retrieves line items for an upcoming invoice preview.
Updates an Invoice by ID.
Like update/4 but raises LatticeStripe.Error on failure.
Voids an open invoice. Only callable on open invoices.
Like void/4 but raises LatticeStripe.Error on failure.
Types
@type t() :: %LatticeStripe.Invoice{ account_country: String.t() | nil, account_name: String.t() | nil, account_tax_ids: list() | nil, amount_due: integer() | nil, amount_paid: integer() | nil, amount_remaining: integer() | nil, amount_shipping: integer() | nil, application: String.t() | nil, application_fee_amount: integer() | nil, attempt_count: integer() | nil, attempted: boolean() | nil, auto_advance: boolean() | nil, automatic_tax: LatticeStripe.Invoice.AutomaticTax.t() | nil, billing_reason: atom() | String.t() | nil, charge: String.t() | nil, collection_method: atom() | String.t() | nil, created: integer() | nil, currency: String.t() | nil, custom_fields: list() | nil, customer: String.t() | nil, customer_address: map() | nil, customer_email: String.t() | nil, customer_name: String.t() | nil, customer_phone: String.t() | nil, customer_shipping: map() | nil, customer_tax_exempt: atom() | String.t() | nil, customer_tax_ids: list() | nil, default_payment_method: String.t() | nil, default_source: String.t() | nil, default_tax_rates: list() | nil, deleted: boolean(), description: String.t() | nil, discount: map() | nil, discounts: list() | nil, due_date: integer() | nil, effective_at: integer() | nil, ending_balance: integer() | nil, extra: map(), footer: String.t() | nil, from_invoice: map() | nil, hosted_invoice_url: String.t() | nil, id: String.t() | nil, invoice_pdf: String.t() | nil, issuer: map() | nil, last_finalization_error: map() | nil, latest_revision: String.t() | nil, lines: LatticeStripe.List.t() | nil, livemode: boolean() | nil, metadata: map() | nil, next_payment_attempt: integer() | nil, number: String.t() | nil, object: String.t(), on_behalf_of: String.t() | nil, paid: boolean() | nil, paid_out_of_band: boolean() | nil, payment_intent: String.t() | nil, payment_settings: map() | nil, period_end: integer() | nil, period_start: integer() | nil, post_payment_credit_notes_amount: integer() | nil, pre_payment_credit_notes_amount: integer() | nil, quote: String.t() | nil, receipt_number: String.t() | nil, rendering: map() | nil, rendering_options: map() | nil, shipping_cost: map() | nil, shipping_details: map() | nil, starting_balance: integer() | nil, statement_descriptor: String.t() | nil, status: atom() | String.t() | nil, status_transitions: LatticeStripe.Invoice.StatusTransitions.t() | nil, subscription: String.t() | nil, subscription_details: map() | nil, subscription_proration_date: integer() | nil, subtotal: integer() | nil, subtotal_excluding_tax: integer() | nil, tax: integer() | nil, test_clock: String.t() | nil, threshold_reason: map() | nil, total: integer() | nil, total_discount_amounts: list() | nil, total_excluding_tax: integer() | nil, total_tax_amounts: list() | nil, transfer_data: map() | nil, webhooks_delivered_at: integer() | nil }
A Stripe Invoice object.
See the Stripe Invoice API for field definitions.
Functions
@spec create(LatticeStripe.Client.t(), map(), keyword()) :: {:ok, t()} | {:error, LatticeStripe.Error.t()}
Creates a new Invoice.
Sends POST /v1/invoices with the given params and returns {:ok, %Invoice{}}.
Parameters
client- A%LatticeStripe.Client{}structparams- Map of invoice attributes. Common params:"customer"- Customer ID (required for manual invoices)"auto_advance"- Whether to auto-finalize (defaulttruefor subscriptions)"collection_method"-"charge_automatically"or"send_invoice"
opts- Per-request overrides (e.g.,[idempotency_key: "..."])
Returns
{:ok, %Invoice{}}on success{:error, %LatticeStripe.Error{}}on failure
@spec create!(LatticeStripe.Client.t(), map(), keyword()) :: t()
Like create/3 but raises LatticeStripe.Error on failure.
@spec create_preview(LatticeStripe.Client.t(), map(), keyword()) :: {:ok, t()} | {:error, LatticeStripe.Error.t()}
Creates an invoice preview.
Replacement for the legacy upcoming/3 endpoint. Returns %Invoice{id: nil}.
Parameters
Pass params as a map with keys like "customer", "subscription",
"subscription_items", "subscription_proration_behavior", etc.
Example
Invoice.create_preview(client, %{
"customer" => "cus_xxx",
"subscription_details" => %{
"items" => [%{"id" => "si_xxx", "price" => "price_new"}],
"proration_behavior" => "create_prorations"
}
})Proration Guard
If client.require_explicit_proration is true, "proration_behavior" must
be present in params or {:error, %Error{type: :proration_required}} is returned.
@spec create_preview!(LatticeStripe.Client.t(), map(), keyword()) :: t()
Like create_preview/3 but raises LatticeStripe.Error on failure.
@spec create_preview_lines(LatticeStripe.Client.t(), map(), keyword()) :: {:ok, LatticeStripe.Response.t()} | {:error, LatticeStripe.Error.t()}
Retrieves line items for a create_preview invoice.
Returns paginated %Invoice.LineItem{} structs for the preview invoice.
Parameters
client- A%LatticeStripe.Client{}structparams- Map with"customer"and optional subscription paramsopts- Per-request overrides
Returns
{:ok, %Response{data: %List{data: [%Invoice.LineItem{}, ...]}}}on success{:error, %LatticeStripe.Error{}}on failure
@spec delete(LatticeStripe.Client.t(), String.t(), keyword()) :: {:ok, t()} | {:error, LatticeStripe.Error.t()}
Deletes a draft Invoice by ID.
Sends DELETE /v1/invoices/:id and returns {:ok, %Invoice{}}.
Only applicable to draft invoices. Finalized invoices cannot be deleted;
use void/3 to cancel a finalized invoice.
Parameters
client- A%LatticeStripe.Client{}structid- The invoice ID stringopts- Per-request overrides
Returns
{:ok, %Invoice{}}on success{:error, %LatticeStripe.Error{}}on failure
@spec delete!(LatticeStripe.Client.t(), String.t(), keyword()) :: t()
Like delete/3 but raises LatticeStripe.Error on failure.
@spec finalize(LatticeStripe.Client.t(), String.t(), map(), keyword()) :: {:ok, t()} | {:error, LatticeStripe.Error.t()}
Finalizes a draft invoice, transitioning it to open status.
After finalization, no more items can be added and the invoice becomes payable. Only callable on draft invoices.
Parameters
client- A%LatticeStripe.Client{}structid- The invoice ID string (e.g.,"in_123")params- Optional params (e.g.,%{"auto_advance" => false})opts- Per-request overrides
Returns
{:ok, %Invoice{status: :open}}on success{:error, %LatticeStripe.Error{}}on failure
@spec finalize!(LatticeStripe.Client.t(), String.t(), map(), keyword()) :: t()
Like finalize/4 but raises LatticeStripe.Error on failure.
Converts a decoded Stripe API map to a %Invoice{} struct.
Maps all known Stripe Invoice fields. Any unrecognized fields are collected
into the extra map so no data is silently lost.
Atomizes status, collection_method, billing_reason, and customer_tax_exempt using a whitelist — unknown values pass through as strings to avoid atom table exhaustion from unexpected Stripe API values.
Example
invoice = LatticeStripe.Invoice.from_map(%{
"id" => "in_123",
"status" => "open",
"collection_method" => "charge_automatically",
"object" => "invoice"
})
# => %LatticeStripe.Invoice{id: "in_123", status: :open, ...}@spec list(LatticeStripe.Client.t(), map(), keyword()) :: {:ok, LatticeStripe.Response.t()} | {:error, LatticeStripe.Error.t()}
Lists Invoices with optional filters.
Sends GET /v1/invoices and returns {:ok, %Response{data: %List{}}} with
typed %Invoice{} items.
Parameters
client- A%LatticeStripe.Client{}structparams- Filter params (e.g.,%{"customer" => "cus_123", "status" => "open"})opts- Per-request overrides
Returns
{:ok, %Response{data: %List{data: [%Invoice{}, ...]}}}on success{:error, %LatticeStripe.Error{}}on failure
@spec list!(LatticeStripe.Client.t(), map(), keyword()) :: LatticeStripe.Response.t()
Like list/3 but raises LatticeStripe.Error on failure.
@spec list_line_items(LatticeStripe.Client.t(), String.t(), map(), keyword()) :: {:ok, LatticeStripe.Response.t()} | {:error, LatticeStripe.Error.t()}
Lists line items for a specific invoice.
Returns paginated line items rendered on the invoice. For draft invoices, these reflect the current InvoiceItems. For finalized invoices, these are locked.
Example
{:ok, response} = Invoice.list_line_items(client, "in_xxx")
line_items = response.data.data # [%Invoice.LineItem{}, ...]Parameters
client- A%LatticeStripe.Client{}structinvoice_id- The invoice ID stringparams- Optional pagination paramsopts- Per-request overrides
Returns
{:ok, %Response{data: %List{data: [%Invoice.LineItem{}, ...]}}}on success{:error, %LatticeStripe.Error{}}on failure
@spec list_line_items!(LatticeStripe.Client.t(), String.t(), map(), keyword()) :: LatticeStripe.Response.t()
Like list_line_items/4 but raises LatticeStripe.Error on failure.
@spec mark_uncollectible(LatticeStripe.Client.t(), String.t(), map(), keyword()) :: {:ok, t()} | {:error, LatticeStripe.Error.t()}
Marks an open invoice as uncollectible. Only callable on open invoices.
Parameters
client- A%LatticeStripe.Client{}structid- The invoice ID stringparams- Optional paramsopts- Per-request overrides
Returns
{:ok, %Invoice{status: :uncollectible}}on success{:error, %LatticeStripe.Error{}}on failure
@spec mark_uncollectible!(LatticeStripe.Client.t(), String.t(), map(), keyword()) :: t()
Like mark_uncollectible/4 but raises LatticeStripe.Error on failure.
@spec pay(LatticeStripe.Client.t(), String.t(), map(), keyword()) :: {:ok, t()} | {:error, LatticeStripe.Error.t()}
Pays an open invoice.
Accepts optional "paid_out_of_band", "payment_method", and "source" params.
Only callable on open invoices.
Parameters
client- A%LatticeStripe.Client{}structid- The invoice ID stringparams- Optional params (e.g.,%{"paid_out_of_band" => true})opts- Per-request overrides
Returns
{:ok, %Invoice{status: :paid}}on success{:error, %LatticeStripe.Error{}}on failure
@spec pay!(LatticeStripe.Client.t(), String.t(), map(), keyword()) :: t()
Like pay/4 but raises LatticeStripe.Error on failure.
@spec retrieve(LatticeStripe.Client.t(), String.t(), keyword()) :: {:ok, t()} | {:error, LatticeStripe.Error.t()}
Retrieves an Invoice by ID.
Sends GET /v1/invoices/:id and returns {:ok, %Invoice{}}.
Parameters
client- A%LatticeStripe.Client{}structid- The invoice ID string (e.g.,"in_123")opts- Per-request overrides
Returns
{:ok, %Invoice{}}on success{:error, %LatticeStripe.Error{}}on failure
@spec retrieve!(LatticeStripe.Client.t(), String.t(), keyword()) :: t()
Like retrieve/3 but raises LatticeStripe.Error on failure.
@spec search(LatticeStripe.Client.t(), map(), keyword()) :: {:ok, LatticeStripe.Response.t()} | {:error, LatticeStripe.Error.t()}
Searches for invoices matching a query.
Searchable Fields
created, currency, customer, last_finalization_error_code,
last_finalization_error_type, metadata, number, receipt_number,
status, subscription, total
Example
Invoice.search(client, %{"query" => "status:'open' AND customer:'cus_xxx'"})Eventual Consistency
Search results may not reflect changes made within the last ~1 second.
Resources that were recently created, updated, or deleted may not appear
in search results immediately. If you need real-time results for a specific
resource, use retrieve/3 instead.
Upcoming invoices (previews) are not searchable because they are not yet persisted objects.
Parameters
client- A%LatticeStripe.Client{}structparams- Map with at least"query"key (Stripe search query string)opts- Per-request overrides
Returns
{:ok, %Response{data: %List{data: [%Invoice{}, ...]}}}on success{:error, %LatticeStripe.Error{}}on failure
@spec search_stream!(LatticeStripe.Client.t(), map(), keyword()) :: Enumerable.t()
Returns a lazy stream of all invoices matching a search query (auto-pagination).
Emits individual %Invoice{} structs. Raises LatticeStripe.Error if any
page fetch fails.
Eventual Consistency
Search results may not reflect changes made within the last ~1 second.
Parameters
client- A%LatticeStripe.Client{}structparams- Map with at least"query"keyopts- Per-request overrides
Returns
An Enumerable.t() of %Invoice{} structs.
@spec send_invoice(LatticeStripe.Client.t(), String.t(), map(), keyword()) :: {:ok, t()} | {:error, LatticeStripe.Error.t()}
Sends an invoice to the customer via email.
Only applicable when collection_method: :send_invoice. Named send_invoice
to avoid conflict with Kernel.send/2.
Parameters
client- A%LatticeStripe.Client{}structid- The invoice ID stringparams- Optional paramsopts- Per-request overrides
Returns
{:ok, %Invoice{}}on success{:error, %LatticeStripe.Error{}}on failure
@spec send_invoice!(LatticeStripe.Client.t(), String.t(), map(), keyword()) :: t()
Like send_invoice/4 but raises LatticeStripe.Error on failure.
@spec stream!(LatticeStripe.Client.t(), map(), keyword()) :: Enumerable.t()
Returns a lazy stream of all Invoices matching the given params (auto-pagination).
Emits individual %Invoice{} structs, fetching additional pages as needed.
Raises LatticeStripe.Error if any page fetch fails.
Parameters
client- A%LatticeStripe.Client{}structparams- Filter params (e.g.,%{"customer" => "cus_123"})opts- Per-request overrides
Returns
An Enumerable.t() of %Invoice{} structs.
@spec stream_line_items!(LatticeStripe.Client.t(), String.t(), map(), keyword()) :: Enumerable.t()
Returns a lazy stream of all line items for a specific invoice (auto-pagination).
Emits individual %Invoice.LineItem{} structs, fetching additional pages as needed.
Raises LatticeStripe.Error if any page fetch fails.
Parameters
client- A%LatticeStripe.Client{}structinvoice_id- The invoice ID stringparams- Optional pagination paramsopts- Per-request overrides
Returns
An Enumerable.t() of %Invoice.LineItem{} structs.
@spec upcoming(LatticeStripe.Client.t(), map(), keyword()) :: {:ok, t()} | {:error, LatticeStripe.Error.t()}
Retrieves an upcoming invoice preview.
Returns a %Invoice{id: nil} representing what the next invoice will look like.
Useful for previewing proration impact before confirming a subscription change.
Parameters
Pass params as a map with keys like "customer", "subscription",
"subscription_items", "subscription_proration_behavior", etc.
Example
Invoice.upcoming(client, %{
"customer" => "cus_xxx",
"subscription" => "sub_xxx",
"subscription_items" => [%{"id" => "si_xxx", "price" => "price_new"}],
"subscription_proration_behavior" => "create_prorations"
})Deprecation Notice
Stripe is deprecating this endpoint in favor of create_preview/3.
Use create_preview/3 for new integrations.
Proration Guard
If client.require_explicit_proration is true, "proration_behavior" must
be present in params or {:error, %Error{type: :proration_required}} is returned.
@spec upcoming!(LatticeStripe.Client.t(), map(), keyword()) :: t()
Like upcoming/3 but raises LatticeStripe.Error on failure.
@spec upcoming_lines(LatticeStripe.Client.t(), map(), keyword()) :: {:ok, LatticeStripe.Response.t()} | {:error, LatticeStripe.Error.t()}
Retrieves line items for an upcoming invoice preview.
Returns paginated %Invoice.LineItem{} structs for the upcoming invoice.
Parameters
client- A%LatticeStripe.Client{}structparams- Map with"customer"and optional subscription paramsopts- Per-request overrides
Returns
{:ok, %Response{data: %List{data: [%Invoice.LineItem{}, ...]}}}on success{:error, %LatticeStripe.Error{}}on failure
@spec update(LatticeStripe.Client.t(), String.t(), map(), keyword()) :: {:ok, t()} | {:error, LatticeStripe.Error.t()}
Updates an Invoice by ID.
Sends POST /v1/invoices/:id with the given params and returns {:ok, %Invoice{}}.
Parameters
client- A%LatticeStripe.Client{}structid- The invoice ID stringparams- Map of fields to updateopts- Per-request overrides
Returns
{:ok, %Invoice{}}on success{:error, %LatticeStripe.Error{}}on failure
@spec update!(LatticeStripe.Client.t(), String.t(), map(), keyword()) :: t()
Like update/4 but raises LatticeStripe.Error on failure.
@spec void(LatticeStripe.Client.t(), String.t(), map(), keyword()) :: {:ok, t()} | {:error, LatticeStripe.Error.t()}
Voids an open invoice. Only callable on open invoices.
Parameters
client- A%LatticeStripe.Client{}structid- The invoice ID stringparams- Optional paramsopts- Per-request overrides
Returns
{:ok, %Invoice{status: :void}}on success{:error, %LatticeStripe.Error{}}on failure
@spec void!(LatticeStripe.Client.t(), String.t(), map(), keyword()) :: t()
Like void/4 but raises LatticeStripe.Error on failure.