Read provider-neutral property and reservation records through a small, stable contract.
https://supahost.io/api/v1The machine-readable OpenAPI 3.1 schema is available at /api/v1/openapi.json.
Create a test key in Settings to build an integration without touching real data. Test keys start with sh_test_; live keys start with sh_live_.
A test key serves a fixed synthetic dataset: three sandbox properties with room types, rate plans, and calendar days, plus eight sandbox reservations across every status and channel. Filters, cursor pagination, and error responses behave exactly as they do for live keys.
- Sandbox records are clearly fake: names like
Sandbox Seaside Resort,@example.comemails, and555phone numbers. - The dataset is stable, so a cursor chain reads the same records on every run. Unknown IDs return
not_found, the same as live keys. - Test keys share the scopes, rate limit, and request audit of live keys. The audit record marks the key environment.
Writes need a live key. Test keys answer every write endpoint (property, task, message, calendar, rate-plan, and webhook management) with sandbox_read_only.
Property endpoints require the properties:read scope. Required response fields are always present; nullable fields include null in their type.
GET /properties
Return one stable page of properties.
| Field | Type | Required | Description |
|---|---|---|---|
Authorization | string | Required | Send Bearer $SUPAHOST_API_KEY. |
| Field | Type | Required | Description |
|---|---|---|---|
limit | integer | Optional | Records per page, from 1 through 200. The default is 100. |
cursor | string | Optional | Send meta.page.nextCursor without changing any other filter. |
updatedAfter | string (date-time) | Optional | Return records changed after this ISO 8601 date and time. |
updated_after | string (date-time) | Optional | Deprecated: use updatedAfter. |
status | 'active' | 'inactive' | 'all' | Optional | Filter by property status. The default is active, or all when reference is sent. |
reference | string | Optional | Return only the property whose reference is exactly this value. Without status, every status is searched. |
| Field | Type | Required | Description |
|---|---|---|---|
data | Property[] | Required | A stable page of property records. |
meta | object | Required | Response metadata. |
meta.requestId | string | Required | Support identifier for this request. |
meta.page | object | Required | Cursor pagination state. |
meta.page.hasMore | boolean | Required | Whether another page is available. |
meta.page.limit | integer | Required | The page size applied to this response. |
meta.page.nextCursor | string | null | Required | The cursor for the next page, or null when the page is final. |
meta.page.snapshotAt | string (date-time) | Required | The stable read boundary shared by every page in the cursor chain. |
data[].id | string | Required | Stable public property UUID. |
data[].code | string | Required | Property code. |
data[].name | string | Required | Display name. |
data[].timezone | string | Required | IANA time zone. |
data[].lodgingType | string | null | Optional | Accommodation type, or null for an unclassified legacy property. Omitted only in older idempotent replay snapshots. |
data[].status | 'active' | 'inactive' | Required | Property status. |
data[].updatedAt | string (date-time) | Required | Last property change time. |
data[].inventory | object | Required | Property inventory summary. |
data[].inventory.maxGuests | integer | Required | Maximum occupancy across active room types. |
data[].inventory.baseCapacity | integer | Optional | Total base capacity of active inventory pools. Excludes dated entitlement allocations and does not subtract reservations or blocks; use the calendar for date-specific availability. |
data[].inventory.physicalUnits | integer | Required | Number of active physical units. |
data[].inventory.strategies | string[] | Required | Inventory strategies used by active pools. |
data[].channels | string[] | Required | Active channel names. |
data[].startingRate | object | null | Required | Lowest active starting rate, or null when no rate exists. |
data[].startingRate.amount | string | Conditional | Required when startingRate is an object. Amount in the currency unit with two decimals (325.00). |
data[].startingRate.amountMinor | string | Conditional | Required when startingRate is an object. Deprecated: the same amount in hundredths (32500). Read amount. |
data[].startingRate.currency | string | Conditional | Required when startingRate is an object. Three-letter currency code. |
data[].sync | object | Optional | Channel sync state of the property details. It does not change updatedAt. Omitted only in older idempotent replay snapshots. |
data[].sync.state | 'synced' | 'pending' | 'failed' | 'not_applicable' | Required | synced: the channel has the current record. pending: a change is on its way to the channel, or Supahost is retrying it; writes to the record fail with 409 sync_in_progress. failed: the change failed and Supahost will not retry it; a person must resolve it in Supahost, and writes to the record fail with 409 sync_failed. not_applicable: the record is not synced to a channel, for example on a draft property or one without a channel connection. synced and not_applicable mean the record's own sync blocks no write. |
data[].sync.reason | string | null | Required | Why the sync is failing, or null. Current reasons: channel_rejected, channel_unreachable, confirmation_unavailable, connection_problem, setup_incomplete, other. Treat an unknown reason as other. |
data[].sync.failedAt | string (date-time) | null | Required | When the last attempt failed, or null. |
data[].sync.pendingSince | string (date-time) | null | Required | When the pending change was queued, or null when the state is not pending. |
data[].reference | string | null | Optional | Your own identifier for the property, unique within the workspace, or null when none is set. Omitted only in older idempotent replay snapshots. |
GET /properties/{propertyId}
Return one property from the API key workspace.
Property IDs are UUID strings, including property references in reservations, tasks, conversations, channels, calendar and rate-plan write results, and new webhook events. Keep IDs as opaque strings. A property path or filter accepts only the UUID.
Pre-GA identifier transition: refresh your property list and stored references after this release. Start a new property pagination chain; old numeric property cursors return invalid_cursor. Retry writes with the same URL, body and Idempotency-Key to preserve replay behavior. Previously queued webhook events retain their original payload.
The response includes an ETag header that names this version of the property. Send it in If-None-Match to get 304 with no body when the property did not change. The tag names the whole response, so it also changes when a derived value, such as the channel sync state, changes.
| Field | Type | Required | Description |
|---|---|---|---|
Authorization | string | Required | Send Bearer $SUPAHOST_API_KEY. |
If-None-Match | string | Optional | The ETag from your last read. Returns 304 with no body when the property did not change. |
| Field | Type | Required | Description |
|---|---|---|---|
propertyId | string (uuid) | Required | Property UUID. |
| Field | Type | Required | Description |
|---|---|---|---|
data | Property | Required | The requested property. |
meta | object | Required | Response metadata. |
meta.requestId | string | Required | Support identifier for this request. |
data.id | string | Required | Stable public property UUID. |
data.code | string | Required | Property code. |
data.name | string | Required | Display name. |
data.timezone | string | Required | IANA time zone. |
data.lodgingType | string | null | Optional | Accommodation type, or null for an unclassified legacy property. Omitted only in older idempotent replay snapshots. |
data.status | 'active' | 'inactive' | Required | Property status. |
data.updatedAt | string (date-time) | Required | Last property change time. |
data.inventory | object | Required | Property inventory summary. |
data.inventory.maxGuests | integer | Required | Maximum occupancy across active room types. |
data.inventory.baseCapacity | integer | Optional | Total base capacity of active inventory pools. Excludes dated entitlement allocations and does not subtract reservations or blocks; use the calendar for date-specific availability. |
data.inventory.physicalUnits | integer | Required | Number of active physical units. |
data.inventory.strategies | string[] | Required | Inventory strategies used by active pools. |
data.channels | string[] | Required | Active channel names. |
data.startingRate | object | null | Required | Lowest active starting rate, or null when no rate exists. |
data.startingRate.amount | string | Conditional | Required when startingRate is an object. Amount in the currency unit with two decimals (325.00). |
data.startingRate.amountMinor | string | Conditional | Required when startingRate is an object. Deprecated: the same amount in hundredths (32500). Read amount. |
data.startingRate.currency | string | Conditional | Required when startingRate is an object. Three-letter currency code. |
data.sync | object | Optional | Channel sync state of the property details. It does not change updatedAt. Omitted only in older idempotent replay snapshots. |
data.sync.state | 'synced' | 'pending' | 'failed' | 'not_applicable' | Required | synced: the channel has the current record. pending: a change is on its way to the channel, or Supahost is retrying it; writes to the record fail with 409 sync_in_progress. failed: the change failed and Supahost will not retry it; a person must resolve it in Supahost, and writes to the record fail with 409 sync_failed. not_applicable: the record is not synced to a channel, for example on a draft property or one without a channel connection. synced and not_applicable mean the record's own sync blocks no write. |
data.sync.reason | string | null | Required | Why the sync is failing, or null. Current reasons: channel_rejected, channel_unreachable, confirmation_unavailable, connection_problem, setup_incomplete, other. Treat an unknown reason as other. |
data.sync.failedAt | string (date-time) | null | Required | When the last attempt failed, or null. |
data.sync.pendingSince | string (date-time) | null | Required | When the pending change was queued, or null when the state is not pending. |
data.reference | string | null | Optional | Your own identifier for the property, unique within the workspace, or null when none is set. Omitted only in older idempotent replay snapshots. |
POST /properties
Create a draft property with properties:write. Send name, code, the postal address fields (addressLine, city, state, postalCode, countryCode), timezone, lodgingType, strategy, bedrooms, bathrooms, maxGuests, baseCapacity, and baseRate, the default nightly rate: { "amount": "225.50", "currency": "USD" }, the same money object as every other rate. A bare amount in USD such as 225 or "225.50" also works. The OpenAPI request schema lists supported types and limits.
lodgingType describes the accommodation, such as hotel, apart_hotel, apartment, or villa. strategy independently selects pooled, fixed_unit, or entitlement inventory. baseCapacity is the number of sellable units in the first room type: at least 1, or 0 for entitlement inventory whose capacity comes from dated owner-night allocations. Bedrooms, bathrooms, guest capacity and the USD nightly rate apply per unit. baseRateMinor in hundredths still works and will be removed.
Returns 201 with the property, first room type, inventory pool and standard rate plan saved atomically. The property stays inactive until activated in the dashboard. Send Idempotency-Key to retry safely. Test keys cannot create properties. inventory.baseCapacity in read responses is the base unit count, not remaining availability; use the calendar for specific dates.
Send reference, your own identifier for the property, to make the create safe to repeat. It is 1 to 128 characters and unique in the workspace. If a property already has the reference, nothing is created. When every field of the request matches that property as stored, the answer is 200 with that property. Text is compared trimmed, code and countryCode in capitals, and an empty state or postalCode as none. When any field differs, the answer is 409 reference_in_use. Find a property by its reference with GET /properties?reference=. An Idempotency-Key is checked first: its replay returns the stored answer.
PUT /properties/{propertyId}
Replace the writable details of one property. This endpoint requires the properties:write scope. Only name, timezone and reference are writable; the other read fields are ignored when sent back.
The response is the updated property record. On a channel-connected property a change of name or timezone also queues to the channel sync outbox and propagates to connected channels asynchronously. A write that changes only reference, or changes nothing, queues nothing: the reference goes to no channel. An archived property must be restored in the dashboard before editing. One exception: send its stored name and timezone with a new reference, or null, to change only the reference. That change goes to no channel.
A reference that another property holds fails with 409 reference_in_use.
Send an Idempotency-Key header to make retries safe: a repeated PUT with the same key and the same payload returns the original record and applies nothing twice; the same key with a different payload fails with 409 idempotency_key_reused. The replay returns the stored response body unchanged, so its sync shows the state at the time of the original write; read the property to get the current state.
A write that meets a channel sync of the property, or of a record it depends on, fails with 409. sync_in_progress means the sync is pending or being retried: wait for Retry-After, then send the write again. sync_failed means the sync failed and Supahost will not retry it: stop, and ask a person in your workspace to resolve it in Supahost. Both name the blocking record in blockedBy.
To avoid replacing a change that you did not see, send the ETag from your last read in If-Match. If the property changed since, the response is 412 precondition_failed and nothing is written. Read the property again and repeat the change. Without If-Match, the replacement always applies. A 412 can also come from a derived value that moved, such as the channel sync state: read the property again and repeat the change; it is not an error to show.
| Field | Type | Required | Description |
|---|---|---|---|
Authorization | string | Required | Send Bearer $SUPAHOST_API_KEY. |
Idempotency-Key | string | Optional | 1 to 200 characters. Makes retries safe. |
If-Match | string | Optional | The ETag from your last read, quotes included. Returns 412 precondition_failed when the property changed since, and 400 when the value is not a tag. |
| Field | Type | Required | Description |
|---|---|---|---|
propertyId | string (uuid) | Required | Property UUID. |
| Field | Type | Required | Description |
|---|---|---|---|
name | string | Required | Display name, 2 to 100 characters. |
timezone | string | Required | IANA time zone. Other read fields sent back on round-trip are ignored. |
reference | string | null | Optional | Your own identifier for the property, 1 to 128 characters, unique in the workspace. Omit it to keep the stored value. Send null to clear it. |
| Field | Type | Required | Description |
|---|---|---|---|
data | Property | Required | The requested property. |
meta | object | Required | Response metadata. |
meta.requestId | string | Required | Support identifier for this request. |
data.id | string | Required | Stable public property UUID. |
data.code | string | Required | Property code. |
data.name | string | Required | Display name. |
data.timezone | string | Required | IANA time zone. |
data.lodgingType | string | null | Optional | Accommodation type, or null for an unclassified legacy property. Omitted only in older idempotent replay snapshots. |
data.status | 'active' | 'inactive' | Required | Property status. |
data.updatedAt | string (date-time) | Required | Last property change time. |
data.inventory | object | Required | Property inventory summary. |
data.inventory.maxGuests | integer | Required | Maximum occupancy across active room types. |
data.inventory.baseCapacity | integer | Optional | Total base capacity of active inventory pools. Excludes dated entitlement allocations and does not subtract reservations or blocks; use the calendar for date-specific availability. |
data.inventory.physicalUnits | integer | Required | Number of active physical units. |
data.inventory.strategies | string[] | Required | Inventory strategies used by active pools. |
data.channels | string[] | Required | Active channel names. |
data.startingRate | object | null | Required | Lowest active starting rate, or null when no rate exists. |
data.startingRate.amount | string | Conditional | Required when startingRate is an object. Amount in the currency unit with two decimals (325.00). |
data.startingRate.amountMinor | string | Conditional | Required when startingRate is an object. Deprecated: the same amount in hundredths (32500). Read amount. |
data.startingRate.currency | string | Conditional | Required when startingRate is an object. Three-letter currency code. |
data.sync | object | Optional | Channel sync state of the property details. It does not change updatedAt. Omitted only in older idempotent replay snapshots. |
data.sync.state | 'synced' | 'pending' | 'failed' | 'not_applicable' | Required | synced: the channel has the current record. pending: a change is on its way to the channel, or Supahost is retrying it; writes to the record fail with 409 sync_in_progress. failed: the change failed and Supahost will not retry it; a person must resolve it in Supahost, and writes to the record fail with 409 sync_failed. not_applicable: the record is not synced to a channel, for example on a draft property or one without a channel connection. synced and not_applicable mean the record's own sync blocks no write. |
data.sync.reason | string | null | Required | Why the sync is failing, or null. Current reasons: channel_rejected, channel_unreachable, confirmation_unavailable, connection_problem, setup_incomplete, other. Treat an unknown reason as other. |
data.sync.failedAt | string (date-time) | null | Required | When the last attempt failed, or null. |
data.sync.pendingSince | string (date-time) | null | Required | When the pending change was queued, or null when the state is not pending. |
data.reference | string | null | Optional | Your own identifier for the property, unique within the workspace, or null when none is set. Omitted only in older idempotent replay snapshots. |
GET /properties/{propertyId}/rooms
Return one stable page of room types for one property, each with its physical units. Inactive records stay in the response with status inactive. inventoryPool.id is the ID that calendar and rate plan writes name; send ?reference= to find the room type that holds your own reference. sync shows whether the channel has the latest version of each room type; send ?sync=failed to list the ones that need a person.
| Field | Type | Required | Description |
|---|---|---|---|
Authorization | string | Required | Send Bearer $SUPAHOST_API_KEY. |
| Field | Type | Required | Description |
|---|---|---|---|
propertyId | string (uuid) | Required | Property UUID. |
| Field | Type | Required | Description |
|---|---|---|---|
limit | integer | Optional | Records per page, from 1 through 200. The default is 100. |
cursor | string | Optional | Send meta.page.nextCursor without changing any other filter. |
updatedAfter | string (date-time) | Optional | Return records changed after this ISO 8601 date and time. |
updated_after | string (date-time) | Optional | Deprecated: use updatedAfter. |
reference | string | Optional | Return only the room type whose reference is exactly this value, active or inactive. |
sync | string | Optional | Return only the room types whose sync.state is one of these values: pending, failed, or both, separated by commas without spaces. A value may repeat. The filter is part of the cursor, so keep it on every page. |
| Field | Type | Required | Description |
|---|---|---|---|
data | RoomType[] | Required | A stable page of room type records, each with its physical units and inventory pool. |
meta | object | Required | Response metadata. |
meta.requestId | string | Required | Support identifier for this request. |
meta.page | object | Required | Cursor pagination state. |
meta.page.hasMore | boolean | Required | Whether another page is available. |
meta.page.limit | integer | Required | The page size applied to this response. |
meta.page.nextCursor | string | null | Required | The cursor for the next page, or null when the page is final. |
meta.page.snapshotAt | string (date-time) | Required | The stable read boundary shared by every page in the cursor chain. |
data[].id | string | Required | Stable room type ID. |
data[].code | string | Required | Room type code. |
data[].name | string | Required | Room type display name. |
data[].status | 'active' | 'inactive' | Required | Room type status. |
data[].maxOccupancy | integer | Required | Maximum occupancy. |
data[].bedrooms | integer | Required | Bedroom count. |
data[].bathrooms | integer | Required | Bathroom count. |
data[].updatedAt | string (date-time) | Required | Last change time of the room type, its physical units, or its inventory pool. |
data[].units | object[] | Required | Physical units of this room type. |
data[].units[].id | string | Required | Stable physical unit ID. |
data[].units[].code | string | Required | Physical unit code. |
data[].units[].name | string | Required | Physical unit display name. |
data[].units[].floor | string | null | Required | Floor label, or null. |
data[].units[].status | 'active' | 'inactive' | Required | Physical unit status. |
data[].inventoryPool | object | null | Required | The room type’s inventory pool, or null when it has no active pool or more than one. |
data[].inventoryPool.id | string | Conditional | Required when inventoryPool is an object. Inventory pool ID. Calendar and rate plan writes name it as inventoryPool.id. |
data[].inventoryPool.strategy | 'pooled' | 'fixed_unit' | 'entitlement' | Conditional | Required when inventoryPool is an object. Inventory strategy of the pool. |
data[].inventoryPool.capacity | integer | Conditional | Required when inventoryPool is an object. Sellable units before reservations and blocks; 0 for entitlement inventory. |
data[].reference | string | null | Required | Your own identifier for the room type, unique within the property, or null when none is set. |
data[].sync | object | Required | Channel sync state of the record itself. A write can also be refused by the sync of a record it depends on, which blockedBy names. It does not change updatedAt, which tracks the record itself. |
data[].sync.state | 'synced' | 'pending' | 'failed' | 'not_applicable' | Required | synced: the channel has the current record. pending: a change is on its way to the channel, or Supahost is retrying it; writes to the record fail with 409 sync_in_progress. failed: the change failed and Supahost will not retry it; a person must resolve it in Supahost, and writes to the record fail with 409 sync_failed. not_applicable: the record is not synced to a channel, for example on a draft property or one without a channel connection. synced and not_applicable mean the record's own sync blocks no write. |
data[].sync.reason | string | null | Required | Why the sync is failing, or null. Current reasons: channel_rejected, channel_unreachable, confirmation_unavailable, connection_problem, setup_incomplete, other. Treat an unknown reason as other. |
data[].sync.failedAt | string (date-time) | null | Required | When the last attempt failed, or null. |
data[].sync.pendingSince | string (date-time) | null | Required | When the pending change was queued, or null when the state is not pending. |
PUT /properties/{propertyId}/rooms
Create and update room types for one property. This endpoint requires the room-types:write scope. The body is an array of room type entries shaped like the read rows; read-only fields such as units and inventoryPool are ignored when sent back.
Each entry is an upsert keyed by id: an entry with an id replaces that room type’s details, and an entry without an id creates a room type with its own inventory pool. Room types not mentioned stay untouched. Every entry applies, or none does. Changes queue to the channel sync outbox and propagate to connected channels asynchronously, the same as a change made in Supahost.
Set reference to your own identifier for a room type to make creates safe to repeat. An entry without an id whose reference already belongs to an active room type on the property updates that room type instead of creating a second one. A reference held by an inactive room type fails with 409 reference_inactive: to reuse it, send that room type back by its id with status: inactive and reference set to null or another value, or use a different reference. A reference another room type holds, on an entry with an id, fails with 409 reference_in_use, as does the losing request when two creates with one reference run at once.
The response lists the room type each entry wrote in roomTypes, one item per entry in request order, with its id, its reference after the write, and its inventoryPool.id, so a create returns the IDs that the calendar and rate plan writes need. An Idempotency-Key replay returns the same list.
The errors calendar_feed_managed and calendar_move_pending (409) belong to a retired setup. No property returns them.
While Supahost pauses calendar writes to a property, it refuses the same room type changes with 409 calendar_writes_paused. Send them again after the Retry-After seconds.
Every error that names a field names it as roomTypes.N.field, where N is the entry’s position in the body array, starting at 0.
Send an Idempotency-Key header to make retries safe: a repeated PUT with the same key and the same payload returns the original summary and applies nothing twice; the same key with a different payload fails with 409 idempotency_key_reused.
A write that meets a channel sync of the room type, or of a record it depends on, fails with 409. sync_in_progress means the sync is pending or being retried: wait for Retry-After, then send the write again. sync_failed means the sync failed and Supahost will not retry it: stop, and ask a person in your workspace to resolve it in Supahost. Both name the blocking record in blockedBy. A property whose channel setup is not complete also fails a create with sync_failed.
| Field | Type | Required | Description |
|---|---|---|---|
Authorization | string | Required | Send Bearer $SUPAHOST_API_KEY. |
Idempotency-Key | string | Optional | 1 to 200 characters. Makes retries safe. |
| Field | Type | Required | Description |
|---|---|---|---|
propertyId | string (uuid) | Required | Property UUID. |
| Field | Type | Required | Description |
|---|---|---|---|
roomTypes[].id | string | Optional | Room type ID to update. Omit to create a room type. |
roomTypes[].code | string | Required | Room type code, unique within the property across active and inactive room types. 2 to 40 letters, numbers, or hyphens, stored in capitals. |
roomTypes[].name | string | Required | Room type display name, 2 to 100 characters. |
roomTypes[].status | string | Required | Only active is writable. inactive is accepted on room types already inactive, where only a reference change applies; archiving is not supported. |
roomTypes[].maxOccupancy | integer | Required | Maximum guests, 1 to 500. |
roomTypes[].bedrooms | integer | Required | Bedroom count, 0 to 50. |
roomTypes[].bathrooms | integer | Required | Bathroom count, 0 to 50. |
roomTypes[].capacity | integer | Conditional | Sellable units of the room type’s inventory pool, 0 to 10,000, before reservations and blocks. Required when the entry creates a room type, and at least 1 unless the property sells entitlement inventory; a create without it fails with 400 invalid_request on roomTypes.N.capacity. Omit on an update, by id or matched by reference, to leave it unchanged. Ignored for entitlement inventory. |
roomTypes[].reference | string | null | Optional | Your own identifier for the room type, 1 to 128 characters without leading or trailing spaces, unique within the property across active and inactive room types. Omit to leave unchanged; null clears it. Each reference can appear once per request. |
| Field | Type | Required | Description |
|---|---|---|---|
data | RoomTypesWriteResult | Required | The applied rooms write summary. |
meta | object | Required | Response metadata. |
meta.requestId | string | Required | Support identifier for this request. |
data.propertyId | string | Required | Public UUID of the property the rooms write applied to. |
data.roomTypesWritten | integer | Required | Room type entries applied by the write. |
data.roomTypes | object[] | Required | One item per request entry, in entry order: the room type each entry created or updated (an inactive room type sent back unchanged included). |
data.roomTypes[].id | string | Required | Room type ID: the new room type for a create, the room type written for an update. |
data.roomTypes[].reference | string | null | Required | The room type’s reference after the write, or null when it has none. |
data.roomTypes[].inventoryPool | object | null | Required | The room type’s inventory pool, or null when it has no active pool or more than one. |
data.roomTypes[].inventoryPool.id | string | Conditional | Required when inventoryPool is an object. Inventory pool ID, for calendar and rate plan writes. |
GET /properties/{propertyId}/rate-plans
Return one stable page of rate plans for one property. This endpoint requires the rate-plans:read scope. sync shows whether the channel has the latest version of each plan; send ?sync=failed to list the ones that need a person.
calendarRate says whether a calendar write must send the plan a rate on a night with units to sell (night_value_required). On a property whose calendar is supplied by a connected source, an active plan is required when an active listing sells it or when it has a stored rate above 0 on a night from today on. A listing you disconnected does not count, even while its channel connection remains. Past rates and stored rates of 0 (stopped nights) do not count. A request that sends a plan a rate on any night also makes it required on the other nights of that request. A plan the channel derives from another plan is derived, and derivedFrom names the parent. Every other plan is not_required: nothing sells or prices it, it is inactive, or the property’s nights fall back to the plan base rate.
| Field | Type | Required | Description |
|---|---|---|---|
Authorization | string | Required | Send Bearer $SUPAHOST_API_KEY. |
| Field | Type | Required | Description |
|---|---|---|---|
propertyId | string (uuid) | Required | Property UUID. |
| Field | Type | Required | Description |
|---|---|---|---|
limit | integer | Optional | Records per page, from 1 through 200. The default is 100. |
cursor | string | Optional | Send meta.page.nextCursor without changing any other filter. |
updatedAfter | string (date-time) | Optional | Return records changed after this ISO 8601 date and time. |
updated_after | string (date-time) | Optional | Deprecated: use updatedAfter. |
reference | string | Optional | Return only the rate plan whose reference is exactly this value, active or inactive. |
sync | string | Optional | Return only the rate plans whose sync.state is one of these values: pending, failed, or both, separated by commas without spaces. A value may repeat. The filter is part of the cursor, so keep it on every page. |
| Field | Type | Required | Description |
|---|---|---|---|
data | RatePlan[] | Required | A stable page of rate plan records. |
meta | object | Required | Response metadata. |
meta.requestId | string | Required | Support identifier for this request. |
meta.page | object | Required | Cursor pagination state. |
meta.page.hasMore | boolean | Required | Whether another page is available. |
meta.page.limit | integer | Required | The page size applied to this response. |
meta.page.nextCursor | string | null | Required | The cursor for the next page, or null when the page is final. |
meta.page.snapshotAt | string (date-time) | Required | The stable read boundary shared by every page in the cursor chain. |
data[].id | string | Required | Stable rate plan ID. |
data[].code | string | Required | Rate plan code. |
data[].name | string | Required | Rate plan display name. |
data[].status | 'active' | 'inactive' | Required | Rate plan status. |
data[].updatedAt | string (date-time) | Required | Last rate plan or inventory pool change time. |
data[].inventoryPool | object | Required | Inventory pool this rate plan prices. |
data[].inventoryPool.id | string | Required | Stable inventory pool ID. |
data[].inventoryPool.code | string | Required | Inventory pool code. |
data[].inventoryPool.name | string | Required | Inventory pool display name. |
data[].inventoryPool.strategy | 'pooled' | 'fixed_unit' | 'entitlement' | Required | Inventory strategy of the pool. |
data[].inventoryPool.roomTypeId | string | Required | Room type the pool sells. |
data[].baseRate | object | Required | Default nightly rate. |
data[].baseRate.amount | string | Required | Amount in the currency unit with two decimals (325.00). |
data[].baseRate.amountMinor | string | Required | Deprecated: the same amount in hundredths (32500). Read amount. |
data[].baseRate.currency | string | Required | Three-letter currency code. |
data[].includedOccupancy | integer | Required | Guests included in the base rate. |
data[].extraGuestRate | object | Required | Nightly rate for each extra guest. |
data[].extraGuestRate.amount | string | Required | Amount in the currency unit with two decimals (325.00). |
data[].extraGuestRate.amountMinor | string | Required | Deprecated: the same amount in hundredths (32500). Read amount. |
data[].extraGuestRate.currency | string | Required | Three-letter currency code. |
data[].weeklyDiscountPercent | number | null | Required | Percent off the accommodation for direct stays of 7 or more nights, or null for none. |
data[].monthlyDiscountPercent | number | null | Required | Percent off the accommodation for direct stays of 28 or more nights, or null for none. The larger tier applies. |
data[].reference | string | null | Required | Your own identifier for the rate plan, unique within the property, or null when none is set. |
data[].calendarRate | 'required' | 'not_required' | 'derived' | Required | Whether a calendar write must send this rate plan a rate on a night with units to sell. required: the property’s calendar is supplied by a connected source and an active listing sells this active plan, or the calendar prices it (it has a stored rate above 0 on a night from today on). A request that sends the plan a rate on any night also makes it required on the request’s other nights. not_required: nothing sells or prices it, it is inactive, or the property’s nights fall back to the plan base rate. derived: the channel derives the plan from derivedFrom, so it never needs a rate of its own. |
data[].derivedFrom | object | null | Required | The rate plan the channel derives this plan from, or null when Supahost has none on record. |
data[].derivedFrom.id | string | Conditional | Required when derivedFrom is an object. ID of the rate plan this plan is derived from. |
data[].sync | object | Required | Channel sync state of the record itself. A write can also be refused by the sync of a record it depends on, which blockedBy names. It does not change updatedAt, which tracks the record itself. |
data[].sync.state | 'synced' | 'pending' | 'failed' | 'not_applicable' | Required | synced: the channel has the current record. pending: a change is on its way to the channel, or Supahost is retrying it; writes to the record fail with 409 sync_in_progress. failed: the change failed and Supahost will not retry it; a person must resolve it in Supahost, and writes to the record fail with 409 sync_failed. not_applicable: the record is not synced to a channel, for example on a draft property or one without a channel connection. synced and not_applicable mean the record's own sync blocks no write. |
data[].sync.reason | string | null | Required | Why the sync is failing, or null. Current reasons: channel_rejected, channel_unreachable, confirmation_unavailable, connection_problem, setup_incomplete, other. Treat an unknown reason as other. |
data[].sync.failedAt | string (date-time) | null | Required | When the last attempt failed, or null. |
data[].sync.pendingSince | string (date-time) | null | Required | When the pending change was queued, or null when the state is not pending. |
PUT /properties/{propertyId}/rate-plans
Create and update rate plans for one property. This endpoint requires the rate-plans:write scope. The body is an array of rate plan entries shaped like the read rows.
Send each rate as { "amount": "225.00", "currency": "USD" }. amount is a string or a number with at most two decimals. A read row also carries amountMinor, the deprecated amount in hundredths. You can send it back with amount when both name the same amount, and a mismatch returns HTTP 400 on ratePlans.N.baseRate.amount.
Each entry is an upsert keyed by id: an entry with an id replaces that plan’s fields, so nights that inherit the base rate follow the new rate, and an entry without an id creates a plan under inventoryPool.id. Plans not mentioned stay untouched. Changes queue to the channel sync outbox and propagate to connected channels asynchronously. A changed base rate also queues the repriced nights for the channel and sends one calendar.updated webhook with kind rates.
Set reference to your own identifier for a plan to make creates safe to repeat. An entry without an id whose reference already belongs to an active plan on the property updates that plan, under the same rules as an update by id, instead of creating a second one. A reference held by an inactive plan fails with 409 reference_inactive: to reuse it, send that plan back by its id with status: inactive and reference set to null or another value (the one change an inactive plan accepts), or use a different reference; a reference another plan holds, on an entry with an id, fails with 409 reference_in_use, as does the losing request when two creates with one reference run at once.
The response lists the plan each entry wrote in ratePlans, one item per entry in request order, with its id and its reference after the write, so a create returns the new plan’s ID and a repeated create returns the ID of the plan it matched. An Idempotency-Key replay returns the same list. Only a replay of a request first made before ratePlans existed returns the summary without it; read those plans with GET /properties/{propertyId}/rate-plans?reference=….
The errors calendar_feed_managed and calendar_move_pending (409) belong to a retired setup. No property returns them.
While Supahost pauses calendar writes to a property, a create fails with 409 calendar_writes_paused. Updates to existing rate plans still work. Send the create again after the Retry-After seconds.
Send an Idempotency-Key header to make retries safe: a repeated PUT with the same key and the same payload returns the original summary and applies nothing twice; the same key with a different payload fails with 409 idempotency_key_reused.
A write that meets a channel sync of the rate plan, or of a record it depends on, fails with 409. sync_in_progress means the sync is pending or being retried: wait for Retry-After, then send the write again. sync_failed means the sync failed and Supahost will not retry it: stop, and ask a person in your workspace to resolve it in Supahost. Both name the blocking record in blockedBy.
| Field | Type | Required | Description |
|---|---|---|---|
Authorization | string | Required | Send Bearer $SUPAHOST_API_KEY. |
Idempotency-Key | string | Optional | 1 to 200 characters. Makes retries safe. |
| Field | Type | Required | Description |
|---|---|---|---|
propertyId | string (uuid) | Required | Property UUID. |
| Field | Type | Required | Description |
|---|---|---|---|
ratePlans[].id | string | Optional | Rate plan ID to update. Omit to create a rate plan. |
ratePlans[].code | string | Required | Rate plan code, unique within its inventory pool. 2 to 40 letters, numbers, or hyphens. |
ratePlans[].name | string | Required | Rate plan display name, 2 to 100 characters. |
ratePlans[].status | string | Required | Only active is writable. inactive is accepted on plans already inactive, where only a reference change applies; archiving is not supported. |
ratePlans[].inventoryPool.id | string | Conditional | Inventory pool ID the plan prices. Required when creating; on update it must match the plan’s pool. Other read fields on inventoryPool are ignored. |
ratePlans[].baseRate | object | Required | amount/currency pair for the default nightly rate. amount is a currency amount with two decimals, such as 225.00. amountMinor still works and will be removed. All rate plans on one property share one currency. |
ratePlans[].includedOccupancy | integer | Required | Guests included in the base rate, 1 to 500. |
ratePlans[].extraGuestRate | object | null | Required | amount/currency pair for each extra guest, or null for no extra-guest rate. amount is a currency amount with two decimals, such as 25.00. |
ratePlans[].weeklyDiscountPercent | number | null | Optional | Percent off the accommodation for direct stays of 7 or more nights, 0 to 100 with at most two decimals. Omit to leave unchanged; null or 0 clears it. Not sent to channels. |
ratePlans[].monthlyDiscountPercent | number | null | Optional | Percent off the accommodation for direct stays of 28 or more nights. When both tiers qualify the larger one applies. |
ratePlans[].reference | string | null | Optional | Your own identifier for the plan, 1 to 128 characters without leading or trailing spaces, unique within the property across active and inactive plans. Omit to leave unchanged; null clears it. Each reference can appear once per request. |
| Field | Type | Required | Description |
|---|---|---|---|
data | RatePlansWriteResult | Required | The applied rate-plans write summary. |
meta | object | Required | Response metadata. |
meta.requestId | string | Required | Support identifier for this request. |
data.propertyId | string | Required | Public UUID of the property the rate-plans write applied to. |
data.plansWritten | integer | Required | Rate plan entries applied by the write. |
data.ratePlans | object[] | Optional | One item per request entry, in entry order: the plan each entry created or updated (an inactive plan sent back unchanged included). Present on every write. Absent only when an Idempotency-Key replays a request first made before this field existed; read those plans with ?reference= instead. |
data.ratePlans[].id | string | Required | Rate plan ID: the new plan for a create, the plan written for an update. |
data.ratePlans[].reference | string | null | Required | The plan’s reference after the write, or null when it has none. |
Protected closures
A normal closed date or availability block is editable. A protected closure adds a durable guard for one inventory pool and stay date. It closes the pool, sets stop sell on every active rate plan, and prevents ordinary API, import, agent and dashboard calendar edits from reopening it. It also prevents removal of existing closed-to-arrival and closed-to-departure flags. It does not turn those flags on automatically.
Protection preserves bookings, reserved and sellable quantities, prices and other restrictions. Its channel update contains only stop sell and existing true arrival/departure flags. It does not publish prices or stay-length rules, or clear channel flags that are false locally. Derived channel plans keep their inherited prices. Booking modifications and cancellations can still update reserved quantities without reopening the date. This is closure protection, not a price freeze or reservation lock.
Protection is enforced in the database and checked again before queued Supahost channel writes. A stale queued reopening is superseded by current closed state. A provider request already in flight finishes before protection commits; the closure is then queued. HTTP 200 proves the Supahost change committed, not that the connected channel has acknowledged delivery. Verify channel delivery separately.
Protection stays active until explicitly removed; there is no automatic expiry. It cannot control direct edits made in the channel manager or an OTA, another application that bypasses Supahost, or privileged database administration. Keep one authorized channel writer for the protected scope.
Writes require the opt-in calendar-protections:write scope, separately from calendar:write. Existing keys do not gain this scope. The key creator must remain an active workspace member with availability.manage permission, including on idempotent retries. Missing scope or permission returns 403. Test keys cannot write; their GET response is an empty sandbox collection.
GET /properties/{propertyId}/calendar/protections
Requires calendar:read. Supply one inventory pool and an inclusive range of 1 to 366 dates. Returns every active protection in that range, ordered by stay date, with no truncation. An unprotected range returns data: []. Unknown properties or pools return 404.
Send Authorization: Bearer $SUPAHOST_API_KEY. For POST and DELETE, use a unique Idempotency-Key (1 to 200 characters) for each intended operation. A retry with the same key and payload replays its original response without changing current state. Reusing a key with different content returns 409 idempotency_key_reused. After removing and re-creating protection, use a new key.
| Field | Type | Required | Description |
|---|---|---|---|
propertyId | string (uuid) | Required | Property UUID. |
| Field | Type | Required | Description |
|---|---|---|---|
inventoryPoolId | string | Required | One inventory pool on the property. |
startsOn | string (date) | Required | First date, inclusive. Range must span 1 to 366 dates. |
endsOn | string (date) | Required | Last date, inclusive. |
| Field | Type | Required | Description |
|---|---|---|---|
data | CalendarProtection[] | Required | Protection records with id, inventoryPoolId, stayDate, original reason, createdAt and releasedAt. No pagination; at most 366 records. |
meta | object | Required | Response metadata. |
meta.requestId | string | Required | Support identifier for this request. |
data[].id | string | Required | |
data[].inventoryPoolId | string | Required | |
data[].stayDate | string | Required | |
data[].reason | string | Required | |
data[].createdAt | string (date-time) | Required | |
data[].releasedAt | string (date-time) | null | Required |
POST /properties/{propertyId}/calendar/protections
Writes require the opt-in calendar-protections:write scope, separately from calendar:write. Existing keys do not gain this scope. The key creator must remain an active workspace member with availability.manage permission, including on idempotent retries. Missing scope or permission returns 403. Test keys cannot write; their GET response is an empty sandbox collection.
Send Authorization: Bearer $SUPAHOST_API_KEY. For POST and DELETE, use a unique Idempotency-Key (1 to 200 characters) for each intended operation. A retry with the same key and payload replays its original response without changing current state. Reusing a key with different content returns 409 idempotency_key_reused. After removing and re-creating protection, use a new key.
| Field | Type | Required | Description |
|---|---|---|---|
propertyId | string (uuid) | Required | Property UUID. |
The strict JSON body requires inventoryPoolId, startsOn, endsOn and a trimmed reason of 2 to 240 characters. Dates must be today or later in the property time zone, span 1 to 366 dates inclusive, and target an active property and non-entitlement pool. Unknown fields and invalid dates return 400 before any mutation. A date already protected keeps its original ID, reason and creator.
curl -X POST "https://supahost.io/api/v1/properties/$PROPERTY_ID/calendar/protections" \
-H "Authorization: Bearer $SUPAHOST_API_KEY" \
-H "Content-Type: application/json" -H "Idempotency-Key: protect-maintenance-1" \
-d '{"inventoryPoolId":"123","startsOn":"2030-10-10","endsOn":"2030-10-12","reason":"Owner maintenance closure"}'| Field | Type | Required | Description |
|---|---|---|---|
data | CalendarProtection[] | Required | Protection records with id, inventoryPoolId, stayDate, original reason, createdAt and releasedAt. No pagination; at most 366 records. |
meta | object | Required | Response metadata. |
meta.requestId | string | Required | Support identifier for this request. |
data[].id | string | Required | |
data[].inventoryPoolId | string | Required | |
data[].stayDate | string | Required | |
data[].reason | string | Required | |
data[].createdAt | string (date-time) | Required | |
data[].releasedAt | string (date-time) | null | Required |
DELETE /properties/{propertyId}/calendar/protections/{closureId}
Writes require the opt-in calendar-protections:write scope, separately from calendar:write. Existing keys do not gain this scope. The key creator must remain an active workspace member with availability.manage permission, including on idempotent retries. Missing scope or permission returns 403. Test keys cannot write; their GET response is an empty sandbox collection.
Send Authorization: Bearer $SUPAHOST_API_KEY. For POST and DELETE, use a unique Idempotency-Key (1 to 200 characters) for each intended operation. A retry with the same key and payload replays its original response without changing current state. Reusing a key with different content returns 409 idempotency_key_reused. After removing and re-creating protection, use a new key.
Read the current protection, review it, then pass its exact closureId and a strict JSON body containing reason (2 to 240 characters). One call removes one date’s protection. Repeat for each approved date. An already released ID returns 409 closure_changed and cannot remove a replacement protection. An ID outside the property returns 400 invalid_reference.
Removal retains the protection record and its release reason, actor and timestamp for audit. The date remains closed, with stop sell and other restrictions unchanged. To reopen it, make a separate ordinary calendar write after removal. The agent has no unlock tool.
| Field | Type | Required | Description |
|---|---|---|---|
propertyId | string (uuid) | Required | Property UUID. |
closureId | string (uuid) | Required | Exact UUID of the active protection to remove. |
curl -X DELETE "https://supahost.io/api/v1/properties/$PROPERTY_ID/calendar/protections/$CLOSURE_ID" \
-H "Authorization: Bearer $SUPAHOST_API_KEY" \
-H "Content-Type: application/json" -H "Idempotency-Key: release-maintenance-1" \
-d '{"reason":"Owner approved reopening"}'| Field | Type | Required | Description |
|---|---|---|---|
data | CalendarProtection[] | Required | Protection records with id, inventoryPoolId, stayDate, original reason, createdAt and releasedAt. No pagination; at most 366 records. |
meta | object | Required | Response metadata. |
meta.requestId | string | Required | Support identifier for this request. |
data[].id | string | Required | |
data[].inventoryPoolId | string | Required | |
data[].stayDate | string | Required | |
data[].reason | string | Required | |
data[].createdAt | string (date-time) | Required | |
data[].releasedAt | string (date-time) | null | Required |
GET /properties/{propertyId}/calendar
Return per-day availability, lowest rate, and minimum stay for every active inventory pool of one property. This endpoint requires the calendar:read scope. The range spans at most 92 days and defaults to the next 31 days in the property time zone. Dates accept years 1 through 9999. The response is limited to 2000 rows (dates × active pools); larger requests fail with calendar_result_too_large, so narrow the range or pass inventoryPoolId.
availableUnits subtracts reservations and availability blocks from the sellable count and is 0 on closed dates. rate, minStay and minStayThrough come from the lowest-priced sellable rate plan. All three are null when no active plan sells the date, and stopSell is true when every active plan is stop-sold. minStayThrough is also null when that plan’s night follows minStay; it shows a value only when the night has a separate one.
Send include=channel to add a channel object to each row. It says, per night, whether the channel has what Supahost holds for it, and why not. See Channel delivery state below. Without include the response and its cost are unchanged.
Send include=holds to see, for each pool night, what Supahost takes off the count for reservations the count may not include yet, and why. It needs the reservations:read scope as well as calendar:read; a key without one of them gets 403 insufficient_scope, and the detail names the scope it lacks. With holds the response is limited to 500 rows (dates × active pools). Send include=channel,holds for both objects. Every time in holds and meta.asOf is UTC with 6 fractional digits. A test key reads a fixed sample with no reservations, so its holds objects list nothing and take nothing off.
meta.asOf says about when Supahost read the calendar, on its own database clock. A write that committed around that time may or may not be in the read, and the row fields and holds are read one after the other, so do not use meta.asOf to decide whether a write is included.
On a pool whose count a connected source sets, every reservation night the count does not include yet comes off the count before Supahost sends the night to the channel. A reservation night counts as included (reflected: true) only when the connected source confirmed it after the reservation got the night and before the read time behind your count, your observedAt. heldNights lists each reservation on the pool night. subtracted is the sum of units over those not reflected. On any other pool nothing comes off, subtracted is 0 and heldNights is empty. A night that is not reflected has the first reason that applies:
no_observation: no read time stands behind the count: you sentobservedAt: null, or no count with a read time was stored.count_changed_since_observation: the stored count is no longer the count the read time belongs to.several_rooms: the reservation holds more than one room that night, and one confirmation cannot stand for each.no_confirmation: the connected source has not confirmed the reservation for this night.confirmed_before_allocation: a confirmation is from before the reservation got this pool night, so it does not prove this room.confirmed_after_observation: a confirmation is not earlier than the read time, so the read did not see it.
sends is this pool’s part of the availability Supahost computes for the channel for the room type night; the room type gets the sum over its active pools. It is null when the channel receives nothing for this room type night: the night is in the past, the property or its room type is not connected to a channel, or the property’s calendar comes from a connected source and a pool of the room type has no count of its own that night. sends is the value before Supahost holds a property closed on the channel (it then sends 0) and before the channel closes tonight at its own cut-off. Read include=channel for what the channel has.
Supahost stores each observedAt 2 minutes earlier than you send it, to allow for clock differences, and compares confirmations with that stored time: observedAtUsed shows it, and sent.observedAt shows what you sent. reflectedFromObservedAt and reflectableAfter already include those 2 minutes, so compare them with the observedAt you would send. Send the same count again with a newer observedAt only when the new value is later than holds.reflectableAfter. A value equal to it or earlier changes nothing the channel receives, so skip it. When reflectableAfter is null, no later read time takes less off that night.
A later observedAt changes what the channel receives only on a property whose calendar you write through this API; on any other property the write is refused. On a closed night, or a night already at 0 after the held nights that stay off, it changes nothing the channel receives either: Supahost stores the new time and sends nothing.
| Field | Type | Required | Description |
|---|---|---|---|
Authorization | string | Required | Send Bearer $SUPAHOST_API_KEY. |
| Field | Type | Required | Description |
|---|---|---|---|
propertyId | string (uuid) | Required | Property UUID. |
| Field | Type | Required | Description |
|---|---|---|---|
from | string (date) | Optional | First stay date, inclusive. The default is today in the property time zone. |
to | string (date) | Optional | Last stay date, inclusive. The default is 30 days after from; the range can span at most 92 days. |
inventoryPoolId | string | Optional | Return rows for one inventory pool ID. |
pool_id | string | Optional | Deprecated: use inventoryPoolId. |
include | 'channel' | 'holds' | 'channel,holds' | Optional | Send channel to add a channel object to each row: whether the channel has what Supahost holds for that night, and why not. Send holds to add a holds object to each row: what Supahost takes off the pool night’s count for held nights, and why. holds needs the reservations:read scope as well as calendar:read, and limits the response to 500 rows. Send channel,holds for both. Without it the response is unchanged. |
| Field | Type | Required | Description |
|---|---|---|---|
data | CalendarDay[] | Required | One row per active inventory pool per stay date in the range. |
meta | object | Required | Response metadata. |
meta.requestId | string | Required | Support identifier for this request. |
meta.asOf | string (date-time) | Optional | With include=holds: about when Supahost read the calendar, on Supahost’s database clock, UTC with 6 fractional digits. A write that committed around this time may or may not be in the read, so do not use it to decide whether a write is included. |
data[].date | string (date) | Required | Stay date in YYYY-MM-DD format. |
data[].inventoryPool | object | Required | Inventory pool this row describes. |
data[].inventoryPool.id | string | Required | Stable inventory pool ID. |
data[].inventoryPool.code | string | Required | Inventory pool code. |
data[].inventoryPool.name | string | Required | Inventory pool display name. |
data[].inventoryPool.strategy | 'pooled' | 'fixed_unit' | 'entitlement' | Required | Inventory strategy of the pool. |
data[].inventoryPool.roomTypeId | string | Required | Room type the pool sells. |
data[].availableUnits | integer | Required | Units left after reservations and blocks; 0 when the pool is closed. |
data[].closed | boolean | Required | Whether the pool is closed on this date. |
data[].stopSell | boolean | Required | Whether every active rate plan is stop-sold on this date. |
data[].rate | object | null | Required | Lowest nightly rate across sellable active rate plans, or null when none sells. |
data[].rate.amount | string | Conditional | Required when rate is an object. Amount in the currency unit with two decimals (325.00). |
data[].rate.amountMinor | string | Conditional | Required when rate is an object. Deprecated: the same amount in hundredths (32500). Read amount. |
data[].rate.currency | string | Conditional | Required when rate is an object. Three-letter currency code. |
data[].minStay | integer | null | Required | Minimum stay of the lowest sellable rate plan, or null when no rate exists. |
data[].minStayThrough | integer | null | Required | Separate minimum stay through this date of the lowest sellable rate plan. Null means the night follows minStay, or that no rate exists. |
data[].channel | object | Optional | Whether the channel has what Supahost holds for this night. Present only with include=channel. |
data[].channel.availability | object | Required | Channel state of the room type availability on this night. |
data[].channel.availability.state | 'synced' | 'pending' | 'failed' | 'held' | 'closed_by_channel' | 'not_sent' | Required | synced: Nothing is outstanding. The channel confirmed the last change, or no change was needed. Supahost does not read the channel again to report this. pending: A change is on its way to the channel, or Supahost is retrying one. failed: The last change failed and Supahost will not retry it. A person must resolve it in Supahost. held: Supahost holds the night closed on the channel (availability 0) until it can confirm the property calendar there. closed_by_channel: The channel closed tonight at its own same-day cut-off. Supahost expects this and does not send the night again. not_sent: Supahost does not send this night to the channel. reason says why. |
data[].channel.availability.reason | string | null | Required | Why the night is not synced, or null. Current reasons: channel_rejected, channel_mismatch, channel_unreachable, confirmation_unavailable, connection_problem, closed_by_channel_cutoff, activation_unconfirmed, property_inactive, not_connected, derived_rate_plan, no_rate_plan, past_night, awaiting_value, awaiting_feed, other. Treat an unknown reason as other. |
data[].channel.availability.value | integer | null | Required | The availability Supahost holds for the channel on this night: the room type total after holds and the close-out. It can differ from the row's availableUnits, which is one pool. 0 while held. Null when the night is not sent. |
data[].channel.availability.observedValue | integer | Optional | The availability a read of the channel showed when it differed from value. Present only then. |
data[].channel.availability.changedAt | string (date-time) | null | Required | When Supahost last recorded a change to the delivery behind this state: the queued or retried change, the failure, or the closure. For held, when the hold started (the hold.since of GET /properties/{propertyId}/channel-sync). Null for synced and not_sent. |
data[].channel.restrictions | object | Required | Channel state of the rates and stay rules on this night. On the rate plan calendar it is that plan. On the property calendar it sums up the pool's active rate plans: failed when one failed, else pending when one is pending, else synced when one reaches the channel, else not_sent (no_rate_plan when the pool has no active plan). |
data[].channel.restrictions.state | 'synced' | 'pending' | 'failed' | 'held' | 'closed_by_channel' | 'not_sent' | Required | synced: Nothing is outstanding. The channel confirmed the last change, or no change was needed. Supahost does not read the channel again to report this. pending: A change is on its way to the channel, or Supahost is retrying one. failed: The last change failed and Supahost will not retry it. A person must resolve it in Supahost. held: Supahost holds the night closed on the channel (availability 0) until it can confirm the property calendar there. closed_by_channel: The channel closed tonight at its own same-day cut-off. Supahost expects this and does not send the night again. not_sent: Supahost does not send this night to the channel. reason says why. |
data[].channel.restrictions.reason | string | null | Required | Why the night is not synced, or null. Current reasons: channel_rejected, channel_mismatch, channel_unreachable, confirmation_unavailable, connection_problem, closed_by_channel_cutoff, activation_unconfirmed, property_inactive, not_connected, derived_rate_plan, no_rate_plan, past_night, awaiting_value, awaiting_feed, other. Treat an unknown reason as other. |
data[].channel.restrictions.changedAt | string (date-time) | null | Required | When Supahost last recorded a change to the delivery behind this state: the queued or retried change, the failure, or the closure. For held, when the hold started (the hold.since of GET /properties/{propertyId}/channel-sync). Null for synced and not_sent. |
data[].holds | object | Optional | With include=holds: what Supahost takes off this pool night’s count for held nights, and why. |
data[].holds.count | integer | null | Required | The night’s own count before blocks and held nights come off: the stored sellable count less reservations. On a property whose calendar was moved from the retired supplier feed to the API, Supahost stores the availableUnits you write as sent, so count is your number. On every other property it stores your availableUnits plus the units blocks hold at that moment. Either way a block added or removed later changes blocked, not count. Null when the night has no count of its own and follows the pool capacity. |
data[].holds.closed | boolean | Required | Whether the pool is closed on this date. |
data[].holds.sent | object | null | Required | The times of the last count the API wrote for this pool night, or null when the API never wrote one. |
data[].holds.sent.observedAt | string (date-time) | null | Conditional | Required when sent is an object. The observedAt you sent, or null when you sent observedAt: null. |
data[].holds.sent.revisionAt | string (date-time) | Conditional | Required when sent is an object. The newest revisionAt Supahost accepted for this pool night. |
data[].holds.sent.recordedAt | string (date-time) | Conditional | Required when sent is an object. When Supahost stored it. |
data[].holds.observedAtUsed | string (date-time) | null | Required | The read time Supahost compares confirmations with, as stored. When your write stored it, it is 2 minutes before the observedAt you sent; when the retired supplier feed stored it, it is the feed’s own read time. Null when no read time belongs to the stored count. |
data[].holds.blocked | integer | Required | Units availability blocks hold on this date. |
data[].holds.subtracted | integer | Required | Units that come off the count for held nights not yet included in it: the sum of units over heldNights with reflected: false. Always 0 on a pool whose count no connected source sets, and on a night without its own count. |
data[].holds.sends | integer | null | Required | This pool’s part of the availability Supahost computes for the channel for the room type night: 0 when closed, otherwise the count (or the pool capacity less reservations) less blocked and subtracted, never below 0. The room type gets the sum over its active pools. Null when the channel receives nothing for this room type night: the night is in the past, the property or its room type is not connected to a channel, or the property’s calendar comes from a connected source and a pool of the room type has no count of its own that night. It is the value before Supahost holds a property closed on the channel, which sends 0 instead, and before the channel closes tonight at its own cut-off. What the channel has is in include=channel. |
data[].holds.reflectableAfter | string (date-time) | null | Required | The earliest reflectedFromObservedAt among heldNights with reflected: false, or null when no such night has one. Sending the same count again with a later observedAt can change what the channel receives only when that observedAt is later than this, and only on a property whose calendar you write through the API (elsewhere the write is refused). On a closed night, or one already at 0 after the held nights that stay off, it changes nothing the channel receives: Supahost stores the new time and sends nothing. |
data[].holds.heldNights | object[] | Required | Each reservation holding units on this pool night, oldest allocation first. Empty where nothing comes off for held nights: a pool whose count no connected source sets, or a night without its own count. |
data[].holds.heldNights[].reservationId | string | Required | The reservation that holds units on this pool night. |
data[].holds.heldNights[].status | 'tentative' | 'confirmed' | Required | Reservation status. Cancelled reservations hold nothing and are not listed. |
data[].holds.heldNights[].units | integer | Required | Units the reservation holds on this pool night. |
data[].holds.heldNights[].allocatedAt | string (date-time) | Required | When the reservation got this pool night. |
data[].holds.heldNights[].confirmationRecordedAt | string (date-time) | null | Required | When Supahost recorded the newest confirmation from the connected source that covers this night, or null when there is none. |
data[].holds.heldNights[].reflected | boolean | Required | Whether your count already includes this night, so nothing comes off for it. |
data[].holds.heldNights[].reason | 'no_observation' | 'count_changed_since_observation' | 'several_rooms' | 'no_confirmation' | 'confirmed_before_allocation' | 'confirmed_after_observation' | 'null' | Required | Why the night still comes off your count, the first that applies: no_observation (no read time stands behind the count), count_changed_since_observation (the stored count is no longer the count that read time belongs to), several_rooms (the reservation holds more than one room that night), no_confirmation, confirmed_before_allocation (a confirmation is from before the reservation got this pool night), confirmed_after_observation (a confirmation is not earlier than the read time). Null when reflected is true. |
data[].holds.heldNights[].reflectedFromObservedAt | string (date-time) | null | Required | The latest observedAt that still leaves this night off your count: sent with the same count, an observedAt later than this counts the night as included. It is the confirmation time plus the 2 minutes Supahost takes off every observedAt. Null when no read time can include the night: the reservation holds more than one room that night, it has no confirmation, or a confirmation is from before it got this pool night. reason names only the first cause, so this can be null under no_observation or count_changed_since_observation too. |
PUT /properties/{propertyId}/calendar
Bulk-update per-day availability, rates, and restrictions for one property. This endpoint requires the calendar:write scope, or calendar:read to validate a request with validateOnly=true. The body is an array of day entries shaped like the read rows. A property calendar row summarizes the pool’s lowest-priced sellable rate plan, and it shows an inherited rate as a number. An entry without ratePlanId writes every active plan on the pool. So do not send a read row back unchanged for a pool with more than one rate plan. Read the rate plan calendar instead, send entries with ratePlanId, and leave out rate and minStay unless you mean to set them.
The error calendar_feed_managed (409) belongs to a retired setup. No property returns it.
When Supahost pauses calendar writes to a property, the request returns 409 calendar_writes_paused and changes nothing. Read the calendar with GET, and send the write again after the Retry-After seconds.
On a property whose calendar is supplied by a connected source, the channel sells a night only from values written for it: an available count for the pool and a rate on the rate plan. There is no fallback to the pool capacity or the plan base rate. Supahost merges your entries for a pool and date with the values it stores, and refuses the request with 400 night_value_required when the night would miss a value the channel needs to sell it. A night with units to sell (an open night whose sellable count is above 0, counted before reservations and blocks, since a cancelled booking or a removed block frees those units without a calendar write) needs a rate on each rate plan that an active listing sells or that the calendar prices, and a rate on at least one rate plan of its pool. The calendar prices a rate plan that has a stored rate above 0 on a night from today on, or that your request sends a rate on any night. A rate plan with no active listing and no rate is not sold, so it needs none (a listing you disconnected does not count, even while its channel connection remains), and a rate plan the channel derives from another one never does. The rate plans read says which rate plans need one in calendarRate. An entry that sends a rate, or reopens a rate plan with stopSell: false, on a night without an available count needs that count. On a room type with more than one active inventory pool, the channel receives the room type’s availability only when every active pool has an available count, so an entry that gives one pool units to sell while another pool of the room type has no count for that night is refused on days.N.availableUnits, and the message names the other pool: send a count for it in the same request.
A rate plan stopped from selling on a night needs no rate there: send stopSell: true without a rate, and the channel receives the night as stopped, with no rate. One rate plan can sell a night while another is stopped. Supahost keeps such a night without a rate, and the rate plan calendar reads it with rate: null. Sending the same stop again changes nothing. To reopen it, send stopSell: false with a rate: without one the request is refused with night_value_required on days.N.rate, for every rate plan, whether or not it needs a rate to sell. That includes an entry without ratePlanId that sends stopSell: false and reaches such a night: the message names each rate plan it would reopen. A night that keeps its rate when you stop it keeps that rate when you reopen it. A stop that Supahost stores on a night that still follows the plan base rate is not sent to the channel, so it does not count until an entry writes that rate plan night.
A night with no units to sell needs no rate. To close a night, send closed: true or availableUnits: 0. A close or a stop is never refused for a missing value: on a night without an available count the channel never received the night, so closed: true there changes nothing it sells. Send availableUnits: 0 too when you want the channel to receive the night as closed. Each errors item names one missing field (days.N.availableUnits, days.N.rate, or days.N.ratePlanId for a rate plan that no entry in the request writes), and its message names the rate plan and why it needs a rate. Nothing is stored. An entry that changes only the rate or the stay rules of a night that has its values is valid. A night with neither a count nor a rate is valid and is not sold. Minimum and maximum stay, stop sell and the arrival and departure flags are not required: they keep their defaults. On every other property the pool capacity and the plan base rate still apply to a night without its own value.
Protected closures cannot be overridden by this endpoint. Reopening inventory or removing protected restrictions returns 409 protected_calendar_closure and rolls back the entire batch, also with skipLocked=true. The protectedNights member lists each protected night the request would reopen by inventory pool and date, up to 100, and protectedNightCount gives the total. Remove those entries, or explicitly remove protection in the calendar or through the protection API first. Removing protection alone leaves the date closed.
Each entry needs date and inventoryPool. An entry that sends availableUnits or closed also needs revisionAt and observedAt, described below. Every other field is optional. An omitted field keeps the stored value. Days that you do not mention stay as they are. For rate, minStay and minStayThrough, null also keeps the stored value.
Every entry that sends availableUnits or closed carries two times. revisionAt is required and cannot be null: send a time that only goes up for a pool night, such as the start of your sync run. The observedAt key is required too: send a time no later than the supplier read behind the count, or null when no supplier read stands behind it. Both are RFC 3339 date-times with a time-zone offset and at most 6 fractional digits, and neither may be more than 2 minutes after Supahost’s own time for the request. A missing time fails the request with 400 count_time_required, a time in the wrong format with 400 invalid_datetime, and a time too far ahead with 400 count_time_in_future. Each errors item names the field, and the request stores nothing. Entries for the same pool and date that send a count must send the same two times. An entry that sends neither availableUnits nor closed may leave both out; a time it sends is checked for its format only, and it never has to match another entry’s. This applies on every property.
Supahost keeps the newest revisionAt for each pool night. When an entry sends an older revisionAt than the stored one, Supahost refuses that pool night: nothing is stored for it, not its count, its rates or its stay rules, and every entry for the same pool and date is refused with it. A refused night is set aside before the other checks, so it never fails the request, and the other entries are checked without it. The request still answers 200 and applies the other nights. refusedNights lists each refused night with reason: "stale_revision", retry: false, the revisionAt you sent and the later storedRevisionAt, both in UTC with 6 fractional digits, and refusedNightCount gives the total. Drop a refused night: sending it again cannot succeed. An equal revisionAt is accepted, so a retry of the same request changes nothing. A write that changes nothing still keeps your revisionAt, so an older run that arrives later is refused. With skipLocked=true, a locked night is listed only in skippedNights and is never compared. Supahost keeps a record of each refused night.
On a property whose calendar was moved from the retired supplier feed to the API, Supahost stores the availableUnits you send as your count, without adding back the units availability blocks hold. A block a person adds in Supahost comes off your count where Supahost computes the channel value, so the channel receives availableUnits less the blocked units, never below 0. A lower count and a close always apply, also on a blocked night. When a person removes the block, the channel value rises by the blocked units with no write from you. The GET calendar then shows availableUnits less the blocked units, which is what the channel receives: on a blocked night do not write back what you read, or the block comes off twice. Send your own count. On every other property a block is added back to your availableUnits, as described below.
On a pool whose sellable count a connected source sets, observedAt decides which reservations the count already includes. A reservation night counts as included only when the connected source confirmed it after the night was booked and before observedAt. Every other reservation night comes off your count before Supahost sends it to the channel, and with observedAt: null they all do. Supahost treats the read as 2 minutes earlier than sent, to allow for clock differences. When you send the same count with a different observedAt and that changes the availability the channel receives, Supahost sends that night to the channel and counts it in nightsChanged.observations. It sends no calendar.updated webhook for it, because the stored calendar did not change. When it changes nothing the channel receives, nothing is sent and nothing is recorded. countsWithoutObservation counts the pool nights the write applied with observedAt: null.
An entry without availableUnits and closed does not touch pool availability. Use it to change prices or restrictions only. A booking that arrives between your read and your write keeps its units. On a night with no stored value, an omitted field keeps its default: availability follows the pool capacity, the pool stays open, and the flags stay false. This is how the API works today: when an entry creates a rate plan night, the minimum and maximum stay it leaves out store the plan’s current defaults, and a later change to the plan defaults does not move that night (issue #1097). An entry that changes nothing is valid.
minStay is the minimum stay for an arrival on the date. minStayThrough is the minimum stay for any stay that includes the date. A night without its own minStayThrough uses its minStay. When you change minStay and omit minStayThrough, a night that has its own through value keeps it. Send both to change both. null or an omitted minStayThrough keeps the stored value. Sending minStayThrough stores a fixed value for that night. The night then no longer follows minStay, and the API cannot clear the value today (issue #1097). To keep a night following minStay, do not send minStayThrough. A night whose read shows null follows minStay. A property calendar row summarizes the pool’s lowest-priced sellable rate plan, and it shows an inherited rate as a number. An entry without ratePlanId writes every active plan on the pool. So do not send a read row back unchanged for a pool with more than one rate plan. Read the rate plan calendar instead, send entries with ratePlanId, and leave out rate and minStay unless you mean to set them. A maxStay you send must be zero or at least both minimum stays, including a stored through value.
Nights locked in the Supahost calendar cannot be written by this endpoint. By default, a request that includes a locked night returns 409 calendar_night_locked and changes nothing. The lockedNights member lists each locked night by inventory pool and date, with the reason it is locked, up to 100. lockedNightCount gives the total. A lock covers the whole pool on that date. The reason is manual (a person locked it), edit (a person or the Supahost agent changed it on a property whose calendar was moved from the retired supplier feed to the API, or earlier, while the feed wrote it), feed_conflict (a lock the retired feed set when it found the night changed outside the feed; locks of this reason can still be on a property), or carried_over (an earlier lock on the whole day).
Send skipLocked=true to write every other entry in the same transaction. The response lists every locked night in skippedNights, with its reason and no cap, and gives the total in skippedNightCount. daysApplied counts the entries accepted and not skipped, including an entry that changed nothing. A skipped entry is not checked against stored values, so it cannot fail the request. When every entry is locked, nothing changes and the response is still 200. Supahost keeps a record of each skipped night and its reason.
The lock wins over your value. When you close a skipped night, or send fewer availableUnits than the lock keeps, while the night is still for sale, Supahost flags the night to an operator because it can be oversold. The night itself does not change. Send the night again after it is unlocked.
A person can lock a night in the calendar. A night is also locked when a person or the Supahost agent edits it on a property whose calendar was moved from the retired supplier feed to the API. A person can unlock the night in the calendar, and your next write of it applies. Locks from the time the feed wrote the property can still be there, and are unlocked the same way.
Send a rate as { "amount": "325.00", "currency": "USD" }. amount is a string or a number with at most two decimals. A read row also carries amountMinor, the deprecated amount in hundredths. You can send it back with amount when both name the same amount, and a mismatch returns HTTP 400 on days.N.rate.amount.
Unknown fields return HTTP 400 before any change. This also applies inside inventoryPool and rate. Use camelCase names such as maxStay. Null rejects for availableUnits, closed, stopSell, maxStay, closedToArrival and closedToDeparture. Use zero or false to clear them.
Without ratePlanId an entry writes every active rate plan on the pool; with it, only that plan’s nightly state changes. Entries for the same pool and date may target different rate plans, but their pool-level fields (availableUnits, closed) must agree, and a pool-level entry cannot share a date with targeted entries. availableUnits is the target availability, and reservations and blocks are added back when the sellable count is stored (only reservations on a property whose calendar was moved from the retired supplier feed to the API, where a block comes off at the channel). That count must fit the pool capacity, or the write fails with 400 invalid_request. A pool whose sellable count a connected source sets is the exception: its count is the source’s own number, not a count of units, so it can exceed the capacity. A request can form at most 90 disjoint date ranges in total; batch genuinely sparse updates into multiple requests. Changed values queue to the channel sync outbox and propagate to connected channels asynchronously. An entry that does not change availability queues no availability update.
Supahost compares each night with the values it stores. A night sent with the values Supahost already stores is not stored again. Supahost sends the channel only the nights that changed, so you can send your whole calendar window on every write. nightsChanged counts the nights that changed: availability counts inventory pool nights, and restrictions counts rate plan nights. A night that follows the pool capacity or the plan base rate changes when you send a value for it, also the same value: from then on it keeps that value. A night with no stored rate plan values changes when an entry writes it. A write that changes nothing queues nothing and sends no calendar.updated webhook.
Supahost sends an unchanged night to the channel again in one case: its last change failed and Supahost stopped retrying it. Then the same values in a new write send it again. A night whose change is still pending is not sent twice. Read the calendar with include=channel to see which nights failed.
Send an Idempotency-Key header to make retries safe: a repeated PUT with the same key and the same payload returns the original summary and applies nothing twice. A replay returns the same skippedNights. The same key with a different payload, a different revisionAt included, or with a different skipLocked value, fails with 409 idempotency_key_reused.
The 200 body also has channelSync. It says what the write queued for the channel, for availability and for restrictions. queued: Supahost queued a change for the channel. unchanged: no stored value of that kind changed, so Supahost queued nothing new. It does not say whether the channel has the values. Read the calendar with include=channel for that. not_written: no entry wrote that kind of value. not_sent: Supahost does not send these values, changed or not, and reason says why (property_inactive, not_connected, no_rate_plan, awaiting_feed, derived_rate_plan). It is the same reason the rate plan calendar with include=channel gives for those nights. heldClosed is true while Supahost holds the property closed on the channel, so availability goes out as 0. channelSync does not say that the channel accepted the change. Read the calendar with include=channel for that. A replay with the same Idempotency-Key returns the stored channelSync.
Send validateOnly=true to test a request against the live calendar without writing it. Supahost runs the checks a real write runs before it writes, under the same rules, and answers 200. accepted is true when the calendar checks would accept the request now, and then refusals is empty. It does not check an Idempotency-Key against the keys Supahost has stored, so a real write that reuses a key with a different body can still answer 409 idempotency_key_reused. refusals lists every refusal it would answer with, in the order it would meet them, each with its HTTP status and the same problem document: the same code, errors items and field paths, and the same named nights. A property whose calendar writes are paused is still checked: calendar_writes_paused comes first, and the field errors of your entries follow it. With skipLocked=true, an accepted validation lists in skippedNights the locked nights a real write would skip. An accepted validation also lists in refusedNights the pool nights a real write would refuse for an older revisionAt. Nothing is stored, queued or sent, no calendar.updated webhook is sent, and no operator alert is raised. The queueing, webhook and audit steps of a real write do not run, so a database failure in them is not predicted.
How far a validation goes depends on the key and the property. With the calendar:write scope, on a property a real write would not refuse for its calendar authority, it takes the real write’s locks and runs its night writes in a transaction that it rolls back: an accepted answer then carries daysApplied, nightsChanged and countsWithoutObservation, counted as the write counts them. With only calendar:read, or on a property whose calendar writes are paused, it runs the same checks as plain reads, takes no lock and writes nothing, and the answer carries neither daysApplied nor nightsChanged. A validation that cannot finish within about 2 seconds, for example while a booking or another write holds the nights, answers 503 service_busy; send it again.
Validation needs the calendar:read or the calendar:write scope; a real write still needs calendar:write. An Idempotency-Key sent with validateOnly=true is checked for its format and otherwise ignored: nothing is stored under it, so you can send the same key with the real write. These answer as a real write does, not with a validation: 401 for an invalid key, 403 for a missing scope, 403 sandbox_read_only for a test key, 429 for the rate limit, 400 for a body that is not JSON, an invalid validateOnly or skipLocked, an invalid Idempotency-Key or a malformed property ID, and 404 for a property outside the key’s workspace, also when the body is invalid. A body that is JSON but does not match the schema is listed in refusals. A test key reads a fixed sample dataset, not your live calendar, and a validation checks the request against the live calendar, so validation needs a live key. Validations count toward the rate limit.
| Field | Type | Required | Description |
|---|---|---|---|
Authorization | string | Required | Send Bearer $SUPAHOST_API_KEY. |
Idempotency-Key | string | Optional | 1 to 200 characters. Makes retries safe. |
| Field | Type | Required | Description |
|---|---|---|---|
propertyId | string (uuid) | Required | Property UUID. |
| Field | Type | Required | Description |
|---|---|---|---|
skipLocked | 'true' | 'false' | Optional | Send true to write every unlocked entry and list the locked nights, with their reasons, in skippedNights. A skipped entry is not checked against stored values, so it cannot fail the request. Without it, one locked night fails the whole request with 409. It does not skip a protected closure: reopening one still fails the request. |
skip_locked | 'true' | 'false' | Optional | Deprecated: use skipLocked. |
validateOnly | 'true' | 'false' | Optional | Send true, once, to check the request without writing it: Supahost runs the checks a real write runs before it writes and answers 200 with validateOnly, accepted (true when the calendar checks would accept the request now; the Idempotency-Key is not checked against stored keys, so a real write that reuses a key with a different body can still answer 409 idempotency_key_reused) and every refusal a real write would answer with, in its order, each with its status and problem document. Nothing is stored, queued or sent, and no webhook or Idempotency-Key record is made; the queueing and audit steps of a real write do not run, so a failure there is not predicted. Needs calendar:read or calendar:write and a live key: a test key reads a fixed sample dataset, not the live calendar a validation checks, so it answers 403 sandbox_read_only. With calendar:write, on a property a real write would not refuse for its calendar authority, the validation takes the real write's locks and runs its night writes in a transaction it rolls back, and an accepted answer carries daysApplied, nightsChanged and countsWithoutObservation. Either way an accepted answer lists in refusedNights the pool nights a real write would refuse. Otherwise (a calendar:read key, or a property whose calendar writes are paused) it takes no lock and writes nothing, and the answer carries neither. A validation that cannot finish within about 2 seconds answers 503 service_busy. Any other value, or the parameter sent twice, is a 400. |
validate_only | 'true' | 'false' | Optional | Deprecated: use validateOnly. |
| Field | Type | Required | Description |
|---|---|---|---|
days[].date | string (date) | Required | Stay date in YYYY-MM-DD format. |
days[].inventoryPool.id | string | Required | Inventory pool ID this entry writes. Optional code, name, strategy and roomTypeId fields are read metadata. Their values do not change the pool. |
days[].ratePlanId | string | Optional | Active rate plan ID on the pool to write. Omit to write every active rate plan on the pool. Entries sharing a pool and date must target different plans with matching pool-level fields. |
days[].revisionAt | string (date-time) | Conditional | Required, and never null, on an entry that sends availableUnits or closed. A time that only goes up for a pool night, such as the start of your sync run. Supahost keeps the newest one per pool night and refuses an older one for that night. An RFC 3339 date-time with a time-zone offset and at most 6 fractional digits, no more than 2 minutes after Supahost’s own time for the request. Optional on any other entry: then only its format is checked. |
days[].observedAt | string (date-time) | null | Conditional | Required on an entry that sends availableUnits or closed, as a date-time or null. A time no later than the supplier read behind the count. Supahost treats the read as 2 minutes earlier than sent, to allow for clock differences. Send null when no supplier read stands behind it. Same format and limit as revisionAt. Optional on any other entry: then only its format is checked. |
days[].availableUnits | integer | Optional | Target available units after reservations and blocks. With them it must fit the pool capacity, except on a pool whose sellable count a connected source sets. Omit it to keep the stored availability. |
days[].closed | boolean | Optional | Whether the pool is closed on this date. Omit it to keep the stored value. New nights default to open. |
days[].stopSell | boolean | Optional | Whether active rate plans stop selling this date. Omit it to keep the stored value. New nights default to false. |
days[].rate | object | null | Optional | amount/currency pair, where amount is a currency amount with two decimals, such as 325.00, and must be positive. amountMinor still works and will be removed. Omit rate or send null to keep the stored rate. |
days[].minStay | integer | null | Optional | Minimum stay for an arrival on this date. Omit it or send null to keep the stored value. Today a new night stores the plan’s current default when this is left out. A later change to the plan default does not move that night. |
days[].minStayThrough | integer | null | Optional | 1 to 365 nights. Minimum stay for any stay that includes this date. Omit it or send null to keep the stored value. A night without its own value uses its minimum stay. Sending minStayThrough stores a fixed value for that night. The night then no longer follows minStay, and the API cannot clear the value today (issue #1097). To keep a night following minStay, do not send minStayThrough. |
days[].maxStay | integer | Optional | 0 to 365 nights. Zero removes the limit. Omission preserves the stored value. Today a new night stores the plan’s current default, or 14, when this is left out. A later change to the plan default does not move that night. A positive maximum cannot be less than the effective minimum stays. |
days[].closedToArrival | boolean | Optional | Whether arrivals are closed. Omission preserves the stored value; new nights default to false. |
days[].closedToDeparture | boolean | Optional | Whether departures are closed. Omission preserves the stored value; new nights default to false. |
| Field | Type | Required | Description |
|---|---|---|---|
data | CalendarWriteResult | Required | The applied calendar write summary. |
meta | object | Required | Response metadata. |
meta.requestId | string | Required | Support identifier for this request. |
data.propertyId | string | Required | Public UUID of the property the calendar write applied to. |
data.daysApplied | integer | Required | Entries the write accepted and did not skip or refuse. It counts entries, including an entry that changed nothing. nightsChanged counts the nights that changed. |
data.nightsChanged | object | Optional | Nights the write changed. A night sent with the values Supahost already stores does not count and is not stored again. Supahost sends it to the channel again only when its last change failed and Supahost stopped retrying it. When both counts are 0, the write sends no calendar.updated webhook. Absent only when an Idempotency-Key replays a request first made before Supahost counted changed nights. |
data.nightsChanged.availability | integer | Required | Inventory pool nights whose stored availability or closed value changed. |
data.nightsChanged.restrictions | integer | Required | Rate plan nights whose stored rate or stay rules changed. An entry without ratePlanId counts once for each active plan it changed. |
data.nightsChanged.observations | integer | Optional | Inventory pool nights whose count did not change, but whose new observedAt changed the availability the channel receives, because it changed how many held reservation nights come off the count. Supahost sends each one to the channel. It does not send a calendar.updated webhook for them, because the stored calendar did not change. Absent only when an Idempotency-Key replays a request first made before Supahost counted them. |
data.countsWithoutObservation | integer | Optional | Inventory pool nights the write applied with observedAt: null: no supplier read stands behind their count, so every held reservation night comes off it. Absent only when an Idempotency-Key replays a request first made before Supahost counted them. |
data.refusedNights | object[] | Optional | Every pool night the write refused, with the reason. Nothing is stored for a refused night: not its count, its rates or its stay rules. The request still answers 200 and applies the other nights. The list is not capped. Absent only when an Idempotency-Key replays a request first made before Supahost refused nights. |
data.refusedNights[].inventoryPoolId | string | Required | Inventory pool of the refused night. |
data.refusedNights[].date | string (date) | Required | Refused stay date in YYYY-MM-DD format. |
data.refusedNights[].reason | 'stale_revision' | Required | Why the night was refused. "stale_revision": Supahost already stores a count for the night with a later revisionAt, so this one is older and was not applied. |
data.refusedNights[].retry | boolean | Required | Whether sending the same entry again can succeed. Always false for stale_revision: drop the entry. |
data.refusedNights[].revisionAt | string (date-time) | Required | The revisionAt the request sent for the night, in UTC with 6 fractional digits. |
data.refusedNights[].storedRevisionAt | string (date-time) | Required | The later revisionAt Supahost stores for the night, in UTC with 6 fractional digits. |
data.refusedNightCount | integer | Optional | Number of pool nights the write refused. Present with refusedNights. |
data.skippedNights | object[] | Optional | Every locked night the write skipped, with the reason it is locked. Present only with skipLocked=true. The list is not capped. Each night appears once, even when several entries name it. |
data.skippedNights[].inventoryPoolId | string | Required | Inventory pool of the locked night. A lock covers the whole pool on that date. |
data.skippedNights[].date | string (date) | Required | Locked stay date in YYYY-MM-DD format. |
data.skippedNights[].reason | 'manual' | 'edit' | 'feed_conflict' | 'carried_over' | Optional | Why the night is locked (see lockedNights[].reason). Absent only when an Idempotency-Key replays a request first made before 2026-11-11. |
data.skippedNightCount | integer | Optional | Number of locked nights the write skipped. Present only with skipLocked=true. |
data.channelSync | object | Optional | What the write sent to the channel. It says what was queued, not whether the channel accepted it: read the calendar with include=channel for that. Absent only when an Idempotency-Key replays a request first made before 2026-11-11. |
data.channelSync.availability | object | Required | Availability of the room types the write changed. |
data.channelSync.availability.outcome | 'queued' | 'unchanged' | 'not_written' | 'not_sent' | Required | queued: a change is on its way to the channel. unchanged: no stored value of this kind changed, so Supahost queued nothing new. It does not say whether the channel has the values: read the calendar with include=channel for that. not_written: no entry wrote this kind of value. not_sent: Supahost does not send these values, changed or not; see reason. |
data.channelSync.availability.reason | string | null | Required | Why the change is not sent, or null. One of property_inactive, not_connected, no_rate_plan, awaiting_feed, derived_rate_plan: the reason the rate plan calendar with include=channel gives for those nights. |
data.channelSync.restrictions | object | Required | Rates and stay rules of the rate plans the write changed. |
data.channelSync.restrictions.outcome | 'queued' | 'unchanged' | 'not_written' | 'not_sent' | Required | queued: a change is on its way to the channel. unchanged: no stored value of this kind changed, so Supahost queued nothing new. It does not say whether the channel has the values: read the calendar with include=channel for that. not_written: no entry wrote this kind of value. not_sent: Supahost does not send these values, changed or not; see reason. |
data.channelSync.restrictions.reason | string | null | Required | Why the change is not sent, or null. One of property_inactive, not_connected, no_rate_plan, awaiting_feed, derived_rate_plan: the reason the rate plan calendar with include=channel gives for those nights. |
data.channelSync.heldClosed | boolean | Required | True when Supahost holds the property closed on the channel, so availability goes out as 0. Read GET /properties/{propertyId}/channel-sync. |
| Field | Type | Required | Description |
|---|---|---|---|
data | CalendarValidationResult | Required | What a real write of the same request would answer, with nothing stored. |
meta | object | Required | Response metadata. |
meta.requestId | string | Required | Support identifier for this request. |
data.propertyId | string | Required | Public UUID of the property the calendar write was validated against. |
data.validateOnly | 'true' | Required | Always true: Supahost checked the request and stored, queued and sent nothing. |
data.accepted | boolean | Required | True when the calendar checks would accept the request now; refusals is then empty. The Idempotency-Key is not checked against stored keys, so a real write that reuses a key with a different body can still answer 409 idempotency_key_reused. |
data.refusals | object[] | Required | Every refusal a real write would answer with, in the order it would meet them: a body that does not match the schema, then a property whose calendar writes are paused (calendar_writes_paused), then the first failed check of the entries (the field errors, a locked night or a protected night). A paused property is still checked, so its field errors are listed too. |
data.refusals[].status | integer | Required | The HTTP status the real write would answer with, such as 400 or 409. |
data.refusals[].problem | object | Required | The problem document the real write would answer with: the same code, detail, errors items and field paths, and the same named nights. |
data.refusals[].problem.type | string | Required | |
data.refusals[].problem.title | string | Required | |
data.refusals[].problem.status | integer | Required | |
data.refusals[].problem.code | string | Required | Stable machine-readable error code. Current codes: invalid_api_key, insufficient_scope, rate_limit_exceeded, sandbox_read_only, closure_permission_required, flow_permission_required, invalid_request, invalid_reference, invalid_date_range, invalid_date, invalid_datetime, invalid_limit, invalid_status, invalid_cursor, invalid_idempotency_key, missing_idempotency_key, invalid_status_transition, invalid_property_id, invalid_reservation_id, invalid_task_id, invalid_conversation_id, invalid_webhook_id, invalid_delivery_id, invalid_flow_id, invalid_rate_plan_id, invalid_pool_id, invalid_block_id, invalid_adjustment_id, invalid_flow_request, payload_too_large, night_value_required, count_time_required, count_time_in_future, calendar_result_too_large, closure_pool_unavailable, closure_date_unavailable, not_found, idempotency_key_reused, sync_in_progress, sync_failed, reference_changed, reference_in_use, reference_inactive, calendar_feed_managed, calendar_move_pending, calendar_writes_paused, protected_calendar_closure, calendar_night_locked, date_block_started, closure_changed, conversation_closed, replies_not_supported, member_inactive, insufficient_inventory, channel_rate_plan, channel_managed, reservation_cancelled, reservation_completed, unit_assigned, multiple_items, flow_unavailable, flow_webhook_key_changed, flow_scope_mismatch, flow_context_unavailable, webhook_endpoint_disabled, webhook_delivery_in_flight, flow_changed, price_adjustment_limit_reached, precondition_failed, write_conflict, service_busy, internal_error. |
data.refusals[].problem.detail | string | Required | |
data.refusals[].problem.requestId | string | Required | |
data.refusals[].problem.retryable | 'no' | 'now' | 'after' | Required | What to do next. no: the same request fails the same way, so change the request or the records first. now: send the same request again. after: send it again once the Retry-After header’s seconds have passed. One code can carry more than one class, so read this member rather than the code. |
data.refusals[].problem.errors | object[] | Optional | Every invalid field the server found in the request, in request order, at most 100. The first item is the one detail describes. Fix them all before you send the request again. |
data.refusals[].problem.errors[].field | string | Required | The invalid field as a dot path: an array index is a plain number, and an array body starts with its collection name, such as days.3.rate, roomTypes.0.capacity or stay.arrivalDate. body names the request body as a whole. |
data.refusals[].problem.errors[].message | string | Required | What is wrong with this field. |
data.refusals[].problem.errors[].code | string | Optional | The problem code for this field, such as invalid_reference. The first item has the top-level code. |
data.refusals[].problem.errorsTruncated | boolean | Optional | Present and true when the request has more than 100 invalid fields and errors lists only the first 100. |
data.refusals[].problem.blockedBy | object | Optional | The record whose channel sync blocks the write. Present on sync_in_progress and sync_failed. |
data.refusals[].problem.blockedBy.type | 'property' | 'room_type' | 'rate_plan' | Required | Kind of record whose channel sync blocks the write. |
data.refusals[].problem.blockedBy.id | string | Required | ID of that record. Read it to see its sync state. |
data.refusals[].problem.blockedBy.reason | string | null | Required | Why the sync is failing, or null. Current reasons: channel_rejected, channel_unreachable, confirmation_unavailable, connection_problem, setup_incomplete, other. Treat an unknown reason as other. |
data.refusals[].problem.lockedNights | object[] | Conditional | Locked nights in the request, ordered by date and pool, each with its lock reason. Lists at most 100. |
data.refusals[].problem.lockedNights[].inventoryPoolId | string | Conditional | Inventory pool of the locked night. A lock covers the whole pool on that date. |
data.refusals[].problem.lockedNights[].date | string (date) | Conditional | Locked stay date in YYYY-MM-DD format. |
data.refusals[].problem.lockedNights[].reason | 'manual' | 'edit' | 'feed_conflict' | 'carried_over' | Conditional | Why the night is locked. "manual": a person locked it in the calendar. "edit": a person or the Supahost agent changed it on a property whose calendar was moved from the retired supplier feed to the API, or earlier, while the feed wrote it. "feed_conflict": a lock the retired supplier feed set when it found the night changed outside the feed; locks of this reason can still be on a property. "carried_over": an earlier lock on the whole day, kept for each room type. |
data.refusals[].problem.lockedNightCount | integer | Conditional | Number of locked nights in the request. |
data.refusals[].problem.protectedNights | object[] | Conditional | Protected nights the request would reopen, ordered by date and pool. Lists at most 100. Remove these entries, or remove their protection first. Absent only in the rare case where the database refused the write before the nights could be named. |
data.refusals[].problem.protectedNights[].inventoryPoolId | string | Conditional | Inventory pool of the protected night. |
data.refusals[].problem.protectedNights[].date | string (date) | Conditional | Protected stay date in YYYY-MM-DD format. |
data.refusals[].problem.protectedNightCount | integer | Conditional | Number of protected nights the request would reopen. Present with protectedNights. |
data.daysApplied | integer | Optional | Present when accepted and the validation ran the night writes: a key with calendar:write, on a property a real write would not refuse for its calendar authority. The entries a real write would apply now, as in the write summary. |
data.nightsChanged | object | Optional | Present with daysApplied: the nights a real write would change now, counted exactly as the write counts them. |
data.nightsChanged.availability | integer | Required | Inventory pool nights whose stored availability or closed value changed. |
data.nightsChanged.restrictions | integer | Required | Rate plan nights whose stored rate or stay rules changed. An entry without ratePlanId counts once for each active plan it changed. |
data.nightsChanged.observations | integer | Optional | Inventory pool nights whose count did not change, but whose new observedAt changed the availability the channel receives, because it changed how many held reservation nights come off the count. Supahost sends each one to the channel. It does not send a calendar.updated webhook for them, because the stored calendar did not change. Absent only when an Idempotency-Key replays a request first made before Supahost counted them. |
data.countsWithoutObservation | integer | Optional | Present with daysApplied: the inventory pool nights a real write would apply with observedAt: null. |
data.refusedNights | object[] | Optional | Present when accepted: every pool night a real write would refuse now, with the reason, as in the write summary. A refused night does not make the request a refusal. |
data.refusedNights[].inventoryPoolId | string | Required | Inventory pool of the refused night. |
data.refusedNights[].date | string (date) | Required | Refused stay date in YYYY-MM-DD format. |
data.refusedNights[].reason | 'stale_revision' | Required | Why the night was refused. "stale_revision": Supahost already stores a count for the night with a later revisionAt, so this one is older and was not applied. |
data.refusedNights[].retry | boolean | Required | Whether sending the same entry again can succeed. Always false for stale_revision: drop the entry. |
data.refusedNights[].revisionAt | string (date-time) | Required | The revisionAt the request sent for the night, in UTC with 6 fractional digits. |
data.refusedNights[].storedRevisionAt | string (date-time) | Required | The later revisionAt Supahost stores for the night, in UTC with 6 fractional digits. |
data.refusedNightCount | integer | Optional | Present with refusedNights: how many there are. |
data.skippedNights | object[] | Optional | Present when accepted with skipLocked=true: every locked night a real write would skip, with its reason. |
data.skippedNights[].inventoryPoolId | string | Required | Inventory pool of the locked night. A lock covers the whole pool on that date. |
data.skippedNights[].date | string (date) | Required | Locked stay date in YYYY-MM-DD format. |
data.skippedNights[].reason | 'manual' | 'edit' | 'feed_conflict' | 'carried_over' | Optional | Why the night is locked (see lockedNights[].reason). Absent only when an Idempotency-Key replays a request first made before 2026-11-11. |
data.skippedNightCount | integer | Optional | Present with skippedNights: how many there are. |
| Field | Type | Required | Description |
|---|---|---|---|
type | string | Required | |
title | string | Required | |
status | integer | Required | |
code | string | Required | Stable machine-readable error code. Current codes: invalid_api_key, insufficient_scope, rate_limit_exceeded, sandbox_read_only, closure_permission_required, flow_permission_required, invalid_request, invalid_reference, invalid_date_range, invalid_date, invalid_datetime, invalid_limit, invalid_status, invalid_cursor, invalid_idempotency_key, missing_idempotency_key, invalid_status_transition, invalid_property_id, invalid_reservation_id, invalid_task_id, invalid_conversation_id, invalid_webhook_id, invalid_delivery_id, invalid_flow_id, invalid_rate_plan_id, invalid_pool_id, invalid_block_id, invalid_adjustment_id, invalid_flow_request, payload_too_large, night_value_required, count_time_required, count_time_in_future, calendar_result_too_large, closure_pool_unavailable, closure_date_unavailable, not_found, idempotency_key_reused, sync_in_progress, sync_failed, reference_changed, reference_in_use, reference_inactive, calendar_feed_managed, calendar_move_pending, calendar_writes_paused, protected_calendar_closure, calendar_night_locked, date_block_started, closure_changed, conversation_closed, replies_not_supported, member_inactive, insufficient_inventory, channel_rate_plan, channel_managed, reservation_cancelled, reservation_completed, unit_assigned, multiple_items, flow_unavailable, flow_webhook_key_changed, flow_scope_mismatch, flow_context_unavailable, webhook_endpoint_disabled, webhook_delivery_in_flight, flow_changed, price_adjustment_limit_reached, precondition_failed, write_conflict, service_busy, internal_error. |
detail | string | Required | |
requestId | string | Required | |
retryable | 'no' | 'now' | 'after' | Required | What to do next. no: the same request fails the same way, so change the request or the records first. now: send the same request again. after: send it again once the Retry-After header’s seconds have passed. One code can carry more than one class, so read this member rather than the code. |
errors | object[] | Optional | Every invalid field the server found in the request, in request order, at most 100. The first item is the one detail describes. Fix them all before you send the request again. |
errors[].field | string | Required | The invalid field as a dot path: an array index is a plain number, and an array body starts with its collection name, such as days.3.rate, roomTypes.0.capacity or stay.arrivalDate. body names the request body as a whole. |
errors[].message | string | Required | What is wrong with this field. |
errors[].code | string | Optional | The problem code for this field, such as invalid_reference. The first item has the top-level code. |
errorsTruncated | boolean | Optional | Present and true when the request has more than 100 invalid fields and errors lists only the first 100. |
blockedBy | object | Optional | The record whose channel sync blocks the write. Present on sync_in_progress and sync_failed. |
blockedBy.type | 'property' | 'room_type' | 'rate_plan' | Required | Kind of record whose channel sync blocks the write. |
blockedBy.id | string | Required | ID of that record. Read it to see its sync state. |
blockedBy.reason | string | null | Required | Why the sync is failing, or null. Current reasons: channel_rejected, channel_unreachable, confirmation_unavailable, connection_problem, setup_incomplete, other. Treat an unknown reason as other. |
lockedNights | object[] | Required | Locked nights in the request, ordered by date and pool, each with its lock reason. Lists at most 100. |
lockedNights[].inventoryPoolId | string | Required | Inventory pool of the locked night. A lock covers the whole pool on that date. |
lockedNights[].date | string (date) | Required | Locked stay date in YYYY-MM-DD format. |
lockedNights[].reason | 'manual' | 'edit' | 'feed_conflict' | 'carried_over' | Required | Why the night is locked. "manual": a person locked it in the calendar. "edit": a person or the Supahost agent changed it on a property whose calendar was moved from the retired supplier feed to the API, or earlier, while the feed wrote it. "feed_conflict": a lock the retired supplier feed set when it found the night changed outside the feed; locks of this reason can still be on a property. "carried_over": an earlier lock on the whole day, kept for each room type. |
lockedNightCount | integer | Required | Number of locked nights in the request. |
| Field | Type | Required | Description |
|---|---|---|---|
type | string | Required | |
title | string | Required | |
status | integer | Required | |
code | string | Required | Stable machine-readable error code. Current codes: invalid_api_key, insufficient_scope, rate_limit_exceeded, sandbox_read_only, closure_permission_required, flow_permission_required, invalid_request, invalid_reference, invalid_date_range, invalid_date, invalid_datetime, invalid_limit, invalid_status, invalid_cursor, invalid_idempotency_key, missing_idempotency_key, invalid_status_transition, invalid_property_id, invalid_reservation_id, invalid_task_id, invalid_conversation_id, invalid_webhook_id, invalid_delivery_id, invalid_flow_id, invalid_rate_plan_id, invalid_pool_id, invalid_block_id, invalid_adjustment_id, invalid_flow_request, payload_too_large, night_value_required, count_time_required, count_time_in_future, calendar_result_too_large, closure_pool_unavailable, closure_date_unavailable, not_found, idempotency_key_reused, sync_in_progress, sync_failed, reference_changed, reference_in_use, reference_inactive, calendar_feed_managed, calendar_move_pending, calendar_writes_paused, protected_calendar_closure, calendar_night_locked, date_block_started, closure_changed, conversation_closed, replies_not_supported, member_inactive, insufficient_inventory, channel_rate_plan, channel_managed, reservation_cancelled, reservation_completed, unit_assigned, multiple_items, flow_unavailable, flow_webhook_key_changed, flow_scope_mismatch, flow_context_unavailable, webhook_endpoint_disabled, webhook_delivery_in_flight, flow_changed, price_adjustment_limit_reached, precondition_failed, write_conflict, service_busy, internal_error. |
detail | string | Required | |
requestId | string | Required | |
retryable | 'no' | 'now' | 'after' | Required | What to do next. no: the same request fails the same way, so change the request or the records first. now: send the same request again. after: send it again once the Retry-After header’s seconds have passed. One code can carry more than one class, so read this member rather than the code. |
errors | object[] | Optional | Every invalid field the server found in the request, in request order, at most 100. The first item is the one detail describes. Fix them all before you send the request again. |
errors[].field | string | Required | The invalid field as a dot path: an array index is a plain number, and an array body starts with its collection name, such as days.3.rate, roomTypes.0.capacity or stay.arrivalDate. body names the request body as a whole. |
errors[].message | string | Required | What is wrong with this field. |
errors[].code | string | Optional | The problem code for this field, such as invalid_reference. The first item has the top-level code. |
errorsTruncated | boolean | Optional | Present and true when the request has more than 100 invalid fields and errors lists only the first 100. |
blockedBy | object | Optional | The record whose channel sync blocks the write. Present on sync_in_progress and sync_failed. |
blockedBy.type | 'property' | 'room_type' | 'rate_plan' | Required | Kind of record whose channel sync blocks the write. |
blockedBy.id | string | Required | ID of that record. Read it to see its sync state. |
blockedBy.reason | string | null | Required | Why the sync is failing, or null. Current reasons: channel_rejected, channel_unreachable, confirmation_unavailable, connection_problem, setup_incomplete, other. Treat an unknown reason as other. |
protectedNights | object[] | Optional | Protected nights the request would reopen, ordered by date and pool. Lists at most 100. Remove these entries, or remove their protection first. Absent only in the rare case where the database refused the write before the nights could be named. |
protectedNights[].inventoryPoolId | string | Required | Inventory pool of the protected night. |
protectedNights[].date | string (date) | Required | Protected stay date in YYYY-MM-DD format. |
protectedNightCount | integer | Optional | Number of protected nights the request would reopen. Present with protectedNights. |
GET /properties/{propertyId}/rate-plans/{ratePlanId}/calendar
Verify nightly prices and all restrictions for one active plan with the calendar:read scope. The response includes stop-sold nights, also those without a rate.
stopSell reports the stored flag. rate is null on a night without a rate, such as a stopped night written without one, and that night does not sell. minStayThrough is null when the night follows minStay. rate falls back to the plan base price when no night exists. Other defaults are minimum 1, maximum 14, and false flags. Maximum 0 means unlimited.
Pool availability subtracts reservations and property-local blocks. Closed pools return zero availability while their plan prices and restrictions remain visible.
Both dates are inclusive. The default range spans 31 days from today in the property time zone. The maximum is 92 days. The endpoint returns 404 for an unknown property, mismatched plan, inactive plan or inactive pool. It reads Supahost data and does not read the channel.
Send include=channel to add a channel object to each row. It says, per night, whether the channel has what Supahost holds for it, and why not. See Channel delivery state below. Without include the response and its cost are unchanged. Here restrictions is this rate plan and availability is its pool's room type.
| Field | Type | Required | Description |
|---|---|---|---|
Authorization | string | Required | Send Bearer $SUPAHOST_API_KEY. |
| Field | Type | Required | Description |
|---|---|---|---|
propertyId | string (uuid) | Required | Property UUID. |
ratePlanId | string (uuid) | Required | Rate plan UUID on this property. |
| Field | Type | Required | Description |
|---|---|---|---|
from | string (date) | Optional | First stay date, inclusive. The default is today in the property time zone. |
to | string (date) | Optional | Last stay date, inclusive. The default is 30 days after from; the range can span at most 92 days. |
include | 'channel' | Optional | Send channel to add a channel object to each row: whether the channel has what Supahost holds for that night, and why not. Without it the response is unchanged. |
| Field | Type | Required | Description |
|---|---|---|---|
data | RatePlanCalendarDay[] | Required | One row per stay date for the selected rate plan. |
meta | object | Required | Response metadata. |
meta.requestId | string | Required | Support identifier for this request. |
data[].date | string (date) | Required | Stay date in YYYY-MM-DD format. |
data[].inventoryPool | object | Required | Inventory pool this row describes. |
data[].inventoryPool.id | string | Required | Stable inventory pool ID. |
data[].inventoryPool.code | string | Required | Inventory pool code. |
data[].inventoryPool.name | string | Required | Inventory pool display name. |
data[].inventoryPool.strategy | 'pooled' | 'fixed_unit' | 'entitlement' | Required | Inventory strategy of the pool. |
data[].inventoryPool.roomTypeId | string | Required | Room type the pool sells. |
data[].availableUnits | integer | Required | Units left after reservations and blocks; 0 when the pool is closed. |
data[].closed | boolean | Required | Whether the pool is closed on this date. |
data[].stopSell | boolean | Required | Stored stop-sell restriction for this plan; false when no night exists. A night with a null rate does not sell either. |
data[].rate | object | null | Required | Stored nightly price with base-price fallback, also on stop-sold nights that have one. Null when the night has no rate: a stop-sold night written without a rate is kept that way, and it needs a rate before it can be reopened. |
data[].rate.amount | string | Conditional | Required when rate is an object. Amount in the currency unit with two decimals (325.00). |
data[].rate.amountMinor | string | Conditional | Required when rate is an object. Deprecated: the same amount in hundredths (32500). Read amount. |
data[].rate.currency | string | Conditional | Required when rate is an object. Three-letter currency code. |
data[].minStay | integer | Required | Minimum stay for an arrival on this date; defaults to 1 when no night exists. |
data[].minStayThrough | integer | null | Required | Separate minimum stay for any stay that includes this date. Null means the night follows minStay. |
data[].channel | object | Optional | Whether the channel has what Supahost holds for this night. Present only with include=channel. |
data[].channel.availability | object | Required | Channel state of the room type availability on this night. |
data[].channel.availability.state | 'synced' | 'pending' | 'failed' | 'held' | 'closed_by_channel' | 'not_sent' | Required | synced: Nothing is outstanding. The channel confirmed the last change, or no change was needed. Supahost does not read the channel again to report this. pending: A change is on its way to the channel, or Supahost is retrying one. failed: The last change failed and Supahost will not retry it. A person must resolve it in Supahost. held: Supahost holds the night closed on the channel (availability 0) until it can confirm the property calendar there. closed_by_channel: The channel closed tonight at its own same-day cut-off. Supahost expects this and does not send the night again. not_sent: Supahost does not send this night to the channel. reason says why. |
data[].channel.availability.reason | string | null | Required | Why the night is not synced, or null. Current reasons: channel_rejected, channel_mismatch, channel_unreachable, confirmation_unavailable, connection_problem, closed_by_channel_cutoff, activation_unconfirmed, property_inactive, not_connected, derived_rate_plan, no_rate_plan, past_night, awaiting_value, awaiting_feed, other. Treat an unknown reason as other. |
data[].channel.availability.value | integer | null | Required | The availability Supahost holds for the channel on this night: the room type total after holds and the close-out. It can differ from the row's availableUnits, which is one pool. 0 while held. Null when the night is not sent. |
data[].channel.availability.observedValue | integer | Optional | The availability a read of the channel showed when it differed from value. Present only then. |
data[].channel.availability.changedAt | string (date-time) | null | Required | When Supahost last recorded a change to the delivery behind this state: the queued or retried change, the failure, or the closure. For held, when the hold started (the hold.since of GET /properties/{propertyId}/channel-sync). Null for synced and not_sent. |
data[].channel.restrictions | object | Required | Channel state of the rates and stay rules on this night. On the rate plan calendar it is that plan. On the property calendar it sums up the pool's active rate plans: failed when one failed, else pending when one is pending, else synced when one reaches the channel, else not_sent (no_rate_plan when the pool has no active plan). |
data[].channel.restrictions.state | 'synced' | 'pending' | 'failed' | 'held' | 'closed_by_channel' | 'not_sent' | Required | synced: Nothing is outstanding. The channel confirmed the last change, or no change was needed. Supahost does not read the channel again to report this. pending: A change is on its way to the channel, or Supahost is retrying one. failed: The last change failed and Supahost will not retry it. A person must resolve it in Supahost. held: Supahost holds the night closed on the channel (availability 0) until it can confirm the property calendar there. closed_by_channel: The channel closed tonight at its own same-day cut-off. Supahost expects this and does not send the night again. not_sent: Supahost does not send this night to the channel. reason says why. |
data[].channel.restrictions.reason | string | null | Required | Why the night is not synced, or null. Current reasons: channel_rejected, channel_mismatch, channel_unreachable, confirmation_unavailable, connection_problem, closed_by_channel_cutoff, activation_unconfirmed, property_inactive, not_connected, derived_rate_plan, no_rate_plan, past_night, awaiting_value, awaiting_feed, other. Treat an unknown reason as other. |
data[].channel.restrictions.changedAt | string (date-time) | null | Required | When Supahost last recorded a change to the delivery behind this state: the queued or retried change, the failure, or the closure. For held, when the hold started (the hold.since of GET /properties/{propertyId}/channel-sync). Null for synced and not_sent. |
data[].holds | object | Optional | With include=holds: what Supahost takes off this pool night’s count for held nights, and why. |
data[].holds.count | integer | null | Required | The night’s own count before blocks and held nights come off: the stored sellable count less reservations. On a property whose calendar was moved from the retired supplier feed to the API, Supahost stores the availableUnits you write as sent, so count is your number. On every other property it stores your availableUnits plus the units blocks hold at that moment. Either way a block added or removed later changes blocked, not count. Null when the night has no count of its own and follows the pool capacity. |
data[].holds.closed | boolean | Required | Whether the pool is closed on this date. |
data[].holds.sent | object | null | Required | The times of the last count the API wrote for this pool night, or null when the API never wrote one. |
data[].holds.sent.observedAt | string (date-time) | null | Conditional | Required when sent is an object. The observedAt you sent, or null when you sent observedAt: null. |
data[].holds.sent.revisionAt | string (date-time) | Conditional | Required when sent is an object. The newest revisionAt Supahost accepted for this pool night. |
data[].holds.sent.recordedAt | string (date-time) | Conditional | Required when sent is an object. When Supahost stored it. |
data[].holds.observedAtUsed | string (date-time) | null | Required | The read time Supahost compares confirmations with, as stored. When your write stored it, it is 2 minutes before the observedAt you sent; when the retired supplier feed stored it, it is the feed’s own read time. Null when no read time belongs to the stored count. |
data[].holds.blocked | integer | Required | Units availability blocks hold on this date. |
data[].holds.subtracted | integer | Required | Units that come off the count for held nights not yet included in it: the sum of units over heldNights with reflected: false. Always 0 on a pool whose count no connected source sets, and on a night without its own count. |
data[].holds.sends | integer | null | Required | This pool’s part of the availability Supahost computes for the channel for the room type night: 0 when closed, otherwise the count (or the pool capacity less reservations) less blocked and subtracted, never below 0. The room type gets the sum over its active pools. Null when the channel receives nothing for this room type night: the night is in the past, the property or its room type is not connected to a channel, or the property’s calendar comes from a connected source and a pool of the room type has no count of its own that night. It is the value before Supahost holds a property closed on the channel, which sends 0 instead, and before the channel closes tonight at its own cut-off. What the channel has is in include=channel. |
data[].holds.reflectableAfter | string (date-time) | null | Required | The earliest reflectedFromObservedAt among heldNights with reflected: false, or null when no such night has one. Sending the same count again with a later observedAt can change what the channel receives only when that observedAt is later than this, and only on a property whose calendar you write through the API (elsewhere the write is refused). On a closed night, or one already at 0 after the held nights that stay off, it changes nothing the channel receives: Supahost stores the new time and sends nothing. |
data[].holds.heldNights | object[] | Required | Each reservation holding units on this pool night, oldest allocation first. Empty where nothing comes off for held nights: a pool whose count no connected source sets, or a night without its own count. |
data[].holds.heldNights[].reservationId | string | Required | The reservation that holds units on this pool night. |
data[].holds.heldNights[].status | 'tentative' | 'confirmed' | Required | Reservation status. Cancelled reservations hold nothing and are not listed. |
data[].holds.heldNights[].units | integer | Required | Units the reservation holds on this pool night. |
data[].holds.heldNights[].allocatedAt | string (date-time) | Required | When the reservation got this pool night. |
data[].holds.heldNights[].confirmationRecordedAt | string (date-time) | null | Required | When Supahost recorded the newest confirmation from the connected source that covers this night, or null when there is none. |
data[].holds.heldNights[].reflected | boolean | Required | Whether your count already includes this night, so nothing comes off for it. |
data[].holds.heldNights[].reason | 'no_observation' | 'count_changed_since_observation' | 'several_rooms' | 'no_confirmation' | 'confirmed_before_allocation' | 'confirmed_after_observation' | 'null' | Required | Why the night still comes off your count, the first that applies: no_observation (no read time stands behind the count), count_changed_since_observation (the stored count is no longer the count that read time belongs to), several_rooms (the reservation holds more than one room that night), no_confirmation, confirmed_before_allocation (a confirmation is from before the reservation got this pool night), confirmed_after_observation (a confirmation is not earlier than the read time). Null when reflected is true. |
data[].holds.heldNights[].reflectedFromObservedAt | string (date-time) | null | Required | The latest observedAt that still leaves this night off your count: sent with the same count, an observedAt later than this counts the night as included. It is the confirmation time plus the 2 minutes Supahost takes off every observedAt. Null when no read time can include the night: the reservation holds more than one room that night, it has no confirmation, or a confirmation is from before it got this pool night. reason names only the first cause, so this can be null under no_observation or count_changed_since_observation too. |
data[].ratePlanId | string | Required | Rate plan ID this row describes. |
data[].maxStay | integer | Required | Maximum stay; 0 means unlimited. Defaults to 14 when no night exists. |
data[].closedToArrival | boolean | Required | Arrival restriction; defaults to false when no night exists. |
data[].closedToDeparture | boolean | Required | Departure restriction; defaults to false when no night exists. |
GET /properties/{propertyId}/channel-sync
Read the channel sync state of one property in one object. This endpoint requires the calendar:read scope. It covers every night from today in the property time zone. Reading it queues or sends nothing.
state is not_sent when Supahost sends nothing for the property, then held when it holds the nights closed, then failing when a night failed, then pending when a change is on its way, else synced. availability and restrictions each have their own state, the number of changes Supahost is sending now (pendingDeliveries), the nights whose last change failed (failedNights), and when the channel last confirmed a change (lastConfirmedAt).
firstIssueDate and lastIssueDate are the first and last nights that are pending or failed. Read the calendar with include=channel between those dates to see each night. The calendar read spans at most 92 days, so a wide window takes more than one read.
hold is set while Supahost holds every night closed on the channel because it could not confirm the property calendar there. retriesExhausted is true when Supahost stopped retrying on its own. Then a person must reconnect the property or ask support.
lastCalendarWriteAt is when Supahost last accepted a calendar write for the property through the API (PUT /properties/{propertyId}/calendar without validateOnly), or null when it recorded none. A write that changed nothing counts. A write refused as a whole, such as a 400 or 409, and a replay of an Idempotency-Key do not. Writes accepted before 2026-11-12 are included only when they sent an available count. If your system writes the calendar, use it to check that your writer is still sending: when it stops, Supahost keeps the last values you sent and the channel keeps selling them.
| Field | Type | Required | Description |
|---|---|---|---|
propertyId | string (uuid) | Required | Property UUID. |
| Field | Type | Required | Description |
|---|---|---|---|
data | ChannelSync | Required | The channel sync state of the property. |
meta | object | Required | Response metadata. |
meta.requestId | string | Required | Support identifier for this request. |
data.propertyId | string | Required | Property UUID. |
data.state | 'synced' | 'pending' | 'failing' | 'held' | 'not_sent' | Required | not_sent when nothing is sent, else held when the nights are held closed, else failing when a night failed, else pending when a change is on its way, else synced. |
data.reason | string | null | Required | Why nothing is sent (property_inactive or not_connected), or null. |
data.hold | object | null | Required | Supahost holds every night closed on the channel (availability 0), or null. |
data.hold.reason | 'activation_unconfirmed' | Conditional | Required when hold is an object. Why Supahost holds the nights closed. |
data.hold.since | string (date-time) | Conditional | Required when hold is an object. When the hold started. |
data.hold.retriesExhausted | boolean | Conditional | Required when hold is an object. True when Supahost stopped retrying on its own. A person must reconnect the property or ask support. |
data.availability | object | Required | Room type availability. |
data.availability.state | 'synced' | 'pending' | 'failing' | 'held' | 'not_sent' | Required | synced: nothing outstanding. pending: changes are on their way. failing: some nights failed. held: the nights are held closed. not_sent: nothing is sent. |
data.availability.pendingDeliveries | integer | Required | Changes Supahost is sending or retrying now. |
data.availability.failedNights | integer | Required | Nights from today whose last change failed and that Supahost will not retry. |
data.availability.firstIssueDate | string (date) | null | Required | First night from today that is pending or failed, or null. |
data.availability.lastIssueDate | string (date) | null | Required | Last night that is pending or failed, or null. Read the calendar with include=channel between the two dates. |
data.availability.lastConfirmedAt | string (date-time) | null | Required | When the channel last confirmed a change of this kind, or null. |
data.restrictions | object | Required | Rates and stay rules. |
data.restrictions.state | 'synced' | 'pending' | 'failing' | 'held' | 'not_sent' | Required | synced: nothing outstanding. pending: changes are on their way. failing: some nights failed. held: the nights are held closed. not_sent: nothing is sent. |
data.restrictions.pendingDeliveries | integer | Required | Changes Supahost is sending or retrying now. |
data.restrictions.failedNights | integer | Required | Nights from today whose last change failed and that Supahost will not retry. |
data.restrictions.firstIssueDate | string (date) | null | Required | First night from today that is pending or failed, or null. |
data.restrictions.lastIssueDate | string (date) | null | Required | Last night that is pending or failed, or null. Read the calendar with include=channel between the two dates. |
data.restrictions.lastConfirmedAt | string (date-time) | null | Required | When the channel last confirmed a change of this kind, or null. |
data.checkedAt | string (date-time) | Required | When Supahost read this state. Supahost reads its own records, not the channel. |
data.lastCalendarWriteAt | string (date-time) | null | Required | When Supahost last accepted a calendar write for this property through the API (PUT /properties/{propertyId}/calendar, not validateOnly), or null when it recorded none. A write that changed nothing counts; a write refused as a whole (for example 400 or 409) and an Idempotency-Key replay do not. Writes accepted before 2026-11-12 are included only when they sent an available count. Use it to check that your writer is still sending. |
Reservation endpoints require the reservations:read scope. Required response fields are always present; nullable fields include null in their type.
items lists the booked room lines of the reservation. Line totals use the currency recorded for the booked nights. An item without a recorded price returns total null, including older cancelled items.
An imported reservation without a known guest price also returns total null. A free stay returns an amount of "0.00". Owner payouts do not replace guest prices.
Money is a currency amount with two decimals, such as "325.00", and a 3-letter currency code. Supahost converts it for you. Send amount as a string or a number. amountMinor still works and will be removed.
GET /reservations
Return one stable page of reservations.
| Field | Type | Required | Description |
|---|---|---|---|
Authorization | string | Required | Send Bearer $SUPAHOST_API_KEY. |
| Field | Type | Required | Description |
|---|---|---|---|
limit | integer | Optional | Records per page, from 1 through 200. The default is 100. |
cursor | string | Optional | Send meta.page.nextCursor without changing any other filter. |
updatedAfter | string (date-time) | Optional | Return records changed after this ISO 8601 date and time. |
updated_after | string (date-time) | Optional | Deprecated: use updatedAfter. |
propertyId | string (uuid) | Optional | Return reservations for one public property UUID. |
property_id | string (uuid) | Optional | Deprecated: use propertyId. |
arrivalFrom | string (date) | Optional | Return arrivals on or after this YYYY-MM-DD date. |
arrival_from | string (date) | Optional | Deprecated: use arrivalFrom. |
arrivalTo | string (date) | Optional | Return arrivals on or before this YYYY-MM-DD date. |
arrival_to | string (date) | Optional | Deprecated: use arrivalTo. |
reference | string | Optional | Return only the reservation whose reference is exactly this value, whatever its status. |
| Field | Type | Required | Description |
|---|---|---|---|
data | Reservation[] | Required | A stable page of reservation records. |
meta | object | Required | Response metadata. |
meta.requestId | string | Required | Support identifier for this request. |
meta.page | object | Required | Cursor pagination state. |
meta.page.hasMore | boolean | Required | Whether another page is available. |
meta.page.limit | integer | Required | The page size applied to this response. |
meta.page.nextCursor | string | null | Required | The cursor for the next page, or null when the page is final. |
meta.page.snapshotAt | string (date-time) | Required | The stable read boundary shared by every page in the cursor chain. |
data[].id | string | Required | Stable reservation ID. |
data[].confirmationCode | string | Required | Guest-facing confirmation code. |
data[].status | 'pending' | 'confirmed' | 'in_house' | 'completed' | 'cancelled' | Required | Reservation lifecycle status. |
data[].updatedAt | string (date-time) | Required | Last reservation change time. |
data[].guest | object | Required | Guest contact summary. |
data[].guest.name | string | Required | Guest name. |
data[].guest.email | string | null | Required | Guest email address, or null. |
data[].guest.phone | string | null | Required | Guest phone number, or null. |
data[].property | object | Required | Reserved property summary. |
data[].property.id | string | Required | Public property UUID. |
data[].property.name | string | Required | Property name. |
data[].stay | object | Required | Stay dates and length. |
data[].stay.arrivalDate | string (date) | Required | Arrival date in YYYY-MM-DD format. |
data[].stay.departureDate | string (date) | Required | Departure date in YYYY-MM-DD format. |
data[].stay.nights | integer | Required | Number of nights. |
data[].occupancy | object | Required | Guest and room counts. |
data[].occupancy.adults | integer | Required | Adult count. |
data[].occupancy.children | integer | Required | Child count. |
data[].occupancy.rooms | integer | Required | Booked room quantity. |
data[].total | object | null | Required | Reservation total. Null when the imported guest price is unknown. |
data[].total.amount | string | Conditional | Required when total is an object. Amount in the currency unit with two decimals (325.00). |
data[].total.amountMinor | string | Conditional | Required when total is an object. Deprecated: the same amount in hundredths (32500). Read amount. |
data[].total.currency | string | Conditional | Required when total is an object. Three-letter currency code. |
data[].source | object | Required | Reservation origin. |
data[].source.type | 'direct' | 'channel' | Required | Whether the reservation was direct or arrived from a channel. |
data[].source.channel | string | Conditional | Required when source.type is channel. |
data[].items | object[] | Required | Booked room lines with per-line totals from their nightly rates. |
data[].items[].id | string | Required | Stable reservation item ID. |
data[].items[].status | 'pending' | 'confirmed' | 'cancelled' | Required | Item lifecycle status. |
data[].items[].checkInDate | string (date) | Required | Check-in date in YYYY-MM-DD format. |
data[].items[].checkOutDate | string (date) | Required | Check-out date in YYYY-MM-DD format. |
data[].items[].nights | integer | Required | Number of nights. |
data[].items[].quantity | integer | Required | Booked room quantity. |
data[].items[].adults | integer | Required | Adult count. |
data[].items[].children | integer | Required | Child count. |
data[].items[].inventoryPoolId | string | Required | Inventory pool the item books. |
data[].items[].ratePlanId | string | Required | Rate plan the item is priced with. |
data[].items[].total | object | null | Required | Booked item total in the recorded currency; null when the price is unknown, including older cancelled items. |
data[].items[].total.amount | string | Conditional | Required when total is an object. Amount in the currency unit with two decimals (325.00). |
data[].items[].total.amountMinor | string | Conditional | Required when total is an object. Deprecated: the same amount in hundredths (32500). Read amount. |
data[].items[].total.currency | string | Conditional | Required when total is an object. Three-letter currency code. |
data[].reference | string | null | Optional | Your own identifier for the booking, set when you create or replace it through this API, or null. Channel booking codes are not references. Omitted only in older idempotent replay snapshots. |
GET /reservations/{reservationId}
Return one reservation from the API key workspace.
The response includes an ETag header that names this version of the reservation. Send it in If-None-Match to get 304 with no body when the reservation did not change. The tag names the whole response, so it also changes when a derived value, such as a line in items, changes.
| Field | Type | Required | Description |
|---|---|---|---|
Authorization | string | Required | Send Bearer $SUPAHOST_API_KEY. |
If-None-Match | string | Optional | The ETag from your last read. Returns 304 with no body when the reservation did not change. |
| Field | Type | Required | Description |
|---|---|---|---|
reservationId | string (uuid) | Required | Reservation UUID. |
| Field | Type | Required | Description |
|---|---|---|---|
data | Reservation | Required | The requested reservation. |
meta | object | Required | Response metadata. |
meta.requestId | string | Required | Support identifier for this request. |
data.id | string | Required | Stable reservation ID. |
data.confirmationCode | string | Required | Guest-facing confirmation code. |
data.status | 'pending' | 'confirmed' | 'in_house' | 'completed' | 'cancelled' | Required | Reservation lifecycle status. |
data.updatedAt | string (date-time) | Required | Last reservation change time. |
data.guest | object | Required | Guest contact summary. |
data.guest.name | string | Required | Guest name. |
data.guest.email | string | null | Required | Guest email address, or null. |
data.guest.phone | string | null | Required | Guest phone number, or null. |
data.property | object | Required | Reserved property summary. |
data.property.id | string | Required | Public property UUID. |
data.property.name | string | Required | Property name. |
data.stay | object | Required | Stay dates and length. |
data.stay.arrivalDate | string (date) | Required | Arrival date in YYYY-MM-DD format. |
data.stay.departureDate | string (date) | Required | Departure date in YYYY-MM-DD format. |
data.stay.nights | integer | Required | Number of nights. |
data.occupancy | object | Required | Guest and room counts. |
data.occupancy.adults | integer | Required | Adult count. |
data.occupancy.children | integer | Required | Child count. |
data.occupancy.rooms | integer | Required | Booked room quantity. |
data.total | object | null | Required | Reservation total. Null when the imported guest price is unknown. |
data.total.amount | string | Conditional | Required when total is an object. Amount in the currency unit with two decimals (325.00). |
data.total.amountMinor | string | Conditional | Required when total is an object. Deprecated: the same amount in hundredths (32500). Read amount. |
data.total.currency | string | Conditional | Required when total is an object. Three-letter currency code. |
data.source | object | Required | Reservation origin. |
data.source.type | 'direct' | 'channel' | Required | Whether the reservation was direct or arrived from a channel. |
data.source.channel | string | Conditional | Required when source.type is channel. |
data.items | object[] | Required | Booked room lines with per-line totals from their nightly rates. |
data.items[].id | string | Required | Stable reservation item ID. |
data.items[].status | 'pending' | 'confirmed' | 'cancelled' | Required | Item lifecycle status. |
data.items[].checkInDate | string (date) | Required | Check-in date in YYYY-MM-DD format. |
data.items[].checkOutDate | string (date) | Required | Check-out date in YYYY-MM-DD format. |
data.items[].nights | integer | Required | Number of nights. |
data.items[].quantity | integer | Required | Booked room quantity. |
data.items[].adults | integer | Required | Adult count. |
data.items[].children | integer | Required | Child count. |
data.items[].inventoryPoolId | string | Required | Inventory pool the item books. |
data.items[].ratePlanId | string | Required | Rate plan the item is priced with. |
data.items[].total | object | null | Required | Booked item total in the recorded currency; null when the price is unknown, including older cancelled items. |
data.items[].total.amount | string | Conditional | Required when total is an object. Amount in the currency unit with two decimals (325.00). |
data.items[].total.amountMinor | string | Conditional | Required when total is an object. Deprecated: the same amount in hundredths (32500). Read amount. |
data.items[].total.currency | string | Conditional | Required when total is an object. Three-letter currency code. |
data.reference | string | null | Optional | Your own identifier for the booking, set when you create or replace it through this API, or null. Channel booking codes are not references. Omitted only in older idempotent replay snapshots. |
POST /reservations
Create one direct reservation. This endpoint requires the reservations:write scope. The body mirrors the read row: guest, stay, occupancy, and one items line with the ratePlanId to book.
The rate plan, its inventory pool, and the property must be active, and a channel-mapped (OTA) rate plan cannot take a direct booking. The total prices from the plan’s base rate for every night. Inventory allocates inside the same transaction and the availability change queues to the channel sync outbox asynchronously. Owner (entitlement) inventory cannot be booked through this endpoint.
Capacity failures return 400 insufficient_inventory. Send an Idempotency-Key header to make retries safe: a repeated POST with the same key and the same payload returns the original reservation instead of booking twice; the same key with a different payload fails with 409 idempotency_key_reused.
A reference also makes the create safe to repeat, with no time limit. If a reservation already has the reference, nothing is booked and no inventory is checked. When its guest, stay dates, occupancy and rate plan match the request, the answer is 200 with that reservation, also when it was cancelled since. When they differ, the answer is 409 reference_in_use. The Idempotency-Key is checked first. Find a booking by its reference with GET /reservations?reference=. Channel booking codes are never references.
| Field | Type | Required | Description |
|---|---|---|---|
Authorization | string | Required | Send Bearer $SUPAHOST_API_KEY. |
Idempotency-Key | string | Optional | 1 to 200 characters. Makes retries safe. |
| Field | Type | Required | Description |
|---|---|---|---|
guest.name | string | Required | Guest name, 2 to 120 characters. |
guest.email | string | null | Required | Guest email address, or null. |
stay.arrivalDate | string (date) | Required | Arrival date in YYYY-MM-DD format. |
stay.departureDate | string (date) | Required | Departure date in YYYY-MM-DD format, 1 to 365 nights after arrival. |
occupancy.adults | integer | Required | Adult count, 1 to 500. Adults plus children must fit the room capacity. |
occupancy.children | integer | Required | Child count, 0 to 500. |
occupancy.rooms | integer | Required | Booked room quantity, 1 to 100. |
items[].ratePlanId | string | Required | Rate plan the line books. Exactly one line; other read fields on items are ignored. |
reference | string | null | Optional | Your own identifier for the booking, 1 to 128 characters, unique in the workspace. On replace, omit it to keep the stored value and send null to clear it. |
| Field | Type | Required | Description |
|---|---|---|---|
data | Reservation | Required | The stored reservation after the write. |
meta | object | Required | Response metadata. |
meta.requestId | string | Required | Support identifier for this request. |
data.id | string | Required | Stable reservation ID. |
data.confirmationCode | string | Required | Guest-facing confirmation code. |
data.status | 'pending' | 'confirmed' | 'in_house' | 'completed' | 'cancelled' | Required | Reservation lifecycle status. |
data.updatedAt | string (date-time) | Required | Last reservation change time. |
data.guest | object | Required | Guest contact summary. |
data.guest.name | string | Required | Guest name. |
data.guest.email | string | null | Required | Guest email address, or null. |
data.guest.phone | string | null | Required | Guest phone number, or null. |
data.property | object | Required | Reserved property summary. |
data.property.id | string | Required | Public property UUID. |
data.property.name | string | Required | Property name. |
data.stay | object | Required | Stay dates and length. |
data.stay.arrivalDate | string (date) | Required | Arrival date in YYYY-MM-DD format. |
data.stay.departureDate | string (date) | Required | Departure date in YYYY-MM-DD format. |
data.stay.nights | integer | Required | Number of nights. |
data.occupancy | object | Required | Guest and room counts. |
data.occupancy.adults | integer | Required | Adult count. |
data.occupancy.children | integer | Required | Child count. |
data.occupancy.rooms | integer | Required | Booked room quantity. |
data.total | object | null | Required | Reservation total. Null when the imported guest price is unknown. |
data.total.amount | string | Conditional | Required when total is an object. Amount in the currency unit with two decimals (325.00). |
data.total.amountMinor | string | Conditional | Required when total is an object. Deprecated: the same amount in hundredths (32500). Read amount. |
data.total.currency | string | Conditional | Required when total is an object. Three-letter currency code. |
data.source | object | Required | Reservation origin. |
data.source.type | 'direct' | 'channel' | Required | Whether the reservation was direct or arrived from a channel. |
data.source.channel | string | Conditional | Required when source.type is channel. |
data.items | object[] | Required | Booked room lines with per-line totals from their nightly rates. |
data.items[].id | string | Required | Stable reservation item ID. |
data.items[].status | 'pending' | 'confirmed' | 'cancelled' | Required | Item lifecycle status. |
data.items[].checkInDate | string (date) | Required | Check-in date in YYYY-MM-DD format. |
data.items[].checkOutDate | string (date) | Required | Check-out date in YYYY-MM-DD format. |
data.items[].nights | integer | Required | Number of nights. |
data.items[].quantity | integer | Required | Booked room quantity. |
data.items[].adults | integer | Required | Adult count. |
data.items[].children | integer | Required | Child count. |
data.items[].inventoryPoolId | string | Required | Inventory pool the item books. |
data.items[].ratePlanId | string | Required | Rate plan the item is priced with. |
data.items[].total | object | null | Required | Booked item total in the recorded currency; null when the price is unknown, including older cancelled items. |
data.items[].total.amount | string | Conditional | Required when total is an object. Amount in the currency unit with two decimals (325.00). |
data.items[].total.amountMinor | string | Conditional | Required when total is an object. Deprecated: the same amount in hundredths (32500). Read amount. |
data.items[].total.currency | string | Conditional | Required when total is an object. Three-letter currency code. |
data.reference | string | null | Optional | Your own identifier for the booking, set when you create or replace it through this API, or null. Channel booking codes are not references. Omitted only in older idempotent replay snapshots. |
PUT /reservations/{reservationId}
Replace the writable fields of one direct reservation. This endpoint requires the reservations:write scope. The body is the same shape as the create body; the stored allocation moves to the new dates, rate plan, and room quantity, and the total reprices.
Channel reservations must be changed in the connected channel (400 channel_managed). Cancelled, started, or completed reservations cannot be changed, and reservations with assigned units or multiple item records need the dashboard.
A reference that another reservation holds fails with 409 reference_in_use.
To avoid replacing a change that you did not see, send the ETag from your last read in If-Match. If the reservation changed since, the response is 412 precondition_failed and nothing is written. Read the reservation again and repeat the change. Without If-Match, the replacement always applies. A 412 can also come from a derived value that moved, such as a line in items: read the reservation again and repeat the change; it is not an error to show.
| Field | Type | Required | Description |
|---|---|---|---|
Authorization | string | Required | Send Bearer $SUPAHOST_API_KEY. |
Idempotency-Key | string | Optional | 1 to 200 characters. Makes retries safe. |
If-Match | string | Optional | The ETag from your last read, quotes included. Returns 412 precondition_failed when the reservation changed since, and 400 when the value is not a tag. |
| Field | Type | Required | Description |
|---|---|---|---|
reservationId | string (uuid) | Required | Reservation UUID. |
| Field | Type | Required | Description |
|---|---|---|---|
guest.name | string | Required | Guest name, 2 to 120 characters. |
guest.email | string | null | Required | Guest email address, or null. |
stay.arrivalDate | string (date) | Required | Arrival date in YYYY-MM-DD format. |
stay.departureDate | string (date) | Required | Departure date in YYYY-MM-DD format, 1 to 365 nights after arrival. |
occupancy.adults | integer | Required | Adult count, 1 to 500. Adults plus children must fit the room capacity. |
occupancy.children | integer | Required | Child count, 0 to 500. |
occupancy.rooms | integer | Required | Booked room quantity, 1 to 100. |
items[].ratePlanId | string | Required | Rate plan the line books. Exactly one line; other read fields on items are ignored. |
reference | string | null | Optional | Your own identifier for the booking, 1 to 128 characters, unique in the workspace. On replace, omit it to keep the stored value and send null to clear it. |
| Field | Type | Required | Description |
|---|---|---|---|
data | Reservation | Required | The stored reservation after the write. |
meta | object | Required | Response metadata. |
meta.requestId | string | Required | Support identifier for this request. |
data.id | string | Required | Stable reservation ID. |
data.confirmationCode | string | Required | Guest-facing confirmation code. |
data.status | 'pending' | 'confirmed' | 'in_house' | 'completed' | 'cancelled' | Required | Reservation lifecycle status. |
data.updatedAt | string (date-time) | Required | Last reservation change time. |
data.guest | object | Required | Guest contact summary. |
data.guest.name | string | Required | Guest name. |
data.guest.email | string | null | Required | Guest email address, or null. |
data.guest.phone | string | null | Required | Guest phone number, or null. |
data.property | object | Required | Reserved property summary. |
data.property.id | string | Required | Public property UUID. |
data.property.name | string | Required | Property name. |
data.stay | object | Required | Stay dates and length. |
data.stay.arrivalDate | string (date) | Required | Arrival date in YYYY-MM-DD format. |
data.stay.departureDate | string (date) | Required | Departure date in YYYY-MM-DD format. |
data.stay.nights | integer | Required | Number of nights. |
data.occupancy | object | Required | Guest and room counts. |
data.occupancy.adults | integer | Required | Adult count. |
data.occupancy.children | integer | Required | Child count. |
data.occupancy.rooms | integer | Required | Booked room quantity. |
data.total | object | null | Required | Reservation total. Null when the imported guest price is unknown. |
data.total.amount | string | Conditional | Required when total is an object. Amount in the currency unit with two decimals (325.00). |
data.total.amountMinor | string | Conditional | Required when total is an object. Deprecated: the same amount in hundredths (32500). Read amount. |
data.total.currency | string | Conditional | Required when total is an object. Three-letter currency code. |
data.source | object | Required | Reservation origin. |
data.source.type | 'direct' | 'channel' | Required | Whether the reservation was direct or arrived from a channel. |
data.source.channel | string | Conditional | Required when source.type is channel. |
data.items | object[] | Required | Booked room lines with per-line totals from their nightly rates. |
data.items[].id | string | Required | Stable reservation item ID. |
data.items[].status | 'pending' | 'confirmed' | 'cancelled' | Required | Item lifecycle status. |
data.items[].checkInDate | string (date) | Required | Check-in date in YYYY-MM-DD format. |
data.items[].checkOutDate | string (date) | Required | Check-out date in YYYY-MM-DD format. |
data.items[].nights | integer | Required | Number of nights. |
data.items[].quantity | integer | Required | Booked room quantity. |
data.items[].adults | integer | Required | Adult count. |
data.items[].children | integer | Required | Child count. |
data.items[].inventoryPoolId | string | Required | Inventory pool the item books. |
data.items[].ratePlanId | string | Required | Rate plan the item is priced with. |
data.items[].total | object | null | Required | Booked item total in the recorded currency; null when the price is unknown, including older cancelled items. |
data.items[].total.amount | string | Conditional | Required when total is an object. Amount in the currency unit with two decimals (325.00). |
data.items[].total.amountMinor | string | Conditional | Required when total is an object. Deprecated: the same amount in hundredths (32500). Read amount. |
data.items[].total.currency | string | Conditional | Required when total is an object. Three-letter currency code. |
data.reference | string | null | Optional | Your own identifier for the booking, set when you create or replace it through this API, or null. Channel booking codes are not references. Omitted only in older idempotent replay snapshots. |
Properties, room types, and rate plans carry a sync object. It tells you whether the channel manager has the latest version of the record.
synced: the channel has the current record.pending: a change is on its way to the channel, or Supahost is retrying one that failed.pendingSinceis when the change was queued. Until it completes, writes to the record fail with409sync_in_progress.failed: the change failed and Supahost will not retry it. A person must resolve it in Supahost. Until then, writes to the record fail with409sync_failed.not_applicable: the record does not sync to a channel. For example, the property is a draft or has no channel connection.
sync.state is the answer a write to the record gets for the record's own sync. pending and failed are exactly the states in which that write fails with sync_in_progress or sync_failed, with the same reason. synced and not_applicable mean the record's own sync does not block a write.
A rate plan's sync shows only the plan's own sync, but a write to the plan can also be refused by the sync of its property or room type, which blockedBy names.
reason tells you why a sync is failing, and failedAt tells you when the last attempt failed. Both are null when nothing failed. A new reason can appear, so treat an unknown one as other.
channel_rejected: The channel refused the change.channel_unreachable: Supahost could not reach the channel manager, or the channel manager asked it to slow down.confirmation_unavailable: Supahost could not confirm that the channel saved the change.connection_problem: The channel connection needs attention, for example a new credential.setup_incomplete: The channel setup of the property is not finished.other: Another cause. Ask a person in your workspace to look at the record in Supahost.
To find the records that need attention, send ?sync=failed or ?sync=failed,pending to the room type or rate plan list. The filter uses the same sync.state the records show, so every record on a filtered page has a sync.state in the filter. The filter is part of the cursor, so keep it on every page. A cursor from a different filter returns invalid_cursor.
Test keys read sandbox records, which sync to no channel. Their sync.state is always not_applicable, so a sync filter returns no sandbox records.
updatedAt and updatedAfter track the record itself, not its sync state. A sync that starts, fails, or completes does not change updatedAt, so an updatedAfter read does not return the record again. Use the sync filter to watch sync state.
Change: a write that meets a failed sync now fails with 409 sync_failed, with retryable no and no Retry-After header. Before, it failed with sync_in_progress and Retry-After: 30. If your client retries every 409 after Retry-After, stop when there is no Retry-After header, and ask a person to resolve the sync.
A calendar write changes Supahost first. Supahost then sends the change to the channel and checks that the channel saved it. The calendar reads with include=channel and the channel sync summary show where that stands. They read Supahost records only. They never queue, send or retry anything.
A night is one room type (availability) or one rate plan (restrictions) on one date. Each night has one state. Supahost checks the causes in this order and reports the first that applies:
not_sent: the property has no linked listing, has no live channel connection, the room type or rate plan has no channel mapping, the rate plan follows its parent plan, the pool has no active rate plan, the night is past, or nothing has written the night yet (awaiting_feed).held(availability only): Supahost holds the night closed on the channel.valueis 0, andchangedAtis when the hold started.pending: the newest change for the night is on its way, or Supahost is retrying it.failed: the newest change failed, Supahost will not retry it, and no later change reached the channel.closed_by_channel: the channel closed tonight at its own same-day cut-off. Supahost expects this and does not send the night again.synced: nothing else applies.
States: synced (Nothing is outstanding. The channel confirmed the last change, or no change was needed. Supahost does not read the channel again to report this.) pending (A change is on its way to the channel, or Supahost is retrying one.) failed (The last change failed and Supahost will not retry it. A person must resolve it in Supahost.) held (Supahost holds the night closed on the channel (availability 0) until it can confirm the property calendar there.) closed_by_channel (The channel closed tonight at its own same-day cut-off. Supahost expects this and does not send the night again.) not_sent (Supahost does not send this night to the channel. reason says why.)
synced means nothing is outstanding: the channel confirmed the last change, or no change was needed. It is not a new read of the channel. Supahost cannot see a change that someone made directly on the channel, so such a night still reads synced.
A failure stays failed until a later change for the night reaches the channel, the night passes, or a person in your workspace resolves the problem in Supahost. When a person resolves it, those nights read synced again.
The state covers every change to the night, from any source: your writes, bookings and the Supahost calendar. The question is what the channel has, whoever wrote it. There is no receipt for one write: one write can become several deliveries, and a later change can replace an earlier one before it is sent.
On the property calendar, restrictions sums up the pool's active rate plans: failed when one failed, else pending when one is pending, else synced when one reaches the channel, else not_sent.
value is the availability Supahost holds for the channel on the night: the total for the room type, after held nights and any close-out. It can differ from availableUnits, which is one inventory pool. observedValue appears only when a read of the channel showed a different number.
reason tells you why a night is not synced. A new reason can appear, so treat an unknown one as other.
channel_rejected: The channel refused the change.channel_mismatch: The channel accepted the change, but a later read showed a different value.channel_unreachable: Supahost could not reach the channel manager, or the channel manager asked it to slow down.confirmation_unavailable: Supahost could not confirm that the channel saved the change.connection_problem: The channel connection needs attention, for example a new credential.closed_by_channel_cutoff: The channel closed tonight at its own same-day cut-off.activation_unconfirmed: The property came back on the channel and Supahost could not confirm its calendar there, so it holds the nights closed.property_inactive: The property has no linked listing, so Supahost sends nothing to the channel.not_connected: The property, room type or rate plan has no channel connection or mapping.derived_rate_plan: The rate plan follows its parent plan. The channel derives it, so Supahost does not send it.no_rate_plan: The pool has no active rate plan to carry rates and stay rules.past_night: The night is before today in the property time zone.awaiting_value: The night has an available count and no rate for this rate plan, or a rate and no count. On a property whose calendar a connected source supplies, the channel sells a night only with both. Send the missing value.awaiting_feed: Nothing has written this night yet, so Supahost has nothing to send for it. Write it with a calendar write. The reason keeps the name it had when a supplier feed wrote the calendar.other: Another cause. Ask a person in your workspace to look at the property in Supahost.
Test keys read sandbox properties, which sync to no channel. Their nights are not_sent with not_connected.
A date block takes quantity units of one inventory pool out of the calendar for a range of nights, with a reason: a repair, an owner visit, a hold. It is the block that the dashboard calendar creates with Block dates. Reading needs calendar:read. Writing needs calendar:write, the scope that also writes nightly availability.
Dates are calendar dates in the property time zone. startsOn is the first blocked night. endsOn is the reopen date, exclusive: the first night the units are sellable again, so the last blocked night is the day before. A block spans 1 to 365 nights.
A block never cancels or changes a reservation. A write checks the pool’s base capacity and that every night in the range has enough unreserved inventory left; if a night has not, the response is 400 insufficient_inventory and the detail names the night. Channel availability updates asynchronously. Each write sends a calendar.updated webhook with kind availability_block, over the first to the last blocked night it affects.
An owner stay on an entitlement pool is not a date block. It is never listed, and its ID returns 404.
Test keys cannot create, replace or remove a date block (sandbox_read_only). Their list is an empty page.
GET /properties/{propertyId}/blocks
Return one stable page of the property’s date blocks, ordered by startsOn and then id. With from or to, only the blocks that have a blocked night in that inclusive range. With inventoryPoolId, only that pool’s blocks. An unknown property returns 404.
| Field | Type | Required | Description |
|---|---|---|---|
Authorization | string | Required | Send Bearer $SUPAHOST_API_KEY. |
| Field | Type | Required | Description |
|---|---|---|---|
propertyId | string (uuid) | Required | Property UUID. |
| Field | Type | Required | Description |
|---|---|---|---|
limit | integer | Optional | Records per page, from 1 through 200. The default is 100. |
cursor | string | Optional | Send meta.page.nextCursor without changing any other filter. |
inventoryPoolId | string (uuid) | Optional | Return only the blocks of this inventory pool UUID. |
from | string (date) | Optional | First night of the range, inclusive. A block is returned when any of its blocked nights falls in the range. |
to | string (date) | Optional | Last night of the range, inclusive. from must not be after to. |
| Field | Type | Required | Description |
|---|---|---|---|
data | DateBlock[] | Required | A stable page of date blocks. |
meta | object | Required | Response metadata. |
meta.requestId | string | Required | Support identifier for this request. |
meta.page | object | Required | Cursor pagination state. |
meta.page.hasMore | boolean | Required | Whether another page is available. |
meta.page.limit | integer | Required | The page size applied to this response. |
meta.page.nextCursor | string | null | Required | The cursor for the next page, or null when the page is final. |
meta.page.snapshotAt | string (date-time) | Required | The stable read boundary shared by every page in the cursor chain. |
data[].id | string | Required | The block UUID. |
data[].propertyId | string | Required | The property UUID. |
data[].inventoryPoolId | string | Required | The inventory pool whose units are blocked. |
data[].startsOn | string | Required | The first blocked night, YYYY-MM-DD, in the property time zone. |
data[].endsOn | string | Required | The reopen date, exclusive, YYYY-MM-DD. |
data[].quantity | integer | Required | Units blocked. |
data[].reason | string | Required | Why the units are blocked. |
data[].createdAt | string (date-time) | Required | When the block was created. |
data[].updatedAt | string (date-time) | Required | When the block last changed. |
POST /properties/{propertyId}/blocks
Needs calendar:write, the scope that also writes nightly availability. Create a date block and get 201 with it and its ETag. Send an Idempotency-Key header to make retries safe: a repeated POST with the same key and the same payload returns 200 with the original block and creates nothing new; the same key with a different payload fails with 409 idempotency_key_reused.
inventoryPoolId must name an active pool of this property that is not an entitlement pool, else 400 invalid_reference. A quantity above the pool’s base capacity returns 400 invalid_request on quantity.
| Field | Type | Required | Description |
|---|---|---|---|
Authorization | string | Required | Send Bearer $SUPAHOST_API_KEY. |
Idempotency-Key | string | Optional | 1 to 200 characters. Makes create retries safe. |
| Field | Type | Required | Description |
|---|---|---|---|
propertyId | string (uuid) | Required | Property UUID. |
| Field | Type | Required | Description |
|---|---|---|---|
inventoryPoolId | string | Required | The inventory pool whose units are blocked. It cannot change later. |
startsOn | string | Required | The first blocked night, in the property time zone. |
endsOn | string | Required | The reopen date, exclusive: the first night the units are sellable again. The last blocked night is the day before. |
quantity | integer | Required | Units of the inventory pool to block, 1 to 1000. |
reason | string | Required | Why the units are blocked, 2 to 240 characters. |
curl -X POST "https://supahost.io/api/v1/properties/$PROPERTY_ID/blocks" \
-H "Authorization: Bearer $SUPAHOST_API_KEY" \
-H "Content-Type: application/json" -H "Idempotency-Key: block-repair-1" \
-d '{"inventoryPoolId":"$POOL_ID","startsOn":"2030-10-10","endsOn":"2030-10-13","quantity":1,"reason":"Plumbing repair"}'| Field | Type | Required | Description |
|---|---|---|---|
data | DateBlock | Required | The date block. |
meta | object | Required | Response metadata. |
meta.requestId | string | Required | Support identifier for this request. |
data.id | string | Required | The block UUID. |
data.propertyId | string | Required | The property UUID. |
data.inventoryPoolId | string | Required | The inventory pool whose units are blocked. |
data.startsOn | string | Required | The first blocked night, YYYY-MM-DD, in the property time zone. |
data.endsOn | string | Required | The reopen date, exclusive, YYYY-MM-DD. |
data.quantity | integer | Required | Units blocked. |
data.reason | string | Required | Why the units are blocked. |
data.createdAt | string (date-time) | Required | When the block was created. |
data.updatedAt | string (date-time) | Required | When the block last changed. |
GET /properties/{propertyId}/blocks/{blockId}
Return one date block of the property. A block of another property, another workspace, or an entitlement pool returns 404.
The response includes an ETag header that names this version of the date block. Send it in If-None-Match to get 304 with no body when the date block did not change.
| Field | Type | Required | Description |
|---|---|---|---|
Authorization | string | Required | Send Bearer $SUPAHOST_API_KEY. |
If-None-Match | string | Optional | The ETag from your last read. Returns 304 with no body when the date block did not change. |
| Field | Type | Required | Description |
|---|---|---|---|
propertyId | string (uuid) | Required | Property UUID. |
blockId | string (uuid) | Required | Date block UUID. |
| Field | Type | Required | Description |
|---|---|---|---|
data | DateBlock | Required | The date block. |
meta | object | Required | Response metadata. |
meta.requestId | string | Required | Support identifier for this request. |
data.id | string | Required | The block UUID. |
data.propertyId | string | Required | The property UUID. |
data.inventoryPoolId | string | Required | The inventory pool whose units are blocked. |
data.startsOn | string | Required | The first blocked night, YYYY-MM-DD, in the property time zone. |
data.endsOn | string | Required | The reopen date, exclusive, YYYY-MM-DD. |
data.quantity | integer | Required | Units blocked. |
data.reason | string | Required | Why the units are blocked. |
data.createdAt | string (date-time) | Required | When the block was created. |
data.updatedAt | string (date-time) | Required | When the block last changed. |
PUT /properties/{propertyId}/blocks/{blockId}
Needs calendar:write, the scope that also writes nightly availability. Replace the block’s startsOn, endsOn, quantity and reason. PUT is a full replacement, and the pool cannot change: remove the block and create a new one to block another pool.
A block that has started (its startsOn is today or earlier in the property time zone) keeps its dates; send its current dates with a new quantity or reason. New dates for a started block return 409 date_block_started. A block that has not started can move only to a startsOn after today; an earlier one returns 400 invalid_request on startsOn. A change that needs more inventory than remains returns 400 insufficient_inventory, and the block keeps its old values.
To avoid replacing a change that you did not see, send the ETag from your last read in If-Match. If the date block changed since, the response is 412 precondition_failed and nothing is written. Read the date block again and repeat the change. Without If-Match, the replacement always applies.
| Field | Type | Required | Description |
|---|---|---|---|
Authorization | string | Required | Send Bearer $SUPAHOST_API_KEY. |
If-Match | string | Optional | The ETag from your last read, quotes included. Returns 412 precondition_failed when the date block changed since, and 400 when the value is not a tag. |
| Field | Type | Required | Description |
|---|---|---|---|
propertyId | string (uuid) | Required | Property UUID. |
blockId | string (uuid) | Required | Date block UUID. |
| Field | Type | Required | Description |
|---|---|---|---|
startsOn | string | Required | The first blocked night, in the property time zone. |
endsOn | string | Required | The reopen date, exclusive: the first night the units are sellable again. The last blocked night is the day before. |
quantity | integer | Required | Units of the inventory pool to block, 1 to 1000. |
reason | string | Required | Why the units are blocked, 2 to 240 characters. |
| Field | Type | Required | Description |
|---|---|---|---|
data | DateBlock | Required | The date block. |
meta | object | Required | Response metadata. |
meta.requestId | string | Required | Support identifier for this request. |
data.id | string | Required | The block UUID. |
data.propertyId | string | Required | The property UUID. |
data.inventoryPoolId | string | Required | The inventory pool whose units are blocked. |
data.startsOn | string | Required | The first blocked night, YYYY-MM-DD, in the property time zone. |
data.endsOn | string | Required | The reopen date, exclusive, YYYY-MM-DD. |
data.quantity | integer | Required | Units blocked. |
data.reason | string | Required | Why the units are blocked. |
data.createdAt | string (date-time) | Required | When the block was created. |
data.updatedAt | string (date-time) | Required | When the block last changed. |
DELETE /properties/{propertyId}/blocks/{blockId}
Needs calendar:write, the scope that also writes nightly availability. Remove the block. Its units go back to the calendar for its nights, and the response is 204 with no body. Send the ETag from your last read in If-Match to avoid removing a block that changed since: a block that changed returns 412 precondition_failed and stays.
| Field | Type | Required | Description |
|---|---|---|---|
Authorization | string | Required | Send Bearer $SUPAHOST_API_KEY. |
If-Match | string | Optional | The ETag from your last read, quotes included. Returns 412 precondition_failed when the date block changed since, and 400 when the value is not a tag. |
| Field | Type | Required | Description |
|---|---|---|---|
propertyId | string (uuid) | Required | Property UUID. |
blockId | string (uuid) | Required | Date block UUID. |
Read endpoints require the tasks:read scope; write endpoints require tasks:write. Required response fields are always present; nullable fields include null in their type.
Tasks embed stable IDs only, so list pages never go stale when a name changes: resolve property names through GET /properties. Tasks without a property link return property and reservationId as null. Tasks without an assignee return assignee as null.
Test keys cannot create or update tasks. Writes with a test key return sandbox_read_only.
GET /tasks
Return one stable page of tasks.
| Field | Type | Required | Description |
|---|---|---|---|
Authorization | string | Required | Send Bearer $SUPAHOST_API_KEY. |
| Field | Type | Required | Description |
|---|---|---|---|
limit | integer | Optional | Records per page, from 1 through 200. The default is 100. |
cursor | string | Optional | Send meta.page.nextCursor without changing any other filter. |
updatedAfter | string (date-time) | Optional | Return records changed after this ISO 8601 date and time. |
updated_after | string (date-time) | Optional | Deprecated: use updatedAfter. |
status | 'open' | 'in_progress' | 'completed' | 'cancelled' | 'all' | Optional | Filter by task status. The default is all. |
propertyId | string (uuid) | Optional | Return tasks for one public property UUID. |
property_id | string (uuid) | Optional | Deprecated: use propertyId. |
| Field | Type | Required | Description |
|---|---|---|---|
data | Task[] | Required | A stable page of task records. |
meta | object | Required | Response metadata. |
meta.requestId | string | Required | Support identifier for this request. |
meta.page | object | Required | Cursor pagination state. |
meta.page.hasMore | boolean | Required | Whether another page is available. |
meta.page.limit | integer | Required | The page size applied to this response. |
meta.page.nextCursor | string | null | Required | The cursor for the next page, or null when the page is final. |
meta.page.snapshotAt | string (date-time) | Required | The stable read boundary shared by every page in the cursor chain. |
data[].id | string | Required | Stable task UUID. |
data[].title | string | Required | Task title. |
data[].description | string | null | Required | Task description, or null. |
data[].category | 'cleaning' | 'maintenance' | 'guest' | 'inspection' | 'listing' | 'operations' | Required | Task category. |
data[].priority | 'low' | 'normal' | 'high' | 'urgent' | Required | Task priority. |
data[].status | 'open' | 'in_progress' | 'completed' | 'cancelled' | Required | Task status. |
data[].source | 'manual' | 'automation' | Required | Whether the task was created manually or by an automation rule. |
data[].dueAt | string (date-time) | null | Required | When the task is due, or null. |
data[].property | object | null | Required | Linked property, or null. Resolve names via the properties endpoint. |
data[].property.id | string | Conditional | Required when property is an object. Public property UUID. |
data[].reservationId | string | null | Required | Linked reservation ID, or null. |
data[].assignee | object | null | Required | Assigned workspace member, or null. |
data[].assignee.id | string | Conditional | Required when assignee is an object. Workspace member user ID. |
data[].createdAt | string (date-time) | Required | Task creation time. |
data[].updatedAt | string (date-time) | Required | Last task change time. |
POST /tasks
Create a task. Send an Idempotency-Key header to make retries safe: a repeated POST with the same key and the same payload returns 200 with the original task and creates nothing new; the same key with a different payload fails with 409 idempotency_key_reused.
| Field | Type | Required | Description |
|---|---|---|---|
Authorization | string | Required | Send Bearer $SUPAHOST_API_KEY. |
Idempotency-Key | string | Optional | 1 to 200 characters. Makes create retries safe. |
| Field | Type | Required | Description |
|---|---|---|---|
title | string | Required | Task title, 2 to 200 characters. |
category | 'cleaning' | 'maintenance' | 'guest' | 'inspection' | 'listing' | 'operations' | Required | Task category. |
priority | 'low' | 'normal' | 'high' | 'urgent' | Required | Task priority. |
description | string | null | Optional | Task description, up to 2,000 characters. |
dueAt | string (date-time) | null | Optional | When the task is due; a time-zone offset is allowed. |
propertyId | string | null | Optional | Property UUID. |
reservationId | string | null | Optional | Reservation UUID. Requires propertyId. |
assigneeUserId | string | null | Optional | Assigned workspace member user UUID. |
| Field | Type | Required | Description |
|---|---|---|---|
data | Task | Required | The created task. |
meta | object | Required | Response metadata. |
meta.requestId | string | Required | Support identifier for this request. |
data.id | string | Required | Stable task UUID. |
data.title | string | Required | Task title. |
data.description | string | null | Required | Task description, or null. |
data.category | 'cleaning' | 'maintenance' | 'guest' | 'inspection' | 'listing' | 'operations' | Required | Task category. |
data.priority | 'low' | 'normal' | 'high' | 'urgent' | Required | Task priority. |
data.status | 'open' | 'in_progress' | 'completed' | 'cancelled' | Required | Task status. |
data.source | 'manual' | 'automation' | Required | Whether the task was created manually or by an automation rule. |
data.dueAt | string (date-time) | null | Required | When the task is due, or null. |
data.property | object | null | Required | Linked property, or null. Resolve names via the properties endpoint. |
data.property.id | string | Conditional | Required when property is an object. Public property UUID. |
data.reservationId | string | null | Required | Linked reservation ID, or null. |
data.assignee | object | null | Required | Assigned workspace member, or null. |
data.assignee.id | string | Conditional | Required when assignee is an object. Workspace member user ID. |
data.createdAt | string (date-time) | Required | Task creation time. |
data.updatedAt | string (date-time) | Required | Last task change time. |
GET /tasks/{taskId}
Return one task from the API key workspace.
The response includes an ETag header that names this version of the task. Send it in If-None-Match to get 304 with no body when the task did not change.
| Field | Type | Required | Description |
|---|---|---|---|
Authorization | string | Required | Send Bearer $SUPAHOST_API_KEY. |
If-None-Match | string | Optional | The ETag from your last read. Returns 304 with no body when the task did not change. |
| Field | Type | Required | Description |
|---|---|---|---|
taskId | string (uuid) | Required | Task UUID. |
| Field | Type | Required | Description |
|---|---|---|---|
data | Task | Required | The requested task. |
meta | object | Required | Response metadata. |
meta.requestId | string | Required | Support identifier for this request. |
data.id | string | Required | Stable task UUID. |
data.title | string | Required | Task title. |
data.description | string | null | Required | Task description, or null. |
data.category | 'cleaning' | 'maintenance' | 'guest' | 'inspection' | 'listing' | 'operations' | Required | Task category. |
data.priority | 'low' | 'normal' | 'high' | 'urgent' | Required | Task priority. |
data.status | 'open' | 'in_progress' | 'completed' | 'cancelled' | Required | Task status. |
data.source | 'manual' | 'automation' | Required | Whether the task was created manually or by an automation rule. |
data.dueAt | string (date-time) | null | Required | When the task is due, or null. |
data.property | object | null | Required | Linked property, or null. Resolve names via the properties endpoint. |
data.property.id | string | Conditional | Required when property is an object. Public property UUID. |
data.reservationId | string | null | Required | Linked reservation ID, or null. |
data.assignee | object | null | Required | Assigned workspace member, or null. |
data.assignee.id | string | Conditional | Required when assignee is an object. Workspace member user ID. |
data.createdAt | string (date-time) | Required | Task creation time. |
data.updatedAt | string (date-time) | Required | Last task change time. |
PUT /tasks/{taskId}
Replace one task. PUT is a full replacement: an omitted status resets the task to open.
To avoid replacing a change that you did not see, send the ETag from your last read in If-Match. If the task changed since, the response is 412 precondition_failed and nothing is written. Read the task again and repeat the change. Without If-Match, the replacement always applies.
| Field | Type | Required | Description |
|---|---|---|---|
Authorization | string | Required | Send Bearer $SUPAHOST_API_KEY. |
If-Match | string | Optional | The ETag from your last read, quotes included. Returns 412 precondition_failed when the task changed since, and 400 when the value is not a tag. |
| Field | Type | Required | Description |
|---|---|---|---|
taskId | string (uuid) | Required | Task UUID. |
| Field | Type | Required | Description |
|---|---|---|---|
title | string | Required | Task title, 2 to 200 characters. |
category | 'cleaning' | 'maintenance' | 'guest' | 'inspection' | 'listing' | 'operations' | Required | Task category. |
priority | 'low' | 'normal' | 'high' | 'urgent' | Required | Task priority. |
description | string | null | Optional | Task description, up to 2,000 characters. |
dueAt | string (date-time) | null | Optional | When the task is due; a time-zone offset is allowed. |
propertyId | string | null | Optional | Property UUID. |
reservationId | string | null | Optional | Reservation UUID. Requires propertyId. |
assigneeUserId | string | null | Optional | Assigned workspace member user UUID. |
status | 'open' | 'in_progress' | 'completed' | 'cancelled' | Optional | Full replacement: the default is open. |
| Field | Type | Required | Description |
|---|---|---|---|
data | Task | Required | The requested task. |
meta | object | Required | Response metadata. |
meta.requestId | string | Required | Support identifier for this request. |
data.id | string | Required | Stable task UUID. |
data.title | string | Required | Task title. |
data.description | string | null | Required | Task description, or null. |
data.category | 'cleaning' | 'maintenance' | 'guest' | 'inspection' | 'listing' | 'operations' | Required | Task category. |
data.priority | 'low' | 'normal' | 'high' | 'urgent' | Required | Task priority. |
data.status | 'open' | 'in_progress' | 'completed' | 'cancelled' | Required | Task status. |
data.source | 'manual' | 'automation' | Required | Whether the task was created manually or by an automation rule. |
data.dueAt | string (date-time) | null | Required | When the task is due, or null. |
data.property | object | null | Required | Linked property, or null. Resolve names via the properties endpoint. |
data.property.id | string | Conditional | Required when property is an object. Public property UUID. |
data.reservationId | string | null | Required | Linked reservation ID, or null. |
data.assignee | object | null | Required | Assigned workspace member, or null. |
data.assignee.id | string | Conditional | Required when assignee is an object. Workspace member user ID. |
data.createdAt | string (date-time) | Required | Task creation time. |
data.updatedAt | string (date-time) | Required | Last task change time. |
A price adjustment raises or lowers selling prices by a percent, for every property or one property, and for every night or only the nights between two dates. Read endpoints require the rate-plans:read scope. Write endpoints require both the calendar:write and the rate-plans:write scope: a key with only one of them gets 403 insufficient_scope, and the detail names the missing one.
An adjustment changes the price where a rate is sold: on channels, in direct booking and on reservation nights. It never changes the stored rates. The calendar endpoints keep returning and accepting the stored rate, and removing an adjustment restores the stored prices exactly.
percent is a percent value, not a fraction: 10 is +10% and -5.5 is -5.5%. Adjustments that cover the same night add up: +10% and +5% sell at +15%. A workspace has at most 100 adjustments; a create past that fails with 409 price_adjustment_limit_reached.
startsOn and endsOn are both inclusive nights. endsOn is the last night covered. Either one can be null: an adjustment with no endsOn covers later nights as Supahost sends them to the channels. Nights more than 365 days out are refused.
A create, a change of anything other than name, and a removal queue the new selling prices to the channels for the properties and nights the adjustment covers, and send one calendar.updated webhook with kind rates for each property reached. A change of name alone queues nothing.
Test keys cannot create, change or remove price adjustments. Writes with a test key return sandbox_read_only. A test key reads an empty list.
GET /price-adjustments
Return one stable page of price adjustments, in the order they last changed. With propertyId, the page holds the adjustments for that property and the ones for every property; a property outside the workspace has none.
| Field | Type | Required | Description |
|---|---|---|---|
Authorization | string | Required | Send Bearer $SUPAHOST_API_KEY. |
| Field | Type | Required | Description |
|---|---|---|---|
limit | integer | Optional | Records per page, from 1 through 200. The default is 100. |
cursor | string | Optional | Send meta.page.nextCursor without changing any other filter. |
updatedAfter | string (date-time) | Optional | Return records changed after this ISO 8601 date and time. |
updated_after | string (date-time) | Optional | Deprecated: use updatedAfter. |
propertyId | string (uuid) | Optional | Return the adjustments that apply to one property: those for that property and those for every property. Without it, every adjustment of the workspace is returned. |
| Field | Type | Required | Description |
|---|---|---|---|
data | PriceAdjustment[] | Required | A stable page of price adjustments. |
meta | object | Required | Response metadata. |
meta.requestId | string | Required | Support identifier for this request. |
meta.page | object | Required | Cursor pagination state. |
meta.page.hasMore | boolean | Required | Whether another page is available. |
meta.page.limit | integer | Required | The page size applied to this response. |
meta.page.nextCursor | string | null | Required | The cursor for the next page, or null when the page is final. |
meta.page.snapshotAt | string (date-time) | Required | The stable read boundary shared by every page in the cursor chain. |
data[].id | string | Required | Stable price adjustment UUID. |
data[].name | string | Required | Name of the adjustment, 1 to 80 characters. |
data[].percent | number | Required | Percent change to every selling price it covers, from -50 through 200, at most two decimals, never 0. 10 raises prices 10% (+10%) and -5.5 lowers them 5.5% (-5.5%). |
data[].propertyId | string | null | Required | Property UUID the adjustment covers, or null for every property in the workspace. |
data[].startsOn | string (date) | null | Required | First night covered, inclusive (YYYY-MM-DD), or null for no start. |
data[].endsOn | string (date) | null | Required | Last night covered, inclusive (YYYY-MM-DD; the guest sleeps that night), or null for no end. A night more than 365 days out is refused. |
data[].createdAt | string (date-time) | Required | When the adjustment was created. |
data[].updatedAt | string (date-time) | Required | Last time the adjustment changed. The ETag follows it. |
POST /price-adjustments
Create a price adjustment. Send an Idempotency-Key header to make retries safe: a repeated POST with the same key and the same payload returns 200 with the original adjustment and creates nothing new; the same key with a different payload fails with 409 idempotency_key_reused. A propertyId outside the workspace fails with 400 invalid_reference.
| Field | Type | Required | Description |
|---|---|---|---|
Authorization | string | Required | Send Bearer $SUPAHOST_API_KEY. |
Idempotency-Key | string | Optional | 1 to 200 characters. Makes create retries safe. |
| Field | Type | Required | Description |
|---|---|---|---|
name | string | Required | Name of the adjustment, 1 to 80 characters. |
percent | number | Required | A percent value from -50 through 200, with at most two decimals, never 0. 10 is +10% and -5.5 is -5.5%. |
propertyId | string (uuid) | null | Optional | Property UUID. Omit it, or send null, to cover every property in the workspace. |
startsOn | string (date) | null | Optional | First night covered, inclusive, as YYYY-MM-DD. Omit it, or send null, for no start. |
endsOn | string (date) | null | Optional | Last night covered, inclusive (the night the guest sleeps), as YYYY-MM-DD. Omit it, or send null, for no end. It must be on or after startsOn, and no more than 365 days out. |
| Field | Type | Required | Description |
|---|---|---|---|
data | PriceAdjustment | Required | The created price adjustment. |
meta | object | Required | Response metadata. |
meta.requestId | string | Required | Support identifier for this request. |
data.id | string | Required | Stable price adjustment UUID. |
data.name | string | Required | Name of the adjustment, 1 to 80 characters. |
data.percent | number | Required | Percent change to every selling price it covers, from -50 through 200, at most two decimals, never 0. 10 raises prices 10% (+10%) and -5.5 lowers them 5.5% (-5.5%). |
data.propertyId | string | null | Required | Property UUID the adjustment covers, or null for every property in the workspace. |
data.startsOn | string (date) | null | Required | First night covered, inclusive (YYYY-MM-DD), or null for no start. |
data.endsOn | string (date) | null | Required | Last night covered, inclusive (YYYY-MM-DD; the guest sleeps that night), or null for no end. A night more than 365 days out is refused. |
data.createdAt | string (date-time) | Required | When the adjustment was created. |
data.updatedAt | string (date-time) | Required | Last time the adjustment changed. The ETag follows it. |
GET /price-adjustments/{adjustmentId}
Return one price adjustment from the API key workspace.
The response includes an ETag header that names this version of the price adjustment. Send it in If-None-Match to get 304 with no body when the price adjustment did not change.
| Field | Type | Required | Description |
|---|---|---|---|
Authorization | string | Required | Send Bearer $SUPAHOST_API_KEY. |
If-None-Match | string | Optional | The ETag from your last read. Returns 304 with no body when the price adjustment did not change. |
| Field | Type | Required | Description |
|---|---|---|---|
adjustmentId | string (uuid) | Required | Price adjustment UUID. |
| Field | Type | Required | Description |
|---|---|---|---|
data | PriceAdjustment | Required | The requested price adjustment. |
meta | object | Required | Response metadata. |
meta.requestId | string | Required | Support identifier for this request. |
data.id | string | Required | Stable price adjustment UUID. |
data.name | string | Required | Name of the adjustment, 1 to 80 characters. |
data.percent | number | Required | Percent change to every selling price it covers, from -50 through 200, at most two decimals, never 0. 10 raises prices 10% (+10%) and -5.5 lowers them 5.5% (-5.5%). |
data.propertyId | string | null | Required | Property UUID the adjustment covers, or null for every property in the workspace. |
data.startsOn | string (date) | null | Required | First night covered, inclusive (YYYY-MM-DD), or null for no start. |
data.endsOn | string (date) | null | Required | Last night covered, inclusive (YYYY-MM-DD; the guest sleeps that night), or null for no end. A night more than 365 days out is refused. |
data.createdAt | string (date-time) | Required | When the adjustment was created. |
data.updatedAt | string (date-time) | Required | Last time the adjustment changed. The ETag follows it. |
PATCH /price-adjustments/{adjustmentId}
Change a price adjustment. Send any of the fields; at least one is required. A field you leave out is unchanged, and null clears propertyId, startsOn or endsOn. A new name alone queues no prices. Any other change queues the prices for the nights the old and the new adjustment cover.
To avoid overwriting a change you did not see, send the ETag from your last read in If-Match. If the adjustment changed since, the response is 412 precondition_failed and nothing is written. Read it again and repeat the change. Without If-Match, the request always applies.
| Field | Type | Required | Description |
|---|---|---|---|
Authorization | string | Required | Send Bearer $SUPAHOST_API_KEY. |
If-Match | string | Optional | The ETag from your last read, quotes included. Returns 412 precondition_failed when the price adjustment changed since, and 400 when the value is not a tag. |
| Field | Type | Required | Description |
|---|---|---|---|
adjustmentId | string (uuid) | Required | Price adjustment UUID. |
| Field | Type | Required | Description |
|---|---|---|---|
name | string | Optional | Name of the adjustment, 1 to 80 characters. |
percent | number | Optional | A percent value from -50 through 200, with at most two decimals, never 0. 10 is +10% and -5.5 is -5.5%. |
propertyId | string (uuid) | null | Optional | Property UUID. Send null to cover every property. |
startsOn | string (date) | null | Optional | First night covered, inclusive, as YYYY-MM-DD. Send null for no start. |
endsOn | string (date) | null | Optional | Last night covered, inclusive (the night the guest sleeps), as YYYY-MM-DD. Send null for no end. It must be on or after startsOn, and no more than 365 days out. |
| Field | Type | Required | Description |
|---|---|---|---|
data | PriceAdjustment | Required | The price adjustment after the change. |
meta | object | Required | Response metadata. |
meta.requestId | string | Required | Support identifier for this request. |
data.id | string | Required | Stable price adjustment UUID. |
data.name | string | Required | Name of the adjustment, 1 to 80 characters. |
data.percent | number | Required | Percent change to every selling price it covers, from -50 through 200, at most two decimals, never 0. 10 raises prices 10% (+10%) and -5.5 lowers them 5.5% (-5.5%). |
data.propertyId | string | null | Required | Property UUID the adjustment covers, or null for every property in the workspace. |
data.startsOn | string (date) | null | Required | First night covered, inclusive (YYYY-MM-DD), or null for no start. |
data.endsOn | string (date) | null | Required | Last night covered, inclusive (YYYY-MM-DD; the guest sleeps that night), or null for no end. A night more than 365 days out is refused. |
data.createdAt | string (date-time) | Required | When the adjustment was created. |
data.updatedAt | string (date-time) | Required | Last time the adjustment changed. The ETag follows it. |
DELETE /price-adjustments/{adjustmentId}
Remove a price adjustment. The nights it covered sell at their stored rates again, and Supahost queues those prices to the channels. The response is 204 with no body.
To avoid overwriting a change you did not see, send the ETag from your last read in If-Match. If the adjustment changed since, the response is 412 precondition_failed and nothing is written. Read it again and repeat the change. Without If-Match, the request always applies.
| Field | Type | Required | Description |
|---|---|---|---|
Authorization | string | Required | Send Bearer $SUPAHOST_API_KEY. |
If-Match | string | Optional | The ETag from your last read, quotes included. Returns 412 precondition_failed when the price adjustment changed since, and 400 when the value is not a tag. |
| Field | Type | Required | Description |
|---|---|---|---|
adjustmentId | string (uuid) | Required | Price adjustment UUID. |
Read endpoints require the conversations:read scope; replies require conversations:write. channel names the sales channel (airbnb, vrbo, direct, or other); internal channel manager identifiers are never exposed.
Test keys cannot send replies. Writes with a test key return sandbox_read_only.
GET /conversations
Return one stable page of conversations, newest activity first.
| Field | Type | Required | Description |
|---|---|---|---|
Authorization | string | Required | Send Bearer $SUPAHOST_API_KEY. |
| Field | Type | Required | Description |
|---|---|---|---|
limit | integer | Optional | Records per page, from 1 through 200. The default is 100. |
cursor | string | Optional | Send meta.page.nextCursor without changing any other filter. |
updatedAfter | string (date-time) | Optional | Return records changed after this ISO 8601 date and time. |
updated_after | string (date-time) | Optional | Deprecated: use updatedAfter. |
status | 'open' | 'closed' | 'all' | Optional | Filter by conversation status. The default is all. |
propertyId | string (uuid) | Optional | Return conversations for one public property UUID. |
property_id | string (uuid) | Optional | Deprecated: use propertyId. |
| Field | Type | Required | Description |
|---|---|---|---|
data | Conversation[] | Required | A stable page of conversation records, newest activity first. |
meta | object | Required | Response metadata. |
meta.requestId | string | Required | Support identifier for this request. |
meta.page | object | Required | Cursor pagination state. |
meta.page.hasMore | boolean | Required | Whether another page is available. |
meta.page.limit | integer | Required | The page size applied to this response. |
meta.page.nextCursor | string | null | Required | The cursor for the next page, or null when the page is final. |
meta.page.snapshotAt | string (date-time) | Required | The stable read boundary shared by every page in the cursor chain. |
data[].id | string | Required | Stable conversation UUID. |
data[].guestName | string | Required | Guest name on the thread. |
data[].subject | string | null | Required | Thread subject, or null. |
data[].status | 'open' | 'closed' | Required | Thread status. |
data[].channel | 'airbnb' | 'vrbo' | 'direct' | 'website' | 'other' | Required | Sales channel the thread runs on. |
data[].property | object | Required | Property the thread belongs to. |
data[].property.id | string | Required | Public property UUID. |
data[].property.name | string | Required | Property name. |
data[].reservationId | string | null | Required | Linked reservation ID, or null. |
data[].lastMessageAt | string (date-time) | Required | Last message time. |
data[].lastMessage | object | Required | Last message summary. |
data[].lastMessage.direction | 'inbound' | 'outbound' | Required | Direction of the last message. |
data[].lastMessage.snippet | string | Required | Body of the last message. |
data[].updatedAt | string (date-time) | Required | Last conversation change time. |
GET /conversations/{conversationId}/messages
Return one stable page of messages in chronological order.
| Field | Type | Required | Description |
|---|---|---|---|
Authorization | string | Required | Send Bearer $SUPAHOST_API_KEY. |
| Field | Type | Required | Description |
|---|---|---|---|
conversationId | string (uuid) | Required | Conversation UUID. |
| Field | Type | Required | Description |
|---|---|---|---|
limit | integer | Optional | Records per page, from 1 through 200. The default is 100. |
cursor | string | Optional | Send meta.page.nextCursor without changing any other filter. |
| Field | Type | Required | Description |
|---|---|---|---|
data | Message[] | Required | A stable page of messages in chronological order. |
meta | object | Required | Response metadata. |
meta.requestId | string | Required | Support identifier for this request. |
meta.page | object | Required | Cursor pagination state. |
meta.page.hasMore | boolean | Required | Whether another page is available. |
meta.page.limit | integer | Required | The page size applied to this response. |
meta.page.nextCursor | string | null | Required | The cursor for the next page, or null when the page is final. |
meta.page.snapshotAt | string (date-time) | Required | The stable read boundary shared by every page in the cursor chain. |
data[].id | string | Required | Stable message UUID. |
data[].direction | 'inbound' | 'outbound' | Required | Message direction. |
data[].senderType | 'guest' | 'staff' | 'system' | Required | Who sent the message. |
data[].senderName | string | null | Required | Staff sender name, or null. |
data[].body | string | Required | Message body. |
data[].occurredAt | string (date-time) | Required | When the message was sent. |
POST /conversations/{conversationId}/messages
Queue a reply for delivery through the channel connection. The 201 response returns the stored message. Replying fails with replies_not_supported when the connection cannot send messages, and with conversation_closed when the thread is closed.
Send an Idempotency-Key header to make retries safe: a repeated POST with the same key and the same payload returns 200 with the original message and queues nothing new; the same key with a different payload fails with 409 idempotency_key_reused.
| Field | Type | Required | Description |
|---|---|---|---|
Authorization | string | Required | Send Bearer $SUPAHOST_API_KEY. |
Idempotency-Key | string | Optional | 1 to 200 characters. Makes create retries safe. |
| Field | Type | Required | Description |
|---|---|---|---|
conversationId | string (uuid) | Required | Conversation UUID. |
| Field | Type | Required | Description |
|---|---|---|---|
body | string | Required | Reply body, 1 to 10,000 characters. |
| Field | Type | Required | Description |
|---|---|---|---|
data | Message | Required | The queued reply. |
meta | object | Required | Response metadata. |
meta.requestId | string | Required | Support identifier for this request. |
data.id | string | Required | Stable message UUID. |
data.direction | 'inbound' | 'outbound' | Required | Message direction. |
data.senderType | 'guest' | 'staff' | 'system' | Required | Who sent the message. |
data.senderName | string | null | Required | Staff sender name, or null. |
data.body | string | Required | Message body. |
data.occurredAt | string (date-time) | Required | When the message was sent. |
Channel endpoints require the channels:read scope. Each connection carries its rate plan mappings; a mapping with null external codes is not linked on the sales channel yet.
Connection credentials are never returned. channelActive reports whether the connection is live on the sales channel, and syncState shows a queued or failed channel manager sync.
GET /channels
Return one stable page of channel connections.
| Field | Type | Required | Description |
|---|---|---|---|
Authorization | string | Required | Send Bearer $SUPAHOST_API_KEY. |
| Field | Type | Required | Description |
|---|---|---|---|
limit | integer | Optional | Records per page, from 1 through 200. The default is 100. |
cursor | string | Optional | Send meta.page.nextCursor without changing any other filter. |
updatedAfter | string (date-time) | Optional | Return records changed after this ISO 8601 date and time. |
updated_after | string (date-time) | Optional | Deprecated: use updatedAfter. |
propertyId | string (uuid) | Optional | Return channel connections for one public property UUID. |
property_id | string (uuid) | Optional | Deprecated: use propertyId. |
| Field | Type | Required | Description |
|---|---|---|---|
data | ChannelConnection[] | Required | A stable page of channel connection records. |
meta | object | Required | Response metadata. |
meta.requestId | string | Required | Support identifier for this request. |
meta.page | object | Required | Cursor pagination state. |
meta.page.hasMore | boolean | Required | Whether another page is available. |
meta.page.limit | integer | Required | The page size applied to this response. |
meta.page.nextCursor | string | null | Required | The cursor for the next page, or null when the page is final. |
meta.page.snapshotAt | string (date-time) | Required | The stable read boundary shared by every page in the cursor chain. |
data[].id | string | Required | Stable channel connection UUID. |
data[].title | string | Required | Connection display name. |
data[].channel | string | Required | Sales channel this connection distributes through, or other. |
data[].status | 'draft' | 'pending' | 'active' | 'error' | Required | Connection status. |
data[].channelActive | boolean | Required | Whether the connection is live on the sales channel. |
data[].syncState | 'pending' | 'failed' | 'null' | Required | Pending channel manager sync state, or null when nothing is queued. |
data[].currency | string | null | Required | Rate currency override, or null. |
data[].property | object | Required | Stable primary associated property. Deprecated: use properties. |
data[].property.id | string | Required | Public property UUID. |
data[].property.name | string | Required | Property name. |
data[].properties | object[] | Required | Properties this account-level connection distributes. |
data[].properties[].id | string | Required | Public property UUID. |
data[].properties[].name | string | Required | Property name. |
data[].mappings | object[] | Required | Rate plan mappings for this connection. |
data[].mappings[].id | string | Required | Stable channel mapping UUID. |
data[].mappings[].ratePlanId | string | Required | Mapped rate plan ID. |
data[].mappings[].ratePlanName | string | Required | Mapped rate plan name. |
data[].mappings[].roomTypeName | string | Required | Room type of the mapped rate plan. |
data[].mappings[].externalRoomCode | string | null | Required | Room code on the sales channel, or null when unmapped. |
data[].mappings[].externalRateCode | string | null | Required | Rate code on the sales channel, or null when unmapped. |
data[].mappings[].primaryOccupancy | boolean | Required | Whether the mapping drives the primary occupancy rate. |
data[].createdAt | string (date-time) | Required | Connection creation time. |
data[].updatedAt | string (date-time) | Required | Last connection change time. |
data[].removedAt | string (date-time) | null | Required | When the account was removed, or null. Only updatedAfter reads return removed accounts. |
Webhook endpoints require the webhooks:manage scope. The signing secret appears exactly once, in the create response; list and get responses never return it.
Test keys cannot create, update, or delete webhook endpoints, or send a delivery again. Writes with a test key return sandbox_read_only.
GET /webhooks
Return one stable page of webhook endpoints, newest first.
| Field | Type | Required | Description |
|---|---|---|---|
Authorization | string | Required | Send Bearer $SUPAHOST_API_KEY. |
| Field | Type | Required | Description |
|---|---|---|---|
limit | integer | Optional | Records per page, from 1 through 200. The default is 100. |
cursor | string | Optional | Send meta.page.nextCursor without changing any other filter. |
| Field | Type | Required | Description |
|---|---|---|---|
data | WebhookEndpoint[] | Required | A stable page of webhook endpoint records, newest first. |
meta | object | Required | Response metadata. |
meta.requestId | string | Required | Support identifier for this request. |
meta.page | object | Required | Cursor pagination state. |
meta.page.hasMore | boolean | Required | Whether another page is available. |
meta.page.limit | integer | Required | The page size applied to this response. |
meta.page.nextCursor | string | null | Required | The cursor for the next page, or null when the page is final. |
meta.page.snapshotAt | string (date-time) | Required | The stable read boundary shared by every page in the cursor chain. |
data[].id | string | Required | Stable webhook endpoint UUID. |
data[].url | string | Required | Endpoint URL. |
data[].description | string | Required | Endpoint description, or an empty string. |
data[].events | string[] | Required | Subscribed event types. |
data[].status | 'active' | 'disabled' | Required | Endpoint status. |
data[].disabledAt | string (date-time) | null | Required | When the endpoint was turned off, or null while it is active. |
data[].disabledReason | 'manual' | 'delivery_failures' | 'null' | Required | Why the endpoint is off: manual when a person turned it off, delivery_failures when Supahost did after 5 days of failed deliveries. Null while it is active. |
data[].createdAt | string (date-time) | Required | Endpoint creation time. |
POST /webhooks
Create a webhook endpoint. The URL must be a public https:// address without embedded credentials: loopback, private, link-local, and reserved hosts are rejected at save time, and delivery re-checks DNS answers and every redirect hop before connecting.
Send an Idempotency-Key header to make retries safe. A repeated POST with the same key and the same payload returns 200 with the original endpoint and creates nothing new; the same key with a different payload fails with 409 idempotency_key_reused.
The 201 response is the only one that includes signingSecret. A replayed request returns 200 without the secret. Both include the ETag of the endpoint as GET /webhooks/{webhookId} returns it.
| Field | Type | Required | Description |
|---|---|---|---|
Authorization | string | Required | Send Bearer $SUPAHOST_API_KEY. |
Idempotency-Key | string | Optional | 1 to 200 characters. Makes create retries safe. |
| Field | Type | Required | Description |
|---|---|---|---|
url | string | Required | Public https:// endpoint URL. |
events | string[] | Required | Subscribed event types from the event catalog. |
description | string | Optional | Endpoint description. |
enabled | boolean | Optional | Set false to turn the endpoint off. The default is true, which turns it on again and clears disabledReason. |
| Field | Type | Required | Description |
|---|---|---|---|
data | WebhookEndpoint | Required | The created webhook endpoint, including its signing secret. |
meta | object | Required | Response metadata. |
meta.requestId | string | Required | Support identifier for this request. |
data.id | string | Required | Stable webhook endpoint UUID. |
data.url | string | Required | Endpoint URL. |
data.description | string | Required | Endpoint description, or an empty string. |
data.events | string[] | Required | Subscribed event types. |
data.status | 'active' | 'disabled' | Required | Endpoint status. |
data.disabledAt | string (date-time) | null | Required | When the endpoint was turned off, or null while it is active. |
data.disabledReason | 'manual' | 'delivery_failures' | 'null' | Required | Why the endpoint is off: manual when a person turned it off, delivery_failures when Supahost did after 5 days of failed deliveries. Null while it is active. |
data.createdAt | string (date-time) | Required | Endpoint creation time. |
data.signingSecret | string | Required | Payload signing secret. Returned only in the create response. |
GET /webhooks/{webhookId}
Return one webhook endpoint from the API key workspace.
The response includes an ETag header that names this version of the webhook endpoint. Send it in If-None-Match to get 304 with no body when the webhook endpoint did not change. The tag names the whole response, so it also changes when a derived value, such as the status after Supahost turns the endpoint off, changes.
| Field | Type | Required | Description |
|---|---|---|---|
Authorization | string | Required | Send Bearer $SUPAHOST_API_KEY. |
If-None-Match | string | Optional | The ETag from your last read. Returns 304 with no body when the webhook endpoint did not change. |
| Field | Type | Required | Description |
|---|---|---|---|
webhookId | string (uuid) | Required | Webhook endpoint UUID. |
| Field | Type | Required | Description |
|---|---|---|---|
data | WebhookEndpoint | Required | The requested webhook endpoint. |
meta | object | Required | Response metadata. |
meta.requestId | string | Required | Support identifier for this request. |
data.id | string | Required | Stable webhook endpoint UUID. |
data.url | string | Required | Endpoint URL. |
data.description | string | Required | Endpoint description, or an empty string. |
data.events | string[] | Required | Subscribed event types. |
data.status | 'active' | 'disabled' | Required | Endpoint status. |
data.disabledAt | string (date-time) | null | Required | When the endpoint was turned off, or null while it is active. |
data.disabledReason | 'manual' | 'delivery_failures' | 'null' | Required | Why the endpoint is off: manual when a person turned it off, delivery_failures when Supahost did after 5 days of failed deliveries. Null while it is active. |
data.createdAt | string (date-time) | Required | Endpoint creation time. |
PUT /webhooks/{webhookId}
Replace one webhook endpoint. PUT is a full replacement: send every field that you want to keep. An omitted enabled sets the endpoint to enabled, so send enabled: false to keep a disabled endpoint disabled.
To avoid replacing a change that you did not see, send the ETag from your last read in If-Match. If the webhook endpoint changed since, the response is 412 precondition_failed and nothing is written. Read the webhook endpoint again and repeat the change. Without If-Match, the replacement always applies. A 412 can also come from a derived value that moved, such as the status after Supahost turns the endpoint off: read the webhook endpoint again and repeat the change; it is not an error to show.
| Field | Type | Required | Description |
|---|---|---|---|
Authorization | string | Required | Send Bearer $SUPAHOST_API_KEY. |
If-Match | string | Optional | The ETag from your last read, quotes included. Returns 412 precondition_failed when the webhook endpoint changed since, and 400 when the value is not a tag. |
| Field | Type | Required | Description |
|---|---|---|---|
webhookId | string (uuid) | Required | Webhook endpoint UUID. |
| Field | Type | Required | Description |
|---|---|---|---|
url | string | Required | Public https:// endpoint URL. |
events | string[] | Required | Subscribed event types from the event catalog. |
description | string | Optional | Endpoint description. |
enabled | boolean | Optional | Set false to turn the endpoint off. The default is true, which turns it on again and clears disabledReason. |
| Field | Type | Required | Description |
|---|---|---|---|
data | WebhookEndpoint | Required | The requested webhook endpoint. |
meta | object | Required | Response metadata. |
meta.requestId | string | Required | Support identifier for this request. |
data.id | string | Required | Stable webhook endpoint UUID. |
data.url | string | Required | Endpoint URL. |
data.description | string | Required | Endpoint description, or an empty string. |
data.events | string[] | Required | Subscribed event types. |
data.status | 'active' | 'disabled' | Required | Endpoint status. |
data.disabledAt | string (date-time) | null | Required | When the endpoint was turned off, or null while it is active. |
data.disabledReason | 'manual' | 'delivery_failures' | 'null' | Required | Why the endpoint is off: manual when a person turned it off, delivery_failures when Supahost did after 5 days of failed deliveries. Null while it is active. |
data.createdAt | string (date-time) | Required | Endpoint creation time. |
DELETE /webhooks/{webhookId}
Delete one webhook endpoint. A successful delete returns 204 with no body. Send the ETag from your last read in If-Match to delete only the version that you read: if the endpoint changed since, the response is 412 precondition_failed and nothing is deleted.
| Field | Type | Required | Description |
|---|---|---|---|
Authorization | string | Required | Send Bearer $SUPAHOST_API_KEY. |
If-Match | string | Optional | The ETag from your last read, quotes included. Returns 412 precondition_failed when the webhook endpoint changed since, and 400 when the value is not a tag. |
| Field | Type | Required | Description |
|---|---|---|---|
webhookId | string (uuid) | Required | Webhook endpoint UUID. |
GET /webhooks/{webhookId}/deliveries
Return one stable page of deliveries for the endpoint, newest first. Each delivery lists its attempts, oldest first.
| Field | Type | Required | Description |
|---|---|---|---|
Authorization | string | Required | Send Bearer $SUPAHOST_API_KEY. |
| Field | Type | Required | Description |
|---|---|---|---|
webhookId | string (uuid) | Required | Webhook endpoint UUID. |
| Field | Type | Required | Description |
|---|---|---|---|
limit | integer | Optional | Records per page, from 1 through 200. The default is 100. |
cursor | string | Optional | Send meta.page.nextCursor without changing any other filter. |
| Field | Type | Required | Description |
|---|---|---|---|
data | WebhookDelivery[] | Required | A stable page of delivery records, newest first. |
meta | object | Required | Response metadata. |
meta.requestId | string | Required | Support identifier for this request. |
meta.page | object | Required | Cursor pagination state. |
meta.page.hasMore | boolean | Required | Whether another page is available. |
meta.page.limit | integer | Required | The page size applied to this response. |
meta.page.nextCursor | string | null | Required | The cursor for the next page, or null when the page is final. |
meta.page.snapshotAt | string (date-time) | Required | The stable read boundary shared by every page in the cursor chain. |
data[].id | string | Required | Stable delivery UUID. |
data[].eventId | string | Required | The envelope id the endpoint receives. A redelivery sends the same value as the first delivery. |
data[].eventType | 'reservation.created' | 'reservation.updated' | 'reservation.cancelled' | 'message.received' | 'message.sent' | 'property.created' | 'property.updated' | 'property.lifecycle_changed' | 'task.created' | 'task.updated' | 'calendar.updated' | Required | Delivered event type. |
data[].eventKey | string | Required | Logical event identity; repeated deliveries of one event share it. |
data[].status | 'pending' | 'delivered' | 'failed' | 'exhausted' | Required | Delivery status. |
data[].attemptCount | integer | Required | Delivery attempts so far, at most 10. |
data[].responseStatus | integer | null | Required | HTTP status the endpoint returned, or null. |
data[].durationMs | integer | null | Required | Last attempt duration in milliseconds, or null. |
data[].nextAttemptAt | string (date-time) | null | Required | When the next attempt is due, or null once the delivery is delivered or exhausted. |
data[].completedAt | string (date-time) | null | Required | When the delivery was delivered or exhausted, or null. |
data[].redeliveryOf | string | null | Required | The first delivery of the same event when this one sends it again, or null. |
data[].attempts | object[] | Required | Every recorded attempt, oldest first. Deliveries made before attempts were recorded list none. |
data[].attempts[].number | integer | Required | Attempt number, from 1. |
data[].attempts[].outcome | 'in_progress' | 'delivered' | 'failed' | 'exhausted' | 'lost' | Required | in_progress while it runs, then delivered, failed (a retry follows), exhausted (the last attempt), or lost (the worker stopped before it saw an answer). |
data[].attempts[].responseStatus | integer | null | Required | HTTP status the endpoint returned, or null. |
data[].attempts[].errorCode | 'http_error' | 'timeout' | 'network_error' | 'blocked_host' | 'too_many_redirects' | 'lost' | 'null' | Required | Why the attempt failed, or null when it succeeded or is still running. |
data[].attempts[].durationMs | integer | null | Required | Attempt duration in milliseconds, or null. |
data[].attempts[].startedAt | string (date-time) | Required | When the attempt started. |
data[].attempts[].finishedAt | string (date-time) | null | Required | When the attempt ended, or null while it runs. |
data[].attempts[].nextAttemptAt | string (date-time) | null | Required | When the next attempt is due after this one failed, or null. |
data[].createdAt | string (date-time) | Required | Delivery creation time. |
POST /webhooks/{webhookId}/deliveries/{deliveryId}/redeliver
Send the event of a delivered or exhausted delivery again. Supahost queues a new delivery with the same payload and envelope id, to the endpoint's current URL, signed with its current secret. The request has no body.
Send an Idempotency-Key header to make retries safe. A repeated request with the same key returns 200 with the first redelivery. The first request returns 201.
The request fails with 409 webhook_delivery_in_flight while a delivery of the same event is pending or failed, and with 409 webhook_endpoint_disabled while the endpoint is off. Neither is retryable as is: wait for the delivery to finish, or turn the endpoint on. A delivery that does not belong to the endpoint returns 404.
| Field | Type | Required | Description |
|---|---|---|---|
Authorization | string | Required | Send Bearer $SUPAHOST_API_KEY. |
Idempotency-Key | string | Optional | 1 to 200 characters. A retried request returns the first redelivery instead of queuing a second. |
| Field | Type | Required | Description |
|---|---|---|---|
webhookId | string (uuid) | Required | Webhook endpoint UUID. |
deliveryId | string (uuid) | Required | Webhook delivery UUID. |
| Field | Type | Required | Description |
|---|---|---|---|
data | WebhookDelivery | Required | The new delivery, queued with the same event. |
meta | object | Required | Response metadata. |
meta.requestId | string | Required | Support identifier for this request. |
data.id | string | Required | Stable delivery UUID. |
data.eventId | string | Required | The envelope id the endpoint receives. A redelivery sends the same value as the first delivery. |
data.eventType | 'reservation.created' | 'reservation.updated' | 'reservation.cancelled' | 'message.received' | 'message.sent' | 'property.created' | 'property.updated' | 'property.lifecycle_changed' | 'task.created' | 'task.updated' | 'calendar.updated' | Required | Delivered event type. |
data.eventKey | string | Required | Logical event identity; repeated deliveries of one event share it. |
data.status | 'pending' | 'delivered' | 'failed' | 'exhausted' | Required | Delivery status. |
data.attemptCount | integer | Required | Delivery attempts so far, at most 10. |
data.responseStatus | integer | null | Required | HTTP status the endpoint returned, or null. |
data.durationMs | integer | null | Required | Last attempt duration in milliseconds, or null. |
data.nextAttemptAt | string (date-time) | null | Required | When the next attempt is due, or null once the delivery is delivered or exhausted. |
data.completedAt | string (date-time) | null | Required | When the delivery was delivered or exhausted, or null. |
data.redeliveryOf | string | null | Required | The first delivery of the same event when this one sends it again, or null. |
data.attempts | object[] | Required | Every recorded attempt, oldest first. Deliveries made before attempts were recorded list none. |
data.attempts[].number | integer | Required | Attempt number, from 1. |
data.attempts[].outcome | 'in_progress' | 'delivered' | 'failed' | 'exhausted' | 'lost' | Required | in_progress while it runs, then delivered, failed (a retry follows), exhausted (the last attempt), or lost (the worker stopped before it saw an answer). |
data.attempts[].responseStatus | integer | null | Required | HTTP status the endpoint returned, or null. |
data.attempts[].errorCode | 'http_error' | 'timeout' | 'network_error' | 'blocked_host' | 'too_many_redirects' | 'lost' | 'null' | Required | Why the attempt failed, or null when it succeeded or is still running. |
data.attempts[].durationMs | integer | null | Required | Attempt duration in milliseconds, or null. |
data.attempts[].startedAt | string (date-time) | Required | When the attempt started. |
data.attempts[].finishedAt | string (date-time) | null | Required | When the attempt ended, or null while it runs. |
data.attempts[].nextAttemptAt | string (date-time) | null | Required | When the next attempt is due after this one failed, or null. |
data.createdAt | string (date-time) | Required | Delivery creation time. |
Start a flow from your own system. The flow must have a webhook trigger, and you must name a version that is published and turned on.
The key needs flows:write. A new key does not have this scope: add it when you create the key. The person who made the key must still have permission to manage automations.
Test keys cannot start a flow (sandbox_read_only).
POST /flows/{flowId}/events
Send one event to the flow. version is the published version to run. key is the event key that the flow’s webhook trigger names. data is your own JSON object. The flow reads it at details.webhook.data.
context is optional. It ties the run to one conversation, reservation or property of the workspace. The record must be inside the properties that the flow covers.
The response is a receipt. 202 means that Supahost saved the event and queued the run. It does not mean that the flow’s actions ran. A flow in shadow mode only records the actions it would take. A live flow follows the approval mode it was published with.
A body can be at most 32 KB, 16 levels deep, and 5,000 JSON values. A larger body returns 413. A version that is not published, a wrong event key, or a record outside the flow’s properties returns 409.
| Field | Type | Required | Description |
|---|---|---|---|
Authorization | string | Required | Send Bearer $SUPAHOST_API_KEY. The key must be a live key with flows:write. |
Content-Type | string | Required | application/json. |
Idempotency-Key | string | Required | 1 to 200 characters. Send the same key and the same body after a lost response to get the first run back. The same key with a different body returns 409. |
| Field | Type | Required | Description |
|---|---|---|---|
flowId | string (uuid) | Required | The flow to start. |
| Field | Type | Required | Description |
|---|---|---|---|
version | integer | Required | |
key | string | Required | |
context | object | Optional | |
context.kind | 'conversation' | 'reservation' | 'property' | Required | |
context.id | string | Required | |
data | object | Required |
curl -X POST "https://supahost.io/api/v1/flows/$FLOW_ID/events" \
-H "Authorization: Bearer $SUPAHOST_API_KEY" \
-H "Content-Type: application/json" -H "Idempotency-Key: door-code-8841" \
-d '{"version":3,"key":"door.code.changed","context":{"kind":"reservation","id":"$RESERVATION_ID"},"data":{"code":"4821"}}'| Field | Type | Required | Description |
|---|---|---|---|
data | FlowInvocationReceipt | Required | The receipt of the queued run. |
meta | object | Required | Response metadata. |
meta.requestId | string | Required | Support identifier for this request. |
data.flowId | string | Required | |
data.version | integer | Required | |
data.runId | string | Required | |
data.eventId | string | Required | |
data.sourceId | string | Required | |
data.mode | 'live' | 'shadow' | Required | |
data.status | 'queued' | Required |
A repeat of the same key and body returns 200 with the first receipt, even if the flow was paused after it.
List endpoints return 100 records by default. Set limit from 1 through 200.
If hasMore is true, send nextCursor as the next cursor. Keep all other filters unchanged.
The cursor holds a snapshot boundary. Records that change during a multi-page read do not move between its pages.
The names of query parameters are camelCase: updatedAfter, propertyId, arrivalFrom, arrivalTo, inventoryPoolId, skipLocked and validateOnly. The snake_case names they replace (updated_after, property_id, arrival_from, arrival_to, pool_id, skip_locked and validate_only) are deprecated and still work with the same meaning. Sending both names of one parameter with different values returns 400. A cursor works with either name.
A response to a request that used a deprecated name has a Deprecation header, a Sunset header and a Link header with rel="deprecation". The API changelog lists each deprecated name, its replacement and the day until which it works.
Each API key can make 120 requests per minute. Supahost does not combine second, minute, and hour quotas.
RateLimit-Limitshows the key limit.RateLimit-Remainingshows the requests left in the current window.RateLimit-Resetshows the seconds until the window resets.Retry-Afterappears with a429response, and with any error whoseretryableisafter.
Supahost records each authenticated request. The record has the key, route, status, duration, and request ID.
Supahost does not store request bodies, response bodies, credentials, or URL query values in this audit record.