> For the complete documentation index, see [llms.txt](https://docs.coupler.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.coupler.io/sources/category/finance-and-accounting/braintree.md).

# Braintree

Connect Braintree to Google Sheets, BigQuery, or AI tools via Coupler.io. Export transactions, subscriptions, disputes, and more.

Braintree is a payment platform owned by PayPal that handles payment processing, recurring billing, and subscription management. It's widely used by SaaS companies and e-commerce businesses to manage transactions, plans, and customer payment profiles.

Connecting Braintree to Coupler.io lets you pull your payment data out of the gateway and into your reporting or analytics stack — without writing any code.

**Why connect Braintree to Coupler.io?**

* Analyze transaction volume, revenue trends, and dispute rates in Google Sheets, Looker Studio, or BigQuery
* Combine subscription and plan data using **Join** or **Aggregate** to track MRR and churn
* Send payment insights to AI tools like ChatGPT, Claude, or Gemini for summaries and anomaly detection
* Append data from multiple Braintree merchant accounts into a single destination

## Prerequisites

* A Braintree account with API access (available on all plans)
* Your **Merchant ID**, **Public Key**, and **Private Key** — found in the Braintree Control Panel under **Settings > API**
* Know whether you're connecting to the **Sandbox** or **Production** environment

## Quick start

{% hint style="success" %}
Start with the **Transactions** entity to get your payment history flowing first. You can always add Subscriptions, Disputes, or Customers to the same data flow later.
{% endhint %}

## How to connect

{% stepper %}
{% step %}
**Create a new data flow in Coupler.io.** From your Coupler.io dashboard, click **Add data flow** and select Braintree as your source.
{% endstep %}

{% step %}
**Enter your Braintree API credentials.** You'll need your Merchant ID, Public Key, and Private Key. Grab these from the Braintree Control Panel under **Settings > API**. Select **Production** or **Sandbox** depending on which environment you want to pull data from.
{% endstep %}

{% step %}
**Set a start date.** Use the date picker to choose how far back you want to pull historical data. Records before this date won't be included.
{% endstep %}

{% step %}
**Choose the entity you want to export.** Select from Transactions, Subscriptions, Customers, Disputes, Plans, Discounts, or Merchant Accounts.
{% endstep %}

{% step %}
**Pick a destination and run the data flow.** Connect to Google Sheets, Excel, BigQuery, Looker Studio, or an AI destination like ChatGPT or Claude. Then run the data flow manually to confirm everything is working.
{% endstep %}
{% endstepper %}

## Available entities

| Entity            | Description                                       |
| ----------------- | ------------------------------------------------- |
| Transactions      | Payment transactions processed through Braintree  |
| Subscriptions     | Recurring billing records and subscription status |
| Customers         | Customer profiles and contact details             |
| Disputes          | Chargebacks and payment disputes                  |
| Plans             | Subscription plans and pricing structures         |
| Discounts         | Discount codes and promotional offers             |
| Merchant Accounts | Merchant account configuration details            |

## Braintree data overview

Braintree exposes seven entities through Coupler.io, covering the full lifecycle of a payment — from a customer profile and subscription plan, through a processed transaction, all the way to a chargeback dispute.

## Entities at a glance

| Entity            | Best used for                                      |
| ----------------- | -------------------------------------------------- |
| Transactions      | Revenue reporting, payment volume, refund analysis |
| Subscriptions     | MRR tracking, churn, billing status                |
| Customers         | Customer segmentation, contact data                |
| Disputes          | Chargeback rate monitoring, dispute outcomes       |
| Plans             | Plan mix analysis, pricing tier breakdowns         |
| Discounts         | Promo usage tracking, discount impact on revenue   |
| Merchant Accounts | Gateway configuration audits                       |

## Transactions

#### Key fields

| Field                     | Description                                |
| ------------------------- | ------------------------------------------ |
| `id`                      | Unique transaction identifier              |
| `amount`                  | Transaction amount                         |
| `status`                  | e.g., settled, failed, voided, refunded    |
| `created_at`              | Timestamp when the transaction was created |
| `updated_at`              | Timestamp of last status change            |
| `currency_iso_code`       | Currency of the transaction                |
| `payment_instrument_type` | e.g., credit card, PayPal                  |
| `merchant_account_id`     | Which merchant account processed this      |
| `order_id`                | Your internal order reference              |
| `refund_ids`              | Linked refund transaction IDs              |

## Subscriptions

#### Key fields

| Field                      | Description                         |
| -------------------------- | ----------------------------------- |
| `id`                       | Subscription ID                     |
| `status`                   | Active, canceled, past due, expired |
| `plan_id`                  | The plan this subscription is on    |
| `price`                    | Current billed amount               |
| `billing_day_of_month`     | Day billing renews each month       |
| `first_billing_date`       | Start of billing                    |
| `paid_through_date`        | Coverage end date                   |
| `number_of_billing_cycles` | Total cycles configured             |
| `current_billing_cycle`    | Current cycle count                 |

## Customers

#### Key fields

| Field                      | Description                   |
| -------------------------- | ----------------------------- |
| `id`                       | Customer ID                   |
| `email`                    | Customer email address        |
| `first_name` / `last_name` | Customer name                 |
| `company`                  | Company name if provided      |
| `created_at`               | When the customer was created |
| `phone`                    | Contact phone number          |

## Disputes

#### Key fields

| Field            | Description                |
| ---------------- | -------------------------- |
| `id`             | Dispute ID                 |
| `amount`         | Amount under dispute       |
| `status`         | Open, won, lost, accepted  |
| `reason`         | Dispute reason code        |
| `received_date`  | When the dispute was filed |
| `reply_by_date`  | Deadline to respond        |
| `transaction_id` | Linked transaction         |

## Plans

#### Key fields

| Field               | Description                 |
| ------------------- | --------------------------- |
| `id`                | Plan ID                     |
| `name`              | Plan display name           |
| `price`             | Plan price                  |
| `billing_frequency` | Billing cycle in months     |
| `currency_iso_code` | Plan currency               |
| `trial_period`      | Whether a trial is included |
| `trial_duration`    | Trial length                |

## Discounts

#### Key fields

| Field                      | Description                          |
| -------------------------- | ------------------------------------ |
| `id`                       | Discount ID                          |
| `name`                     | Discount name                        |
| `amount`                   | Fixed discount amount                |
| `number_of_billing_cycles` | How many cycles the discount applies |

## Common field combinations

* **Transaction + Merchant Account** — Use a **Join** to attribute revenue by merchant account
* **Subscription + Plan** — Join on `plan_id` to analyze revenue by pricing tier
* **Dispute + Transaction** — Join on `transaction_id` to calculate chargeback rates per payment method or merchant account
* **Subscription + Customer** — Join to build a customer-level MRR and churn view

## Use cases by role

{% tabs %}
{% tab title="Finance teams" %}

* Pull Transactions daily into Google Sheets or BigQuery to reconcile revenue
* Use Aggregate to sum settled transaction amounts by day, week, or currency
* Track dispute amounts and outcomes to monitor chargeback exposure
* Join Subscriptions and Plans to calculate MRR by pricing tier
  {% endtab %}

{% tab title="Product & Growth" %}

* Analyze plan distribution and trial conversion by joining Plans and Subscriptions
* Monitor discount usage and its impact on billed revenue
* Feed subscription churn data into ChatGPT or Claude for narrative summaries
  {% endtab %}

{% tab title="Operations" %}

* Export Merchant Accounts to audit gateway configuration across environments
* Use Append to combine Sandbox and Production transaction data for comparison
* Track dispute reply deadlines to avoid automatic losses
  {% endtab %}
  {% endtabs %}

## Platform-specific notes

* Braintree uses cursor-based pagination internally — large transaction exports may take longer on the first run
* The `start_date` parameter applies primarily to Transactions and Subscriptions; static entities like Plans and Discounts return all records regardless
* Sandbox and Production are separate environments — make sure your credentials match the environment you want to report on
* Refunds appear as separate transaction records linked via `refund_ids`, not as negative line items on the original transaction

## Braintree common issues

### Connection issues

<details>

<summary>Invalid credentials error when connecting</summary>

Double-check that you're using the correct **Merchant ID**, **Public Key**, and **Private Key** from the Braintree Control Panel under **Settings > API**. These are environment-specific — Sandbox credentials won't work against Production and vice versa. Make sure the environment you selected in Coupler.io matches the credentials you've entered.

</details>

<details>

<summary>Connection succeeds but no data loads</summary>

This usually means the start date is set too far in the future, or you've selected an entity (like Plans or Discounts) that has no records yet in your account. Try setting an earlier start date or switching to the Transactions entity to confirm the connection is working.

</details>

### Missing data

<details>

<summary>Transactions from a certain period are missing</summary>

Braintree applies the start date filter to transaction created dates. If you moved the start date forward, earlier transactions are excluded. Reset the start date using the date picker to cover the period you need, then re-run the data flow.

</details>

<details>

<summary>Refunds aren't showing up</summary>

Refunds in Braintree are recorded as separate transaction records, not modifications to the original. Make sure your Transactions export covers the date range when the refund was processed — it will have its own `created_at` timestamp and a `type` of `credit`.

</details>

<details>

<summary>Plans, Discounts, or Merchant Accounts return no data</summary>

These entities are static and don't filter by date. If they're returning empty, it likely means none have been created in your Braintree account yet. Verify in the Braintree Control Panel that the relevant records exist.

</details>

### Permission errors

<details>

<summary>API key doesn't have permission to access disputes or subscriptions</summary>

Braintree API keys inherit the permissions of the user or role they belong to. If you're seeing access errors for specific entities, check in the Braintree Control Panel that the API user has the necessary role permissions — for example, dispute access may require an elevated role.

</details>

### Data discrepancies

<details>

<summary>Transaction amounts don't match my Braintree dashboard totals</summary>

The Braintree dashboard typically shows **settled** amounts only. Your Coupler.io export includes all transaction statuses (authorized, submitted for settlement, failed, voided, etc.). Filter by `status = settled` in your destination to match dashboard figures.

</details>

<details>

<summary>Subscription counts differ between Coupler.io and Braintree</summary>

Expired or canceled subscriptions are included in Coupler.io exports. If the Braintree dashboard shows only active subscriptions, apply a `status = Active` filter in your destination sheet or BI tool.

</details>

### Rate limits

<details>

<summary>Data flow times out or fails on large transaction exports</summary>

Braintree's API can be slow when paginating through large transaction histories. If you hit timeouts, try narrowing the start date to reduce the volume of records per run. Once your historical data is loaded, future incremental runs will be much faster.

</details>

## Braintree FAQ

<details>

<summary>Which Braintree credentials do I need to connect?</summary>

You need three values from the Braintree Control Panel under **Settings > API**: your **Merchant ID**, **Public Key**, and **Private Key**. You'll also need to know whether you're connecting to the Sandbox or Production environment, since each has its own set of credentials.

</details>

<details>

<summary>Can I export data from both Sandbox and Production?</summary>

Yes, but you'll need a separate data flow for each environment. Sandbox and Production have different API credentials and completely separate data — they can't be combined in a single data flow.

</details>

<details>

<summary>How does the start date affect which records are exported?</summary>

The start date filters Transactions and Subscriptions by their `created_at` date. Any records created before the start date won't be included. Static entities like Plans, Discounts, and Merchant Accounts ignore the start date and always return all records.

</details>

<details>

<summary>Why do my transaction totals look higher than what Braintree's dashboard shows?</summary>

Braintree's dashboard typically displays settled amounts only. Coupler.io exports include all statuses — authorized, submitted for settlement, failed, voided, and refunded. Filter your export to `status = settled` to match the dashboard.

</details>

<details>

<summary>Can I pull data from multiple Braintree merchant accounts?</summary>

Each merchant account lives under the same Braintree gateway credentials, so a single data flow will capture transactions across all merchant accounts. The `merchant_account_id` field on each transaction tells you which account it belongs to. If you need to combine data from entirely separate Braintree gateways, use Coupler.io's **Append** transformation.

</details>

<details>

<summary>Are refunds included in the Transactions export?</summary>

Yes — refunds appear as separate transaction records with a `type` of `credit`, not as modifications to the original transaction. Make sure your start date covers the date the refund was processed, as it will have its own `created_at` timestamp.

</details>

<details>

<summary>Can I use Braintree data with AI tools?</summary>

Yes. Coupler.io supports AI destinations including ChatGPT, Claude, Gemini, Perplexity, Cursor, and OpenClaw. You can send your transaction or subscription data directly to these tools for summaries, anomaly detection, or financial narrative generation.

</details>

<details>

<summary>How do I calculate MRR from Braintree data?</summary>

Join the Subscriptions entity to the Plans entity on `plan_id` to get the price and billing frequency for each active subscription. Filter subscriptions to `status = Active`, then aggregate the price field — adjusting for billing frequency if you have both monthly and annual plans.

</details>

{% hint style="info" %}
For a full list of available fields per entity, see the [Data Overview](#braintree-data-overview). For setup tips and date filter guidance, check [Best Practices](https://docs.coupler.io/sources/category/finance-and-accounting/braintree/best-practices.md).
{% endhint %}


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.coupler.io/sources/category/finance-and-accounting/braintree.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.
