Skip to content
FacilydevelopersDashboard
Build with Facily
DocsREST APIsSettle Move Out
Search the full API reference Esc to close

Settle Move Out

Leases · REST API reference

Get support
POST/v1/leases/{lease_id}/settlement
Settle a completed move-out's balance: refund a credit by card or by check, or keep the balance on the ledger. Card and check need payment.refund at the lease's facility, keep needs lease.terminate. 409 `no_move_out`, `nothing_to_refund`, `no_card_payment`, `no_payment_to_refund`, `pre_cutover_unconfirmed`, `quote_busy`, and `terminal_refund_required` for a card-reader payment whose merchant cannot reverse it through the processor (refund it at the reader, or by check). The same Idempotency-Key returns the first settlement: a card refund already started is finished or returned, one not started runs only up to the credit left; a different method or check number is a 400.

Authentication

Bearer API key or Facily session, subject to permissions and facility scope.

Authentication and scope

Request example

Replace bracketed path values with real IDs from your environment. The body, where shown, is generated from the schema and uses illustrative values.

cURL
curl --request POST \
  --url 'https://api.staging.facily.ai/v1/leases/<LEASE_ID>/settlement' \
  --header "Authorization: Bearer $FACILY_API_KEY" \
  --header 'Idempotency-Key: <IDEMPOTENCY_KEY>' \
  --header 'Content-Type: application/json' \
  --data '{
  "method": "card",
  "check_number": "string",
  "confirm_pre_cutover": false
}'
An example for building your request, not an executed call. Check required fields, allowed values, and environment configuration before sending.

Parameters

lease_idpath · stringrequired

Format: uuid

Idempotency-Keyheader · stringrequired

Min length: 1 · Max length: 60

Request body

application/json · Required

check_numberstring | null

Required for check.

Min length: 1 · Max length: 50

Show check_number schema
string | null

Required for check.

Variant 1: string
string
Variant 2: null
null
confirm_pre_cutoverboolean

Staff checked the credit from before cutover against the previous system's records. A check refund that reaches it needs this (409 pre_cutover_unconfirmed); it never goes to a card.

Default: false

methodstringrequired

card: refund the credit to the newest Facily card payments since go-live; check: refund it by check against the ledger's payments, migrated ones included; keep: leave the balance on the ledger.

Values: "card", "check", "keep"

Responses

Expand a status to inspect its schema. Generated examples show structure and synthetic values.

200Successful Response
JSON · generated example
{
  "data": {
    "amount": "<VALUE_MATCHING_PATTERN>",
    "lease_id": "00000000-0000-4000-8000-000000000001",
    "method": "card",
    "refunds": [
      {
        "amount": "<VALUE_MATCHING_PATTERN>",
        "payment_id": "00000000-0000-4000-8000-000000000001",
        "refund_to": "original_method",
        "status": "string"
      }
    ],
    "remaining_credit": "<VALUE_MATCHING_PATTERN>",
    "replayed": false
  },
  "meta": {
    "request_id": "string"
  }
}

application/json

dataMoveOutSettlementResponserequired
Show data schema
amountstringrequired

keep: the balance left on the ledger; card, check: the total of the refunds listed (on a replay, what was started, and what is still to start up to the credit left).

Pattern: ^(?!^[-+.]*$)[+-]?0*\d*\.?\d*$

lease_idstringrequired

Format: uuid

methodstringrequired

Values: "card", "check", "keep"

refundsMoveOutRefundResponse[]required
Show refunds schema
amountstringrequired

Pattern: ^(?!^[-+.]*$)[+-]?0*\d*\.?\d*$

payment_idstringrequired

Format: uuid

refund_tostringrequired

Values: "original_method", "check"

statusstring | null

completed, pending (the processor has not answered yet) or failed. Null on a replay.

Show status schema
string | null

completed, pending (the processor has not answered yet) or failed. Null on a replay.

Variant 1: string
string
Variant 2: null
null
remaining_creditstringrequired

Credit still on the ledger that this settlement could not refund: credit from before cutover (card), or credit no payment carries. Settle it by check or keep it.

Pattern: ^(?!^[-+.]*$)[+-]?0*\d*\.?\d*$

replayedbooleanrequired
metaMetarequired

Envelope metadata. Every response carries one.

Show meta schema
request_idstringrequired
400Validation error
JSON · generated example
{
  "error": {
    "code": "string",
    "message": "string",
    "details": {}
  },
  "meta": {
    "request_id": "string"
  }
}

application/json

errorErrorBodyrequired

The shape of error.* in an error response.

Show error schema
codestringrequired
detailsobject | null
Show details schema
object | null
Variant 1: object
object
Variant 2: null
null
messagestringrequired
metaMetarequired

Envelope metadata. Every response carries one.

Show meta schema
request_idstringrequired
401Unauthenticated
JSON · generated example
{
  "error": {
    "code": "string",
    "message": "string",
    "details": {}
  },
  "meta": {
    "request_id": "string"
  }
}

application/json

errorErrorBodyrequired

The shape of error.* in an error response.

Show error schema
codestringrequired
detailsobject | null
Show details schema
object | null
Variant 1: object
object
Variant 2: null
null
messagestringrequired
metaMetarequired

Envelope metadata. Every response carries one.

Show meta schema
request_idstringrequired
403Permission denied
JSON · generated example
{
  "error": {
    "code": "string",
    "message": "string",
    "details": {}
  },
  "meta": {
    "request_id": "string"
  }
}

application/json

errorErrorBodyrequired

The shape of error.* in an error response.

Show error schema
codestringrequired
detailsobject | null
Show details schema
object | null
Variant 1: object
object
Variant 2: null
null
messagestringrequired
metaMetarequired

Envelope metadata. Every response carries one.

Show meta schema
request_idstringrequired
404Not found
JSON · generated example
{
  "error": {
    "code": "string",
    "message": "string",
    "details": {}
  },
  "meta": {
    "request_id": "string"
  }
}

application/json

errorErrorBodyrequired

The shape of error.* in an error response.

Show error schema
codestringrequired
detailsobject | null
Show details schema
object | null
Variant 1: object
object
Variant 2: null
null
messagestringrequired
metaMetarequired

Envelope metadata. Every response carries one.

Show meta schema
request_idstringrequired
409Business logic error
JSON · generated example
{
  "error": {
    "code": "string",
    "message": "string",
    "details": {}
  },
  "meta": {
    "request_id": "string"
  }
}

application/json

errorErrorBodyrequired

The shape of error.* in an error response.

Show error schema
codestringrequired
detailsobject | null
Show details schema
object | null
Variant 1: object
object
Variant 2: null
null
messagestringrequired
metaMetarequired

Envelope metadata. Every response carries one.

Show meta schema
request_idstringrequired
503Temporary failure
JSON · generated example
{
  "error": {
    "code": "string",
    "message": "string",
    "details": {}
  },
  "meta": {
    "request_id": "string"
  }
}

application/json

errorErrorBodyrequired

The shape of error.* in an error response.

Show error schema
codestringrequired
detailsobject | null
Show details schema
object | null
Variant 1: object
object
Variant 2: null
null
messagestringrequired
metaMetarequired

Envelope metadata. Every response carries one.

Show meta schema
request_idstringrequired
Continue exploringAll leases operations
Build something that works beautifully.

Facily API · Contract v1.200 · Reviewed October 29, 2026

Settle Move Out | Facily Developers