Stripe Real-time

This connector captures data from Stripe's API into Estuary collections.

It is available for use in the Estuary web application. For local development or open-source workflows, ghcr.io/estuary/source-stripe-native:dev provides the latest version of the connector as a Docker image. You can also follow the link in your browser to see past image versions.

Data synchronization

The Stripe connector uses a combination of real-time event streaming and periodic backfills to ensure data consistency. Most streams capture changes in real-time via Stripe's Events API, but some streams require scheduled backfills due to limitations in Stripe's event generation.

Streams requiring scheduled backfills

The following streams are configured with daily scheduled backfills (at midnight UTC) to ensure eventual consistency:

Stream	Reason for Scheduled Backfill
Accounts	Stripe's event generation for accounts is inconsistent. While webhooks may receive account.updated events, the Events API endpoint may not reliably surface them. This stream uses the list endpoint directly for incremental capture.
Persons	Events for person records may not consistently appear in Stripe's Events API. Persons are child records of connected accounts.
ExternalAccountCards	Events for external account cards may not consistently appear in Stripe's Events API. These are child records accessed via connected account endpoints.
ExternalBankAccount	Events for external bank accounts may not consistently appear in Stripe's Events API. These are child records accessed via connected account endpoints.

These scheduled backfills provide guaranteed eventual consistency by periodically re-querying the list endpoints, ensuring that no data is missed even if Stripe fails to generate corresponding events.

Stripe API limitations

The connector handles several known limitations of the Stripe API:

• Inconsistent event generation: Stripe's Events API may not surface events for certain resource types, even when corresponding webhooks are delivered. This particularly affects account-related resources.
• Connected account child streams: Resources like Persons, ExternalAccountCards, and ExternalBankAccount must be queried through parent account endpoints (e.g., /v1/accounts/{id}/persons), requiring per-account queries when capturing connected accounts.
• Events API retention: Stripe retains events for 30 days. While other resources can backfill beyond this window using their own list endpoints, the Events stream is limited to the most recent 30 days regardless of the configured start_date. The connector gracefully handles this by treating Stripe's retention expiry as a completed backfill.

Supported data resources

The following data resources are supported through the Stripe API:

• Accounts
• Application fees
• Application fees refunds
• Balance transactions
• Bank accounts
• Cards
• Charges
• Checkout sessions
• Checkout sessions line items
• Coupons
• Credit notes
• Credit notes line items
• Customer balance transactions
• Customers
• Disputes
• Early fraud warning
• Events
• External account cards
• External bank account
• Files
• File links
• Invoice items
• Invoice line items
• Invoices
• Payment intents
• Payment methods
• Payouts
• Persons
• Plans
• Products
• Promotion codes
• Refunds
• Reviews
• Setup attempts
• Setup intents
• Subscription items
• Subscriptions
• Subscription schedule
• Top ups
• Transfer reversals
• Transfers
• Usage records

By default, each resource is mapped to an Estuary collection through a separate binding.

Connected Accounts

This connector can capture data from Stripe Connected Accounts. To enable this feature, set the capture_connected_accounts property to true in your configuration. When enabled, each document will include an account_id field that identifies which account the data belongs to.

How connected account capture works

When capture_connected_accounts is enabled, the connector handles different streams in different ways:

• Accounts stream: Always queries from the platform account using the /v1/accounts endpoint to list all connected accounts. This stream does not create per-account subtasks.
• Most other streams: Create per-account subtasks that query each connected account's data using the Stripe-Account header to access account-specific resources.
• Child streams (Persons, ExternalAccountCards, ExternalBankAccount): Query each connected account's child resources via parent endpoints (e.g., /v1/accounts/{id}/persons).

This architecture ensures efficient data capture while respecting Stripe's API access patterns for connected accounts.

Data consistency considerations

For captures with many connected accounts, the connector uses a priority-based rotation system to fairly process accounts based on how recently they were synced. Combined with scheduled backfills for streams with unreliable event generation, this ensures eventual consistency across all connected accounts.

Prerequisites

• An API Key for your Stripe account. This usually starts with sk_live_ or sk_test_ depending on your environment. Manage your Stripe keys in their developer dashboard.

Configuration

You configure connectors either in the Estuary web app, or by directly editing the catalog specification file. See connectors to learn more about using connectors. The values and specification sample below provide configuration details specific to the Stripe source connector.

Properties

Endpoint

Property	Title	Description	Type	Required/Default
/credentials	Credentials		object	Required
/credentials/credentials_title	Credentials Title	The type of authentication. Currently only accepts Private App Credentials.	string	Private App Credentials
/credentials/access_token	Access Token	Stripe API key. Usually starts with sk_live_.	string	Required
/start_date	Start Date	UTC date and time in the format YYYY-MM-DDTHH:MM:SSZ. Only data generated after this date will be replicated.	string	30 days before the present date
/capture_connected_accounts	Capture Connected Accounts	Whether to capture data from connected accounts.	boolean	false

Bindings

Property	Title	Description	Type	Required/Default
/stream	Stream	Resource from Stripe from which collections are captured.	string	Required
/syncMode	Sync Mode	Connection method.	string	Required

Sample

captures:
  ${PREFIX}/${CAPTURE_NAME}:
    endpoint:
      connector:
        image: ghcr.io/estuary/source-stripe-native:dev
        config:
            credentials:
                credentials_title: Private App Credentials
                access_token: <secret>
            start_date: 2025-01-01T00:00:00Z
            capture_connected_accounts: true
    bindings:
      - resource:
          stream: charges
          syncMode: incremental
        target: ${PREFIX}/charges
      - resource:
          stream: customer_balance_transactions
          syncMode: full_refresh
        target: ${PREFIX}/customerbalancetransactions
    {...}