Create invoice payment plansPublic preview
Learn how to create payment plans for your Stripe invoices.
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 favourable 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.
Limitations
Payment plans are currently a preview feature and have a few important limitations. Make sure that the following limitations don’t conflict with your use case:
- Payment plans aren’t supported by Stripe Revenue Recognition or the Stripe Connector for NetSuite.
- Invoices with payment plans aren’t reflected accurately by Stripe Tax obligations monitoring. Consult with your tax advisor.
- Stripe Tax doesn’t support partial refunds, so tax liability won’t be reflected accurately. Consult your tax advisor.
- Payment plans don’t auto-charge customers with saved payment details. Customers must return to the payment page to make subsequent payments. You can’t use them with
charge_invoices.automatically - Stripe automatically emails reminders to your customers to complete subsequent payments. We send these emails 1 week before payments are due by default. Sending these emails overrides any email reminder schedules and settings for one-off invoices. You can turn off the email reminders by disabling the setting for Send finalised invoices and credit notes to customers.
- For Connect users, application fees can’t be set on payment plan-enabled invoices. You can only set fees on PaymentIntents.
- Additional fields associated with payment plans aren’t available in Sigma.
- Some Billing Analytics charts (Top Subscribers, Collections) only register invoices that are fully paid. Other charts are unaffected.
- Subscription invoices can’t have payment plans applied.
Note
If you want to enable buy now, pay later for B2C invoices, read our buy now, pay later guide for more information.
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_. Payment plans aren’t supported for charge_ 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. 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_ field as shown below:
curl https://api.stripe.com/v1/invoices \ -u: \ -d customer=sk_test_BQokikJOvBiI2HlWgH4olfQ2\ -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_BQokikJOvBiI2HlWgH4olfQ2\ -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_ field for invoices with various payment structures. Keep in mind that the total amount from the amounts_ 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_ field for an invoice before finalising 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_ field lets you specify an exact date for a payment, providing more customisation 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_BQokikJOvBiI2HlWgH4olfQ2
In this example, we update an invoice’s payment plan to use specific due dates instead of days_. The amounts_ field also adjusts to show new payment amounts, showcasing the flexibility in modifying payment plans before finalising an invoice.
Finalise the invoice
You can finalise an invoice after setting up the payment plan and adding the desired invoice items. You can’t modify a finalised invoice, for example, updating the payment plan, adding or removing invoice items, or making changes to the invoice’s amounts or dates.
Before finalising 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_BQokikJOvBiI2HlWgH4olfQ2\ -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 finalising the invoice. Here’s an example of how to finalise an invoice:
curl https://api.stripe.com/v1/invoices//finalize \ -u{{INVOICE_ID}}: \ -X POSTsk_test_BQokikJOvBiI2HlWgH4olfQ2
After finalising an invoice, it’s ready to be sent to the customer for payment. Any adjustments to the invoice need to be done before finalisation, so review the invoice details before doing this step. Learn more about finalisation from our status transitions and finalisation guide.
Post-finalisation actions on invoices
You can still revise, void, or mark as uncollectible a finalised 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 details.