# Adds invoice description, footer, and custom fields to the Subscriptions API ## What’s new The [description](https://docs.stripe.com/api/subscriptions/create.md?api-version=2026-06-24.dahlia#create_subscription-invoice_settings-description), [footer](https://docs.stripe.com/api/subscriptions/create.md?api-version=2026-06-24.dahlia#create_subscription-invoice_settings-footer), and [custom_fields](https://docs.stripe.com/api/subscriptions/create.md?api-version=2026-06-24.dahlia#create_subscription-invoice_settings-custom_fields) parameters are now available on the [invoice_settings](https://docs.stripe.com/api/subscriptions/create.md?api-version=2026-06-24.dahlia#create_subscription-invoice_settings) hash when you create or update a [Subscription](https://docs.stripe.com/api/subscriptions.md?api-version=2026-06-24.dahlia). These properties are also returned when you retrieve a Subscription. Previously, these fields were configurable exclusively in the Stripe Dashboard. ## Impact You can now programmatically control the description, footer, and custom fields that appear on every invoice generated by a subscription without needing to update each invoice individually. This is useful for adding information such as PO numbers, contract references, or other reconciliation details at the subscription level. See the [subscription invoices documentation](https://docs.stripe.com/billing/invoices/subscription.md) for more details. ## Changes #### REST API | Parameters | Change | Resources or endpoints | | --- | --- | --- | | `custom_fields`, `description`, `footer` | Added | [Subscription#create.invoice_settings](/api/subscriptions/create?api-version=2026-06-24.dahlia#create_subscription-invoice_settings), [Subscription#update.invoice_settings](/api/subscriptions/update?api-version=2026-06-24.dahlia#update_subscription-invoice_settings), [Subscription.invoice_settings](/api/subscriptions/object?api-version=2026-06-24.dahlia#subscription_object-invoice_settings) | #### Ruby | Parameters | Change | Resources or methods | | --- | --- | --- | | `custom_fields`, `description`, `footer` | Added | [Subscription::InvoiceSetting](/api/subscriptions/object?api-version=2026-06-24.dahlia#subscription_object-invoice_settings), [SubscriptionCreateParams::InvoiceSetting](/api/subscriptions/create?api-version=2026-06-24.dahlia#create_subscription-invoice_settings), [SubscriptionUpdateParams::InvoiceSetting](/api/subscriptions/update?api-version=2026-06-24.dahlia#update_subscription-invoice_settings) | #### Python | Parameters | Change | Resources or methods | | --- | --- | --- | | `custom_fields`, `description`, `footer` | Added | [Subscription.InvoiceSetting](/api/subscriptions/object?api-version=2026-06-24.dahlia#subscription_object-invoice_settings), [SubscriptionCreateParamsInvoiceSetting](/api/subscriptions/create?api-version=2026-06-24.dahlia#create_subscription-invoice_settings), [SubscriptionModifyParamsInvoiceSetting](/api/subscriptions/update?api-version=2026-06-24.dahlia#update_subscription-invoice_settings) | #### PHP | Parameters | Change | Resources or methods | | --- | --- | --- | | `custom_fields`, `description`, `footer` | Added | [Subscription.create().$params.invoice_setting](/api/subscriptions/create?api-version=2026-06-24.dahlia#create_subscription-invoice_settings), [Subscription.invoice_settings](/api/subscriptions/object?api-version=2026-06-24.dahlia#subscription_object-invoice_settings), [Subscription.update().$params.invoice_setting](/api/subscriptions/update?api-version=2026-06-24.dahlia#update_subscription-invoice_settings) | #### Java | Parameters | Change | Resources or methods | | --- | --- | --- | | `customFields`, `description`, `footer` | Added | [Subscription.invoice_settings](/api/subscriptions/object?api-version=2026-06-24.dahlia#subscription_object-invoice_settings), [SubscriptionCreateParams.invoice_settings](/api/subscriptions/create?api-version=2026-06-24.dahlia#create_subscription-invoice_settings), [SubscriptionUpdateParams.invoice_settings](/api/subscriptions/update?api-version=2026-06-24.dahlia#update_subscription-invoice_settings) | #### Node.js | Parameters | Change | Resources or methods | | --- | --- | --- | | `custom_fields`, `description`, `footer` | Added | [Subscription.invoice_settings](/api/subscriptions/object?api-version=2026-06-24.dahlia#subscription_object-invoice_settings), [SubscriptionCreateParams.invoice_settings](/api/subscriptions/create?api-version=2026-06-24.dahlia#create_subscription-invoice_settings), [SubscriptionUpdateParams.invoice_settings](/api/subscriptions/update?api-version=2026-06-24.dahlia#update_subscription-invoice_settings) | #### Go | Parameters | Change | Resources or methods | | --- | --- | --- | | `CustomFields`, `Description`, `Footer` | Added | [SubscriptionInvoiceSettings](/api/subscriptions/object?api-version=2026-06-24.dahlia#subscription_object-invoice_settings), [SubscriptionCreateInvoiceSettingsParams](/api/subscriptions/create?api-version=2026-06-24.dahlia#create_subscription-invoice_settings), [SubscriptionUpdateInvoiceSettingsParams](/api/subscriptions/update?api-version=2026-06-24.dahlia#update_subscription-invoice_settings) | #### .NET | Parameters | Change | Resources or methods | | --- | --- | --- | | `CustomFields`, `Description`, `Footer` | Added | [Subscription.InvoiceSettings](/api/subscriptions/object?api-version=2026-06-24.dahlia#subscription_object-invoice_settings), [SubscriptionInvoiceSettingsOptions](/api/subscriptions/create?api-version=2026-06-24.dahlia#create_subscription-invoice_settings), [SubscriptionInvoiceSettingsOptions](/api/subscriptions/update?api-version=2026-06-24.dahlia#update_subscription-invoice_settings) | ## Upgrade #### REST API 1. [View your current API version](https://docs.stripe.com/upgrades.md#view-your-api-version-and-the-latest-available-upgrade-in-workbench) in Workbench. 2. 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](https://docs.stripe.com/api/versioning.md) to include `Stripe-Version: 2026-06-24.dahlia` 3. Upgrade the API version used for [webhook endpoints](https://docs.stripe.com/webhooks/versioning.md). 4. [Test your integration](https://docs.stripe.com/testing.md) against the new version. 5. If you use Connect, [test your Connect integration](https://docs.stripe.com/connect/testing.md). 6. In Workbench, [perform the upgrade](https://docs.stripe.com/upgrades.md#perform-the-upgrade). You can [roll back the version](https://docs.stripe.com/upgrades.md#roll-back-your-api-version) for 72 hours. Learn more about [Stripe API upgrades](https://docs.stripe.com/upgrades.md). #### Ruby 1. [View your current API version](https://docs.stripe.com/upgrades.md#view-your-api-version-and-the-latest-available-upgrade-in-workbench) in Workbench. 2. Upgrade your Ruby SDK to the latest version. 3. Upgrade the API version used for [webhook endpoints](https://docs.stripe.com/webhooks/versioning.md). 4. [Test your integration](https://docs.stripe.com/testing.md) against the new version. 5. If you use Connect, [test your Connect integration](https://docs.stripe.com/connect/testing.md). 6. In Workbench, [perform the upgrade](https://docs.stripe.com/upgrades.md#perform-the-upgrade). You can [roll back the version](https://docs.stripe.com/upgrades.md#roll-back-your-api-version) for 72 hours. Learn more about [Stripe API upgrades](https://docs.stripe.com/upgrades.md). #### Python 1. [View your current API version](https://docs.stripe.com/upgrades.md#view-your-api-version-and-the-latest-available-upgrade-in-workbench) in Workbench. 2. Upgrade your Python SDK to the latest version. 3. Upgrade the API version used for [webhook endpoints](https://docs.stripe.com/webhooks/versioning.md). 4. [Test your integration](https://docs.stripe.com/testing.md) against the new version. 5. If you use Connect, [test your Connect integration](https://docs.stripe.com/connect/testing.md). 6. In Workbench, [perform the upgrade](https://docs.stripe.com/upgrades.md#perform-the-upgrade). You can [roll back the version](https://docs.stripe.com/upgrades.md#roll-back-your-api-version) for 72 hours. Learn more about [Stripe API upgrades](https://docs.stripe.com/upgrades.md). #### PHP 1. [View your current API version](https://docs.stripe.com/upgrades.md#view-your-api-version-and-the-latest-available-upgrade-in-workbench) in Workbench. 2. Upgrade your PHP SDK to the latest version. 3. Upgrade the API version used for [webhook endpoints](https://docs.stripe.com/webhooks/versioning.md). 4. [Test your integration](https://docs.stripe.com/testing.md) against the new version. 5. If you use Connect, [test your Connect integration](https://docs.stripe.com/connect/testing.md). 6. In Workbench, [perform the upgrade](https://docs.stripe.com/upgrades.md#perform-the-upgrade). You can [roll back the version](https://docs.stripe.com/upgrades.md#roll-back-your-api-version) for 72 hours. Learn more about [Stripe API upgrades](https://docs.stripe.com/upgrades.md). #### Java 1. [View your current API version](https://docs.stripe.com/upgrades.md#view-your-api-version-and-the-latest-available-upgrade-in-workbench) in Workbench. 2. Upgrade your Java SDK to the latest version. 3. Upgrade the API version used for [webhook endpoints](https://docs.stripe.com/webhooks/versioning.md). 4. [Test your integration](https://docs.stripe.com/testing.md) against the new version. 5. If you use Connect, [test your Connect integration](https://docs.stripe.com/connect/testing.md). 6. In Workbench, [perform the upgrade](https://docs.stripe.com/upgrades.md#perform-the-upgrade). You can [roll back the version](https://docs.stripe.com/upgrades.md#roll-back-your-api-version) for 72 hours. Learn more about [Stripe API upgrades](https://docs.stripe.com/upgrades.md). #### Node.js 1. [View your current API version](https://docs.stripe.com/upgrades.md#view-your-api-version-and-the-latest-available-upgrade-in-workbench) in Workbench. 2. Upgrade your Node SDK to the latest version. 3. Upgrade the API version used for [webhook endpoints](https://docs.stripe.com/webhooks/versioning.md). 4. [Test your integration](https://docs.stripe.com/testing.md) against the new version. 5. If you use Connect, [test your Connect integration](https://docs.stripe.com/connect/testing.md). 6. In Workbench, [perform the upgrade](https://docs.stripe.com/upgrades.md#perform-the-upgrade). You can [roll back the version](https://docs.stripe.com/upgrades.md#roll-back-your-api-version) for 72 hours. Learn more about [Stripe API upgrades](https://docs.stripe.com/upgrades.md). #### Go 1. [View your current API version](https://docs.stripe.com/upgrades.md#view-your-api-version-and-the-latest-available-upgrade-in-workbench) in Workbench. 2. Upgrade your Go SDK to the latest version. 3. Upgrade the API version used for [webhook endpoints](https://docs.stripe.com/webhooks/versioning.md). 4. [Test your integration](https://docs.stripe.com/testing.md) against the new version. 5. If you use Connect, [test your Connect integration](https://docs.stripe.com/connect/testing.md). 6. In Workbench, [perform the upgrade](https://docs.stripe.com/upgrades.md#perform-the-upgrade). You can [roll back the version](https://docs.stripe.com/upgrades.md#roll-back-your-api-version) for 72 hours. Learn more about [Stripe API upgrades](https://docs.stripe.com/upgrades.md). #### .NET 1. [View your current API version](https://docs.stripe.com/upgrades.md#view-your-api-version-and-the-latest-available-upgrade-in-workbench) in Workbench. 2. Upgrade your .NET SDK to the latest version. 3. Upgrade the API version used for [webhook endpoints](https://docs.stripe.com/webhooks/versioning.md). 4. [Test your integration](https://docs.stripe.com/testing.md) against the new version. 5. If you use Connect, [test your Connect integration](https://docs.stripe.com/connect/testing.md). 6. In Workbench, [perform the upgrade](https://docs.stripe.com/upgrades.md#perform-the-upgrade). You can [roll back the version](https://docs.stripe.com/upgrades.md#roll-back-your-api-version) for 72 hours. Learn more about [Stripe API upgrades](https://docs.stripe.com/upgrades.md).