Release Status Released Supported By Stitch
Availability Free Status Page Stripe Status Page
Default Historical Sync 1 year Default Replication Frequency 30 minutes
Whitelisting Unsupported Destination Incompatibilities Possible incompatibilities. Learn more.

Connecting Stripe

Connecting your Stripe data to Stitch is a four-step process:

  1. Add Stripe as a Stitch data source
  2. Define the Historical Sync
  3. Define the Replication Frequency
  4. Authorize Stitch to access Stripe

Prerequisites

The user who sets up the integration must have Admin permissions in Stripe. If you don’t have these permissions, please loop in a Stripe admin before continuing.

Add Stripe as a Stitch Data Source

  1. Sign into your Stitch account.
  2. On the Stitch Dashboard page, click the Add Integration button.

  3. Click the Stripe icon.

  4. Enter a name for the integration. This is the name that will display on the for the integration; it’ll also be used to create the schema in your destination.

    For example, the name “Stitch Stripe” would create a schema called stitch_stripe in the destination. Note: Schema names cannot be changed after you save the integration.

Define the Historical Sync

The Sync Historical Data setting will define the starting date for your Stripe integration. This means that data equal to or newer than this date will be replicated to your data warehouse.

Change this setting if you want to sync data beyond Stripe’s default setting of 1 year. For a detailed look at historical syncs, check out the Syncing Historical SaaS Data guide.

Define the Replication Frequency

The Replication Frequency controls how often Stitch will attempt to extract data from your Stripe integration.

Note: This setting only affects the frequency of data extraction from Stripe, not the interval at which data is loaded into your data warehouse. For example: a one (1) minute Replication Frequency means Stitch will attempt to extract data every minute, but loading the extracted data may take longer than this.

Use the Default Frequency

To use the default Replication Frequency (30 minutes), leave the Use integration default box checked and click Save Integration to create the integration.

Customize the Frequency

To adjust the Replication Frequency:

  1. Uncheck the Use integration default checkbox. A slider with various frequencies will display.
  2. Click the desired frequency on the slider.
  3. Click Save Integration to create the integration.

To help prevent overages, consider setting the integration to replicate less frequently. See the Understanding & Reducing Your Row Usage guide for tips on reducing your usage.

Authorize Stitch to Access Stripe

Lastly, you’ll be directed to Stripe’s website to complete the setup. Remember you must have Admin permissions in Stripe for the connection to be successful.

  1. A screen asking for authorization to Stripe will display. Note that Stitch will only ever read your data.
  2. Click Sign in with Stripe to connect.
  3. Enter your Stripe credentials and click Sign into your account.
  4. After the authorization process successfully completes, you’ll be redirected back to Stitch.
  5. Click All Done.

Stripe’s Intial Replication Job

After you finish setting up Stripe, you might see its Sync Status show as Pending on either the Stitch Dashboard or in the Integration Details page.

For a new integration, a Pending status indicates that Stitch is in the process of scheduling the initial replication job for the integration. This may take some time to complete.


Replicating Stripe Data

Stripe’s API uses an event-based approach to create and update data points. Because this approach can create large numbers of records and drive up your row usage, it’s important to understand how Stripe’s API works and how Stitch queries it for data as a result.

In this section, we’ll be using the word “object” to refer to the entities (ex: customer) contained within an API.

Updates in “Traditional” APIs

When we talk about “traditional” APIs, we mean the kind that only have a single type of object. In this case, when a record is updated, only that object is “notified.”

If, for example, a customer email address is updated, only the customers object would be affected.

By this we mean that only the row in the customers table for that particular account would change. The email field would show the new email address and the updated_at field would show the time the change - or event - happened.

To summarize: one change = one row.

Updates in Stripe’s API

Stripe works a little differently than the traditional API we outlined above: it’s designed to use a change - or an event - to one object to update another.

Instead of having just one object like customers that is directly updated, Stripe’s API has two: a “parent” object (customers) and an “update” object (update_customers).

Let’s use the updated customer email example again. If a customer email address is updated, several things will happen in Stripe’s API as a result of its event-based update method:

  1. A row will be created in the stripe_events table to record the event details,
  2. A row will be created in the stripe_update_customers table,
  3. The row in the stripe_customers table for that customer’s account will be updated based on the corresponding data in stripe_update_customers

In this case, one change doesn’t equate to a single row. That single change resulted in the creation of three rows.

Additionally, note that:

  • Stitch doesn’t persist the update objects to your data warehouse as tables, but still queries them to be able to update the parent object tables accordingly.
  • Updates to events that update other events aren’t currently supported. For example: if a dispute is updated, the related charge in the stripe_charges table will not be updated.

    You can, however, find this info in the stripe_events table.

Impact on Row Counts

Because a single event can result in creating or updating multiple rows, Stripe can potentially drive up your row usage. Additionally, Stripe deeply nests their data. If you use a data warehouse that doesn’t natively support nested structures, Stitch will de-nest these records and create subtables, resulting in a greater number of replicated rows.

To counter this, we recommend setting the Replication Frequency to something less frequent - like every 24 hours instead of every 30 minutes - to help keep your row count down and prevent overages.


