hot.dev/stripe / ::stripe::invoices

Invoices and invoice items: drafts, finalization, payment, sending, voiding, previews, and search. See https://docs.stripe.com/api/invoices.

Functions

create-invoice

fn (request: CreateInvoiceRequest): Map
fn (request: CreateInvoiceRequest, options: ::stripe::api/RequestOptions | Map): Map

POST /v1/invoices - Create a draft invoice. Pending invoice items for the customer are included only with pending_invoice_items_behavior: "include" (the default is "exclude"); or attach items to the draft afterwards with create-invoice-item(..., invoice.id). Set auto_advance: true to let Stripe finalize and collect it automatically.

Example

::invoices ::stripe::invoices

invoice ::invoices/create-invoice(::invoices/CreateInvoiceRequest({
  customer: "cus_...",
  collection_method: "send_invoice",
  days_until_due: 30
}))
::invoices/create-invoice-item(::invoices/CreateInvoiceItemRequest({
  customer: "cus_...",
  invoice: invoice.id,
  amount: 2500,
  currency: "usd",
  description: "Consulting"
}))
::invoices/finalize-invoice(invoice.id)
::invoices/send-invoice(invoice.id)

create-invoice-item

fn (request: CreateInvoiceItemRequest): Map
fn (request: CreateInvoiceItemRequest, options: ::stripe::api/RequestOptions | Map): Map
fn (customer: Str, amount: Int, currency: Str, description: Str): Map
fn (customer: Str, amount: Int, currency: Str, description: Str, options: ::stripe::api/RequestOptions | Map): Map
fn (customer: Str, amount: Int, currency: Str, description: Str, invoice: Str): Map
fn (customer: Str, amount: Int, currency: Str, description: Str, invoice: Str, options: ::stripe::api/RequestOptions | Map): Map

POST /v1/invoiceitems - Add a one-off line to a customer's next invoice, or to a specific draft with invoice. Give either a flat amount (smallest currency unit), or pricing: {price: "price_..."} with a quantity (since 2025-03-31.basil, price moved under pricing).

The 4- and 5-arity forms are shortcuts for a flat-amount item: (customer, amount, currency, description) and the same with a draft invoice ID.

Example

::invoices ::stripe::invoices

::invoices/create-invoice-item("cus_...", 2500, "usd", "Consulting")
::invoices/create-invoice-item(::invoices/CreateInvoiceItemRequest({
  customer: "cus_...",
  pricing: {price: "price_..."},
  quantity: 2
}))

create-invoice-preview

fn (params: Map): Map
fn (params: Map, opts: Map): Map

POST /v1/invoices/create_preview - Preview the next invoice for a customer or subscription without creating it, e.g. to show the prorated cost of a plan change. params takes the API's fields directly (customer, subscription, subscription_details: {items, proration_date}, ...).

Example

::invoices ::stripe::invoices

preview ::invoices/create-invoice-preview({
  customer: "cus_...",
  subscription: "sub_...",
  subscription_details: {items: [{id: "si_...", price: "price_pro"}]}
})
preview.amount_due

delete-invoice

fn (invoice: Str): Map
fn (invoice: Str, opts: Map): Map

DELETE /v1/invoices/{invoice} - Delete a draft invoice. Finalized invoices must be voided instead.

delete-invoice-item

fn (invoice-item: Str): Map
fn (invoice-item: Str, opts: Map): Map

DELETE /v1/invoiceitems/{invoiceitem} - Delete an invoice item that isn't yet on a finalized invoice.

finalize-invoice

fn (invoice: Str): Map
fn (invoice: Str, request: FinalizeInvoiceRequest): Map
fn (invoice: Str, request: FinalizeInvoiceRequest, options: ::stripe::api/RequestOptions | Map): Map

POST /v1/invoices/{invoice}/finalize - Finalize a draft invoice so it can be paid. auto_advance: false finalizes without letting Stripe attempt collection automatically.

get-invoice

fn (invoice: Str): Map
fn (invoice: Str, params: Map): Map
fn (invoice: Str, params: Map, opts: Map): Map

GET /v1/invoices/{invoice} - Retrieve an invoice by ID. Optional params such as {expand: ["payments"]}. The subscription an invoice belongs to is at parent.subscription_details.subscription; the client secret for paying it client-side is confirmation_secret.client_secret.

list-invoice-lines

fn (invoice: Str): Map
fn (invoice: Str, params: Map): Map
fn (invoice: Str, params: Map, opts: Map): Map

GET /v1/invoices/{invoice}/lines - List an invoice's line items. Optional params: limit, starting_after, ending_before.

list-invoices

fn (): Map
fn (request: ListInvoicesRequest): Map
fn (request: ListInvoicesRequest, opts: Map): Map

