Request template

book is the request template the widget prepares for you and keeps up to date as the basket changes, on window.CTStore.koala.basketPayload.book and on each onBasket event as data.book. When and how to send it is explained in the concepts page Creating the subscription.

What the widget gives you

Click a property to see the shape it carries; msgRaw shows both request shapes:

book

The prepared request, on basketPayload.book and on the onBasket event data.book.

• The body of the subscription request.

  • data

    • Example'5K7SXD'

      Constraints4 to 255 characters. Must be unique across your bookings.
    • ConstraintsAt least one entry.

      Quote

      One selected bundle, referencing the quote it was priced from.

      • referencestringrequiredThe quote this policy is based on. Filled by the widget; leave it as is.
      • ConstraintsExactly the travellers the quote was priced for, in the same order.

        Traveler

        An insured traveller on the policy. One entry per traveller you sent in the trip context, in the same order.

        • Example'ADULT'

          ConstraintsINFANT is 0 to 23 months old, CHILD 2 to 11 years, ADULT 12 to 64 years, SENIOR 65 years and over.
        • Example'[TRAVELER_1_FIRSTNAME]'

          Constraints1 to 255 characters.
        • Example'[TRAVELER_1_LASTNAME]'

          Constraints1 to 255 characters.
        • Example'IE'
        • Example1
    • Customer

      The policyholder and main contact.

      • Constraints1 to 255 characters.
      • Constraints1 to 255 characters.
      • Example'mary.dancer@gmail.com'

        ConstraintsA valid email address, 255 characters at most.
      • Example'en-GB'

        Constraints5 characters: an ISO 639-1 language code and an ISO 3166-1 region code. It sets the language of our communications with the travellers.
    • Payment

      Card details. Only required when Koala is the merchant of record.

      • cardType'CREDIT' | 'DEBIT'Card type.
      • Example'VI'

        ConstraintsOne of VI (Visa), MC (Mastercard), AX (American Express), DI (Discover), DC (Diners Club), JC (JCB), MA (Maestro).
      • cardNumberstringrequiredCard number.
      • expirationDatestringrequiredExpiration date of the card.
      • seriesCodestringrequiredSeries code (CVV).
      • cardHolderNamestringrequiredName of the card holder.
• fullUrlstringWhere to send it, by HTTP POST. Filled by the widget; leave it as is.

What you fill in

Every value the widget cannot know is a placeholder string in the form [TOKEN]; find and replace each before sending:

data.bookingNumberin both request shapes

[BOOKINGNUMBER]your booking number4 to 255 characters, unique across your bookings.

data.customerthe policyholder

[CUSTOMER_FIRSTNAME]their first name1 to 255 characters.[CUSTOMER_LASTNAME]their last name1 to 255 characters.[CUSTOMER_EMAIL]their emailA valid email address, 255 characters at most.[CUSTOMER_LANGUAGE]their language, e.g. 'en-GB'5 characters: an ISO 639-1 language code and an ISO 3166-1 region code.

data.quotes[].travelers[]each insured travellerone pair per traveller

[TRAVELER_n_FIRSTNAME]the first name of traveller n1 to 255 characters. n is the position of the traveller, counting from 1.[TRAVELER_n_LASTNAME]the last name of traveller n1 to 255 characters. n is the position of the traveller, counting from 1.

data.paymentthe card detailsonly when Koala is the merchant of record

[CARDTYPE]the card type'CREDIT' or 'DEBIT'.[CARDCODE]the card network code'VI', 'MC', 'AX', 'DI', 'DC', 'JC' or 'MA'.[CARDNUMBER]the card number[EXPIREDATE]the expiration date[SERIESCODE]the series code (CVV)[CARDHOLDERNAME]the card holder name

The deleted-quote request carries only [BOOKINGNUMBER]; everything else in it is already complete, so leave it as prepared.

Every token is unique

No token appears twice in the payload, so you can replace them across the whole request body without any risk of one value landing somewhere it does not belong:

• the policyholder's tokens are prefixed with CUSTOMER_, so they cannot collide with a traveller's name;
• each traveller's name tokens carry that traveller's position, [TRAVELER_1_FIRSTNAME], [TRAVELER_2_FIRSTNAME], and so on.

Positions count from 1 and follow the order of the travellers you sent in the trip context, so [TRAVELER_2_LASTNAME] is the second entry of your dataSource.travelers array. When Koala derived the travellers from the car-rental passengers counts instead, the order is adults (including teens), then children, then infants.

What you get back

Creating the subscription returns 201 with the created policies; deleting the quote returns 204 with no body:

SubscriptionResponse

The body returned with 201 when the subscription is created.

• data

  • Example'5K7SXD'
  • ConstraintsAt least one entry.

    Contract

    A policy issued by the subscription. One entry per selected bundle.

    • Example'94e70133-8108-4ed8-a929-8ded4113311c'

      ConstraintsA UUID.
    • Example{ type: 'FLIGHT_DISRUPTION', name: 'Flight Disruption Compensation', coveredEventType: 'TRIP' }
    • coveredEventobjectrequiredThe covered trip or flight, echoing what was quoted.
    • ContractTraveler

      A traveller covered by the contract, with the name you filled in.

      • Example'ADULT'
      • Example'Mary'
      • Example'Dancer'
      • Example'IE'

        ConstraintsISO 3166-1 alpha-2.
    • Price

      A monetary amount.

      • Example103.86

        ConstraintsA number with at most 2 decimals.
      • Example'EUR'

        ConstraintsISO 4217.
    • Example'2026-09-14T08:21:00+02:00'
  • Price

    A monetary amount.

    • Example103.86

      ConstraintsA number with at most 2 decimals.
    • Example'EUR'

      ConstraintsISO 4217.

Keep data.contracts[].id with your booking: it is how a policy is identified when you interact with Koala about it.

A duplicate subscription request is rejected with 409, because its booking number and its quote have already been used. What to do on a failure, retries included, is explained in Creating the subscription.