Stripe Reference

Stripe API key

To sync your Stripe data to your Sequin database, you just need to provide us with a Stripe API key.

Create a Stripe API key

While you can supply Sequin with a standard key, we recommend you provision us with a restricted key like so:

Step 1: Login to your Stripe dashboard and ensure you are in the correct account.

Step 2: In the Restricted keys section click the + Create restricted key button.

Step 3: In the top left, name the key something like "Sequin."

Step 4: Under the "Permissions" column, select "Read" for every row except "All webhook resources." For "All webhook resources," select "Write."

Step 5: Click Create.

Listed out, Sequin needs the following permissions:

  • All core resource: Read
  • All checkout resources: Read
  • All bulling resources: Read
  • All connect resources: Read
  • All orders resources: Read
  • All issuing resources: Read
  • All reporting resources: Read
  • All webhook resources: WRITE
  • CLI permissions: None

Test keys

To get familiar with how Sequin works with Stripe, you can always start by using your Stripe test key. Sequin resources that use a Stripe test API key are free to use.

To retrieve your Stripe test key, follow these steps:

Step 1: Login to your Stripe dashboard.

Step 2: Toggle to view your Stripe test data by flipping the View test data switch.

Step 3: Click the Reveal test key button.

Stripe database schema

Your Sequin database will contain all your Stripe data. We're still working on an entity-relationship diagram (ERD) that you can use as a reference. We have one in progress here, but it's not for the faint of heart!

The Stripe Sigma documentation is a helpful resource, as naturally a lot of our names and structure are similar.

Upcoming Objects

Stripe has several object types, such as `Upcoming Invoices`, which are only generated on-demand as previews.

Since these objects are not persistent in Stripe, they don't have an `id`. In this case, Sequin uses the `customer_id` or `subscription_id` as a proxy for primary key. For example, the `upcoming_customer_invoice` table uses `customer_id` as the primary key. The `upcoming_subscription_invoice` table uses `subscription_id` as the primary key.

Unlike most objects, Stripe doesn't create `Events` for changes to these objects. Instead, Sequin detects other events that are likely to trigger updates on these objects and immediately fetches an updated version from Stripe's `/v1/invoices/upcoming` endpoint to keep your synced data up-to-date.

You can see all Sequin's table schemas related to Upcoming Invoices here

Stripe data types


Stripe stores currency amounts in the smallest unit. Your Sequin data does the same.

So as an example, $10.00 USD will be stored as an integer value of `1000` in your Sequin database.


Currency types are stored as ISO 4217 Currency Codes in lower case.

JSON blobs

Some nested data structures are stored as type `JSONB` in your Sequin database.

The syncing process

Sequin workers first backfill your database with all your Stripe data by paginating through all Stripe API endpoints.

Then, after the backfill, Sequin workers poll Stripe's `/events` endpoint twice per second to ingest any creates, updates, or deletes.

You can read more about how Sequin's syncing process for Stripe works on our blog.


Your Sequin database is read-only.

We advocate for a one-way data flow: read from your Sequin database, write to Stripe's API. Any changes will flow down to your Sequin database for you to read again.

Sometimes, you want to make sure that changes that you just wrote have been synced to your database. We call this scenario a read-after-write.

To do so, you can call our wait endpoint. To find the URL for your sync's wait endpoint, just click "Connect" in the Sequin console. Wait endpoints take this form:

Where `kind` is the platform, like `stripe` or `close`. `id` is the Sequin ID of your sync.

A wait endpoint only returns after we've confirmed your database is up-to-date. So, you can weave it into your workflow like this:

  1. Make a write request directly to the API
  2. Call your sync's wait endpoint
  3. When #2 completes, read from your Sequin database

Here's an example curl request to a wait endpoint on Sequin:

> curl
< { "ok": true }

Note: The wait endpoint is in alpha and experimental. We may add additional properties to the response in the near future.


Your Sequin database will contain all your Stripe data - which includes PII and sensitive information. We take the security of that data seriously.

Please read about our full security practices. Here is a short synopsis of how we keep your Stripe data secure:

  • You supply us with an API key which is encrypted at rest. The Sequin application database is only accessible through a bastion host.
  • We only access customer databases by request or to diagnose a sync issue.
  • Sequin workers first backfill your database with all your Stripe data. Then, after the backfill, Sequin workers poll Stripe's events endpoint every second to keep your data in-sync.
  • Data flows directly from Stripe, through Sequin workers, to your database. We don't cache or store Stripe data anywhere else.
  • We use Sentry and Datadog for error monitoring. Sometimes errors Datadog catches will contain API response data. But these are minimized and our logs in Datadog have a shelf-life of 30 days.
  • By default, Sequin provisions a private database and a database user for you on a shared RDS instance. While Sequin shared instances are secure, we can also sync to a database you own for greater peace of mind.
Real-time Revenue Dashboard

Was this helpful?