Migrate from 2023-10-16 to 2024-04-10

What Changed

const lineItemCreationDate = invoice.lines.data[0].created; // Assumed product creation date
console.log(lineItemCreationDate);

const lineItemAddedDate = invoice.lines.data[0].created; // Accurately reflects line item addition to invoice
console.log(lineItemAddedDate);
// To get product creation date, fetch the Product object: 
// const product = await stripe.products.retrieve(lineItem.price.product);

Migration Steps

1. 1

   Review Stripe Changelog for 2024-04-10

   config

   Familiarize yourself with all changes introduced in API version 2024-04-10, paying close attention to breaking changes specific to your integration's features. Identify all affected API calls and webhook handlers. This ensures a comprehensive understanding of potential impacts.

   • ↳Check for changes in object structures and required parameters.
   • ↳Identify new deprecations that might affect future upgrades.
2. 2

   Update Stripe Client Libraries/SDKs

   code

   Ensure your application uses the latest stable version of your Stripe client library (e.g., `stripe-node`, `stripe-php`). This ensures compatibility with the new API version and gives access to new features and fixes. Update your dependency manager accordingly.

   • ↳Always pin major SDK versions to prevent unexpected breaking changes.
   • ↳Test SDK updates independently before API version bumps.
3. 3

   Set API Version to 2024-04-10

   config

   Update the API version header in your application's Stripe configuration. This is crucial for enabling the new API behavior. Do this incrementally, starting with your development environment before pushing to production.

   • ↳Set the `apiVersion` globally if possible, or per-request if necessary for specific endpoints.
   • ↳Avoid hardcoding API versions; use environment variables or configuration files.
4. 4

   Implement Code Adjustments for 'InvoiceLineItem.created'

   code

   Review any code that interprets the `created` timestamp on `InvoiceLineItem` objects. If you were using it to determine product creation date, you must adjust your logic to retrieve the product's actual creation date directly or through other means, as it now reflects when the line item was added to the invoice.

   • ↳Analyze existing reports or analytics that rely on this field.
   • ↳Consider adding a custom `metadata` field to the `Price` or `Product` if you need to store creation date with the product itself.
5. 5

   Review Webhook Handlers

   code

   Although no major webhook structure changes are documented as breaking, new fields or updated defaults might exist. Thoroughly test all webhook handlers to ensure they correctly parse and process events for `2024-04-10`. Pay attention to any new `metadata` fields that might now be populated.

   • ↳Use Stripe CLI to replay webhook events for various scenarios.
   • ↳Examine the full JSON payload of new version webhooks in a development environment.
6. 6

   Perform Thorough Integration Testing

   test

   Execute a full suite of integration tests covering key Stripe workflows: customer creation, payment processing (one-time, subscriptions), refunds, webhooks, and any connected account operations. Utilize Stripe Test Mode with the new API version to catch regressions.

   • ↳Focus on end-to-end flows involving multiple Stripe objects.
   • ↳Test edge cases like failed payments, cancellations, and retries.
7. 7

   Deploy to Staging/Production Incrementally

   deploy

   Deploy the updated code to a staging environment first for final verification. Once confident, deploy to production gradually, monitoring logs and error rates closely. Consider a canary release strategy if your infrastructure supports it.

   • ↳Use feature flags to enable the new API version for a subset of users initially.
   • ↳Have a clear rollback plan in case of unexpected issues.
8. 8

   Monitor Production Environment Closely

   verify

   After full deployment, monitor your application's logs, Stripe error rates, and key business metrics. Watch for any anomalies related to payments, subscriptions, or data processing that might indicate overlooked migration issues. Proactive monitoring is key.

   • ↳Set up alerts for Stripe API errors or failed webhook deliveries.
   • ↳Continuously review user feedback for any payment-related problems.

Testing Checklist

1. 1.

   Customer creation/update

   Create new customers, update existing ones and verify data consistency.

2. 2.

   Payment processing

   Process one-time payments (e.g., cards, ACH), create and manage subscriptions.

3. 3.

   Webhook handling

   Trigger and verify all handled webhooks (e.g., `charge.succeeded`, `invoice.paid`, `customer.subscription.updated`) for correct parsing.

4. 4.

   Refunds/Cancellations

   Initiate refunds for charges, cancel subscriptions and verify states.

5. 5.

   Invoice generation and retrieval

   Generate manual invoices, retrieve upcoming invoices, verify line item data including 'created' timestamp.

6. 6.

   Metadata handling

   Ensure custom `metadata` fields on various objects (e.g., PaymentIntent, Customer, Invoice Line Item) are correctly passed and retrieved.

Common Mistakes