> ## Documentation Index
> Fetch the complete documentation index at: https://documentation.debbiecollect.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Settlements

> Read a billing back in full: the payments, how they were split, and what the creditor is charged

A settlement — a *billing* — is the periodic account between a creditor and the
collector. It says how the money collected on the creditor's cases was split,
and what the creditor is charged for the work. It ends either in a payout to the
creditor or in an amount the creditor owes.

Posting one correctly means fetching **both** halves. The payments and their
distribution are one endpoint; the fees and disbursements are another. Take only
the first and the account is half posted.

## The flow

<Steps>
  <Step title="billings.create fires">
    The webhook carries a `billingId`, the `creditorId` and the currency.
  </Step>

  <Step title="Fetch the deposit distribution">
    `GET /v1/{tenantId}/billings/{billingId}/deposit-distribution` — every
    payment in the settlement and how it was split.
  </Step>

  <Step title="Fetch the billing vouchers">
    `GET /v1/{tenantId}/billings/{billingId}/billing-vouchers` — the fees
    (honorarer) and disbursements (udlæg).
  </Step>

  <Step title="Post it">
    Revenue, commission, fees, disbursements, overpayments and the net amount.
  </Step>
</Steps>

## 1. The webhook

```json theme={null}
{
  "event": "billings.create",
  "time": "2026-07-01T02:15:03.221Z",
  "data": {
    "billingId": "9c1f2b3a-4d5e-6f70-8192-a3b4c5d6e7f8",
    "id": 40218,
    "date": "2026-06-30T22:00:00.000Z",
    "billingAppendixId": "869cd519-beb7-4c8c-a854-760df763daad",
    "creditorId": "a7fcf07c-74f2-40d9-8ea6-e67b07b14ca4",
    "currency": "DKK"
  }
}
```

Verify the `X-Verification-Token` header, acknowledge with 200, and do the
fetching asynchronously. `billingId` is what both endpoints below take. Key the
handler on it so a redelivery does not post the settlement twice.

`payouts.create` follows when the money actually moves, with `type` telling you
whether it is a `CREDITOR_RECEIVABLES` settlement, an `OVERPAYMENT` refund to
the debtor, or a `COURT_FEE`.

## 2. The deposit distribution

```
GET /v1/{tenantId}/billings/{billingId}/deposit-distribution
```

One entry per payment in the settlement: which case and customer it belongs to,
which case vouchers it was distributed across, how much of it was an
overpayment, and which of the distributed amounts carry collection commission.

```json theme={null}
{
  "meta": { "currentPage": 0, "pageSize": 25 },
  "items": [
    {
      "currency": "DKK",
      "isAdjustment": false,
      "depositCaseVoucher": {
        "caseVoucherId": "1a2b3c4d-5e6f-7a8b-9c0d-1e2f3a4b5c6d",
        "id": 118067630,
        "amount": 250000,
        "source": "COLLECTOR",
        "state": "PARTIAL_PAYMENT",
        "paymentType": "BANK_TRANSFER",
        "transactionAccountId": "6f2a1c8e-9b0d-4e3f-8a71-2c4d5e6f7a8b"
      },
      "customer": { "referenceId": "CUST-40218" },
      "case": {
        "caseId": "3f1c2d4e-5a6b-7c8d-9e0f-1a2b3c4d5e6f",
        "id": 10427,
        "groupId": "0b1a0f3c-6c1d-4b8f-9b6b-6f6a1f2e7a10",
        "groupLabel": "Consumer"
      },
      "caseVouchers": [
        {
          "caseVoucherId": "7a8b9c0d-1e2f-3a4b-5c6d-7e8f9a0b1c2d",
          "referenceId": "D12412347",
          "voucherTypeId": "eb41e58e-fccf-419d-a771-cd5027fe6e87",
          "amount": 200000,
          "source": "CREDITOR",
          "collectionCommission": true
        },
        {
          "caseVoucherId": "2d3e4f50-6a7b-8c9d-0e1f-2a3b4c5d6e7f",
          "referenceId": null,
          "voucherTypeId": "4c3ccbbf-0651-45b2-b37b-4fe736acfd7e",
          "amount": 50000,
          "source": "COLLECTOR",
          "collectionCommission": false
        }
      ],
      "overpayment": 0
    }
  ]
}
```

* **`customer.referenceId` and `caseVouchers[].referenceId`** are the creditor's
  own identifiers — the customer number and the invoice number that were sent
  in. They are what makes the settlement postable in the creditor's system.
* **`depositCaseVoucher.amount` is the payment**; the amounts in `caseVouchers`
  plus `overpayment` add up to it.
* **`overpayment`** is owed back to the debtor, not to the creditor.

### `source` says who imposed what

* **`CREDITOR`** — imposed by the creditor: the invoices, reminder and
  compensation fees sent at handover, and the payments the creditor registered
  itself. These already exist in the creditor's own bookkeeping.
* **`COLLECTOR`** — imposed by the collector during collection: collection fees,
  court fees, interest.

