Source: https://docs.debitura.com/referral-partners/integration-guides/preview-case-pricing

# Preview Case Pricing

Look up the Debitura success fee for a potential case before your client onboards. No case is created and no client account is required.

Works with both integrations

Preview uses only your API key, so a [Starter Integration](https://docs.debitura.com/referral-partners/integration-guides/starter-integration.md) can call it too, to show the fee before the user clicks "Send to collection".

<a id="overview"></a>

## Overview

Call `POST /cases/preview` to check whether a jurisdiction is covered and what the success fee will be. Use this in your sales or onboarding flow to show clients their expected fee upfront, or to gate the onboarding flow based on coverage.

Pricing returned reflects your referral partner's agreed rate — including zone pricing where applicable.

**Business context:** See [Success Fees](https://support.debitura.com/en/articles/13429835-success-fees-how-pricing-is-calculated-claim-size-region-age) for how Debitura calculates pricing, including age-based surcharge tiers.

<a id="implementation"></a>

## Implementation

<a id="check-eligibility-and-pricing"></a>

### Check eligibility and pricing

```http
POST https://referral-api.debitura.com/cases/preview
XApiKey: YOUR_API_KEY
Content-Type: application/json

{
  "amountToRecover": 50000,
  "currencyCode": "GBP",
  "debtor": {
    "type": "Company",
    "countryAlpha2": "GB"
  }
}
```

For US debtors, send `debtor.stateAlpha2` (e.g. `"CA"`, `"NY"`) to get state-level pricing; without it the preview prices on the US country-default jurisdiction.

<a id="read-the-response"></a>

### Read the response

**Eligible:**

```json
{
  "isEligible": true,
  "ineligibilityReason": null,
  "requiresKycVerification": false,
  "jurisdiction": {
    "id": 42,
    "name": "United Kingdom",
    "countryAlpha2": "GB",
    "stateAlpha2": null
  },
  "pricingPreview": {
    "baseSuccessFeePercentage": 18.0,
    "ageSurchargePercentage": 0.0,
    "totalSuccessFeePercentage": 18.0,
    "currencyCode": "GBP",
    "pricingSource": "Standard agreement",
    "pricingSourceDescription": "18% success fee — Standard Debitura collection rates (International zone, $10,000–$49,999 tier)"
  },
  "pendingActions": [
    { "type": "PoA", "collectionPartnerId": "8a4f9c0e-..." }
  ],
  "combinedSigningUrl": null
}
```

`requiresKycVerification` indicates whether the matched collection partner requires KYC verification before cases can be submitted. When `true`, submit KYC data via the [KYC Verification](https://docs.debitura.com/referral-partners/integration-guides/kyc-verification.md) endpoint before creating cases.

The response also includes a `pendingActions` array that lists the signing-related steps the matched partner will require ahead of onboarding (typically a per-creditor Power of Attorney, plus a `Kyc` entry when the matched partner requires it). The list is always present and empty when nothing is pending. Each entry has the shape `{ "type": "PoA" | "Kyc", "collectionPartnerId": "<guid>" }`. Because the preview is creditor-less, creditor-specific items such as SDCA upgrade are not included here — they surface on `POST /cases` via the `signingHandoff` object.

The response also carries a top-level `combinedSigningUrl` field, which is reserved for future use and **always `null`** on `POST /cases/preview`. The chain-walking URL is only emitted on `POST /cases` responses (where the creditor is identified) — see [Case Submission](https://docs.debitura.com/referral-partners/integration-guides/case-submission.md#handling-pending-signing-after-submission).

You may pass an optional `returnUrl` on the request body. It is accepted on `/cases/preview` for forward compatibility and to keep the request shape identical to `POST /cases`, but it is never read by the preview endpoint — the controller has no dependency on the URL-safety logic used elsewhere, so `returnUrl` has no effect on the preview response regardless of its value. It has a 2048-character max length; exceeding it triggers standard model validation and returns an automatic `400`, it is not silently dropped.

`totalSuccessFeePercentage` is the definitive rate to use — it is `baseSuccessFeePercentage + ageSurchargePercentage` with all age adjustments already applied. Show this to clients and use it in calculations.

`pricingSource` tells you which pricing rule was applied. `pricingSourceDescription` gives a human-readable explanation including the fee, zone, and bracket. Possible `pricingSource` values:

| Value | Meaning |
| --- | --- |
| `Standard agreement` | Default Debitura SDCA rates |
| `Creditor custom pricing` | Custom rate agreed between creditor and partner |
| `Managing partner custom pricing` | Custom rate agreed between managing partner and partner |
| `Jurisdiction custom pricing` | Referral partner zone rate for a specific jurisdiction |
| `Partner custom pricing` | Collection partner's own custom rate brackets |
| `Accepted quote` | Custom quote for legal or non-standard cases |

**Ineligible:**

`jurisdiction` is always present — it reflects the resolved jurisdiction even when no partner is available there. When `isEligible` is `false`, `pricingPreview` is `null` and `ineligibilityReason` explains why.

```json
{
  "isEligible": false,
  "ineligibilityReason": "We don't have an exclusive pre-legal partner in the provided jurisdiction.",
  "jurisdiction": {
    "id": 15,
    "name": "Greenland",
    "countryAlpha2": "GL",
    "stateAlpha2": null
  },
  "pricingPreview": null
}
```

Do not proceed to onboarding for ineligible cases.

<a id="minimums-and-reason-codes"></a>

### Minimums and reason codes

Every response carries a stable `ineligibilityReasonCode` (`null` when eligible): `NoGeographicCoverage`, `AmountBelowMinimum`, `AmountAboveMaximum`, `DebtorTypeNotCovered`, `NotCoveredByPartnerRules`, `ExcludedForClient` or `EligibilityUndetermined`. Only `NoGeographicCoverage` means there is no partner in the jurisdiction. `AmountBelowMinimum` means the jurisdiction is covered and only the claim amount fell short, so do not ask the client to correct the address. `EligibilityUndetermined` is a transient failure on Debitura's side: retry.

Two optional amounts help you explain a minimum. Both are in the request's `currencyCode` and never below the 100 USD platform minimum:

| Field | Meaning |
| --- | --- |
| `applicableMinimumAmount`, `applicableMinimumCurrencyCode` | What this claim would have to reach to be accepted. Present only when no partner matched. Never returned for a client excluded from a partner in that market, who is told no partner can take the claim for their account. |
| `marketMinimumAmount`, `marketMinimumCurrencyCode` | The smallest claim the marketplace takes for this jurisdiction and debtor type. A statement about the market, returned whether or not a partner matched, and independent of the claim amount. It is not the admission rules applied when a case is created. `null` when no partner covers the market or the amount cannot be priced. |

`amountCheckUnavailable` is `true` when a currency conversion needed to evaluate the amount was unavailable, so the amount-based part of the answer was not checked. It can be `true` on an eligible answer: treat it as provisional and retry.

When the response is eligible but pricing needs an exchange rate that is unavailable, `pricingPreview` is `null` instead of the request failing. Retry before showing a fee.

<a id="age-based-pricing"></a>

### Age-based pricing

By default, the endpoint returns the base rate only. [Claim Amount and Age](https://docs.debitura.com/developer-concepts/claim-amount-and-age.md) explains the three supported aging modes:

-   **Single invoice** — pass `dueDate` (simplest)
-   **Multi-invoice ledger** — pass `claimLines` and let Debitura derive the total and age buckets (recommended)
-   **Pre-calculated portfolio** — pass `amountToRecover` and cumulative age bucket fields

`dueDate`, age bucket fields, and `claimLines` are mutually exclusive on pricing preview.

<a id="single-invoice-pass-duedate"></a>

### Single invoice: pass dueDate

Pass the invoice due date as an ISO 8601 date string (`YYYY-MM-DD`). Debitura computes the age surcharge internally — no bucket arithmetic needed.

**Example — single invoice, 14 months overdue:**

```http
POST https://referral-api.debitura.com/cases/preview
XApiKey: YOUR_API_KEY
Content-Type: application/json

{
  "amountToRecover": 50000,
  "currencyCode": "GBP",
  "dueDate": "2024-01-15",
  "debtor": {
    "type": "Company",
    "countryAlpha2": "GB"
  }
}
```

Response:

```json
{
  "isEligible": true,
  "ineligibilityReason": null,
  "requiresKycVerification": true,
  "jurisdiction": {
    "id": 42,
    "name": "United Kingdom",
    "countryAlpha2": "GB",
    "stateAlpha2": null
  },
  "pricingPreview": {
    "baseSuccessFeePercentage": 18.0,
    "ageSurchargePercentage": 8.0,
    "totalSuccessFeePercentage": 26.0,
    "currencyCode": "GBP",
    "pricingSource": "Standard agreement",
    "pricingSourceDescription": "18% success fee — Standard Debitura collection rates (International zone, $10,000–$49,999 tier)"
  }
}
```

<a id="portfolio-blended-age-pricing"></a>

### Portfolio: blended age pricing

For portfolios with invoices at different ages, pass the portion of the total that falls into each age bucket. `amountToRecoverOver12Months` and `amountToRecoverOver24Months` must always be provided together.

`amountToRecoverOver6Months` is optional — it improves zone tier accuracy for the 180-day threshold and must satisfy:

-   Can only be provided alongside both `amountToRecoverOver12Months` and `amountToRecoverOver24Months`
-   Must be `>=` `amountToRecoverOver12Months` (the 6-month bucket includes the 12-month bucket)
-   Must be `<=` `amountToRecover` (must be a subset of the total)

**Example — portfolio with mixed ages:**

```http
POST https://referral-api.debitura.com/cases/preview
XApiKey: YOUR_API_KEY
Content-Type: application/json

{
  "amountToRecover": 100000,
  "currencyCode": "GBP",
  "amountToRecoverOver6Months": 60000,
  "amountToRecoverOver12Months": 40000,
  "amountToRecoverOver24Months": 15000,
  "debtor": {
    "type": "Company",
    "countryAlpha2": "GB"
  }
}
```

The blended `ageSurchargePercentage` and resulting `totalSuccessFeePercentage` are calculated automatically.

<a id="portfolio-pass-claim-lines"></a>

### Portfolio: pass claim lines

When you have invoice-level outstanding balances, send those invoices instead of calculating the total and buckets yourself:

```json
{
  "currencyCode": "GBP",
  "claimLines": [
    { "dueDate": "2024-01-15", "amount": 423.42, "reference": "INV-1001" },
    { "dueDate": "2025-05-02", "amount": 700.87, "reference": "INV-1042" }
  ],
  "debtor": {
    "type": "Company",
    "countryAlpha2": "GB"
  }
}
```

Each `amount` is the invoice's outstanding balance after payments and credit notes. Omit `amountToRecover`, `dueDate`, and all age bucket fields when sending `claimLines`. The endpoint accepts at most 1,000 lines and returns indexed validation keys such as `ClaimLines[2].DueDate`.

<a id="error-handling"></a>

## Error handling

| Status | Field | Cause | Action |
| --- | --- | --- | --- |
| `401` | — | Missing or invalid `XApiKey` | Verify the API key is present in the request header |
| `400` | `amountToRecover` | Zero or negative | Validate positive numbers before calling |
| `400` | `debtor.type` | Value other than `Company` or `Private` | Check the debtor type mapping in your system |
| `400` | `debtor.countryAlpha2` | Unrecognised country code | Validate against ISO 3166-1 alpha-2 |
| `400` | `currencyCode` | Not a recognised 3-letter ISO 4217 code | Validate length (must be exactly 3 chars) and value |
| `400` | `dueDate` | Future date | Due date cannot be in the future |
| `400` | `dueDate` | Combined with any age bucket field | Use `dueDate` or age bucket fields — not both |
| `400` | `claimLines` | Empty, over 1,000 lines, or combined with another amount-and-age mode | Send 1–1,000 lines and omit `amountToRecover`, `dueDate`, and age bucket fields |
| `400` | `ClaimLines[n].amount` | Zero, negative, or more than 2 decimal places | Send the positive outstanding balance with at most 2 decimal places |
| `400` | `ClaimLines[n].dueDate` | Missing, before 2000-01-01, or in the future | Send a valid invoice due date |
| `400` | `amountToRecoverOver12Months` | Provided without `amountToRecoverOver24Months` (or vice versa) | Always send the 12- and 24-month fields together |
| `400` | `amountToRecoverOver6Months` | Provided without `amountToRecoverOver12Months` and `amountToRecoverOver24Months` | Over6 requires both 12- and 24-month fields |
| `400` | `amountToRecoverOver6Months` | Less than `amountToRecoverOver12Months` | The 6-month bucket must include the 12-month bucket |
| `400` | `amountToRecoverOver6Months` | Exceeds `amountToRecover` | Age bucket values must be subsets of the total |
| `400` | `amountToRecoverOver12Months` | Exceeds `amountToRecover` | Age bucket values must be subsets of the total |
| `400` | `amountToRecoverOver24Months` | Exceeds `amountToRecoverOver12Months` | The 24-month bucket must be a subset of the 12-month bucket |
| `400` | any age field | Negative value | All age bucket values must be non-negative |

400 responses come in three shapes:

1.  **Field-keyed** `{ "fieldName": ["error message"] }` — age-bucket and `dueDate` validation.
2.  **Structured `ApiErrorResponseDto`** `{ "error", "message", "businessErrors": [] }` — value-level business validations (`amountToRecover`, `debtor.type`, `currencyCode`, `debtor.countryAlpha2`/state).
3.  **ASP.NET `ProblemDetails`** — model-binding errors (e.g. wrong field type, malformed JSON).

Once pricing is confirmed, continue with [Client Onboarding](https://docs.debitura.com/referral-partners/integration-guides/client-onboarding.md). See the [Preview case pricing API reference](https://docs.debitura.com/api/referral-partner-api/cases.md#preview-case-pricing) for the full request and response schema.
