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
  • Stripe Account ID

Setup guide​

note

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 Calabi Connect 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 Calabi Connect.

Step 1: Set up Stripe​

  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.

Step 2: Set up the Stripe connector in Calabi Connect​

For Calabi Connect:​

  1. Log into your Calabi Connect account.
  2. Click Sources and then click + New source.
  3. On the Set up the source page, select Stripe from the Source type dropdown.
  4. Enter a name for the Stripe connector.

For Calabi Connect:​

  1. Navigate to the Calabi Connect dashboard.
  2. Click Sources and then click + New source.
  3. On the Set up the source page, select Stripe from the Source type dropdown.
  4. Enter a name for the Stripe connector.

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

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

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

  4. (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 Calabi Connect will not re-export data after it has been synced.
    • Setting the Lookback Window to 1 means Calabi Connect will re-export data from the past day, capturing any changes made in the last 24 hours.
    • Setting the Lookback Window to 7 means Calabi Connect will re-export and capture any data changes within the last week.

  5. (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 Calabi Connect 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.

  6. (Optional) For Streams with API Data Retention Validation, select which streams should validate cursor age against Stripe's 30-day event retention period. When a selected stream's cursor is older than 30 days, the connector performs a full refresh to avoid missing data due to the Events API retention limit. Streams not selected here will always use incremental sync regardless of cursor age.

By default, no streams are selected — all streams will use incremental sync without cursor age validation. You can add streams to this list based on your account's usage patterns. For high-usage streams like charges, invoice_items, invoice_line_items, invoices, payment_intents, and payouts, enabling cursor age validation is recommended since a stale cursor likely indicates missed data rather than normal inactivity.

Streams like customers, subscriptions, products, and plans may not need validation because some accounts legitimately have no new records in 30+ days, and forcing a full refresh would be unnecessary.

  1. (Optional) For Number of Concurrent Threads, enter the number of worker threads to use for the sync. The default is 10. You can set this to any value between 2 and 100. Higher values increase throughput but also increase API usage. The effective upper bound depends on your Stripe account's rate limits.

  2. (Optional) For Max Number of API Calls per Second, enter the maximum number of API requests per second the connector is allowed to make. If not specified, the connector defaults to 25 calls per second for test and sandbox API keys and 100 calls per second for live API keys. This value cannot exceed Stripe's actual rate limits.

  3. 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:

Entity-Relationship Diagram (ERD)​

Data type map​

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

Stripe API version​

This connector uses Stripe API version 2022-11-15. Stripe returns data shaped according to this version regardless of the version configured in your Stripe dashboard. For details on Stripe API versioning, see Stripe API upgrades.

Limitations & Troubleshooting​

Expand to see details about Stripe connector limitations and troubleshooting.

Connector limitations​

Rate limiting​

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

warning

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.

Cursor age validation and automatic full refresh​

To prevent data loss caused by the 30-day Events API retention limit, the connector can validate the age of each stream's cursor before choosing between incremental and full refresh sync. If a stream's cursor is older than 30 days, the connector automatically falls back to a full refresh for that stream instead of using the Events API, which would only return the last 30 days of data.

This behavior is configurable via the "Streams with API Data Retention Validation" setting (see setup guide step 10). Only streams listed in this setting will have their cursor age validated. By default, no streams are selected — all streams will use incremental sync without cursor age validation.

For high-usage streams like Charges, Invoice Items, Invoice Line Items, Invoices, Payment Intents, and Payouts, enabling cursor age validation is recommended since a stale cursor likely indicates missed data rather than normal inactivity. Streams like Customers, Subscriptions, Products, and Plans may not need validation because some accounts legitimately have no new records in 30+ days, making a full refresh unnecessary.

You can customize which streams have cursor age validation by modifying the Streams with API Data Retention Validation list in your connection settings. The full list of streams eligible for cursor age validation is:

  • Accounts
  • Application Fees
  • Application Fee Refunds
  • Authorizations
  • Bank Accounts
  • Cardholders
  • Charges
  • Checkout Sessions
  • Coupons
  • Credit Notes
  • Customers
  • Disputes
  • Early Fraud Warnings
  • External Account Bank Accounts
  • External Account Cards
  • Invoice Items
  • Invoice Line Items
  • Invoices
  • Payment Intents
  • Payment Methods
  • Payouts
  • Persons
  • Plans
  • Prices
  • Products
  • Promotion Codes
  • Refunds
  • Reviews
  • Setup Intents
  • Subscription Items
  • Subscription Schedule
  • Subscriptions
  • Top Ups
  • Transactions
  • Transfers
warning

Important: If a stream is removed from the validation list and its cursor becomes stale (older than 30 days), the connector will continue using the Events API for incremental sync, which only returns the last 30 days of data. This may result in missed updates for records older than 30 days. Only remove streams from the validation list if you are confident that a stale cursor is acceptable for your use case.

Troubleshooting​

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:

  • Balance Transactions
  • Customer Balance Transactions
  • Events
  • File Links
  • Files
  • Setup Attempts
  • Shipping Rates
  • Transfer Reversals

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

note

updated is an artificial cursor field introduced by Calabi Connect for the Incremental sync option.

  • Accounts
  • Application Fees
  • Application Fee Refunds
  • Authorizations
  • Bank Accounts
  • Cardholders
  • Cards
  • Charges
  • Checkout Sessions
  • Checkout Session Line Items (cursor field is checkout_session_updated)
  • Coupons
  • Credit Notes
  • Customers
  • Disputes
  • Early Fraud Warnings
  • External Account Bank Accounts
  • External Account Cards
  • Invoice Items
  • Invoice Line Items
  • Invoices
  • Payment Intents
  • Payment Methods
  • Payouts
  • Payout Balance Transactions
  • Promotion Codes
  • Persons
  • Plans
  • Prices
  • Products
  • Refunds
  • Reviews
  • Setup Intents
  • Subscription Schedule
  • Subscription Items
  • Subscriptions
  • Top Ups
  • Transactions
  • Transfers

Incremental deletes​

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.

  • Check out common troubleshooting issues for the Stripe source connector on our Calabi Connect Forum.