Commerce & billing
Set up Stripe
Connect Stripe to make billing searchable — customers, invoices, subscriptions, disputes, refunds and credit notes, each linked to its customer, so “what does this customer pay us” and “which invoices are open” answer from the billing system itself. Read-only.
Before you start
- A Stripe API key from the Stripe Dashboard, Developers → API keys. Create a restricted key (rk_live_…) rather than using the full secret key.
- Grant it READ on Customers, Invoices, Subscriptions, Disputes, Charges and Credit notes — refunds ride the Charges permission — and nothing more; that is everything this source touches.
- Can never write or move money: only reads are ever issued, and a restricted key with read permissions cannot. A full secret key (sk_live_…) works too but grants far more than needed.
- In the Stripe Dashboard open Developers → API keys → Create restricted key, grant the six READ permissions above, and copy the key.
- Documents → Stripe, paste it as API key.
- Choose access groups, Test, then Sync.
What comes in
- Customers — name (the email or id when Stripe has no name), email, description, customer since and a delinquent flag when Stripe marks one.
- Invoices — number, status, amount due, amount paid, currency and date, with up to 10 line items.
- Subscriptions — every status, cancelled ones included: the plan (the price's nickname, or its amount and interval), status, the amount per month (yearly, weekly and daily prices normalised to a month, times quantity), currency, start date and next renewal. A subscription with several prices shows its first.
- Disputes — reason, status, amount, currency and when opened. Refunds — status, amount, currency, reason and date. Credit notes — number, status, total, currency, reason and date.
- Each links to its customer — a dispute or refund through its charge — and a customer's record sums up what hangs off it: how many of each, their totals and the latest date. Charges are not records of their own. Amounts are rendered in whole currency from Stripe's minor units; zero-decimal currencies such as JPY are already whole.
Access
Access is allow-only: the groups chosen on the source cover everything Stripe brings in — the source exposes no per-item viewers to mirror.
Each object type caps at 3,000, newest first; when a cap is reached the sync summary says so, and anything that ages past it stays searchable rather than disappearing. A restricted key missing the Charges or Credit notes permission does not fail the sync — refunds or credit notes are left out, already-synced ones stay, and the sync summary names exactly which permission to add. Test names the Stripe account it reached and counts customers; a rejected key reads as Stripe rejecting the credentials. Revoke access any time by deleting the restricted key under Developers → API keys.
Last updated 20 Sep 2026