Self-certification tutorial: Charges API

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

Create a charge
Read back the charge details
Update the charge details
Delete the charge
Contact connectivity support to validate your integration and enable live/production property access

Who is this for

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

Before you start

You will need to use an existing test property which was either created by Property API or found in the list of test properties on the provider portal.

Step 1 - Create a charge

With your new Charges API integration, create a charge within your system that will trigger a request to create the charge within Booking.com via the endpoint listed below. Save the RUID to include in your report to connectivity support (see below).

Sample request:

PUT
https://supply-xml.booking.com/charges-api/properties/{property_id}/charges

Header parameter

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

Header	Description	Type	Required/ Optional	Notes
`Content-Type: application/json`	Specifies the expected content type.	string	required
`Accept-Version`	Specify the version number to get the API functionality specific to that version.	string	optional	Currently supports the value: 1.0

Request body

The following is a request body example:

{
  "property_charges": [
    {
      "charge_key": {
        "type": "CLEANINGFEE",
        "guest_origin": "ANY",
        "travel_purpose": "ANY"
      },
      "charge_periods": [
        {
          "applicable": {
            "from": "2024-10-01",
            "to": "2024-11-28"
          },
          "configuration": {
            "amount": {
              "value": 20.00,
              "base": [],
              "mode": "PER_STAY"
            },
            "excluded": true
          }
        }
      ]
    }
  ]
}

Response body

The following is a response body example:

{
  "warnings": [],
  "errors": [],
  "meta": {
    "ruid": "XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX"
  }
}

Step 2 - Read the property's charges

Using your system, trigger a read request of the charges you have just created. Save the RUID to include in your report to connectivity support.

Sample request:

GET
https://supply-xml.booking.com/charges-api/properties/{property_id}/charges

Header parameter

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

Header	Description	Type	Required/ Optional	Notes
`Accept-Version`	Specify the version number to get the API functionality specific to that version.	string	optional	Currently supports the value: 1.0

Response body

{
  "data": {
    "property_charges": [
      {
        "charge_key": {
          "type": "CLEANINGFEE",
          "guest_origin": "ANY",
          "travel_purpose": "ANY"
        },
        "charge_periods": [
          {
            "applicable": {
              "from": "2024-09-09",
              "to": "2024-09-30"
            },
            "configuration": {
              "amount": {
                "value": 18.00,
                "base": [],
                "mode": "PER_STAY"
              },
              "excluded": true
            }
          },
          {
            "applicable": {
              "from": "2024-10-01",
              "to": "2024-11-28"
            },
            "configuration": {
              "amount": {
                "value": 20.00,
                "base": [],
                "mode": "PER_STAY"
              },
              "excluded": true
            }
          },
          {
            "applicable": {
              "from": "2024-11-29"
            },
            "configuration": {
              "amount": {
                "value": 18.00,
                "base": [],
                "mode": "PER_STAY"
              },
              "excluded": true
            }
          }
        ]
      },
      ...
      ...
      ...
      {
        "charge_key": {
          "type": "PETFEE",
          "guest_origin": "ANY",
          "travel_purpose": "ANY"
        },
        "charge_periods": [
          {
            "applicable": {
              "from": "2024-09-09"
            },
            "configuration": {
              "amount": {
                "value": 5.00,
                "base": [],
                "mode": "PER_STAY"
              },
              "excluded": true
            }
          }
        ]
      }
    ],
    "room_charges": [
      {
        "room_id": 801185511,
        "charges": [
          {
            "charge_key": {
              "type": "DESTINATIONCHARGE",
              "guest_origin": "ANY",
              "travel_purpose": "LEISURE"
            },
            "charge_periods": [
              {
                "applicable": {
                  "from": "2024-09-09"
                },
                "configuration": {
                  "amount": {
                    "value": 1.98,
                    "base": [],
                    "mode": "PER_PERSON_PER_NIGHT"
                  },
                  "excluded": false
                }
              }
            ]
          }
        ]
      }
    ]
  },
  "warnings": [],
  "errors": [],
  "meta": {
    "ruid": "XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX"
  }
}

Step 3 - Update the charge

Using your system, trigger an update request using the endpoint listed below. Save the RUID to include in your report to connectivity support.

Sample Request:

PUT
https://supply-xml.booking.com/charges-api/properties/{property_id}/charges

Header parameter

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

Header	Description	Type	Required/ Optional	Notes
`Accept-Version`	Specify the version number to get the API functionality specific to that version.	string	optional	Currently supports the value: 1.0

Request body:

The following is a request body example:

{
  "property_charges": [
    {
      "charge_key": {
        "type": "CLEANINGFEE",
        "guest_origin": "ANY",
        "travel_purpose": "ANY"
      },
      "charge_periods": [
        {
          "applicable": {
            "from": "2024-10-01"
          },
          "configuration": {
            "amount": {
              "value": 5.00,
              "base": [],
              "mode": "PER_PERSON_PER_NIGHT"
            },
            "excluded": true
          }
        }
      ]
    }
  ],
  "room_charges": []
}

Response body

{
  "warnings": [],
  "errors": [],
  "meta": {
    "ruid": "XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX"
  }
}

Step 4 - Delete the charge

Using your system, trigger a delete request using the endpoint listed below. Save the RUID to include in your report to connectivity support.

Sample Request:

PUT
https://supply-xml.booking.com/charges-api/properties/{property_id}/charges

Header parameter

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

Header	Description	Type	Required/ Optional	Notes
`Accept-Version`	Specify the version number to get the API functionality specific to that version.	string	optional	Currently supports the value: 1.0

Request body:

The following is a request body example:

{
  "property_charges": [
    {
      "charge_key": {
        "type": "CLEANINGFEE",
        "guest_origin": "ANY",
        "travel_purpose": "ANY"
      },
      "charge_periods": [
        {
          "applicable": {
            "from": "2024-08-09"
          },
          "configuration": null
        }
      ]
    }
  ],
  "room_charges": []
}

Response body

{
  "warnings": [],
  "errors": [],
  "meta": {
    "ruid": "XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX"
  }
}

Step 4 - Send the RUIDs to Booking.com

Send via your organization’s domain email the RUID values obtained in the response bodies of the PUT and GET requests to connectivity@booking.com for validation and certification.

Email template

I would like to be certified for production use of Charges API. Please find the RUIDs for all of the steps in the tutorial.

I look forward to hearing from you.