Integration
Stripe + Bastle
What syncs from Stripe, what it makes possible, and how to connect it.
This connector works and can be connected today, with edge cases still being closed. Check the first month against the source before you rely on it.
What does the Stripe integration do?
What syncs
Bastle reads the following from Stripe and normalises it into the same entities every other source produces. Ingestion is read-only: nothing is created, changed or cancelled upstream.
- Prices and legacy plans → Bastle plans, with interval and interval count mapped 1:1 (quarterly reads as month × 3). One-time prices are skipped; their charges land in Other Revenue.
- Customers, subscriptions and subscription items — item one is the base plan and its quantity is seats, remaining items become add-ons priced per interval.
- Coupons and discounts, flattened to a per-interval discount in cents. A 100% coupon produces a discount equal to the gross, which the metrics engine treats as a churn on apply and an upgrade on expiry.
- Charges and refunds in integer cents, with the Stripe fee read from the expanded balance transaction during backfill.
- Delinquency state: invoice.payment_failed sets the customer delinquent, invoice.payment_succeeded clears it.
- Trial lifecycle as events — trial started, trial converted, trial cancelled — derived from subscription status transitions rather than guessed from dates.
- Disputes, recorded as activity events for Recover. They do not move MRR.
- Cadence: webhook-driven, so seconds behind Stripe. Historical backfill is run manually today.
Once connected
What Stripe data unlocks
Connecting a source is not the point; what you can answer afterwards is. These are the questions this data makes answerable.
MRR that reconciles with Stripe
Recurring revenue is normalised per subscription — monthly at face value, quarterly divided by three, annual divided by twelve, less live discounts — so the number can be traced back to the specific subscriptions behind it rather than to a chart.
Failed payments as a working queue
invoice.payment_failed marks the customer delinquent with a timestamp, which is what Recover's dunning campaigns and the delinquency window policy both read from.
Trial conversion measured, not inferred
A trialing subscription becoming active is recorded as a distinct conversion event, so trial conversion rate is counted from transitions rather than reconstructed from trial end dates after the fact.
Fee-aware net revenue
Charges carry Stripe's fee, so net revenue and gross margin work off what actually landed rather than off the gross amount invoiced.
Setup
Connecting Stripe
The whole flow, start to first chart. No implementation call and no data engineer.
- Open Settings → IntegrationsThe integrations grid is driven by the connector registry, so every provider Bastle knows about is listed with its real status.
- Connect the Stripe accountBastle authenticates server-side with a Stripe secret key. A restricted key with read access is enough — Bastle never writes to Stripe. Credentials are held server-side and never reach the browser.
- Point a Stripe webhook at BastleAdd an endpoint in the Stripe dashboard targeting /api/webhooks/stripe with your Bastle source id in the query string, subscribe it to the customer, subscription, invoice and charge event types listed in the connector docs, then save the signing secret in Bastle.
- Ask us to run the historical backfillFirst-time imports are triggered by hand while the scheduled runner is being wired. Once it completes, the webhook keeps the account current with no further action.
Why the webhook is the important half
Most analytics tools describe their Stripe integration in terms of the initial import, because that is the part a demo shows. The part that decides whether your numbers are trustworthy in month four is the event stream. Bastle's endpoint verifies the Stripe-Signature header against the endpoint secret before it touches the database, so an unauthenticated request can never trigger a lookup, and the Stripe SDK re-verifies afterwards as defence in depth. Events from a Connect account that does not match the source's pinned account id are rejected with the same generic error as a bad signature, so there is no way to probe which source ids exist.
Where subscription state gets subtle
Two Stripe behaviours cause most of the disagreement between billing dashboards and analytics tools. The first is cancel_at_period_end: a subscription flagged for cancellation is still generating revenue until Stripe actually ends it, so Bastle keeps it active until then and dates the cancellation when it happens. The second is discounts. Percentage coupons apply to the gross of base plus add-ons and are stored as a flat per-interval amount; a 100% coupon produces a discount equal to the gross, and the metrics engine excludes that customer from paid MRR — counting it as churn on apply and an upgrade on expiry. Both rules are policy, and both are written down in the MRR definition rather than buried in a sync job.
Fees, and why backfill sees them and webhooks often do not
Stripe's fee lives on the balance transaction, not on the charge. Backfill expands it, so imported charges carry the real fee. Webhook deliveries usually carry only the balance transaction id, so a charge that arrives live records a fee of zero until the next sync fills it in. Net revenue is therefore slightly optimistic for very recent charges and correct for everything else. That is a real limitation and it is better stated than discovered.
What "beta" means here
The connector is written and the inbound webhook route verifies signatures and writes normalised rows, so a connected account keeps up with changes as they happen. What is not self-serve yet is the historical backfill: the code that walks your provider's API from the beginning exists in the connector, but the scheduled runner that triggers it is still a stub, so first-time imports are run by hand with us. Expect to email someone once during setup, and expect that to stop being true.
Bastle is free while in beta, connectors included. There is no tier that unlocks a provider.
Related
Other sources
Companies billing through Stripe usually have at least one of these in the stack too.
- ChargebeeBetaThe Chargebee integration reads a Chargebee site through the v2 API with Product Catalog 2.0 semantics: item prices become plans, subscriptions carry add-ons, and invoices and transactions become charges and refunds in integer cents. Webhooks authenticated with HTTP basic auth keep subscription and dunning state current between imports.
- RecurlyBetaThe Recurly integration reads a Recurly site through the v3 API at version v2021-02-25, importing plans, accounts, subscriptions and transactions in that order so that references resolve as they are written. Webhook notifications are verified by HMAC signature with a five-minute replay tolerance and optional endpoint basic auth, and both US and EU data regions are supported.
- PaddleBetaThe Paddle integration reads Paddle Billing — the current platform, not Paddle Classic — importing prices as plans plus customers, subscriptions, transactions and adjustments. Because Paddle is a merchant of record, its own reported fee totals are treated as authoritative, so net revenue reflects what Paddle actually remitted rather than an estimate.
- WebhooksLiveBastle sends outbound webhooks for subscription, charge, trial and dunning events derived from every connected source, signed with an HMAC header and retried on a backoff schedule across roughly fourteen hours. Endpoints subscribe with exact event types or wildcard patterns, and delivery history is visible in settings. This is shipped and self-serve today.
- Universal APILiveBastle's write API accepts subscription data from any billing system, including one you built yourself. A single batched import endpoint upserts plans, customers, subscriptions, charges and refunds against your own external ids, and a read API returns the same metrics the dashboard renders. It is available today, self-serve, with scoped API keys.
Stripe and Bastle: common questions
What Stripe permissions does Bastle need?
How far behind Stripe is Bastle?
Does Bastle support Stripe Connect platforms?
Does Bastle write anything back to my billing provider?
Connect Stripe and see your own history.
Bastle backfills what Stripe will serve, then keeps current over webhooks — usually a couple of minutes before the first real chart. Free while in beta, no card required.