# Data Overview

Chargedesk exposes four main entities through Coupler.io. Each maps to a core part of your billing operation — transactions, customers, recurring plans, and product catalog.

## Entities

| Entity        | Description                                                       |
| ------------- | ----------------------------------------------------------------- |
| Charges       | All payment attempts and their outcomes across connected gateways |
| Customers     | Profiles of everyone who has been charged or subscribed           |
| Subscriptions | Active, canceled, and past recurring billing agreements           |
| Products      | Products and pricing tiers set up in Chargedesk                   |

***

#### Charges fields

| Field        | Description                                            |
| ------------ | ------------------------------------------------------ |
| charge\_id   | Unique identifier for the charge                       |
| amount       | Transaction amount                                     |
| currency     | Currency code (e.g., USD, EUR)                         |
| status       | Charge outcome: succeeded, failed, refunded, disputed  |
| gateway      | Payment gateway used (Stripe, PayPal, Braintree, etc.) |
| customer\_id | Linked customer identifier                             |
| created\_at  | Timestamp of the charge                                |
| description  | Charge description or product label                    |
| refunded     | Whether the charge was refunded                        |
| dispute      | Whether the charge is under dispute                    |

#### Customers fields

| Field          | Description                               |
| -------------- | ----------------------------------------- |
| customer\_id   | Unique customer identifier                |
| name           | Customer full name                        |
| email          | Customer email address                    |
| created\_at    | Date the customer record was created      |
| gateway        | Gateway associated with the customer      |
| total\_charges | Number of charges linked to the customer  |
| total\_spend   | Cumulative amount charged to the customer |

#### Subscriptions fields

| Field               | Description                                          |
| ------------------- | ---------------------------------------------------- |
| subscription\_id    | Unique subscription identifier                       |
| customer\_id        | Linked customer identifier                           |
| status              | Current state: active, canceled, past\_due, trialing |
| plan\_name          | Name of the subscribed plan                          |
| amount              | Recurring billing amount                             |
| currency            | Currency code                                        |
| billing\_interval   | Billing frequency (monthly, yearly, etc.)            |
| started\_at         | Subscription start date                              |
| canceled\_at        | Cancellation date if applicable                      |
| next\_billing\_date | Upcoming renewal date                                |

#### Products fields

| Field             | Description                       |
| ----------------- | --------------------------------- |
| product\_id       | Unique product identifier         |
| name              | Product name                      |
| description       | Product description               |
| price             | Default price                     |
| currency          | Currency code                     |
| billing\_interval | Billing frequency for the product |
| created\_at       | Date the product was created      |

***

## Common field combinations

* **Charges + Customers** — Join on `customer_id` to see how much each customer has spent and their charge history
* **Subscriptions + Customers** — Join on `customer_id` to track which customers are on which plans and identify churn risk
* **Charges + Subscriptions** — Append or Join to build a full revenue picture that covers both one-time and recurring revenue
* **Charges grouped by gateway** — Aggregate charges by `gateway` to compare performance across payment processors

***

## Use cases by role

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

* Export all charges into Google Sheets or Excel for monthly revenue reconciliation
* Use the Aggregate transformation to calculate MRR and ARR from the Subscriptions entity
* Monitor failed and disputed charges by filtering the Charges entity by `status`
* Send subscription data to BigQuery for long-term retention and trend analysis
  {% endtab %}

{% tab title="Support teams" %}

* Pull customer and charge data into a shared Google Sheet so support agents can quickly look up billing history
* Track customers with `past_due` subscriptions to prioritize outreach
* Use the Join transformation to combine customer profiles with their full charge history in one view
  {% endtab %}

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

* Analyze product adoption by exporting Products and Subscriptions, then joining on plan details
* Send subscription and churn data to ChatGPT or Claude for AI-assisted cohort analysis
* Use Looker Studio with Charges data to build a live revenue dashboard
  {% endtab %}
  {% endtabs %}

***

## Platform-specific notes

* Chargedesk aggregates data from multiple gateways, so the `gateway` field is important for filtering and segmenting records correctly
* The `start_date` parameter controls how far back historical data is synced — setting this too far back on large accounts can increase initial sync time
* Charge statuses and subscription states reflect what Chargedesk has received from the underlying gateway; small delays between gateway events and Chargedesk records are normal
* Customer and subscription records are linked via `customer_id` — this is the key field to use for Join transformations across entities