Stripe

Enrich Stripe with data from your warehouse to create, manage, and drive revenue analysis from your customers, products, prices, subscriptions, and invoices resources.

Overview

The Stripe integration allows you to sync data from your warehouse based on models that you define.
Create and schedule syncs to the supported resources to keep your data up-to-date in Stripe to facilitate the creation of records with associations, or fulfill your business requirements.

Stripe offers a multitude of integrations, which comes at the cost of requiring the user to make precise design decisions when choosing one integration over another. The Hightouch Stripe integration strives to make this process as painless as possible by allowing you to:

1. Extract and structure data from your warehouse based on models that you define to fit your Stripe integration needs.
2. Sync to supported core resources that are required for Stripe integrations.

Getting Started

Step 1: Connect to Stripe

Retrieve your API Token from Stripe.

1. Log in to Stripe.
2. Visit your Account Dashboard Homepage.
3. Copy your Secret key.

If you haven't created your API key, Stripe will require you to enter your business details on the Stripe Onboarding page.

Add Stripe as a destination in Hightouch

1. Log in to Hightouch or create a free Hightouch account
2. Click on Destinations in the left sidebar
3. Click on Add destination in the top right corner
4. Select Stripe in the destination catalog and click Continue to proceed
5. Paste your Secret key into the API key field and click Continue to proceed
6. Give your destination a name and unique slug (e.g., Stripe Production” and Stripe-production)
7. Click Finish to create your Stripe destination!

Step 2: Connect to your data source

Hightouch sits on top of your data warehouse and can read from Snowflake, Redshift, BigQuery, Databricks, Postgres, MySQL, and many other data sources. You can even fetch data from Google Sheets and Airtable. Hightouch can help activate your data wherever it resides.

We've written dedicated guides for each supported data source. Take your pick:

• Connect to Airtable
• Connect to Amazon Athena
• Connect to Amazon Redshift
• Connect to Clickhouse
• Connect to Databricks
• Connect to Elasticsearch
• Connect to Firebolt
• Connect to Google BigQuery
• Connect to Google Sheets
• Connect to Looker
• Connect to Metabase
• Connect to MySQL
• Connect to Palantir Foundry
• Connect to PostgreSQL
• Connect to Rockset
• Connect to SFTP
• Connect to Snowflake
• Connect to SQL Server
• Connect to Trino

Connect to a sample database instead

Waiting for credentials to your data warehouse? No problem! You can connect to one of our sample databases to get started right away. For the rest of this tutorial, we'll use our demo Postgres database, which contains a users table with names, emails, locations, and other user attributes. This sample source is available when you log in for the first time—no setup required.

Next, we'll write a SQL query to define which users should be synced to our Stripe customers resource. You can follow the same pattern to sync to other support Stripe resources,

Step 3: Create a model

In Hightouch, a model represents a query that filters or transforms the records in your data source. Models are used to determine exactly which records to sync between sources and destinations.

When you connect to a data warehouse, your models will probably be written in SQL. You can also import models from tools like dbt and Looker.

In this example, we'll keep it simple. Suppose you want to sync all your customers to Stripe. To accomplish this, you'll want to create a model that looks like this:

SELECT * FROM users;

1. Click on Models in the left sidebar.
2. Click on Add model in the top right corner.
3. Select Demo Database as your source and click Continue to proceed.
4. Select SQL Editor as your modeling method.
5. Paste the SQL query from above into the editor on the left side of the page.
6. Click Preview to execute the query.
7. Click Continue to proceed.
8. Give your model a name and unique slug (e.g., "All Users" and all-users).
9. Select id as the primary key for your model.
10. Click Finish to create your model! We just created a model using a SQL query that retrieves all our current users. Next, we'll configure our sync to add these users to the Stripe customers resource.

Step 4: Create a sync

1. Click on Syncs in the left sidebar.
2. Click on Add sync in the top right corner.
3. Select All Users as your model and click Continue to proceed.
4. Select Stripe as your destination and click Continue to proceed.
5. Give your destination a name and unique slug (e.g., "Stripe All Customers Sync" and stripe-all-customers-sync) and click Finish to proceed.
6. Select Customers from the object dropdown.
7. Select Upsert from the mode radio options.
8. Select email and we will map it to Customer Email from the external ID mapping field.
9. Select first_name and we will map it to Name in the fields that we'd like to sync to Stripe.
10. Click Continue to proceed to the last step.
11. Select Interval to tell your sync to run on a set interval.
12. Configure your sync schedule to run every 5 minutes.
13. Click Finish to create your sync!

