Skip to main content

Create a contract

What is a Subscription?​

Subscription is the endpoint that you will use to create a contract for a booking. Travelers will benefit from Koala protection only once the contract is created.

You will use the Subscription endpoint every time the travelers have added a Koala product to their shopping cart and completed the payment on your website.

To post a Subscription, you should first make a call to our Quote API to obtain the precious <QUOTE_REFERENCE>.

In total, you will need to provide:

  • The Quote reference
  • The booking number (a unique reference number from your information system, usually the one you shared with your customers)
  • The client details
  • The travelers details

Example of Subscription input​

This is an example of the payload you need to send us:

{
  "data": {
    "bookingNumber": "5K7SXD",
    "quotes": [
      {
        "reference": "<QUOTE_REFERENCE>",
        "travelers": [
          {
            "ageRange": "ADULT",
            "birthday": "1968-06-09",
            "firstName": "Marty",
            "lastName": "McFly"
          },
          {
            "ageRange": "ADULT",
            "birthday": "1968-01-21",
            "firstName": "Jennifer",
            "lastName": "Parker"
          }
        ]
      }
    ],
    "customer": {
      "email": "marty.mcfly@gmail.com",
      "firstName": "Marty",
      "lastName": "McFly",
      "language": "en-GB"
    }
  }
}

Possible Subscription outputs​

Our Subscriptions API will give you different responses:

  • 201: The Subscription is valid and the contract is successfully created. The travelers are now covered by Koala 🐨
  • 400: The Subscription is invalid. You may have forgotten one mandatory field or made a mistake with one format.
  • 401: The Subscription cannot be created because you are experimenting an issue with your token.
  • 409: The Subscription cannot be created because the booking number or the quote reference you used has already been sent to us.

More details about 409 error messsages​

A booking number and the quote reference can only be used once with our Subscriptions service.

If you are experiencing this issue but do not know why, please send us an email at support@hikoala.co


Example of Successful Subscription​

If the payload is valid you will receive a 201 response.

Here is an example of successful response:

{
  "data": {
    "bookingNumber": "5K7SXD",
    "price": {
      "amount": 59.97,
      "currency": "EUR"
    }
  }
}

The travelers for that booking are now covered by Koala and can travel with peace of mind 🐨