Stripe Schema

Stitch's Stripe integration includes these tables:


stripe_balance_history

Replication Method: Incremental
Primary Key: id
Contains Nested Structures?: Yes

The stripe_balance_history table contains info about transactions have have contributed to your Stripe account balance, including charges, transfers, etc.

Table Info & Attributes

stripe_balance_history & Nested Structures

This table contains nested structures. If you use a data warehouse that doesn't natively support nested structures, some of the attributes listed below may be in a subtable.

These items are marked with a *

stripe_balance_history Attributes

While we try to include everything Stripe has here, this may not be a full list of attributes. Refer to Stripe's documentation for a full list and description of each attribute.

  • Balance History ID (id)

  • amount

  • available_on

  • created

  • currency

  • description

  • fee

  • fee_details*

  • net

  • source__sourced_transfers__data*

  • status

  • type

stripe_charges

Replication Method: Incremental
Primary Key: id
Contains Nested Structures?: No

The stripe_charges table contains info about charges to credit and debit cards.

Note that charge dispute data is not included in this table. See Table Info & Attributes for details.

Table Info & Attributes

Charge Dispute Support

Due to the current structure of our Stripe integration and how updates work in the Stripe API, records in this table will not be updated if a related dispute is updated.

You can, however, find this info in the stripe_events table.

stripe_charges Attributes

While we try to include everything Stripe has here, this may not be a full list of attributes. Refer to Stripe's documentation for a full list and description of each attribute.

  • Charge ID (id)

  • received_at

  • amount

  • amount_refunded

  • balance_transaction

  • captured

  • created

  • currency

  • customer_id

  • description

  • dispute_id

  • failure_code

  • failure_message

  • fraud_details_stripe_report

  • fraud_details_user_report

  • invoice_id

  • paid

  • receipt_email

  • receipt_number

  • refunded

  • statement_descriptor

  • status

stripe_coupons

Replication Method: Incremental
Primary Key: id
Contains Nested Structures?: No

The stripe_coupons table contains info about percent or amount-off discounts that may be applied to a customer. Note that coupons only apply to invoices; they don't apply to one-off charges.

Table Info & Attributes

stripe_coupons Attributes

While we try to include everything Stripe has here, this may not be a full list of attributes. Refer to Stripe's documentation for a full list and description of each attribute.

  • Coupon ID (id)

  • received_at

  • created

  • duration

  • duration_in_months

  • metadata__quota_calls

  • metadata__quota_level

  • metadata__service

  • percent_off

  • times_redeemed

  • valid

stripe_customers

Replication Method: Incremental
Primary Key: id
Contains Nested Structures?: Yes

The stripe_customers table contains info about your Stripe customers. This table allows you to track multiple charges associated with a single customer.

Table Info & Attributes

stripe_customers & Nested Structures

This table contains nested structures. If you use a data warehouse that doesn't natively support nested structures, some of the attributes listed below may be in a subtable.

These items are marked with a *

stripe_customers Attributes

While we try to include everything Stripe has here, this may not be a full list of attributes. Refer to Stripe's documentation for a full list and description of each attribute.

  • Customer ID (id)

  • received_at

  • account_balance

  • created

  • currency

  • delinquent

  • description

  • discount_id

  • email

  • metadata__id

  • metadata__extra

  • metadata__name

  • metadata__settings

  • workspace

stripe_events

Replication Method: Incremental
Primary Key: id
Contains Nested Structures?: Yes

The stripe_events table contains info about events. When an interesting event occurs, a new event object is created. For example, when a charge succeeds a charge.succeeded event is created; or, when an invoice can't be paid, an invoice.payment_failed event is created.

Table Info & Attributes

stripe_events & Nested Structures

This table contains nested structures. If you use a data warehouse that doesn't natively support nested structures, some of the attributes listed below may be in a subtable.

These items are marked with a *

Event Replication

The stripe_events table is sort of a “grab bag” of all events across all endpoints, or tables. For every event that takes place on a parent object, a row will be added to the table.

For example: If a customer account is updated, you’ll see the latest state of the customer’s account info in the stripe_customers table. You’ll also see a row in this table for the actual update event itself.

stripe_events Attributes

While we try to include everything Stripe has here, this may not be a full list of attributes. Refer to Stripe's documentation for a full list and description of each attribute.

  • Event ID (id)

  • created

  • data__object__business_url

  • data__object__charges_enabled

  • data__object__country

  • data__object__default_currency

  • data__object__default_source

  • data__object__delinquent

  • data__object__description

  • data__object__details_submitted

  • data__object__discount

  • data__object__display_name

  • data__object__email

  • data__object__id

  • data__object__managed

  • data__object__object

  • data__object__shipping

  • data__object__sources__data*

  • data__object__statement_descriptor

  • data__object__subscriptions__data*

  • data__object__support_phone

  • data__object__timezone

  • data__object__transfers_enabled

  • livemode

  • object

  • pending_webhooks

  • request

  • type

stripe_invoice_items

Replication Method: Incremental
Primary Key: id
Contains Nested Structures?: No

