openapi: 3.0.0
info:
  title: Offers API - Event Ticket Protection
  version: 1.0.0
  description: >-
    The Offers API enables event-ticketing partners to create, confirm, and
    manage event ticket protection. The Create Offer endpoint accepts one or
    more events (each with its own tickets) and returns protection products
    priced for the combined ticket purchase.
  x-gitbook-description-html: >-
    <p>The Offers API enables event-ticketing partners to create, confirm, and
    manage event ticket protection. The Create Offer endpoint accepts one or
    more events (each with its own tickets) and returns protection products
    priced for the combined ticket purchase.</p>
servers:
  - url: https://api.xcover.com/x
paths:
  /partners/{partner_code}/offers/:
    post:
      summary: Create Offer
      description: >-
        The Create Offer endpoint generates event ticket protection offerings
        based on the events and tickets being purchased. Multiple events may
        be quoted in a single request; the response returns one or more
        protection products with pricing.
      tags:
        - Create Offer
      parameters:
        - name: active_only
          in: query
          required: false
          description: When using a test API key, only return active offers
          schema:
            type: boolean
            default: false
        - name: include_content
          in: query
          required: false
          description: Include localized content in the response
          schema:
            type: boolean
            default: true
        - name: extra_fields
          in: query
          required: false
          description: >-
            Comma-separated list of specific extra fields to include. Available
            fields: tax, commission, benefits, surcharge
          schema:
            type: string
        - name: exclude_offer_ids
          in: query
          required: false
          description: >-
            Comma-separated list of Offer Config IDs to exclude from the
            response
          schema:
            type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                schema:
                  type: string
                  description: >-
                    Schema identifier for the offer type. Optional. If not
                    provided, the default schema for your partner will be used.
                customer:
                  type: object
                  description: Customer information
                  properties:
                    currency:
                      type: string
                      description: Currency code (e.g., USD, AUD, EUR, GBP)
                    country:
                      type: string
                      description: Customer's country code (e.g., US, AU, GB)
                    region:
                      type: string
                      description: Customer's region or state
                    postcode:
                      type: string
                      description: Customer's postal code
                    language:
                      type: string
                      description: Customer's preferred language tag (e.g., en-us)
                    email:
                      type: string
                      format: email
                    ip:
                      type: string
                  required:
                    - currency
                    - country
                    - language
                partner:
                  type: object
                  description: Partner information
                  properties:
                    transaction_id:
                      type: string
                      description: Partner transaction identifier
                    customer_id:
                      type: string
                      description: Partner customer identifier
                    subsidiary:
                      type: string
                      description: >-
                        Partner subsidiary identifier (e.g., regional
                        subsidiary, white-label brand).
                    metadata:
                      type: object
                      description: Additional partner metadata
                      additionalProperties: true
                context:
                  type: object
                  description: Event-ticketing context.
                  properties:
                    events:
                      type: array
                      description: Events whose tickets are being protected.
                      items:
                        type: object
                        properties:
                          id:
                            type: string
                            description: Partner's event identifier.
                          name:
                            type: string
                            description: Event name.
                          start_date:
                            type: string
                            format: date-time
                            description: Event start date and time.
                          end_date:
                            type: string
                            format: date-time
                            nullable: true
                            description: >-
                              Event end date and time. May be omitted for
                              single-day events; for multi-day events this
                              should be set.
                          venue:
                            type: string
                            description: Venue name.
                          city:
                            type: string
                          country:
                            type: string
                          multiday_event:
                            type: boolean
                            description: Whether the event spans multiple days.
                          duration_days:
                            type: integer
                            description: Event duration in days.
                          category:
                            type: string
                            description: Event category (e.g., Music, Comedy, Sports).
                          total_amount:
                            type: number
                            description: >-
                              Total ticket amount for this event in the
                              customer currency.
                          ticket_count:
                            type: integer
                            description: Number of tickets being purchased for this event.
                          tickets:
                            type: array
                            description: Individual tickets being purchased.
                            items:
                              type: object
                              properties:
                                id:
                                  type: string
                                  description: Partner's ticket identifier.
                                type:
                                  type: string
                                  description: >-
                                    Ticket type / tier (e.g., GA, VIP,
                                    Meet & Greet).
                                status:
                                  type: string
                                  description: >-
                                    Ticket status (e.g., purchased, layaway,
                                    layaway - void).
                                price:
                                  type: number
                                  description: Face value of the ticket.
                                total_paid:
                                  type: number
                                  description: >-
                                    Amount the customer has paid so far for
                                    this ticket (useful for layaway).
                              required:
                                - id
                                - price
                        required:
                          - id
                          - name
                          - start_date
                          - country
                  additionalProperties: true
              required:
                - customer
                - context
            examples:
              ACMEEvents:
                $ref: '#/components/examples/ACMEEventsOfferRequest'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
                description: >-
                  Event ticket protection offer responses are wrapped in a
                  top-level `data` object.
                properties:
                  data:
                    type: object
                    properties:
                      id:
                        type: string
                        description: Offer ID
                      currency:
                        type: string
                      products:
                        type: array
                        items:
                          type: object
                          properties:
                            id:
                              type: string
                              description: Product (quote) ID
                            product_config_id:
                              type: string
                            type:
                              type: string
                              nullable: true
                            schema_url:
                              type: string
                              format: uri
                              nullable: true
                            details:
                              type: object
                              properties:
                                policy_version_id:
                                  type: string
                                start_date:
                                  type: string
                                  format: date-time
                                  nullable: true
                                end_date:
                                  type: string
                                  format: date-time
                                  nullable: true
                                finance:
                                  type: object
                                  properties:
                                    price:
                                      type: object
                                      properties:
                                        total_amount:
                                          type: number
                                          nullable: true
                                        total_amount_without_tax:
                                          type: number
                                          nullable: true
                                        total_amount_formatted:
                                          type: string
                                          nullable: true
                                        total_amount_without_tax_formatted:
                                          type: string
                                          nullable: true
                                    tax:
                                      type: object
                                      properties:
                                        total_amount:
                                          type: number
                                          nullable: true
                                        total_amount_formatted:
                                          type: string
                                          nullable: true
                                    surcharge:
                                      type: object
                                      properties:
                                        total_amount:
                                          type: number
                                          nullable: true
                                        total_amount_formatted:
                                          type: string
                                          nullable: true
                                    commission:
                                      type: object
                                      properties:
                                        total_amount:
                                          type: number
                                          nullable: true
                                        total_amount_formatted:
                                          type: string
                                          nullable: true
                                pds_url:
                                  type: string
                                  format: uri
                                files:
                                  type: array
                                  items:
                                    type: object
                                    properties:
                                      name:
                                        type: string
                                      url:
                                        type: string
                                        format: uri
                                      type:
                                        type: string
                                extra_fields:
                                  type: object
                                  description: >-
                                    Event-ticketing-specific computed fields
                                    about the resulting policy.
                                  properties:
                                    seller_entity:
                                      type: string
                                      description: >-
                                        Legal selling entity for the insurance
                                        product.
                                    event_datetime:
                                      type: string
                                      format: date-time
                                      nullable: true
                                      description: >-
                                        Resolved primary event date and time.
                                    policy_start_date:
                                      type: string
                                      format: date-time
                                      nullable: true
                                    policy_start_calculated:
                                      type: string
                                      format: date-time
                                      nullable: true
                                    event_id:
                                      type: string
                                      nullable: true
                                    customer_id:
                                      type: string
                                      nullable: true
                                    esim_eligible:
                                      type: boolean
                                      description: >-
                                        Whether the customer is eligible for a
                                        bundled travel eSIM perk.
                                    esimid:
                                      type: string
                                      nullable: true
                                      description: eSIM identifier when provisioned.
                                    same_day:
                                      type: boolean
                                      description: >-
                                        Whether the offer is being purchased
                                        on the same day as the event.
                                  additionalProperties: true
                                experiment:
                                  type: array
                                  description: >-
                                    Experiment metadata. Returned as an array
                                    (may be empty).
                                  items:
                                    type: object
                                    additionalProperties: true
                                benefits:
                                  type: array
                                  items:
                                    type: object
                                    additionalProperties: true
                      content:
                        type: object
                        properties:
                          schema_version:
                            type: string
                          locale:
                            type: string
                      provider_reference:
                        type: string
                        description: >-
                          Provider reference identifier for downstream
                          tracking and reconciliation.
              examples:
                ACMEEvents:
                  $ref: '#/components/examples/ACMEEventsOfferResponse'
        '403':
          description: Forbidden
          content:
            application/json:
              schema:
                type: object
                properties:
                  type:
                    type: string
                  message:
                    type: string
        '422':
          description: Unprocessable Entity
          content:
            application/json:
              schema:
                type: object
                properties:
                  type:
                    type: string
                  message:
                    type: string
                  errors:
                    type: object
                    additionalProperties: true
    parameters:
      - name: partner_code
        in: path
        required: true
        description: >-
          Partner code identifier. Client Solutions Engineer (CSE) should
          provide this value.
        schema:
          type: string
  /partners/{partner_code}/offers/{offer_id}/confirm/:
    post:
      summary: Confirm Offer
      description: >-
        Finalize the purchase of event ticket protection. Converts the
        selected Offer into a confirmed booking after payment.


        ## Idempotency


        Supports `x-idempotency-key` header for safe retries.
      tags:
        - Confirm Offer
      parameters:
        - name: x-idempotency-key
          in: header
          required: false
          schema:
            type: string
            format: uuid
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                quotes:
                  type: array
                  items:
                    type: object
                    properties:
                      id:
                        type: string
                    required:
                      - id
                policyholder:
                  type: object
                  properties:
                    first_name:
                      type: string
                    last_name:
                      type: string
                    email:
                      type: string
                      format: email
                    address1:
                      type: string
                    city:
                      type: string
                    region:
                      type: string
                    postcode:
                      type: string
                    country:
                      type: string
                  required:
                    - first_name
                    - last_name
                    - email
                    - country
              required:
                - quotes
                - policyholder
            examples:
              ACMEEvents:
                $ref: '#/components/examples/ACMEEventsConfirmRequest'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
                properties:
                  id:
                    type: string
                  status:
                    type: string
                  currency:
                    type: string
                  total_price:
                    type: number
                  total_price_formatted:
                    type: string
                  partner_transaction_id:
                    type: string
                    nullable: true
                  created_at:
                    type: string
                    format: date-time
                  updated_at:
                    type: string
                    format: date-time
                  pds_url:
                    type: string
                    format: uri
                  security_token:
                    type: string
                  quotes:
                    type: array
                    items:
                      type: object
                      properties:
                        id:
                          type: string
                        policy_start_date:
                          type: string
                          format: date-time
                        policy_end_date:
                          type: string
                          format: date-time
                          nullable: true
                        status:
                          type: string
                        price:
                          type: number
                        price_formatted:
                          type: string
                        policy:
                          type: object
                          properties:
                            policy_type:
                              type: string
                            policy_type_version:
                              type: string
                            policy_type_slug:
                              type: string
                            policy_type_group_name:
                              type: string
                            policy_name:
                              type: string
                            policy_code:
                              type: string
                            policy_version:
                              type: string
                            category:
                              type: string
                            policy_currency:
                              type: string
                        tax:
                          type: object
                          properties:
                            total_tax:
                              type: number
                              nullable: true
                            total_amount_without_tax:
                              type: number
                              nullable: true
                            total_tax_formatted:
                              type: string
                              nullable: true
                            total_amount_without_tax_formatted:
                              type: string
                              nullable: true
                        benefits:
                          type: array
                          items:
                            type: object
                            additionalProperties: true
                        commission:
                          type: object
                          properties:
                            partner_commission:
                              type: number
                              nullable: true
                            total_commission:
                              type: number
                              nullable: true
                            partner_commission_formatted:
                              type: string
                              nullable: true
                            total_commission_formatted:
                              type: string
                              nullable: true
                        created_at:
                          type: string
                          format: date-time
                        confirmed_at:
                          type: string
                          format: date-time
                        pds_url:
                          type: string
                          format: uri
                        can_be_cancelled:
                          type: boolean
                  coi:
                    type: object
                    properties:
                      url:
                        type: string
                        format: uri
                      pdf:
                        type: string
                        format: uri
                  policyholder:
                    type: object
                    properties:
                      first_name:
                        type: string
                      last_name:
                        type: string
                      email:
                        type: string
                        format: email
                      country:
                        type: string
                  total_tax:
                    type: number
                  total_tax_formatted:
                    type: string
                  total_premium:
                    type: number
                  total_premium_formatted:
                    type: string
                  fnol_link:
                    type: string
                    format: uri
              examples:
                ACMEEvents:
                  $ref: '#/components/examples/ACMEEventsConfirmResponse'
        '403':
          description: Forbidden
          content:
            application/json:
              schema:
                type: object
                properties:
                  type:
                    type: string
                  message:
                    type: string
        '404':
          description: Not Found
          content:
            application/json:
              schema:
                type: object
                properties:
                  type:
                    type: string
                  message:
                    type: string
        '409':
          description: Conflict - Duplicate Request (Idempotent)
          content:
            application/json:
              schema:
                type: object
              examples:
                ACMEEvents:
                  $ref: '#/components/examples/ACMEEventsConfirmResponse'
        '422':
          description: Unprocessable Entity
          content:
            application/json:
              schema:
                type: object
                properties:
                  type:
                    type: string
                  message:
                    type: string
                  errors:
                    type: array
                    items:
                      type: string
        '423':
          description: Locked - Request In Progress
          content:
            application/json:
              schema:
                type: object
                properties:
                  type:
                    type: string
                  message:
                    type: string
    parameters:
      - name: partner_code
        in: path
        required: true
        schema:
          type: string
      - name: offer_id
        in: path
        required: true
        description: The offer ID returned from the Create Offer endpoint.
        schema:
          type: string
  /partners/{partner_code}/offers/{offer_id}/opt_out/:
    post:
      summary: Opt-out Offer
      description: Record when a customer declines an event ticket protection offer.
      tags:
        - Opt-out Offer
      responses:
        '204':
          description: No Content - Opt-out recorded successfully
        '403':
          description: Forbidden
          content:
            application/json:
              schema:
                type: object
                properties:
                  type:
                    type: string
                  message:
                    type: string
        '404':
          description: Not Found
          content:
            application/json:
              schema:
                type: object
                properties:
                  type:
                    type: string
                  message:
                    type: string
    parameters:
      - name: partner_code
        in: path
        required: true
        schema:
          type: string
      - name: offer_id
        in: path
        required: true
        schema:
          type: string
  /partners/{partner_code}/bookings/{booking_id}/:
    patch:
      summary: Modify Booking
      description: >-
        Modify an existing event ticket protection booking. Typical
        modifications include event reschedules (updating event start/end
        dates) or adjusting ticket counts.
      tags:
        - Modify Booking
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                quotes:
                  type: array
                  items:
                    type: object
                    properties:
                      id:
                        type: string
                      update_fields:
                        type: object
                        description: >-
                          Fields to update on the quote. For event ticket
                          protection, common fields are nested `events`
                          updates (e.g., new start_date/end_date) or
                          ticket-level changes.
                        additionalProperties: true
                    required:
                      - id
                      - update_fields
            examples:
              ACMEEvents:
                $ref: '#/components/examples/ACMEEventsModifyRequest'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
                properties:
                  id:
                    type: string
                  status:
                    type: string
                  currency:
                    type: string
                  total_price:
                    type: number
                  total_price_formatted:
                    type: string
                  quotes:
                    type: array
                    items:
                      type: object
                      properties:
                        id:
                          type: string
                        status:
                          type: string
                        price:
                          type: number
                        price_formatted:
                          type: string
                        price_diff:
                          type: number
                        price_diff_formatted:
                          type: string
                  total_price_diff:
                    type: number
                  total_price_diff_formatted:
                    type: string
              examples:
                ACMEEvents:
                  $ref: '#/components/examples/ACMEEventsModifyResponse'
        '403':
          description: Forbidden
          content:
            application/json:
              schema:
                type: object
                properties:
                  type:
                    type: string
                  message:
                    type: string
        '422':
          description: Unprocessable Entity
          content:
            application/json:
              schema:
                type: object
                properties:
                  type:
                    type: string
                  message:
                    type: string
                  errors:
                    type: array
                    items:
                      type: string
    parameters:
      - name: partner_code
        in: path
        required: true
        schema:
          type: string
      - name: booking_id
        in: path
        required: true
        schema:
          type: string
  /partners/{partner_code}/bookings/{booking_id}/quote_for_update:
    patch:
      summary: Modify Booking - Preview
      description: >-
        Preview the price changes that would result from a modification
        without applying them. The response includes an `update_id` that can
        be used to confirm the modification.
      tags:
        - Modify Booking
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                quotes:
                  type: array
                  items:
                    type: object
                    properties:
                      id:
                        type: string
                      update_fields:
                        type: object
                        additionalProperties: true
                    required:
                      - id
                      - update_fields
            examples:
              ACMEEvents:
                $ref: '#/components/examples/ACMEEventsModifyRequest'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
                properties:
                  id:
                    type: string
                  status:
                    type: string
                  currency:
                    type: string
                  total_price:
                    type: number
                  total_price_formatted:
                    type: string
                  quotes:
                    type: array
                    items:
                      type: object
                      properties:
                        id:
                          type: string
                        status:
                          type: string
                        price:
                          type: number
                        price_formatted:
                          type: string
                        price_diff:
                          type: number
                        price_diff_formatted:
                          type: string
                  total_price_diff:
                    type: number
                  total_price_diff_formatted:
                    type: string
                  update_id:
                    type: string
              examples:
                ACMEEvents:
                  $ref: '#/components/examples/ACMEEventsModifyPreviewResponse'
        '403':
          description: Forbidden
          content:
            application/json:
              schema:
                type: object
                properties:
                  type:
                    type: string
                  message:
                    type: string
        '422':
          description: Unprocessable Entity
          content:
            application/json:
              schema:
                type: object
                properties:
                  type:
                    type: string
                  message:
                    type: string
                  errors:
                    type: object
    parameters:
      - name: partner_code
        in: path
        required: true
        schema:
          type: string
      - name: booking_id
        in: path
        required: true
        schema:
          type: string
  /partners/{partner_code}/bookings/{booking_id}/confirm_update/{update_id}/:
    post:
      summary: Modify Booking - Confirm
      description: Finalize a previewed modification.
      tags:
        - Modify Booking
      requestBody:
        required: false
        content:
          application/json:
            schema:
              type: object
              properties:
                xpay_charge_id:
                  type: string
      responses:
        '201':
          description: Created
          content:
            application/json:
              schema:
                type: object
                properties:
                  id:
                    type: string
                  status:
                    type: string
                  currency:
                    type: string
                  total_price:
                    type: number
                  total_price_formatted:
                    type: string
                  quotes:
                    type: array
                    items:
                      type: object
                      properties:
                        id:
                          type: string
                        status:
                          type: string
                        price:
                          type: number
                        price_formatted:
                          type: string
                        price_diff:
                          type: number
                        price_diff_formatted:
                          type: string
                  total_price_diff:
                    type: number
                  total_price_diff_formatted:
                    type: string
              examples:
                ACMEEvents:
                  $ref: '#/components/examples/ACMEEventsModifyConfirmResponse'
        '403':
          description: Forbidden
          content:
            application/json:
              schema:
                type: object
                properties:
                  type:
                    type: string
                  message:
                    type: string
        '404':
          description: Not Found
          content:
            application/json:
              schema:
                type: object
                properties:
                  type:
                    type: string
                  message:
                    type: string
        '422':
          description: Unprocessable Entity
          content:
            application/json:
              schema:
                type: object
                properties:
                  type:
                    type: string
                  message:
                    type: string
    parameters:
      - name: partner_code
        in: path
        required: true
        schema:
          type: string
      - name: booking_id
        in: path
        required: true
        schema:
          type: string
      - name: update_id
        in: path
        required: true
        schema:
          type: string
  /partners/{partner_code}/bookings/{booking_id}/cancel:
    post:
      summary: Cancel Booking
      description: >-
        Cancel an event ticket protection booking. Typical cancellation
        reasons include the event being cancelled by the organizer, the
        customer being unable to attend, or a duplicate booking.


        When `preview` is `true`, returns a refund preview with a
        `cancellation_id`. When `preview` is `false` (or omitted), the
        cancellation is applied immediately.
      tags:
        - Cancel Booking
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                preview:
                  type: boolean
                refund_required:
                  type: boolean
                quotes:
                  type: array
                  items:
                    type: object
                    properties:
                      id:
                        type: string
                      reason_for_cancellation:
                        type: string
                    required:
                      - id
            examples:
              ACMEEventsDirectCancel:
                $ref: '#/components/examples/ACMEEventsCancelRequest'
              ACMEEventsPreviewCancel:
                $ref: '#/components/examples/ACMEEventsCancelPreviewRequest'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
                properties:
                  id:
                    type: string
                  status:
                    type: string
                  quotes:
                    type: array
                    items:
                      type: object
                      properties:
                        id:
                          type: string
                        policy_start_date:
                          type: string
                          format: date-time
                        policy_end_date:
                          type: string
                          format: date-time
                          nullable: true
                        policy_cancellation_date:
                          type: string
                          format: date-time
                          nullable: true
                        status:
                          type: string
                        price:
                          type: number
                        refund_value:
                          type: number
                        adjustment_fee:
                          type: number
                  policyholder:
                    type: object
                    properties:
                      first_name:
                        type: string
                      last_name:
                        type: string
                      email:
                        type: string
                        format: email
                      country:
                        type: string
                  total_price:
                    type: number
                  total_price_formatted:
                    type: string
                  total_refund:
                    type: number
                  total_refund_formatted:
                    type: string
                  currency:
                    type: string
                  cancellation_id:
                    type: string
                    nullable: true
                  confirm_before:
                    type: string
                    format: date-time
                    nullable: true
                  refund_amount:
                    type: number
                  refund_amount_formatted:
                    type: string
              examples:
                ACMEEventsDirectCancel:
                  $ref: '#/components/examples/ACMEEventsCancelResponse'
                ACMEEventsPreviewCancel:
                  $ref: '#/components/examples/ACMEEventsCancelPreviewResponse'
        '403':
          description: Forbidden
          content:
            application/json:
              schema:
                type: object
                properties:
                  type:
                    type: string
                  message:
                    type: string
        '404':
          description: Not Found
          content:
            application/json:
              schema:
                type: object
                properties:
                  type:
                    type: string
                  message:
                    type: string
        '422':
          description: Unprocessable Entity
          content:
            application/json:
              schema:
                type: object
                properties:
                  type:
                    type: string
                  message:
                    type: string
                  errors:
                    type: array
                    items:
                      type: string
    parameters:
      - name: partner_code
        in: path
        required: true
        schema:
          type: string
      - name: booking_id
        in: path
        required: true
        schema:
          type: string
  /partners/{partner_code}/bookings/{booking_id}/confirm_cancellation/{cancellation_id}/:
    post:
      summary: Cancel Booking - Confirm
      description: Finalize a previewed cancellation.
      tags:
        - Cancel Booking
      requestBody:
        required: false
        content:
          application/json:
            schema:
              type: object
              properties:
                reason_for_cancellation:
                  type: string
            examples:
              ACMEEvents:
                $ref: '#/components/examples/ACMEEventsCancelConfirmRequest'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
                properties:
                  id:
                    type: string
                  status:
                    type: string
                  quotes:
                    type: array
                    items:
                      type: object
                      properties:
                        id:
                          type: string
                        status:
                          type: string
                        price:
                          type: number
                        refund_value:
                          type: number
                        cancelled_at:
                          type: string
                          format: date-time
                  total_refund:
                    type: number
                  total_refund_formatted:
                    type: string
                  refund_amount:
                    type: number
                  refund_amount_formatted:
                    type: string
              examples:
                ACMEEvents:
                  $ref: '#/components/examples/ACMEEventsCancelConfirmResponse'
        '403':
          description: Forbidden
          content:
            application/json:
              schema:
                type: object
                properties:
                  type:
                    type: string
                  message:
                    type: string
        '404':
          description: Not Found
          content:
            application/json:
              schema:
                type: object
                properties:
                  type:
                    type: string
                  message:
                    type: string
        '422':
          description: Unprocessable Entity
          content:
            application/json:
              schema:
                type: object
                properties:
                  type:
                    type: string
                  message:
                    type: string
                  errors:
                    type: array
                    items:
                      type: string
    parameters:
      - name: partner_code
        in: path
        required: true
        schema:
          type: string
      - name: booking_id
        in: path
        required: true
        schema:
          type: string
      - name: cancellation_id
        in: path
        required: true
        schema:
          type: string
