---
title: "Preview case pricing"
method: POST
path: "/cases/preview"
tags: ["PreviewCases"]
---

# Preview case pricing

`POST /cases/preview`

Preview the success fee pricing for a potential case without creating it.

**What This Endpoint Returns:**
- IsEligible - Whether the case can be submitted (partner available in this jurisdiction)
- PricingPreview - Estimated success fee with base rate and any age-based surcharges
- Jurisdiction - Geographic details for the matched jurisdiction

**Use This To:**
1. Show your clients the Debitura success fee before they onboard
2. Check if a jurisdiction is supported before starting the onboarding flow
3. Display age-adjusted pricing for aged debt portfolios

**Required Fields:**
- AmountToRecover - Total principal amount
- CurrencyCode - ISO 4217 currency code (e.g., 'GBP', 'EUR', 'USD')
- Debtor.Type - 'Company' or 'Private'
- Debtor.CountryAlpha2 - ISO 3166-1 alpha-2 country code
- Debtor.StateAlpha2 - Required for US cases only (e.g., 'CA', 'NY')

**Age-Based Pricing (Optional)**

**Single invoice — pass `dueDate`:** The simplest way to get age-adjusted pricing. Provide the invoice due date (ISO 8601, e.g. `2024-01-15`) and Debitura computes the age surcharge internally. Cannot be a future date. Mutually exclusive with age bucket fields.

**Multi-invoice portfolio — pass age buckets:** For portfolios with invoices at different ages, pass the portion of the total that falls into each age bracket:
- `AmountToRecoverOver12Months` and `AmountToRecoverOver24Months` must be provided together
- `AmountToRecoverOver6Months` is optional but improves pricing tier accuracy at the 180-day threshold; can only be provided alongside the 12/24-month fields, must be >= `AmountToRecoverOver12Months`, and must be <= `AmountToRecover`

`dueDate` and age bucket fields are mutually exclusive — use one or the other. When no age fields are provided, base pricing is returned without age surcharge.

**Important Notes:**
- This endpoint does NOT create a case — it only previews pricing
- Pricing is based on the referral partner's agreed rate (jurisdiction pricing zone rate if applicable)
- No creditor or client account is needed

## Request body

- DebituraWebExternalApiContractsV1CasesRequestsPreviewCaseRequestApiViewModel — Request model for previewing case eligibility, partner assignment, and required actions before actually creating a collection case. This endpoint allows you to check: - Whether a case would be eligible for collection (partner coverage available) - Which partner would be assigned - What documents need to be signed (SDCA, Power of Attorney) - Estimated pricing with age-based surcharges Use this to guide users through document signing before final case submission.
  - `amountToRecover` number, double, required — The TOTAL amount to recover for this case. This represents the full principal amount across all invoices (if multiple invoices are bundled). For multi-invoice cases with different ages, you can optionally provide age breakdown fields (AmountToRecoverOver12Months and AmountToRecoverOver24Months) to enable blended age-based pricing. If age breakdown fields are omitted, the preview will show base pricing without age surcharge calculation.
  - `currencyCode` string, required — ISO 4217 currency code for the amount (e.g., "DKK", "EUR", "USD")
  - `debtor` DebituraWebExternalApiContractsV1CasesRequestsPreviewDebtorDto, required — Simplified debtor information for case preview. Only includes the minimum fields required for partner routing and eligibility checking.
    - `type` string, required — Debtor type. Valid values: "Company" or "Private" This affects partner selection as different partners may specialize in B2B vs B2C collection.
    - `countryAlpha2` string, required — Country code (ISO 3166-1 alpha-2 format, e.g., "DK", "US", "PL") Used to determine jurisdiction and available collection partners.
    - `stateAlpha2` string, nullable — US state code (e.g., "CA", "NY") REQUIRED for United States cases only, as US partner coverage is state-specific. Optional for other countries.
  - `amountToRecoverOver6Months` number, double, nullable — OPTIONAL - MULTI-INVOICE AGE BUCKET PRICING (PRICING ZONE 180-DAY THRESHOLD) The portion of AmountToRecover that is more than 6 months (180 days) overdue. This includes amounts that are 12+ and 24+ months overdue. This field is optional and can only be provided alongside AmountToRecoverOver12Months and AmountToRecoverOver24Months. It enables precise pricing tier selection based on the 180-day threshold. When omitted, the system falls back to deriving the threshold from AmountToRecoverOver12Months. Validation rules: - Must be ≤ AmountToRecover - Must be ≥ AmountToRecoverOver12Months
  - `amountToRecoverOver12Months` number, double, nullable — OPTIONAL - MULTI-INVOICE AGE BUCKET PRICING The portion of AmountToRecover that is more than 12 months overdue. This includes amounts that are 24+ months overdue. If provided, AmountToRecoverOver24Months must also be provided. Both fields must be provided together or both omitted. Used to calculate blended age uplift for multi-invoice cases: - Amount under 12 months = AmountToRecover - AmountToRecoverOver12Months - Amount 12-24 months = AmountToRecoverOver12Months - AmountToRecoverOver24Months - Amount over 24 months = AmountToRecoverOver24Months Blended uplift formula: ((A12-A24)×10 + A24×20) / AmountToRecover where A12 = AmountToRecoverOver12Months, A24 = AmountToRecoverOver24Months Validation rules: - Must be ≤ AmountToRecover - Must be ≥ AmountToRecoverOver24Months
  - `amountToRecoverOver24Months` number, double, nullable — OPTIONAL - MULTI-INVOICE AGE BUCKET PRICING The portion of AmountToRecover that is more than 24 months overdue. If provided, AmountToRecoverOver12Months must also be provided. Both fields must be provided together or both omitted. Used to calculate blended age uplift for multi-invoice cases. See AmountToRecoverOver12Months for full details on the calculation. Validation rules: - Must be ≤ AmountToRecoverOver12Months - Must be ≤ AmountToRecover
  - `dueDate` string, date-time, nullable — Optional invoice due date. Mutually exclusive with age bucket fields. If provided, Debitura computes the age surcharge internally — no need to calculate age buckets. Cannot be a future date.
  - `returnUrl` string, nullable — Optional: URL the creditor user should land on after completing any pending signing chain (SDCA upgrade / PoA / JPA / KYC) on the Debitura Creditors app. Embedded, URL-encoded, into `PreviewCaseResponseApiViewModel.Result.SigningHandoff.CombinedSigningUrl` (when at least one signing-related required action is present) and into `BusinessErrorResponseApiDTO.SigningHandoff.CombinedSigningUrl` / `InvoiceDto.SigningHandoff.CombinedSigningUrl` on POST `/cases`. Must be an absolute http(s) URL. Values that fail validation (relative URLs, non-http schemes, header-injection characters) are silently dropped — the combined URL is still emitted but without the returnUrl query parameter, and the Creditors app falls back to its own safe in-app default landing. Additive. Existing integrations that omit this field see the same behaviour as before.

