Stripe Migration Guide

Availability

Core Standard Plus Pro Enterprise Flex Self-Managed Enterprise PyAirbyte

Support Level

Airbyte

Connector Version

5.15.17 (last updated 10 days ago)

Sync Success Rate

Usage Rate

Definition ID

e094cb9a-26de-4645-8761-65c0c425d1de

Upgrading to 6.0.0

Version 6.0.0 fixes the invoice_line_items and subscription_items incremental streams. These streams were incorrectly emitting parent objects (invoices and subscriptions) instead of individual child items (line items and subscription items).

Summary of changes

The invoice_line_items stream now emits individual line item records with IDs starting with il_ instead of invoice records with IDs starting with in_. Similarly, the subscription_items stream now emits individual subscription item records with IDs starting with si_ instead of subscription records with IDs starting with sub_.

Each child record includes parent metadata fields for context:

• invoice_line_items: Includes invoice_id, invoice_created, and invoice_updated fields
• subscription_items: Includes subscription_id, subscription_created, and subscription_updated fields

Migration Steps

1. Upgrade the Stripe connector by pressing the upgrade button and following the instructions on the screen.

2. Navigate to the connection's Schema tab.

3. Select Refresh source schema to detect the new schema structure.

4. For the invoice_line_items and subscription_items streams, you will need to reset the data since the record structure has fundamentally changed.

5. If your destination supports the Refresh feature:

   • Select Refresh and retain records for the affected streams
   • This will pull in all historical data with the new structure

6. If your destination does not support the Refresh feature:

   • You will need to Clear the affected streams
   • Then sync the connection again to retrieve all data with the new structure

Downstream Impact

If you have downstream transformations or queries that depend on the structure of invoice_line_items or subscription_items data, you will need to update them to work with the new record structure. The records now represent individual line items and subscription items rather than their parent objects.

Review the following information to prepare for and execute your upgrade.

Review the changelog

Before updating a connector, review the changelog to understand the changes and their potential impact on your existing connections. Find the changelog for any connector by navigating to the bottom of the documentation for that connector. Major version releases also include a migration guide.

Plan for major updates

Major updates may require you to adjust connection settings or even make changes to your data pipelines. Allocate enough time and resources for this. Use the migration guide to ensure your transition process goes smoothly.

Airbyte provides tooling that guarantees safe connector version bumps and enforces automated version bumps for minor and patch updates. You always need to manually update for major version bumps.

Self-managed plans: pin a specific version if you can't update

If you're unable to upgrade to the new version of a connector, you can pin that connector to a specific version.

1. In the navigation bar:

   • If you're on the Self-Managed Enterprise plan, click Organization settings > Sources/Destinations.

   • If you're on any other plan, click Workspace settings > Sources/Destinations.

2. Edit the entry for the connector you want to pin.

3. Set the Default Version to the version you want to use.

Self-managed plans: update the local connector image

If you self-manage Airbyte, you must manually update the connector image in your local registry before proceeding with the migration. Follow the steps below.

1. In the navigation bar:

   • If you're on the Self-Managed Enterprise plan, click Organization settings > Sources/Destinations.

   • If you're on any other plan, click Workspace settings > Sources/Destinations.

2. Find the connector you want to update in the list of connectors.

   note

   Airbyte lists two versions, the current in-use version and the latest version available.

3. Click Change to update your OSS version to the latest available version.

Update the connector version

Update each instance of the connector separately. If you have multiple instances of a connector, updating one doesn't affect the others.

1. In the navigation bar:

   • If you're on the Self-Managed Enterprise plan, click Organization settings > Sources/Destinations.

   • If you're on any other plan, click Workspace settings > Sources/Destinations.

2. Select the instance of the connector you wish to upgrade.

3. Select Upgrade.

4. Follow the prompt to confirm you are ready to upgrade to the new version.

Clear data from affected streams

After upgrading a connector with a breaking change, you must refresh affected schemas and clear your data.

1. In the nav bar, click Connections.

2. Find the connection affected by the upgrade.

3. Click the Schema tab.

4. Click Refresh source schema (looks like ). When Airbyte finishes, it shows you any detected schema changes.

5. Click OK.

6. Click Save changes

7. Clear the data for the streams affected by this upgrade.

Once the clear is complete, you can begin syncing your data again as usual.

Upgrading to 5.6.0

