Source: https://docs.debitura.com/referral-partners/integration-guides/revenue-tracking

# Revenue Tracking

Display Debitura revenue data to your users using the Reporting API.

<a id="overview"></a>

## Overview

The `/reporting/transactions` endpoint returns individual payment transactions and pre-aggregated revenue totals. Each transaction includes the case, client, payment amount, and your referral fee earnings broken down by recognition stage.

Exchange rate fluctuation

Revenue in the **Pending** stage uses live exchange rates and will change until the rate is locked. Show these amounts as estimates, not confirmed earnings. Each transaction includes an `earnings.isEstimate` flag — when `true`, the amounts may change before recognition.

Revenue moves through six stages:

| Stage | What it means | Amounts are... |
| --- | --- | --- |
| **Pending** | Collection partner commission receipt is unconfirmed and Debitura has not issued its platform invoice. The referral amount is still pending | **Estimates** (fluctuate with FX rates) |
| **Confirmed / Pending Invoice** | The collection partner has confirmed receiving its commission; Debitura has not yet issued its platform invoice. The amount is confirmed | **Final** |
| **Awaiting Collection Partner Payment** | Debitura has invoiced the collection partner. Waiting for their payment | Check `earnings.isEstimate`; this stage can still contain estimates |
| **Ready to Invoice Debitura** | Normally Debitura has received the platform payment. For partners configured with `ConfirmedPipeline`, confirmed collection-partner commission receipt can make the amount ready earlier | Check `earnings.isEstimate` |
| **Awaiting Debitura Payment** | You've invoiced Debitura. Payment is being processed | Final |
| **Paid** | Debitura has paid your invoice | Final |

