Source: https://docs.debitura.com/referral-partners/concepts/jurisdiction-pricing-carveouts

# Jurisdiction Pricing Zones

How bilateral agreements control **partner routing, pricing, and contract requirements** for specific debtor jurisdictions.

Formerly called "Carve-Outs"

This feature was previously referred to as jurisdiction carve-outs or `JurisdictionPricingCarveOut` in older API versions. The current name is **Jurisdiction Pricing Zone** (`JurisdictionPricingZone`).

<a id="what-is-a-jurisdiction-pricing-zone"></a>

## What Is a Jurisdiction Pricing Zone?

A **jurisdiction pricing zone** is a bilateral agreement between Debitura and a referral partner that applies to a specific combination of referral partner + debtor country. When a zone is active, it controls three things:

1.  **Routing** — cases in the zone's jurisdiction are assigned to a specific collection partner, bypassing the standard partner-matching process
2.  **Pricing** — custom success fee tiers replace the standard SDCA pricing
3.  **Contract requirements** — a Jurisdiction Pricing Appendix (JPA) may need to be signed before cases proceed

Zones are **per-debtor-jurisdiction**, not partner-wide. Whether a zone applies depends on the country of the specific debtor in the case — not on the referral partner's country or account-level settings.

Zones affect routing

When a zone is active for a jurisdiction, **all cases in that jurisdiction are routed to the zone's designated collection partner**. This takes priority over Debitura's standard partner-matching logic. The zone partner handles every case in that jurisdiction regardless of claim size — even sub-threshold claims that fall back to standard SDCA pricing.

