Pricing Workflow

Overview

The pricing object contains information required to enable bookings including availability and length of stay based on the number of guests.

Pricing Information is specific to unit types within a listing. e.g.: a 1 room apartment will have different prices and a maximum number of guests compared to a 2 room apartment.

Integration Steps

Endpoints Available
GET	`/v1/updates/pricing`
GET	`/v1/listings/{listingId}/unit-types/{unitTypeId}/pricing`

Step 1: Fetching the Pricing Updates

Make an API call to route GET /v1/updates/pricing to fetch the latest pricing updates.
As this is a paginated API, you have to pass the following parameters:

Parameter	Description
`cursor`	Each response returns you a `next` cursor, that you can then use to retrieve next page of updates.
`limit`	The maximum number of pricing updates returned by API.

If you are integrating with this API for the first time, the cursor parameter should be omitted. Every subsequent request should contain the cursor that is provided to you in the previous call’s next field. That way you can poll for listing updates that happened after the last successful pull.

Sample Request

curl -X 'GET' \
  'https://chapi.bookiply.com/v1/updates/pricing?cursor=asJ34sgt&limit=3' \
  -H 'Accept: application/json'
  -H 'Authorization: Bearer SIGNED_JWT'

Sample Response

{
  "updates": [
    {
      "listingId": "1386b2ba-eca5-4adf-9e04-62fc521273f9",
      "unitTypeId": "fc033fae-191e-4618-80be-a8ffd48f25fc",
      "pricingUrl": "/listings/1386b2ba-eca5-4adf-9e04-62fc521273f9/unit-types/fc033fae-191e-4618-80be-a8ffd48f25fc/pricing",
      "version": "951"
    },
    {
      "listingId": "7b1cb9d9-9c58-47ee-8435-72a536eadedc",
      "unitTypeId": "507e2397-11a8-455f-b845-e7224d09093b",
      "pricingUrl": "/listings/7b1cb9d9-9c58-47ee-8435-72a536eadedc/unit-types/507e2397-11a8-455f-b845-e7224d09093b/pricing",
      "version": "956"
    },
    {
      "listingId": "cd7adf70-6be7-4b6a-a0f9-924fabe442e2",
      "unitTypeId": "b7fc3c34-749f-419c-bb32-c3de5e59767d",
      "pricingUrl": "/listings/cd7adf70-6be7-4b6a-a0f9-924fabe442e2/unit-types/b7fc3c34-749f-419c-bb32-c3de5e59767d/pricing",
      "version": "957"
    }
  ],
  "next": "JSMjIwtNQ1sNAJRykxRsjK0MD"
}

Parameter	Description
`listingId`	Unique id of the listing
`unitTypeId`	Unique id of the unit type under the listing
`pricingUrl`	The pricing URL which can be used to fetch the pricing
`version`	An unique identifier, specifying the update version in a global incremental series for every update. If version is 20, this means that this is the 20^thupdate on Listing or Pricing in our inventory.

Step 2: Processing the Pricing Update

After successfully fetching the pricing updates, the content found in the pricingUrl field needs to be processed.
The pricingUrl field represents the API route for fetching pricing content (i.e GET /v1/listings/{listingId}/unit-types/{unitTypeId}/pricing).

Sample Request

curl -X 'GET' \
  'https://chapi.bookiply.com/v1/listings/1386b2ba-eca5-4adf-9e04-62fc521273f9/unit-types/fc033fae-191e-4618-80be-a8ffd48f25fc/pricing' \
  -H 'Accept: application/json'
  -H 'Authorization: Bearer SIGNED_JWT'

Sample Response

{
  "listingId": "1386b2ba-eca5-4adf-9e04-62fc521273f9",
  "unitTypeId": "fc033fae-191e-4618-80be-a8ffd48f25fc",
  "availabilities": [
    {
      "date": "2022-04-26",
      "unitsAvailable": 1
    },
    {
      "date": "2022-04-27",
      "unitsAvailable": 1
    }
  ],
  "losRecords": {
      "los": {
        "2022-04-26": [
          {
            "price": [
              0,
              80,
              120,
              150
            ],
            "currency": "EUR",
            "maxOccupancy": 2
          },
          {
            "price": [
              0,
              90,
              130,
              160
            ],
            "currency": "EUR",
            "maxOccupancy": 3
          }
        ],
        "2022-04-27": [
          {
            "price": [
              0,
              80
            ],
            "currency": "EUR",
            "maxOccupancy": 2
          },
          {
            "price": [
              0,
              90
            ],
            "currency": "EUR",
            "maxOccupancy": 3
          }
        ]
      }
    }
}

LOS Structure

"losRecords": {
      "los": {
        "CHECK-IN_DATE": [
          {
            "price": [
              PRICE_FOR_1_NIGHT,
              PRICE_FOR_2_NIGHTS,
              PRICE_FOR_3_NIGHTS,
              PRICE_FOR_4_NIGHTS
            ],
            "currency": "EUR",
            "maxOccupancy": MAX_NUMBER_OF_GUESTS
          }
       ]
    }
}

The los object contains a list of available check-in dates. Each CHECK-IN_DATE has an array of price objects based on the max number of guests.
The number of prices in the price list indicates the number of nights possible to book from the check-in date.

Example:

"2022-04-26": [
    {
        "price": [
          0,
          80,
          120,
          150
        ],
        "currency": "EUR",
        "maxOccupancy": 2
    },
    {
        "price": [
          0,
          90,
          130,
          160
        ],
        "currency": "EUR",
        "maxOccupancy": 3
    }
]

A 1-night stay on check-in date 2022-04-26 is not possible since the price is 0
A 2-nights stay on check-in date 2022-04-26 costs 80 euros for 2 guests and 90 euros for 3 guests. Similarly for 3 and 4 nights.

Sync Frequency

To ensure the latest listing availability and prices, partners should regularly poll the pricing updates. The pricing updates API can be polled up to the interval specified in the Rate limiting. We recommend that you poll it multiple times per minute to avoid overbookings. We also recommend reconfirming the availability of the property before processing the new booking. This can be done by fetching the same price update for specific listing & unit type as shown above.