Invoices API updates
Stripe has recently improved the clarity and expressiveness of the statuses that an invoice can have.
In previous versions of the Stripe API, Invoices didn’t have statuses. Instead, there was a series of booleans, like closed
, paid
, and forgiven
.
We’ve introduced statuses on invoices to better correlate Stripe invoices with finance workflows. Now, all Invoice objects have a status
property. The status
field can have the values draft
, open
, paid
, void
, and uncollectible
.
- The
draft
status indicates that an invoice is mutable. - The
open
status indicates that the invoice has been finalized, is no longer mutable, and is ready for payment. - The
paid
status indicates that the invoice has been paid in full. - The
void
status indicates that the invoice is no longer valid. - The
uncollectible
status indicates that the invoice is very unlikely to be paid, and could be considered a bad debt.
For more details on these statuses, and the transitions between them, see the invoicing guide.
Sample invoice timelines![](https://b.stripecdn.com/docs-statics-srv/assets/fcc3a1c24df6fcffface6110ca4963de.svg)
This section presents sample timelines for both one-off and subscription invoices, showing the statuses that both types of invoices can proceed through.
One-off invoice example![](https://b.stripecdn.com/docs-statics-srv/assets/fcc3a1c24df6fcffface6110ca4963de.svg)
Here is an example timeline that a one-off invoice could go through. This sequence of events presents no changes from the pre-existing invoicing timeline, except that Stripe now exposes a status
field to more clearly represent an invoice’s status.
- Nov 16: Through the API, you might create an invoice that represents shipping 12 widgets to a customer. Stripe sends an
invoice.
webhook, notifying you of the recently-created invoice. Looking at the API, you see that the invoice hascreated status='draft'
. - Nov 26: After reviewing the invoice, an accountant finalizes the invoice using the Stripe Dashboard. While the invoice is being finalized, its status is updated to
status='open'
and thefinalized_
field is set. Stripe sends anat invoice.
webhook, notifying you that the invoice was finalized.finalized - Nov 26: Seconds later, Stripe emails the invoice, and begins retries. To help your CRM system keep track of when invoices are sent, Stripe sends an
invoice.
webhook each time it’s sent.sent - Dec 01: Your customer clicks the link in the email and pays the invoice using a Hosted Invoice Payment page. Unfortunately, they pay with an expired credit card. Their payment fails, and Stripe sends the
invoice.
webhook notifying you of this failure.payment_ failed - Dec 03: With an updated credit card, the customer tries again. This time, the payment succeeds! Stripe sends the
invoice.
webhook notifying you of this success, saves the card, and sets the invoice topaid status='paid'
. If configured, Stripe also immediately emails your customer a receipt showing that the invoice was paid.
Subscription invoice example![](https://b.stripecdn.com/docs-statics-srv/assets/fcc3a1c24df6fcffface6110ca4963de.svg)
Here is an example timeline for an invoice generated by a subscription.
- Nov 13: Through the dashboard, you create a recurring subscription for a customer, configured for charging automatically. The subscription has a 20 day trial, so the first invoice will be in 20 days (Dec 03). Stripe sends a
customer.
webhook.subscription. created
- Nov 30: Three days before the trial ends, Stripe sends a
customer.
webhook. Three days before charging the credit card would be a good time to send a trial reminder email.subscription. trial_ will_ end
- Dec 03: At the end of the trial, a
status='draft'
invoice is created. Stripe sends aninvoice.
webhook, notifying you of the recently-created invoice.created - Dec 03: Approximately one hour later, the invoice is automatically finalized. This entails updating the
status
as'open'
, settingfinalized_
, and sending anat invoice.
webhook.finalized - Dec 03: Soon after, Stripe attempts to charge the customer’s card on file. The customer’s payment succeeds. Stripe sends the
invoice.
webhook to notify you of this success, and sets the invoice topaid status='paid'
.
New API methods![](https://b.stripecdn.com/docs-statics-srv/assets/fcc3a1c24df6fcffface6110ca4963de.svg)
Stripe has released a suite of new APIs for managing the status of an invoice. The new options, detailed in the upgrade checklist below, are:
- Send an invoice: Stripe automatically sends and re-sends invoices through email. This endpoint, available in the Stripe API, allows you to send the invoice to your customer whenever you want.
- Finalize an invoice: In the example above, the accountant finalized the invoice using the Stripe Dashboard. This functionality is also available in the Stripe API.
- Void an invoice: Once an invoice has been finalized, it can’t be deleted. Voiding is used to indicate that the invoice was issued in error. You could consider voiding an invoice with an error in your company’s name, and then creating an entirely new invoice to replace it.
- Delete a draft invoice: This action is applicable only to draft invoices. Deleted invoices aren’t visible through your Dashboard or the API. They cannot be un-deleted.
- Mark an invoice uncollectible: Your accounting department might want to maintain a register of “doubtful debts” - that is, a list of invoices that are deemed to be uncollectible. You can use this API to tag applicable invoices.
Upgrade checklist ![](https://b.stripecdn.com/docs-statics-srv/assets/fcc3a1c24df6fcffface6110ca4963de.svg)
The following sections list functional changes in the Invoice
object, and in invoice-related webhooks.
Invoice
object![](https://b.stripecdn.com/docs-statics-srv/assets/fcc3a1c24df6fcffface6110ca4963de.svg)
Stripe has added several fields to the Invoice
object to help users better understand its status and behavior.
finalized_ at
The new finalized_
field indicates the time at which the invoice was finalized. This is available for requests made on all API versions.
status
The new status
field is available for requests made on all API versions. This replaces many booleans on the invoice, such as:
- For requests made with the 2018-11-08 version and later, the
paid=true
boolean is removed. Check for the equivalentstatus='paid'
instead. - For requests made with the 2018-11-08 version and later, the
forgiven=true
boolean is removed. Check for the equivalentstatus='uncollectible'
instead.
auto_ advance
The new auto_
field indicates whether automatic collection is active. For the 'draft'
and 'open'
statuses, the auto_
field can be updated. Otherwise, auto_
will always be false
.
When auto_
, Stripe will not:
- Automatically issue draft invoices
- Automatically send the first (or reminder) emails for
collection_
invoicesmethod='send_ invoice' - Automatically attempt the first (or retry) payments for
collection_
invoicesmethod='charge_ automatically'
Even with auto_
, Stripe automatically reconciles inbound credit transfers. If a transfer references an invoice, the credit transfer is reconciled to that invoice. If an invoice isn’t provided, Stripe searches for unpaid invoices and tries to pay them.
For invoices with the statuses 'uncollectible'
, 'void'
, and 'paid'
, the auto_
field is always false
.
On versions prior to 2018-11-08, the closed
field is still present, and equal to the inverse of auto_
. For example, auto_
is equivalent to closed=false
(and vice versa). Invoices created using prior API versions will continue to default to closed=false
.
Webhooks![](https://b.stripecdn.com/docs-statics-srv/assets/fcc3a1c24df6fcffface6110ca4963de.svg)
With this update, we’ve introduced three new webhooks:
invoice.
: Sent when an invoice is finalized.finalized invoice.
: Sent when an invoice is voided.voided invoice.
: Sent when an invoice is marked uncollectible.marked_ uncollectible
The existing invoice.
webhook is sent upon creating an invoice. If your webhook handler needs to differentiate between one-off invoices and invoices generated by a subscription, check for the existence of the invoice.
property in the webhook body.
These pre-existing webhooks are unchanged:
invoice.
: Sent when an invoice is emailed to a user, either automatically, through the API, or in the Dashboard.sent invoice.
: Sent when adeleted draft
invoice is deleted, either through the API or in the Dashboard.invoice.
orpaid invoice.
: Sent when an attempt to pay an invoice succeeds or fails.payment_ failed