Running costs

Reading needs landlord:read:costs, writing landlord:write:costs.

`GET /costs`

The cost rows of your apartments, as the portal shows them, with the two monthly totals: what you carry, what the agency carries. Categories the agency keeps internal are not listed — with one exception: a row charged to you always shows, because a deduction from your payout is never hidden.

Query parameter	Meaning
`unit`	Unit slug; default all your current units

{
  "costs": [
    {
      "id": "01931…",
      "unitSlug": "marina-loft-2br",
      "unitName": "Marina Loft · 2BR",
      "categoryId": "0189b…",
      "category": "Electricity",
      "categoryGroup": "utilities",
      "label": "DEWA",
      "amount": 42000,
      "currency": "AED",
      "recurrence": "monthly",
      "monthlyEquivalent": 42000,
      "startDate": "2026-01-01",
      "endDate": null,
      "chargedTo": "owner",
      "source": "owner",
      "notes": null,
      "createdAt": "2026-01-03T09:00:00.000Z"
    }
  ],
  "monthly": { "owner": 61000, "agency": 35000 },
  "currency": "AED"
}

chargedTo: "owner" reduces your payout on the statement; "agency" is the agency’s own money, shown for transparency. source says who recorded the row. monthly counts recurring rows only — one-offs are not a monthly load.

`GET /cost-categories`

The categories you may see, with ownerEditable marking the ones you may book against. The agency’s own lines (management fee, permit renewal) are visible but not yours to book.

{
  "categories": [
    { "id": "0189b…", "key": "electricity", "label": "Electricity", "group": "utilities", "defaultRecurrence": "monthly", "ownerEditable": true, "hint": "DEWA bill" },
    { "id": "0189c…", "key": "management_fee", "label": "Management fee", "group": "fees", "defaultRecurrence": "monthly", "ownerEditable": false, "hint": null }
  ]
}

`POST /costs`

Record a cost on one of your current units — your DEWA bill, your insurance premium. The row is always charged to you and marked as your entry, so the office can tell your input from its own bookkeeping.

curl -X POST https://api.myrentalcalendar.com/partner/v1/landlord/costs \
  -H "Authorization: Bearer $KEY" -H "Content-Type: application/json" \
  -d '{ "unit": "marina-loft-2br", "categoryId": "0189b…", "label": "DEWA September", "amount": 43500, "recurrence": "one_time", "startDate": "2026-09-01" }'

Field	Required	Notes
`unit`	yes	Slug of one of your current units
`categoryId`	yes	A category with `ownerEditable: true`
`label`	yes	2–160 characters
`amount`	yes	Minor units per occurrence, positive
`recurrence`	no	`one_time` (default), `monthly`, `quarterly`, `yearly`
`startDate`	yes	The cost date, or the first occurrence of a recurring row
`endDate`	no	Recurring rows only; `null` = open-ended
`notes`	no	Up to 500 characters

Response 201 with the row in the shape above.

HTTP	`code`	Meaning
400	`VALIDATION`	Malformed body, an end date on a one-off, or an end before the start
403	`FORBIDDEN`	The category is maintained by the agency
404	`NOT_FOUND`	Not one of your current units, or a category you cannot see

`DELETE /costs/:id`

Removes a row you recorded (source: "owner"). The office’s bookkeeping is not yours to delete and answers 404, like a wrong id.