Edit invoices

To begin the post-finalization revision process, use the Create endpoint with the from_invoice parameter. This request creates a new draft invoice that’s linked back to the original as a revision. It also duplicates all of the invoice line items associated with the invoice. It doesn’t, however, duplicate any invoice credit notes, which could result in a change to the amount due. Also, this request doesn’t pull in pending invoice items the way invoice creation does.

curl https://api.stripe.com/v1/invoices \
  -u "
sk_test_BQokikJOvBiI2HlWgH4olfQ2
:" \
  -d "from_invoice[invoice]"={{ORIGINAL_INVOICE_ID}} \
  -d "from_invoice[action]"=revision

After you submit a request to create an invoice using the from_invoice parameter, Stripe responds with the following:

{
  "id": "{{FIRST_REVISION_INVOICE_ID}}",
  "status": "draft",
  "from_invoice": {
    "invoice": "{{ORIGINAL_INVOICE_ID}}",
    "action": "revision",
  },
}

This new draft invoice has mostly identical fields to the original invoice, with a few exceptions:

• If you updated the invoice’s customer after finalizing the original invoice, the new invoice uses the updated customer information. Note that, if you use automatic tax, this might cause a recalculation of the tax amount.
• If the original invoice had auto_advance == true, the revision invoice has it set to false.
• The revision invoice’s starting_balance and amount_due reflects any customer balance applied to the original invoice plus any additional balance that is available on the customer object.

From here, you can make additional changes to the invoice like you would any draft. The following example updates the description of the invoice:

curl https://api.stripe.com/v1/invoices/{{FIRST_REVISION_INVOICE_ID}} \
  -u "
sk_test_BQokikJOvBiI2HlWgH4olfQ2
:" \
  -d description="Updated maintenance contract"

To add a new line item to the revised invoice:

curl https://api.stripe.com/v1/invoiceitems \
  -u "
sk_test_BQokikJOvBiI2HlWgH4olfQ2
:" \
  -d customer=
{{CUSTOMER_ID}} \
  -d invoice={{FIRST_REVISION_INVOICE_ID}} \
  -d "pricing[price]"=
{{PRICE_ID}} \
  -d quantity=100 \
  --data-urlencode description="Additional Stripe swag!"

Invoice revisions allow you to update customer information and have it reflected in the PDFs and on the Hosted Invoice Pages of finalized invoices:

curl https://api.stripe.com/v1/customers/{{CUSTOMER_ID}} \
  -u "
sk_test_BQokikJOvBiI2HlWgH4olfQ2
:" \
  -d name="John Doe"

After you make all of your desired changes, finalize the revised invoice:

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

Finalizing the revised invoice changes its state to open, and sets the finalized_at parameter to the current time stamp (rather than the finalized_at time stamp for the original invoice ). When you finalize an invoice, Stripe does the following:

• Voids the original invoice.
• Adds a latest_revision parameter to the original invoice.

In some cases, you might need to make several revisions to an invoice. The process here is the same one used for the first revision except that Stripe updates the latest_revision parameter on all previous revisions. We only update the latest_revision parameter on finalization, not when you create the revised invoice.

curl https://api.stripe.com/v1/invoices \
  -u "
sk_test_BQokikJOvBiI2HlWgH4olfQ2
:" \
  -d "from_invoice[invoice]"={{FIRST_REVISION_INVOICE_ID}} \
  -d "from_invoice[action]"=revision

After you submit a request using the from_invoice parameter, you receive a response similar to the following:

{
  "id": "{{LATEST_REVISION_INVOICE_ID}}",
  "status": "draft",
  "from_invoice": {
    "invoice": "{{FIRST_REVISION_INVOICE_ID}}",
    "action": "revision",
  },
  # ... more fields
}

Finalize the new invoice to complete the revision:

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

If you attempt to fetch the original invoice, you receive a response indicating that it’s void. Stripe voids the original invoice as soon as the first revision finalizes.

{
  "id": "{{ORIGINAL_INVOICE_ID}}",
  "status": "void",
  "latest_revision": "{{LATEST_REVISION_INVOICE_ID}}", # This has changed from "{{FIRST_REVISION_INVOICE_ID}".
}

Stripe enforces several constraints on invoice revisions:

• Invoices can have at most one draft revision—If you POST to the /v1/invoices endpoint when another draft invoice exists with the same from_invoice[invoice] parameter, Stripe responds with a 400 status code.

• You can only create a revision for invoices with open or uncollectible statuses—If you POST to the /v1/invoices endpoint, and from_invoice[invoice] corresponds to an invoice with any state other than open or uncollectible, we respond with a 400 status code.

• If an invoice is open or uncollectible but has a payment intent in the processing state, you can’t create or finalize revisions—If a customer is using a payment method where the invoice status doesn’t update to paid when a payment attempt is initiated (like us_bank_account), we respond with a 400 status code.

• If an open or uncollectible invoice enters a paid or void status or has a processing payment intent while it has a draft revision, you can’t finalize the revision—Stripe enforces this through a 400 status code on any endpoint that could result in invoice finalization, including /v1/invoices/:id/finalize, /v1/invoices/:id/pay, and /v1/invoices/:id/send.

• You can’t revise invoices that are attached to a subscription—After finalization, you can’t edit invoices that have a subscription ID after finalization. For these types of invoices, Stripe sends an invoice.created webhook 1 hour before finalization for all invoices after the first. Additionally, you can’t edit any standalone invoices with subscription line items. These standalone invoices are usually created by pulling in pending proration line items.

• You can’t revise invoices that have credit notes—You can’t create a revision for an invoice that has a credit note.