Invoices

Invoices are statements of amounts owed by a customer, and are either generated one-off, or generated periodically from a subscription.

They contain invoice items, and proration adjustments that may be caused by subscription upgrades/downgrades (if necessary).

If your invoice is configured to be billed through automatic charges, Stripe automatically finalizes your invoice and attempts payment. Note that finalizing the invoice, when automatic, does not happen immediately as the invoice is created. Stripe waits until one hour after the last webhook was successfully sent (or the last webhook timed out after failing). If you (and the platforms you may have connected to) have no webhooks configured, Stripe waits one hour after creation to finalize the invoice.

If your invoice is configured to be billed by sending an email, then based on your email settings, Stripe will email the invoice to your customer and await payment. These emails can contain a link to a hosted page to pay the invoice.

Stripe applies any customer credit on the account before determining the amount due for the invoice (i.e., the amount that will be actually charged). If the amount due for the invoice is less than Stripe’s minimum allowed charge per currency, the invoice is automatically marked paid, and we add the amount due to the customer’s credit balance which is applied to the next invoice.

More details on the customer’s credit balance are here.

Related guide: Send invoices to customers

Was this section helpful? Yes No

Create a preview invoice

POST / v1 / invoices / create_preview

Create an invoice

POST / v1 / invoices

Update an invoice

POST / v1 / invoices /:id

Retrieve an invoice

GET / v1 / invoices /:id

List all invoices

GET / v1 / invoices

Delete a draft invoice

DELETE / v1 / invoices /:id

Attach a payment to an Invoice

POST / v1 / invoices /:id / attach_payment

Finalize an invoice

POST / v1 / invoices /:id / finalize

Mark an invoice as uncollectible

POST / v1 / invoices /:id / mark_uncollectible

Pay an invoice

POST / v1 / invoices /:id / pay

Search invoices

GET / v1 / invoices / search

Send an invoice for manual payment

POST / v1 / invoices /:id / send

Void an invoice

POST / v1 / invoices /:id / void

The Invoice object

Attributes

• id string Unique identifier for the object. For preview invoices created using the create preview endpoint, this id will be prefixed with upcoming_in.
• auto _ advance boolean Controls whether Stripe performs automatic collection of the invoice. If false, the invoice’s state doesn’t automatically advance without an explicit action.
• automatic _ tax object Settings and latest results for automatic tax lookup for this invoice.
• collection _ method enum Either charge_automatically, or send_invoice. When charging automatically, Stripe will attempt to pay this invoice using the default source attached to the customer. When sending an invoice, Stripe will email this invoice to the customer with payment instructions. Possible enum values charge_automatically Attempt payment using the default source attached to the customer. send_invoice Email payment instructions to the customer.
• confirmation _ secret nullable object Includable The confirmation secret associated with this invoice. Currently, this contains the client_secret of the PaymentIntent that Stripe creates during invoice finalization.
• currency enum Three-letter ISO currency code, in lowercase. Must be a supported currency.
• customer string Expandable The ID of the customer to bill.
• customer _ account nullable string The ID of the account representing the customer to bill.
• description nullable string An arbitrary string attached to the object. Often useful for displaying to users. Referenced as ‘memo’ in the Dashboard.
• hosted _ invoice _ url nullable string The URL for the hosted invoice page, which allows customers to view and pay an invoice. If the invoice has not been finalized yet, this will be null.
• lines object The individual line items that make up the invoice. lines is sorted as follows: (1) pending invoice items (including prorations) in reverse chronological order, (2) subscription items in reverse chronological order, and (3) invoice items added after invoice creation in chronological order.
• metadata nullable map Set of key-value pairs that you can attach to an object. This can be useful for storing additional information about the object in a structured format.
• parent nullable object The parent that generated this invoice
• payments object Includable Payments for this invoice. Use invoice payment to get more details.
• period _ end timestamp The latest timestamp at which invoice items can be associated with this invoice. Use the line item period to get the service period for each price.
• period _ start timestamp The earliest timestamp at which invoice items can be associated with this invoice. Use the line item period to get the service period for each price.
• status nullable enum The status of the invoice, one of draft, open, paid, uncollectible, or void. Learn more
• total integer Total after discounts and taxes.

More attributes

