# Create invoice payment plans Learn how to create payment plans for your Stripe invoices. Invoice payment plans let you split an [invoice](https://docs.stripe.com/api/invoices/object.md) total into separate payments with different due dates. For example, you can collect a deposit followed by the remaining balance, or offer more favorable terms by dividing the amount due into smaller installments over time. Stripe sends installment reminders and shows customers a history of past payments. This feature is in [private preview](https://docs.stripe.com/release-phases.md). > This feature is in private preview. You can request early access by filling in the form below. ### Interested in getting early access to invoice payment plans? Enter your email address below and our team will contact you soon. ```bash curl https://docs.stripe.com/preview/register \ -X POST \ -H "Content-Type: application/json" \ -H "Referer: https://docs.stripe.com/invoicing/payment-plans" \ -d '{"email": "EMAIL", "preview": "billing_invoice_payment_plans_preview"}' ``` ## Limitations Payment plans have a few 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. - 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_automatically` invoices. - 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 Stripe Sigma. - Some Billing Analytics charts (Top Subscribers) only register invoices that are fully paid. Other charts are unaffected. - You can’t apply payment plans to subscription invoices. # API This guide shows how to set up and manage payment plans using the [Invoicing API](https://docs.stripe.com/api/invoices.md) and the [Payment Plan API](https://docs.stripe.com/api/payment-plan.md). ## Create supporting objects Before setting up payment plans, review [Integrate with the Invoicing API](https://docs.stripe.com/invoicing/integration.md). You need to understand how to create products, prices, and customers using the Stripe API or Dashboard to use this feature. ## Create an invoice and add invoice items Before creating a payment plan, create the invoice that the payment plan applies to. Set the invoice’s [collection_method](https://docs.stripe.com/api/invoices/create.md#create_invoice-collection_method) to `send_invoice`. Payment plans aren’t supported for `charge_automatically` invoices. ```curl curl https://api.stripe.com/v1/invoices \ -u "<>:" \ -H "Stripe-Version: 2026-08-26.preview" \ -d "customer={{CUSTOMER_ID}}" \ -d collection_method=send_invoice \ -d auto_advance=false ``` ## Create the payment plan The payment plan’s `schedule` describes how Stripe divides the invoice total into installments and when each installment is due. This section explains two common use cases: flexible payment terms and an initial deposit. ### Flexible payment terms Use percentage-based installments when you want the payment amounts to adjust with the invoice total. For example, suppose you have an invoice for 6,000 USD and want the customer to pay it in four equal installments. Create a schedule with four installments of 25% each: ```curl curl https://api.stripe.com/v1/payment_plans \ -u "<>:" \ -H "Stripe-Version: 2026-08-26.preview" \ -d "collects_on[0][type]=invoice_details" \ -d "collects_on[0][invoice_details][invoice]={{INVOICE_ID}}" \ -d "schedule[type]=amounts_due" \ -d "schedule[amounts_due][amounts][0][type]=percentage" \ -d "schedule[amounts_due][amounts][0][percentage]=25" \ -d "schedule[amounts_due][amounts][0][description]=Payment 1" \ -d "schedule[amounts_due][amounts][0][due_date][type]=relative" \ -d "schedule[amounts_due][amounts][0][due_date][relative][interval]=day" \ -d "schedule[amounts_due][amounts][0][due_date][relative][count]=30" \ -d "schedule[amounts_due][amounts][1][type]=percentage" \ -d "schedule[amounts_due][amounts][1][percentage]=25" \ -d "schedule[amounts_due][amounts][1][description]=Payment 2" \ -d "schedule[amounts_due][amounts][1][due_date][type]=relative" \ -d "schedule[amounts_due][amounts][1][due_date][relative][interval]=day" \ -d "schedule[amounts_due][amounts][1][due_date][relative][count]=60" \ -d "schedule[amounts_due][amounts][2][type]=percentage" \ -d "schedule[amounts_due][amounts][2][percentage]=25" \ -d "schedule[amounts_due][amounts][2][description]=Payment 3" \ -d "schedule[amounts_due][amounts][2][due_date][type]=relative" \ -d "schedule[amounts_due][amounts][2][due_date][relative][interval]=day" \ -d "schedule[amounts_due][amounts][2][due_date][relative][count]=90" \ -d "schedule[amounts_due][amounts][3][type]=percentage" \ -d "schedule[amounts_due][amounts][3][percentage]=25" \ -d "schedule[amounts_due][amounts][3][description]=Payment 4" \ -d "schedule[amounts_due][amounts][3][due_date][type]=relative" \ -d "schedule[amounts_due][amounts][3][due_date][relative][interval]=day" \ -d "schedule[amounts_due][amounts][3][due_date][relative][count]=120" ``` When you use percentages, the percentages in the schedule must add up to 100. Stripe calculates each installment’s concrete amount from the invoice total. ### Initial deposit To collect an initial deposit followed by payments for the remaining amount, represent the deposit as the first fixed-amount installment. For example, suppose you have an invoice for 5,000 USD and want the customer to pay a 1,000 USD deposit followed by two equal payments. Create the payment plan as follows: ```curl curl https://api.stripe.com/v1/payment_plans \ -u "<>:" \ -H "Stripe-Version: 2026-08-26.preview" \ -d "collects_on[0][type]=invoice_details" \ -d "collects_on[0][invoice_details][invoice]={{INVOICE_ID}}" \ -d "schedule[type]=amounts_due" \ -d "schedule[amounts_due][amounts][0][type]=fixed_amount" \ -d "schedule[amounts_due][amounts][0][fixed_amount][amount]=100000" \ -d "schedule[amounts_due][amounts][0][fixed_amount][currency]=usd" \ -d "schedule[amounts_due][amounts][0][description]=Deposit" \ -d "schedule[amounts_due][amounts][0][due_date][type]=relative" \ -d "schedule[amounts_due][amounts][0][due_date][relative][interval]=day" \ -d "schedule[amounts_due][amounts][0][due_date][relative][count]=0" \ -d "schedule[amounts_due][amounts][1][type]=fixed_amount" \ -d "schedule[amounts_due][amounts][1][fixed_amount][amount]=200000" \ -d "schedule[amounts_due][amounts][1][fixed_amount][currency]=usd" \ -d "schedule[amounts_due][amounts][1][description]=Payment 1" \ -d "schedule[amounts_due][amounts][1][due_date][type]=relative" \ -d "schedule[amounts_due][amounts][1][due_date][relative][interval]=day" \ -d "schedule[amounts_due][amounts][1][due_date][relative][count]=30" \ -d "schedule[amounts_due][amounts][2][type]=fixed_amount" \ -d "schedule[amounts_due][amounts][2][fixed_amount][amount]=200000" \ -d "schedule[amounts_due][amounts][2][fixed_amount][currency]=usd" \ -d "schedule[amounts_due][amounts][2][description]=Payment 2" \ -d "schedule[amounts_due][amounts][2][due_date][type]=relative" \ -d "schedule[amounts_due][amounts][2][due_date][relative][interval]=day" \ -d "schedule[amounts_due][amounts][2][due_date][relative][count]=60" ``` For fixed-amount schedules, the amounts must use the same currency and add up to the invoice’s final [amount_due](https://docs.stripe.com/api/invoices/object.md#invoice_object-amount_due). You can’t mix fixed amounts and percentages in the same schedule. ## Update the payment plan You can update a payment plan’s `schedule` to change due dates, amounts, descriptions, or the number of installments. The schedule represents your intended payment structure. The payment plan’s `installments` represent the current result of applying that schedule to the invoice: concrete amounts and due dates, stable installment IDs, amounts paid or forgiven, and each installment’s status. When updating a schedule, include an existing installment’s `id` to preserve its identity. Omit the `id` to create a new installment. Any existing installment IDs not included in the updated schedule are removed. This example preserves three installments while changing their fixed amounts and using absolute due dates: ```curl curl https://api.stripe.com/v1/payment_plans/{{PAYMENT_PLAN_ID}} \ -u "<>:" \ -H "Stripe-Version: 2026-08-26.preview" \ -d "schedule[type]=amounts_due" \ -d "schedule[amounts_due][amounts][0][id]={{PAYMENT_PLAN_INSTALLMENT_ID}}" \ -d "schedule[amounts_due][amounts][0][type]=fixed_amount" \ -d "schedule[amounts_due][amounts][0][fixed_amount][amount]=100000" \ -d "schedule[amounts_due][amounts][0][fixed_amount][currency]=usd" \ -d "schedule[amounts_due][amounts][0][description]=Updated deposit" \ -d "schedule[amounts_due][amounts][0][due_date][type]=absolute" \ -d "schedule[amounts_due][amounts][0][due_date][absolute]=1790812800" \ -d "schedule[amounts_due][amounts][1][id]={{PAYMENT_PLAN_INSTALLMENT_ID}}" \ -d "schedule[amounts_due][amounts][1][type]=fixed_amount" \ -d "schedule[amounts_due][amounts][1][fixed_amount][amount]=150000" \ -d "schedule[amounts_due][amounts][1][fixed_amount][currency]=usd" \ -d "schedule[amounts_due][amounts][1][description]=Updated payment 1" \ -d "schedule[amounts_due][amounts][1][due_date][type]=absolute" \ -d "schedule[amounts_due][amounts][1][due_date][absolute]=1793491200" \ -d "schedule[amounts_due][amounts][2][id]={{PAYMENT_PLAN_INSTALLMENT_ID}}" \ -d "schedule[amounts_due][amounts][2][type]=fixed_amount" \ -d "schedule[amounts_due][amounts][2][fixed_amount][amount]=250000" \ -d "schedule[amounts_due][amounts][2][fixed_amount][currency]=usd" \ -d "schedule[amounts_due][amounts][2][description]=Updated payment 2" \ -d "schedule[amounts_due][amounts][2][due_date][type]=absolute" \ -d "schedule[amounts_due][amounts][2][due_date][absolute]=1796083200" ``` The response includes the updated schedule and an updated `installments` array. In this example, the installments show the new 1,000 USD, 1,500 USD, and 2,500 USD amounts and the resolved due dates, together with their payment state and status. If payments or credits have already changed the invoice balance, the installment values can differ from the values expressed in the schedule. ## Finalize the invoice You can finalize an invoice after setting up the payment plan and adding the desired invoice items. You can also add a payment plan to an already finalized invoice. After finalization, you can’t add or remove invoice items or change the invoice’s amounts or dates. However, you can update the payment plan associated with the invoice. If you change the invoice items before finalization, make sure the fixed amounts in the payment plan’s schedule add up to the new invoice total. Percentage-based schedules continue to divide the updated invoice total according to their configured percentages. After adding the necessary invoice items and making sure your payment plan is set up correctly, finalize the invoice: ```curl curl -X POST https://api.stripe.com/v1/invoices/{{INVOICE_ID}}/finalize \ -u "<>:" \ -H "Stripe-Version: 2026-08-26.preview" ``` After finalization, the invoice is ready to send to the customer for payment. Review the invoice details before finalizing because you must make any adjustments to the invoice itself before this step. Learn more about [status transitions and finalization](https://docs.stripe.com/invoicing/integration/workflow-transitions.md). ## Post-finalization actions on invoices After you finalize an invoice, you can still update its payment plan through the API. Update the payment plan to change the schedule or metadata. This lets you reschedule or resize unpaid installments without voiding the invoice and starting over. When installment amounts change, Stripe applies payments to installments using first-in, first-out allocation. Earlier payments fill earlier installments before applying to later installments. ## Notifications Stripe emails your customer about each installment using the reminder schedule in your [invoice reminder settings](https://dashboard.stripe.com/settings/billing/invoice). Payment plans use the same schedule as your other invoices, applied to each installment due date instead of the invoice due date. To turn off email reminders, disable **Invoice reminders**. ## Listen for payment plan events Stripe sends the following events for payment plans. Each event contains the full [PaymentPlan](https://docs.stripe.com/api/payment-plan/object.md) object, including its `installments` array, so you can read the status of every installment from a single event. | Event | Stripe sends it when | | --- | --- | | `payment_plan.created` | You create a payment plan. | | `payment_plan.updated` | You change a payment plan, including its schedule. | | `payment_plan.installment_will_be_due` | An installment approaches its due date. | | `payment_plan.installment_due` | An installment reaches its due date. | | `payment_plan.installment_paid` | Your customer pays an installment. | If a schedule change leaves an installment with nothing left to collect and no money moves, Stripe sends `payment_plan.updated` and doesn’t send `payment_plan.installment_paid`. [Verify webhook signatures](https://docs.stripe.com/events/manage-webhook-endpoints.md#signature-errors) to confirm that events came from Stripe. ## Disclaimer By using invoice payment plans, you acknowledge the following: - This feature isn’t a buy now, pay later service. Stripe isn’t responsible to you or your customer for failure to pay or failure to deliver goods or services. To enable buy now, pay later for B2C invoices, read our [buy now, pay later guide](https://docs.stripe.com/payments/buy-now-pay-later.md). - Some payment methods, such as Affirm, Revolut Pay, and Afterpay, might have contractual or regulatory restrictions on their use in installment-based payment arrangements. Review your provider’s terms to confirm compliance before enabling payment plans for your customers. ### Australia This feature isn’t intended to provide you or your customers with any form of credit or alter the price of a good or service. Neither you nor your customers are charged additional fees associated with payment plans. ### Japan By reflecting a payment schedule, you can extend more flexible net terms or collect a deposit and allow a single invoice to be paid over multiple due dates. If you provide a financial product or service, consult with your legal advisors regarding applicable restrictions and requirements before setting up invoices. Installment payments, lending, credit, and buy now, pay later services are subject to regulation in Japan, and you might need to register or obtain approvals before engaging in those services.