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

Cancel Booking

Cancel Booking

post

Cancel a policy booking when a customer no longer requires coverage. This endpoint supports two modes controlled by the preview field:

  • Preview mode (preview: true): Calculate the refund amount without cancelling. Returns a cancellation_id for use with the Confirm Cancellation endpoint.

  • Immediate cancellation (preview: false or omitted): Cancel the booking immediately and process any applicable refunds.

Use preview mode when you need customer confirmation before finalizing the cancellation.

Authorizations
AuthorizationstringRequired

Composite Authentication Scheme (Client Key, Date, and Signature)

This scheme requires the client to provide three mandatory headers in every request:

1. X-Api-Key (Client Key)

  • Purpose: Public identifier for the API consumer.
  • Example: X-Api-Key: YOUR_API_KEY_HERE

2. Date (Timestamp)

  • Purpose: Timestamp used for generating the signature and preventing replay attacks.
  • Format: RFC 7231 format (e.g., in GMT).
  • Example: Date: Sun, 09 Nov 2025 04:04:00 GMT

3. Authorization (Computed Signature)

  • Purpose: The cryptographic signature that verifies the request's authenticity and integrity.
  • Format: SIGNATURE [authHeader]

Signature Generation Logic: The authHeader value is derived from a cryptographic hash (e.g., HMAC-SHA256) of canonical request components (HTTP Method, Path, and the contents of the Date header), signed with the private Client Secret.

Path parameters
partner_codestringRequired

Partner code identifier. Client Solutions Engineer (CSE) should provide this value.

booking_idstringRequired

The booking ID returned from the Confirm Offer endpoint.

Body
previewbooleanOptional
refund_requiredbooleanOptional
Responses
200

OK - cancelled

