Adds support for partial payments on invoices
What’s new
We added support for attaching multiple Payment Intents to an Invoice. Allowing partial payments and multiple payments on invoices provides greater flexibility for businesses and customers in managing payments and cash flow. We also introduced the invoice_payment.paid webhook to track when an attached payment transitions to the paid status. To support issuing credit notes for partially paid invoices, we added a mixed type, pre_payment_amount field, and post_payment_amount field to credit note objects.
Impact
Attach multiple payments to an invoice
You can now use the Attach Payment API to attach multiple payments to an invoice:
Command Line
Select a language
cURL
Stripe CLI
Ruby
Python
PHP
Java
Node.js
Go
.NET
No results
Issue credit notes for partially paid invoices
You can continue to use the Create Credit Note method to issue credit notes for partially paid invoices. A credit note first reduces the invoice’s amount_remaining (and amount_due), but not below zero. The pre_payment_amount field on the credit note object tracks this portion. The remaining amount after reducing the invoice’s amount_remaining to zero applies to the post_payment_amount field on the credit note object. A credit note has a mixed type if both the pre_payment_amount and the post_payment_amount are non-zero.
For more information about issuing credit notes, see the Create Credit Notes API.
Changes
| Endpoint | Change | Resource |
|---|---|---|
| attach_payment | Added | Invoice |
| Parameters | Change | Resources or endpoints |
| post_payment_amount pre_payment_amount | Added | CreditNote |
| Values | Change | Enums |
| invoice_payment. paid | Added | Event. type |
| invoice_payment. paid | Added | WebhookEndpoint#create. enabled_events WebhookEndpoint#update. enabled_events |
| mixed | Added | CreditNote. type |
| Change | Event type | |
| invoice_payment. paid | Added | InvoicePayment |
Upgrade
- View your current API version in Workbench.
- If you use an SDK, upgrade to the corresponding SDK version for this API version.
- If you don’t use an SDK, update your API requests to include Stripe-Version: 2025-05-28. basil
- Upgrade the API version used for webhook endpoints .
- Test your integration against the new version.
- If you use Connect, test your Connect integration .
- In Workbench, perform the upgrade . You can roll back the version for 72 hours.
Learn more about Stripe API upgrades.