Plan hold top-up

POST

/v1/functions/hospitality.function.plan_hold_top_up/invoke

curl --request POST \
  --url https://api.aerandil.com/v1/functions/hospitality.function.plan_hold_top_up/invoke \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{ "params": { "on_demand": true }, "target": { "id": "2489E9AD-2EE2-8E00-8EC9-32D5F69181C0", "object_type": "hospitality.stay" } }'

• Production API

What an in-house stay’s pending card holds cover against its bill, and what the night audit’s top-up would do about it now: held (the stay’s live holds), posted (the balance of the bills they sit on), incidental (the allowance of the incidental-hold rule the booking matches, for the nights still to come — at least one), and OPERA’s top-up, excess = posted − held + incidental. action is top_up (a second hold of amount, by the house’s set_hold_top_up rule above its threshold, or by set_credit_limit_overage = hold once the bill reached what is held), charge (credit_limit_overage = charge and the bill has reached what is held: capture taken from the holds and amount held afresh), refused (refusal: the house’s max_per_stay reached, or the money in more than one currency) or none; reason is the desk’s sentence. Also the rule (policy_code, match_reason), the house’s settings, the stay’s top-ups so far, its last recorded refusal and any attempt the card rail opened and has not recorded. The card rail acts on this after each night audit and on the desk’s Top up now; nothing is held by reading it. Read-only.

Authorizations

• aerandil_oauth
  functions:invoke
• aerandil_oauth
  functions:hospitality.function.plan_hold_top_up:invoke

Request Body^required

Media typeapplication/json

object

params

required

object

on_demand

The desk's Top up now: any excess is due, whatever the house's rule and threshold (never past its max_per_stay)

boolean

target

required

object

id

required

string format: uuid

object_type

required

Allowed value: hospitality.stay

Responses

200

Function invoked. The body carries the typed return_value shaped by the function’s declared return_type.

Media typeapplication/json

InvokeFunctionResponse

Envelope returned by the Aerandil function engine. correlation_id is the per-invocation id for trace stitching; return_value is the typed value the function computed (shape declared by the function’s return_type).

object

correlation_id

required

Per-invocation correlation id; appears on log/trace records this function emitted.

string format: uuid

return_value

required

object

action

required

string

Allowed values: none top_up charge refused

amount

object

amount

required

string format: decimal

currency

required

string format: iso-4217

capture

object

amount

required

string format: decimal

currency

required

string format: iso-4217

credit_limit_overage

required

string

Allowed values: off hold charge

excess

object

amount

required

string format: decimal

currency

required

string format: iso-4217

folio_id

string format: uuid

held

object

amount

required

string format: decimal

currency

required

string format: iso-4217

hold_payment_id

string format: uuid

holds

Array<string>

incidental

object

amount

required

string format: decimal

currency

required

string format: iso-4217

last_refusal

string

Allowed values: card_declined insufficient_funds authentication_required no_consent no_card max_reached other_currency processor_refused attempt_abandoned

last_refusal_detail

string

last_refused_at

string format: date-time

match_reason

string

max_per_stay

required

integer

nights_left

integer

open_attempt

string

policy_code

string

posted

object

amount

required

string format: decimal

currency

required

string format: iso-4217

reason

required

string

refusal

string

Allowed values: card_declined insufficient_funds authentication_required no_consent no_card max_reached other_currency processor_refused attempt_abandoned

threshold

object

amount

required

string format: decimal

currency

required

string format: iso-4217

top_up_on

required

boolean

top_ups

required

integer

Example

{
  "return_value": {
    "action": "none",
    "credit_limit_overage": "off",
    "last_refusal": "card_declined",
    "refusal": "card_declined"
  }
}

Headers

Cache-Control

string

Always no-store — function results are time-sensitive and never cacheable.

404

Function or target object not found.

422

Parameter validation or domain-rule violation.