Revenue Tracking

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

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. Business context: See Revenue sharing and financial reconciliation for the commercial model, payment terms, and invoicing process.

Fetch Revenue Data

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.

Common Queries

This month's revenue

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

Revenue for a specific client

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

Only recognized revenue (what you can invoice)

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

Search by case reference or client name

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.

Filter by invoicing status

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.

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:

"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.

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.

Handle Pagination

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

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.

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

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.

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.

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 for full parameter and response documentation.

See the Transactions API Reference for full parameter and response documentation, the Clients API Reference for client list with stats and summary, and Attribution to understand how revenue percentage is determined.