## Response `200`

Preview completed

- DebituraWebReferralPartnerApiModelsCasesReferralPartnerPreviewCaseResponse — Response from the Referral Partner pricing preview endpoint. Returns eligibility, jurisdiction, estimated success fee pricing, and any actions that the creditor will need to complete before cases can be submitted (PoA, KYC, SDCA upgrade).
  - `isEligible` boolean — Whether the case is eligible for collection (a partner is available in the requested jurisdiction). If false, check IneligibilityReason for details.
  - `ineligibilityReason` string, nullable — Explanation of why the case is not eligible (only present when IsEligible = false). Common reasons: "We don't have an exclusive pre-legal partner in the provided jurisdiction."
  - `jurisdiction` DebituraWebExternalApiContractsV1CasesJurisdictionDto — Geographic jurisdiction information for the case.
    - `id` integer — Internal jurisdiction identifier.
    - `name` string, nullable — Display name of the jurisdiction (e.g., "Denmark", "United States - California").
    - `countryAlpha2` string, nullable — ISO 3166-1 alpha-2 country code.
    - `stateAlpha2` string, nullable — ISO 3166-2 state/region code (only for countries with state-level routing like the US).
  - `pricingPreview` DebituraWebExternalApiContractsV1CasesPricingPreviewDto — Estimated pricing for the case, including age-based surcharges.
    - `baseSuccessFeePercentage` number, double — Base success fee percentage before age surcharges. This is the standard rate for cases under 12 months overdue.
    - `ageSurchargePercentage` number, double — Additional percentage points added for aged invoices. Calculated based on invoice age: - 12-24 months overdue: +8 percentage points - 24+ months overdue: +15 percentage points - Multi-invoice with mixed ages: blended rate (0-15 percentage points)
    - `totalSuccessFeePercentage` number, double — Total success fee percentage (base + age surcharge). This is the percentage of the recovered amount that will be charged as a success fee.
    - `currencyCode` string, nullable — ISO 4217 currency code for the case.
    - `pricingSource` string, nullable — Which pricing rule determined the fee. Possible values: "Standard agreement", "Creditor custom pricing", "Managing partner custom pricing", "Jurisdiction custom pricing", "Partner custom pricing", "Accepted quote".
    - `pricingSourceDescription` string, nullable — Human-readable explanation of why this pricing was applied. Example: "9.5% success fee — BD Legal custom collection rates (EU zone, $1,000–$7,999 tier)"
  - `requiresKycVerification` boolean — Whether the resolved collection partner requires KYC verification before cases can be submitted. When true, the creditor must complete KYC verification before case creation. Use the case creation endpoint with a creditor ID to determine whether KYC is already on file.
  - `pendingActions` DebituraWebReferralPartnerApiModelsCasesPendingActionDto[], nullable — Structured list of actions the creditor will need to complete before (or as part of) submitting cases for the matched collection partner. Always present — empty when nothing is pending. At preview time the request is creditor-less, so this list reflects the matched partner's hard requirements (e.g. PoA per partner, KYC if the partner is configured for it). Creditor-specific items such as SDCA upgrade are returned only when the API has creditor context. Additive over Debitura.Web.ReferralPartnerApi.Models.Cases.ReferralPartnerPreviewCaseResponse.RequiresKycVerification — old clients that only read Debitura.Web.ReferralPartnerApi.Models.Cases.ReferralPartnerPreviewCaseResponse.RequiresKycVerification are unaffected.
    - `type` 'SdcaUpgrade' | 'PoA' | 'Jpa' | 'Kyc' — Type of action that may need to be completed by the creditor before (or as part of) submitting cases via the referral partner API. New values may be added in future API versions — clients should treat unknown values as informational and not crash. Wire format is LOCKED to NAMED STRING values (e.g. `"PoA"`, `"Kyc"`) via Newtonsoft.Json.Converters.StringEnumConverter. The host serializer for this API is Newtonsoft.Json (`AddNewtonsoftJson` in `Program.cs`), so a `System.Text.Json``JsonStringEnumConverter` attribute would be silently ignored — hence the explicit Newtonsoft converter here. Numeric values below mirror `Domain.CombinedSigningStep` (SdcaUpgrade=1, PoA=2, Jpa=3, Kyc=4, Done=5) by convention, but they are an internal implementation detail. Clients MUST consume the string names; the numbers are not part of the public contract. Renumbering or removing already-released values is forbidden — see `Debitura.Wiki/engineering/development-philosophy/backend-standards.md` (line 102: "Never renumber or remove released enum values"). The System.Text.Json.Serialization.JsonStringEnumConverter attribute is declared in addition so that consumers (and our own integration tests) who parse responses using `System.Text.Json` can deserialize the string form back into this enum. The Newtonsoft converter is what actually controls outbound wire format on this host.
    - `collectionPartnerId` string, uuid, nullable — The collection partner this action is scoped to, when applicable. Set for partner-specific actions (PoA, KYC). Null for actions that are not partner-scoped (e.g. SDCA upgrade, which is platform-wide).
    - `dueDate` string, date-time, nullable — Optional deadline by which the action must be completed (UTC). Reserved for orchestrator-generated payloads (the orchestrator endpoint), where SDCA-upgrade entries can include their refresh deadline. Always null on the `/cases/preview` endpoint, since preview is creditor-less and SDCA-upgrade is not surfaced there.
  - `combinedSigningUrl` string, nullable — Always `null` on `/cases/preview` because preview is creditor-less — no concrete creditor signing state exists to chain. The structured Debitura.Web.ReferralPartnerApi.Models.Cases.ReferralPartnerPreviewCaseResponse.PendingActions array on this response indicates which step types the matched partner will require ahead of onboarding. The canonical placement for the combined-signing URL on POST `/cases` responses is the nested `SigningHandoff` envelope (a `SigningHandoffDto` on both `BusinessErrorResponseApiDTO` and `InvoiceDto`). The combined URL is populated on POST `/cases` responses, where the creditor IS identified: <list type="bullet"><item><description>422 with at least one signing-related business error (`MissingDebtCollectionContract`, `MissingPowerOfAttorney`, `MissingKycVerification`) — see `BusinessErrorResponseApiDTO.SigningHandoff.CombinedSigningUrl`.</description></item><item><description>200 with `AllowPendingContracts=true` when signings remain — see `InvoiceDto.SigningHandoff.CombinedSigningUrl`.</description></item></list> Both POST surfaces use the same Creditors-app `/Signing/PendingContracts` entry point and walk the SDCA-upgrade → PoA → JPA → KYC chain end-to-end. This flat `CombinedSigningUrl` field on `/cases/preview` is preserved as-is for backward compatibility (it is always null in practice).

## Other responses

- `400` — Invalid request (validation errors)
- `500` — Internal server error

---

[API](https://skmtc.net/debitura/apis/debitura-referral-partner-api.md) · [All operations](https://skmtc.net/debitura/apis/debitura-referral-partner-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/debitura/debitura-referral-partner-api/versions/9c466e0e2bf4/schema)