> This page is for version v1 (default).
> For other versions, use one of these documentation indexes:
> - v1 (default): https://developers.truemed.com/v-1/llms.txt

> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://developers.truemed.com/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://developers.truemed.com/_mcp/server.

# Overview

> How to use the Reconciliations API to tie Truemed payouts and transactions back to your own ledger.

The Reconciliations API lets you pull the same charge, refund, fee, dispute, and payout data
you see in the Truemed Partner Dashboard—programmatically. Use it to tie Truemed activity back
to your own ledger, match bank deposits to underlying orders, and replace manual CSV exports
with a scheduled sync.

## Why it matters

Reconciliation is normally a manual process: download a CSV from the dashboard, open it in a
spreadsheet, and match rows against your orders and bank statements. The Reconciliations API
turns that into a routine integration:

* **Automate end-of-month close** — Pull a date range on a schedule and feed it directly into
  your accounting system or data warehouse.
* **Match bank deposits to orders** — Every transaction row carries the `payout_id` that ties
  it to a specific Stripe payout, so you can trace a bank deposit back to the individual
  charges that funded it.
* **Track fees and disputes alongside revenue** — Charges, refunds, Truemed fees, and disputes
  all come back in one stream, typed by `type`, so your books stay aligned with what hit
  your account.
* **Stay current without dashboard logins** — Pull the data your finance team needs without
  exporting from the UI.

## How it works

There are two endpoints. Most integrations call both: payouts to match the bank, transactions
to break each payout down into its underlying activity.

#### List payouts for a date range

Call [`GET /api/v1/reconciliation/payouts`](/api-reference/reconciliations/list-payout-reconciliation)
with a `start_date` and `end_date`. You'll get a paginated list of payouts—each with a
`payout_id`, arrival `date`, and `amount`—that you can match against deposits in your bank
account.

#### List the transactions that funded those payouts

Call [`GET /api/v1/reconciliation/transactions`](/api-reference/reconciliations/list-transaction-reconciliation)
for the same date range. Each row represents a single piece of activity—a charge, refund,
Truemed fee, or dispute—and carries the `payout_id` it was settled in (or `null` if it
hasn't paid out yet).

#### Match and post to your books

Group transaction rows by `payout_id` and verify the sum reconciles to the corresponding
payout amount. Use `order_id` to tie each row back to the matching order in your own
system.

## Important URLs

| Environment | Base API URL                          |
| ----------- | ------------------------------------- |
| Dev         | `https://dev-api.truemed.com/api/v1/` |
| Production  | `https://api.truemed.com/api/v1/`     |

## Authentication

Both endpoints accept the same authentication as the rest of the Truemed API — your merchant
API key, sent in the `x-truemed-api-key` header. You can create and manage keys yourself from
the **Developers** tab of your Truemed dashboard.

> **Note**
>
> **Shopify merchants:** the Developers tab isn't enabled by default. To generate an API key,
> contact your Truemed point of contact or [merchants@truemed.com](mailto:merchants@truemed.com)
> and ask to have developer-portal access enabled on your account. Once it's turned on, the
> **Developers** tab appears in your dashboard and you can create a key there.

## Transaction row types

The `type` field on each transaction row tells you what kind of activity it represents:

| Type             | Meaning                                          |
| ---------------- | ------------------------------------------------ |
| `Charge`         | A successful payment from a customer.            |
| `Full Refund`    | A full refund issued back to the customer.       |
| `Partial Refund` | A partial refund issued back to the customer.    |
| `Dispute`        | A chargeback or dispute filed against a charge.  |
| `Fee`            | A Truemed fee deducted from a payout.            |
| `Fee Refund`     | A reversal of a previously deducted Truemed fee. |

## Matching rows to Shopify orders

The single field that ties a Truemed transaction row to a Shopify order is **`payment_id`** — for
Shopify merchants this is the order's **Payment Reference** (the same value the Partner Dashboard
CSV labels **Shopify ID**).

### Worked example

A `Charge` row from [`GET /api/v1/reconciliation/transactions`](/api-reference/reconciliations/list-transaction-reconciliation)
looks like this:

```json
{
  "order_id": "02495450-7987-459f-b2ab-1499b8864681",
  "payment_id": "rSllsQAvxYGXIUvTLMCgFwGkx",
  "charge_date": "2026-06-03",
  "type": "Charge",
  "order_total": "749.95",
  "fee": "-61.99",
  "order_items": "The Collection Snowboard: Liquid",
  "name": "Jordan Rivers",
  "email": "jordan@example.com"
}
```

#### Take the payment_id from the row

Here that's `rSllsQAvxYGXIUvTLMCgFwGkx`. This is the match key.

#### Find the same value in Shopify

On the Shopify order it appears as the **Payment ID**:

![Payment ID on a Shopify order](/_fern-img/532cfd113e2064913f27f5fb84a61cc92db65c711b767943195f37b92d303797.webp)

In a Shopify **order CSV export**, it's the **Payment Reference** column.

#### Confirm the match

The two strings are identical, so that Shopify order is now tied to the Truemed row — along
with its `order_total`, `fee`, and (once settled) `payout_id`.

### Field reference

When reconciling a Shopify order, these are the fields you'll use most:

| API field     | What it is                                                                  |
| ------------- | --------------------------------------------------------------------------- |
| `payment_id`  | **The match key** — equals the Shopify order's **Payment Reference**.       |
| `order_total` | Order total, inclusive of sales tax, shipping, and fees.                    |
| `fee`         | Truemed fee deducted from the order (negative).                             |
| `order_items` | Comma-separated names of the items on the order.                            |
| `payout_id`   | The Stripe payout this row settled in (`null` until it pays out).           |
| `order_id`    | Truemed's own order identifier — quote this in any Truemed support request. |

> **Note**
>
> `payment_id` is populated for Shopify orders. For integrations that don't supply a platform
> payment reference it may be `null`; in that case, match on `order_id` instead.

This is the programmatic equivalent of the manual CSV matching described in
[Reconciliation and order details](/guides/setup/shopify/reconciliation).

## Linking rows to payouts

Each transaction row carries:

* **`payout_id`** — The payout the row was (or will be) settled in. `null` until the funds
  settle, then populated with the matching `payout_id` from `/payouts`.
* **`payout_date`** — The arrival date of that payout. Also `null` until settlement.

Once a row is settled, `payout_id` lets you roll transaction rows up to the payout level and
verify that the sum (charges + refunds + fees) equals the payout amount that arrived in your
bank account.

## Customer PII

For merchants that store their own customer data, transaction rows include `name` and `email`.
For merchants configured to hide customer PII, those fields are omitted and a `customer_id`
(an anonymized identifier) is returned instead, so you can still group activity by customer
without holding raw PII.