GET /v1/invoices - List invoices, most recent first. Filter by customer, subscription, or status ("draft", "open", "paid", "uncollectible", "void").

mark-invoice-uncollectible

fn (invoice: Str): Map
fn (invoice: Str, options: ::stripe::api/RequestOptions | Map): Map

POST /v1/invoices/{invoice}/mark_uncollectible - Mark an open invoice as uncollectible (bad debt). It can still be paid later.

pay-invoice

fn (invoice: Str): Map
fn (invoice: Str, request: PayInvoiceRequest): Map
fn (invoice: Str, request: PayInvoiceRequest, options: ::stripe::api/RequestOptions | Map): Map

POST /v1/invoices/{invoice}/pay - Attempt payment on an open invoice now, outside the normal collection schedule. Pass payment_method to charge a specific method, off_session: false when the customer is present (allows 3DS), or paid_out_of_band: true to mark it paid outside Stripe. Pass an idempotency key so a retry never charges twice.

Example

::invoices ::stripe::invoices

paid ::invoices/pay-invoice("in_...",
  ::invoices/PayInvoiceRequest({payment_method: "pm_..."}),
  ::stripe::api/RequestOptions({idempotency_key: "in_123-pay-1"}))
paid.status  // => "paid"

search-invoices

fn (query: Str): Map
fn (query: Str, params: Map): Map
fn (query: Str, params: Map, opts: Map): Map

GET /v1/invoices/search - Search invoices with Stripe's search query language, e.g. status:"open" AND customer:"cus_...". Pass next_page back as page in params to continue.

send-invoice

fn (invoice: Str): Map
fn (invoice: Str, options: ::stripe::api/RequestOptions | Map): Map

POST /v1/invoices/{invoice}/send - Email an invoice to the customer for manual payment. The invoice must use collection_method: "send_invoice". In test mode no email is actually sent.

update-invoice

fn (invoice: Str, request: UpdateInvoiceRequest): Map
fn (invoice: Str, request: UpdateInvoiceRequest, options: ::stripe::api/RequestOptions | Map): Map

POST /v1/invoices/{invoice} - Update an invoice. Most fields can only change while it is a draft; metadata, auto_advance and a few others stay editable after finalization.

void-invoice

fn (invoice: Str): Map
fn (invoice: Str, options: ::stripe::api/RequestOptions | Map): Map

POST /v1/invoices/{invoice}/void - Void a finalized invoice. Voiding is irreversible and similar to deletion for accounting purposes.

Types

CreateInvoiceItemRequest

CreateInvoiceItemRequest type {
    customer: Str?,
    invoice: Str?,
    subscription: Str?,
    amount: Int?,
    currency: Str?,
    description: Str?,
    quantity: Int?,
    pricing: Map?,
    price_data: Map?,
    unit_amount_decimal: Str?,
    period: Map?,
    discountable: Bool?,
    discounts: Vec<Map>?,
    tax_rates: Vec<Str>?,
    tax_behavior: Str?,
    tax_code: Str?,
    metadata: Map?,
    expand: Vec<Str>?
}

CreateInvoiceRequest

CreateInvoiceRequest type {
    customer: Str?,
    subscription: Str?,
    auto_advance: Bool?,
    collection_method: Str?,
    days_until_due: Int?,
    due_date: Int?,
    description: Str?,
    metadata: Map?,
    currency: Str?,
    automatic_tax: Map?,
    default_payment_method: Str?,
    default_tax_rates: Vec<Str>?,
    discounts: Vec<Map>?,
    custom_fields: Vec<Map>?,
    footer: Str?,
    pending_invoice_items_behavior: Str?,
    payment_settings: Map?,
    expand: Vec<Str>?
}

FinalizeInvoiceRequest

FinalizeInvoiceRequest type {
    auto_advance: Bool?,
    expand: Vec<Str>?
}

ListInvoicesRequest

ListInvoicesRequest type {
    customer: Str?,
    subscription: Str?,
    status: Str?,
    collection_method: Str?,
    created: Any?,
    due_date: Any?,
    limit: Int?,
    starting_after: Str?,
    ending_before: Str?,
    expand: Vec<Str>?
}

PayInvoiceRequest

PayInvoiceRequest type {
    payment_method: Str?,
    off_session: Bool?,
    forgive: Bool?,
    paid_out_of_band: Bool?,
    mandate: Str?,
    source: Str?,
    expand: Vec<Str>?
}

UpdateInvoiceRequest

UpdateInvoiceRequest type {
    description: Str?,
    metadata: Map?,
    auto_advance: Bool?,
    collection_method: Str?,
    days_until_due: Int?,
    due_date: Int?,
    default_payment_method: Str?,
    discounts: Any?,
    custom_fields: Any?,
    footer: Str?,
    payment_settings: Map?,
    expand: Vec<Str>?
}