Ctrlk
Contact Us
For the complete documentation index, see llms.txt. This page is also available as Markdown.

Modify Booking

Modifying an existing booked policy

The modification workflow is used when a customer wants to make changes to their existing policy. This endpoint allows you to update policy details which may result in price adjustments, refunds, or additional fees.

Use Cases

Common modification scenarios include:

  • Travel Insurance - Changing the date of an overseas vacation

  • Product Insurance - Increasing the item value or value of goods

  • Event Insurance - Changing the date of an event

  • General Updates - Modifying insured persons, coverage amounts, or policy dates

Modification Workflow

Step 1: Booking Retrieval

First, obtain information about the customer's purchased insurance. This step can be skipped if you have stored all relevant information such as:

  • INS number (booking ID)

  • Quote IDs

  • Price paid

  • Current policy details

Use the GET /partners/{partner_code}/bookings/{booking_id} endpoint to retrieve current booking details if needed.

Step 2: Preview Modification (Optional but Recommended)

Before applying changes, use the Modify booking - preview endpoint (/partners/{partner_code}/bookings/{booking_id}/quote_for_update) to:

  • See the new price after modifications

  • Calculate any refund or additional fee

  • Validate that the modification is possible

  • Display the price difference to the customer for approval

Step 3: Apply Modification

Once the customer approves the changes, call this endpoint to apply the modification.

Making a Modify Booking Request

Path Parameters

  • partner_code - Your partner identifier

  • booking_id - The booking ID (INS number) to modify

Request Body

  • quotes (required) - Array of quote modifications, each containing:

    • id (required) - The quote ID to modify

    • policy_start_date (optional) - New policy start date

    • update_fields (required) - Object containing fields to update:

      • insured - Updated list of insured persons

      • Other policy-specific fields that can be modified

Price Changes

Modifications may result in:

  • Additional Fee - If the new coverage costs more (customer pays the difference)

  • Refund - If the new coverage costs less (customer receives pro-rata refund)

  • No Change - If the modification doesn't affect pricing

The response will include price_diff and price_diff_formatted fields showing the price adjustment.

Response Status Codes

  • HTTP 200 OK - Modification successfully applied

  • HTTP 403 Forbidden - Authentication or authorization error

  • HTTP 422 Unprocessable Entity - Validation error or modification not allowed

Important Notes

Policy Restrictions: Not all policies support modifications. Check the policy terms and the fields_allowed_to_update field in the booking response.

Price Validation: Always preview the modification first to show the customer any price changes before applying.

Refund Handling: If a refund is due, the partner may need to process the refund to the customer depending on the payment method and policy cooling-off period.

Modification Limits: Some modifications may not be allowed after certain time periods or once the policy has started.

Best Practices

  1. Always use the preview endpoint before applying modifications

  2. Display price changes clearly to the customer

  3. Obtain customer confirmation before applying changes that increase the price

  4. Store the modification history for customer service purposes

  5. Handle refunds promptly according to your payment provider's processes

PreviousOpt-out OfferNextCancel Booking

Last updated

Was this helpful?