Integration
Paddle + Bastle
What syncs from Paddle, 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 Paddle integration do?
What syncs
Bastle reads the following from Paddle and normalises it into the same entities every other source produces. Ingestion is read-only: nothing is created, changed or cancelled upstream.
- Prices with their products → plans, with billing cycle interval and frequency mapped onto Bastle's interval and interval count.
- Trial periods from the price's trial configuration. A year-long trial is folded into twelve months because Bastle's trial unit has no year.
- Customers and subscriptions, including active and archived states.
- Transactions → charges, with the fee taken from Paddle's own totals.
- Adjustments → refunds and credits.
- Cadence: webhook-driven via a notification destination; historical import run manually today.
Once connected
What Paddle data unlocks
Connecting a source is not the point; what you can answer afterwards is. These are the questions this data makes answerable.
Merchant-of-record economics done right
Paddle collects tax and its own fee before remitting. Reading Paddle's reported fee rather than assuming a percentage is the difference between a net revenue figure that reconciles with your bank and one that does not.
Sandbox before production
The connector targets Paddle's sandbox host when the source is configured for it, so an integration can be proven against test data before a live key is issued.
Global sellers without a tax model
Because Paddle handles tax as the seller of record, Bastle can treat the remitted amount as revenue without you modelling VAT rules inside your analytics.
Setup
Connecting Paddle
The whole flow, start to first chart. No implementation call and no data engineer.
- Create a Paddle API keyPaddle → Developer Tools → Authentication. Sandbox and live keys are not interchangeable, so note which environment the key belongs to.
- Connect Paddle in Settings → IntegrationsEnter the API key and set the environment to match it. A live key with the environment set to sandbox will fail every call.
- Add a notification destination in PaddlePoint it at /api/webhooks/paddle, subscribe it to the subscription, transaction and adjustment events, and store the destination's endpoint secret in Bastle for signature verification.
- Ask us to run the historical importBackfill runs manually during onboarding while the scheduled runner is being wired.
Paddle Billing, not Paddle Classic
Paddle runs two generations of platform with different APIs and different object models. This connector targets Paddle Billing. If your account is still on Paddle Classic, the integration will not work and it is better to know that in one sentence here than after an afternoon of debugging.
Why the fee field matters more than usual
With most processors the fee is a small correction. With a merchant of record it is structural: Paddle sells to your customer, collects tax, takes its cut and remits the rest. Bastle reads the fee Paddle reports on each transaction rather than applying a rate, so net revenue reflects the actual remittance. Gross revenue and net revenue can diverge substantially on a Paddle book, and that gap is real rather than a rounding artefact.
Amounts and intervals
Paddle returns amounts as strings in the smallest currency unit, which Bastle parses to integer cents directly — no float ever touches the value. Billing cycles map cleanly onto Bastle intervals, with one exception: a trial expressed in years becomes months multiplied by twelve, because the trial unit enum stops at months.
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 Paddle usually have at least one of these in the stack too.
- 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.
- 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.
- Apple App StoreBetaThe Apple App Store integration tracks auto-renewable subscription revenue for iOS apps through the App Store Server API, with real-time updates from App Store Server Notifications V2. Apple's commission is applied as the fee on each charge, so net revenue reflects the developer's actual proceeds rather than the storefront price.
- 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.
Paddle and Bastle: common questions
Does Bastle support Paddle Classic?
How does Bastle handle tax on a Paddle book?
Can I test against Paddle sandbox first?
Does Bastle write anything back to my billing provider?
Connect Paddle and see your own history.
Bastle backfills what Paddle will serve, then keeps current over webhooks — usually a couple of minutes before the first real chart. Free while in beta, no card required.