Skip to main content

Declare a booking cancellation

You should only look at this section when you are selling a WITHDRAWAL product (= Koala Flex).

Why using Contracts?​

Contract is the endpoint that you will use to create a claim when you have been informed of a booking cancellation from travelers.

Once a claim is created, we will initiate the refund process.

How to declare a booking cancellation?​

To declare a booking cancellation, you need to follow a 2-steps process.

Step 1:

Make a GET on: (please replace the bookingNumber with the booking number wanting to cancel their booking)

curl -X GET "https://staging-partner.api.hikoala.co/subscriptions/<bookingNumber>/contracts" -H "Content-Type: application/JSON" -H "accept: application/JSON" -H "Authorization: Bearer <token>"

Inside this payload, go inside the array containing the product type WITHDRAWAL and store the contract.id relating to the booking.

Step 2:

Make a POST on: (please replace the contract.id with the one that you found in step 1)

curl -X POST "https://staging-partner.api.hikoala.co/contracts/<contractId>/claims" -H "Content-Type: application/JSON" -H "accept: application/JSON" -H "Authorization: Bearer <token>" --data-raw '{"data": {}}'

If you did correctly those 2 steps, you should have received a 201 response. We are now aware of the traveler’s booking cancellation 👍

Provide a modification cost​

For products of type CHANGE_FOR_ANY_REASON you must provide a modificationCost field, which represents the cost of changing the reservation.

Make a POST on: (please replace the <contractId> with the one that you found in step 1)

curl -X POST "https://staging-partner.api.hikoala.co/contracts/<contractId>/claims" -H "Content-Type: application/JSON" -H "accept: application/JSON" -H "Authorization: Bearer <token>" --data-raw '{"data": {"modificationCost":"<modificationCost>", "productType":"CHANGE_FOR_ANY_REASON"}}'

Possible Contracts outputs​

Our Contracts API can send you back the following responses:

  • 201: The Claim is successfully created and the refund process has been initiated 🤩
  • 400: The Claim is invalid. You may have forgotten one mandatory field or made a mistake with one format.
  • 401: The Claim cannot be created because you are experimenting an issue with your token.
  • 404: There is no contract associated with the contractId that you have provided.

How to know a claim status​

If you want to know the status of a claim, you can make a GET on: (please replace the bookingNumber with the booking number you want to know the claim status)

curl -X GET "https://staging-partner.api.hikoala.co/subscriptions/<bookingNumber>/contracts" -H "Content-Type: application/JSON" -H "accept: application/JSON" -H "Authorization: Bearer <token>"

Inside this payload, go inside the array containing the product type WITHDRAWAL, go to claim and then refer to status.

The claim status are the following:

  • MORE_INFO_NEEDED -> Information is missing to determine the eligibility of the travelers.
  • MANUAL_VERIFICATION_NEEDED -> Suspicion of fraud has been detected for this claim. This happens when the claim creation date is too close to subscription creation (< 24 hours). In order to bypass this error, you can add claimDate in the payload to postDate the claim creation. This option is not available in production
  • ACCEPTED -> Travelers eligible for compensation, we are waiting for receiving their bank details.
  • REFUNDABLE -> Bank details received, the bank transfer has not been processed yet.
  • REFUNDED -> Bank transfer has been processed, the travelers have either received their compensation or will receive it shortly.
  • REJECTED -> Based on the information given, the traveler is not entitled to compensation.

If you want to be informed proactively of the claim status, you can subscribe to our webhook and receive a data feed of all the claims status changes 👀