Stripe Reference
We've closed our beta for Stripe. Join the waitlist and we'll notify you when we're ready.
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.
Stripe data types
Amounts
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
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.
Writes
Stripe Proxy
Sequin provisions a read-only sync of your Stripe data. This is to promote a one-way data flow architecture.
To mutate your data, you write to the Stripe API through Sequin. Sequin applies those mutations to Stripe and your Sequin database at the same time. This means subsequent reads by your code or a SQL client will reflect the update data:

With this architecture, your code is structured so that you're using SQL for reads but API calls for writes. This gives you the best of both worlds and ensures your database stays in sync with Stripe.
How to write through the proxy
To use the Sequin Proxy, you craft HTTP requests to the Stripe API like you normally would but prepend proxy.sequin.io/
to the beginning of the hostname.
For example, here's a request that creates a new subscription:
curl https://proxy.sequin.io/api.stripe.com/v1/subscriptions
-u "sk_▒▒▒▒▒▒▒▒▒▒" \
--data-urlencode "customer=cus_▒▒▒▒▒▒▒▒▒▒" \
--data-urlencode "items[0][price]=price_▒▒▒▒▒▒▒▒▒▒"
Note the request looks exactly the same as what you'd find in the Stripe API docs, except for the URL. The base of the URL is https://proxy.sequin.io/api.stripe.com
instead of https://api.stripe.com
. This sends the request through the Sequin Proxy so that mutations are applied immediately to your Postgres database as well as your Stripe base.
The proxy works with every Stripe API procedure available: list requests (GET), updates (PATCH), creates (POST), and deletes (DELETE). All fields will be written to your database immediately.
Read-after-write
If you prefer not to use our proxy, you can still make calls directly to Stripe's API and 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:
https://api.sequin.io/api/wait/:id
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:
- Make a write request directly to the API
- Call your sync's wait endpoint
- When #2 completes, read from your Sequin database
Here's an example curl request to a wait endpoint on Sequin:
> curl https://api.sequin.io/api/wait/0f062f20-ac57-4c00-8e69-cfb1cbcfdd5f
< { "ok": true }
Note: The wait endpoint is in alpha and experimental. We may add additional properties to the response in the near future.