Last updated

Self-certification tutorial: Property status

In this tutorial, you will use the Property API to:

  • Check if a property is Open/Bookable
  • Open a property
  • Close a property with a reason

Who is this for?

You should follow this if you are a developer who has completed the integration of Property API’s status endpoint and is looking to start using this with live properties in production.

Before you start

We recommend that you use a test property with the appropriate machine account permissions to complete the tutorial While you'll notice the test property cannot be opened or closed (this is by design), using it helps you understand how to properly structure request bodies for the endpoints.

Step 1 - Check your property's status for going Open/Bookable

Use the status end point's Check operation to know if your property can go to the Open/Bookable state. Save the RUID to include in your report to Connectivity Support (see below).

Sample request:

POST https://supply-xml.booking.com/property-api/properties/{propertyId}/status 

Header parameter

The following table describes the elements you can add in the header:

HeaderDescriptionTypeRequired/
Optional
Notes
Content-Type: application/jsonSpecifies the expected content type.stringRequired

Path parameter

The following table describes the elements you can add in the path:

ValueDescriptionTypeRequired/
Optional
Notes
{property ID}Specify the unique ID of the property to check or update state.integerRequired

Request body

{
   "operation" : "Check"
}
{
    "data": {
        "status": "Checks have passed, property may now be opened."
    },
    "warnings": [],
    "errors": [],
    "meta": {
        "ruid": "..."
    }
}

If the response contains warnings or errors, follow the guidance in Handling errors and warnings in status endpoint before proceeding.

Step 2 - Use status endpoint to Open the property

Once the property status check returns no errors, you can try to open your test property. However, note that test properties cannot be opened or closed. This is the intended behaviour.

Sample request:

POST https://supply-xml.booking.com/property-api/properties/{propertyId}/status 

Header parameter

The following table describes the elements you can add in the header:

HeaderDescriptionTypeRequired/
Optional
Notes
Content-Type: application/jsonSpecifies the expected content type.stringRequired

Path parameter

The following table describes the elements you can add in the path:

ValueDescriptionTypeRequired/
Optional
Notes
{property ID}Specify the unique ID of the property to check or update state.integerRequired

Sample request:

POST https://supply-xml.booking.com/property-api/properties/{propertyId}/status 
{
    "operation" : "Open"
}

Sample response: Open

For a test property, the API returns the error: Can't change status of a test property

While the API returns an error (this is by design), note the ruid returned in the response object and share it with the Support team.

For a live property, the API returns:

{
    "data": {
        "status": "Property ... is in Open / bookable status"
    },
    "warnings": [],
    "errors": [],
    "meta": {
        "ruid": "..."
    }
}

Step 3 - Close a hotel

In this step, you can try to close the test hotel using the following sample request. However, note that test properties cannot be opened or closed. This is the intended behaviour.

Sample request:

POST https://supply-xml.booking.com/property-api/properties/{propertyId}/status 

Header parameter

The following table describes the elements you can add in the header:

HeaderDescriptionTypeRequired/
Optional
Notes
Content-Type: application/jsonSpecifies the expected content type.stringRequired

Path parameter

The following table describes the elements you can add in the path:

ValueDescriptionTypeRequired/
Optional
Notes
{property ID}Specify the unique ID of the property to check or update state.integerRequired
{
    "operation" : "Close",
    "reason": {
        "type": "Renovation",
        "description" : "Example"
    }
}

Sample response: Closed

For a test property, the API returns the error: Can't change status of a test property While the API returns an error (this is by design), note the ruid returned in the response object and share it with the Support team.

For a live property, the API returns:

{
    "data": {
        "status": "Property ... is in Closed (requested by hotel) status"
    },
    "warnings": [],
    "errors": [],
    "meta": {
        "ruid": "..."
    }
}

Step 4 - Send the RUIDs to Booking.com

Through your organization’s domain email address, send the ruid values obtained in the response bodies of the POSTrequests to connectivity@booking.com for validation and certification.

Email template

I would like to be certified for production use of Property Status endpoints. Please find the RUIDs for all the steps in the tutorial.

I look forward to hearing from you.