Adds support for invoice items metadata and period in subscriptions and schedules

What’s new

We introduced a new way to customize the metadata and period fields for one-off invoice items generated by subscriptions and subscription schedules:.

You can directly attach metadata when configuring add_invoice_items, eliminating the need to add this information later in subsequent and separate API calls.
You can specify custom period.start and period.end dates that override the default subscription billing cycle dates. This gives you precise control over revenue recognition periods for one-off charges. We’ve also included timestamp indicators (such as max_item_period_start and min_item_period_end for subscriptions, phase_start and phase_end for schedules). This helps you align dates to important timestamps such as subscription billing periods or subscription schedule phase dates.

Specify the metadata or the period field for add_invoice_items using the following API endpoints:

Parameters	Change	Resources or endpoints
metadata period	Added	Invoice#create_preview. schedule_details. phases[]. add_invoice_items[] Subscription#create. add_invoice_items[] Subscription#update. add_invoice_items[] + 3 more SubscriptionSchedule. phases[]. add_invoice_items[] SubscriptionSchedule#create. phases[]. add_invoice_items[] SubscriptionSchedule#update. phases[]. add_invoice_items[]

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-08-27. basil