Skip to main content

Stripe

This page contains the setup guide and reference information for the Stripe source connector.

Prerequisites​

  • Access to the Stripe account containing the data you wish to replicate

Setup Guide​

To authenticate the Stripe connector, you need to use a Stripe API key. Although you may use an existing key, we recommend that you create a new restricted key specifically for Airbyte and grant it Read privileges only. We also recommend granting Read privileges to all available permissions, and configuring the specific data you would like to replicate within Airbyte.

Create a Stripe Secret Key​

  1. Log in to your Stripe account.
  2. In the top navigation bar, click Developers.
  3. In the top-left corner, click API keys.
  4. Click + Create restricted key.
  5. Choose a Key name, and select Read for all available permissions.
  6. Click Create key. You may be prompted to enter a confirmation code sent to your email address.

For more information on Stripe API Keys, see the Stripe documentation.

Set up the Stripe source connector in Airbyte​

  1. Log in to your Airbyte Cloud or Airbyte Open Source account.

  2. In the left navigation bar, click Sources. In the top-right corner, click + New source.

  3. Find and select Stripe from the list of available sources.

  4. For Source name, enter a name to help you identify this source.

  5. For Account ID, enter your Stripe Account ID. This ID begins with acct_, and can be found in the top-right corner of your Stripe account settings page.

  6. For Secret Key, enter the restricted key you created for the connection.

  7. For Replication Start Date, use the provided datepicker or enter a UTC date and time programmatically in the format YYYY-MM-DDTHH:mm:ssZ. The data added on and after this date will be replicated.

  8. (Optional) For Lookback Window, you may specify a number of days from the present day to reread data. This allows the connector to retrieve data that might have been updated after its initial creation, and is useful for handling any post-transaction adjustments. This applies only to streams that do not support event-based incremental syncs, please see the list below.

    • Leaving the Lookback Window at its default value of 0 means Airbyte will not re-export data after it has been synced.
    • Setting the Lookback Window to 1 means Airbyte will re-export data from the past day, capturing any changes made in the last 24 hours.
    • Setting the Lookback Window to 7 means Airbyte will re-export and capture any data changes within the last week.

  9. (Optional) For Data Request Window, you may specify the time window in days used by the connector when requesting data from the Stripe API. This window defines the span of time covered in each request, with larger values encompassing more days in a single request. Generally speaking, the lack of overhead from making fewer requests means a larger window is faster to sync. However, this also means the state of the sync will persist less frequently. If an issue occurs or the sync is interrupted, a larger window means more data will need to be resynced, potentially causing a delay in the overall process.

    For example, if you are replicating three years worth of data:

    • A Data Request Window of 365 days means Airbyte makes 3 requests, each for a year. This is generally faster but risks needing to resync up to a year's data if the sync is interrupted.
    • A Data Request Window of 30 days means 36 requests, each for a month. This may be slower but minimizes the amount of data that needs to be resynced if an issue occurs.

    If you are unsure of which value to use, we recommend leaving this setting at its default value of 365 days.

  10. Click Set up source and wait for the tests to complete.

Supported sync modes​

The Stripe source connector supports the following sync modes:

  • Full Refresh
  • Incremental

Supported streams​

The Stripe source connector supports the following streams:

danger

Stripe API Restriction on Events Data: Access to the events endpoint is guaranteed only for the last 30 days by Stripe. If you use the Full Refresh Overwrite sync, be aware that any events data older than 30 days will be deleted from your target destination and replaced with the data from the last 30 days only. Use an Append sync mode to ensure historical data is retained. Please be aware: this also means that any change older than 30 days will not be replicated using the incremental sync mode. If you want all your synced data to remain up to date, please set up your sync frequency to no more than 30 days.

note

Since the Stripe API does not allow querying objects which were updated since the last sync, the Stripe connector uses the Events API under the hood to implement incremental syncs and export data based on its update date. However, not all the entities are supported by the Events API, so the Stripe connector uses the created field or its analogue to query for new data in your Stripe account. These are the entities synced based on the date of creation:

  • BalanceTransactions
  • CheckoutSessionLineItems (cursor field is checkout_session_expires_at)
  • Events
  • FileLinks
  • Files
  • SetupAttempts
  • ShippingRates

On the other hand, the following streams use the updated field value as a cursor:

  • Application Fees

  • Application Fee Refunds

  • Authorizations

  • Bank accounts

  • Cardholders

  • Cards

  • Charges

  • Checkout Sessions

  • Coupons

  • Credit Notes

  • Customer Balance Transactions

  • Customers

  • Disputes

  • Early Fraud Warnings

  • External Account Bank Accounts

  • External Account Cards

  • Invoice Items

  • Invoices

  • Payment Intents

  • Payouts

  • Promotion Codes

  • Persons

  • Plans

  • Prices

  • Products

  • Refunds

  • Reviews

  • Setup Intents

  • Subscription Schedule

  • Subscriptions

  • Top Ups

  • Transactions

  • Transfers

    :::

The Stripe API also provides a way to implement incremental deletes for a limited number of streams:

  • Bank Accounts
  • Coupons
  • Customers
  • External Account Bank Accounts
  • External Account Cards
  • Invoices
  • Invoice Items
  • Persons
  • Plans
  • Prices
  • Products
  • Subscriptions

Each record is marked with is_deleted flag when the appropriate event happens upstream.

:::

Data type mapping​

The Stripe API uses the same JSON Schema types that Airbyte uses internally (string, date-time, object, array, boolean, integer, and number), so no type conversions are performed for the Stripe connector.

Performance considerations​

The Stripe connector should not run into Stripe API limitations under normal usage. Create an issue if you see any rate limit issues that are not automatically retried successfully.

Changelog​

