Operations on Stripe InvoiceItem objects.
An InvoiceItem is a billable line that you create explicitly and attach to an invoice
before it is finalized. InvoiceItems live at /v1/invoiceitems and are mutatable while
the target invoice is in draft status.
InvoiceItem vs Invoice Line Item
InvoiceItem (this module) is a standalone resource you create explicitly at
/v1/invoiceitems. Mutatable while the target invoice is in draft status.
Invoice Line Item (LatticeStripe.Invoice.LineItem) is a read-only rendered row on
a finalized invoice, accessed via Invoice.list_line_items/4. Invoice line items have
il_... IDs; InvoiceItems have ii_... IDs.
InvoiceItems can only be added to invoices in draft status. Once finalized, line items are locked.
Operations not supported by the Stripe API
- search — The
/v1/invoiceitems/searchendpoint does not exist. Uselist/2with filters for discovery.
Usage
client = LatticeStripe.Client.new!(api_key: "sk_live_...", finch: MyApp.Finch)
# Create an InvoiceItem and attach it to a draft invoice
{:ok, item} = LatticeStripe.InvoiceItem.create(client, %{
"customer" => "cus_123",
"invoice" => "in_123",
"amount" => 5000,
"currency" => "usd",
"description" => "Professional services"
})
# Retrieve an InvoiceItem
{:ok, item} = LatticeStripe.InvoiceItem.retrieve(client, item.id)
# List InvoiceItems for a customer
{:ok, resp} = LatticeStripe.InvoiceItem.list(client, %{"customer" => "cus_123"})Stripe API Reference
See the Stripe InvoiceItem API for the full object reference and available parameters.
Summary
Functions
Creates a new InvoiceItem.
Like create/3 but raises LatticeStripe.Error on failure.
Deletes an InvoiceItem by ID.
Like delete/3 but raises LatticeStripe.Error on failure.
Converts a decoded Stripe API map to a %InvoiceItem{} struct.
Lists InvoiceItems with optional filters.
Like list/3 but raises LatticeStripe.Error on failure.
Retrieves an InvoiceItem by ID.
Like retrieve/3 but raises LatticeStripe.Error on failure.
Returns a lazy stream of all InvoiceItems matching the given params (auto-pagination).
Updates an InvoiceItem by ID.
Like update/4 but raises LatticeStripe.Error on failure.
Types
@type t() :: %LatticeStripe.InvoiceItem{ amount: integer() | nil, currency: String.t() | nil, customer: LatticeStripe.Customer.t() | String.t() | nil, date: integer() | nil, deleted: boolean(), description: String.t() | nil, discountable: boolean() | nil, discounts: list() | nil, extra: map(), id: String.t() | nil, invoice: LatticeStripe.Invoice.t() | String.t() | nil, livemode: boolean() | nil, metadata: map() | nil, object: String.t(), period: LatticeStripe.InvoiceItem.Period.t() | nil, plan: map() | nil, price: map() | nil, proration: boolean() | nil, proration_details: map() | nil, quantity: integer() | nil, subscription: LatticeStripe.Subscription.t() | String.t() | nil, subscription_item: String.t() | nil, tax_rates: list() | nil, test_clock: String.t() | nil, unit_amount: integer() | nil, unit_amount_decimal: String.t() | nil, unit_amount_excluding_tax: String.t() | nil }
A Stripe InvoiceItem object.
See the Stripe InvoiceItem API for field definitions.
Functions
@spec create(LatticeStripe.Client.t(), map(), keyword()) :: {:ok, t()} | {:error, LatticeStripe.Error.t()}
Creates a new InvoiceItem.
Sends POST /v1/invoiceitems with the given params and returns {:ok, %InvoiceItem{}}.
Only applicable to draft invoices. Once an invoice is finalized, its line items are locked.
Parameters
client- A%LatticeStripe.Client{}structparams- Map of InvoiceItem attributes. Common params:"customer"- Customer ID (required)"amount"- Amount in smallest currency unit"currency"- Three-letter ISO currency code"invoice"- Invoice ID to attach to (must be in draft status)"description"- Human-readable description
opts- Per-request overrides (e.g.,[idempotency_key: "..."])
Returns
{:ok, %InvoiceItem{}}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 delete(LatticeStripe.Client.t(), String.t(), keyword()) :: {:ok, t()} | {:error, LatticeStripe.Error.t()}
Deletes an InvoiceItem by ID.
Sends DELETE /v1/invoiceitems/:id and returns {:ok, %InvoiceItem{}}.
Only applicable to draft invoices. Once an invoice is finalized, its line items are locked.
Parameters
client- A%LatticeStripe.Client{}structid- The InvoiceItem ID stringopts- Per-request overrides
Returns
{:ok, %InvoiceItem{}}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.
Converts a decoded Stripe API map to a %InvoiceItem{} struct.
Maps all known Stripe InvoiceItem fields. Any unrecognized fields are collected
into the extra map so no data is silently lost.
Parses the period field into a %LatticeStripe.InvoiceItem.Period{} struct.
Example
item = LatticeStripe.InvoiceItem.from_map(%{
"id" => "ii_123",
"amount" => 5000,
"currency" => "usd",
"customer" => "cus_123",
"object" => "invoiceitem"
})@spec list(LatticeStripe.Client.t(), map(), keyword()) :: {:ok, LatticeStripe.Response.t()} | {:error, LatticeStripe.Error.t()}
Lists InvoiceItems with optional filters.
Sends GET /v1/invoiceitems and returns {:ok, %Response{data: %List{}}} with
typed %InvoiceItem{} items.
Parameters
client- A%LatticeStripe.Client{}structparams- Filter params (e.g.,%{"customer" => "cus_123", "invoice" => "in_123"})opts- Per-request overrides
Returns
{:ok, %Response{data: %List{data: [%InvoiceItem{}, ...]}}}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 retrieve(LatticeStripe.Client.t(), String.t(), keyword()) :: {:ok, t()} | {:error, LatticeStripe.Error.t()}
Retrieves an InvoiceItem by ID.
Sends GET /v1/invoiceitems/:id and returns {:ok, %InvoiceItem{}}.
Parameters
client- A%LatticeStripe.Client{}structid- The InvoiceItem ID string (e.g.,"ii_123")opts- Per-request overrides
Returns
{:ok, %InvoiceItem{}}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 stream!(LatticeStripe.Client.t(), map(), keyword()) :: Enumerable.t()
Returns a lazy stream of all InvoiceItems matching the given params (auto-pagination).
Emits individual %InvoiceItem{} 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 %InvoiceItem{} structs.
@spec update(LatticeStripe.Client.t(), String.t(), map(), keyword()) :: {:ok, t()} | {:error, LatticeStripe.Error.t()}
Updates an InvoiceItem by ID.
Sends POST /v1/invoiceitems/:id with the given params and returns {:ok, %InvoiceItem{}}.
Only applicable to draft invoices. Once an invoice is finalized, its line items are locked.
Parameters
client- A%LatticeStripe.Client{}structid- The InvoiceItem ID stringparams- Map of fields to updateopts- Per-request overrides
Returns
{:ok, %InvoiceItem{}}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.