Finance

Three read-only ledgers behind one scope, read:finance: the invoices the agency issued to guests, the payments it recorded against bookings, and the security deposits it holds, returned or kept. Enough for bookkeeping exports and reconciliation; issuing, voiding and e-invoicing stay in the console.

The buyer on an invoice is a guest and therefore personal data: the billing block appears only when the key also holds read:guests.

`GET /partner/v1/invoices`

Query parameter	Required	Meaning
`from` / `to`	no	Issued on or after / on or before
`status`	no	`issued` or `void`
`bookingId`	no	Invoices of one booking
`unit`	no	Unit slug
`page` / `pageSize`	no	1-based page, 1–200 rows (default 100); newest first

{
  "invoices": [
    {
      "id": "0192e…",
      "number": "INV-2026-000412",
      "kind": "tax_invoice",
      "status": "issued",
      "typeCode": "380",
      "issuedOn": "2026-09-02",
      "supplyFrom": "2026-09-10",
      "supplyTo": "2026-09-14",
      "dueOn": "2026-09-09",
      "currency": "AED",
      "subtotal": 205000,
      "vatAmount": 10250,
      "feeAmount": 8000,
      "total": 223250,
      "bookingId": "0191a…",
      "unitSlug": "marina-loft-2br",
      "unitName": "Marina Loft · 2BR",
      "createdAt": "2026-09-02T10:01:55.000Z",
      "billing": { "name": "Nadia Rahman", "address": "…", "trn": null, "email": "nadia@example.com" }
    }
  ],
  "page": 1, "pageSize": 100, "totalItems": 412, "pageCount": 5
}

Field	Notes
`kind`	`tax_invoice` or `simplified`
`typeCode`	UNCL1001: `380` tax invoice, `381` credit note
`subtotal` / `vatAmount` / `feeAmount` / `total`	Net base, VAT, fees outside VAT (Tourism Dirham), grand total — minor units
`billing`	Only with `read:guests`

`GET /partner/v1/invoices/:id`

The same record plus its lines — exactly what the printed sheet carries — and the internal notes:

{
  "invoice": {
    "number": "INV-2026-000412",
    "…": "…",
    "lines": [
      { "label": "4 nights", "qty": 4, "unitAmount": 45000, "vatPct": 5, "net": 180000, "vat": 9000, "gross": 189000 },
      { "label": "Cleaning fee", "qty": 1, "unitAmount": 25000, "vatPct": 5, "net": 25000, "vat": 1250, "gross": 26250 },
      { "label": "Tourism Dirham", "qty": 1, "unitAmount": 8000, "vatPct": 0, "net": 8000, "vat": 0, "gross": 8000, "feeOutsideVat": true }
    ],
    "notes": null
  }
}

`GET /partner/v1/payments`

Recorded guest payments by the day the money arrived.

Query parameter	Meaning
`from` / `to`	Received on or after / on or before
`bookingId`	Payments of one booking
`kind`	`deposit`, `balance`, `security_deposit`, `refund`
`page` / `pageSize`	As everywhere

{
  "payments": [
    { "id": "0192f…", "bookingId": "0191a…", "kind": "deposit", "method": "bank_transfer", "amount": 111625, "currency": "AED", "receivedOn": "2026-09-03", "reference": "TRF 88213", "createdAt": "2026-09-03T11:20:00.000Z" }
  ],
  "page": 1, "pageSize": 100, "totalItems": 980, "pageCount": 10
}

Refunds are stored as positive amounts with kind: "refund" — subtract them when you compute what a booking has paid.

`GET /partner/v1/deposits`

The security-deposit ledger: one row per booking that carries a deposit.

Query parameter	Meaning
`status`	One or a comma-separated list of `pending`, `received`, `refunded`, `partially_withheld`, `withheld`, `waived`
`bookingId`	One booking
`page` / `pageSize`	As everywhere

{
  "deposits": [
    {
      "id": "01930…",
      "bookingId": "0191a…",
      "unitSlug": "marina-loft-2br",
      "arrival": "2026-09-10",
      "departure": "2026-09-14",
      "amount": 150000,
      "currency": "AED",
      "status": "partially_withheld",
      "method": "bank_transfer",
      "receivedAt": "2026-09-09T13:00:00.000Z",
      "refundedAt": "2026-09-20T09:30:00.000Z",
      "refundedAmount": 120000,
      "withheldAmount": 30000,
      "withholdCategory": "extra_cleaning",
      "refundDue": "2026-09-28",
      "updatedAt": "2026-09-20T09:30:00.000Z"
    }
  ],
  "page": 1, "pageSize": 100, "totalItems": 64, "pageCount": 1
}

refundDue is the date by which the agency intends to return the deposit (departure plus its refund window). withholdCategory is one of damage, smoke_odour, extra_cleaning, missing_items, late_checkout, other; the free-text note behind it stays internal.