Invoices can make several status transitions. The following table outlines the status transitions and their endpoints. It also lists the webhooks that are emitted by the endpoint, and the resulting status for each.
Finalize draft invoices
Invoices are initially created with
status=draft, and you can only edit them while they’re in this state. When an invoice is ready to be paid, you should finalize it. Finalizing an invoice sets
status=open on the invoice. You can manually finalize an invoice in the Dashboard or by using the /v1/invoices/:id/finalize API endpoint:
Finalizing an invoice does the following:
- It allows the invoice to be paid.
- It ensures that an invoice number is present.
- It makes certain properties immutable on the invoice.
- It creates an incomplete payment intent for the invoice.
- It generates a unique URL where someone can pay the invoice, and a link to download a PDF of the invoice.
Finalized invoice restrictions
After you finalize an invoice, you can’t change certain fields that pertain to the amount and customer. This is to satisfy the common tax-compliance requirement that finalized invoices be retained—as they were finalized—for a legally required minimum time period.
If you require updates to the invoice amount after it finalizes, use credit notes. Credit notes allow you to modify the invoice amount by specifying an adjustment in money owed by the customer. You can issue credit notes for any invoice in an
paid status. Finalizing the invoice copies the following customer fields to it and makes them immutable:
If you want to change a customer-related property on an invoice:
- Void the current invoice.
- Duplicate the voided invoice.
- Update the customer information on the new invoice.
Edit finalized invoices
Invoices aren’t updated after they finalize, so they won’t be updated to reflect successful payment. Customers can check the payment status with a receipt. You can only adjust finalized invoices by issuing credit notes, which provide an accounting paper trail of changes to the invoice amount.
In some jurisdictions, editing fields that modify the total amount due on an invoice could render the invoice invalid. These are typically fields associated with your account, customer, line items, or taxes.
Emails after finalization
By default, Stripe automatically sends invoices when you set collection_method to
send_invoice. Stripe does not email invoices in the following cases:
- When charged automatically.
- When automatic collection is turned off for the invoice.
- When the Send reminders if an invoice hasn’t been paid option is turned off.
Some payment methods require customer interaction to complete the payment—for example, a European card or bank transfer may require Strong Customer Authentication (SCA).
Use the payment_intent for the invoice to choose how to handle the response from the payment attempt, which may be either success or
When the status of the PaymentIntent is
requires_action you must have your user complete a 3D Secure authentication flow to complete the payment.
Instead of building this yourself, you can rely on Stripe to handle it for you. Enable reminder emails in the Dashboard so that Stripe can automatically send emails to your Customers whenever
requires_action occurs. These emails include a link to the Hosted Invoice Page, where a customer can perform all of the actions required to pay the invoice. Learn more about these emails and how to customize them on Sending email reminders.