VersionDatePull RequestSubject
4.5.02023-10-2531327Use concurrent CDK when running in full-refresh
4.4.22023-10-2431764Base image migration: remove Dockerfile and use the python-connector-base image
4.4.12023-10-1831553Adjusted Setup Attempts and extended Checkout Sessions stream schemas
4.4.02023-10-0431046Added margins field to invoice_line_items stream.
4.3.12023-09-2730800Handle permission issues a non breaking
4.3.02023-09-2630752Do not sync upcoming invoices, extend stream schemas
4.2.02023-09-2130660Fix updated state for the incremental syncs
4.1.12023-09-1530494Fix datatype of invoices.lines property
4.1.02023-08-2929950Implement incremental deletes, add suggested streams
4.0.12023-09-0730254Fix cursorless incremental streams
4.0.02023-08-1529330Implement incremental syncs based on date of update
3.17.42023-08-1529425Revert 3.17.3
3.17.32023-08-0128911Revert 3.17.2 and fix atm_fee property
3.17.22023-08-0128911Fix stream schemas, remove custom 403 error handling
3.17.12023-08-0128887Fix Invoices schema
3.17.02023-07-2826127Add Prices stream
3.16.02023-07-2728776Add new fields to stream schemas
3.15.02023-07-0928709Remove duplicate streams
3.14.02023-07-0927217Add ShippingRates stream
3.13.02023-07-1828466Pin source API version
3.12.02023-05-2026208Add new stream Persons
3.11.02023-06-2627734License Update: Elv2 stream
3.10.02023-06-2227132Add CreditNotes stream
3.9.12023-06-2027522Fix formatting
3.9.02023-06-1927362Add new Streams: Transfer Reversals, Setup Attempts, Usage Records, Transactions
3.8.02023-06-1227238Add Topups stream; Add Files stream; Add FileLinks stream
3.7.02023-06-0627083Add new Streams: Authorizations, Cardholders, Cards, Payment Methods, Reviews
3.6.02023-05-2425893Add ApplicationFeesRefunds stream with parent ApplicationFees
3.5.02023-05-2022859Add stream Early Fraud Warnings
3.4.32023-05-1025965Fix Airbyte date-time data-types
3.4.22023-05-0425795Added CDK TypeTransformer to guarantee declared JSON Schema data-types
3.4.12023-04-2423389Add customer_tax_ids to Invoices
3.4.02023-03-2023963Add SetupIntents stream
3.3.02023-04-1225136Add stream Accounts
3.2.02023-04-1023624Add new stream Subscription Schedule
3.1.02023-03-1019906Expand tiers when syncing Plans streams
3.0.52023-03-2522866Specified date formatting in specification
3.0.42023-03-2424471Fix stream slices for single sliced streams
3.0.32023-03-1724179Get customer's attributes safely
3.0.22023-03-1324051Cache customers stream; Do not request transactions of customers with zero balance.
3.0.12023-02-2222898Add missing column to Subscriptions stream
3.0.02023-02-2123295Fix invoice schema
2.0.02023-02-1422312Another fix of Invoices stream schema + Remove http urls from openapi_spec.json
1.0.22023-02-0922659Set AvailabilityStrategy for all streams
1.0.12023-01-2722042Set AvailabilityStrategy for streams explicitly to None
1.0.02023-01-2521858Update the Subscriptions and Invoices stream schemas
0.1.402022-10-2018228Update the PaymentIntents stream schema
0.1.392022-09-2817304Migrate to per-stream states.
0.1.382022-09-0916537Fix redeem_by field type for customers stream
0.1.372022-08-1615686Fix the bug when the stream couldn't be fetched due to limited permission set, if so - it should be skipped
0.1.362022-08-0415292Implement slicing
0.1.352022-07-2114924Remove additionalProperties field from spec and schema
0.1.342022-07-0114357Add external account streams -
0.1.332022-06-0613449Add semi-incremental support for CheckoutSessions and CheckoutSessionsLineItems streams, fixed big in StripeSubStream, added unittests, updated docs
0.1.322022-04-3012500Improve input configuration copy
0.1.312022-04-2012230Update connector to use a spec.yaml
0.1.302022-03-2111286Minor corrections to documentation and connector specification
0.1.292022-03-0810359Improved performance for streams with substreams: invoice_line_items, subscription_items, bank_accounts
0.1.282022-02-0810165Improve 404 handling for CheckoutSessionsLineItems stream
0.1.272021-12-289148Fix date, arrival\_date fields
0.1.262021-12-218992Fix type events.request in schema
0.1.252021-11-258250Rearrange setup fields
0.1.242021-11-087729Include tax data in checkout_sessions_line_items stream
0.1.232021-11-087729Correct payment_intents schema
0.1.222021-11-057345Add 3 new streams
0.1.212021-10-076841Fix missing start_date argument + update json files for SAT
0.1.202021-09-306017Add lookback_window_days parameter
0.1.192021-09-276466Use start_date parameter in incremental streams
0.1.182021-09-146004Fix coupons and subscriptions stream schemas by removing incorrect timestamp formatting
0.1.172021-09-146004Add PaymentIntents stream
0.1.162021-07-284980Remove Updated field from schemas
0.1.152021-07-214878Fix incorrect percent_off and discounts data filed types
0.1.142021-07-094669Subscriptions Stream now returns all kinds of subscriptions (including expired and canceled)
0.1.132021-07-034528Remove regex for acc validation
0.1.122021-06-083973Add AIRBYTE_ENTRYPOINT for Kubernetes support
0.1.112021-05-303744Fix types in schema
0.1.102021-05-283728Update data types to be number instead of int
0.1.92021-05-133367Add acceptance tests for connected accounts
0.1.82021-05-113566Bump CDK connectors
Was this page helpful?