Skip to main content

Stripe Migration Guide

Availability
Available CoreAvailable StandardAvailable PlusAvailable ProAvailable Enterprise FlexAvailable Self-Managed EnterpriseAvailable PyAirbyte
Support Level
Airbyte
Connector Version
6.0.1 (last updated 4 days ago)
Definition ID
e094cb9a-26de-4645-8761-65c0c425d1de

Upgrading to 6.0.0​

Version 6.0.0 fixes a bug where the invoice_line_items and subscription_items incremental streams emitted only one record per Stripe event instead of correctly expanding nested line items. An event containing N line items previously produced 1 record; it now produces N records.

What changed​

We changed how records are extracted from the API response for the invoice_line_items and subscription_items streams to ensure nested data is properly treated as individual records.

Example: invoice_line_items​

Before (5.x): A single Stripe event with an invoice containing 3 line items produced 1 flattened record:

{
  "id": "evt_1234",
  "type": "invoice.updated",
  "data": {
    "object": {
      "id": "in_abc",
      "lines": {
        "data": [
          {"id": "il_1", "amount": 1000},
          {"id": "il_2", "amount": 2000},
          {"id": "il_3", "amount": 500}
        ]
      }
    }
  }
}

This event emitted 1 record containing the top-level event fields. The nested line items inside data.object.lines.data were lost.

After (6.0.0): The same event now emits 3 records, 1 per line item:

{"id": "il_1", "amount": 1000, "invoice_id": "in_abc", "invoice_updated": 1712600000}
{"id": "il_2", "amount": 2000, "invoice_id": "in_abc", "invoice_updated": 1712600000}
{"id": "il_3", "amount": 500, "invoice_id": "in_abc", "invoice_updated": 1712600000}

The same change applies to subscription_items, which expands items from data.object.items.data.

Who is affected​

Users syncing the invoice_line_items or subscription_items streams in incremental mode. Previously synced data for these streams may be incomplete due to the bug.

Migration steps​

After upgrading, you can choose to either leave your syncs as-is or run a full refresh to recapture the correct values for impacted fields.

Option 1: Leave syncs alone. Future incremental syncs will emit records correctly. Historical data already in your destination will remain incomplete, but no action is required.

Option 2: Run a full refresh. A full refresh will recapture the correct values for all records in the impacted streams. If you choose this option, decide between:

  • Full Refresh and Retain records: Keeps existing data in your destination and layers the refreshed data on top. This is the safer option for most users.
  • Full Refresh and Clear: Replaces all existing data in the destination for these streams. Use caution: because the Stripe Events API only retains events for the last 30 days, clearing will cause you to lose all updates to event-based streams in your destination that are older than 30 days. See the Stripe API event retention limitation for more details.
tip

If the 30-day retention window is a concern, consider making a backup of your currently synced data in a separate table in your destination before clearing the stream. Once the backup is complete, you can safely run a Full Refresh and Clear without losing historical data.

Connector upgrade guide​

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.
  1. 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.
  1. 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.

Was this page helpful?