Properties, units and rate plans

These endpoints return the static content of the properties you can sell: descriptions, images, units, rate plans and their policies. Prices and availability are not here; use Availability for those.

Which properties you see

• Only properties you have an active contract with. Until a contract is live, GET /properties doesn't list the property and GET /properties/{id} returns 403 You do not have an active partnership with this property.
• Only active properties and active units. A property or unit type the hotel deactivates disappears from the response.
• Only public rate plans. Corporate negotiated rates (CNRs) are never listed on these endpoints. They appear only in Availability when you send the matching corporate_profile_id.

Downloading your content (GET /properties)

{
  "data": { "properties": [ { "id": "6Y1227GD", "name": "…", "units": [ … ], "rate_plans": [ … ], "…": "…" } ] },
  "links": {
    "first":    { "method": "GET", "url": "https://api.katanox.com/v2/properties?limit=50&page=0" },
    "previous": { "method": "", "url": "" },
    "next":     { "method": "GET", "url": "https://api.katanox.com/v2/properties?limit=50&page=1" },
    "last":     { "method": "GET", "url": "https://api.katanox.com/v2/properties?limit=50&page=180" }
  },
  "meta": { "total_properties": 9075 }
}

How to page through everything: request page=0, 1, 2, … with limit=50 and stop when data.properties is empty.

• Don't stop at links.last or when links.next is empty; the last page can be missing from both.
• links.previous / links.next are returned as {"method":"","url":""} when there is no such page. links is null when you have no properties.
• Don't use meta.total_properties as the number of properties you will receive. It counts the properties under your contracts, including ones that are currently inactive.

Common mistake: deleting a property from your catalogue because one sync didn't return it. A temporary problem on our side can return a short or empty page. Only remove a property after it has been missing from several consecutive syncs, and alert on a sync that returns far fewer properties than the previous one.

Keeping content fresh.

• Hotels update their content at irregular times. Refreshing your copy weekly is enough for descriptions, images and amenities.
• Rate plans change more often. A new corporate rate or promotion adds rate plans; an expired one removes them. An offer in availability can reference a rate_plan_id you haven't downloaded yet: use the rate_plans map in the availability response, or fetch it with GET /rate-plans?ids=.

Property

Empty strings and empty lists are returned as "" and [], not omitted.

There are no policies on the property itself. Policies belong to rate plans.

Image

Facilities and amenities

Each facility and amenity has id, category and name.

• Parking is always a property facility (e.g. Free Parking, Valet, Parking garage), never a unit amenity.
• Wi-Fi is a unit amenity, Free WIFI.
• The full list of facility and amenity names is fixed. There is no endpoint for it; ask your account manager for the current list if you map our content to your own.

Unit

A unit is a unit type, not a physical unit.

• Use bed_types, not the name, for the bed setup. We pass unit names through as the hotel sends them and don't parse them.
• Maximum occupancy is not exposed. The availability search only returns units that fit the guests you asked for (Availability → Limits).
• Some hotels expose few unit types. Some chains sell only their "best available" unit through us and assign the actual unit at check-in.
• There is no filter for unit type (twin/double) in availability. Map and filter units on your side.

Rate plan

For booking, use the policies from availability. The policies here describe the rate plan in general. The ones that apply to a specific stay are in data.rate_plans of the availability response, and the ones that apply to a booking are stored on the reservation (Cancellation).

An empty cancellation_policies list does not mean the rate is non-refundable. It means the hotel hasn't provided the policy for that rate plan. Report it to us.

Translations

translations holds the content in other languages: locale, name, description.

• name and description on the object itself are always in the default language (usually English).
• On GET /properties and GET /properties/{id}, translations are only returned when you send a locale other than en. You then get every available translation, not only the one you asked for.
• On GET /properties/{property_id}/units/{id}, locale returns only that language.
• Rate plans always include every available translation.

Content quality

We pass property content through as the hotel or chain gives it to us. A few things to know:

• Coordinates come from the chain. Some chains give the street entrance rather than the building, so they can differ slightly from map services. If you find coordinates that are clearly wrong, tell us and we'll raise it with the chain.
• Two properties can share an address, for example two hotels in the same building.
• Room names follow the chain's naming. See Unit.
• Where a property comes from is not exposed. The content looks the same whichever hotel system or channel serves the property.

IDs and mapping

• Katanox IDs are unique across all chains. A hotel's own code (e.g. a chain property code) can clash with another chain's, so always store our id.
• Rate plan IDs are unique across properties, so GET /rate-plans?ids= doesn't need a property ID.
• If you need to match our properties to your own catalogue, ask your account manager for a mapping file.

Single unit, single rate plan

GET /v2/properties/{property_id}/units/{id} returns { "unit": { … } }.

GET /v2/properties/{property_id}/rate-plans/{id} returns { "rate_plan": { … } }.

Several rate plans (GET /rate-plans)

GET /v2/rate-plans?ids=6Y11JROY,P8XW5MG2

• Returns { "data": { "rate_plans": [ … ] } }.
• Pass up to 50 IDs. Repeat ids or comma-separate.
• Rate plans you don't have access to are left out of the response without an error.
• 400 Rate plan ids cannot be empty when no ID is sent. 404 when none of the IDs can be returned.

Corporate profiles (GET /corporate-profiles)

A corporate profile represents one company you sell corporate negotiated rates (CNRs) for. We create it when the hotel has loaded the CNR, and you send its id as corporate_profile_id in availability searches (Availability).

{ "data": [ { "id": "J0GER8X4", "name": "Acme Corp" } ], "meta": { "total": 1 } }

• Store one corporate_profile_id per company on your side.
• With a corporate profile, some hotels return only the corporate rate, not their public rates.
• A CNR stops appearing when its contract with the hotel ends.