Connect Stripe

Create a read-only Stripe restricted key with exactly the three read scopes ParityRail needs.

ParityRail reads your Stripe account to see each customer’s plan, status, and trial. The key you create here can only read — it can never change anything in your Stripe account.

Before you start

A Stripe account with Dashboard access to Developers → API keys — enough permission to create a restricted key.
A decision on test vs live: a test key (rk_test_) reads Stripe test data; a live key (rk_live_) reads your real, paying customers. Connect the one whose customers you want to check.
Admin role on the ParityRail project — connecting Stripe requires admin.
Optional: for near-real-time re-checks, have your webhook signing secret (whsec_…) ready — see Webhooks.

No Stripe account? Skip straight to step 7 below and use demo mode instead.

Connect Stripe

In the Stripe Dashboard, go to Developers → API keys → Create restricted key. Name it parityrailso it’s easy to find later.

Set exactly these resources to Read — leave everything else at None:

Resource	Access	Why
Customers	`Read`	List and retrieve customers, their email, and metadata for identity mapping.
Subscriptions	`Read`	Read subscription status, items, price, quantity, and trial to derive the promise.
Invoices	`Read`	Read the latest invoice to tell a paid trial apart from an unpaid one.

Optionally also grant these two — leave them off unless you use Checkout Session events or Stripe Entitlements:

Resource	Access	When
Checkout Sessions	`Read`	Listed on the onboarding screen; optional, and only relevant to checkout-session events.
Entitlements	`Read`	Only if you use Stripe Entitlements and enable entitlement fetching for the project.

Create the key and copy it — it starts with rk_.
In the ParityRail onboarding wizard, go to step 2 (Stripe). In the “Restricted API key” card, paste the key into the “API key” field.
```
rk_test_<...>
```
A live key (rk_live_…) or a full secret key (sk_test_… / sk_live_…) also works, if that’s what you have.
Optional: paste your webhook signing secret into the “Webhook signing secret (optional)” field.
```
whsec_<...>
```
Click “Test & connect”. The button reads “Testing connection…” while ParityRail verifies the key by listing one customer.
Just exploring? Skip all of the above and click “Connect demo dataset” in the dashed “Use demo mode” card instead.

Verify it worked

On success, a toast reads “Stripe connected (test mode)” or “(live mode)”, and the form is replaced by a green “Stripe connected” card showing a masked account label (for example rk_test_…abcd) and a mode badge.

Directly below, a “Key permissions” card renders the real permission checklist — Customers, Subscriptions, and Invoices — each with a green checkmark once your restricted key can read it. Continue becomes enabled.

Demo mode instead toasts “Demo mode enabled — 250 fixture customers loaded” and shows all three permissions green.

Troubleshooting

Symptom	Fix
Red X on Customers, Subscriptions, or Invoices in the Key permissions checklist, with `Grant read access to <resource> in your restricted key`	That scope is missing. Add Read for that resource in Stripe, then click “Re-check” on the checklist card. A failing scope does not block Continue — a customer may legitimately have no subscriptions.
`Stripe rejected the API key. Check that the secret or restricted key is correct, belongs to the right account, and has not been revoked.`	The key is wrong, revoked, or from the wrong account — recreate it in Stripe and paste it again.
`Enter a Stripe restricted key (rk_…) or secret key (sk_…)`	The pasted value doesn’t match the `sk_`/`rk_` + test/live pattern — you likely copied a publishable key (`pk_`) or a partial string.
`Webhook signing secrets start with whsec_`	The signing-secret field must be blank or a whsec_ value.
Connected, but to the wrong data	You used a test key but wanted live customers (or vice versa). Click “Reconnect” and paste the correct-environment key.
`The Stripe API key does not have the required permissions…`	The key has no read scopes at all, so it can't even list customers. Grant Customers, Subscriptions, and Invoices Read, then reconnect.

What ParityRail never accesses

The connector only ever lists and retrieves the resources above. It has no write scope at all, so it isn’t just careful about your Stripe data — it’s structurally unable to change it.

No payment data. It never reads raw payment methods, card numbers, or bank details.
No charges, refunds, or payouts. It never creates, modifies, reads, or issues any of these.
No writes. It never changes subscriptions, customers, prices, or any other Stripe object.