openapi: 3.0.1
info:
  title: Cover Genius XCover Bookings API
  description: The XCover distribution API from Cover Genius lets partners create embedded insurance offers (quotes) at the point of sale, confirm them into bound policies (bookings), retrieve and modify bookings, and cancel them. Requests are authenticated with an HTTP Signature (HMAC) scheme using an X-Api-Key header, a Date header, and an Authorization signature header. This document models the documented XCover Offers and Bookings surface served from https://api.xcover.com/x.
  termsOfService: https://www.covergenius.com/terms-of-use/
  contact:
    name: Cover Genius Partner Support
    url: https://partner-docs.covergenius.com
  version: '2.0'
servers:
- url: https://api.xcover.com/x
  description: XCover production base URL
security:
- XCoverSignature: []
tags:
- name: Bookings
paths:
  /partners/{partner_code}/offers/{offer_id}/confirm/:
    post:
      operationId: confirmOffer
      tags:
      - Bookings
      summary: Confirm offer (create booking)
      description: Confirms selected quotes from an offer into a bound policy, creating a booking. Supports an x-idempotency-key header to safely retry; a duplicate key returns 409.
      parameters:
      - $ref: '#/components/parameters/PartnerCode'
      - $ref: '#/components/parameters/OfferId'
      - name: x-idempotency-key
        in: header
        required: false
        schema:
          type: string
          format: uuid
        description: Idempotency key (UUID) to deduplicate confirm requests.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ConfirmOfferRequest'
      responses:
        '200':
          description: Booking confirmed.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Booking'
        '409':
          $ref: '#/components/responses/Error'
        '401':
          $ref: '#/components/responses/Error'
  /partners/{partner_code}/bookings/{booking_id}/:
    get:
      operationId: getBooking
      tags:
      - Bookings
      summary: Get booking
      description: Retrieves the details of a confirmed booking and its policies.
      parameters:
      - $ref: '#/components/parameters/PartnerCode'
      - $ref: '#/components/parameters/BookingId'
      responses:
        '200':
          description: Booking details.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Booking'
        '404':
          $ref: '#/components/responses/Error'
    patch:
      operationId: modifyBooking
      tags:
      - Bookings
      summary: Modify booking
      description: Applies modifications directly to a confirmed booking.
      parameters:
      - $ref: '#/components/parameters/PartnerCode'
      - $ref: '#/components/parameters/BookingId'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ModifyBookingRequest'
      responses:
        '200':
          description: Booking modified.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Booking'
        '400':
          $ref: '#/components/responses/Error'
  /partners/{partner_code}/bookings/{booking_id}/quote_for_update:
    patch:
      operationId: quoteForUpdate
      tags:
      - Bookings
      summary: Quote booking modification
      description: Previews the price impact of a proposed modification without applying it. Returns an update_id to be used with confirm_update.
      parameters:
      - $ref: '#/components/parameters/PartnerCode'
      - $ref: '#/components/parameters/BookingId'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ModifyBookingRequest'
      responses:
        '200':
          description: Update preview with price difference and update_id.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UpdatePreview'
  /partners/{partner_code}/bookings/{booking_id}/confirm_update/{update_id}/:
    post:
      operationId: confirmBookingUpdate
      tags:
      - Bookings
      summary: Confirm booking modification
      description: Confirms a previously previewed booking modification by update_id.
      parameters:
      - $ref: '#/components/parameters/PartnerCode'
      - $ref: '#/components/parameters/BookingId'
      - name: update_id
        in: path
        required: true
        schema:
          type: string
        description: Identifier returned by quote_for_update.
      responses:
        '200':
          description: Modification confirmed.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Booking'
  /partners/{partner_code}/bookings/{booking_id}/cancel:
    post:
      operationId: cancelBooking
      tags:
      - Bookings
      summary: Cancel booking
      description: Cancels a booking. With preview true the response returns a cancellation_id and refund preview without cancelling; with preview false the booking is cancelled immediately.
      parameters:
      - $ref: '#/components/parameters/PartnerCode'
      - $ref: '#/components/parameters/BookingId'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CancelBookingRequest'
      responses:
        '200':
          description: Cancellation preview or confirmation.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CancellationResult'
        '400':
          $ref: '#/components/responses/Error'
components:
  schemas:
    Policyholder:
      type: object
      required:
      - first_name
      - last_name
      - email
      properties:
        first_name:
          type: string
        last_name:
          type: string
        email:
          type: string
          format: email
        phone:
          type: string
        country:
          type: string
        age:
          type: integer
    UpdatePreview:
      type: object
      properties:
        update_id:
          type: string
        price_difference:
          type: string
        price_difference_formatted:
          type: string
        currency:
          type: string
    ModifyBookingRequest:
      type: object
      properties:
        quotes:
          type: array
          items:
            type: object
            properties:
              id:
                type: string
              policy_start_date:
                type: string
                format: date-time
              fields:
                type: object
    CancelBookingRequest:
      type: object
      properties:
        preview:
          type: boolean
          description: When true, returns a cancellation preview without cancelling.
        cancellation_reason:
          type: string
    Booking:
      type: object
      properties:
        id:
          type: string
        status:
          type: string
        policies:
          type: array
          items:
            $ref: '#/components/schemas/Quote'
        policyholder:
          $ref: '#/components/schemas/Policyholder'
        partner_transaction_id:
          type: string
    Error:
      type: object
      properties:
        error:
          type: string
        message:
          type: string
        details:
          type: array
          items:
            type: object
    CancellationResult:
      type: object
      properties:
        cancellation_id:
          type: string
        refund_amount:
          type: string
        refund_amount_formatted:
          type: string
        status:
          type: string
    Quote:
      type: object
      properties:
        id:
          type: string
        status:
          type: string
          description: Quote/policy status (e.g. QUOTED, RECEIVED, CONFIRMED, CANCELLED).
        price:
          type: string
        currency:
          type: string
        policy_start_date:
          type: string
          format: date-time
    ConfirmOfferRequest:
      type: object
      required:
      - quotes
      - policyholder
      properties:
        quotes:
          type: array
          description: Quote IDs from the offer to bind into policies.
          items:
            type: string
        policyholder:
          $ref: '#/components/schemas/Policyholder'
        partner_transaction_id:
          type: string
        payment_details:
          type: object
  parameters:
    OfferId:
      name: offer_id
      in: path
      required: true
      schema:
        type: string
      description: Identifier of an offer returned by createOffer.
    BookingId:
      name: booking_id
      in: path
      required: true
      schema:
        type: string
      description: Identifier of a confirmed booking.
    PartnerCode:
      name: partner_code
      in: path
      required: true
      schema:
        type: string
      description: The partner's unique XCover partner code (e.g. LLODT).
  responses:
    Error:
      description: Error response.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
  securitySchemes:
    XCoverSignature:
      type: apiKey
      in: header
      name: Authorization
      description: HTTP Signature authentication. Each request carries an X-Api-Key header, a Date header (RFC 822 GMT), and an Authorization header of the form Signature keyId="{API_KEY}",algorithm="hmac-sha512",signature="{base64}". The signature is an HMAC of the canonical string (by default the date header) computed with the partner's secret key.