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
Headers
{
"id": "8WD8Y-LTEKE-INS",
"status": "CONFIRMED",
"currency": "USD",
"total_price": 4.27,
"total_price_formatted": "US$4.27",
"partner_transaction_id": "id-to-stitch-transactions-in-two-systems",
"created_at": "2021-01-15T01:19:49.529799Z",
"updated_at": "2021-01-15T01:19:59.773302Z",
"pds_url": "https://staging.xcover.com/en/pds/8WD8Y-LTEKE-INS",
"security_token": "UiRlP-6bLfQ-1YLjR-ste66",
"quotes": [
{
"id": "201eb11b-4494-40e8-97fa-e107c76501bf",
"policy_start_date": "2021-01-17T13:00:00+00:00",
"policy_end_date": "2021-01-19T13:00:00+00:00",
"status": "CONFIRMED",
"price": 4.27,
"price_formatted": "US$4.27",
"policy": {
"policy_type": "event_ticket_protection",
"policy_name": "Missed Event Cover (Generic)",
"policy_code": "MECG0001",
"policy_version": "5d24e2d1-a341-4b8b-9917-82878470a9c3",
"category": "event_ticket_protection",
"content": {
"title": "Missed Event Cover for Justin Bibber",
"header": null,
"description": "90% of attendees add Missed Event Cover for generous protection when things go wrong or your plans change. For only per ticket it covers you - and all ticket holders - if:",
"optout_msg": "",
"disclaimer": "<p>This insurance is arranged by Cover Genius Ltd which is authorised and regulated by the FCA (No.750711). Policies are underwritten by Markel International Insurance Company Limited which is authorised by the PRA and regulated by the FCA, (No.202570).</p>"
},
"underwriter": {
"disclaimer": "This plan is arranged by XCover.com",
"name": "Cover Genius Pty Ltd"
},
"claim_selector_id": null
},
"insured": [
{
"id": "3aa30165-7a71-45ab-8899-f479fcb6e8e2",
"first_name": "Darin",
"last_name": "Sikanic",
"email": "[email protected]",
"region": null
}
],
"tax": {
"total_tax": 0.0,
"total_amount_without_tax": 4.27,
"total_tax_formatted": "US$0.00",
"total_amount_without_tax_formatted": "US$4.27",
"taxes": []
},
"duration": "2 00:00:00",
"benefits": [
{
"description": "Updated Transalation",
"limit": 7.77,
"limit_policy_currency": 10.0,
"limit_formatted": "US$7.77",
"limit_policy_currency_formatted": "A$10.00",
"excess": 3.88,
"excess_policy_currency": 5.0,
"excess_formatted": "US$3.88",
"excess_policy_currency_formatted": "A$5.00"
},
{
"description": "Updated Transalation",
"limit_description": "Benefit Text Test 01",
"excess": 4.66,
"excess_policy_currency": 6.0,
"excess_formatted": "US$4.66",
"excess_policy_currency_formatted": "A$6.00"
},
{
"description": "Description",
"limit": 11.65,
"limit_policy_currency": 15.0,
"limit_formatted": "US$11.65",
"limit_policy_currency_formatted": "A$15.00"
},
{
"description": "Description",
"limit": 15.54,
"limit_policy_currency": 20.0,
"limit_formatted": "US$15.54",
"limit_policy_currency_formatted": "A$20.00",
"excess_description": "Excess Text Test 01"
},
{
"description": "Description",
"limit_description": "Benefit Text Test 02",
"excess_description": "Excess Text Test 02"
}
],
"commission": {
"total_commission": 0.0,
"total_commission_formatted": "US$0.00"
},
"created_at": "2021-01-15T01:19:49.523137Z",
"confirmed_at": "2021-01-15T01:19:59.750719Z",
"updated_at": "2021-01-15T01:19:59.763517Z",
"cancelled_at": null,
"is_renewable": false,
"cover_amount": 77.7,
"cover_amount_formatted": "US$77.70",
"pds_url": "https://staging.xcover.com/en/pds/8WD8Y-LTEKE-INS?policy_type=event_ticket_protection_v1",
"attachments": [],
"files": [],
"extra_fields": {},
"next_renewal": null,
"can_be_cancelled": true
}
],
"coi": {
"url": "https://staging.xcover.com/en/coi/8WD8Y-LTEKE-INS?security_token=UiRlP-6bLfQ-1YLjR-ste66",
"pdf": "https://staging.xcover.com/en/coi/8WD8Y-LTEKE-INS.pdf?security_token=UiRlP-6bLfQ-1YLjR-ste66"
},
"account_url": "https://staging.xcover.com/en/account?id=0bde2670-c3f9-4e79-a837-063d5d5e3874&signup_token=zl4qR-wNoL5-fHZ4M-u0Lmb",
"policyholder": {
"first_name": "Ben",
"middle_name": null,
"last_name": "H",
"email": "[email protected]",
"phone": null,
"country": "US",
"age": null,
"address1": null,
"address2": null,
"city": null,
"postcode": null,
"region": "NYC",
"secondary_email": null,
"birth_date": null,
"company": null
},
"total_tax": 0.0,
"total_tax_formatted": "US$0.00",
"total_premium": 4.27,
"total_premium_formatted": "US$4.27",
"partner": {
"id": "87ZRF",
"name": "Generic Partner",
"title": "Generic Partner",
"logo": "https://staging.static.xcover.com/media/partnerlogos/2020/08/12/travel_logo.png",
"contact_url": "https://staging.xcover.com/en/about",
"partner_url": "https://staging.xcover.com",
"help_center_url": "https://staging.xcover.com/en/help/your-insurance",
"updated_at": "2020-10-28T07:48:24.671777Z",
"xpay_refund_enabled": false,
"subsidiary": {
"id": "87ZRF",
"name": "Generic Partner",
"title": "Generic Partner",
"logo": "https://staging.static.xcover.com/media/partnerlogos/2020/08/12/travel_logo.png",
"contact_url": "https://staging.xcover.com/en/about",
"partner_url": "https://staging.xcover.com",
"help_center_url": "https://staging.xcover.com/en/help/your-insurance",
"updated_at": "2020-10-28T07:48:24.671777Z",
"xpay_refund_enabled": false
}
},
"customer_language": "en"
}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
Ensure the fields you are modifying do not affect price. Speak to your assigned Client Solutions Engineer (CSE) before implementing this endpoint.
Modify Booking
PATCH https://api.xcover.com/x/partners/:partner_id/bookings/:quote_package_id/
Updates booking details instantly.
Path Parameters
Headers
{
"id": "8WD8Y-LTEKE-INS",
"status": "CONFIRMED",
"currency": "USD",
"total_price": 3.5,
"total_price_formatted": "US$3.50",
"partner_transaction_id": "id-to-stitch-transactions-in-two-systems",
"created_at": "2021-01-15T01:19:49.529799Z",
"updated_at": "2021-01-15T01:30:17.360948Z",
"pds_url": "https://staging.xcover.com/en/pds/8WD8Y-LTEKE-INS",
"security_token": "UiRlP-6bLfQ-1YLjR-ste66",
"quotes": [
{
"id": "201eb11b-4494-40e8-97fa-e107c76501bf",
"policy_start_date": "2021-01-17T13:00:00+00:00",
"policy_end_date": "2021-01-19T13:00:00+00:00",
"status": "CONFIRMED",
"price": 3.5,
"price_formatted": "US$3.50",
"policy": {
"policy_type": "event_ticket_protection",
"policy_name": "Missed Event Cover (Generic)",
"policy_code": "MECG0001",
"policy_version": "5d24e2d1-a341-4b8b-9917-82878470a9c3",
"category": "event_ticket_protection",
"content": {
"title": "Missed Event Cover for Justin Bibber",
"header": null,
"description": "90% of attendees add Missed Event Cover for generous protection when things go wrong or your plans change. For only per ticket it covers you - and all ticket holders - if:",
"optout_msg": "",
"disclaimer": "<p>This insurance is arranged by Cover Genius Ltd which is authorised and regulated by the FCA (No.750711). Policies are underwritten by Markel International Insurance Company Limited which is authorised by the PRA and regulated by the FCA, (No.202570).</p>"
},
"underwriter": {
"disclaimer": "This plan is arranged by XCover.com",
"name": "Cover Genius Pty Ltd"
},
"claim_selector_id": null
},
"insured": [
{
"id": "3aa30165-7a71-45ab-8899-f479fcb6e8e2",
"first_name": "Darin",
"last_name": "Sikanic",
"email": "[email protected]",
"region": null
}
],
"tax": {
"total_tax": 0.0,
"total_amount_without_tax": 3.5,
"total_tax_formatted": "US$0.00",
"total_amount_without_tax_formatted": "US$3.50",
"taxes": []
},
"duration": "2 00:00:00",
"benefits": [
{
"description": "Updated Transalation",
"limit": 7.77,
"limit_policy_currency": 10.0,
"limit_formatted": "US$7.77",
"limit_policy_currency_formatted": "A$10.00",
"excess": 3.88,
"excess_policy_currency": 5.0,
"excess_formatted": "US$3.88",
"excess_policy_currency_formatted": "A$5.00"
},
{
"description": "Updated Transalation",
"limit_description": "Benefit Text Test 01",
"excess": 4.66,
"excess_policy_currency": 6.0,
"excess_formatted": "US$4.66",
"excess_policy_currency_formatted": "A$6.00"
},
{
"description": "Description",
"limit": 11.65,
"limit_policy_currency": 15.0,
"limit_formatted": "US$11.65",
"limit_policy_currency_formatted": "A$15.00"
},
{
"description": "Description",
"limit": 15.54,
"limit_policy_currency": 20.0,
"limit_formatted": "US$15.54",
"limit_policy_currency_formatted": "A$20.00",
"excess_description": "Excess Text Test 01"
},
{
"description": "Description",
"limit_description": "Benefit Text Test 02",
"excess_description": "Excess Text Test 02"
}
],
"commission": {
"total_commission": 0.0,
"total_commission_formatted": "US$0.00"
},
"created_at": "2021-01-15T01:19:49.523137Z",
"confirmed_at": "2021-01-15T01:19:59.750719Z",
"updated_at": "2021-01-15T01:30:17.355406Z",
"cancelled_at": null,
"is_renewable": false,
"cover_amount": 38.85,
"cover_amount_formatted": "US$38.85",
"pds_url": "https://staging.xcover.com/en/pds/8WD8Y-LTEKE-INS?policy_type=event_ticket_protection_v1",
"attachments": [],
"files": [],
"extra_fields": {},
"next_renewal": null,
"can_be_cancelled": true,
"price_diff": -0.77,
"price_diff_formatted": "-US$0.77"
}
],
"coi": {
"url": "https://staging.xcover.com/en/coi/8WD8Y-LTEKE-INS?security_token=UiRlP-6bLfQ-1YLjR-ste66",
"pdf": "https://staging.xcover.com/en/coi/8WD8Y-LTEKE-INS.pdf?security_token=UiRlP-6bLfQ-1YLjR-ste66"
},
"account_url": "https://staging.xcover.com/en/account?id=0bde2670-c3f9-4e79-a837-063d5d5e3874&signup_token=zl4qR-wNoL5-fHZ4M-u0Lmb",
"policyholder": {
"first_name": "Ben",
"middle_name": null,
"last_name": "H",
"email": "[email protected]",
"phone": null,
"country": "US",
"age": null,
"address1": null,
"address2": null,
"city": null,
"postcode": null,
"region": "NYC",
"secondary_email": null,
"birth_date": null,
"company": null
},
"total_tax": 0.0,
"total_tax_formatted": "US$0.00",
"total_premium": 3.5,
"total_premium_formatted": "US$3.50",
"total_price_diff": -0.77,
"total_price_diff_formatted": "-US$0.77",
"update_id": "qh89u-AIB2k-34CC8-UPD"
}{
"quotes": [
{
"id": "{{quote_1_id}}",
"update_fields": {
"insured": [
{
"id": "{{insured_uuid}}",
"first_name": "Darin",
"last_name": "Sikanic",
"email": "[email protected]"
}
]
}
}
]
}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
Headers
{
"id": "8WD8Y-LTEKE-INS",
"status": "CONFIRMED",
"currency": "USD",
"total_price": 3.5,
"total_price_formatted": "US$3.50",
"partner_transaction_id": "id-to-stitch-transactions-in-two-systems",
"created_at": "2021-01-15T01:19:49.529799Z",
"updated_at": "2021-01-15T01:30:17.360948Z",
"pds_url": "https://staging.xcover.com/en/pds/8WD8Y-LTEKE-INS",
"security_token": "UiRlP-6bLfQ-1YLjR-ste66",
"quotes": [
{
"id": "201eb11b-4494-40e8-97fa-e107c76501bf",
"policy_start_date": "2021-01-17T13:00:00+00:00",
"policy_end_date": "2021-01-19T13:00:00+00:00",
"status": "CONFIRMED",
"price": 3.5,
"price_formatted": "US$3.50",
"policy": {
"policy_type": "event_ticket_protection",
"policy_name": "Missed Event Cover (Generic)",
"policy_code": "MECG0001",
"policy_version": "5d24e2d1-a341-4b8b-9917-82878470a9c3",
"category": "event_ticket_protection",
"content": {
"title": "Missed Event Cover for Justin Bibber",
"header": null,
"description": "90% of attendees add Missed Event Cover for generous protection when things go wrong or your plans change. For only per ticket it covers you - and all ticket holders - if:",
"optout_msg": "",
"disclaimer": "<p>This insurance is arranged by Cover Genius Ltd which is authorised and regulated by the FCA (No.750711). Policies are underwritten by Markel International Insurance Company Limited which is authorised by the PRA and regulated by the FCA, (No.202570).</p>"
},
"underwriter": {
"disclaimer": "This plan is arranged by XCover.com",
"name": "Cover Genius Pty Ltd"
},
"claim_selector_id": null
},
"insured": [
{
"id": "3aa30165-7a71-45ab-8899-f479fcb6e8e2",
"first_name": "Darin",
"last_name": "Sikanic",
"email": "[email protected]",
"region": null
}
],
"tax": {
"total_tax": 0.0,
"total_amount_without_tax": 3.5,
"total_tax_formatted": "US$0.00",
"total_amount_without_tax_formatted": "US$3.50",
"taxes": []
},
"duration": "2 00:00:00",
"benefits": [
{
"description": "Updated Transalation",
"limit": 7.77,
"limit_policy_currency": 10.0,
"limit_formatted": "US$7.77",
"limit_policy_currency_formatted": "A$10.00",
"excess": 3.88,
"excess_policy_currency": 5.0,
"excess_formatted": "US$3.88",
"excess_policy_currency_formatted": "A$5.00"
},
{
"description": "Updated Transalation",
"limit_description": "Benefit Text Test 01",
"excess": 4.66,
"excess_policy_currency": 6.0,
"excess_formatted": "US$4.66",
"excess_policy_currency_formatted": "A$6.00"
},
{
"description": "Description",
"limit": 11.65,
"limit_policy_currency": 15.0,
"limit_formatted": "US$11.65",
"limit_policy_currency_formatted": "A$15.00"
},
{
"description": "Description",
"limit": 15.54,
"limit_policy_currency": 20.0,
"limit_formatted": "US$15.54",
"limit_policy_currency_formatted": "A$20.00",
"excess_description": "Excess Text Test 01"
},
{
"description": "Description",
"limit_description": "Benefit Text Test 02",
"excess_description": "Excess Text Test 02"
}
],
"commission": {
"total_commission": 0.0,
"total_commission_formatted": "US$0.00"
},
"created_at": "2021-01-15T01:19:49.523137Z",
"confirmed_at": "2021-01-15T01:19:59.750719Z",
"updated_at": "2021-01-15T01:30:17.355406Z",
"cancelled_at": null,
"is_renewable": false,
"cover_amount": 38.85,
"cover_amount_formatted": "US$38.85",
"pds_url": "https://staging.xcover.com/en/pds/8WD8Y-LTEKE-INS?policy_type=event_ticket_protection_v1",
"attachments": [],
"files": [],
"extra_fields": {},
"next_renewal": null,
"can_be_cancelled": true,
"price_diff": -0.77,
"price_diff_formatted": "-US$0.77"
}
],
"coi": {
"url": "https://staging.xcover.com/en/coi/8WD8Y-LTEKE-INS?security_token=UiRlP-6bLfQ-1YLjR-ste66",
"pdf": "https://staging.xcover.com/en/coi/8WD8Y-LTEKE-INS.pdf?security_token=UiRlP-6bLfQ-1YLjR-ste66"
},
"account_url": "https://staging.xcover.com/en/account?id=0bde2670-c3f9-4e79-a837-063d5d5e3874&signup_token=zl4qR-wNoL5-fHZ4M-u0Lmb",
"policyholder": {
"first_name": "Ben",
"middle_name": null,
"last_name": "H",
"email": "[email protected]",
"phone": null,
"country": "US",
"age": null,
"address1": null,
"address2": null,
"city": null,
"postcode": null,
"region": "NYC",
"secondary_email": null,
"birth_date": null,
"company": null
},
"total_tax": 0.0,
"total_tax_formatted": "US$0.00",
"total_premium": 3.5,
"total_premium_formatted": "US$3.50",
"total_price_diff": -0.77,
"total_price_diff_formatted": "-US$0.77",
"update_id": "qh89u-AIB2k-34CC8-UPD"
}A reduction in ticket prices here is used as an example for a cause for policy value refund. See response in above section tab.
{
"quotes": [
{
"id": "{{quote_1_id}}",
"update_fields": {
"tickets": [
{"price": 25},
{"price": 25}
]
}
}
]
}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
Headers
{
"id": "8WD8Y-LTEKE-INS",
"status": "CONFIRMED",
"currency": "USD",
"total_price": 3.5,
"total_price_formatted": "US$3.50",
"partner_transaction_id": "id-to-stitch-transactions-in-two-systems",
"created_at": "2021-01-15T01:19:49.529799Z",
"updated_at": "2021-01-15T01:43:18.466465Z",
"pds_url": "https://staging.xcover.com/en/pds/8WD8Y-LTEKE-INS",
"security_token": "UiRlP-6bLfQ-1YLjR-ste66",
"quotes": [
{
"id": "201eb11b-4494-40e8-97fa-e107c76501bf",
"policy_start_date": "2021-01-17T13:00:00+00:00",
"policy_end_date": "2021-01-19T13:00:00+00:00",
"status": "CONFIRMED",
"price": 3.5,
"price_formatted": "US$3.50",
"policy": {
"policy_type": "event_ticket_protection",
"policy_name": "Missed Event Cover (Generic)",
"policy_code": "MECG0001",
"policy_version": "5d24e2d1-a341-4b8b-9917-82878470a9c3",
"category": "event_ticket_protection",
"content": {
"title": "Missed Event Cover for Justin Bibber",
"header": null,
"description": "90% of attendees add Missed Event Cover for generous protection when things go wrong or your plans change. For only per ticket it covers you - and all ticket holders - if:",
"optout_msg": "",
"disclaimer": "<p>This insurance is arranged by Cover Genius Ltd which is authorised and regulated by the FCA (No.750711). Policies are underwritten by Markel International Insurance Company Limited which is authorised by the PRA and regulated by the FCA, (No.202570).</p>"
},
"underwriter": {
"disclaimer": "This plan is arranged by XCover.com",
"name": "Cover Genius Pty Ltd"
},
"claim_selector_id": null
},
"insured": [
{
"id": "3aa30165-7a71-45ab-8899-f479fcb6e8e2",
"first_name": "Darin",
"last_name": "Sikanic",
"email": "[email protected]",
"region": null
}
],
"tax": {
"total_tax": 0.0,
"total_amount_without_tax": 3.5,
"total_tax_formatted": "US$0.00",
"total_amount_without_tax_formatted": "US$3.50",
"taxes": []
},
"duration": "2 00:00:00",
"benefits": [
{
"description": "Updated Transalation",
"limit": 7.77,
"limit_policy_currency": 10.0,
"limit_formatted": "US$7.77",
"limit_policy_currency_formatted": "A$10.00",
"excess": 3.88,
"excess_policy_currency": 5.0,
"excess_formatted": "US$3.88",
"excess_policy_currency_formatted": "A$5.00"
},
{
"description": "Updated Transalation",
"limit_description": "Benefit Text Test 01",
"excess": 4.66,
"excess_policy_currency": 6.0,
"excess_formatted": "US$4.66",
"excess_policy_currency_formatted": "A$6.00"
},
{
"description": "Description",
"limit": 11.65,
"limit_policy_currency": 15.0,
"limit_formatted": "US$11.65",
"limit_policy_currency_formatted": "A$15.00"
},
{
"description": "Description",
"limit": 15.54,
"limit_policy_currency": 20.0,
"limit_formatted": "US$15.54",
"limit_policy_currency_formatted": "A$20.00",
"excess_description": "Excess Text Test 01"
},
{
"description": "Description",
"limit_description": "Benefit Text Test 02",
"excess_description": "Excess Text Test 02"
}
],
"commission": {
"total_commission": 0.0,
"total_commission_formatted": "US$0.00"
},
"created_at": "2021-01-15T01:19:49.523137Z",
"confirmed_at": "2021-01-15T01:19:59.750719Z",
"updated_at": "2021-01-15T01:43:18.462228Z",
"cancelled_at": null,
"is_renewable": false,
"cover_amount": 38.85,
"cover_amount_formatted": "US$38.85",
"pds_url": "https://staging.xcover.com/en/pds/8WD8Y-LTEKE-INS?policy_type=event_ticket_protection_v1",
"attachments": [],
"files": [],
"extra_fields": {},
"next_renewal": null,
"can_be_cancelled": true,
"price_diff": -0.77,
"price_diff_formatted": "-US$0.77"
}
],
"coi": {
"url": "https://staging.xcover.com/en/coi/8WD8Y-LTEKE-INS?security_token=UiRlP-6bLfQ-1YLjR-ste66",
"pdf": "https://staging.xcover.com/en/coi/8WD8Y-LTEKE-INS.pdf?security_token=UiRlP-6bLfQ-1YLjR-ste66"
},
"account_url": "https://staging.xcover.com/en/account?id=0bde2670-c3f9-4e79-a837-063d5d5e3874&signup_token=zl4qR-wNoL5-fHZ4M-u0Lmb",
"policyholder": {
"first_name": "Ben",
"middle_name": null,
"last_name": "H",
"email": "[email protected]",
"phone": null,
"country": "US",
"age": null,
"address1": null,
"address2": null,
"city": null,
"postcode": null,
"region": "NYC",
"secondary_email": null,
"birth_date": null,
"company": null
},
"total_tax": 0.0,
"total_tax_formatted": "US$0.00",
"total_premium": 3.5,
"total_premium_formatted": "US$3.50",
"total_price_diff": -0.77,
"total_price_diff_formatted": "-US$0.77"
}
Last updated