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.

:::warning 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	Case is active but the collection partner has not yet paid Debitura's platform commission. Fee is speculative — amounts may change	Estimates (fluctuate with FX rates)
Confirmed / Pending Invoice	Collection partner has paid. Exchange rate is now locked. Amount is confirmed but not yet invoiced	Final
Awaiting Collection Partner Payment	Debitura has invoiced the collection partner. Waiting for their payment	Final
Ready to Invoice Debitura	Collection partner paid. You can now invoice Debitura for your share	Final
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=0 HTTP/1.1
Host: referral-api.debitura.com
XApiKey: your-api-key

Status values: 0 = Pending, 1 = Invoiced, 2 = Paid.

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 is the total platform revenue across all stages for the filtered period, independent of your referral fee.

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 payment date. fromDate/toDate filter when the debtor paid, not when revenue was recognized.

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.

What's Next

• API Reference — Transactions - Transaction-level revenue data
• API Reference — Clients - Client list with stats and summary
• Attribution - How revenue percentage is determined