<Warning>
  The two do not line up. A `CREDITOR` entry can be settled by a payment the
  collector received, and a `COLLECTOR` entry by a payment the creditor received
  itself. `depositCaseVoucher.source` says who received the money;
  `caseVouchers[].source` says who imposed what it paid. Read them separately —
  treating one as a proxy for the other is the usual way a settlement fails to
  reconcile.
</Warning>

### Direct payments

Payments registered with `source: "CREDITOR"` are **not** in the distribution by
default, and the commission charged on them is reported as a separate fee among
the billing vouchers instead. Add `?includeDepositsWithSourceCreditor=true` to
have them reported here with their commission as part of the distribution.

<Warning>
  `billing-vouchers` always reports that commission, whatever is passed here. So
  when both halves of the settlement are taken — which is what this guide
  recommends — leave the parameter off. Turning it on and also reading the
  billing vouchers counts the commission on direct payments twice.
</Warning>

<Card horizontal title="API reference: Get deposit distribution">
  See [GET Get deposit distribution](/api-reference/endpoints/billing/get) for
  full details.
</Card>

## 3. The billing vouchers

```
GET /v1/{tenantId}/billings/{billingId}/billing-vouchers
```

The fees and disbursements on the settlement.

Only the ones that stand on their own are returned. A fee charged on a specific
deposit belongs to that deposit's distribution and is reported there as
`collectionCommission`, so booking both endpoints counts nothing twice — and
misses nothing.

```json theme={null}
{
  "meta": { "currentPage": 0, "pageSize": 25 },
  "items": [
    {
      "billingVoucherId": "5e6f7a8b-9c0d-1e2f-3a4b-5c6d7e8f9a0b",
      "id": 8841,
      "billingId": "9c1f2b3a-4d5e-6f70-8192-a3b4c5d6e7f8",
      "label": "Retsafgift",
      "category": "disbursement",
      "voucherTypeId": "6991fa7e-5812-4948-be69-0001d1f7205f",
      "amount": 75000,
      "currency": "DKK",
      "caseId": "3f1c2d4e-5a6b-7c8d-9e0f-1a2b3c4d5e6f",
      "caseSequentialId": 10427,
      "creditorId": "a7fcf07c-74f2-40d9-8ea6-e67b07b14ca4",
      "creditorReferenceId": "CLIENT-4471",
      "creditorName": "Nordisk Byg A/S",
      "referenceId": null,
      "text": null,
      "createdAt": "2026-06-14T09:02:11.000Z",
      "caseVoucher": null,
      "depositCaseVoucher": null
    }
  ]
}
```

* **`category`** is `fee` — the collector's own charge, a honorar — or
  `disbursement`, an outlay paid on the creditor's behalf, an udlæg. They
  usually go to different accounts, and can be fetched separately with
  `?category=["fee"]` or `?category=["disbursement"]` (JSON encoded, as on
  Debbie's other list filters). Both are returned when it is omitted.
* **`amount` excludes VAT**, and `vat` carries the VAT charged on the entry.
* **`caseId` and `caseSequentialId`** tie the charge to a case where there is
  one; a charge that is not case specific has them null.
* **`depositCaseVoucher`** is the payment that triggered the charge, where there
  is one. Commission on a payment made directly to the creditor appears here,
  with `depositCaseVoucher.source` set to `CREDITOR`.

<Note>
  Do not derive the fees from the `case-vouchers.*` webhook stream instead. A
  voucher event carries no billing reference, so nothing in it says which
  settlement a fee ends up on — or whether it has been settled at all — and a
  voucher can still be changed or removed after it was reported.
</Note>

<Card horizontal title="API reference: Get billing vouchers">
  See [GET Get billing
  vouchers](/api-reference/endpoints/billing/get-billing-vouchers) for full
  details.
</Card>

## 4. Posting it

| What                                             | Where it comes from                                                                                        |
| ------------------------------------------------ | ---------------------------------------------------------------------------------------------------------- |
| Payments against the creditor's own receivables  | Distribution entries with `caseVouchers[].source` `CREDITOR`                                               |
| Collection entries settled out of those payments | Distribution entries with `caseVouchers[].source` `COLLECTOR`                                              |
| Commission                                       | `caseVouchers[].collectionCommission` on the distribution, and commission lines among the billing vouchers |
| Fees charged to the creditor                     | Billing vouchers with `category` `fee`                                                                     |
| Disbursements charged to the creditor            | Billing vouchers with `category` `disbursement`                                                            |
| Owed back to the debtor                          | `overpayment` on the distribution                                                                          |

What is left is the net, which `payouts.create` reports when it moves.

<Tip>
  Reconcile the parts against the settlement total before posting. If they do not
  add up, something was missed — most often the billing vouchers, or the direct
  payments landing on whichever side of `includeDepositsWithSourceCreditor` you
  did not expect.
</Tip>

## Paging and scopes

Both endpoints return `items` plus `meta`, 25 per page by default, with no total
count — page with `page` and `pageSize` until a page returns fewer items than
`pageSize`. See [Pagination](/api-reference/pagination).

Both require `read:billings`.