openapi: 3.0.0
info:
  title: Offers API
  version: 1.0.0
  description: >-
    The Offers API enables partners to create, confirm, and manage product
    offers containing single or multiple insurance and non-insurance products.
    It provides endpoints for generating offers, confirming bookings, handling
    opt-outs, and modifying existing policies.
  x-gitbook-description-document:
    object: document
    data:
      schemaVersion: 9
    nodes:
      - object: block
        type: paragraph
        isVoid: false
        data: {}
        nodes:
          - object: text
            leaves:
              - object: leaf
                text: >-
                  The Offers API enables partners to create, confirm, and manage
                  product offers containing single or multiple insurance and
                  non-insurance products. It provides endpoints for generating
                  offers, confirming bookings, handling opt-outs, and modifying
                  existing policies.
                marks: []
            key: 10AXbTTHj0ql
        key: acNAbXJrvxg9
    key: 6O6rFTjw7myg
  x-gitbook-description-html: >-
    <p>The Offers API enables partners to create, confirm, and manage product
    offers containing single or multiple insurance and non-insurance products.
    It provides endpoints for generating offers, confirming bookings, handling
    opt-outs, and modifying existing policies.</p>
servers:
  - url: https://api.xcover.com/x
paths:
  /partners/{partner_code}/offers/:
    post:
      summary: Create Offer
      description: >-
        The Create Offer endpoint generates product offerings based on your
        business context and customer information. This endpoint uses a
        schema-driven approach to validate requests and returns one or more
        products with detailed pricing, product information, and content for
        display.
      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
          x-gitbook-description-html: <p>When using a test API key, only return active offers</p>
        - name: include_content
          in: query
          required: false
          description: Include localized content in the response
          schema:
            type: boolean
            default: true
          x-gitbook-description-html: <p>Include localized content in the response</p>
        - 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
          x-gitbook-description-html: >-
            <p>Comma-separated list of specific extra fields to include.
            Available fields: tax, commission, benefits, surcharge</p>
        - name: exclude_offer_ids
          in: query
          required: false
          description: >-
            Comma-separated list of Offer Config IDs to exclude from the
            response
          schema:
            type: string
          x-gitbook-description-html: >-
            <p>Comma-separated list of Offer Config IDs to exclude from the
            response</p>
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                schema:
                  type: string
                  description: >-
                    Schema identifier for the offer type. If not provided, the
                    default schema for your partner will be used. The Client
                    Solutions Engineer (CSE) will provide the appropriate schema
                    identifier during integration.
                  example: acme-schema-v1
                  x-gitbook-description-html: >-
                    <p>Schema identifier for the offer type. If not provided,
                    the default schema for your partner will be used. The Client
                    Solutions Engineer (CSE) will provide the appropriate schema
                    identifier during integration.</p>
                customer:
                  type: object
                  description: Customer information
                  properties:
                    currency:
                      type: string
                      description: Currency code (e.g., USD, AUD, EUR, GBP)
                      x-gitbook-description-html: <p>Currency code (e.g., USD, AUD, EUR, GBP)</p>
                    country:
                      type: string
                      description: Customer's country code (e.g., US, AU, GB)
                      x-gitbook-description-html: <p>Customer's country code (e.g., US, AU, GB)</p>
                    region:
                      type: string
                      description: Customer's region or state
                      x-gitbook-description-html: <p>Customer's region or state</p>
                    language:
                      type: string
                      description: Customer's preferred language (e.g., en)
                      x-gitbook-description-html: <p>Customer's preferred language (e.g., en)</p>
                    email:
                      type: string
                      format: email
                      description: Customer's email address
                      x-gitbook-description-html: <p>Customer's email address</p>
                    ip:
                      type: string
                      description: Customer's IP address
                      x-gitbook-description-html: <p>Customer's IP address</p>
                    postcode:
                      type: string
                      description: Customer's postal code
                      x-gitbook-description-html: <p>Customer's postal code</p>
                  required:
                    - currency
                    - country
                    - language
                  x-gitbook-description-html: <p>Customer information</p>
                partner:
                  type: object
                  description: Partner information
                  properties:
                    transaction_id:
                      type: string
                      description: Partner transaction identifier
                      x-gitbook-description-html: <p>Partner transaction identifier</p>
                    customer_id:
                      type: string
                      description: Partner customer identifier
                      x-gitbook-description-html: <p>Partner customer identifier</p>
                    subsidiary:
                      type: string
                      description: Partner subsidiary identifier
                      x-gitbook-description-html: <p>Partner subsidiary identifier</p>
                    metadata:
                      type: object
                      description: Additional partner metadata
                      properties:
                        merchant_id:
                          type: string
                          description: Merchant identifier
                          x-gitbook-description-html: <p>Merchant identifier</p>
                        merchant_name:
                          type: string
                          description: Human-readable merchant name
                          x-gitbook-description-html: <p>Human-readable merchant name</p>
                        sales_channel:
                          type: string
                          description: Sales channel (e.g., online, in-store)
                          x-gitbook-description-html: <p>Sales channel (e.g., online, in-store)</p>
                        device:
                          type: string
                          description: Device type (e.g., desktop, mobile, tablet)
                          x-gitbook-description-html: <p>Device type (e.g., desktop, mobile, tablet)</p>
                      additionalProperties: true
                      x-gitbook-description-html: <p>Additional partner metadata</p>
                  x-gitbook-description-html: <p>Partner information</p>
                context:
                  type: object
                  description: >-
                    Business context data required for offer selection and
                    pricing. The specific fields required will be defined
                    through the offer schema with the Client Solutions Engineer
                    (CSE).
                  properties:
                    purchase_date:
                      type: string
                      format: date-time
                      description: Date and time the purchase was made
                      x-gitbook-description-html: <p>Date and time the purchase was made</p>
                    estimated_shipping_date:
                      type: string
                      format: date-time
                      description: Estimated shipping date of the product
                      x-gitbook-description-html: <p>Estimated shipping date of the product</p>
                    estimated_delivery_date:
                      type: string
                      format: date-time
                      description: Estimated delivery date of the product
                      x-gitbook-description-html: <p>Estimated delivery date of the product</p>
                    product:
                      type: object
                      description: Product being protected
                      properties:
                        sku:
                          type: string
                          description: Product SKU
                          x-gitbook-description-html: <p>Product SKU</p>
                        brand:
                          type: string
                          description: Product brand
                          x-gitbook-description-html: <p>Product brand</p>
                        model:
                          type: string
                          description: Product model
                          x-gitbook-description-html: <p>Product model</p>
                        title:
                          type: string
                          description: Product title
                          x-gitbook-description-html: <p>Product title</p>
                        variant:
                          type: string
                          description: Product variant identifier (e.g., warranty term such as 2y)
                          x-gitbook-description-html: >-
                            <p>Product variant identifier (e.g., warranty term
                            such as 2y)</p>
                        category:
                          type: string
                          description: Product category name
                          x-gitbook-description-html: <p>Product category name</p>
                        category_id:
                          type: string
                          description: Product category identifier
                          x-gitbook-description-html: <p>Product category identifier</p>
                        quantity:
                          type: integer
                          description: Quantity purchased
                          x-gitbook-description-html: <p>Quantity purchased</p>
                        condition:
                          type: string
                          description: Product condition (e.g., new, refurbished, used)
                          x-gitbook-description-html: >-
                            <p>Product condition (e.g., new, refurbished,
                            used)</p>
                        description:
                          type: string
                          description: Product description
                          x-gitbook-description-html: <p>Product description</p>
                        retail_value:
                          type: number
                          description: Retail price of the product
                          x-gitbook-description-html: <p>Retail price of the product</p>
                        wholesale_value:
                          type: number
                          description: Wholesale price of the product
                          x-gitbook-description-html: <p>Wholesale price of the product</p>
                        term:
                          type: string
                          description: Coverage term for the product (e.g., 2y)
                          x-gitbook-description-html: >-
                            <p>Coverage term for the product (e.g., 2y)</p>
                      required:
                        - sku
                        - title
                        - quantity
                        - retail_value
                      x-gitbook-description-html: <p>Product being protected</p>
                    warranty:
                      type: object
                      description: Warranty details for the product
                      properties:
                        manufacturer_duration:
                          type: string
                          description: Duration of the manufacturer warranty (e.g., 1y)
                          x-gitbook-description-html: >-
                            <p>Duration of the manufacturer warranty (e.g.,
                            1y)</p>
                        term:
                          type: string
                          description: Extended warranty term (e.g., 2y)
                          x-gitbook-description-html: <p>Extended warranty term (e.g., 2y)</p>
                        benefit:
                          type: string
                          description: >-
                            Benefit type (e.g., accidental damage and extended
                            warranty)
                          x-gitbook-description-html: >-
                            <p>Benefit type (e.g., accidental damage and
                            extended warranty)</p>
                      x-gitbook-description-html: <p>Warranty details for the product</p>
                  additionalProperties: true
                  x-gitbook-description-html: >-
                    <p>Business context data required for offer selection and
                    pricing. The specific fields required will be defined
                    through the offer schema with the Client Solutions Engineer
                    (CSE).</p>
              required:
                - schema
                - customer
                - context
            examples:
              ACMEProductProtection:
                $ref: '#/components/examples/ACMEOfferRequest'
      responses:
        '200':
          description: OK
          headers:
            Date:
              schema:
                type: string
            Transfer-Encoding:
              schema:
                type: string
            Connection:
              schema:
                type: string
            CF-Ray:
              schema:
                type: integer
            CF-Cache-Status:
              schema:
                type: string
            Allow:
              schema:
                type: string
            Server:
              schema:
                type: string
            Strict-Transport-Security:
              schema:
                type: string
            cross-origin-opener-policy:
              schema:
                type: string
            referrer-policy:
              schema:
                type: string
            x-content-type-options:
              schema:
                type: string
            x-envoy-decorator-operation:
              schema:
                type: string
            x-envoy-upstream-service-time:
              schema:
                type: integer
            x-frame-options:
              schema:
                type: string
            Vary:
              schema:
                type: string
            Content-Encoding:
              schema:
                type: string
            Server-Timing:
              schema:
                type: string
            Cf-Team:
              schema:
                type: integer
          content:
            application/json:
              schema:
                type: object
                properties:
                  id:
                    type: string
                    description: Offer ID
                    x-gitbook-description-html: <p>Offer ID</p>
                  offer_config_id:
                    type: string
                    description: Offer configuration identifier
                    x-gitbook-description-html: <p>Offer configuration identifier</p>
                  offer_schema:
                    type: string
                    description: Schema identifier for the offer
                    x-gitbook-description-html: <p>Schema identifier for the offer</p>
                  currency:
                    type: string
                    description: Currency code for the offer pricing
                    x-gitbook-description-html: <p>Currency code for the offer pricing</p>
                  products:
                    type: array
                    items:
                      type: object
                      properties:
                        id:
                          type: string
                          description: Product (quote) ID
                          x-gitbook-description-html: <p>Product (quote) ID</p>
                        product_config_id:
                          type: string
                          description: Product configuration identifier
                          x-gitbook-description-html: <p>Product configuration identifier</p>
                        name:
                          type: string
                          description: Product name
                          x-gitbook-description-html: <p>Product name</p>
                        type:
                          type: string
                          nullable: true
                          description: Product type
                          x-gitbook-description-html: <p>Product type</p>
                        schema_url:
                          type: string
                          nullable: true
                          format: uri
                          description: URL to the product schema definition
                          x-gitbook-description-html: <p>URL to the product schema definition</p>
                        details:
                          type: object
                          properties:
                            policy_version_id:
                              type: string
                              description: Policy version identifier
                              x-gitbook-description-html: <p>Policy version identifier</p>
                            start_date:
                              type: string
                              format: date-time
                              description: Coverage start date
                              x-gitbook-description-html: <p>Coverage start date</p>
                            end_date:
                              type: string
                              format: date-time
                              description: Coverage end date
                              x-gitbook-description-html: <p>Coverage end date</p>
                            finance:
                              type: object
                              properties:
                                price:
                                  type: object
                                  properties:
                                    total_amount:
                                      type: number
                                      nullable: true
                                    total_amount_without_tax:
                                      type: number
                                      nullable: true
                                    total_amount_min:
                                      type: number
                                      nullable: true
                                    total_amount_max:
                                      type: number
                                      nullable: true
                                    total_amount_formatted:
                                      type: string
                                      nullable: true
                                    total_amount_without_tax_formatted:
                                      type: string
                                      nullable: true
                                    total_amount_min_formatted:
                                      type: string
                                      nullable: true
                                    total_amount_max_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
                              description: URL to the Product Disclosure Statement
                              x-gitbook-description-html: <p>URL to the Product Disclosure Statement</p>
                            files:
                              type: array
                              description: Associated documents (e.g., IPID)
                              items:
                                type: object
                                properties:
                                  name:
                                    type: string
                                    description: File name
                                    x-gitbook-description-html: <p>File name</p>
                                  url:
                                    type: string
                                    format: uri
                                    description: File URL
                                    x-gitbook-description-html: <p>File URL</p>
                                  type:
                                    type: string
                                    description: File type (e.g., IPID, OTHER)
                                    x-gitbook-description-html: <p>File type (e.g., IPID, OTHER)</p>
                              x-gitbook-description-html: <p>Associated documents (e.g., IPID)</p>
                            extra_fields:
                              type: object
                              description: >-
                                Schema-specific extra fields providing additional
                                pricing and product metadata.
                              properties:
                                pricing_matrix:
                                  type: array
                                  description: >-
                                    Rows from the pricing matrix used to compute
                                    the offer price.
                                  items:
                                    type: object
                                    additionalProperties: true
                                  x-gitbook-description-html: >-
                                    <p>Rows from the pricing matrix used to
                                    compute the offer price.</p>
                                appliance:
                                  type: string
                                  description: >-
                                    Appliance classification (e.g., appliance,
                                    non-appliance)
                                  x-gitbook-description-html: >-
                                    <p>Appliance classification (e.g.,
                                    appliance, non-appliance)</p>
                                retail_ex_tax:
                                  type: number
                                  nullable: true
                                  description: Retail price excluding tax
                                  x-gitbook-description-html: <p>Retail price excluding tax</p>
                                retail_inc_tax:
                                  type: number
                                  nullable: true
                                  description: Retail price including tax
                                  x-gitbook-description-html: <p>Retail price including tax</p>
                                retail_ex_tax_rounded:
                                  type: number
                                  nullable: true
                                  description: Retail price excluding tax (rounded)
                                  x-gitbook-description-html: <p>Retail price excluding tax (rounded)</p>
                                retail_inc_tax_rounded:
                                  type: number
                                  nullable: true
                                  description: Retail price including tax (rounded)
                                  x-gitbook-description-html: <p>Retail price including tax (rounded)</p>
                                taxes:
                                  type: object
                                  description: Tax breakdown
                                  additionalProperties: true
                                  x-gitbook-description-html: <p>Tax breakdown</p>
                                tax_rate:
                                  type: number
                                  nullable: true
                                  description: Applied tax rate
                                  x-gitbook-description-html: <p>Applied tax rate</p>
                                benefit_type:
                                  type: string
                                  description: Benefit type for this product
                                  x-gitbook-description-html: <p>Benefit type for this product</p>
                                partner_commission:
                                  type: number
                                  nullable: true
                                  description: Partner commission amount
                                  x-gitbook-description-html: <p>Partner commission amount</p>
                                variant:
                                  type: string
                                  description: Variant identifier (e.g., 2y)
                                  x-gitbook-description-html: <p>Variant identifier (e.g., 2y)</p>
                              additionalProperties: true
                              x-gitbook-description-html: >-
                                <p>Schema-specific extra fields providing
                                additional pricing and product metadata.</p>
                            experiment:
                              type: object
                              description: Experiment metadata (if applicable)
                              additionalProperties: true
                              x-gitbook-description-html: <p>Experiment metadata (if applicable)</p>
                            benefits:
                              type: array
                              description: Coverage benefits associated with the product
                              items:
                                type: object
                                additionalProperties: true
                              x-gitbook-description-html: <p>Coverage benefits associated with the product</p>
                  content:
                    type: object
                    properties:
                      schema_version:
                        type: string
                        description: Content schema version
                        x-gitbook-description-html: <p>Content schema version</p>
                      locale:
                        type: string
                        description: Content locale (e.g., en, en-US)
                        x-gitbook-description-html: <p>Content locale (e.g., en, en-US)</p>
                      slug:
                        type: string
                        description: Content slug identifier for the offer
                        x-gitbook-description-html: <p>Content slug identifier for the offer</p>
                      title:
                        type: string
                        description: Main title for the offer
                        x-gitbook-description-html: <p>Main title for the offer</p>
                      extras:
                        type: object
                        description: Additional content fields specific to the offer
                        additionalProperties: true
                        x-gitbook-description-html: <p>Additional content fields specific to the offer</p>
                      heading:
                        type: string
                        description: Heading text
                        x-gitbook-description-html: <p>Heading text</p>
                      sub_heading:
                        type: string
                        description: Sub-heading text
                        x-gitbook-description-html: <p>Sub-heading text</p>
                      disclaimer:
                        type: string
                        description: Legal disclaimer text
                        x-gitbook-description-html: <p>Legal disclaimer text</p>
                      disclaimer_html:
                        type: string
                        description: HTML formatted disclaimer
                        x-gitbook-description-html: <p>HTML formatted disclaimer</p>
                      price_unit:
                        type: string
                        description: Price unit descriptor (e.g., per person)
                        x-gitbook-description-html: <p>Price unit descriptor (e.g., per person)</p>
                      description:
                        type: string
                        description: Offer description
                        x-gitbook-description-html: <p>Offer description</p>
                      positive_cta:
                        type: string
                        description: Text for accept/yes button
                        x-gitbook-description-html: <p>Text for accept/yes button</p>
                      negative_cta:
                        type: string
                        description: Text for decline/no button
                        x-gitbook-description-html: <p>Text for decline/no button</p>
                      negative_cta_warning:
                        type: string
                        description: Warning shown when user declines
                        x-gitbook-description-html: <p>Warning shown when user declines</p>
                      required_message:
                        type: string
                        description: Message shown when selection is required
                        x-gitbook-description-html: <p>Message shown when selection is required</p>
                      credibility_message:
                        type: string
                        description: >-
                          Trust/credibility message (deprecated, use
                          credibility)
                        x-gitbook-description-html: >-
                          <p>Trust/credibility message (deprecated, use
                          credibility)</p>
                  errors:
                    type: object
                    description: Any errors encountered during offer creation
                    additionalProperties: true
                    x-gitbook-description-html: <p>Any errors encountered during offer creation</p>
              examples:
                ACMEProductProtection:
                  $ref: '#/components/examples/ACMEOfferResponse'
          x-gitbook-description-html: <p>OK</p>
        '403':
          description: Forbidden
          headers:
            Date:
              schema:
                deprecated: false
            Transfer-Encoding:
              schema:
                deprecated: false
            Connection:
              schema:
                deprecated: false
            CF-Ray:
              schema:
                deprecated: false
            CF-Cache-Status:
              schema:
                deprecated: false
            Allow:
              schema:
                deprecated: false
            Server:
              schema:
                deprecated: false
            Strict-Transport-Security:
              schema:
                deprecated: false
            cross-origin-opener-policy:
              schema:
                deprecated: false
            referrer-policy:
              schema:
                deprecated: false
            x-content-type-options:
              schema:
                deprecated: false
            x-envoy-decorator-operation:
              schema:
                deprecated: false
            x-envoy-upstream-service-time:
              schema:
                deprecated: false
            x-frame-options:
              schema:
                deprecated: false
            Vary:
              schema:
                deprecated: false
            Content-Encoding:
              schema:
                deprecated: false
            Server-Timing:
              schema:
                deprecated: false
            Cf-Team:
              schema:
                deprecated: false
          content:
            application/json:
              schema:
                type: object
                properties:
                  type:
                    type: string
                  message:
                    type: string
          x-gitbook-description-html: <p>Forbidden</p>
        '422':
          description: Unprocessable Entity
          headers:
            Date:
              schema:
                deprecated: false
            Content-Length:
              schema:
                deprecated: false
            Connection:
              schema:
                deprecated: false
            CF-Ray:
              schema:
                deprecated: false
            CF-Cache-Status:
              schema:
                deprecated: false
            Allow:
              schema:
                deprecated: false
            Server:
              schema:
                deprecated: false
            Strict-Transport-Security:
              schema:
                deprecated: false
            cross-origin-opener-policy:
              schema:
                deprecated: false
            referrer-policy:
              schema:
                deprecated: false
            x-content-type-options:
              schema:
                deprecated: false
            x-envoy-decorator-operation:
              schema:
                deprecated: false
            x-envoy-upstream-service-time:
              schema:
                deprecated: false
            x-frame-options:
              schema:
                deprecated: false
            Vary:
              schema:
                deprecated: false
            Server-Timing:
              schema:
                deprecated: false
            Cf-Team:
              schema:
                deprecated: false
          content:
            application/json:
              schema:
                type: object
                properties:
                  type:
                    type: string
                  message:
                    type: string
                  errors:
                    type: object
                    properties:
                      schema:
                        type: array
                        items:
                          type: string
                          format: style
          x-gitbook-description-html: <p>Unprocessable Entity</p>
      x-gitbook-description-document:
        object: document
        data:
          schemaVersion: 9
        nodes:
          - object: block
            type: paragraph
            isVoid: false
            data: {}
            nodes:
              - object: text
                leaves:
                  - object: leaf
                    text: >-
                      The Create Offer endpoint generates product offerings
                      based on your business context and customer information.
                      This endpoint uses a schema-driven approach to validate
                      requests and returns one or more products with detailed
                      pricing, product information, and content for display.
                    marks: []
                key: 0RRW02clNct8
            key: WE3NLRh15NdX
        key: s5GHgC6g4tXl
      x-gitbook-description-html: >-
        <p>The Create Offer endpoint generates product offerings based on your
        business context and customer information. This endpoint uses a
        schema-driven approach to validate requests and returns one or more
        products with detailed pricing, product information, and content for
        display.</p>
    parameters:
      - name: partner_code
        in: path
        required: true
        description: >-
          Partner code identifier. Client Solutions Engineer (CSE) should
          provide this value.
        schema:
          type: string
        x-gitbook-description-html: >-
          <p>Partner code identifier. Client Solutions Engineer (CSE) should
          provide this value.</p>
  /partners/{partner_code}/offers/{offer_id}/confirm/:
    post:
      summary: Confirm Offer
      description: >-
        The Confirm Offer endpoint is used to finalize the purchase of products
        from a previously created Offer. This endpoint converts the selected
        Offer into a confirmed booking after payment has been successfully
        collected.


        ## Idempotency


        This endpoint supports idempotency keys via the `x-idempotency-key`
        header to prevent duplicate transactions. Provide a unique operation
        identifier (e.g., UUID) to ensure safe retries. Duplicate requests
        return:

        - **409 Conflict**: The request was already processed; response contains
          the cached original result (handle as success)

        - **423 Locked**: The original request is still processing; retry after
          a short delay
      tags:
        - Confirm Offer
      parameters:
        - name: x-idempotency-key
          in: header
          required: false
          description: >-
            A unique identifier to ensure idempotent request processing. If a
            request with the same idempotency key and body has already been
            processed, the cached response is returned with a 409 Conflict
            status code (which can be treated as successful). Keys are stored
            for 48 hours.
          schema:
            type: string
            format: uuid
            example: 550e8400-e29b-41d4-a716-446655440000
          x-gitbook-description-html: >-
            <p>A unique identifier to ensure idempotent request processing. If a
            request with the same idempotency key and body has already been
            processed, the cached response is returned with a 409 Conflict
            status code (which can be treated as successful). Keys are stored
            for 48 hours.</p>
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                quotes:
                  type: array
                  description: Array of quote objects to confirm
                  items:
                    type: object
                    properties:
                      id:
                        type: string
                        description: The product ID (quote ID) from the offer response
                        x-gitbook-description-html: >-
                          <p>The product ID (quote ID) from the offer
                          response</p>
                    required:
                      - id
                  x-gitbook-description-html: <p>Array of quote objects to confirm</p>
                policyholder:
                  type: object
                  description: Policyholder information
                  properties:
                    first_name:
                      type: string
                      description: Policyholder's first name
                      x-gitbook-description-html: <p>Policyholder's first name</p>
                    last_name:
                      type: string
                      description: Policyholder's last name
                      x-gitbook-description-html: <p>Policyholder's last name</p>
                    email:
                      type: string
                      format: email
                      description: Policyholder's email address
                      x-gitbook-description-html: <p>Policyholder's email address</p>
                    address1:
                      type: string
                      description: Policyholder's address line 1
                      x-gitbook-description-html: <p>Policyholder's address line 1</p>
                    city:
                      type: string
                      description: Policyholder's city
                      x-gitbook-description-html: <p>Policyholder's city</p>
                    postcode:
                      type: string
                      description: Policyholder's postal code
                      x-gitbook-description-html: <p>Policyholder's postal code</p>
                    country:
                      type: string
                      description: Policyholder's country code
                      x-gitbook-description-html: <p>Policyholder's country code</p>
                  required:
                    - first_name
                    - last_name
                    - email
                    - country
                  x-gitbook-description-html: <p>Policyholder information</p>
              required:
                - quotes
                - policyholder
            examples:
              RetailProductProtection:
                $ref: '#/components/examples/RetailProductProtectionConfirmRequest'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
                properties:
                  id:
                    type: string
                    description: Booking ID
                    x-gitbook-description-html: <p>Booking ID</p>
                  status:
                    type: string
                    description: Booking status
                    x-gitbook-description-html: <p>Booking status</p>
                  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
                        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
                            taxes:
                              type: array
                              items:
                                type: object
                                properties:
                                  tax_amount:
                                    type: number
                                  tax_code:
                                    type: string
                                  tax_amount_formatted:
                                    type: string
                            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:
                RetailProductProtection:
                  $ref: '#/components/examples/RetailProductProtectionConfirmResponse'
          x-gitbook-description-html: <p>OK</p>
        '403':
          description: Forbidden
          content:
            application/json:
              schema:
                type: object
                properties:
                  type:
                    type: string
                  message:
                    type: string
          x-gitbook-description-html: <p>Forbidden</p>
        '404':
          description: Not Found
          content:
            application/json:
              schema:
                type: object
                properties:
                  type:
                    type: string
                  message:
                    type: string
          x-gitbook-description-html: <p>Not Found</p>
        '409':
          description: Conflict - Duplicate Request (Idempotent)
          content:
            application/json:
              schema:
                type: object
                description: >-
                  Returns the cached response from the original successful
                  request. This response can be handled identically to a 200 OK
                  response.
                x-gitbook-description-html: >-
                  <p>Returns the cached response from the original successful
                  request. This response can be handled identically to a 200 OK
                  response.</p>
              examples:
                RetailProductProtection:
                  $ref: '#/components/examples/RetailProductProtectionConfirmResponse'
          x-gitbook-description-html: <p>Conflict - Duplicate Request (Idempotent)</p>
        '422':
          description: Unprocessable Entity
          content:
            application/json:
              schema:
                type: object
                properties:
                  type:
                    type: string
                  message:
                    type: string
                  errors:
                    type: array
                    items:
                      type: string
          x-gitbook-description-html: <p>Unprocessable Entity</p>
        '423':
          description: Locked - Request In Progress
          content:
            application/json:
              schema:
                type: object
                properties:
                  type:
                    type: string
                  message:
                    type: string
          x-gitbook-description-html: <p>Locked - Request In Progress</p>
      x-gitbook-description-html: >-
        <p>The Confirm Offer endpoint is used to finalize the purchase of
        products from a previously created Offer. This endpoint converts the
        selected Offer into a confirmed booking after payment has been
        successfully collected.</p><h2>Idempotency</h2><p>This endpoint supports
        idempotency keys via the <code>x-idempotency-key</code> header to
        prevent duplicate transactions. Provide a unique operation identifier
        (e.g., UUID) to ensure safe retries. Duplicate requests
        return:</p><ul><li><strong>409 Conflict</strong>: The request was
        already processed; response contains the cached original result (handle
        as success)</li><li><strong>423 Locked</strong>: The original request is
        still processing; retry after a short delay</li></ul>
    parameters:
      - name: partner_code
        in: path
        required: true
        description: >-
          Partner code identifier. Client Solutions Engineer (CSE) should
          provide this value.
        schema:
          type: string
        x-gitbook-description-html: >-
          <p>Partner code identifier. Client Solutions Engineer (CSE) should
          provide this value.</p>
      - name: offer_id
        in: path
        required: true
        description: The offer ID returned from the Create Offer endpoint.
        schema:
          type: string
        x-gitbook-description-html: <p>The offer ID returned from the Create Offer endpoint.</p>
  /partners/{partner_code}/offers/{offer_id}/opt_out/:
    post:
      summary: Opt-out Offer
      description: >-
        The Opt-out Offer endpoint is used to record when a customer declines an
        offer. This helps track conversion rates and customer preferences.
      tags:
        - Opt-out Offer
      responses:
        '204':
          description: No Content - Opt-out recorded successfully
          x-gitbook-description-html: <p>No Content - Opt-out recorded successfully</p>
        '403':
          description: Forbidden
          content:
            application/json:
              schema:
                type: object
                properties:
                  type:
                    type: string
                  message:
                    type: string
          x-gitbook-description-html: <p>Forbidden</p>
        '404':
          description: Not Found
          content:
            application/json:
              schema:
                type: object
                properties:
                  type:
                    type: string
                  message:
                    type: string
          x-gitbook-description-html: <p>Not Found</p>
      x-gitbook-description-html: >-
        <p>The Opt-out Offer endpoint is used to record when a customer declines
        an offer. This helps track conversion rates and customer
        preferences.</p>
    parameters:
      - name: partner_code
        in: path
        required: true
        description: >-
          Partner code identifier. Client Solutions Engineer (CSE) should
          provide this value.
        schema:
          type: string
        x-gitbook-description-html: >-
          <p>Partner code identifier. Client Solutions Engineer (CSE) should
          provide this value.</p>
      - name: offer_id
        in: path
        required: true
        description: The offer ID returned from the Create Offer endpoint.
        schema:
          type: string
        x-gitbook-description-html: <p>The offer ID returned from the Create Offer endpoint.</p>
  /partners/{partner_code}/bookings/{booking_id}/:
    patch:
      summary: Modify Booking
      description: >-
        The Modify Booking endpoint is used when a customer wants to make
        changes to their existing policy. This endpoint allows you to update
        policy details which may result in price adjustments, refunds, or
        additional fees. The modification is applied directly.
      tags:
        - Modify Booking
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                quotes:
                  type: array
                  items:
                    type: object
                    properties:
                      id:
                        type: string
                        description: The quote ID to modify
                        x-gitbook-description-html: <p>The quote ID to modify</p>
                      update_fields:
                        type: object
                        description: Fields to update on the quote
                        additionalProperties: true
                        x-gitbook-description-html: <p>Fields to update on the quote</p>
                    required:
                      - id
                      - update_fields
            examples:
              RetailProductProtection:
                $ref: '#/components/examples/RetailProductProtectionModifyRequest'
      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:
                RetailProductProtection:
                  $ref: '#/components/examples/RetailProductProtectionModifyResponse'
          x-gitbook-description-html: <p>OK</p>
        '403':
          description: Forbidden
          content:
            application/json:
              schema:
                type: object
                properties:
                  type:
                    type: string
                  message:
                    type: string
          x-gitbook-description-html: <p>Forbidden</p>
        '422':
          description: Unprocessable Entity
          content:
            application/json:
              schema:
                type: object
                properties:
                  type:
                    type: string
                  message:
                    type: string
                  errors:
                    type: array
                    items:
                      type: string
          x-gitbook-description-html: <p>Unprocessable Entity</p>
      x-gitbook-description-html: >-
        <p>The Modify Booking endpoint is used when a customer wants to make
        changes to their existing policy. This endpoint allows you to update
        policy details which may result in price adjustments, refunds, or
        additional fees. The modification is applied directly.</p>
    parameters:
      - name: partner_code
        in: path
        required: true
        description: >-
          Partner code identifier. Client Solutions Engineer (CSE) should
          provide this value.
        schema:
          type: string
        x-gitbook-description-html: >-
          <p>Partner code identifier. Client Solutions Engineer (CSE) should
          provide this value.</p>
      - name: booking_id
        in: path
        required: true
        description: The booking ID returned from the Confirm Offer endpoint.
        schema:
          type: string
        x-gitbook-description-html: <p>The booking ID returned from the Confirm Offer endpoint.</p>
  /partners/{partner_code}/bookings/{booking_id}/quote_for_update:
    patch:
      summary: Modify Booking - Preview
      description: >-
        The Modify Booking Preview endpoint allows you to preview the price
        changes that would result from a modification without actually 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
                        description: The quote ID to modify
                        x-gitbook-description-html: <p>The quote ID to modify</p>
                      update_fields:
                        type: object
                        description: Fields to update on the quote
                        additionalProperties: true
                        x-gitbook-description-html: <p>Fields to update on the quote</p>
                    required:
                      - id
                      - update_fields
            examples:
              RetailProductProtection:
                $ref: '#/components/examples/RetailProductProtectionModifyRequest'
      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
                    description: >-
                      The update ID to use when confirming this modification via
                      the Confirm Update endpoint.
                    x-gitbook-description-html: >-
                      <p>The update ID to use when confirming this modification
                      via the Confirm Update endpoint.</p>
              examples:
                RetailProductProtection:
                  $ref: '#/components/examples/RetailProductProtectionModifyPreviewResponse'
          x-gitbook-description-html: <p>OK</p>
        '403':
          description: Forbidden
          content:
            application/json:
              schema:
                type: object
                properties:
                  type:
                    type: string
                  message:
                    type: string
          x-gitbook-description-html: <p>Forbidden</p>
        '422':
          description: Unprocessable Entity
          content:
            application/json:
              schema:
                type: object
                properties:
                  type:
                    type: string
                  message:
                    type: string
                  errors:
                    type: object
          x-gitbook-description-html: <p>Unprocessable Entity</p>
      x-gitbook-description-html: >-
        <p>The Modify Booking Preview endpoint allows you to preview the price
        changes that would result from a modification without actually applying
        them. The response includes an update_id that can be used to confirm the
        modification.</p>
    parameters:
      - name: partner_code
        in: path
        required: true
        description: >-
          Partner code identifier. Client Solutions Engineer (CSE) should
          provide this value.
        schema:
          type: string
        x-gitbook-description-html: >-
          <p>Partner code identifier. Client Solutions Engineer (CSE) should
          provide this value.</p>
      - name: booking_id
        in: path
        required: true
        description: The booking ID returned from the Confirm Offer endpoint.
        schema:
          type: string
        x-gitbook-description-html: <p>The booking ID returned from the Confirm Offer endpoint.</p>
  /partners/{partner_code}/bookings/{booking_id}/confirm_update/{update_id}/:
    post:
      summary: Modify Booking - Confirm
      description: >-
        The Confirm Update endpoint finalizes a previewed modification. Use the
        update_id returned from the Modify Booking Preview endpoint.
      tags:
        - Modify Booking
      requestBody:
        required: false
        content:
          application/json:
            schema:
              type: object
              properties:
                xpay_charge_id:
                  type: string
                  description: XPay charge ID if additional payment is required
                  x-gitbook-description-html: <p>XPay charge ID if additional payment is required</p>
      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:
                RetailProductProtection:
                  $ref: '#/components/examples/RetailProductProtectionModifyConfirmResponse'
          x-gitbook-description-html: <p>Created</p>
        '403':
          description: Forbidden
          content:
            application/json:
              schema:
                type: object
                properties:
                  type:
                    type: string
                  message:
                    type: string
          x-gitbook-description-html: <p>Forbidden</p>
        '404':
          description: Not Found
          content:
            application/json:
              schema:
                type: object
                properties:
                  type:
                    type: string
                  message:
                    type: string
          x-gitbook-description-html: <p>Not Found</p>
        '422':
          description: Unprocessable Entity
          content:
            application/json:
              schema:
                type: object
                properties:
                  type:
                    type: string
                  message:
                    type: string
          x-gitbook-description-html: <p>Unprocessable Entity</p>
      x-gitbook-description-html: >-
        <p>The Confirm Update endpoint finalizes a previewed modification. Use
        the update_id returned from the Modify Booking Preview endpoint.</p>
    parameters:
      - name: partner_code
        in: path
        required: true
        description: >-
          Partner code identifier. Client Solutions Engineer (CSE) should
          provide this value.
        schema:
          type: string
        x-gitbook-description-html: >-
          <p>Partner code identifier. Client Solutions Engineer (CSE) should
          provide this value.</p>
      - name: booking_id
        in: path
        required: true
        description: The booking ID returned from the Confirm Offer endpoint.
        schema:
          type: string
        x-gitbook-description-html: <p>The booking ID returned from the Confirm Offer endpoint.</p>
      - name: update_id
        in: path
        required: true
        description: The update ID returned from the Modify Booking Preview endpoint.
        schema:
          type: string
        x-gitbook-description-html: >-
          <p>The update ID returned from the Modify Booking Preview
          endpoint.</p>
  /partners/{partner_code}/bookings/{booking_id}/cancel:
    post:
      summary: Cancel Booking
      description: >-
        The Cancel Booking endpoint is used when a customer no longer requires
        coverage and has contacted the partner directly to cancel the policy.
        This endpoint handles the cancellation process and calculates any
        applicable refunds.


        When `preview` is set to `true`, the cancellation is not applied but a
        preview of the refund is returned along with a `cancellation_id` that
        can be used to confirm the cancellation.


        When `preview` is set to `false` (or omitted), the cancellation is
        applied immediately.
      tags:
        - Cancel Booking
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                preview:
                  type: boolean
                  description: >-
                    When true, returns a preview of the cancellation without
                    applying it. Use the returned cancellation_id to confirm.
                  x-gitbook-description-html: >-
                    <p>When true, returns a preview of the cancellation without
                    applying it. Use the returned cancellation_id to
                    confirm.</p>
                refund_required:
                  type: boolean
                  description: Whether a refund is required for this cancellation
                  x-gitbook-description-html: <p>Whether a refund is required for this cancellation</p>
                quotes:
                  type: array
                  description: Array of quotes to cancel. Required when preview is true.
                  items:
                    type: object
                    properties:
                      id:
                        type: string
                        description: The quote ID to cancel
                        x-gitbook-description-html: <p>The quote ID to cancel</p>
                      reason_for_cancellation:
                        type: string
                        description: Reason for cancelling this quote
                        x-gitbook-description-html: <p>Reason for cancelling this quote</p>
                    required:
                      - id
                  x-gitbook-description-html: >-
                    <p>Array of quotes to cancel. Required when preview is
                    true.</p>
            examples:
              RetailProductProtectionDirectCancel:
                $ref: '#/components/examples/RetailProductProtectionCancelRequest'
              RetailProductProtectionPreviewCancel:
                $ref: '#/components/examples/RetailProductProtectionCancelPreviewRequest'
      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
                        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
                    description: >-
                      Present when preview=true. Use this ID to confirm the
                      cancellation.
                    x-gitbook-description-html: >-
                      <p>Present when preview=true. Use this ID to confirm the
                      cancellation.</p>
                  confirm_before:
                    type: string
                    format: date-time
                    nullable: true
                    description: Deadline to confirm the cancellation preview
                    x-gitbook-description-html: <p>Deadline to confirm the cancellation preview</p>
                  refund_amount:
                    type: number
                  refund_amount_formatted:
                    type: string
              examples:
                RetailProductProtectionDirectCancel:
                  $ref: '#/components/examples/RetailProductProtectionCancelResponse'
                RetailProductProtectionPreviewCancel:
                  $ref: '#/components/examples/RetailProductProtectionCancelPreviewResponse'
          x-gitbook-description-html: <p>OK</p>
        '403':
          description: Forbidden
          content:
            application/json:
              schema:
                type: object
                properties:
                  type:
                    type: string
                  message:
                    type: string
          x-gitbook-description-html: <p>Forbidden</p>
        '404':
          description: Not Found
          content:
            application/json:
              schema:
                type: object
                properties:
                  type:
                    type: string
                  message:
                    type: string
          x-gitbook-description-html: <p>Not Found</p>
        '422':
          description: Unprocessable Entity
          content:
            application/json:
              schema:
                type: object
                properties:
                  type:
                    type: string
                  message:
                    type: string
                  errors:
                    type: array
                    items:
                      type: string
          x-gitbook-description-html: <p>Unprocessable Entity</p>
      x-gitbook-description-html: >-
        <p>The Cancel Booking endpoint is used when a customer no longer
        requires coverage and has contacted the partner directly to cancel the
        policy. This endpoint handles the cancellation process and calculates
        any applicable refunds.</p><p>When <code>preview</code> is set to
        <code>true</code>, the cancellation is not applied but a preview of the
        refund is returned along with a <code>cancellation_id</code> that can be
        used to confirm the cancellation.</p><p>When <code>preview</code> is set
        to <code>false</code> (or omitted), the cancellation is applied
        immediately.</p>
    parameters:
      - name: partner_code
        in: path
        required: true
        description: >-
          Partner code identifier. Client Solutions Engineer (CSE) should
          provide this value.
        schema:
          type: string
        x-gitbook-description-html: >-
          <p>Partner code identifier. Client Solutions Engineer (CSE) should
          provide this value.</p>
      - name: booking_id
        in: path
        required: true
        description: The booking ID returned from the Confirm Offer endpoint.
        schema:
          type: string
        x-gitbook-description-html: <p>The booking ID returned from the Confirm Offer endpoint.</p>
  /partners/{partner_code}/bookings/{booking_id}/confirm_cancellation/{cancellation_id}/:
    post:
      summary: Cancel Booking - Confirm
      description: >-
        The Confirm Cancellation endpoint finalizes a previewed cancellation.
        Use the cancellation_id returned from the Cancel Booking endpoint when
        preview was set to true.
      tags:
        - Cancel Booking
      requestBody:
        required: false
        content:
          application/json:
            schema:
              type: object
              properties:
                reason_for_cancellation:
                  type: string
                  description: Reason for the cancellation
                  x-gitbook-description-html: <p>Reason for the cancellation</p>
            examples:
              RetailProductProtection:
                $ref: '#/components/examples/RetailProductProtectionCancelConfirmRequest'
      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:
                RetailProductProtection:
                  $ref: '#/components/examples/RetailProductProtectionCancelConfirmResponse'
          x-gitbook-description-html: <p>OK</p>
        '403':
          description: Forbidden
          content:
            application/json:
              schema:
                type: object
                properties:
                  type:
                    type: string
                  message:
                    type: string
          x-gitbook-description-html: <p>Forbidden</p>
        '404':
          description: Not Found
          content:
            application/json:
              schema:
                type: object
                properties:
                  type:
                    type: string
                  message:
                    type: string
          x-gitbook-description-html: <p>Not Found</p>
        '422':
          description: Unprocessable Entity
          content:
            application/json:
              schema:
                type: object
                properties:
                  type:
                    type: string
                  message:
                    type: string
                  errors:
                    type: array
                    items:
                      type: string
          x-gitbook-description-html: <p>Unprocessable Entity</p>
      x-gitbook-description-html: >-
        <p>The Confirm Cancellation endpoint finalizes a previewed cancellation.
        Use the cancellation_id returned from the Cancel Booking endpoint when
        preview was set to true.</p>
    parameters:
      - name: partner_code
        in: path
        required: true
        description: >-
          Partner code identifier. Client Solutions Engineer (CSE) should
          provide this value.
        schema:
          type: string
        x-gitbook-description-html: >-
          <p>Partner code identifier. Client Solutions Engineer (CSE) should
          provide this value.</p>
      - name: booking_id
        in: path
        required: true
        description: The booking ID returned from the Confirm Offer endpoint.
        schema:
          type: string
        x-gitbook-description-html: <p>The booking ID returned from the Confirm Offer endpoint.</p>
      - name: cancellation_id
        in: path
        required: true
        description: The cancellation ID returned from the Cancel Booking preview endpoint.
        schema:
          type: string
        x-gitbook-description-html: >-
          <p>The cancellation ID returned from the Cancel Booking preview
          endpoint.</p>