application/json
post/partners/{partner_code}/bookings/{booking_id}/cancel
POST /x/partners/{partner_code}/bookings/{booking_id}/cancel HTTP/1.1
Host: api.xcover.com
Authorization: YOUR_API_KEY
Content-Type: application/json
Accept: */*
Content-Length: 97

{
  "preview": true,
  "refund_required": true,
  "quotes": [
    {
      "id": "text",
      "reason_for_cancellation": "text"
    }
  ]
}
{
  "id": "text",
  "status": "text",
  "quotes": [
    {
      "id": "text",
      "policy_start_date": "2026-01-01T00:00:00.000Z",
      "policy_end_date": "2026-01-01T00:00:00.000Z",
      "policy_cancellation_date": "2026-01-01T00:00:00.000Z",
      "policy_coolingoff_date": "2026-01-01T00:00:00.000Z",
      "status": "text",
      "price": 1,
      "refund_value": 1,
      "adjustment_fee": 1,
      "policy": {
        "policy_type": "text",
        "policy_type_version": "text",
        "policy_type_slug": "text",
        "policy_type_group_name": "text",
        "policy_name": "text",
        "policy_code": "text",
        "policy_version": "text",
        "category": "text",
        "content": {
          "title": "text",
          "header": null,
          "description": "text",
          "optout_msg": "text",
          "inclusions": [],
          "exclusions": [],
          "disclaimer": "text",
          "disclaimer_html": "text",
          "payment_disclaimer": "text",
          "in_path_disclaimer": "text"
        },
        "underwriter": {
          "disclaimer": "text",
          "name": "text"
        },
        "claim_selector_id": null,
        "policy_currency": "text"
      },
      "insured": [
        {
          "id": "text",
          "first_name": "text",
          "last_name": "text",
          "email": "[email protected]",
          "region": null
        }
      ],
      "created_at": "2026-01-01T00:00:00.000Z",
      "confirmed_at": "2026-01-01T00:00:00.000Z",
      "updated_at": "2026-01-01T00:00:00.000Z",
      "cancelled_at": "2026-01-01T00:00:00.000Z",
      "cancelled_from": "2026-01-01T00:00:00.000Z",
      "commission": null
    }
  ],
  "policyholder": {
    "first_name": "text",
    "last_name": "text",
    "email": "[email protected]",
    "phone": "text",
    "address1": null,
    "address2": null,
    "postcode": "text",
    "company": null,
    "company_reg_id": null,
    "middle_name": null,
    "country": "text",
    "age": 1,
    "city": null,
    "region": "text",
    "secondary_email": null,
    "birth_date": null,
    "allow_updates": true,
    "fields_allowed_to_update": []
  },
  "pds_url": "https://example.com",
  "coi": {
    "url": "https://example.com",
    "pdf": "https://example.com"
  },
  "created_at": "2026-01-01T00:00:00.000Z",
  "updated_at": "2026-01-01T00:00:00.000Z",
  "total_price": 1,
  "total_price_formatted": "text",
  "total_refund": 1,
  "total_refund_formatted": "text",
  "total_tax": 1,
  "total_tax_formatted": "text",
  "total_premium": 1,
  "total_premium_formatted": "text",
  "currency": "text",
  "cancellation_id": null,
  "confirm_before": null,
  "partner": {
    "id": "text",
    "slug": "text",
    "name": "text",
    "title": "text",
    "logo": "https://example.com",
    "contact_url": "https://example.com",
    "partner_url": "https://example.com",
    "help_center_url": "https://example.com",
    "updated_at": "2026-01-01T00:00:00.000Z",
    "xpay_payment_enabled": true,
    "xpay_b2c_payment_enabled": true,
    "xpay_refund_enabled": true,
    "automatic_refund_by_xcore": true,
    "allow_policy_modifications_on_xcover": true,
    "emails": [],
    "attributes": {},
    "signup_method_on_xcover": null,
    "use_standard_region": null,
    "allow_payout_customer": true,
    "eligible_for_xpay_charge_retry": true,
    "subsidiary": {
      "id": "text",
      "slug": "text",
      "name": "text",
      "title": "text",
      "logo": "https://example.com",
      "contact_url": "https://example.com",
      "partner_url": "https://example.com",
      "help_center_url": "https://example.com",
      "updated_at": "2026-01-01T00:00:00.000Z",
      "xpay_payment_enabled": true,
      "xpay_b2c_payment_enabled": true,
      "xpay_refund_enabled": true,
      "automatic_refund_by_xcore": true,
      "allow_policy_modifications_on_xcover": true,
      "emails": [],
      "attributes": {},
      "signup_method_on_xcover": null,
      "use_standard_region": null,
      "allow_payout_customer": true,
      "eligible_for_xpay_charge_retry": true
    }
  },
  "refund_amount": 1,
  "refund_amount_formatted": "text",
  "cancellation_payout_url": null
}

Cancel Booking - confirm

post

Confirm and finalize a previously previewed cancellation. This endpoint completes the cancellation process initiated by calling Cancel Booking with preview: true. You must provide the cancellation_id returned from the preview request. The cancellation will be processed and any applicable refunds will be issued.

Authorizations
AuthorizationstringRequired

Composite Authentication Scheme (Client Key, Date, and Signature)

This scheme requires the client to provide three mandatory headers in every request:

1. X-Api-Key (Client Key)

  • Purpose: Public identifier for the API consumer.
  • Example: X-Api-Key: YOUR_API_KEY_HERE

2. Date (Timestamp)

  • Purpose: Timestamp used for generating the signature and preventing replay attacks.
  • Format: RFC 7231 format (e.g., in GMT).
  • Example: Date: Sun, 09 Nov 2025 04:04:00 GMT

3. Authorization (Computed Signature)

  • Purpose: The cryptographic signature that verifies the request's authenticity and integrity.
  • Format: SIGNATURE [authHeader]

Signature Generation Logic: The authHeader value is derived from a cryptographic hash (e.g., HMAC-SHA256) of canonical request components (HTTP Method, Path, and the contents of the Date header), signed with the private Client Secret.

Path parameters
partner_codestringRequired

Partner code identifier. Client Solutions Engineer (CSE) should provide this value.

booking_idstringRequired

The booking ID returned from the Confirm Offer endpoint.

cancellation_idstringRequired

The cancellation ID returned from the Cancel Booking endpoint.

Body
reason_for_cancellationstringOptional
Responses
200

OK

post/partners/{partner_code}/bookings/{booking_id}/confirm_cancellation/{cancellation_id}/
POST /x/partners/{partner_code}/bookings/{booking_id}/confirm_cancellation/{cancellation_id}/ HTTP/1.1
Host: api.xcover.com
Authorization: YOUR_API_KEY
Content-Type: application/json
Accept: */*
Content-Length: 34

{
  "reason_for_cancellation": "text"
}
No content
PreviousConfirm Booking
NextResponses

Last updated

Was this helpful?