Integration
PayPal + Bastle
What syncs from PayPal, 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 PayPal integration do?
What syncs
Bastle reads the following from PayPal and normalises it into the same entities every other source produces. Ingestion is read-only: nothing is created, changed or cancelled upstream.
- Billing plans → Bastle plans, with the regular billing cycle mapped to interval and interval count. Plans whose cycles are omitted from the list response are fetched individually.
- Subscriptions with their status and billing history.
- Captured payments → charges, and refunds against them.
- Subscription lifecycle events — created, activated, cancelled, suspended, payment failed — from the webhook stream.
- Cadence: webhook-driven for changes; historical import run manually today.
Once connected
What PayPal data unlocks
Connecting a source is not the point; what you can answer afterwards is. These are the questions this data makes answerable.
Recurring revenue from PayPal Subscriptions
PayPal reports payments, not subscription analytics. Bastle normalises billing plans and subscriptions into the same MRR, churn and retention model used for every other source.
Suspensions handled as their own state
A suspended PayPal subscription is neither active nor cancelled. Treating it as either produces a wrong churn number, so it is tracked distinctly.
Sandbox parity
The connector targets PayPal's sandbox host when the source is configured for it, so the mapping can be verified against test subscriptions first.
Setup
Connecting PayPal
The whole flow, start to first chart. No implementation call and no data engineer.
- Create a REST app in the PayPal developer dashboardIt yields a client id and secret. Bastle exchanges them for an access token per run using the client credentials grant.
- Register a webhook and note its idPoint it at /api/webhooks/paypal and subscribe to the billing subscription and payment events. PayPal's signature verification requires the webhook id, so record it.
- Connect PayPal in Settings → IntegrationsEnter the client id, secret and webhook id, and set the environment to live or sandbox to match the credentials.
- Ask us to run the historical importBackfill runs manually during onboarding while the scheduled runner is being wired.
Subscriptions, not checkout volume
PayPal handles two very different kinds of money movement: one-off checkout payments and recurring billing subscriptions. Only the second produces recurring revenue, and this connector is built around it. If your PayPal account is mostly one-off transactions, connecting it will produce accurate charge history and very little MRR, which is the correct answer rather than a bug.
Webhook verification
PayPal signs webhook deliveries and verifies them against a registered webhook id, so that id is required rather than optional. Without it there is no way to distinguish a genuine PayPal delivery from anything else that can reach a public URL, and Bastle will not process unverified events.
Token handling
Access tokens are minted per run from the client credentials, cached for the duration of that run, and re-minted on expiry. They are never persisted, so a leaked database row cannot yield a usable PayPal token.
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 PayPal usually have at least one of these in the stack too.
- BraintreeBetaThe Braintree integration reads a merchant account through the Braintree GraphQL API and ingests real-time webhooks, importing customers, recurring billing subscriptions, transactions, refunds and disputes. Identifiers are normalised to Braintree's legacy ids throughout, because that is what the webhook payloads carry.
- StripeBetaThe Stripe integration turns a Stripe account into Bastle's subscription data model: prices become plans, subscriptions carry their add-ons and discounts, and charges carry the Stripe fee from the balance transaction. Ongoing changes arrive over a signature-verified webhook endpoint within seconds of happening in Stripe, so MRR, churn and failed-payment state track the billing account rather than a nightly export.
- 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.
- 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.
PayPal and Bastle: common questions
Does Bastle track one-off PayPal payments?
Why does Bastle need my PayPal webhook id?
How does a suspended subscription affect churn?
Does Bastle write anything back to my billing provider?
Connect PayPal and see your own history.
Bastle backfills what PayPal will serve, then keeps current over webhooks — usually a couple of minutes before the first real chart. Free while in beta, no card required.