Integration
Braintree + Bastle
What syncs from Braintree, 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 Braintree integration do?
What syncs
Bastle reads the following from Braintree and normalises it into the same entities every other source produces. Ingestion is read-only: nothing is created, changed or cancelled upstream.
- Customers, recurring billing subscriptions, transactions and refunds, paged through the GraphQL API with cursor pagination.
- Plans and add-ons, with GraphQL global ids decoded back to legacy ids so webhook and API records line up.
- Disputes, recorded as activity events rather than revenue movements.
- Failed transactions, which set the delinquency flag used by the failed-payment queue.
- Cadence: webhook-driven for changes; historical import run manually today.
Once connected
What Braintree data unlocks
Connecting a source is not the point; what you can answer afterwards is. These are the questions this data makes answerable.
Subscription metrics on a PayPal-owned gateway
Braintree reports transactions well and subscription analytics poorly. Bastle turns recurring billing subscriptions into normalised plans and MRR with the same definitions used for every other source.
Disputes separated from churn
A chargeback is not a cancellation. Disputes land as their own events so they inform recovery work without distorting revenue churn.
Consistent ids across API and webhooks
Braintree's GraphQL global ids and its legacy ids refer to the same objects in different encodings. Bastle stores legacy ids everywhere, so records from a backfill and records from a webhook match instead of duplicating.
Setup
Connecting Braintree
The whole flow, start to first chart. No implementation call and no data engineer.
- Generate Braintree API keysBraintree Control Panel → Settings → API. Bastle needs the public and private key pair; the merchant id is stored for reference.
- Connect Braintree in Settings → IntegrationsEnter the key pair and choose the environment — sandbox or production. The environment selects which Braintree API host is used.
- Add a webhook destination in BraintreePoint it at /api/webhooks/braintree and subscribe to the subscription, transaction, refund and dispute notifications.
- Ask us to run the historical importBackfill runs manually during onboarding while the scheduled runner is being wired.
Two id systems, one truth
Braintree's GraphQL API returns global ids — base64 strings encoding a type and a legacy id — while its webhook payloads carry the legacy id. A connector that stores whichever id it happened to receive ends up with the same subscription recorded twice under two keys. Bastle decodes global ids back to legacy ids on the way in and keys everything on those, so a record imported by backfill and the same record delivered by webhook are one row.
Pinned API version
The connector requests a specific Braintree API version on every call. The top-level customer, transaction, refund and subscription queries it depends on are recent additions, so an older version simply cannot serve them — pinning makes that a clear error rather than a partial import.
Rate limiting
Rate-limited and unavailable responses are retried with the delay Braintree asks for, falling back to exponential backoff. Large merchants should expect an initial import measured in minutes rather than seconds.
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 Braintree usually have at least one of these in the stack too.
- PayPalBetaThe PayPal integration reads billing plans, subscriptions, transactions and refunds through PayPal's REST APIs using OAuth2 client credentials, and ingests webhooks verified against a registered webhook id. It covers PayPal Subscriptions rather than one-off checkout volume, which is what makes recurring revenue metrics meaningful on a PayPal book.
- 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.
- 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.
- 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.
Braintree and Bastle: common questions
Does Bastle read Braintree transactions or subscriptions?
Can I connect a Braintree sandbox account?
Does Bastle need a full-access Braintree key?
Does Bastle write anything back to my billing provider?
Connect Braintree and see your own history.
Bastle backfills what Braintree will serve, then keeps current over webhooks — usually a couple of minutes before the first real chart. Free while in beta, no card required.