Breaking changes
Replaces top-level tax-related properties with improved tax modeling on Invoices, Invoice Line Items, and Credit Note Line Items Breaking changes
What’s new
We’re introducing a new taxes concept on Invoice Line Items and Credit Note Line Items that contains tax-related data and unifies the structure of tax objects in preparation for adding new types of tax objects. This replaces the top-level tax-related properties on the Invoice Line Item and Credit Note Line Item objects.
We’re also introducing a new total_taxes property on the Invoice and Credit Note objects for aggregated tax information.
Why is this a breaking change?
- tax _ rates and tax _ amounts are no longer available on the Invoice Line Item and Credit Note Line Item objects.
- total _ tax _ amounts is no longer available on the Invoice object.
Impact
Tax Rate IDs on Invoice Line Items and Credit Note Line Items are now nested inside the new taxes property:
- Replace line _ item. tax _ rates[0] with line _ item. taxes[0]. tax _ rate _ details. tax _ rate (after verifying that line _ item. taxes[0]. type is tax _ rate _ details )
- Replace line _ item. tax _ amounts[0]. amount with line _ item. taxes[0]. amount
Tax totals on Invoices and Credit Notes are now stored in total_taxes:
- Replace invoice. total _ tax _ amounts[0]. amount with invoice. total _ taxes[0]. amount (after verifying that invoice. total _ taxes[0]. type is tax _ rate _ details )
Changes
| Parameters | Change | Resources or endpoints |
|---|---|---|
| tax_amounts | Removed | CreditNote CreditNoteLineItem InvoiceLineItem |
| amount_excluding_tax unit_amount_excluding_tax | Removed | CreditNoteLineItem InvoiceLineItem |
| tax_rates | Removed | InvoiceLineItem |
| tax total_tax_amounts | Removed | Invoice |
| total_taxes | Added | CreditNote Invoice |
| taxes | Added | CreditNoteLineItem InvoiceLineItem |
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-03-31. 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.