# Currencies, occupancy & allocations `POST /search` is the canonical availability endpoint. It takes one or more properties, a stay window, and a per-room occupancy composition, and returns ranked **allocations** — bundles of priced room **slots** that together house the requested party. This page explains the three request inputs that shape that response: `currency`, `occupancy[]`, and the allocation controls. ## Currency Set `currency` to the ISO 4217 three-letter code you want every monetary field in the response rendered in (for example `TRY`, `EUR`, `USD`). * When `currency` matches the property's stored currency, amounts are returned as-is. * When `currency` differs, the service converts each priced amount to your requested currency before ranking. The currency actually applied is echoed on `response.currency_code` and on each `allocations[].currency`; it is identical for every property in a single request. * If a property cannot be converted to the requested currency, that property's result carries `error_code: "UNSUPPORTED_FX_PAIR"` and an empty `allocations` array — other properties in the same request still succeed. If **every** property fails this way, the whole call returns `422`. `currency` is optional. Omit it to receive amounts in each property's stored currency. All monetary fields (`grand_total`, `stay_total`, `per_night_avg`) are returned as **decimal strings**, not numbers, to preserve scale. ## Occupancy `occupancy[]` describes the party, one entry per room you want priced together. Each entry is an `OccupancySpec`: | Field | Type | Notes | | ------------ | -------------------------- | --------------------------------------------------------------- | | `adults` | integer (1..10) | Adult headcount in this room slot. Required. | | `child_ages` | integer\[] (0..17, max 10) | Ages of children sharing this slot. Omit or send `[]` for none. | Rules: * `occupancy[]` length is `1..9`; order is significant — slot 0 is your canonical first room. * **Single-slot input** (one `OccupancySpec`) asks the engine to house the whole party in one room, then — under `allocation_strategy: auto` — to fall back to splitting the party across multiple rooms if no single room fits. * **Multi-slot input** (two or more `OccupancySpec` entries) is matched strictly: the engine prices each slot's occupancy against eligible rooms and bundles them. * Child pricing is driven by `child_ages`, not by a child count — always send the real ages. ## Allocations An **allocation** is one complete way to house the requested party. Each allocation bundles one or more **slots**; a slot is a single priced room for the stay window. | Allocation field | Meaning | | ------------------------------ | ---------------------------------------------------------------------------------------------------------------- | | `allocation_id` | Deterministic, stable id (`alc_` + 32 hex). Pass it to `/prebook` to reconstruct the exact slot set server-side. | | `strategy` | `single-room` (one room covers the whole party) or `multi-room-split` (2..9 rooms combined). | | `rooms` | Number of slots in the allocation (1..9). | | `slots[]` | The priced rooms in the bundle (`rate_key`, `room_public_id`, `rate_plan_public_id`, `stay_total`, `status`, …). | | `grand_total` | Sum of `slots[].stay_total` in the response currency. The ranking key. | | `grand_total_before_promotion` | Pre-promotion total, for display of savings. | Each slot carries a `status`. On the partner-facing surface every returned slot is `AVAILABLE`, and `total_blocked` is always `0`. `total_available` counts the allocations whose every slot is `AVAILABLE`. ### Allocation controls | Request field | Default | Effect | | -------------------------- | ------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `allocation_strategy` | `auto` | `auto` matches `occupancy[]` strictly first, then falls back to multi-room-split discovery when no single-room option is available. `strict` disables the fallback. | | `max_rooms_per_allocation` | `9` | Upper cap on rooms bundled in the auto-fallback path. | | `include_alternatives` | `false` | `false` (BAR-only) returns one allocation per strategy (≤2 total). `true` returns the top ranked allocations. | | `max_alternatives` | `50` | Caps the allocation count when `include_alternatives: true` (1..50). | Allocations arrive ranked by `grand_total` ascending — the cheapest valid way to house the party is first. For a single best price per strategy, leave `include_alternatives: false`. To present a choice of room/rate combinations, set `include_alternatives: true` and read up to `max_alternatives` allocations. ## Example — multi-room search A request for two properties, a 3-night stay, two rooms (2 adults + a 6-year-old; 2 adults), priced in `TRY`: ```bash curl -sS -X POST https://ari.console.adrasis.com/api/v1/search \ -H "Authorization: Bearer $ACCESS_TOKEN" \ -H "Content-Type: application/json" \ -d '{ "property_ids": ["7gQ2kPa9", "9hT4mRb2"], "checkin": "2026-06-10", "checkout": "2026-06-13", "occupancy": [ { "adults": 2, "child_ages": [6] }, { "adults": 2 } ], "allocation_strategy": "auto", "include_alternatives": false, "currency": "TRY", "country_code": "TR", "language": "en-US" }' ``` Response (abridged): ```json { "currency_code": "TRY", "request_time": "2026-06-02T08:30:00Z", "results": [ { "property_id": "7gQ2kPa9", "total_available": 1, "total_blocked": 0, "allocations": [ { "allocation_id": "alc_3f1a9c4e7b2d8061a5c4e9f0b1d2a3c4", "rooms": 2, "strategy": "multi-room-split", "currency": "TRY", "grand_total": "42600.00", "grand_total_before_promotion": "47200.00", "slots": [ { "rate_key": "rpStd01:r3Tz9Lm0:multi", "room_public_id": "r3Tz9Lm0", "room_name": "Deluxe King Room", "rate_plan_public_id": "rpStd01", "rate_plan_name": "Best Available Rate", "stay_total": "23400.00", "per_night_avg": "7800.00", "status": "AVAILABLE" }, { "rate_key": "rpStd01:r8Yk2Qn5:multi", "room_public_id": "r8Yk2Qn5", "room_name": "Superior Twin Room", "rate_plan_public_id": "rpStd01", "rate_plan_name": "Best Available Rate", "stay_total": "19200.00", "per_night_avg": "6400.00", "status": "AVAILABLE" } ] } ] }, { "property_id": "9hT4mRb2", "error_code": "UNSUPPORTED_FX_PAIR", "total_available": 0, "total_blocked": 0, "allocations": [] } ] } ``` The first property returns a `multi-room-split` allocation bundling two `AVAILABLE` slots whose combined occupancy houses the party; `grand_total` is the sum of both slots in `TRY`. The second property could not be converted to the requested currency and surfaces the failure inline without failing the request. Pass the chosen `allocation_id` to `/prebook` to lock its price and policy — see [The booking flow](/developer/booking-flow.md). For metering and rate-limit behavior, see [Rate limits & usage](/developer/rate-limits-and-usage.md). For the full schema, see the [API reference](/developer/api-reference.md). --- # Agent Instructions: Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter: ``` GET https://adrasis.gitbook.io/developer/currencies-occupancy-allocations.md?ask= ``` The question should be specific, self-contained, and written in natural language. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.