Sync Inc

Stripe Reference

Stripe API keys

To sync all your Stripe data to your Sync Inc database, you need to provide us with a Stripe API key.

Create a Stripe API key

While you can supply Sync Inc 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 "Sync Inc."

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, Sync Inc 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 Sync Inc works with Stripe, you can always start by using your Stripe test key. Sync Inc 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 Sync Inc 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, Sync Inc 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, Sync Inc 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 fresh.

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

Stripe data types

Amounts

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

So as an example, $10.00 USD will be stored as an integer value of `1000` in your Sync Inc 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 Sync Inc database.

The syncing process

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

Then, after the backfill, Sync Inc workers poll Stripe's `/events` endpoint every second to ingest any creates, updates, or deletes.

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

Writes

Your Sync Inc database is read-only.

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

Security

Your Sync Inc 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 Sync Inc application database is only accessible through a bastion host.
  • We only access customer databases by request or to diagnose a sync issue.
  • Sync Inc workers first backfill your database with all your Stripe data. Then, after the backfill, Sync Inc workers poll Stripe's events endpoint every second to keep your data in-sync.
  • Data flows directly from Stripe, through Sync Inc 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, Sync Inc provisions a private database and a database user for you on a shared RDS instance. While Sync Inc shared instances are secure, we can also sync to a database you own for greater peace of mind.
Cheat sheet
Schema

Was this helpful?