The stripe_invoice_items table contains info about items contained in customer invoices.

Table Info & Attributes

stripe_invoice_items Attributes

While we try to include everything Stripe has here, this may not be a full list of attributes. Refer to Stripe's documentation for a full list and description of each attribute.

  • Invoice Item ID (id)

  • received_at

  • amount

  • currency

  • customer_id

  • date

  • description

  • discountable

  • invoice_id

  • period_end

  • period_start

  • plan_id

  • proration

  • quantity

  • bigint

  • subscription_id

stripe_invoices

Replication Method: Incremental
Primary Key: id
Contains Nested Structures?: Yes

The stripe_invoices table contains info about customer invoices. Note that this does not include upcoming invoices - see the Table Info section for details.

Table Info & Attributes

stripe_invoices & Nested Structures

This table contains nested structures. If you use a data warehouse that doesn't natively support nested structures, some of the attributes listed below may be in a subtable.

These items are marked with a *

Upcoming Invoices

Stitch’s Stripe integration doesn’t currently replicate upcoming invoices, which Stripe defines as “the next upcoming invoice.”

This is due to the way Stripe generates and assigns IDs to invoices. Existing invoices have IDs while upcoming invoices do not. As Stitch uses the id column to identify new data for replication, if an invoice doesn’t have an ID, Stitch will be unable to replicate it.

stripe_invoices Attributes

While we try to include everything Stripe has here, this may not be a full list of attributes. Refer to Stripe's documentation for a full list and description of each attribute.

  • Invoice ID (id)

  • received_at

  • amount_due

  • attempt_count

  • attempted

  • charge_id

  • closed

  • currency

  • customer_id

  • date

  • discount_id

  • ending_balance

  • forgiven

  • lines*

  • next_payment_attempt

  • paid

  • period_end

  • period_start

  • receipt_number

  • starting_balance

  • subscription_id

  • subtotal

  • total

  • webhooks_delivered_at

stripe_plans

Replication Method: Incremental
Primary Key: id
Contains Nested Structures?: No

The stripe_plans table contains pricing information for different products and feature levels on your site. For example, you may have a $10/month plan for basic features and a $20/month plan for premium features.

Table Info & Attributes

stripe_plans Attributes

While we try to include everything Stripe has here, this may not be a full list of attributes. Refer to Stripe's documentation for a full list and description of each attribute.

  • Plan ID (id)

  • received_at

  • amount

  • created

  • currency

  • interval

  • interval_count

  • metadata__available

  • metadata__grandfathered

  • metadata__overage_rows_fee

  • metadata__overage_rows_per

  • metadata__quota_calls

  • metadata__quota_level

  • metadata__quota_rows

  • metadata__service

  • metadata__tier

  • name

  • statement_descriptor

  • trial_period_days

stripe_subscriptions

Replication Method: Incremental
Primary Key: id
Contains Nested Structures?: No

The stripe_subscriptions table contains the details of subscription plans your customers belong to.

Table Info & Attributes

stripe_subscriptions Attributes

While we try to include everything Stripe has here, this may not be a full list of attributes. Refer to Stripe's documentation for a full list and description of each attribute.

  • Subscription ID (id)

  • received_at

  • cancel_at_period_end

  • current_period_end

  • current_period_start

  • customer_id

  • discount_id

  • metadata__quota_calls

  • metadata__quota_rows

  • plan_id

  • quantity

  • start

  • status

  • trial_end

  • trial_start

  • canceled_at

stripe_transfers

Replication Method: Incremental
Primary Key: id
Contains Nested Structures?: Yes

The stripe_transfers table contains info about your transfers. A transfer is created any time Stripe sends you money or you initiiate a transfer to a connected account, including bank accounts and debit cards.

Table Info & Attributes

stripe_transfers & Nested Structures

This table contains nested structures. If you use a data warehouse that doesn't natively support nested structures, some of the attributes listed below may be in a subtable.

These items are marked with a *

stripe_transfers Attributes

While we try to include everything Stripe has here, this may not be a full list of attributes. Refer to Stripe's documentation for a full list and description of each attribute.

  • Transfer ID (id)

  • amount

  • amount_reversed

  • application_fee

  • balance_transaction

  • created

  • currency

  • date

  • description

  • destination

  • destination_payment

  • failure_code

  • failure_message

  • livemode

  • medata__method

  • metadata__recipient

  • metadata__reversals*

  • reversed

  • source_transaction

  • source_type

  • statement_descriptor

  • status

  • type

stripe_transfer_transactions

Replication Method: Incremental
Primary Key: transfer_id:transaction_id
Contains Nested Structures?: No

The stripe_transfer_transactions table contains transfer and transaction IDs, which will allow you to join transfers with the transactions in the stripe_balance_history table.

Table Info & Attributes

stripe_transfer_transactions Attributes

While we try to include everything Stripe has here, this may not be a full list of attributes. Refer to Stripe's documentation for a full list and description of each attribute.

  • transfer_id

  • transaction_id



Questions? Feedback?

Did this article help? If you have questions or feedback, feel free to submit a pull request with your suggestions, open an issue on GitHub, or reach out to us.