Money & ALEHow the money works

Money and ALE

What a placement costs, what has been paid, and how much of the additional living expenses allowance is left.

The ALE position

GET /claims/{reference}/expenses
{
  "data": {
    "reference": "REQ-6FED6B",
    "ale_limit": 20000,
    "approved_total": 6420.50,
    "pending_total": 310,
    "remaining": 13579.50,
    "percent_used": 32.1,
    "monthly_burn_rate": 2140.17,
    "projected_depletion_date": "2027-03-14",
    "by_category": { "lodging": 5800, "food": 420.5, "transportation": 200 },
    "pending_review": 2,
    "expenses": [ … ]
  }
}

monthly_burn_rate is measured over the days the request has actually been open, so a four-day-old placement does not report an alarming monthly figure. projected_depletion_date is null when nothing has been spent, or when there is no limit to run out of.

Raise the limit with PATCH /claims/{reference}:

{ "ale_limit": 25000 }

Reviewing an expense

POST /claims/{reference}/expenses/{expense_id}/review
{ "decision": "approved", "notes": "Within policy" }

decision is approved or rejected. Approved expenses count against the limit; pending ones are reported separately so you can see what is coming.

What has been paid on a placement

GET /claims/{reference}/placement carries the detail per home:

{
  "payments": [
    {
      "status": "succeeded",
      "amount": 4900,
      "platform_fee": 408,
      "currency": "usd",
      "charge_type": "initial",
      "paid_at": "2026-10-28T11:22:00Z",
      "covers_rent": true,
      "covers_deposit": true
    }
  ],
  "deposit_refunds": [
    { "amount": 1500, "status": "requested", "reason": "End of stay", "requested_at": "2027-02-02T09:00:00Z" }
  ]
}

Who pays what

Rent and deposit have separate payers, set per request and changeable:

{ "rent_payer": "carrier", "deposit_payer": "housing_recipient" }

Values: carrier, tpa, temporary_housing_company, housing_recipient.

Moving a payer off housing_recipient is the standard rescue when a household never registers — they cannot pay through a platform they never joined.

Getting a deposit back

POST /claims/{reference}/deposit-return
{ "property_id": "0ba283af-…", "note": "Stay ended, no damage" }

This asks the landlord to refund it. They approve and refund from their own account, which is where the deposit has been all along.

Why payment itself is not an API call

Rent is charged directly on the landlord’s Stripe account. Havnly never holds the money — the platform fee is collected on top, and the rest is the landlord’s from the moment it clears.

Taking card details through this API would put your systems inside PCI scope for a payment that is not ours to take. So the paying party completes it in Havnly, and you hear payment.succeeded the moment it clears.

CancellingCharges & invoices