Breaking changes
Replaces top-level price fields with improved price modeling on Invoice Items and Invoice Line Items Breaking changes
What’s new
We’re introducing a new polymorphic pricing concept on Invoice Items and Invoice Line Items. It contains all price-related data and unifies the structure of pricing objects ( Price and Plan) to prepare for adding new pricing object types. We’re also moving unit amount data into pricing.
Why is this a breaking change?
- price and plan fields are no longer available on Invoice Items and Invoice Line Items.
- Move unit _ amount and unit _ amount _ decimal to the new pricing concept on Invoice Items and Invoice Line Items.
Impact
Replace all references to price or plan on Invoice Items or Invoice Line Items with the pricing field:
- Instead of invoice _ item. price. id , use invoice _ item. pricing. price _ details. price after verifying that invoice _ item. pricing. type is price _ details
- When creating or updating Invoice Items, use the pricing parameter instead of price (for example, set pricing. price instead of passing the price parameter)
- For unit amounts, use pricing. unit _ amount _ decimal instead of unit _ amount or unit _ amount _ decimal
- When creating or updating Invoice Items, use the unit _ amount _ decimal parameter instead of unit _ amount
Changes
| Parameters | Change | Resources or endpoints |
|---|---|---|
| plan price unit_amount_decimal unit_amount | Removed | InvoiceItem |
| plan price | Removed | InvoiceLineItem |
| pricing | Added | Invoice#add_lines. lines[] Invoice#update_lines. lines[] InvoiceItem#create + 4 more InvoiceItem#update InvoiceLineItem#update InvoiceItem InvoiceLineItem |
| price | Removed | Invoice#add_lines. lines[] Invoice#update_lines. lines[] InvoiceItem#create + 4 more InvoiceItem#update InvoiceItem InvoiceLineItem#update InvoiceLineItem |
| unit_amount | Removed | InvoiceItem#create InvoiceItem#update InvoiceItem |
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.