Cancellation Workflow
Cancel a specific policy booking
Cancelling a policy booking is used where a user no longer requires coverage, and has contacted the partner directly to cancel this policy.
For example: Cancellation of a Product insurance policy where the product is on-sold or no longer needed. Where a refund is due, the partner (depending on method of payment collection, and policy cooling off period) may need to provide a refund to the user. This calculated pro-rata refund for the user (where applicable) is returned in the Cancellation response.
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
partner_id
string
Unique Partner Code
quote_package_id
string
Quote Package ID (INS)
Headers
Content-Type
string
application/json
Date
string
Current Datetime
Authorization
string
HMAC Signature
X-Api-Key
string
API Key
{
"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 Cancellation
Once a booking has been retrieved, check the can_be_cancelled flag is set to true in the response before issuing a cancellation request.
To ensure you refund the correct amount to the customer, it is recommended to first preview a cancellation and then confirm the cancellation once you have successfully issued the refund.
Cancel Booking
POST https://api.xcover.com/x/partners/:partner_id/bookings/:quote_package_id/cancel
The booking cancel endpoint accepts a JSON payload against the URI containing the Quote Package ID returned by a /booking request. The payload consists of a list of quotes selected for cancellation and an optional reason for the cancellation.
Path Parameters
partner_id
string
Unique Partner Code
quote_package_id
string
Quote Package ID
Headers
Content-Type
string
application/json
Date
string
Current Datetime
Authorization
string
HMAC Signature
X-Api-Key
string
API Key
{
"id": "string",
"status": "string",
"quotes": [
{
"id": "string",
"policy_start_date": "2020-09-25T05:31:10Z",
"policy_end_date": "2020-09-25T05:31:10Z",
"policy_cancellation_date": "2020-09-25T05:31:10Z",
"policy_coolingoff_date": "2020-09-25T05:31:10Z",
"status": "string",
"price": 0,
"refund_value": 0,
"adjustment_fee": 0,
"policy": {
"policy_type": "string",
"policy_name": "string",
"policy_code": "string",
"policy_version": "string",
"category": "string",
"content": {
"title": "string",
"header": "string",
"description": "string",
"optout_msg": "string",
"inclusions": [
{
"title": "string",
"description": "string"
}
],
"exclusions": [
{
"title": "string",
"description": "string"
}
],
"disclaimer": "string",
"disclaimer_html": "string"
},
"underwriter": {
"disclaimer": "string",
"name": "string"
}
},
"insured": [
{
"id": "string",
"first_name": "string",
"middle_name": "string",
"last_name": "string",
"email": "[email protected]",
"country": "AF",
"address1": "string",
"address2": "string",
"city": "string",
"postcode": "string",
"region": "string",
"phone": "string",
"age": 0,
"birth_date": "2020-09-25",
"metadata": {
"property1": "string",
"property2": "string"
},
"company": "string"
}
],
"created_at": "2020-09-25T05:31:10Z",
"confirmed_at": "2020-09-25T05:31:10Z",
"updated_at": "2020-09-25T05:31:10Z",
"cancelled_at": "2020-09-25T05:31:10Z"
}
],
"policyholder": {
"first_name": "string",
"middle_name": "string",
"last_name": "string",
"email": "[email protected]",
"phone": "string",
"country": "AF",
"age": 0,
"address1": "string",
"address2": "string",
"city": "string",
"postcode": "string",
"region": "string",
"secondary_email": "[email protected]",
"birth_date": "2020-09-25",
"company": "string",
"tax_payer_id": "string"
},
"pds_url": "http://example.com",
"coi": {
"pdf": "http://example.com",
"url": "http://example.com"
},
"created_at": "2020-09-25T05:31:10Z",
"updated_at": "2020-09-25T05:31:10Z",
"total_price": 0,
"total_price_formatted": "string",
"total_refund": 0,
"total_refund_formatted": "string",
"total_tax": 0,
"total_tax_formatted": "string",
"total_premium": 0,
"total_premium_formatted": "string",
"currency": "str",
"cancellation_id": "string",
"confirm_before": "2020-09-25T05:31:10Z",
"partner": {
"id": "string",
"name": "string",
"title": "string",
"logo": "http://example.com",
"contact_url": "http://example.com",
"partner_url": "http://example.com",
"help_center_url": "http://example.com",
"updated_at": "2020-09-25T05:31:10Z",
"xpay_refund_enabled": true,
"subsidiary": {
"id": "string",
"name": "string",
"title": "string",
"logo": "http://example.com",
"contact_url": "http://example.com",
"partner_url": "http://example.com",
"help_center_url": "http://example.com"
}
}
}{
"quotes": [
{
"id": "62fd1f8b-f8fa-420a-82a0-6990976fb8cc",
"reason_for_cancellation": "No longer travelling"
}
]
}Preview a Cancellation
An optional preview flag can be set to true in the booking cancellation request payload, the response will confirm a refund amount and timeframe required before cancellation can be completed.
Preview Cancellation
POST https://api.xcover.com/x/partners/:partner_id/bookings/:quote_package_id/cancel
The booking cancel endpoint accepts a JSON payload against the URI containing the Quote Package ID returned by a /booking request. The payload consists of a the preview flag set to true along with a list of quotes selected for cancellation and an optional reason for the cancellation.
Path Parameters
partner_id
string
Unique Partner Code
quote_package_id
string
Quote Package ID
Headers
Content-Type
string
application/json
Date
string
Current Datetime
Authorization
string
HMAC Signature
X-Api-Key
string
API Key
{
"id": "8UHPK-ALPQT-INS",
"status": "CANCELLED",
"quotes": [
{
"id": "d5465e90-f22f-477a-b0cc-2950fcf034ff",
"policy_start_date": "2021-01-07T18:18:48Z",
"policy_end_date": "2021-01-17T15:45:00Z",
"policy_cancellation_date": null,
"policy_coolingoff_date": "2021-01-21T18:18:59.940059Z",
"status": "CANCELLED",
"price": 22.4,
"refund_value": 22.4,
"adjustment_fee": 0.0,
"created_at": "2021-01-07T18:18:49.035218Z",
"confirmed_at": "2021-01-07T18:18:59.940059Z",
"updated_at": "2021-01-07T18:19:04.222570Z",
"cancelled_at": null
}
],
"created_at": "2021-01-07T18:18:49.145872Z",
"updated_at": "2021-01-07T18:18:59.958252Z",
"total_price": 0.0,
"total_price_formatted": "€0.00",
"total_refund": 22.4,
"total_refund_formatted": "22.40",
"currency": "EUR",
"cancellation_id": "90o3N-fIexx-Zw2bd-CCL",
"confirm_before": "2021-01-08T18:19:04.228699Z"
}
{
"preview": true,
"quotes": [
{
"id": "62fd1f8b-f8fa-420a-82a0-6990976fb8cc",
"reason_for_cancellation": "No longer travelling"
}
]
}Confirm Cancellation
To confirm a cancellation that has been previewed a request to the following endpoint needs to be made.
Confirm Cancellation
POST https://api.xcover.com/x/partners/:partner_id/bookings/:quote_package_id/confirm_cancellation
Confirm the previewed cancellation.
Path Parameters
partner_id
string
Unique Parter Code
quote_package_id
string
Quote Package ID
cancellation_id
string
Cancellation ID
Headers
Content-Type
string
application/json
Date
string
Current Datetime
Authorization
string
HMAC Signature
X-Api-Key
string
API Key
{
"id": "8UHPK-ALPQT-INS",
"status": "CANCELLED",
"quotes": [
{
"id": "d5465e90-f22f-477a-b0cc-2950fcf034ff",
"policy_start_date": "2021-01-07T18:18:48Z",
"policy_end_date": "2021-01-17T15:45:00Z",
"policy_cancellation_date": null,
"policy_coolingoff_date": "2021-01-21T18:18:59.940059Z",
"status": "CANCELLED",
"price": 22.4,
"refund_value": 22.4,
"adjustment_fee": 0.0,
"created_at": "2021-01-07T18:18:49.035218Z",
"confirmed_at": "2021-01-07T18:18:59.940059Z",
"updated_at": "2021-01-07T18:19:04.222570Z",
"cancelled_at": null
}
],
"created_at": "2021-01-07T18:18:49.145872Z",
"updated_at": "2021-01-07T18:18:59.958252Z",
"total_price": 0.0,
"total_price_formatted": "€0.00",
"total_refund": 22.4,
"total_refund_formatted": "22.40",
"currency": "EUR",
"cancellation_id": "90o3N-fIexx-Zw2bd-CCL",
"confirm_before": "2021-01-08T18:19:04.228699Z"
}
Last updated
Was this helpful?