Get a price from the API

Now that you know what a bundle is, it is time for you to understand how to display a price in your purchase funnel.

What is a Quote?

Quote is the endpoint that you will use to obtain the price of Koala products (in the form of bundles now that you are an expert!).

Every time that you need to know how much a Koala product costs, you will call the Quote API and send us the traveler's trip details. Our Quote engine will then compute the price of all the possible bundles for the given trip details.

You will receive from us one price per bundle.

note

For one customer session in your purchase funnel, the Quote API can be called several times if the traveler decides to make changes to his booking details (choose a new flight, add or remove a traveler, add options included in the compensation, change dates, etc...).

Quote expiration

Every Quote has a limited validity period. The response contains an expirationDate field (ISO 8601) that tells you until when the <QUOTE_REFERENCE> can be turned into a contract via the Subscriptions endpoint.

By default, a Quote is valid for 72 hours from the moment it was issued (if you need us to extend this validity period, please let us know at support@hikoala.co).

caution

Two things to do in your integration:

• Store the expirationDate alongside the <QUOTE_REFERENCE> when you receive the Quote response.
• Check it before posting the Subscription. If the stored Quote has expired, call the Quote API again to obtain a fresh <QUOTE_REFERENCE> before creating the Subscription.

Calling /subscriptions with an expired reference returns a 400 error, no contract is created, and the traveler will not be covered.

Example of Quote input

This is an example of a payload to provide to the Quotes service for a trip containing only a Journey:

{
  "data": {
    "currency": "EUR",
    "trips": [
      {
        "price": {
          "amount": 590.97,
          "currency": "EUR"
        },
        "journeys": [
          {
            "flights": [
              {
                "airlineIata": "AF",
                "number": "65",
                "departureAirportIata": "LAX",
                "arrivalAirportIata": "CDG",
                "departureDate": "2021-08-03T09:50:00Z",
                "arrivalDate": "2021-08-04T11:50:00Z"
              }
            ]
          }
        ],
        "travelers": [
          {
            "ageRange": "ADULT"
          }
        ]
      }
    ]
  }
}

Possible Quote outputs

Our Quote API will give you different responses:

• 201: The Quote is valid and respects the expected format. Inside this response, you will find a <QUOTE_REFERENCE> and an expirationDate that will be required for the Subscriptions. Pay close attention to the quote validity and to the expiration date. Keep this reference warm 👌
• 400: The Quote is invalid. You may have forgotten one mandatory field or made a mistake with one format.
• 401: The Quote cannot be sent because you are experiencing an issue with your token.

Only Quotes with a 201 response and a valid body can be displayed in your purchase funnel.

Valid payload but inability to sell the bundle

Each product and, by extension, each bundle can come with a set of limitations of sales (Example: A product can sometimes be sold only up to a certain time before departure.).

If you send a payload in the right format but that ends up in breach with one of the sales limitation, you will receive a valid 201 response from the server. However, your Quote will have a false validity, meaning that we can not sell the bundle to the given trip.

Invalid Quotes come with reasons to help you understand why we cannot cover the given trip.

note

You must only display valid Quotes in your purchase funnel.

Example: If you are selling 2 products, you may receive the following response:

{
  "data": [
    {
      "quotes": [
        {
          "valid": true,
          "bundle": "silver",
          "price": {
            "amount": 590.97,
            "currency": "EUR"
          },
          "reference": "<QUOTE_REFERENCE>",
          "date": "2021-06-03T14:49:07.790+02:00",
          "expirationDate": "2021-06-04T14:49:07.790+02:00"
        },
        {
          "valid": false,
          "bundle": "gold",
          "reasons": [
            "One of the flights is too close in the future (cannot cover flights departing before '2021-08-02T12:50:00Z+03:00' and journeys.0.flights.0.departure_date is '2021-08-03T12:50:00.000+03:00')"
          ],
          "date": "2021-06-03T14:49:07.790+02:00"
        }
      ]
    }
  ]
}

Here, you will be able to sell the silver bundle but not the gold one.