Modification Workflow

Modifying an existing booked policy

The modification workflow is used when a customer wants to make a change to their existing policy. Examples could include; changing the date of an overseas vacation, increasing the item value or value of goods in a container, or changing the date of an event.

These changes may be possible for certain policies and can be done using the Booking Update API endpoints. These changes, if available, will cause a difference in policy price which may result in a refund or additional fee depending on the changes made.

The below diagram illustrates the API calls needed to successfully modify a customers policy.

Booking Retrieval

The first step is to obtain information regarding the customers purchased insurance, this step can be skipped if you have stored all relevant information about a customers insurance booking such as INS number, Quote IDs, price paid, etc.

Retrieve a Booking

GET https://api.xcover.com/x/partners/:partner_id/bookings/:quote_package_id

Retrieves a specific booking by providing the quote package ID.

Path Parameters

Name
Type
Description

partner_id

string

Unique Partner Code

quote_package_id

string

Quote Package ID (INS)

Headers

Name
Type
Description

Content-Type

string

application/json

Date

string

Current Datetime

Authorization

string

HMAC Signature

X-Api-Key

string

API Key

Booking Modification

In some circumstances a modification will not impact the premium price of a specific policy. This could be for a variety of reasons where additional information is supplied to enhance the profile of a policy, covered item, or insured party. Examples of such use cases: - Manufacturer or serial number information received after the policy booking - Product receipt or ownership verification documents or images - Address or phone number information updates for the insured

Modify Booking

PATCH https://api.xcover.com/x/partners/:partner_id/bookings/:quote_package_id/

Updates booking details instantly.

Path Parameters

Name
Type
Description

partner_id

string

Unique Partner Code

quote_package_id

string

Quote Package ID (INS)

Headers

Name
Type
Description

Content-Type

string

application/json

Date

string

Current Datetime

Authorization

string

HMAC Signature

X-API-Key

string

API Key

Preview Modification - Quote for Booking Update.

A request to the quote_for_booking_update endpoint will include the details of the policy that have changed the response will include the outstanding amount to be charged or refunded.

After calling the quote_for_booking_update endpoint, and once partial refund or any additional charge is collected, a confirm update request is submitted to complete the booking update workflow.

Preview Modification

PATCH https://api.xcover.com/x/partners/:partner_id/bookings/:quote_package_id/quote_for_update

Generates a Quote for booking changes as specified in the request which can then be confirmed using the endpoint specified in the Response

Path Parameters

Name
Type
Description

partner_id

string

Unique Partner Code

quote_package_id

string

Quote Package ID (INS)

Headers

Name
Type
Description

Content-Type

string

application/json

Date

string

Current Datetime

Authorization

string

HMAC Signature

X-API-Key

string

API Key

A reduction in ticket prices here is used as an example for a cause for policy value refund. See response in above section tab.

Confirm Modification

To confirm a modification that has been previewed a request to the following endpoint needs to be made.

Confirm Modification

POST https://api.xcover.com/x/partners/:partner_id/bookings/:quote_package_id/confirm_update/:update_id/

Confirm the booking update and charge or refund. Optionally include the charge ID reference. Request contains no payload.

Path Parameters

Name
Type
Description

partner_id

string

Unique Partner ID

quote_package_id

string

Quote Package ID (INS)

update_id

string

ID referencing the update

Headers

Name
Type
Description

Content-Type

string

application/json

Date

string

Current Datetime

Authorization

string

HMAC Signature

X-API-Key

string

API Key

Last updated

Was this helpful?