Skip to content
Create account
or
Sign in
The Stripe Docs logo
/
Ask AI
Create account
Sign in
Get started
Payments
Finance automation
Platforms and marketplaces
Money management
Developer tools
Get started
Payments
Finance automation
Get started
Payments
Finance automation
Platforms and marketplaces
Money management
Overview
Billing
    Overview
    About the Billing APIs
    Subscriptions
    Invoicing
      Overview
      API quickstart
      Integrate with the API
      Invoicing without code
      Invoice lifecycle
      Preview invoices
      Edit invoices
      Schedule invoice finalization
      Status transitions and finalization
      Send customer emails
      Generate credit notes
      Invoice customers
      Customers
      Customer credit balance
      Customer tax IDs
      Invoice payments
      Hosted Invoice Page
      Create invoice payment plans
      Payment methods for invoices
      Automated collections
      Invoice customization
      Customize invoices
      Invoice rendering templates
      Group invoice line items
      Summarize line items
      Global invoicing
      Best practices
      Multi-currency customers
      Other invoicing features
      Products and prices
      Manage bulk invoice line items
      Taxes
    Usage-based billing
    Connect and Billing
    Tax and Billing
    Quotes
    Revenue recovery
    Automations
    Scripts
    Revenue recognition
    Customer management
    Entitlements
    Test your integration
Tax
Reporting
Data
Startup incorporation
HomeFinance automationBillingInvoicing

Status transitions and finalization

Learn about invoice status transitions and finalization.

Copy page

The following graphic shows the different ways that an invoice can transition from status to status:

Status transitions and finalization

Transitions and endpoints

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:

StatusAPI EndpointEmitted WebhookEnd Status
draftDELETE /v1/invoices/:idinvoice.deleted(Deleted)
draftPOST /v1/invoices/:id/finalizeinvoice.finalizedopen
openPOST /v1/invoices/:id/payinvoice.paidpaid
openPOST /v1/invoices/:id/payinvoice.payment_failedopen
openPOST /v1/invoices/:id/sendinvoice.sentopen
openPOST /v1/invoices/:id/voidinvoice.voidedvoid
openPOST /v1/invoices/:id/mark_uncollectibleinvoice.marked_uncollectibleuncollectible
uncollectiblePOST /v1/invoices/:id/payinvoice.paidpaid
uncollectiblePOST /v1/invoices/:id/payinvoice.payment_faileduncollectible
uncollectiblePOST /v1/invoices/:id/voidinvoice.voidedvoid

Finalize draft invoices

When you enable automatic collection, Stripe automatically finalizes, and begins automatic collection of the invoice. We wait 1 hour after receiving a successful response to the invoice.created event from all listening webhooks before attempting payment. If we don’t receive a successful response within 72 hours, we attempt to finalize and send the invoice. You can configure a longer grace period.

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, finalize it. Finalizing an invoice sets status=open on the invoice. You can manually finalize an invoice in the Dashboard or by using the Finalize endpoint. If you’ve configured webhook endpoints, you receive an invoice.finalized event when an invoice finalizes.

Command Line
cURL
curl -X POST https://api.stripe.com/v1/invoices/
{{INVOICE_ID}}
/finalize
\ -u "
sk_test_BQokikJOvBiI2HlWgH4olfQ2
:"

In live mode, if your webhook endpoint doesn’t respond properly, Stripe continues retrying the webhook notification for up to 3 days with an exponential back off. In a sandbox, we retry three times over a few hours. During that time, we won’t attempt to charge the customer unless we receive a successful response. We also send you an email to notify you that the webhook is failing.

This behavior applies to all webhook endpoints defined on your account, including cases where a Connect application or other third-party service is having trouble handling incoming webhooks.

You can configure a longer grace period.

Post-finalization

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.

Caution

If an invoice isn’t finalized, you can’t collect payment.

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.

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. It’s your responsibility to make sure that the invoices you create comply with all applicable laws.

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 open or paid status. Finalizing the invoice copies the following customer fields to it and makes them immutable:

  • invoice.customer_address
  • invoice.customer_email
  • invoice.customer_name
  • invoice.customer_phone
  • invoice.customer_shipping
  • invoice.customer_tax_exempt
  • invoice.customer_tax_ids

If you want to change a customer-related property on an invoice:

  1. Void the current invoice.
  2. Duplicate the voided invoice.
  3. Update the customer information on the new invoice.

Emails after finalization

By default, Stripe automatically sends invoices when you set collection_method to send_invoice. Stripe doesn’t email invoices in the following cases:

  • When charged automatically.
  • When automatic collection is turned off for the invoice.
  • When the Email finalized invoices to customers option is turned off.

Note

If you turn off the Email finalized invoices to customers option, automatic or manual finalization doesn’t send an invoice.

Asynchronous payments

Payments Intents API

For more details on using the Payment Intents API to complete 3D Secure authentication, refer to the 3D Secure guide.

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 invoice’s payment_intent parameter to choose how to handle the response from the payment attempt, which may be either success or requires_action.

When the status of the PaymentIntent is requires_action, you must have your user complete a 3D Secure authentication 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. To learn more about these emails and how to customize them, see Sending email reminders.

Was this page helpful?
YesNo
Need help? Contact Support.
Join our early access program.
Check out our changelog.
Questions? Contact Sales.
LLM? Read llms.txt.
Powered by Markdoc