Cancelling a placement

Placements fall through. The household’s home is repaired sooner than expected, the claim is settled, the family moves in with relatives. Cancelling is a first-class call, not a support ticket.

POST /claims/{reference}/cancel-booking

{
  "property_id": "0ba283af-…",
  "reason": "Repairs finished early — the household is going home"
}

reason is optional but it is what the landlord and the household read, so send one.

What cancelling does

It is not a delete. In order:

1. The booking is cancelled.
2. The calendar is freed — every hold and block this placement put on the home is removed, so it can be offered again the same day.
3. The contract is withdrawn — signature links stop working, and any signatures already collected are cleared. A signed lease for a stay that is not happening is worse than none.
4. The home goes back on the market and off this request.
5. The landlord, the household and the assigned adjuster are all notified.

{
  "data": {
    "request_id": "8e1c…",
    "property_id": "0ba283af-…",
    "cancelled": true,
    "property": "Culver City — 2 bed",
    "was_paid": false
  }
}

The request itself stays open. Cancelling one home does not close the housing request — match again and place somewhere else.

If money has already moved

A placement that has been paid for is refused:

{
  "error": {
    "code": "already_paid",
    "message": "This placement has been paid for. Request a refund first…",
    "payment": { "id": "…", "amount_total_cents": 412000, "currency": "usd" }
  }
}

This is deliberate. Havnly never holds the money — rent and deposits are charged directly on the landlord’s own Stripe account — so cancelling here cannot move a cent back. Request the refund first, or, if you are settling with the landlord outside the platform, send "force": true to cancel anyway.

Asking for a refund

POST /claims/{reference}/refund-request

{
  "property_id": "0ba283af-…",
  "reason": "Placement cancelled before move-in"
}

{
  "data": {
    "refund_request_id": "b21f…",
    "amount_cents": 412000,
    "currency": "usd",
    "status": "pending_owner_approval"
  }
}

202, not 200: the request has been put to the landlord, who approves or declines it from their dashboard. You will hear the outcome on payment.refunded. Only the most recent settled payment on that home is refundable, and only one request can be open at a time.

Errors

Ending a stay that has already started

Cancelling is for a placement that has not begun. Once the household has moved in, the stay ends by its move-out date, and shortening it is a date change — POST /claims/{reference}/dates — so the final month is billed for what was actually used. See Move-in dates.