---
title: "Raise a charge against a tenancy"
method: POST
path: "/api/v1/invoices"
tags: ["Money"]
---

# Raise a charge against a tenancy

`POST /api/v1/invoices`

## Request

- Base URL: `http://localhost:5180`
- URL: `http://localhost:5180/api/v1/invoices`
- Auth: API key in cookie `better-auth.session_token`

Files one notice on the signed-in owner’s account. The number is assigned here, off the numbers already filed, and the row id carries it, so two sessions raising a charge in the same moment cannot mint the same number: the second is refused by storage and retried on the next one. VAT is read from the jurisdiction pack the building stands under, and a charge whose treatment nobody has confirmed is refused rather than written at zero, because a notice that should have carried VAT leaves the owner owing the tax out of what the tenant paid. `vatRate` is how the owner states it themselves. Every amount is integer cents.

## Request body

- object
  - `leaseId` string, required: The tenancy the notice is raised against.
  - `kind` 'rent' | 'charges' | 'charges_settlement' | 'utilities' | 'recharge' | 'late_fee' | 'indemnity' | 'other', required: What the money is for. A credit note is a reduction, not a charge.
  - `amount` integer, required: The net, in integer cents. Any VAT is worked out on top of it.
  - `dueDate` string, required: When it falls due. A date already past is raised overdue.
  - `description` string, required: What it is, in the owner’s words. The tenant reads this.
  - `periodStart` string: A calendar date, `YYYY-MM-DD`.
  - `periodEnd` string: A calendar date, `YYYY-MM-DD`.
  - `note` string: Why it was raised. Kept on the record, never shown to the tenant.
  - `vatRate` number: The rate the owner states, as a decimal. Required where the pack cannot settle the treatment, and the only way to raise a charge outside letting a home.

## Response `200`

The notice, as filed.

- object
  - `ok` unknown, required
  - `data` object, required
    - `invoice` object, required: The notice as it was filed, carrying the number the account assigned it.
      - `id` string, required: Stable record id, e.g. `lse_012`.
      - `number` string, required
      - `leaseId` string: Stable record id, e.g. `lse_012`.
      - `contactId` string, required: Stable record id, e.g. `lse_012`.
      - `teamId` string, required: Stable record id, e.g. `lse_012`.
      - `kind` string, required
      - `status` string, required
      - `issueDate` string, required: A calendar date, `YYYY-MM-DD`.
      - `dueDate` string, required: A calendar date, `YYYY-MM-DD`.
      - `subtotal` integer, required: Money, always in integer cents. €1,250.00 is 125000.
      - `vatTotal` integer, required: Money, always in integer cents. €1,250.00 is 125000.
      - `total` integer, required: Money, always in integer cents. €1,250.00 is 125000.
      - `paidAmount` integer, required: Money, always in integer cents. €1,250.00 is 125000.
      - `structuredRef` string: Belgian-style structured reference, the key to automatic reconciliation.
      - `currency` string, required
  - `meta` object, required
    - `requestId` string, required: Echoed in the x-request-id header. Quote it in a bug report.

## Other responses

- `400`: A malformed body, or a kind that is not a charge.
- `404`: No tenancy on this account has that id.
- `409`: The number series moved under this request more times than it was retried. Nothing was written; send it again.
- `422`: Nothing confirms what VAT this charge carries, so it was not raised. The message says why, and `details.reason` is `vat_unsettled`. Send `vatRate` to state it.
- `429`: Writing faster than the limit allows.

---

[API](https://skmtc.dev/dardaris/apis/dardaris-api.md) · [All operations](https://skmtc.dev/dardaris/apis/dardaris-api/llms.txt) · [OpenAPI document](https://skmtc.dev/dardaris/apis/dardaris-api/revisions/4aff33835c73?raw)