When a customer modifies their reservation such that the price, location, or dates of the reservation change, we require the partner to let us know so we can modify the associated Weather Guarantee.

Changes that don't require a modification

Not all changes to a reservation require a modification to the Weather Guarantee, though it is sometimes simplest to modify the Weather Guarantee for any change. Changes that don't require a modification are:

Price: when the price of a reservation changes by less than 10%, it is acceptable to reuse the existing Weather Guarantee. For example, if a customer changes room type but the difference in price is 5%, then the existing guarantee can remain.
Location: when the location of a customer's reservation changes by less than 5km, it is acceptable to reuse the existing Weather Guarantee. For example, if a customer changes their campsite location from one side of the property to another side of the property.

Modifying a Weather Guarantee

There are different modification scenarios, but all of them follow the same general flow.

The partner will call Modify Guarantee with the Weather Guarantee ID and the required modification
The API will return a response with a list of proposed modifications and a flag indicating whether the customer must opt in to the change
The partner will present the modified Weather Guarantee details to the customer in their booking modification UI
When the customer confirms the change to their booking, the partner will call Confirm modification with the ID returned in step 2 if the modified Weather Guarantee is accepted or if the modification does not require the customer to opt in.
1. If the customer declines the change to the Weather Guarantee, the partner will call Decline Guarantee Quote.

Create Modification

Request

The Modify Guarantee endpoint accepts a request body containing the Guarantee ID and fields that indicate which part of the Weather Guarantee needs to be modified. The following fields can be passed in the request to indicate which part of the Guarantee to modify:

coverage_start_date: Modified booking start date (str, "YYYY-mm-dd" format)
coverage_end_date: Modified booking end date (str, "YYYY-mm-dd" format)
exposure_total_coverage_amount: Modified booking price (float)
coverage_start_hour_number: Modified coverage start hour (int)
coverage_end_hour_number: Modified coverage end hour (int)
exposure_name: Modified exposure name (str)
exposure_latitude: Modified exposure latitude (float)
exposure_longitude: Modified exposure longitude (float)
exposure_address: Modified exposure address (json)

It is possible to pass multiple fields and perform multiple modifications in a single request.

Response

All calls to Modify Guarantee will return the same response body, but certain modifications will need to be handled differently. There are two types of modifications: one type requires the customer to explicitly accept the change and the other type does not.

Customer Opt-In not Required

The following scenarios don't require the customer to accept the change:

The exposure_total_coverage_amount decreases which causes the cost of the Weather Guarantee to decrease proportionally
coverage_end_date is decreased or coverage_start_date is increased, causing the reservation to decrease in length within the original booking dates. For example, the original trip was October 20 to October 25, but the end date is changed to October 23 or the start date is changed to October 21. This will be accompanied by a decrease in the exposure_total_coverage_amount which will cause the price of the Guarantee to decrease proportionally.

In both cases, we decrease the cost of the Weather Guarantee proportionally with the decrease in the exposure_total_coverage_amount. If exposure_total_coverage_amount decreases by 25%, then the cost of the Weather Guarantee will also decrease by 25%.

The response body will look like the following when customer opt-in is not required:

{
    "modification_quote": {
        // quote body
    },
    "id": "497034f2-7cc6-46b4-8fbb-5f7ba8fbc1fc",
    "price_change": -3,
		"risk_rescored": false,
		"risk_rescored_reason": "",
		"user_opt_in_required": false,
    "reference_guarantee_id": "2f524226-d905-4950-a00e-4a01fd0533bb",
    "plain_language": {
        "coverage_changes": "Your weather guarantee was re-assessed and your coverage details may have changed."
    }
}

The partner should display the coverage_changes plain language to the customer in their booking modification UI, but the customer does not need to opt in again, which is reflected in user_opt_in_required being set to false.

Customer Opt-In Required

All other modification scenario requires the customer to opt-in to the new Weather Guarantee. These scenarios are:

The length of the trip increases, which can occur by the coverage_start_date moving up in time, the coverage_end_date moving back in time, or a combination of both. For example, the original trips dates are January 5 to January 10 and the coverage_end_date is changed to January 13.
The dates of the trip change such that none of the new dates overlap with the previous dates. For example, the original trip was February 3 to February 5 and the new dates are February 22 to February 24.
The exposure_total_coverage_amount increases which means the customer will be charged for the difference in cost between their existing Weather Guarantee and the new Weather Guarantee.
The location of the exposure changes. This is represented by a new exposure_address or a new combination of exposure_latitude and exposure_longitude. For example, a customer changes their tee time to another course that is 20 miles away.

In these cases, the price of the new Guarantee will change to reflect the new risk profile of the booking. This means the price may increase or decrease and the deductible hours may change. The response will look like the below

{
  "modification_quote": {
    // quote body
  },
  "id": "497034f2-7cc6-46b4-8fbb-5f7ba8fbc1fc",
  "price_change": -3,
  "risk_rescored": true,
  "risk_rescored_reason": "location modification outside of threshold",
  "user_opt_in_required": true,
  "reference_guarantee_id": "2f524226-d905-4950-a00e-4a01fd0533bb",
  "plain_language": {
    "coverage_changes": "Your weather guarantee was re-assessed and your coverage details may have changed."
  }
}

user_opt_in_required is now true, which means the customer must be presented the new Guarantee details and be given the opportunity to decline the new coverage.

Confirm Modification

Every modification should conclude with a confirmation or decline of the change. If the customer opts in to the change, or the change doesn't require an opt-in, then the partner will use the Confirm modification endpoint with the id returned in the Modify Guarantee response. The endpoint has an optional request body used to pass us the reservation ID if it has changed due to the modification:

{
  "reservation_id": "ABC123"
}

The response will contain the modified Weather Guarantee details:

{
  "id": "00000000-0000-0000-0000-000000000000",
  "product_id": "00000000-0000-0000-0000-000000000000",
  "offer_key": "",
  "created_at": "0001-01-01T00:00:00Z",
  "coverage_start_date": "",
  "coverage_end_date": "",
  "coverage_start_hour": "",
  "coverage_end_hour": "",
  "lang_locale": "und",
  "wholesale_price": 0,
  "suggested_price": 0,
  "tax_amount": 0,
  "tax_rate": 0,
  "tax_was_assessed": false,
  "expires_at": "0001-01-01T00:00:00Z",
  "currency": "XXX",
  "exposure_name": "",
  "exposure_latitude": 0,
  "exposure_longitude": 0,
  "exposure_total_coverage_amount": 0,
  "exposure_protections": null,
  "payout_tiers": null
}

If the customer declines the modified Weather Guarantee, then the partner will call Decline Guarantee Quote with the id returned in Modify Guarantee.