Source: https://docs.debitura.com/api/referral-partner-api/reporting

# Reporting — Referral Partner API

Base URL: `https://referral-api.debitura.com`

Authentication: `XApiKey` API key; see [authentication](https://docs.debitura.com/developer-concepts/authentication.md).

Generated from [OpenAPI](https://docs.debitura.com/openapi/referral-partner-api.json). Examples are schema illustrations, not observed responses. Complete schemas, including recursive types, are in OpenAPI.

<a id="get-transaction-level-revenue-data"></a>

## Get transaction-level revenue data

`GET /reporting/transactions`

Retrieves comprehensive transaction-level financial data for all clients linked to the authenticated referral partner.

**IMPORTANT: Fields whose names end in `Usd` are returned in USD. Native transaction amounts
retain their own currencies: case amounts use `case.currency`, collected amounts use
`payment.currency`, and `earnings.collectionPartnerAmount` uses
`earnings.collectionPartnerCurrency`.**

Revenue Recognition Stages
The response includes a 4-stage revenue breakdown for each transaction, representing the complete lifecycle from collection to payment:

1. **Unrecognized Revenue** - Collections that have occurred but revenue is not yet recognized (typically due to pending verifications or disputes)
2. **Uninvoiced Recognized Revenue** - Revenue that has been recognized as earned but not yet invoiced to the partner
3. **Invoiced Revenue** - Revenue that has been invoiced to the partner but not yet paid
4. **Paid Revenue** - Revenue that has been paid to the partner

Exchange Rate Rules (Critical for Revenue Calculations)
- **Stage 1 (Unrecognized)** - Amounts fluctuate with current exchange rates (recalculated in real-time)
- **Stages 2-4 (Recognized/Invoiced/Paid)** - Amounts are LOCKED at the exchange rate from the moment revenue was recognized (Stage 1 → Stage 2 transition)
- This locking prevents exchange rate volatility from affecting recognized revenue, invoices, and payments
- The locked exchange rate is used for all downstream stages (Stages 2, 3, and 4)

Monthly Invoicing Workflow
Revenue progresses through stages on a monthly cycle:
- Collections occur throughout the month (Stage 1)
- At month-end, unrecognized revenue is reviewed and recognized (Stage 1 → Stage 2, exchange rate locked)
- Recognized revenue is invoiced to the partner (Stage 2 → Stage 3)
- Partner pays the invoice (Stage 3 → Stage 4)
- Use this endpoint to track revenue status before and after monthly invoicing

Transaction Data
Each transaction includes:
- Client identification (External Tenant ID, Client ID, Company Name)
- Case/Invoice details (Case ID, Debitura Reference, Creditor Reference)
- Debtor information (Name, Country)
- Financial amounts (case, payment, and collection-partner amounts in their identified native currencies; revenue-stage fields in USD; Collection Date)
- Revenue breakdown across all 4 stages (in USD)
- Referral fee percentage applied to this transaction

Filtering and Pagination
- **DateFrom/DateTo** - Filter transactions by collection date range (ISO 8601 format)
- **ExternalTenantId** - Filter to specific client(s)
- **Page/PageSize** - Paginate results (default: page 1, size 10, max: 100)

Sorting
- **Sort** - Sort field and direction (format: 'field:direction')
- Supported fields: collectionDate, amount
- Examples: 'collectionDate:desc', 'amount:asc'
- Default: collectionDate:desc (most recent first)

Use Cases
- Generate partner commission reports with explicit native and USD currency fields
- Track revenue recognition status and exchange rate impact
- Reconcile monthly invoices and payments
- Analyze per-client performance
- Export financial data for accounting systems
- Monitor outstanding receivables
- Understand exchange rate fluctuations on Stage 1 (unrecognized) revenue

The data returned represents real collection activity and actual revenue earned from cases created through the referral partnership.

### Query parameters

- `FromDate` (datetime): Filter transactions from this date (inclusive). ISO 8601 format.
- `ToDate` (datetime): Filter transactions to this date (inclusive). ISO 8601 format.
- `ExternalTenantId` (string): Filter by specific client's external tenant ID
- `HasRecognizedRevenue` (boolean): When true, only show transactions where revenue has been recognized (collection partner has paid Debitura).
When false, only show unrecognized transactions.
- `CommissionPaymentStatuses` (array of enums): Filter by commission payment status (Unpaid = 0, Paid = 1, Credited = 2).
Tracks whether Debitura has received the collection partner's commission.
- `PlatformInvoicingStatuses` (array of enums): Filter by platform invoicing status (NotInvoiced = 0, InvoiceIssued = 1, PaymentReceived = 2, InvoiceCredited = 3).
Tracks Debitura's invoicing lifecycle with the collection partner.
- `ReferralInvoicingStatuses` (array of enums): Filter by referral invoicing status (Pending = 0, Invoiced = 1, Paid = 2)
- `RevenueStages` (array of enums): Filter by revenue-lifecycle stage (see TransactionRevenueStage). Use this instead of
combining CommissionPaymentStatuses/PlatformInvoicingStatuses/ReferralInvoicingStatuses when you need
a row list for one specific "Ready to Invoice" tab bucket — it applies the same ConfirmedPipeline
fold the summary already uses, so the row list matches the badge count exactly for partners in
ConfirmedPipeline mode. ANDed with the other filters above if both are supplied.
            
Only narrows the row-list (`data`) — the returned `summary` always reports all 7 bucket
totals regardless of this filter, since its purpose is to drive tab badge counts and would
otherwise collapse the other buckets toward zero.
- `Search` (string): Search text to filter by case reference, client company name, or debtor name (company or
individual first/last name) — case-insensitive, partial match.
Minimum 2 characters required for search to be applied.
- `Page` (integer): Page number (1-indexed)
  Min 1.
- `PageSize` (integer): Number of results per page (default: 10, max: 100)
  1 to 100.
- `CountryIds` (array of integers): Filter by debtor country ID(s). Multiple values can be provided.
Only transactions where the debtor's country matches one of the specified IDs are returned.
- `CollectionPartnerIds` (array of uuids): Filter by collection partner ID(s). Multiple values can be provided.
Only transactions for cases assigned to one of the specified collection partners are returned.
- `Sort` (string): Sort field and direction. Format: "field[:asc|desc]"
Supported fields: collectionDate, amount
Examples: "collectionDate:desc", "amount:asc"
Default: collectionDate:desc

### Response 200

Transactions retrieved successfully

- `data` (array of objects, nullable): 
- `data[].transactionId` (uuid): Read-only row identity: the confirmation for received portions, otherwise the payout.
- `data[].payoutId` (uuid): The original financial source. A transaction row identity is not an editable payout ID.
- `data[].date` (datetime): 
- `data[].client` (object): 
- `data[].client.externalTenantId` (string, nullable): 
- `data[].client.creditorId` (uuid): 
- `data[].client.companyName` (string, nullable): 
- `data[].case` (object): 
- `data[].case.invoiceId` (uuid): 
- `data[].case.caseReference` (string, nullable): 
- `data[].case.debtorName` (string, nullable): 
- `data[].case.originalAmount` (number): The creditor-original claim amount, frozen at the moment this payout was created.
Never the invoice's live/current GrossAmount — a later claim edit or currency
conversion does not change this value for an already-created payout.
- `data[].case.currency` (string, nullable): ISO currency of OriginalAmount, frozen alongside it at payout creation.
Not the case invoice's live/current currency.
- `data[].case.collectionPartner` (string, nullable): Display name of the collection partner handling this case.
Null if no collection partner has been assigned yet.
- `data[].payment` (object): 
- `data[].payment.amount` (number): 
- `data[].payment.currency` (string, nullable): ISO currency of Amount, sourced from the collected payment and potentially
different from the invoice and payout currencies.
- `data[].payment.paymentDate` (datetime): 
- `data[].earnings` (object): 
- `data[].earnings.currency` (string, nullable): ISO currency of the payout-denominated earnings amounts, sourced from the payout's
frozen currency. This can differ from Payment's currency.
- `data[].earnings.debituraRevenue` (number): Debitura's share of the collection partner's commission on this payment, before your
referral fee is deducted, in the original transaction currency.
- `data[].earnings.debituraRevenueUsd` (number): Debitura's share of the collection partner's commission on this payment, before your
referral fee is deducted, converted to USD.
- `data[].earnings.netDebituraRevenueUsd` (number): Debitura's revenue on this payment after your referral fee is deducted
(DebituraRevenueUsd - ReferralFeeAmountUsd).
- `data[].earnings.successFeePercentageSnapshot` (number, nullable): Contractual success-fee rate frozen when this payout was created, expressed in percentage
points (for example, 30.00 means 30%). Null means no snapshot is available; it does not
identify the pricing type. This rate is contractual metadata and may differ from the actual
saved collection-partner allocation on non-standard payouts.
- `data[].earnings.collectionPartnerAmount` (number): Actual gross amount saved for the collection partner on this payout, denominated in
CollectionPartnerCurrency. This persisted allocation is the source of truth
and is not recalculated from SuccessFeePercentageSnapshot.
- `data[].earnings.collectionPartnerCurrency` (string, nullable): ISO currency of CollectionPartnerAmount, sourced from the payout's frozen
currency. Null when the payout currency is unavailable; payment currency is deliberately
not used as a fallback because it is independently editable.
- `data[].earnings.referralFeePercentage` (number): 
- `data[].earnings.referralFeeAmount` (number): Referral fee owed to you on this payment, in the payout's native currency. Zero when not yet settled and
CommissionPaymentStatus is "Credited" — the underlying
collection-partner commission was written off. Already invoiced, paid or disputed referral
earnings retain their recorded amount.
- `data[].earnings.referralFeeAmountUsd` (number): Same as ReferralFeeAmount, converted to USD, preserving the same settled-history exception.
- `data[].earnings.isEstimate` (boolean): True only when CommissionPaymentStatus is "Unpaid" — the final amount may still change based
on FX rates or the underlying commission not materializing. False for "Paid" (final) and for
"Credited" (final: zero for pending earnings, or the retained amount for already
invoiced, paid or disputed earnings).
- `data[].recognition` (object): 
- `data[].recognition.isRecognized` (boolean): Whether revenue has been recognized: PlatformInvoicingStatus == PaymentReceived AND
the commission has not been written off, or its referral earnings were already
invoiced, paid or disputed before the write-off.
- `data[].recognition.referralFeeRecognizedUsd` (number): Recognized referral fee amount in USD (0 if not yet recognized)
- `data[].status` (object): 
- `data[].status.commissionPaymentStatus` (string, nullable): Commission payment status: "Unpaid" | "Paid" | "Credited"
Tracks whether the collection partner has received the underlying commission.
Unpaid = not yet received (estimate). Paid = confirmed and received.
Credited = the commission was written off — the collection partner will not pay it. A
Credited transaction remains visible here and in the unfiltered transactions list, but its
pending earnings become zero and IsEstimate is false. Already invoiced, paid or disputed
referral earnings retain their amounts and stages. Current revenue summary totals exclude
credited transactions.
- `data[].status.platformInvoicingStatus` (string, nullable): Platform invoicing status: "NotInvoiced" | "InvoiceIssued" | "PaymentReceived" | "InvoiceCredited"
Tracks Debitura's invoicing lifecycle with the collection partner.
- `data[].status.referralInvoicingStatus` (string, nullable): Referral invoicing status: "Pending" | "Invoiced" | "Paid" | "Disputed"
Tracks the referral partner's invoicing with Debitura. Set only via manual DB operation —
no application code path writes anything but "Pending" (at payout creation).
- `page` (object): Paging metadata describing a paged result set.
- `page.totalResults` (integer): Total number of records for the query (filtered or all as applicable).
- `page.pageSize` (integer): How many records are returned per page.
- `page.currentPage` (integer): Which page number is being shown, calculated from the number of skipped items.
- `page.responseCount` (integer): How many records are present in the current page.
- `page.totalPages` (integer): Total number of pages available given TotalResults and PageSize.
Returns 0 if PageSize is 0 rather than dividing by zero.
- `summary` (object): 
- `summary.revenue` (object): Pending stages exclude written-off commission. Already invoiced, paid or disputed referral
earnings remain in their corresponding stages. Credited transactions remain visible in the
unfiltered list with their commission status unchanged.
- `summary.revenue.pendingReferralFeeUsd` (number): Stage 1: Pending — CommissionPaymentStatus=Unpaid (exactly), PlatformInvoicingStatus=
NotInvoiced, and ReferralInvoicingStatus=null/Pending (excludes payouts already invoiced/paid to
the referral partner via a commission clawback after settlement — see Stage 5/6).
Fee is speculative. Depends on the client paying the collection partner. Amount may change.
- `summary.revenue.pendingCount` (integer): 
- `summary.revenue.confirmedPendingInvoiceReferralFeeUsd` (number): Stage 2: Confirmed, awaiting Debitura invoice — CommissionPaymentStatus=Paid, PlatformInvoicingStatus=NotInvoiced,
and ReferralInvoicingStatus=null/Pending (excludes payouts already invoiced/paid to the referral
partner — see Stage 5/6).
Fee is confirmed. Debitura will invoice the collection partner on the next billing cycle (8th of month).
- `summary.revenue.confirmedPendingInvoiceCount` (integer): 
- `summary.revenue.awaitingCollectionPartnerPaymentReferralFeeUsd` (number): Stage 3: Awaiting collection partner payment — PlatformInvoicingStatus=InvoiceIssued and
ReferralInvoicingStatus=null/Pending (excludes payouts already invoiced/paid to the referral
partner — see Stage 5/6).
Debitura has invoiced the collection partner. Payment expected within 30 days.
- `summary.revenue.awaitingCollectionPartnerPaymentCount` (integer): 
- `summary.revenue.readyToInvoiceDebituraReferralFeeUsd` (number): Stage 4: Ready to invoice Debitura — PlatformInvoicingStatus=PaymentReceived and ReferralInvoicingStatus=null/Pending.
Collection partner has paid Debitura. Referral partner can now invoice Debitura.
- `summary.revenue.readyToInvoiceDebituraCount` (integer): 
- `summary.revenue.awaitingDebituraPaymentReferralFeeUsd` (number): Stage 5: Awaiting Debitura payment — ReferralInvoicingStatus=Invoiced. NOT gated on
PlatformInvoicingStatus: that tracks Debitura's own invoicing cycle with the collection partner,
an independent axis from the referral partner's invoicing state (ConfirmedPipeline partners can
be invoiced/paid before Debitura's own PlatformInvoicingStatus reaches PaymentReceived).
Referral partner has invoiced Debitura. Payment expected within 20 business days.
Disputed amounts are excluded — see DisputedReferralFeeUsd.
- `summary.revenue.awaitingDebituraPaymentCount` (integer): 
- `summary.revenue.paidReferralFeeUsd` (number): Stage 6: Paid — ReferralInvoicingStatus=Paid. NOT gated on PlatformInvoicingStatus — see Stage 5.
Debitura has paid the referral partner.
- `summary.revenue.paidCount` (integer): 
- `summary.revenue.disputedReferralFeeUsd` (number): Disputed — ReferralInvoicingStatus=Disputed. NOT gated on PlatformInvoicingStatus — see Stage 5.
Deliberately excluded from every other bucket (including "ready to invoice" / "awaiting payment"
totals): per business rules, disputed referral fees must be shown separately, not folded
into a "payment expected" lifecycle stage, since the amount may still be reduced, corrected, or
reverted.
- `summary.revenue.disputedCount` (integer): 
- `summary.totalDebituraRevenueUsd` (number): Current total Debitura revenue across all matching transactions, before referral fees are
deducted. Excludes any transaction whose CommissionPaymentStatus is "Credited" —
this is a current/non-Credited summary total, and intentionally does not equal the sum of
gross Payout.DebituraRevenueInUsd still visible per-row in the unfiltered transactions list,
since a credited payout's own record is never zeroed or recomputed there.
- `summary.netTotalDebituraRevenueUsd` (number): Same as TotalDebituraRevenueUsd, after referral fees are deducted. Also excludes
Credited transactions.

```json
{
  "data": [
    {
      "transactionId": "3f2b6c1e-8a4d-4b7f-9c2e-5d1a0b9e7f31",
      "payoutId": "3f2b6c1e-8a4d-4b7f-9c2e-5d1a0b9e7f31",
      "date": "2026-10-01T14:05:00Z",
      "client": {
        "externalTenantId": "string",
        "creditorId": "3f2b6c1e-8a4d-4b7f-9c2e-5d1a0b9e7f31",
        "companyName": "Muster GmbH"
      },
      "case": {
        "invoiceId": "3f2b6c1e-8a4d-4b7f-9c2e-5d1a0b9e7f31",
        "caseReference": "INV-2026-0042",
        "debtorName": "Muster GmbH",
        "originalAmount": 2500,
        "currency": "EUR",
        "collectionPartner": "string"
      },
      "payment": {
        "amount": 2500,
        "currency": "EUR",
        "paymentDate": "2026-10-01T14:05:00Z"
      },
      "earnings": {
        "currency": "EUR",
        "debituraRevenue": 1.5,
        "debituraRevenueUsd": 1.5,
        "netDebituraRevenueUsd": 1.5,
        "successFeePercentageSnapshot": 2500,
        "collectionPartnerAmount": 2500,
        "collectionPartnerCurrency": "EUR",
        "referralFeePercentage": 2500,
        "referralFeeAmount": 2500,
        "referralFeeAmountUsd": 2500,
        "isEstimate": true
      },
      "recognition": {
        "isRecognized": true,
        "referralFeeRecognizedUsd": 2500
      },
      "status": {
        "commissionPaymentStatus": "string",
        "platformInvoicingStatus": "string",
        "referralInvoicingStatus": "string"
      }
    }
  ],
  "page": {
    "totalResults": 42,
    "pageSize": 25,
    "currentPage": 1,
    "responseCount": 42,
    "totalPages": 1
  },
  "summary": {
    "revenue": {
      "pendingReferralFeeUsd": 2500,
      "pendingCount": 42,
      "confirmedPendingInvoiceReferralFeeUsd": 2500,
      "confirmedPendingInvoiceCount": 42,
      "awaitingCollectionPartnerPaymentReferralFeeUsd": 2500,
      "awaitingCollectionPartnerPaymentCount": 42,
      "readyToInvoiceDebituraReferralFeeUsd": 2500,
      "readyToInvoiceDebituraCount": 42,
      "awaitingDebituraPaymentReferralFeeUsd": 2500,
      "awaitingDebituraPaymentCount": 42,
      "paidReferralFeeUsd": 2500,
      "paidCount": 42,
      "disputedReferralFeeUsd": 2500,
      "disputedCount": 42
    },
    "totalDebituraRevenueUsd": 2500,
    "netTotalDebituraRevenueUsd": 2500
  }
}
```

### Response 400

Invalid request parameters (e.g., invalid date format, page size too large)

- `error` (string, nullable): Short human-readable error label (legacy field — preserved for backward compatibility).
- `message` (string, nullable): Human-readable error description (legacy field — preserved for backward compatibility).
- `businessErrors` (array of objects, nullable): Canonical structured error array. Consumers should migrate to reading this field.
- `businessErrors[].type` (string, nullable): The type of business error (e.g., "MissingDebtCollectionContract", "MissingPowerOfAttorney", "NoPartnerAvailable").
- `businessErrors[].message` (string, nullable): A human-readable description of the error.
- `businessErrors[].solutionUrl` (string, nullable): A URL where the user can resolve this <i>specific</i> error (e.g., sign a contract).
            

Partners who want a <b>single URL</b> that walks the user through every pending
signing in one chain — instead of forwarding one URL per
`BusinessErrorApiDTO` — should use
SigningHandoff's `CombinedSigningUrl`.
The two are complementary: `SolutionUrl` is granular per-error;
`CombinedSigningUrl` is the chain-walking alternative for signing-related errors.

```json
{
  "error": null,
  "message": "Payment plan agreed with the debtor.",
  "businessErrors": [
    {
      "type": "string",
      "message": "Payment plan agreed with the debtor.",
      "solutionUrl": "https://app.debitura.com/…"
    }
  ]
}
```

### Response 500

Internal server error

- `error` (string, nullable): Short human-readable error label (legacy field — preserved for backward compatibility).
- `message` (string, nullable): Human-readable error description (legacy field — preserved for backward compatibility).
- `businessErrors` (array of objects, nullable): Canonical structured error array. Consumers should migrate to reading this field.
- `businessErrors[].type` (string, nullable): The type of business error (e.g., "MissingDebtCollectionContract", "MissingPowerOfAttorney", "NoPartnerAvailable").
- `businessErrors[].message` (string, nullable): A human-readable description of the error.
- `businessErrors[].solutionUrl` (string, nullable): A URL where the user can resolve this <i>specific</i> error (e.g., sign a contract).
            

Partners who want a <b>single URL</b> that walks the user through every pending
signing in one chain — instead of forwarding one URL per
`BusinessErrorApiDTO` — should use
SigningHandoff's `CombinedSigningUrl`.
The two are complementary: `SolutionUrl` is granular per-error;
`CombinedSigningUrl` is the chain-walking alternative for signing-related errors.

```json
{
  "error": null,
  "message": "Payment plan agreed with the debtor.",
  "businessErrors": [
    {
      "type": "string",
      "message": "Payment plan agreed with the debtor.",
      "solutionUrl": "https://app.debitura.com/…"
    }
  ]
}
```