**Business context:** See [Referral program overview](https://support.debitura.com/en/articles/13908998-referral-partners-referral-program-overview-what-you-earn-when-and-what-counts) for details on how referral pricing is structured.

<a id="decision-flow"></a>

## Decision Flow

When a case is submitted for a debtor in a jurisdiction where a zone exists:

**Key points:**

-   Whether a JPA must be signed depends only on whether an appendix-bearing zone applies to the debtor's country — **not** on the claim amount. A sub-threshold case in an appendix-bearing zone still returns `422 MissingPowerOfAttorney` until the JPA is signed.
-   Claim amount affects **pricing only** — claims below the zone's lowest tier fall through to standard SDCA pricing while still being routed to the zone partner.
-   The API never returns a zone-specific error — all missing signing requirements surface as `MissingPowerOfAttorney`

<a id="amount-thresholds"></a>

## Amount Thresholds

A zone defines a set of **pricing tiers** covering specific claim amount brackets. Claims that fall **below the lowest bracket** are not covered by the zone's tiers and fall through to standard SDCA pricing instead.

This means:

-   The threshold only determines **which pricing applies** (a zone tier vs. standard SDCA fall-through) — it does **not** affect whether a JPA must be signed
-   A sub-threshold case in an appendix-bearing zone still requires a signed JPA and returns `422 MissingPowerOfAttorney` until it is signed
-   The exact threshold is specific to your zone configuration — confirm the value with Debitura

<a id="signing-scenarios"></a>

## Signing Scenarios

When a case is created, Debitura evaluates whether a zone applies to the debtor's country and amount. This determines what signing, if any, is required before the case can proceed.

Whether a JPA is required depends on the existence of an active **appendix-bearing** zone for the debtor's country (a zone configured with a pricing appendix and not internal-only) — not on the claim amount.

| Scenario | What the API requires |
| --- | --- |
| No zone for debtor country | Standard SDCA + PoA flow (no zone involvement) |
| Zone without a pricing appendix (routing/pricing only) | Standard SDCA + PoA flow — no JPA required |
| Appendix-bearing zone applies, JPA not signed | Same 422 as missing PoA — `solutionUrl` points to PoA signing page |
| Appendix-bearing zone applies, JPA already signed | Case proceeds normally |

Internally, the PoA signing flow handles three combinations:

| PoA needed | JPA needed | What happens |
| --- | --- | --- |
| true | true | PoA and JPA documents are merged — one signature covers both |
| true | false | PoA document only |
| false | true | JPA document is presented as PoA |
| false | false | All signing complete — no action needed |

From the API's perspective, the distinction between PoA and JPA is never surfaced. The signing URL always points to the same PoA signing flow, regardless of which documents are bundled inside.

<a id="how-the-api-communicates-zone-requirements"></a>

## How the API Communicates Zone Requirements

<a id="error-on-case-creation"></a>

### Error on Case Creation

When a case requires a JPA that has not been signed, the API returns `422 Unprocessable Entity` with a `MissingPowerOfAttorney` business error — the same error returned for a missing PoA. The `solutionUrl` always points to the PoA signing page.

```json
{
  "businessErrors": [
    {
      "type": "MissingPowerOfAttorney",
      "message": "Power of attorney not signed with partner X.",
      "solutionUrl": "https://referral.debitura.com/PowerOfAttorney/Sign/..."
    }
  ]
}
```

`MissingJurisdictionPricingAppendix` is never returned by the API. All missing-signing requirements, including zone requirements, surface as `MissingPowerOfAttorney`. See [Error Handling](https://docs.debitura.com/developer-concepts/error-handling.md) for how to handle 422 responses.

<a id="checking-contract-status"></a>

### Checking Contract Status

Use `GET /cases/{id}/contract-status` to determine what signing is outstanding for a case in `PendingContractSigning` state.

```http
GET https://customer-api.debitura.com/cases/{caseId}/contract-status
Authorization: Bearer {clientToken}
```

The response includes a `needsPoaSigning` field that consolidates both PoA and JPA requirements.

Which field carries the signing URL depends on what is missing:

| Situation | `poa.solutionUrl` | `pricingAppendix` |
| --- | --- | --- |
| PoA missing (no zone) | Set | `null` |
| JPA missing, PoA already signed | `null` | Set with `solutionUrl` |
| Both missing | Set | Set with `solutionUrl` |

Example — JPA missing, PoA already signed:

```json
{
  "sdca": {
    "signed": true,
    "requiresResigning": false
  },
  "poa": {
    "signed": true,
    "requiresResigning": false,
    "solutionUrl": null
  },
  "pricingAppendix": {
    "signed": false,
    "requiresResigning": false,
    "solutionUrl": "https://referral.debitura.com/PowerOfAttorney/Sign/..."
  },
  "collectionPartnerName": "Oriel Collections Limited",
  "needsPoaSigning": true
}
```

`needsPoaSigning` is `true` when:

-   The PoA is missing or stale, **or**
-   A jurisdiction pricing appendix is required for the debtor's country and has not been signed

`needsPoaSigning` is `false` when all required signing is complete.

**Recommended implementation:** When `needsPoaSigning` is `true`, use `poa.solutionUrl` if non-null, otherwise fall back to `pricingAppendix.solutionUrl`. The signing flow is context-aware — it detects whether a JPA is required for the debtor's country and bundles it into the same session. See [White-Label UI](https://docs.debitura.com/referral-partners/concepts/white-label-ui.md) for how to handle the redirect.

<a id="onboarding-vs-post-onboarding"></a>

## Onboarding vs Post-Onboarding

The zone signing experience differs between the initial onboarding flow and case creation.

<a id="during-onboarding"></a>

### During Onboarding

The onboarding `SignAgreements` step can present up to three checkboxes:

-   SDCA
-   SDCA + PoA
-   SDCA + PoA + zone agreement

When a zone applies, the third checkbox is shown with the zone's configured label text (for example, "UK Pricing Appendix"). A single signature covers all checked agreements.

After onboarding, no further zone-specific UI is shown. The referral partner integration does not need to differentiate between PoA and JPA in the post-onboarding flow. See [Client Onboarding](https://docs.debitura.com/referral-partners/integration-guides/client-onboarding.md) for how SDCA and PoA signing are handled during onboarding.

<a id="after-onboarding--first-case-in-a-zone-jurisdiction"></a>

### After Onboarding — First Case in a Zone Jurisdiction

When a creditor submits their first case in the zone jurisdiction (whether they onboarded before or after the zone was configured), the flow is:

1.  **Case submission** — `POST /cases` returns `422 MissingPowerOfAttorney` with a `solutionUrl`
2.  **Present signing URL** — redirect or surface the `solutionUrl` to the creditor
3.  **Creditor signs** — the JPA is presented on the Debitura-hosted signing page
4.  **Redirect back** — creditor is redirected to your `returnUrl` after signing
5.  **Retry submission** — resubmit the same case; it now proceeds without error

This is identical to the missing-PoA flow. No zone-specific handling is required in your integration.

Creditors onboarded before the zone was activated

If a zone is added to your Debitura account **after** creditors are already active, those creditors will receive a `422 MissingPowerOfAttorney` on their next case submission in the zone jurisdiction — even though they have already signed their PoA. This is expected: the JPA is a separate agreement requiring its own signature.

To avoid all existing creditors hitting a hard 422 simultaneously on go-live, consider using `allowPendingContracts: true` during your rollout window. Cases will be created in `PendingContractSigning` state instead of being rejected outright, giving creditors time to sign the JPA before their cases are actioned. Once rollout is complete, you can remove the flag.

<a id="after-onboarding-ongoing"></a>

### After Onboarding (Ongoing)

Once a creditor has signed the JPA, zone requirements are absorbed transparently into the standard PoA flow:

-   The API only returns `MissingPowerOfAttorney` — never `MissingJurisdictionPricingAppendix`
-   The `solutionUrl` always points to the PoA signing page
-   Your integration does not need separate logic for zone jurisdictions

<a id="contract-validation"></a>

## Contract Validation

Customer API calls always use strict contract validation — a `422` is returned when contracts are unsigned. To opt in to permissive mode (case created as `PendingContractSigning` instead of failing), set `allowPendingContracts: true` in the case creation request body.

<a id="integration-checklist"></a>

## Integration Checklist

Before going live with a zone jurisdiction, verify:

-   [ ]  **422 handling is in place** — your integration catches `MissingPowerOfAttorney` and surfaces the `solutionUrl` to the creditor
-   [ ]  **Return URL is configured** — your `returnUrl` in the signing flow brings the creditor back to a sensible location after signing
-   [ ]  **Retry logic is implemented** — after the creditor signs and is redirected back, the case submission is retried
-   [ ]  **Pricing tier behavior verified** — claims below the zone's lowest tier fall through to standard SDCA pricing (the JPA requirement is unaffected by claim amount; an appendix-bearing zone still requires a signed JPA at any amount)
-   [ ]  **Test environment validated** — run the full flow in the test environment: submit a case in the zone jurisdiction → get the 422 → sign the JPA → retry → confirm the case is created
-   [ ]  **Rollout strategy decided** — if existing creditors are already active, decide whether to use `allowPendingContracts: true` during the rollout window to avoid a hard cutover

## Diagrams

```mermaid
flowchart TD
    A[Case submitted] --> B{Active zone\nfor debtor country?}
    B -- No --> C[Standard routing\n+ SDCA pricing]
    B -- Yes --> D[Route to zone partner]
    D --> E{Zone requires\na signed JPA?}
    E -- No --> H[Case proceeds\nPricing set by claim amount]
    E -- Yes --> G{JPA signed?}
    G -- Yes --> H
    G -- No --> I[422 MissingPowerOfAttorney\nPresent solutionUrl]
    I --> J[Client signs JPA] --> H
```