components:
  examples:
    ACMEEventsOfferRequest:
      summary: ACME Events - Create Offer Request
      value:
        partner:
          transaction_id: c992efc4-da4c-4f45-996a-f16365ca3196
          subsidiary: acme-events-us
        context:
          events:
            - id: '666643'
              name: ACME Single Day Music Event
              start_date: '2026-04-29T15:00:00.000Z'
              end_date: '2026-04-30T15:00:00.000Z'
              venue: Downtown Music Hall
              city: Newark
              country: US
              multiday_event: true
              duration_days: 3
              category: Music
              total_amount: 550.44
              ticket_count: 3
              tickets:
                - price: 121.46
                  type: GA
                  status: layaway
                  id: '459624186'
                  total_paid: 14.46
                - price: 214.49
                  type: VIP
                  status: purchased
                  id: '459624281'
                  total_paid: 214.49
                - price: 214.49
                  type: VIP
                  status: purchased
                  id: '459624282'
                  total_paid: 214.49
            - id: '666644'
              name: ACME Multi-Day Comedy Festival
              start_date: '2026-05-29T03:00:00.000Z'
              venue: City Comedy Club
              city: Los Angeles
              country: US
              duration_days: 3
              category: Comedy
              total_amount: 2339.44
              ticket_count: 5
              multiday_event: true
              tickets:
                - price: 282.78
                  type: General Admission
                  status: layaway
                  id: '459624379'
                  total_paid: 22.88
                - price: 282.78
                  type: General Admission
                  status: layaway - void
                  id: '459624380'
                  total_paid: 22.88
                - price: 282.78
                  type: General Admission
                  status: layaway - void
                  id: '459624381'
                  total_paid: 22.88
                - price: 426.91
                  type: VIP
                  status: purchased
                  id: '459624479'
                  total_paid: 426.91
                - price: 1064.19
                  type: Meet & Greet
                  status: purchased
                  id: '459624579'
                  total_paid: 1064.19
        customer:
          currency: USD
          country: US
          region: NY
          postcode: '10036'
          language: en-us
    ACMEEventsOfferResponse:
      summary: ACME Events - Create Offer Response
      value:
        data:
          id: 462870ac-f408-48ef-8f86-7cf4dbf92652
          currency: USD
          products:
            - id: 78e02aeb-86fa-47e1-b1b7-e0f12b734c5a
              product_config_id: 7d28c1c6-6e62-44e6-aa5b-27b06bf17f13
              type: xcover
              schema_url: https://staging.static.xcover.com/media/product-types/schemas/xcover.json
              details:
                policy_version_id: d09c2b37-bb8c-41ae-b281-58d99bd13ede
                start_date: '2025-12-02T22:58:15.061427+00:00'
                end_date: '2025-12-07T16:00:00+00:00'
                finance:
                  price:
                    total_amount: 123.68
                    total_amount_without_tax: null
                    total_amount_formatted: US$123.68
                    total_amount_without_tax_formatted: null
                  tax:
                    total_amount: null
                    total_amount_formatted: null
                  surcharge:
                    total_amount: null
                    total_amount_formatted: null
                  commission:
                    total_amount: null
                    total_amount_formatted: null
                pds_url: https://staging.xcover.com/en-us/pds/eff06da8-4e56-475a-865d-3716b1ae4ee2?policy_type=event_ticket_protection_v1
                files: []
                extra_fields:
                  seller_entity: Cover Genius Insurance Services, LLC.
                  event_datetime: '2025-12-07T16:00:00Z'
                  policy_start_date: '2025-12-02T22:58:15.061427+00:00'
                  customer_id: N/A
                  event_id: null
                  esimid: ''
                  esim_eligible: true
                  policy_start_calculated: '2025-12-02T22:58:15.086266+00:00'
                  same_day: false
                experiment: []
                benefits: []
          content:
            schema_version: content:1.0
            locale: en-us
          provider_reference: eff06da8-4e56-475a-865d-3716b1ae4ee2
    ACMEEventsConfirmRequest:
      summary: ACME Events - Confirm Offer Request
      value:
        quotes:
          - id: 78e02aeb-86fa-47e1-b1b7-e0f12b734c5a
        policyholder:
          first_name: Jane
          last_name: Doe
          email: jane.doe@email.com
          address1: 350 5th Avenue
          city: New York
          region: NY
          postcode: '10036'
          country: US
    ACMEEventsConfirmResponse:
      summary: ACME Events - Confirm Offer Response
      value:
        id: ETP9K-4MR2N-INS
        status: CONFIRMED
        currency: USD
        total_price: 123.68
        total_price_formatted: US$123.68
        partner_transaction_id: null
        created_at: '2025-12-02T23:00:00.000000Z'
        updated_at: '2025-12-02T23:00:00.150000Z'
        pds_url: https://www.xcover.com/en/pds/ETP9K-4MR2N-INS
        security_token: 4kLqX-9PrLm-bcDjK-72NM4
        quotes:
          - id: 78e02aeb-86fa-47e1-b1b7-e0f12b734c5a
            policy_start_date: '2025-12-02T22:58:15.061427+00:00'
            policy_end_date: '2025-12-07T16:00:00+00:00'
            status: CONFIRMED
            price: 123.68
            price_formatted: US$123.68
            policy:
              policy_type: event_ticket_protection
              policy_type_version: '1'
              policy_type_slug: event_ticket_protection_v1
              policy_type_group_name: events
              policy_name: ACME Events Ticket Protection
              policy_code: AETP0001
              policy_version: d09c2b37-bb8c-41ae-b281-58d99bd13ede
              category: event_ticket_protection
              policy_currency: USD
            tax:
              total_tax: 0
              total_amount_without_tax: 123.68
              total_tax_formatted: US$0.00
              total_amount_without_tax_formatted: US$123.68
            benefits: []
            commission:
              partner_commission: 0
              total_commission: 0
              partner_commission_formatted: US$0.00
              total_commission_formatted: US$0.00
            created_at: '2025-12-02T23:00:00.000000Z'
            confirmed_at: '2025-12-02T23:00:00.150000Z'
            pds_url: https://www.xcover.com/en/pds/ETP9K-4MR2N-INS?policy_type=event_ticket_protection_v1&quote_id=78e02aeb-86fa-47e1-b1b7-e0f12b734c5a
            can_be_cancelled: true
        coi:
          url: https://www.xcover.com/en/coi/ETP9K-4MR2N-INS?security_token=4kLqX-9PrLm-bcDjK-72NM4
          pdf: https://www.xcover.com/en/coi/ETP9K-4MR2N-INS.pdf?security_token=4kLqX-9PrLm-bcDjK-72NM4
        policyholder:
          first_name: Jane
          last_name: Doe
          email: jane.doe@email.com
          country: US
        total_tax: 0
        total_tax_formatted: US$0.00
        total_premium: 123.68
        total_premium_formatted: US$123.68
        fnol_link: https://www.xcover.com/en/account/claims/fnol?bookingID=ETP9K-4MR2N-INS&security_token=4kLqX-9PrLm-bcDjK-72NM4
    ACMEEventsModifyRequest:
      summary: ACME Events - Modify Booking Request (event rescheduled)
      value:
        quotes:
          - id: 78e02aeb-86fa-47e1-b1b7-e0f12b734c5a
            update_fields:
              events:
                - id: '666643'
                  start_date: '2026-05-06T15:00:00.000Z'
                  end_date: '2026-05-07T15:00:00.000Z'
    ACMEEventsModifyResponse:
      summary: ACME Events - Modify Booking Response
      value:
        id: ETP9K-4MR2N-INS
        status: CONFIRMED
        currency: USD
        total_price: 123.68
        total_price_formatted: US$123.68
        quotes:
          - id: 78e02aeb-86fa-47e1-b1b7-e0f12b734c5a
            status: CONFIRMED
            price: 123.68
            price_formatted: US$123.68
            price_diff: 0
            price_diff_formatted: US$0.00
        total_price_diff: 0
        total_price_diff_formatted: US$0.00
    ACMEEventsModifyPreviewResponse:
      summary: ACME Events - Modify Booking Preview Response
      value:
        id: ETP9K-4MR2N-INS
        status: CONFIRMED
        currency: USD
        total_price: 123.68
        total_price_formatted: US$123.68
        quotes:
          - id: 78e02aeb-86fa-47e1-b1b7-e0f12b734c5a
            status: CONFIRMED
            price: 123.68
            price_formatted: US$123.68
            price_diff: 0
            price_diff_formatted: US$0.00
        total_price_diff: 0
        total_price_diff_formatted: US$0.00
        update_id: HrKp7-WmQcR-h2YO8
    ACMEEventsModifyConfirmResponse:
      summary: ACME Events - Modify Booking Confirm Response
      value:
        id: ETP9K-4MR2N-INS
        status: CONFIRMED
        currency: USD
        total_price: 123.68
        total_price_formatted: US$123.68
        quotes:
          - id: 78e02aeb-86fa-47e1-b1b7-e0f12b734c5a
            status: CONFIRMED
            price: 123.68
            price_formatted: US$123.68
            price_diff: 0
            price_diff_formatted: US$0.00
        total_price_diff: 0
        total_price_diff_formatted: US$0.00
    ACMEEventsCancelRequest:
      summary: ACME Events - Cancel Booking Request (Direct)
      value:
        preview: false
        refund_required: true
    ACMEEventsCancelResponse:
      summary: ACME Events - Cancel Booking Response (Direct)
      value:
        id: ETP9K-4MR2N-INS
        status: CANCELLED
        quotes:
          - id: 78e02aeb-86fa-47e1-b1b7-e0f12b734c5a
            policy_start_date: '2025-12-02T22:58:15.061427+00:00'
            policy_end_date: '2025-12-07T16:00:00+00:00'
            policy_cancellation_date: '2025-12-03T10:00:00.000000Z'
            status: CANCELLED
            price: 123.68
            refund_value: 123.68
            adjustment_fee: 0
        policyholder:
          first_name: Jane
          last_name: Doe
          email: jane.doe@email.com
          country: US
        total_price: 0
        total_price_formatted: US$0.00
        total_refund: 123.68
        total_refund_formatted: US$123.68
        currency: USD
        cancellation_id: null
        confirm_before: null
        refund_amount: 123.68
        refund_amount_formatted: US$123.68
    ACMEEventsCancelPreviewRequest:
      summary: ACME Events - Cancel Booking Request (Preview)
      value:
        preview: true
        refund_required: true
        quotes:
          - id: 78e02aeb-86fa-47e1-b1b7-e0f12b734c5a
            reason_for_cancellation: event cancelled by organizer
    ACMEEventsCancelPreviewResponse:
      summary: ACME Events - Cancel Booking Response (Preview)
      value:
        id: ETP9K-4MR2N-INS
        status: CANCELLED
        quotes:
          - id: 78e02aeb-86fa-47e1-b1b7-e0f12b734c5a
            policy_start_date: '2025-12-02T22:58:15.061427+00:00'
            policy_end_date: '2025-12-07T16:00:00+00:00'
            policy_cancellation_date: null
            status: CANCELLED
            price: 123.68
            refund_value: 123.68
            adjustment_fee: 0
        policyholder:
          first_name: Jane
          last_name: Doe
          email: jane.doe@email.com
          country: US
        total_price: 0
        total_price_formatted: US$0.00
        total_refund: 123.68
        total_refund_formatted: US$123.68
        currency: USD
        cancellation_id: gWq3r-31DZ5-ZZx4J-CCL
        confirm_before: '2025-12-04T10:00:00.000000Z'
        refund_amount: 123.68
        refund_amount_formatted: US$123.68
    ACMEEventsCancelConfirmRequest:
      summary: ACME Events - Cancel Booking Confirm Request
      value:
        reason_for_cancellation: event cancelled by organizer
    ACMEEventsCancelConfirmResponse:
      summary: ACME Events - Cancel Booking Confirm Response
      value:
        id: ETP9K-4MR2N-INS
        status: CANCELLED
        quotes:
          - id: 78e02aeb-86fa-47e1-b1b7-e0f12b734c5a
            status: CANCELLED
            price: 123.68
            refund_value: 123.68
            cancelled_at: '2025-12-03T10:05:00.000000Z'
        total_refund: 123.68
        total_refund_formatted: US$123.68
        refund_amount: 123.68
        refund_amount_formatted: US$123.68
  securitySchemes:
    CustomAPISignature:
      type: apiKey
      name: Authorization
      in: header
      description: >
        **Composite Authentication Scheme (Client Key, Date, and Signature)**


        Requires three mandatory headers in every request:


        ### 1. X-Api-Key (Client Key)

        * **Purpose:** Public identifier for the API consumer.


        ### 2. Date (Timestamp)

        * **Purpose:** Timestamp used for generating the signature and
        preventing replay attacks.

        * **Format:** RFC 7231 format (e.g., in GMT).


        ### 3. Authorization (Computed Signature)

        * **Purpose:** Cryptographic signature that verifies the request's
        authenticity and integrity.

        * **Format:** `SIGNATURE [authHeader]`


        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**.
security:
  - CustomAPISignature: []
