Read Sell-limit recommendation

GET

/v1/object-types/hospitality.sell_limit_recommendation/objects/{id}

const url = 'https://api.aerandil.com/v1/object-types/hospitality.sell_limit_recommendation/objects/2489E9AD-2EE2-8E00-8EC9-32D5F69181C0';
const options = {method: 'GET', headers: {Authorization: 'Bearer <token>'}};

try {
  const response = await fetch(url, options);
  const data = await response.json();
  console.log(data);
} catch (error) {
  console.error(error);
}

curl --request GET \
  --url https://api.aerandil.com/v1/object-types/hospitality.sell_limit_recommendation/objects/2489E9AD-2EE2-8E00-8EC9-32D5F69181C0 \
  --header 'Authorization: Bearer <token>'

Read an existing instance.

A typed overbooking recommendation issued by an agent against one room type over a date range: the oversell headroom the type may sell past its sellable rooms on every night of the range (oversell_limit), or the explicit reset to the operator’s declared limit — with the reading behind it frozen at issue: the rooms on the books, the share of them believed to arrive, the walk cost and the marginal rate the limit balances, and the walks expected at it. Applying it moves each ledger row’s oversell_limit through the overlay set_availability writes, bounded by the row’s oversell_ceiling (the declared limit where none is set) and by what is already sold. The decision_* fields mutate exactly once on the transition out of suggested.

Authorizations

aerandil_oauth
objects:read
aerandil_oauth
objects:hospitality.sell_limit_recommendation:read

Parameters

Path Parameters

required

string format: uuid

Object id (UUID v7, server-generated at create time).

Query Parameters

branch

string format: uuid

Read through an open branch’s copy-on-first-write overlay view instead of the canonical (main) plane. Does not compose with as_of (422). The branch must exist under the caller’s tenant.

Responses

200

Object found.

application/json

object

created_at

required

string format: date-time

required

string format: uuid

object_type

required

Allowed value: hospitality.sell_limit_recommendation

properties

required

object

applied_oversell_limit

Applied oversell limit

The oversell headroom the apply wrote on the first night (for a reset, the declared limit it restored there)

integer

confidence

required

Operator-facing confidence ordinal

string

Allowed values: low medium high

confidence_score

Calibrated probability (0..=1) — set when the model emits one

string format: decimal

decided_at

When the recommendation transitioned out of suggested

string format: date-time

decision_status

required

Lifecycle state

string

Allowed values: suggested applied modified_and_applied rejected expired superseded

end_date

required

Last night

Last night the limit would cover (inclusive)

string format: date

expected_walks

Expected walks

Guests the recommender expects to walk on the first night at the recommended limit

string format: decimal

expires_at

required

After this, decision_status moves to expired

string format: date-time

expires_on

The house business day this lapses after. When set, the house's open business date decides expiry (not the wall clock) and expires_at is the nominal end of that day in the house's timezone

string format: date

factors_considered

required

Signals the recommendation conditioned on

Array<string>

Allowed values: pickup_pace booking_curve competitive_set event_calendar historical_pattern segment_mix channel_mix length_of_stay_distribution cancellation_rate no_show_rate package_attachment group_displacement weather other

forecast_snapshot

Sell-limit recommendation forecast snapshot

Forecast snapshot frozen at issue time (per §B.2)

object

ari_score

string format: decimal

as_of

required

string format: date-time

competitive_set_adr

object

amount

required

string format: decimal

currency

required

string format: iso-4217

competitive_set_occupancy_pct

string format: decimal

event_calendar_signal

string

forecast_kind

required

string

Allowed values: internal_pms external_rms external_str_compset hybrid other

mpi_score

string format: decimal

on_books_revenue

object

amount

required

string format: decimal

currency

required

string format: iso-4217

on_books_rooms

integer

pickup_last_24h

integer

pickup_last_7d

integer

rgi_score

string format: decimal

transient_adr_forecast

object

amount

required

string format: decimal

currency

required

string format: iso-4217

transient_rooms_forecast

integer

required

Recommendation id

string

issued_at

required

When the agent emitted the recommendation

string format: date-time

marginal_rate

Sell-limit recommendation marginal rate

The nightly rate one more sale on the first night would earn

object

amount

required

string format: decimal

currency

required

string format: iso-4217

oversell_limit

Oversell limit

Oversell headroom recommended over the sellable rooms on every night of the range (rooms; absent on a reset)

integer

rationale_text

Human-readable explanation surfaced to operators

string

rejection_reason

Free-text reason set on reject

string

reset

Reset

Recommend returning the limit to the operator’s declared one

boolean

rooms_on_books

Rooms on books

Rooms of the type on the books for the first night, at issue time

integer

show_rate

Show rate

Share of the rooms on the books the recommender believes will arrive on the first night (0..=1)

string format: decimal

start_date

required

First night

First night the limit would cover

string format: date

walk_cost

Sell-limit recommendation walk cost

What the recommender believes walking one arriving guest costs the house, past the night’s own revenue

object

amount

required

string format: decimal

currency

required

string format: iso-4217

provenance

Per-property source attribution and pins. An entry under properties means the property’s current value came from that source (on the source’s own clock, source_updated_at); an entry under pins is a human override protecting the property from sourced writes.

object

pins

object

key

additional properties

object

pinned_at

string format: date-time

pinned_by

object

reason

required

string

properties

object

key

additional properties

object

external_id

string

recorded_at

required

string format: date-time

source

required

string

source_updated_at

string format: date-time

stream

string

scope

required

One of: discriminator: level

object

level

required

string

Allowed value: tenant

Allowed values: tenant

tenant_id

required

string format: uuid

updated_at

required

string format: date-time

version

required

integer

>= 1

Example

{
  "object_type": "hospitality.sell_limit_recommendation",
  "properties": {
    "confidence": "low",
    "decision_status": "suggested",
    "factors_considered": [
      "pickup_pace"
    ],
    "forecast_snapshot": {
      "forecast_kind": "internal_pms"
    }
  },
  "scope": {
    "level": "tenant"
  }
}

Headers

ETag

string

/^"\d+"$/

Quoted strong validator (RFC 7232 §2.3) carrying the object’s monotonic version. Informational on the read path — object mutation goes through typed actions on /v1/actions/{action}/apply, not raw CRUD.

404

No object with that id (or soft-deleted).