# 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