# Stripe

> Bring customers, invoices, charges, subscriptions and the rest of your Stripe account into your warehouse, with history.

## Before you start

You need two things from Stripe: your account ID, and an API key that can read your data.

- **A restricted key.** sanda only ever reads, so create a restricted key rather than using your full secret key. In the Stripe Dashboard, open **Developers**, then **API keys**, and create a restricted key. Give it **Read** on every available permission and nothing more, and choose what to sync in sanda instead. Copy the key when Stripe shows it, because Stripe does not show it again. A restricted key starts with `rk_live_`.
- **Your account ID.** It starts with `acct_` and is shown in your Stripe account settings.
- **Permission to create keys.** Ask the owner of the Stripe account if you cannot see the **API keys** page.

A key from test mode reads your test data, not your live data. Use a live key for the real account.

## Connect Stripe

:::steps
1. **Choose Stripe.** Go to **Data · Connections**, press **New connection** and pick **Stripe**.
2. **Enter the account.** Put your account ID, the one starting `acct_`, in **Account ID**.
3. **Enter the key.** Paste the restricted key into **Secret Key**. The form's hint mentions `sk_live_`, the start of a full secret key, but a restricted key works in the same field.
4. **Choose how far back to load.** Under **Advanced settings**, **Replication start date** opens on 2017-01-25T00:00:00Z, and only data generated after that date is loaded. Enter a later date, in UTC, to load less history and finish the first run sooner.
5. **Continue.** Press **Continue**, name the connection, and press **Read schema**. sanda signs in and lists the Stripe objects it can read. If it fails, the message says why. See [Troubleshoot connections](https://docs.sanda-os.com.au/connections/troubleshooting).
:::

The rest of the flow, naming the connection, setting a frequency and choosing streams, is the same for every source. See [Add a connection](https://docs.sanda-os.com.au/connections/add-a-connection).

## What syncs

Stripe's objects each become a stream, and land in your warehouse as their own tables. The usual starting points are customers, invoices, charges, subscriptions and refunds. The stream list shows what the connection offers, and you choose which to sync.

## Tips

- **Amounts are in the smallest currency unit.** For most currencies, including Australian dollars, an amount of 1050 means 10.50 in that currency. Divide by 100 when you model revenue.
- **Catch late restatements with a lookback.** **Lookback Window in days** re-reads the last N days on every run, for streams that cannot read Stripe's event log: `Events`, `SetupAttempts`, `ShippingRates`, `BalanceTransactions`, `Files`, `FileLinks` and `Refunds`. A few days is a sensible start if your reports rely on figures Stripe restates after the fact.
- **A long pause can lose changes.** Some incremental reads follow Stripe's event log, and Stripe keeps events for 30 days. If a connection stays paused for longer, the streams you list under **Streams with API Data Retention Validation** do a full refresh on their next run, in place of reading a log that no longer reaches back far enough.
- **Stripe's rate limits apply.** **Max number of API calls per second** caps sanda's requests. When you leave it empty, sanda uses 25 calls a second for test keys and 100 for live keys.

## Configuration fields

What the connection form asks for. Required fields are marked; the rest are optional.

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| **Account ID** | string | Yes | Your Stripe account ID (starts with 'acct_'). |
| **Secret Key** | string, secret | Yes | Stripe API key (usually starts with 'sk_live_'). |
| **Replication start date** | string | No | UTC date and time in the format 2017-01-25T00:00:00Z. Only data generated after this date will be replicated. Default `2017-01-25T00:00:00Z`. |
| **Lookback Window in days** | integer | No | When set, the connector will always re-export data from the past N days, where N is the value set here. This is useful if your data is frequently updated after creation. The Lookback Window only applies to streams that do not support event-based incremental syncs: Events, SetupAttempts, ShippingRates, BalanceTransactions, Files, FileLinks, Refunds. Default `0`. |
| **Data request time increment in days** | integer | No | The time increment used by the connector when requesting data from the Stripe API. The bigger the value is, the less requests will be made and faster the sync will be. On the other hand, the more seldom the state is persisted. Default `365`. |
| **Number of concurrent threads** | integer | No | The number of worker thread to use for the sync. The performance upper boundary depends on call_rate_limit setting and type of account. Default `10`. |
| **Streams with API Data Retention Validation** | array | No | Select streams where cursor age is validated against the Stripe API 30-day event retention period. When a selected stream's cursor is older than 30 days, the connector performs a full refresh to avoid missing data. Streams not selected here will always use incremental sync regardless of cursor age. |
| **Max number of API calls per second** | integer | No | The number of API calls per second that you allow connector to make. This value can not be bigger than real API call rate limit (https://stripe.com/docs/rate-limits). If not specified the default maximum is 25 calls per second for test/sandbox tokens and 100 for production tokens. |

## Related

:::links
- [Sync modes](https://docs.sanda-os.com.au/connections/sync-modes): How sanda reads each stream on every run.
- [Sync schedules](https://docs.sanda-os.com.au/connections/schedules): How often a connection runs.
- [Allowlist sanda’s address](https://docs.sanda-os.com.au/connections/allowlist): For a system behind a firewall.
- [Troubleshoot connections](https://docs.sanda-os.com.au/connections/troubleshooting): What an error means and how to fix it.
:::