Search Sell-limit recommendation

POST

/v1/object-types/hospitality.sell_limit_recommendation/search

const url = 'https://api.aerandil.com/v1/object-types/hospitality.sell_limit_recommendation/search';
const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: '{"branch":"2489E9AD-2EE2-8E00-8EC9-32D5F69181C0","cursor":"example","filters":[{"property":"id","type":"eq","value":"example"}],"limit":1,"order":"asc","property_id":"2489E9AD-2EE2-8E00-8EC9-32D5F69181C0","scope":{"level":"tenant"},"sort_by":"created_at"}'
};

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

curl --request POST \
  --url https://api.aerandil.com/v1/object-types/hospitality.sell_limit_recommendation/search \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{ "branch": "2489E9AD-2EE2-8E00-8EC9-32D5F69181C0", "cursor": "example", "filters": [ { "property": "id", "type": "eq", "value": "example" } ], "limit": 1, "order": "asc", "property_id": "2489E9AD-2EE2-8E00-8EC9-32D5F69181C0", "scope": { "level": "tenant" }, "sort_by": "created_at" }'

Search for instances. Filters eq, contains, gte and lte AND-compose; or / not are additive follow-ups. Pages with an opaque cursor; the +1 fetch returns has_more without a second round-trip. Ordered by sort_by (default created_at) in order (default ascending), id breaking ties; rows with no value for a property key sort last.

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

Request Body^required

application/json

object

branch

Optional open-branch id. Search composes that branch’s copy-on-first-write overlay instead of main, so a preview reads its own hypothetical writes. Omit to read main.

string format: uuid

cursor

Opaque cursor from a prior response’s next_cursor. Pass back verbatim; do not introspect.

string

filters

Conjunctive list of predicates. Empty or omitted matches every row in scope, capped by limit.

Array

One of:

object

property

required

Allowed value: id

type

required

Allowed value: eq

value

required

string

limit

Page size. Server defaults to 50, silently clamps at 500 (AIP-158 §3).

integer

>= 1 <= 500

order

Direction of sort_by: asc (oldest / smallest first) or desc. A cursor is bound to the sort_by and order it was minted under; another pair is refused (422).

string

default: asc

Allowed values: asc desc

property_id

The house a desk stands in: keeps this property’s rows (property- or venue-scoped there) and every row scoped to no property (tenant, brand, portfolio), and drops a sibling house’s — the meaning property_id has on the event tail.

string format: uuid

scope

One of: discriminator: level

object

level

required

string

Allowed value: tenant

Allowed values: tenant

sort_by

What the page is ordered by: the row’s created_at or updated_at, or a property whose type orders — strings, enums and dates as text, ints, decimals and durations as numbers, datetimes as instants. Rows with no value sort last in either direction. A property the caller is not cleared to read is refused (403).

string

default: created_at

Allowed values: created_at updated_at id start_date end_date oversell_limit rooms_on_books show_rate expected_walks confidence confidence_score rationale_text issued_at expires_at expires_on decision_status decided_at applied_oversell_limit rejection_reason

Responses

200

Search results, ordered by (sort_by, id) in the requested order (ascending by default).

application/json

object

data

required

Array<object>

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

has_more

required

boolean

next_cursor

Cursor for the next page; omitted when the result set is exhausted.

string

Example

{
  "data": [
    {
      "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"
      }
    }
  ]
}

422

Validation error — unknown property or filter type mismatch.

Search Sell-limit recommendation

Authorizations

Request Bodyrequired

Responses

200

Example

422

Request Body^required