Skip to main content

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.

Revenue moves through four stages:

  1. Unrecognized - Debtor paid, but exchange rate not locked
  2. Ready to Invoice - Exchange rate locked, you can invoice Debitura
  3. Invoiced - You have invoiced Debitura
  4. Paid - Debitura has paid your invoice

For endpoint details, see the API Reference. For the commercial model, see Getting started with Debitura.

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, 3 = Disputed.

Build Dashboard Widgets​

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

Dashboard LabelSummary Field
Pending Collectionsummary.revenue.unrecognizedReferralFeeUsd
Ready to Invoicesummary.revenue.referralFeeRecognizedUninvoicedUsd
Invoicedsummary.revenue.referralFeeRecognizedInvoicedUsd
Paidsummary.revenue.referralFeeRecognizedPaidUsd

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​

StatusMeaningAction
400Invalid request parameters (e.g., invalid date format, page size too large)Check parameter formats match API specification
500Internal server errorRetry 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​