components:
  examples:
    ACMEOfferRequest:
      summary: ACME Product Protection - Create Offer Request
      value:
        schema: acme-schema-v1
        customer:
          currency: USD
          country: US
          region: NY
          language: en
        partner:
          transaction_id: '{{$guid}}'
          customer_id: '{{$guid}}'
          metadata:
            merchant_id: ACME-ONLINE-US
            merchant_name: ACME Retail
            sales_channel: online
            device: desktop
        context:
          purchase_date: '2025-12-08T14:30:00-08:00'
          estimated_shipping_date: '2025-12-14T00:00:00Z'
          estimated_delivery_date: '2025-12-18T00:00:00Z'
          product:
            sku: SKU-LAH-XY1000XM5
            brand: Living and Home
            model: XY1000XM5
            title: Portable Charcoal BBQ Grill
            variant: 2y
            category: baby carriers & accessories
            quantity: 1
            condition: new
            category_id: BBQ-101
            description: >-
              Portable Charcoal BBQ Grill,Heavy Duty Outdoor Carbon Steel
              Barbecue.
            retail_value: 134.6
            wholesale_value: 320
            term: 2y
          warranty:
            manufacturer_duration: 1y
            term: 2y
            benefit: accidental damage and extended warranty
    ACMEOfferResponse:
      summary: ACME Product Protection - Create Offer Response
      value:
        id: 73ac3ba5-51da-408d-82dc-e0b09f61c659
        offer_config_id: 2069942c-abbc-43f1-9695-73f9274e79d5
        offer_schema: acme-schema-v1
        currency: USD
        products:
          - id: ad92e3bd-9664-4c7a-a93b-16a52f4c656a
            product_config_id: d105be56-b6d9-4c83-a00b-200c1e4abbd9
            name: ACME Product Protection
            type: null
            schema_url: null
            details:
              policy_version_id: 7d101dc2-e8c6-40e4-855d-39fde21964d1
              start_date: '2025-12-08T14:30:00-08:00'
              end_date: '2027-12-08T14:30:00-08:00'
              finance:
                price:
                  total_amount: 7.99
                  total_amount_without_tax: null
                  total_amount_min: null
                  total_amount_max: null
                  total_amount_formatted: US$7.99
                  total_amount_without_tax_formatted: null
                  total_amount_min_formatted: null
                  total_amount_max_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://xcover.com/en/pds/73ac3ba5-51da-408d-82dc-e0b09f61c659?policy_type=product_insurance_offer_engine_v1
              files:
                - name: EN_AD_EW_IPID
                  url: >-
                    https://static.xcover.com/media/pds/041422fa-160d-4e30-aeab-430094d297ac/EN_AD_EW_IPID.pdf
                  type: IPID
              extra_fields:
                pricing_matrix:
                  - b2b: false
                    category: baby carriers & accessories
                    country: US
                    benefit: accidental damage and extended warranty
                    variant: 2y
                    appliance: false
                    uw_fee_rate: 0.017125
                appliance: non-appliance
                retail_ex_tax: 7.75
                taxes: {}
                tax_rate: 0
                retail_inc_tax: 7.75
                retail_inc_tax_rounded: 7.99
                retail_ex_tax_rounded: 7.99
                benefit_type: accidental damage and extended warranty
                partner_commission: null
                variant: 2y
              experiment: {}
              benefits: []
        content:
          schema_version: content:1.0
          locale: en
          slug: acme-us-offer-all-variants
          title: Retail Protection Offer Content
          extras: {}
          heading: Protect Your Purchase
          disclaimer: test
          price_unit: ''
          description: ''
          sub_heading: >-
            Extend your warranty and protect your purchase against accidental
            damage and defects.
          negative_cta: No thanks
          positive_cta: Your item is protected!
          disclaimer_html: <p data-block-key="df15u">test</p>
          required_message: Add Protection Plan
          credibility_message: ''
          negative_cta_warning: ''
        errors: {}
    RetailProductProtectionConfirmRequest:
      summary: Retail Product Protection - Confirm Offer Request
      value:
        quotes:
          - id: ad92e3bd-9664-4c7a-a93b-16a52f4c656a
        policyholder:
          first_name: Jane
          last_name: Doe
          email: jane.doe@email.com
          address1: 350 5th Avenue
          city: New York
          postcode: '10118'
          country: US
    RetailProductProtectionConfirmResponse:
      summary: Retail Product Protection - Confirm Offer Response
      value:
        id: Q5K8M-3PR2N-INS
        status: CONFIRMED
        currency: USD
        total_price: 7.99
        total_price_formatted: US$7.99
        partner_transaction_id: null
        created_at: '2025-12-08T22:30:00.000000Z'
        updated_at: '2025-12-08T22:30:00.150000Z'
        pds_url: https://www.xcover.com/en/pds/Q5K8M-3PR2N-INS
        security_token: 9bFkX-WzAoa-oHjBK-14f6M
        quotes:
          - id: ad92e3bd-9664-4c7a-a93b-16a52f4c656a
            policy_start_date: '2025-12-08T14:30:00-08:00'
            policy_end_date: '2027-12-08T14:30:00-08:00'
            status: CONFIRMED
            price: 7.99
            price_formatted: US$7.99
            policy:
              policy_type: product_insurance_offer_engine
              policy_type_version: '1'
              policy_type_slug: product_insurance_offer_engine_v1
              policy_type_group_name: retail
              policy_name: ACME Product Protection
              policy_code: QPP0001
              policy_version: 7d101dc2-e8c6-40e4-855d-39fde21964d1
              category: product_insurance
              policy_currency: USD
            tax:
              total_tax: 0
              total_amount_without_tax: 7.99
              taxes: []
              total_tax_formatted: US$0.00
              total_amount_without_tax_formatted: US$7.99
            benefits: []
            commission:
              partner_commission: 0
              surcharge_commission: 0
              total_commission: 0
              partner_commission_formatted: US$0.00
              surcharge_commission_formatted: US$0.00
              total_commission_formatted: US$0.00
            created_at: '2025-12-08T22:30:00.000000Z'
            confirmed_at: '2025-12-08T22:30:00.150000Z'
            updated_at: '2025-12-08T22:30:00.150000Z'
            cancelled_at: null
            cancelled_from: null
            is_renewable: false
            can_be_cancelled: true
            pds_url: >-
              https://www.xcover.com/en/pds/Q5K8M-3PR2N-INS?policy_type=product_insurance_offer_engine_v1&quote_id=ad92e3bd-9664-4c7a-a93b-16a52f4c656a
        coi:
          url: >-
            https://www.xcover.com/en/coi/Q5K8M-3PR2N-INS?security_token=9bFkX-WzAoa-oHjBK-14f6M
          pdf: >-
            https://www.xcover.com/en/coi/Q5K8M-3PR2N-INS.pdf?security_token=9bFkX-WzAoa-oHjBK-14f6M
        account_url: >-
          https://www.xcover.com/en/account?id=c4a91d2e-efb5-4574-abcd-d8f8f599a6c1
        sign_up_url: >-
          https://www.xcover.com/en/account?id=c4a91d2e-efb5-4574-abcd-d8f8f599a6c1
        policyholder:
          first_name: Jane
          last_name: Doe
          email: jane.doe@email.com
          phone: null
          address1: 350 5th Avenue
          city: New York
          region: NY
          postcode: '10118'
          country: US
          allow_updates: true
        total_tax: 0
        total_tax_formatted: US$0.00
        total_premium: 7.99
        total_premium_formatted: US$7.99
        fnol_link: >-
          https://www.xcover.com/en/account/claims/fnol?bookingID=Q5K8M-3PR2N-INS&security_token=9bFkX-WzAoa-oHjBK-14f6M
        booking_agent: null
    RetailProductProtectionModifyRequest:
      summary: Retail Product Protection - Modify Booking Request
      value:
        quotes:
          - id: ad92e3bd-9664-4c7a-a93b-16a52f4c656a
            update_fields:
              context:
                product:
                  retail_value: 149.99
    RetailProductProtectionModifyResponse:
      summary: Retail Product Protection - Modify Booking Response
      value:
        id: Q5K8M-3PR2N-INS
        status: CONFIRMED
        currency: USD
        total_price: 8.99
        total_price_formatted: US$8.99
        partner_transaction_id: null
        created_at: '2025-12-08T22:30:00.000000Z'
        updated_at: '2025-12-09T09:15:00.000000Z'
        pds_url: https://www.xcover.com/en/pds/Q5K8M-3PR2N-INS
        security_token: 9bFkX-WzAoa-oHjBK-14f6M
        quotes:
          - id: ad92e3bd-9664-4c7a-a93b-16a52f4c656a
            policy_start_date: '2025-12-08T14:30:00-08:00'
            policy_end_date: '2027-12-08T14:30:00-08:00'
            status: CONFIRMED
            price: 8.99
            price_formatted: US$8.99
            price_diff: 1
            price_diff_formatted: US$1.00
            policy:
              policy_type: product_insurance_offer_engine
              policy_type_version: '1'
              policy_type_slug: product_insurance_offer_engine_v1
              policy_type_group_name: retail
              policy_name: ACME Product Protection
              policy_code: QPP0001
              policy_version: 7d101dc2-e8c6-40e4-855d-39fde21964d1
              category: product_insurance
              policy_currency: USD
            tax:
              total_tax: 0
              total_amount_without_tax: 8.99
              total_tax_formatted: US$0.00
              total_amount_without_tax_formatted: US$8.99
            commission:
              partner_commission: 0
              total_commission: 0
              partner_commission_formatted: US$0.00
              total_commission_formatted: US$0.00
            can_be_cancelled: true
        coi:
          url: >-
            https://www.xcover.com/en/coi/Q5K8M-3PR2N-INS?security_token=9bFkX-WzAoa-oHjBK-14f6M
          pdf: >-
            https://www.xcover.com/en/coi/Q5K8M-3PR2N-INS.pdf?security_token=9bFkX-WzAoa-oHjBK-14f6M
        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: 8.99
        total_premium_formatted: US$8.99
        total_price_diff: 1
        total_price_diff_formatted: US$1.00
        fnol_link: >-
          https://www.xcover.com/en/account/claims/fnol?bookingID=Q5K8M-3PR2N-INS&security_token=9bFkX-WzAoa-oHjBK-14f6M
    RetailProductProtectionModifyPreviewResponse:
      summary: Retail Product Protection - Modify Booking Preview Response
      value:
        id: Q5K8M-3PR2N-INS
        status: CONFIRMED
        currency: USD
        total_price: 8.99
        total_price_formatted: US$8.99
        partner_transaction_id: null
        created_at: '2025-12-08T22:30:00.000000Z'
        updated_at: '2025-12-09T09:15:00.000000Z'
        pds_url: https://www.xcover.com/en/pds/Q5K8M-3PR2N-INS
        security_token: 9bFkX-WzAoa-oHjBK-14f6M
        quotes:
          - id: ad92e3bd-9664-4c7a-a93b-16a52f4c656a
            policy_start_date: '2025-12-08T14:30:00-08:00'
            policy_end_date: '2027-12-08T14:30:00-08:00'
            status: CONFIRMED
            price: 8.99
            price_formatted: US$8.99
            price_diff: 1
            price_diff_formatted: US$1.00
        total_price_diff: 1
        total_price_diff_formatted: US$1.00
        update_id: VbXr3-UPpMW-h2YO8
    RetailProductProtectionModifyConfirmResponse:
      summary: Retail Product Protection - Modify Booking Confirm Response
      value:
        id: Q5K8M-3PR2N-INS
        status: CONFIRMED
        currency: USD
        total_price: 8.99
        total_price_formatted: US$8.99
        partner_transaction_id: null
        created_at: '2025-12-08T22:30:00.000000Z'
        updated_at: '2025-12-09T09:20:00.000000Z'
        pds_url: https://www.xcover.com/en/pds/Q5K8M-3PR2N-INS
        security_token: 9bFkX-WzAoa-oHjBK-14f6M
        quotes:
          - id: ad92e3bd-9664-4c7a-a93b-16a52f4c656a
            policy_start_date: '2025-12-08T14:30:00-08:00'
            policy_end_date: '2027-12-08T14:30:00-08:00'
            status: CONFIRMED
            price: 8.99
            price_formatted: US$8.99
            price_diff: 1
            price_diff_formatted: US$1.00
        coi:
          url: >-
            https://www.xcover.com/en/coi/Q5K8M-3PR2N-INS?security_token=9bFkX-WzAoa-oHjBK-14f6M
          pdf: >-
            https://www.xcover.com/en/coi/Q5K8M-3PR2N-INS.pdf?security_token=9bFkX-WzAoa-oHjBK-14f6M
        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: 8.99
        total_premium_formatted: US$8.99
        total_price_diff: 1
        total_price_diff_formatted: US$1.00
        fnol_link: >-
          https://www.xcover.com/en/account/claims/fnol?bookingID=Q5K8M-3PR2N-INS&security_token=9bFkX-WzAoa-oHjBK-14f6M
    RetailProductProtectionCancelRequest:
      summary: Retail Product Protection - Cancel Booking Request (Direct)
      value:
        preview: false
        refund_required: true
    RetailProductProtectionCancelResponse:
      summary: Retail Product Protection - Cancel Booking Response (Direct)
      value:
        id: Q5K8M-3PR2N-INS
        status: CANCELLED
        quotes:
          - id: ad92e3bd-9664-4c7a-a93b-16a52f4c656a
            policy_start_date: '2025-12-08T14:30:00-08:00'
            policy_end_date: '2027-12-08T14:30:00-08:00'
            policy_cancellation_date: '2025-12-10T10:00:00.000000Z'
            policy_coolingoff_date: '2025-12-22T22:30:00.000000Z'
            status: CANCELLED
            price: 7.99
            refund_value: 7.99
            adjustment_fee: 0
            policy:
              policy_type: product_insurance_offer_engine
              policy_type_version: '1'
              policy_type_slug: product_insurance_offer_engine_v1
              policy_type_group_name: retail
              policy_name: ACME Product Protection
              policy_code: QPP0001
              policy_version: 7d101dc2-e8c6-40e4-855d-39fde21964d1
              category: product_insurance
              policy_currency: USD
            created_at: '2025-12-08T22:30:00.000000Z'
            confirmed_at: '2025-12-08T22:30:00.150000Z'
            updated_at: '2025-12-10T10:00:00.000000Z'
            cancelled_at: '2025-12-10T10:00:00.000000Z'
            cancelled_from: '2025-12-10T10:00:00.000000Z'
            commission: null
        policyholder:
          first_name: Jane
          last_name: Doe
          email: jane.doe@email.com
          country: US
          allow_updates: false
          fields_allowed_to_update: []
        pds_url: https://www.xcover.com/en/pds/Q5K8M-3PR2N-INS
        coi:
          url: >-
            https://www.xcover.com/en/coi/Q5K8M-3PR2N-INS?security_token=9bFkX-WzAoa-oHjBK-14f6M
          pdf: >-
            https://www.xcover.com/en/coi/Q5K8M-3PR2N-INS.pdf?security_token=9bFkX-WzAoa-oHjBK-14f6M
        created_at: '2025-12-08T22:30:00.000000Z'
        updated_at: '2025-12-10T10:00:00.000000Z'
        total_price: 0
        total_price_formatted: US$0.00
        total_refund: 7.99
        total_refund_formatted: US$7.99
        total_tax: 0
        total_tax_formatted: US$0.00
        total_premium: 0
        total_premium_formatted: US$0.00
        currency: USD
        cancellation_id: null
        confirm_before: null
        refund_amount: 7.99
        refund_amount_formatted: US$7.99
        cancellation_payout_url: null
    RetailProductProtectionCancelPreviewRequest:
      summary: Retail Product Protection - Cancel Booking Request (Preview)
      value:
        preview: true
        refund_required: true
        quotes:
          - id: ad92e3bd-9664-4c7a-a93b-16a52f4c656a
            reason_for_cancellation: product returned
    RetailProductProtectionCancelPreviewResponse:
      summary: Retail Product Protection - Cancel Booking Response (Preview)
      value:
        id: Q5K8M-3PR2N-INS
        status: CANCELLED
        quotes:
          - id: ad92e3bd-9664-4c7a-a93b-16a52f4c656a
            policy_start_date: '2025-12-08T14:30:00-08:00'
            policy_end_date: '2027-12-08T14:30:00-08:00'
            policy_cancellation_date: null
            policy_coolingoff_date: '2025-12-22T22:30:00.000000Z'
            status: CANCELLED
            price: 7.99
            refund_value: 7.99
            adjustment_fee: 0
            policy:
              policy_type: product_insurance_offer_engine
              policy_type_version: '1'
              policy_type_slug: product_insurance_offer_engine_v1
              policy_type_group_name: retail
              policy_name: ACME Product Protection
              policy_code: QPP0001
              policy_version: 7d101dc2-e8c6-40e4-855d-39fde21964d1
              category: product_insurance
              policy_currency: USD
            created_at: '2025-12-08T22:30:00.000000Z'
            confirmed_at: '2025-12-08T22:30:00.150000Z'
            updated_at: '2025-12-10T10:00:00.000000Z'
            cancelled_at: null
            cancelled_from: null
            commission: null
        policyholder:
          first_name: Jane
          last_name: Doe
          email: jane.doe@email.com
          country: US
          allow_updates: true
        pds_url: https://www.xcover.com/en/pds/Q5K8M-3PR2N-INS
        coi:
          url: >-
            https://www.xcover.com/en/coi/Q5K8M-3PR2N-INS?security_token=9bFkX-WzAoa-oHjBK-14f6M
          pdf: >-
            https://www.xcover.com/en/coi/Q5K8M-3PR2N-INS.pdf?security_token=9bFkX-WzAoa-oHjBK-14f6M
        created_at: '2025-12-08T22:30:00.000000Z'
        updated_at: '2025-12-10T10:00:00.000000Z'
        total_price: 0
        total_price_formatted: US$0.00
        total_refund: 7.99
        total_refund_formatted: US$7.99
        total_tax: 0
        total_tax_formatted: US$0.00
        total_premium: 0
        total_premium_formatted: US$0.00
        currency: USD
        cancellation_id: nsX8f-21DZ5-ZZx4J-CCL
        confirm_before: '2025-12-11T10:00:00.000000Z'
        refund_amount: 7.99
        refund_amount_formatted: US$7.99
        cancellation_payout_url: null
    RetailProductProtectionCancelConfirmRequest:
      summary: Retail Product Protection - Cancel Booking Confirm Request
      value:
        reason_for_cancellation: product returned
    RetailProductProtectionCancelConfirmResponse:
      summary: Retail Product Protection - Cancel Booking Confirm Response
      value:
        id: Q5K8M-3PR2N-INS
        status: CANCELLED
        quotes:
          - id: ad92e3bd-9664-4c7a-a93b-16a52f4c656a
            policy_start_date: '2025-12-08T14:30:00-08:00'
            policy_end_date: '2027-12-08T14:30:00-08:00'
            policy_cancellation_date: '2025-12-10T10:05:00.000000Z'
            policy_coolingoff_date: '2025-12-22T22:30:00.000000Z'
            status: CANCELLED
            price: 7.99
            refund_value: 7.99
            adjustment_fee: 0
            created_at: '2025-12-08T22:30:00.000000Z'
            confirmed_at: '2025-12-08T22:30:00.150000Z'
            updated_at: '2025-12-10T10:05:00.000000Z'
            cancelled_at: '2025-12-10T10:05:00.000000Z'
            cancelled_from: '2025-12-10T10:05:00.000000Z'
            commission: null
        policyholder:
          first_name: Jane
          last_name: Doe
          email: jane.doe@email.com
          country: US
          allow_updates: false
          fields_allowed_to_update: []
        pds_url: https://www.xcover.com/en/pds/Q5K8M-3PR2N-INS
        coi:
          url: >-
            https://www.xcover.com/en/coi/Q5K8M-3PR2N-INS?security_token=9bFkX-WzAoa-oHjBK-14f6M
          pdf: >-
            https://www.xcover.com/en/coi/Q5K8M-3PR2N-INS.pdf?security_token=9bFkX-WzAoa-oHjBK-14f6M
        created_at: '2025-12-08T22:30:00.000000Z'
        updated_at: '2025-12-10T10:05:00.000000Z'
        total_price: 0
        total_price_formatted: US$0.00
        total_refund: 7.99
        total_refund_formatted: US$7.99
        total_tax: 0
        total_tax_formatted: US$0.00
        total_premium: 0
        total_premium_formatted: US$0.00
        currency: USD
        cancellation_id: null
        confirm_before: null
        refund_amount: 7.99
        refund_amount_formatted: US$7.99
        cancellation_payout_url: null
  securitySchemes:
    CustomAPISignature:
      type: apiKey
      name: Authorization
      in: header
      description: >
        **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: a1b2c3d4e5f6g7h8`


        ### 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**.
      x-gitbook-description-html: >-
        <p><strong>Composite Authentication Scheme (Client Key, Date, and
        Signature)</strong></p>

        <p>This scheme requires the client to provide <strong>three</strong>
        mandatory headers in every request:</p>

        <h3>1. X-Api-Key (Client Key)</h3>

        <ul>

        <li><strong>Purpose:</strong> Public identifier for the API
        consumer.</li>

        <li><strong>Example:</strong> <code>X-Api-Key:
        a1b2c3d4e5f6g7h8</code></li>

        </ul>

        <h3>2. Date (Timestamp)</h3>

        <ul>

        <li><strong>Purpose:</strong> Timestamp used for generating the
        signature and preventing replay attacks.</li>

        <li><strong>Format:</strong> RFC 7231 format (e.g., in GMT).</li>

        <li><strong>Example:</strong> <code>Date: Sun, 09 Nov 2025 04:04:00
        GMT</code></li>

        </ul>

        <h3>3. Authorization (Computed Signature)</h3>

        <ul>

        <li><strong>Purpose:</strong> The cryptographic signature that verifies
        the request's authenticity and integrity.</li>

        <li><strong>Format:</strong> <code>SIGNATURE [authHeader]</code></li>

        </ul>

        <p><strong>Signature Generation Logic:</strong>

        The <code>authHeader</code> value is derived from a cryptographic hash
        (e.g., HMAC-SHA256) of canonical request components (HTTP Method, Path,
        and the contents of the <code>Date</code> header), signed with the
        private <strong>Client Secret</strong>.</p>
security:
  - CustomAPISignature: []