• object string, value is "invoice"
• account _ country nullable string
• account _ name nullable string
• account _ tax _ ids nullable array of strings Expandable
• amount _ due integer
• amount _ overpaid integer
• amount _ paid integer
• amount _ paid _ off _ stripe integer Includable
• amount _ remaining integer
• amount _ shipping integer
• application nullable string Expandable Connect only
• attempt _ count integer
• attempted boolean
• automatically _ finalizes _ at nullable timestamp
• billing _ reason nullable enum
• created timestamp
• custom _ fields nullable array of objects
• customer _ address nullable object
• customer _ email nullable string
• customer _ name nullable string
• customer _ phone nullable string
• customer _ shipping nullable object
• customer _ tax _ exempt nullable enum
• customer _ tax _ ids nullable array of objects
• default _ payment _ method nullable string Expandable
• default _ source nullable string Expandable
• default _ tax _ rates array of objects
• discounts array of strings Expandable
• due _ date nullable timestamp
• effective _ at nullable timestamp
• ending _ balance nullable integer
• footer nullable string
• from _ invoice nullable object
• invoice _ pdf nullable string
• issuer object Connect only
• last _ finalization _ error nullable object
• latest _ revision nullable string Expandable
• livemode boolean
• next _ payment _ attempt nullable timestamp
• number nullable string
• on _ behalf _ of nullable string Expandable Connect only
• payment _ settings object
• post _ payment _ credit _ notes _ amount integer
• pre _ payment _ credit _ notes _ amount integer
• receipt _ number nullable string
• rendering nullable object
• shipping _ cost nullable object
• shipping _ details nullable object
• starting _ balance integer
• statement _ descriptor nullable string
• status _ details nullable object
• status _ transitions object
• subtotal integer
• subtotal _ excluding _ tax nullable integer
• test _ clock nullable string Expandable
• threshold _ reason nullable object
• total _ discount _ amounts nullable array of objects
• total _ excluding _ tax nullable integer
• total _ pretax _ credit _ amounts nullable array of objects
• total _ taxes nullable array of objects
• webhooks _ delivered _ at nullable timestamp

The Invoice object

Create a preview invoice

POST / v1 / invoices / create_preview

At any time, you can preview the upcoming invoice for a subscription or subscription schedule. This will show you all the charges that are pending, including subscription renewal charges, invoice item charges, etc. It will also show you any discounts that are applicable to the invoice.

You can also preview the effects of creating or updating a subscription or subscription schedule, including a preview of any prorations that will take place. To ensure that the actual proration is calculated exactly the same as the previewed proration, you should pass the subscription_details.proration_date parameter when doing the actual subscription update.

The recommended way to get only the prorations being previewed on the invoice is to consider line items where parent.subscription_item_details.proration is true.

Note that when you are viewing an upcoming invoice, you are simply viewing a preview – the invoice has not yet been created. As such, the upcoming invoice will not show up in invoice listing calls, and you cannot use the API to pay or edit the invoice. If you want to change the amount that your customer will be billed, you can add, remove, or update pending invoice items, or update the customer’s discount.

Note: Currency conversion calculations use the latest exchange rates. Exchange rates may vary between the time of the preview and the time of the actual invoice creation. Learn more

Parameters

• automatic _ tax object Settings for automatic tax lookup for this invoice preview.
• customer string The identifier of the customer whose upcoming invoice you’re retrieving. If automatic_tax is enabled then one of customer, customer_details, subscription, or schedule must be set.
• customer _ account string The identifier of the account representing the customer whose upcoming invoice you’re retrieving. If automatic_tax is enabled then one of customer, customer_account, customer_details, subscription, or schedule must be set.
• subscription string The identifier of the subscription for which you’d like to retrieve the upcoming invoice. If not provided, but a subscription_details.items is provided, you will preview creating a subscription with those items. If neither subscription nor subscription_details.items is provided, you will retrieve the next upcoming invoice from among the customer’s subscriptions.

More parameters

• currency enum
• customer _ details object
• discounts array of objects
• invoice _ items array of objects
• issuer object Connect only
• on _ behalf _ of string Connect only
• preview _ mode enum
• schedule string
• schedule _ details object
• subscription _ details object

Returns

Returns an invoice if valid customer information is provided. Raises an error otherwise.

Response