And we are done. Your Stripe sync configuration is complete!

Things to keep in mind

For some Stripe resources, certain fields are conditionally required based on values of fields in the record that is being synced.

We strongly recommend using Stripe's API documentation as reference while creating your Hightouch configuration form for each of the resources and structure your model accordingly.

• Customer Object
• Product Object
• Price Object
• Subscription Object
• Invoice Object
• Invoice Item Object
• Quote Object

Sync Configuartion

Object Selection

Hightouch supports syncing to the following Stripe resources:

• Customers
• Products
• Prices
• Subscriptions
• Invoices
• Invoice Items
• Quotes

Sync Modes

This integration supports Upsert and Update modes for all supported resources.

In Upsert mode, records that are not found in Stripe given the provided identifier will be inserted. And existing records will be updated.

In Update mode, existing records will be updated. No new records will be inserted.

Record Matching

Customers

In Upsert mode, records can be matched from your source to your Stripe workspace by Customer Email.

In Update mode, records can be matched from your source to your Stripe workspace by Stripe Customer ID or by Customer Email.

Products

In Upsert and Update mode, records can be matched from your source to your Stripe workspace by Product ID.

Prices

In Upsert and Update mode, records can be matched from your source to your Stripe workspace by Price ID.

Subscriptions

In Upsert and Update mode, records can be matched from your source to your Stripe workspace by Subscription ID.

Invoices

In Upsert and Update mode, records can be matched from your source to your Stripe workspace by Invoice ID.

Invoice Items

In Upsert and Update mode, records can be matched from your source to your Stripe workspace by Invoice Item ID.

Quotes

In Upsert and Update mode, records can be matched from your source to your Stripe workspace by Quote ID.

Field Mapping

Hightouch allows you to sync columns from your source to the supported Stripe resouces.

Associations

For Subscription, Invoice, and Invoice Item resources, Hightouch can perform a reference look-up for the Customer ID field.

After selecting the Customer ID Stripe field from mappings, a reference input will be rendered. Similar to the Customer resource, Hightouch can conduct a look-up using a Customer Emailand the respective Customer ID will be used in the request to Stripe.

If a look-up is not required, the follow configuration will bypass the look-up step.

Custom Field Mapping

Hightouch allows you to set custom attributes. Any mappings from this section will be synced to the metadata of each record.

Delete Records

The delete section allows you to configure how the sync behaves when the Hightouch sync engine recognizes that a record has been removed from your source.

In the Stripe integration, deletes are only supported in Upsert mode.

Customers

In the Customers resource, you can either:

• Do Nothing.
• Delete the associated customer record.

Products

In the Products resource, you can either:

• Do Nothing.
• Delete the associated product record.

Prices

In the Prices resource, deletion is not supported.

Subscriptions

In the Subscriptions resource, you can either:

• Do Nothing.
• Cancel the associated subscription.

Invoices

In the Invoices resource, you can either:

• Do Nothing.
• Delete the associated invoice. Deletion is only supported if the associated invoice is a draft; if the invoice is not a draft, Hightouch will do nothing to the existing record in Stripe.

Invoice Items

In the Invoice Items resource, you can either:

• Do Nothing.
• Delete the associated invoice item. Deletion is only supported if the associated invoice item is not attached to an invoice or if it is attached to a draft invoice, otherwise, Hightouch will do nothing to the existing invoice item in Stripe.

Quotes

In the Quotes resource, you can either:

• Do Nothing.
• Delete the associated quote.

Troubleshooting

Common errors

• Common errors that we've noticed are mainly Stripe API errors when data from your model is structured incorrectly or expected data is missing.
• For some Stripe resources, certain fields are conditionally required based on values of fields in the record that is being synced, so an error will be thrown if these fields are missing.
• We strongly recommend using Stripe's API documentation as reference while creating your Hightouch configuration form for each of the resources and model your data accordingly.
• You can use the Hightouch debugger to learn about errors that are thrown.
• Reach out to us for assistance. We are here to help!

Use the Hightouch debugger

Hightouch provides full visibility into the Stripe API calls made during each of your sync runs. We recommend reading our article on debugging tips and tricks.

Set up sync alerts

Hightouch can alert you of any sync issues via Slack, PagerDuty, SMS, and/or email. For details, please visit our article on alerting.