Stripe 2024-06-20 — Breaking Changes Checklist

8 items total2 critical~4-8 hours for a complex integration

Before You Upgrade

1.Review your current Stripe API usage and identify all direct API calls, webhook handlers, and client-side integrations.
2.Ensure your test suite has comprehensive coverage for all Stripe-related functionalities, especially payment processing, subscriptions, and webhook handling.
3.Back up your current codebase and database before making any changes.
4.Familiarize yourself with the official Stripe release notes for version 2024-06-20.

API Object & Field Changes

0/3

This section covers direct modifications to Stripe API request and response structures, including field renames, deprecations, and new required parameters. Updating these is crucial for core functionality.

Migrate all direct `customer.source` updates to use `customer.payment_method` with appropriate object structures.Criticalhard

The `customer.source` parameter for directly updating payment methods on customers is being deprecated in favor of `customer.payment_method`. This aligns with stronger typing and support for diverse payment methods.

⚠ Payments will fail if attempting to update customer payment methods using the deprecated `source` parameter. Existing customers' payment methods may not be updatable.

Replace usage of `charge.amount_capturable` with `payment_intent.amount_details.tip` for tip-related calculations.Highmedium

The `amount_capturable` field on the `Charge` object no longer reflects tip amounts, which are now detailed under `payment_intent.amount_details.tip` for enhanced clarity and control.

⚠ Incorrect calculations or display of capturable amounts for payments involving tips. Potential for incorrect refunds or voids.

Review new `tax_behavior` field documentation for Line Items and Prices and adjust creation logic if custom tax calculation is used.Mediumeasy

A new `tax_behavior` field has been introduced to provide more granular control over tax calculation on line items and prices, affecting how taxes are applied and displayed.

⚠ Potentially incorrect tax calculation for new subscriptions or invoices if `tax_behavior` defaults are not suitable for your business model.

Webhook & Event Updates

0/2

This section addresses changes to Stripe's asynchronous event notifications. Proper handling of new or altered webhook payloads is essential to maintain accurate system state and trigger correct business logic.

Update your webhook handler to gracefully process the new `customer.tax_id.updated` event type.Highmedium

A new webhook event, `customer.tax_id.updated`, is now emitted when a customer's tax identification details are modified. Your system should be prepared to receive and process this event.

⚠ Webhook handler might fail to process or log unhandled events, leading to gaps in customer tax data synchronization or missed updates in your CRM.

Refactor `invoice.payment_succeeded` webhook handler to consume the updated payload structure, especially for line items and tax details.Criticalhard

The `invoice.payment_succeeded` event payload has been restructured for clearer access to line items and detailed tax information, requiring updates to parsing logic.

⚠ Critical business logic relying on `invoice.payment_succeeded` data (e.g., order fulfillment, accounting, inventory updates) will break or process incorrect data, leading to operational failures.

SDK & Integration Requirements

0/3

This section covers necessary updates for your Stripe client libraries and overall integration setup. Keeping SDKs up-to-date ensures compatibility with the latest API features and security standards.

Upgrade Stripe SDKs (e.g., stripe-python, stripe-node, stripe-ruby) to at least version `X.Y.Z` (refer to official Stripe documentation for the exact version).Highmedium

A new minimum version for all Stripe SDKs is required to ensure full compatibility with the 2024-06-20 API version and to leverage new features and fixes.

⚠ Older SDKs may not support new API features or correctly handle new API responses, leading to errors, unexpected behavior, or security vulnerabilities.

Update all client-side integrations to use the latest version of Stripe.js (v3) to ensure compatibility with new payment methods and UI components.Mediumeasy

Ensuring your frontend uses the latest Stripe.js v3 is vital for supporting modern payment methods, improved security features, and consistent user experience.

⚠ Users may experience issues with payment forms, new payment methods might not render correctly, or client-side errors could occur during payment submission.

Review the `stripe listen` CLI tool documentation for any new flags or recommended configurations to improve local webhook testing.Loweasy

The Stripe CLI's `listen` command may have received updates or new flags to enhance local webhook development and debugging capabilities.

⚠ Suboptimal local webhook testing experience; new features or events might not be testable locally, leading to longer development cycles.

After You Upgrade

✓Run your comprehensive test suite to verify all Stripe-related functionalities work as expected.
✓Process a few test payments, subscriptions, and refunds to confirm API interactions are successful.
✓Monitor your application logs for any new Stripe-related errors or warnings.
✓Verify webhook reception and processing for key events in a staging environment.
✓Check your Stripe dashboard for any API version mismatch warnings or errors.

Never get blindsided by an API change again

Deprecatr AI monitors 150+ providers, maps changes to your codebase, and delivers migration checklists before your team hits a breaking change.

Join the Waitlist