For endpoint details, see the [API Reference](https://docs.debitura.com/api/referral-partner-api/reporting.md#get-transaction-level-revenue-data). **Business context:** See [Revenue sharing and financial reconciliation](https://support.debitura.com/en/articles/13913362-referral-partners-revenue-sharing-and-financial-reconciliation) for the commercial model, payment terms, and invoicing process.

<a id="fetch-revenue-data"></a>

## Fetch Revenue Data

```http
GET /reporting/transactions?fromDate=2025-01-01&toDate=2025-12-31 HTTP/1.1
Host: referral-api.debitura.com
XApiKey: your-api-key
```

The response includes individual transactions in `data` and aggregated totals in `summary`.

<a id="common-queries"></a>

## Common Queries

<a id="this-months-revenue"></a>

### This month's revenue

```http
GET /reporting/transactions?fromDate=2025-02-01&toDate=2025-02-28 HTTP/1.1
Host: referral-api.debitura.com
XApiKey: your-api-key
```

<a id="revenue-for-a-specific-client"></a>

### Revenue for a specific client

```http
GET /reporting/transactions?externalTenantId=your-client-id HTTP/1.1
Host: referral-api.debitura.com
XApiKey: your-api-key
```

<a id="only-recognized-revenue-what-you-can-invoice"></a>

### Only recognized revenue (what you can invoice)

```http
GET /reporting/transactions?hasRecognizedRevenue=true HTTP/1.1
Host: referral-api.debitura.com
XApiKey: your-api-key
```

<a id="search-by-case-reference-or-client-name"></a>

### Search by case reference or client name

```http
GET /reporting/transactions?search=INV-2025-001 HTTP/1.1
Host: referral-api.debitura.com
XApiKey: your-api-key
```

The `search` parameter matches against case reference numbers and client company names. Useful for finding specific transactions without knowing exact IDs.

<a id="filter-by-invoicing-status"></a>

### Filter by invoicing status

```http
GET /reporting/transactions?referralInvoicingStatuses=Pending HTTP/1.1
Host: referral-api.debitura.com
XApiKey: your-api-key
```

Status values: `Pending`, `Invoiced`, `Paid`, `Disputed` (case-insensitive; the numbers `0`–`3` are still accepted). To filter on several statuses, repeat the parameter: `?referralInvoicingStatuses=Pending&referralInvoicingStatuses=Invoiced`.

<a id="response-summary-object"></a>

## Response Summary Object

The `GET /reporting/transactions` response includes a `summary` object alongside the `data` array. This gives you pre-aggregated revenue totals in a single API call, without client-side aggregation:

```json
"summary": {
  "revenue": {
    "pendingReferralFeeUsd": 0.0,
    "pendingCount": 0,
    "confirmedPendingInvoiceReferralFeeUsd": 167.60,
    "confirmedPendingInvoiceCount": 5,
    "awaitingCollectionPartnerPaymentReferralFeeUsd": 0.0,
    "awaitingCollectionPartnerPaymentCount": 0,
    "readyToInvoiceDebituraReferralFeeUsd": 0.0,
    "readyToInvoiceDebituraCount": 0,
    "awaitingDebituraPaymentReferralFeeUsd": 0.0,
    "awaitingDebituraPaymentCount": 0,
    "paidReferralFeeUsd": 0.0,
    "paidCount": 0
  },
  "totalDebituraRevenueUsd": 335.21
}
```

Each revenue stage has a fee total (in USD) and a transaction count. Use this to build dashboard summary cards -- total earnings, pending amounts, and payment status breakdowns -- all from one API call.

`totalDebituraRevenueUsd` totals platform revenue before referral fees for matching non-`Credited` rows. It excludes credited/write-off commission rows even when they remain visible in transaction history.

<a id="build-dashboard-widgets"></a>

## Build Dashboard Widgets

The `summary` object contains pre-aggregated revenue by stage. Map these fields to your dashboard:

| Dashboard Label | Summary Field |
| --- | --- |
| Pending | `summary.revenue.pendingReferralFeeUsd` |
| Confirmed / Pending Invoice | `summary.revenue.confirmedPendingInvoiceReferralFeeUsd` |
| Awaiting Collection Partner Payment | `summary.revenue.awaitingCollectionPartnerPaymentReferralFeeUsd` |
| Ready to Invoice Debitura | `summary.revenue.readyToInvoiceDebituraReferralFeeUsd` |
| Awaiting Debitura Payment | `summary.revenue.awaitingDebituraPaymentReferralFeeUsd` |
| Paid | `summary.revenue.paidReferralFeeUsd` |

For per-client aggregation, group the `data` array by `client.externalTenantId`.

<a id="handle-pagination"></a>

## Handle Pagination

For large result sets, use the `page` and `pageSize` parameters:

```http
GET /reporting/transactions?fromDate=2025-01-01&toDate=2025-12-31&page=1&pageSize=100 HTTP/1.1
Host: referral-api.debitura.com
XApiKey: your-api-key
```

Continue incrementing `page` until the response contains fewer items than `pageSize`.

<a id="error-handling"></a>

## Error Handling

| Status | Meaning | Action |
| --- | --- | --- |
| 400 | Invalid request parameters (e.g., invalid date format, page size too large) | Check parameter formats match API specification |
| 500 | Internal server error | Retry with exponential backoff; contact support if persistent |

<a id="gotchas"></a>

## Gotchas

**"Pending Collection" amounts fluctuate.** Unrecognized revenue uses live exchange rates. Show these as estimates, not confirmed earnings. Each transaction includes an `earnings.isEstimate` flag — when `true`, the amounts are based on current exchange rates and may change before recognition.

**Dates filter by transaction row date.** `fromDate`/`toDate` filter the commission-receipt creation date for receipt portions, otherwise the payout date. They do not filter the separately returned debtor `payment.paymentDate`.

**API returns UTC timestamps.** Convert to user's timezone for display.

<a id="per-client-stats-via-get-clients"></a>

## Per-Client Stats via GET /clients

The `GET /clients` endpoint includes per-client case stats and an unfiltered portfolio summary, useful for dashboard overviews without querying individual transactions.

```http
GET /clients?Page=1&PageSize=50 HTTP/1.1
Host: referral-api.debitura.com
XApiKey: your-api-key
```

The response includes:

-   **`summary`** — Portfolio-level KPIs (unfiltered, always reflects your full client base):
    -   `totalClients`, `attributedClients`, `onboardingComplete`, `onboardingPending`, `totalCases`
-   **Per-client `caseStats`** — `casesTotal`, `casesClosed`, and `earningsUsd` for each client

Use `GET /clients` for high-level dashboards. Use `/reporting/transactions` for transaction-level detail, revenue stage breakdowns, and invoicing workflows.

See the [GET /clients API Reference](https://docs.debitura.com/api/referral-partner-api/clients.md#list-all-linked-clients) for full parameter and response documentation.

See the [Transactions API Reference](https://docs.debitura.com/api/referral-partner-api/reporting.md#get-transaction-level-revenue-data) for full parameter and response documentation, the [Clients API Reference](https://docs.debitura.com/api/referral-partner-api/clients.md#list-all-linked-clients) for client list with stats and summary, and [Attribution](https://docs.debitura.com/referral-partners/concepts/attribution.md) to understand how revenue percentage is determined.