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

Cancellation

Replace the RentalCover cancel call with the Offers API preview and confirm cancellation flow.

On RentalCover, a single call cancels the booking. On the Offers API you can preview the refund first, then confirm. A single call still works if you don't need the preview. The booking is identified by its INS in the URL.

1

Preview the refund (optional)

Use the preview when the customer should see the refund before agreeing, or when an adjustment fee may apply. Nothing is cancelled yet.

POST /insurances/cancel/{reference}
{ "CancelReason": "Customer trip has been cancelled" }
POST /partners/{partner_code}/bookings/{booking_id}/cancel
{ "preview": true }

Response (trimmed):

{
  "id": "XXXXX-XXXXX-INS",
  "quotes": [
    { "id": "{quote_id}", "price": 52.51, "refund_value": 52.51, "adjustment_fee": 0 }
  ],
  "total_refund": 52.51,
  "cancellation_id": "{cancellation_id}",
  "confirm_before": "2027-02-21T17:04:09Z"
}

Show total_refund to the customer and keep the cancellation_id.

2

Confirm the cancellation

POST /partners/{partner_code}/bookings/{booking_id}/confirm_cancellation/{cancellation_id}/

Send an x-idempotency-key. The booking moves to CANCELLED, and the response has the final refund_value, adjustment_fee and total_refund.

If confirm_before has passed, request a new preview.

3

Or cancel in one step

For automated cancellations, such as a rental cancelled by the supplier, skip the preview. The body is optional.

POST /partners/{partner_code}/bookings/{booking_id}/cancel
{
  "quotes": [
    { "id": "{quote_id}", "reason_for_cancellation": "Customer no longer needs cover" }
  ]
}

Rules

  • Cancellation window. The window and any grace period after pickup are set per integration, usually to match your current RentalCover terms. Send an accurate pickup.date with its offset at Create Offer.

  • Outside the window the call returns an error. Show the customer a message instead of retrying.

  • Already cancelled? A cancel call with a new idempotency key on a cancelled booking returns an error. Check with Get Booking and treat CANCELLED as success.

  • Not sure it worked? After a timeout, call Get Booking. If the status is still CONFIRMED, retry with the same idempotency key.

  • Refunds under single payment. Refund the customer refund_value, not the full premium, whenever an adjustment_fee applies. Under dual payment, Cover Genius refunds the card.

Rebooking

If your platform changes a booking by cancelling it and creating a new one, mark the new booking as a rebooking:

  1. Cancel the existing booking with "reason_for_cancellation": "Cancel and rebook".

  2. Create a new offer with these extra partner.metadata fields:

    "metadata": {
      "rebooking": true,
      "rebooking_prior_id": "XXXXX-XXXXX-INS"
    }
  3. Confirm the new offer. It gets its own INS, so store it and link it to the old one.

rebooking and rebooking_prior_id are free-form metadata. They are stored with the booking as a reference to the cancelled one, and don't change how the new booking is priced or processed.

For changes to rental dates or customer details, prefer modification. The booking keeps its INS, so you reconcile one booking instead of two.

Cancellations you didn't make

Customers can cancel from their XCover account, and Cover Genius can also cancel a booking. In both cases you receive a BOOKING_CANCELLED webhook.

See also

Last updated

Was this helpful?