> 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/data-overview.md).

# 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


---

# 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 dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

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

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

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.