Create Invoice Payment PlansBeta
Invoice Payment Plans let you break up an invoice’s total amount into separate payments with different due dates for your customers. This can expand your billing flexibility. For example, you could first collect a deposit and then the balance amount of a transaction at a later date. Alternatively, you could break up dues into more favorable terms for your customers by splitting them up into multiple, smaller increments over time. Stripe reminds your customers of upcoming payments that they have to make and shows them a history of past payments that they’ve already made. You can use both the Dashboard and the API to generate Payment Plans.
Note
Payment Plans are only available for non-subscription-generated invoices. Additionally, Payment Plans let you split up amounts due over multiple dates and remind your customers to make payments, but they don’t automatically charge saved payment methods on each due date. Stripe doesn’t offer financing for or guarantee collections with Payment Plans.
Interested in getting early access to Invoice Payment Plans?
Thank you! We'll be in touch soon.
This guide shows how to set up and manage payment plans using the amounts_due field on the Invoicing API.
Create supporting objects
Before setting up payment plans, make sure to review the concepts in the integrate with the Invoicing API guide. You need an understanding of how to create products, prices, and customers using the Stripe API or Dashboard to use this feature.
Create an invoice with a payment plan
The amounts_due field helps you set up payment plans with Stripe Invoices. To use this feature, set the collection_method for the invoice to send_invoice
. Payment plans are not supported for charge_automatically
invoices.
This section goes through two common use cases for payment plans: flexible payment terms and initial deposit.
Flexible payment terms
Use payment plans when you want to divide the amount due from your customer into smaller increments to make payment easier for them. For example, suppose you have an invoice of 6,000 USD, and you want the customer to pay it in three payments. You can set up the payment plan using the amounts_due
field as shown below:
curl https://api.stripe.com/v1/invoices \ -u
: \ -d customer=sk_test_4eC39HqLyjWDarjtT1zdp7dc\ -d collection_method=send_invoice \ -d auto_advance=true \ -d "amounts_due[][amount]=2000" \ -d "amounts_due[][days_until_due]=30" \ -d "amounts_due[][description]=Payment 1" \ -d "amounts_due[][amount]=2000" \ -d "amounts_due[][days_until_due]=60" \ -d "amounts_due[][description]=Payment 2" \ -d "amounts_due[][amount]=2000" \ -d "amounts_due[][days_until_due]=90" \ -d "amounts_due[][description]=Payment 3"{{CUSTOMER_ID}}
Initial deposit
In some situations, you might want to ask for an initial deposit followed by a payment plan for the remaining amount. For example, suppose you have an invoice of 5,000 USD, and you want the customer to pay a 1,000 USD deposit followed by two equal payments for the remaining amount. You can set up the payment plan as follows:
curl https://api.stripe.com/v1/invoices \ -u
: \ -d customer=sk_test_4eC39HqLyjWDarjtT1zdp7dc\ -d collection_method=send_invoice \ -d auto_advance=true \ -d "amounts_due[][amount]=1000" \ -d "amounts_due[][days_until_due]=1" \ -d "amounts_due[][description]=Deposit" \ -d "amounts_due[][amount]=2000" \ -d "amounts_due[][days_until_due]=30" \ -d "amounts_due[][description]=Payment 1" \ -d "amounts_due[][amount]=2000" \ -d "amounts_due[][days_until_due]=60" \ -d "amounts_due[][description]=Payment 2"{{CUSTOMER_ID}}
The examples above illustrate how to set up payment plans using the amounts_due
field for invoices with various payment structures. Keep in mind that the total amount from the amounts_due
field must equal the final amount_due of the invoice. With these examples, you can begin creating tailored payment plans based on your specific needs.
Update the payment plan
You can update the amounts_due
field for an invoice before finalizing it, letting you modify the payment plan as needed. This allows you to make adjustments, such as changing due dates, altering payment amounts, or adding new payments.
In addition to setting the number of days until a payment is due with days_until_due, you can also set a specific due date using the due_date field. The due_date
field lets you specify an exact date for a payment, providing more customization options for your payment plans.
Here’s an example of updating an invoice’s payment plan:
curl https://api.stripe.com/v1/invoices/
\ -u{{INVOICE_ID}}: \ -d "amounts_due[][amount]=1000" \ -d "amounts_due[][due_date]=1677514200" \ -d "amounts_due[][description]=Updated Payment 1" \ -d "amounts_due[][amount]=3000" \ -d "amounts_due[][due_date]=1678132000" \ -d "amounts_due[][description]=Updated Payment 2"sk_test_4eC39HqLyjWDarjtT1zdp7dc
In this example, we update an invoice’s payment plan to use specific due dates instead of days_until_due
. The amounts_due
field also adjusts to show new payment amounts, showcasing the flexibility in modifying payment plans before finalizing an invoice.
Finalize the invoice
After setting up the payment plan and adding the desired invoice items, it’s time to finalize the invoice. When an invoice is finalized, it can no longer be modified—this includes updating the payment plan, adding or removing invoice items, or making changes to the invoice’s amounts or dates.
Before finalizing your invoice, make sure you’ve added the required invoice items. Here’s an example of adding an invoice item:
curl https://api.stripe.com/v1/invoiceitems \ -u
: \ -d customer=sk_test_4eC39HqLyjWDarjtT1zdp7dc\ -d invoice={{CUSTOMER_ID}}\ -d price={{INVOICE_ID}}\ -d currency=usd{{PRICE_ID}}
After adding the necessary invoice items and making sure your payment plan is set up correctly, proceed with finalizing the invoice. Here’s an example of how to finalize an invoice:
curl https://api.stripe.com/v1/invoices/
/finalize \ -u{{INVOICE_ID}}: \ -X POSTsk_test_4eC39HqLyjWDarjtT1zdp7dc
After finalizing an invoice, it’s ready to be sent to the customer for payment. Any adjustments to the invoice need to be done before finalization, so review the invoice details before doing this step. Learn more about finalization from our status transitions and finalization guide.
Post-finalization actions on invoices
You can still revise, void, or mark as uncollectible a finalized invoice with a payment plan, only before the first payment is received. Additionally, Payment Plans can only be “marked as paid” outside Stripe for the entire remaining amount due of the invoice, and not for a partial amount.
Tracking partially paid invoices
Payment plan invoices that have been partially paid display a partially paid status across the Stripe Dashboard. However, if any invoice payments aren’t made by their due date, the overdue status takes precedence. To view invoice status with the API, review the amounts_due and payments fields for useful details.