The Payment Methods stream previously sync data from Treasury flows. This version will now provide data about customers' payment methods.

We bumped this in a minor version because we didn't want to pause all connection, but still want to document the process of moving to this latest version.

Summary of changes:

• The stream Payment Methods will now provide data about customers' payment methods.
• The stream Payment Methods now incrementally syncs using the events endpoint.
• customer field type will be changed from object to string.

Refresh affected schemas and reset data

1. Select Connections in the main navbar.
   1. Select the connection(s) affected by the update.
2. Select the Replication tab.
   1. Select Refresh source schema.
   2. Select OK.

Any detected schema changes will be listed for your review.

3. Select Save changes at the bottom of the page.
   1. Ensure the Reset affected streams option is checked.

Depending on destination type you may not be prompted to reset your data.

4. Select Save connection.

This will reset the data in your destination and initiate a fresh sync.

For more information on resetting your data in Airbyte, see this page.

Upgrading to 5.4.0

The Refunds stream previously did not sync incrementally correctly. Incremental syncs are now resolved, and the Refunds stream now receives the correct updates using the events endpoint. This version resolves incremental sync issues with the Refunds stream.

Summary of changes:

• The stream Refunds cursor changed from the field created to updated when syncing incrementally.
• The stream Refunds now incrementally syncs using the events endpoint.

Migration Steps

1. Upgrade the Stripe connector by pressing the upgrade button and following the instructions on the screen.

info

The following migration steps are relevant for those who would like to sync Refunds incrementally. These migration steps can be skipped if you prefer to sync using Full Refresh.

The stream Refunds will need to be synced historically again to ensure the connection continues syncing smoothly. If available for your destination, we recommend initiating a Refresh for the stream, which will pull in all historical data for the stream without removing the existing data first and update your destination with all data once complete. To initiate a Refresh:

1. Navigate to the connection's Schema tab. Navigate to the Refunds stream.
2. Update the Refunds stream to use the Incremental | Append + Dedup sync mode. This ensures your data will sync correctly and capture all updates efficiently.
3. If your stream already has a sync mode of either Incremental | Append + Dedup or Incremental | Append, simply update the cursor from created_at to updated_at.
4. Save the connection.
5. Review the prompt to Refresh the Refunds stream. Select Refresh and retain records to ensure any data no longer found in Stripe is retained in your destination.
6. Confirm the modal to save the connection and initiate a Refresh. This will start to pull in all historical data for the stream.

note

If you are using a destination that does not support the Refresh feature, you will need to Clear your stream. This will remove the data from the destination for just that stream. You will then need to sync the connection again in order to sync all data again for that stream.

Upgrading to 5.0.0

This change fixes multiple incremental sync issues with the Refunds, Checkout Sessions and Checkout Sessions Line Items streams:

• Refunds stream was not syncing data in the incremental sync mode. Cursor field has been updated to "created" to allow for incremental syncs. Because of the changed cursor field of the Refunds stream, incremental syncs will not reflect every update of the records that have been previously replicated. Only newly created records will be synced. To always have the up-to-date data, users are encouraged to make use of the lookback window.
• CheckoutSessions stream had been missing data for one day when using the incremental sync mode after a reset; this has been resolved.
• CheckoutSessionsLineItems previously had potential data loss. It has been updated to use a new cursor field checkout_session_updated.
• Incremental streams with the created cursor had been duplicating some data; this has been fixed.

Stream schema update is a breaking change as well as changing the cursor field for the Refunds and the CheckoutSessionsLineItems stream. A schema refresh and data reset of all effected streams is required after the update is applied.

Also, this update affects three more streams: Invoices, Subscriptions, SubscriptionSchedule. Schemas are changed in this update so that the declared data types would match the actual data.

Stream schema update is a breaking change as well as changing the cursor field for the Refunds and the CheckoutSessionsLineItems stream. A schema refresh and data reset of all effected streams is required after the update is applied. Because of the changed cursor field of the Refunds stream, incremental syncs will not reflect every update of the records that have been previously replicated. Only newly created records will be synced. To always have the up-to-date data, users are encouraged to make use of the lookback window.

Upgrading to 4.0.0

A major update of most streams to support event-based incremental sync mode. This allows the connector to pull not only the newly created data since the last sync, but the modified data as well. A schema refresh is required for the connector to use the new cursor format.