> ## 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. # Register case voucher allocation > Register a payment made directly to the creditor or a credit note against a list of existing case vouchers. Set `voucherTypeId` to deposit or credit note; other types are currently rejected. All created vouchers use source `CREDITOR`. Each item in `matches` supplies a positive `amount` in minor units and exactly one of `caseVoucherId` and `caseVoucherReferenceId`. References must be unambiguous within the supplied `creditorId`. A target may appear only once, including when supplied by ID and reference in different items. Each amount must fit within the target's remaining fixed-distribution capacity. All targets must have the same currency. Matches are grouped by case. One allocation voucher is created per case with the sum of that case's match amounts, and one fixed distribution per target on both accounts, using the allocation voucher date. No fixed distribution crosses cases. The response is an array of the created allocation vouchers and their `targetCaseVouchers`, including each `matchedAmount`. **Required scope:** `write:case-vouchers` ## OpenAPI ````yaml POST /v1/{tenantId}/case-vouchers/allocations openapi: 3.1.0 info: title: Debbie API Docs description: > The Debbie API is a RESTful interface, allowing you to programmatically update, add and access your data in the platform. It provides predictable URLs for accessing resources, and uses built-in HTTP features to receive commands and return responses. This makes it easy to communicate with third party systems. ## Idempotency The Debbie API supports idempotency for non-idempotent requests through the optional `Idempotency-Key` header. This ensures that retrying the same request multiple times will produce the same result, preventing duplicate operations. ### Using Idempotency Keys - Include an `Idempotency-Key` header with a unique string (we recommend UUIDs) - Maximum key length is 64 characters - Keys are valid for 48 hours - Responses served from the idempotency cache include an `Idempotency-Cached` header ### Example ```http Idempotency-Key: 123e4567-e89b-12d3-a456-426614174000 ``` ### Error Cases - Invalid key format: 400 Bad Request - Reusing a key for a different request: 400 Bad Request ### Best Practices - Use a new key for each unique business transaction - Use the same key when retrying a failed request - Store keys with request details for debugging contact: email: api-support@debbie.dk version: v0.1.0 servers: - url: https://api.debbiecollect.com security: - bearerAuth: [] tags: - name: Authorization description: Endpoints for interacting with authorization - name: Cases description: Endpoints for interacting with cases - name: Customers description: Endpoints for interacting with customers - name: Creditors description: Endpoints for interacting with creditors - name: Ultimate creditors description: >- Endpoints for interacting with ultimate creditors. An ultimate creditor is the original creditor behind the creditor on a case — for example when a debt collection agency forwards cases on behalf of its own client. On cases with an ultimate creditor, the creditor template mentions (name, address and company identifier) use the details of the ultimate creditor. - name: Updates description: Endpoints for interacting with updates - name: Users description: Endpoints for interacting with updates - name: Files description: Endpoints for interacting with files - name: Case vouchers description: Endpoints for interacting with case vouchers - name: Voucher types description: The voucher types of the tenant, used to categorize case vouchers - name: Interactions description: >- Interactions are messages and notes on a case, for example an incoming message from a debtor. - name: Billing description: Endpoints for interacting with billing - name: Transaction accounts description: >- Endpoints for interacting with transaction accounts — the bank and payment service provider accounts that payments are registered on - name: Links description: Endpoints for generating links - name: Webhooks description: >- Debbie provides a range of webhooks. To try them out please visit Debbie Caseworker and navigate to Settings --> Developers --> Webhooks. - name: End reasons description: Endpoints for interacting with end reasons - name: Case groups description: Endpoints for interacting with case groups - name: Documents description: Endpoints for attaching documentation to a case or to a creditor - name: Case voucher allocations description: Apply creditor payments and credit notes to specific case vouchers. externalDocs: description: Find out more about Debbie here url: https://debbiecollect.com paths: /v1/{tenantId}/case-vouchers/allocations: post: tags: - Case voucher allocations summary: Register case voucher allocation description: >- Register a payment made directly to the creditor or a credit note against a list of existing case vouchers. Set `voucherTypeId` to deposit or credit note; other types are currently rejected. All created vouchers use source `CREDITOR`. Each item in `matches` supplies a positive `amount` in minor units and exactly one of `caseVoucherId` and `caseVoucherReferenceId`. References must be unambiguous within the supplied `creditorId`. A target may appear only once, including when supplied by ID and reference in different items. Each amount must fit within the target's remaining fixed-distribution capacity. All targets must have the same currency. Matches are grouped by case. One allocation voucher is created per case with the sum of that case's match amounts, and one fixed distribution per target on both accounts, using the allocation voucher date. No fixed distribution crosses cases. The response is an array of the created allocation vouchers and their `targetCaseVouchers`, including each `matchedAmount`. **Required scope:** `write:case-vouchers` operationId: create-case-voucher-allocation parameters: - in: path name: tenantId schema: type: string format: uuid required: true description: Id of the tenant - in: query name: creditorId schema: type: string format: uuid required: true description: Id of the creditor the case voucher belongs to requestBody: description: The creditor allocation content: application/json: schema: $ref: '#/components/schemas/NewCaseVoucherAllocation' examples: payment: summary: Payment allocated to three invoices across cases value: voucherTypeId: c51f2f6a-8081-45ef-b52d-5e0569fdf12e date: '2026-06-04' currency: DKK matches: - caseVoucherReferenceId: D12412347 amount: 100000 - caseVoucherReferenceId: D12412348 amount: 20000 - caseVoucherId: d341b682-c7b2-48b4-9152-17c3b4085089 amount: 30000 credit-note: summary: Credit note partially applied to one invoice value: voucherTypeId: ef2cdc50-230f-4046-b1af-0f9c498dddd3 date: '2026-06-04' currency: DKK text: Credit note for returned goods matches: - caseVoucherReferenceId: D12412347 amount: 20000 required: true responses: '201': description: >- All allocations were registered. Returns one allocation voucher per case. content: application/json: schema: type: array items: $ref: '#/components/schemas/CaseVoucherAllocation' example: - caseId: 3f1c2d4e-5a6b-4c8d-9e0f-1a2b3c4d5e6f caseVoucherId: 1a2b3c4d-5e6f-4a8b-9c0d-1e2f3a4b5c6d amount: 120000 currency: DKK date: '2026-06-04T00:00:00.000Z' voucherTypeId: c51f2f6a-8081-45ef-b52d-5e0569fdf12e targetCaseVouchers: - caseVoucherId: 7a8b9c0d-1e2f-4a4b-8c6d-7e8f9a0b1c2d referenceId: D12412347 amount: -120000 matchedAmount: 100000 - caseVoucherId: 426148d2-204a-414b-8c76-cab1261c9b98 referenceId: D12412348 amount: -20000 matchedAmount: 20000 - caseId: 92dd77da-9098-41f0-9568-01e8e5f8b603 caseVoucherId: 0ba4a63e-e4c5-4aae-8ab7-0d3d6e0c89ad amount: 30000 currency: DKK date: '2026-06-04T00:00:00.000Z' voucherTypeId: c51f2f6a-8081-45ef-b52d-5e0569fdf12e targetCaseVouchers: - caseVoucherId: d341b682-c7b2-48b4-9152-17c3b4085089 referenceId: D12412349 amount: -30000 matchedAmount: 30000 '400': description: >- The allocation cannot be placed on the referenced case voucher. `message` says why: - `Reference id … matches more than one case voucher, so the allocation cannot be placed` — send `caseVoucherId` instead. - `Allocation is in … but case voucher … is in …` — the `currency` sent does not match the voucher's. - `Case voucher … is expired and can no longer be settled`. - `Case voucher … is not a debt` — the voucher is a payment or a credit note, not an invoice or a fee. - `Amount … exceeds the … still outstanding on case voucher …` — the amount is more than what is left on the voucher, counting fixed distributions already registered against it. - `Each case voucher may only appear once in matches` — remove duplicate targets, including ID/reference aliases. Currency checks apply across the entire request. Any invalid match rejects the whole request; no vouchers are committed. '401': $ref: '#/components/responses/UnauthorizedError' '404': description: >- No case voucher matched: `No case voucher found with id …` or `No case voucher found with reference id …`. The voucher does not exist within the creditor's creditor, has been deleted, or is not on a case yet. A missing target rejects the whole request. '422': $ref: '#/components/responses/UnprocessableContent' components: schemas: NewCaseVoucherAllocation: type: object properties: date: oneOf: - type: string format: date - type: string format: date-time description: >- Date of the payment or credit note: YYYY-MM-DD or an ISO 8601 timestamp with Z or a timezone offset (for example, 2026-09-21T12:34:56+02:00). Defaults to now. Invalid calendar dates and timestamps without a timezone are rejected. currency: $ref: '#/components/schemas/Currency' description: >- Optional currency assertion. When omitted, the first target determines the currency. All targets must use that currency; mixed-currency requests are rejected. text: type: string description: Free text shown on the created allocation voucher. voucherTypeId: type: string format: uuid enum: - c51f2f6a-8081-45ef-b52d-5e0569fdf12e - ef2cdc50-230f-4046-b1af-0f9c498dddd3 description: >- Type of the new allocation voucher: deposit (c51f2f6a-8081-45ef-b52d-5e0569fdf12e) or credit note (ef2cdc50-230f-4046-b1af-0f9c498dddd3). matches: type: array minItems: 1 items: $ref: '#/components/schemas/CaseVoucherAllocationMatch' description: >- Allocations to existing debt vouchers belonging to the supplied creditor. Targets may belong to different cases, but must use the same currency. Amounts are summed per case to create one allocation voucher per case. required: - voucherTypeId - matches description: >- One payment or credit note allocated across one or more case vouchers. All matches are validated and saved in one transaction. There is no separate total amount: each created voucher is the sum of its case's match amounts. CaseVoucherAllocation: type: object properties: caseId: type: string format: uuid description: Id of the case the allocation was registered on caseVoucherId: type: string format: uuid description: Id of the created payment or credit note voucher amount: type: integer description: Sum of the matchedAmount values on this case, in minor units. currency: $ref: '#/components/schemas/Currency' date: type: string voucherTypeId: type: string format: uuid enum: - c51f2f6a-8081-45ef-b52d-5e0569fdf12e - ef2cdc50-230f-4046-b1af-0f9c498dddd3 description: >- Type of the new allocation voucher: deposit (c51f2f6a-8081-45ef-b52d-5e0569fdf12e) or credit note (ef2cdc50-230f-4046-b1af-0f9c498dddd3). targetCaseVouchers: type: array minItems: 1 items: type: object description: A debt voucher matched by the created allocation voucher. properties: caseVoucherId: type: string format: uuid referenceId: type: - string - 'null' amount: type: integer description: The full amount of the voucher, negative because it is a debt matchedAmount: type: integer minimum: 1 description: >- Amount applied to this target in minor units, as requested in matches. The separate amount field is the full original debt amount. required: - caseVoucherId - referenceId - amount - matchedAmount description: Only targets on this case, with their allocated amounts. description: >- One created allocation voucher on one case. The endpoint returns an array with one item per matched case, ordered by the first occurrence of each case in matches. required: - caseId - caseVoucherId - amount - currency - date - voucherTypeId - targetCaseVouchers Currency: type: string enum: - DKK - SEK - NOK - USD - EUR - GBP - CHF description: Currency CaseVoucherAllocationMatch: type: object properties: caseVoucherId: type: - string - 'null' format: uuid description: >- Debbie's id of the case voucher being settled, as returned when the voucher was created. It must belong to the creditor. Give either this or `caseVoucherReferenceId`, not both. caseVoucherReferenceId: type: - string - 'null' description: >- The creditor's reference for the case voucher being settled — normally the invoice number. It is looked up within the creditor given in `creditorId`, and must match exactly one case voucher. Give either this or `caseVoucherId`, not both. minLength: 1 amount: type: integer description: >- Positive amount in minor units, for either type. 200.00 is sent as 20000. Cannot exceed the target capacity remaining after existing fixed distributions. minimum: 1 required: - amount oneOf: - required: - caseVoucherId properties: caseVoucherReferenceId: type: 'null' caseVoucherId: type: string - required: - caseVoucherReferenceId properties: caseVoucherId: type: 'null' caseVoucherReferenceId: type: string description: >- One target case voucher and the positive amount to apply to it in minor units. Give exactly one of caseVoucherId and caseVoucherReferenceId; the unused identifier may be absent or null. A target may only occur once, including when identified by both its ID and reference in separate matches. responses: UnauthorizedError: description: Access token missing or invalid UnprocessableContent: description: Unable to process the contained instructions. securitySchemes: bearerAuth: type: http scheme: bearer description: >- Authentication can be done by using a bearer token in the Authorization header. This is done using the following format `Authorization: Bearer {token}`. ````