Skip to main content
Referral Partner API

Reporting

Base URL
https://referral-api.debitura.com
Authentication
API key in the XApiKey header

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

  • FromDatedatetime

    Filter transactions from this date (inclusive). ISO 8601 format.

  • ToDatedatetime

    Filter transactions to this date (inclusive). ISO 8601 format.

  • ExternalTenantIdstring

    Filter by specific client's external tenant ID

  • HasRecognizedRevenueboolean

    When true, only show transactions where revenue has been recognized (collection partner has paid Debitura). When false, only show unrecognized transactions.

  • CommissionPaymentStatusesarray of enums

    Filter by commission payment status (Unpaid = 0, Paid = 1, Credited = 2). Tracks whether Debitura has received the collection partner's commission.

  • PlatformInvoicingStatusesarray of enums

    Filter by platform invoicing status (NotInvoiced = 0, InvoiceIssued = 1, PaymentReceived = 2, InvoiceCredited = 3). Tracks Debitura's invoicing lifecycle with the collection partner.

  • ReferralInvoicingStatusesarray of enums

    Filter by referral invoicing status (Pending = 0, Invoiced = 1, Paid = 2)

  • RevenueStagesarray 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.

  • Searchstring

    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.

  • Pageinteger

    Page number (1-indexed)

    Min 1
  • PageSizeinteger

    Number of results per page (default: 10, max: 100)

    1 to 100
  • CountryIdsarray 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.

  • CollectionPartnerIdsarray 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.

  • Sortstring

    Sort field and direction. Format: "field[:asc|desc]" Supported fields: collectionDate, amount Examples: "collectionDate:desc", "amount:asc" Default: collectionDate:desc

Returns

200 Transactions retrieved successfully

  • dataarray of objectsnullable
  • pageobject

    Paging metadata describing a paged result set.

  • summaryobject

Errors

400Invalid request parameters (e.g., invalid date format, page size too large)
500Internal server error

See Error handling.

GET/reporting/transactions
curl https://referral-api.debitura.com/reporting/transactions \
  -H "XApiKey: $DEBITURA_API_KEY"
Response
{
  "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
  }
}