openapi: 3.0.0
info:
  title: Offers API - Logistics
  version: 1.0.0
  description: >-
    The Offers API enables logistics partners to create, confirm, and manage
    shipping protection offers for parcels. It provides endpoints for
    generating offers, confirming bookings, handling opt-outs, modifying
    shipping details, and cancelling protection.
  x-gitbook-description-html: >-
    <p>The Offers API enables logistics partners to create, confirm, and manage
    shipping protection offers for parcels. It provides endpoints for
    generating offers, confirming bookings, handling opt-outs, modifying
    shipping details, and cancelling protection.</p>
servers:
  - url: https://api.xcover.com/x
paths:
  /partners/{partner_code}/offers/:
    post:
      summary: Create Offer
      description: >-
        The Create Offer endpoint generates shipping protection offerings for
        one or more parcels. The request describes the order, the packages
        being shipped, the carrier, and the sender/receiver. The response
        returns one or more products with pricing and policy details.
      tags:
        - Create Offer
      parameters:
        - name: active_only
          in: query
          required: false
          description: When using a test API key, only return active offers
          schema:
            type: boolean
            default: false
        - name: include_content
          in: query
          required: false
          description: Include localized content in the response
          schema:
            type: boolean
            default: true
        - name: extra_fields
          in: query
          required: false
          description: >-
            Comma-separated list of specific extra fields to include. Available
            fields: tax, commission, benefits, surcharge
          schema:
            type: string
        - name: exclude_offer_ids
          in: query
          required: false
          description: >-
            Comma-separated list of Offer Config IDs to exclude from the
            response
          schema:
            type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                schema:
                  type: string
                  description: >-
                    Schema identifier for the offer type. 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-logistics-schema-v1
                placement:
                  type: string
                  description: >-
                    Where the offer is being displayed in the partner flow
                    (e.g., checkout, cart, post-purchase).
                customer:
                  type: object
                  description: Customer information
                  properties:
                    currency:
                      type: string
                      description: Currency code (e.g., USD, AUD, EUR, GBP)
                    country:
                      type: string
                      description: Customer's country code (e.g., US, AU, GB)
                    region:
                      type: string
                      description: Customer's region or state
                    language:
                      type: string
                      description: Customer's preferred language (e.g., en)
                    email:
                      type: string
                      format: email
                    ip:
                      type: string
                    postcode:
                      type: string
                  required:
                    - currency
                    - country
                    - language
                partner:
                  type: object
                  description: Partner information
                  properties:
                    transaction_id:
                      type: string
                      description: Partner transaction identifier
                    customer_id:
                      type: string
                      description: Partner customer identifier
                    subsidiary:
                      type: string
                      description: Partner subsidiary identifier
                    metadata:
                      type: object
                      description: Additional partner metadata
                      properties:
                        merchant_id:
                          type: string
                          description: Merchant identifier
                        merchant_name:
                          type: string
                          description: Human-readable merchant name
                      additionalProperties: true
                context:
                  type: object
                  description: >-
                    Logistics-specific context describing the order, shipment,
                    packages, sender, and receiver.
                  properties:
                    order_total:
                      type: integer
                      description: >-
                        Total order amount in the minor unit of the customer
                        currency (e.g., cents for USD).
                    shipping_cost:
                      type: integer
                      description: Shipping cost charged to the customer (minor units).
                    declared_value:
                      type: integer
                      description: >-
                        Total declared value of the shipment (minor units).
                        Used to derive coverage.
                    lot_url:
                      type: string
                      format: uri
                      description: >-
                        URL to the product listing or order summary, used for
                        downstream verification.
                    carrier:
                      type: string
                      description: Shipping carrier (e.g., UPS, FedEx, USPS, DHL).
                    carrier_service_name:
                      type: string
                      description: Specific carrier service (e.g., UPS Ground, FedEx Express).
                    shipping_date:
                      type: string
                      format: date-time
                      description: Date the shipment is dispatched.
                    shipping_method:
                      type: string
                      description: How the package is handed to the carrier (e.g., drop off, pickup).
                    frontend_distr:
                      type: boolean
                      description: >-
                        True when the offer is presented directly to the end
                        customer (frontend distribution).
                    dual_coverage:
                      type: boolean
                      description: >-
                        True when the shipment is already partially covered by
                        the carrier (used to avoid double coverage).
                    packages:
                      type: array
                      description: Packages being shipped under this offer.
                      items:
                        type: object
                        properties:
                          type:
                            type: string
                            description: Package type (e.g., Parcel, Pallet, Envelope).
                          width:
                            type: number
                            description: Package width.
                          height:
                            type: number
                            description: Package height.
                          length:
                            type: number
                            description: Package length.
                          weight:
                            type: number
                            description: Package weight.
                          description:
                            type: string
                            description: Free-text description of the package contents.
                          declared_value:
                            type: integer
                            description: Declared value of this package (minor units).
                          items:
                            type: array
                            description: Individual items contained in the package.
                            items:
                              type: object
                              properties:
                                sku:
                                  type: string
                                hs_code:
                                  type: string
                                  description: Harmonized System (HS) tariff code.
                                brand:
                                  type: string
                                model:
                                  type: string
                                description:
                                  type: string
                                quantity:
                                  type: integer
                                price:
                                  type: integer
                                  description: Item price (minor units).
                              required:
                                - sku
                                - quantity
                                - price
                        required:
                          - type
                          - declared_value
                    receiver:
                      type: object
                      description: Recipient of the shipment.
                      properties:
                        first_name:
                          type: string
                        last_name:
                          type: string
                        address1:
                          type: string
                        address2:
                          type: string
                        city:
                          type: string
                        postcode:
                          type: string
                        region:
                          type: string
                        country:
                          type: string
                        email:
                          type: string
                          format: email
                        phone:
                          type: string
                      required:
                        - first_name
                        - last_name
                        - address1
                        - city
                        - postcode
                        - country
                    sender:
                      type: object
                      description: Sender / fulfillment origin.
                      properties:
                        first_name:
                          type: string
                        last_name:
                          type: string
                        company_name:
                          type: string
                        address1:
                          type: string
                        address2:
                          type: string
                        city:
                          type: string
                        postcode:
                          type: string
                        region:
                          type: string
                        country:
                          type: string
                        email:
                          type: string
                          format: email
                        phone:
                          type: string
                  additionalProperties: true
              required:
                - schema
                - customer
                - context
            examples:
              ACMELogistics:
                $ref: '#/components/examples/ACMELogisticsOfferRequest'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
                properties:
                  id:
                    type: string
                    description: Offer ID
                  offer_config_id:
                    type: string
                  offer_schema:
                    type: string
                  currency:
                    type: string
                  products:
                    type: array
                    items:
                      type: object
                      properties:
                        id:
                          type: string
                        product_config_id:
                          type: string
                        name:
                          type: string
                        type:
                          type: string
                          nullable: true
                        schema_url:
                          type: string
                          nullable: true
                          format: uri
                        details:
                          type: object
                          properties:
                            policy_version_id:
                              type: string
                            start_date:
                              type: string
                              format: date-time
                              nullable: true
                            end_date:
                              type: string
                              format: date-time
                              nullable: true
                            finance:
                              type: object
                              properties:
                                price:
                                  type: object
                                  properties:
                                    total_amount:
                                      type: number
                                      nullable: true
                                    total_amount_without_tax:
                                      type: number
                                      nullable: true
                                    total_amount_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
                            files:
                              type: array
                              items:
                                type: object
                                properties:
                                  name:
                                    type: string
                                  url:
                                    type: string
                                    format: uri
                                  type:
                                    type: string
                            extra_fields:
                              type: object
                              description: >-
                                Logistics-specific computed fields about the
                                resulting policy.
                              properties:
                                shipping_type:
                                  type: string
                                  description: >-
                                    Computed shipment classification (e.g.,
                                    domestic, international).
                                address_computed:
                                  type: string
                                  description: >-
                                    Receiver address concatenated for
                                    verification.
                                policy_end_date:
                                  type: string
                                  format: date-time
                                  nullable: true
                                policy_duration:
                                  type: integer
                                  description: Coverage duration in days.
                                partner_subsidiary:
                                  type: string
                                  nullable: true
                              additionalProperties: true
                            experiment:
                              type: object
                              additionalProperties: true
                            benefits:
                              type: array
                              items:
                                type: object
                                additionalProperties: true
                  content:
                    type: object
                    properties:
                      schema_version:
                        type: string
                      locale:
                        type: string
                  errors:
                    type: object
                    additionalProperties: true
              examples:
                ACMELogistics:
                  $ref: '#/components/examples/ACMELogisticsOfferResponse'
        '403':
          description: Forbidden
          content:
            application/json:
              schema:
                type: object
                properties:
                  type:
                    type: string
                  message:
                    type: string
        '422':
          description: Unprocessable Entity
          content:
            application/json:
              schema:
                type: object
                properties:
                  type:
                    type: string
                  message:
                    type: string
                  errors:
                    type: object
                    properties:
                      schema:
                        type: array
                        items:
                          type: string
    parameters:
      - name: partner_code
        in: path
        required: true
        description: >-
          Partner code identifier. Client Solutions Engineer (CSE) should
          provide this value.
        schema:
          type: string
  /partners/{partner_code}/offers/{offer_id}/confirm/:
    post:
      summary: Confirm Offer
      description: >-
        Finalize the purchase of shipping protection from a previously created
        Offer. Converts the selected Offer into a confirmed booking after
        payment has been collected.


        ## Idempotency


        This endpoint supports idempotency keys via the `x-idempotency-key`
        header to prevent duplicate transactions.
      tags:
        - Confirm Offer
      parameters:
        - name: x-idempotency-key
          in: header
          required: false
          description: >-
            A unique identifier to ensure idempotent request processing. Keys
            are stored for 48 hours.
          schema:
            type: string
            format: uuid
      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
                    required:
                      - id
                policyholder:
                  type: object
                  description: >-
                    Policyholder information. For logistics, this is typically
                    the shipment receiver.
                  properties:
                    first_name:
                      type: string
                    last_name:
                      type: string
                    email:
                      type: string
                      format: email
                    address1:
                      type: string
                    address2:
                      type: string
                    city:
                      type: string
                    postcode:
                      type: string
                    region:
                      type: string
                    country:
                      type: string
                  required:
                    - first_name
                    - last_name
                    - email
                    - country
              required:
                - quotes
                - policyholder
            examples:
              ACMELogistics:
                $ref: '#/components/examples/ACMELogisticsConfirmRequest'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
                properties:
                  id:
                    type: string
                  status:
                    type: string
                  currency:
                    type: string
                  total_price:
                    type: number
                  total_price_formatted:
                    type: string
                  partner_transaction_id:
                    type: string
                    nullable: true
                  created_at:
                    type: string
                    format: date-time
                  updated_at:
                    type: string
                    format: date-time
                  pds_url:
                    type: string
                    format: uri
                  security_token:
                    type: string
                  quotes:
                    type: array
                    items:
                      type: object
                      properties:
                        id:
                          type: string
                        policy_start_date:
                          type: string
                          format: date-time
                        policy_end_date:
                          type: string
                          format: date-time
                          nullable: true
                        status:
                          type: string
                        price:
                          type: number
                        price_formatted:
                          type: string
                        policy:
                          type: object
                          properties:
                            policy_type:
                              type: string
                            policy_type_version:
                              type: string
                            policy_type_slug:
                              type: string
                            policy_type_group_name:
                              type: string
                            policy_name:
                              type: string
                            policy_code:
                              type: string
                            policy_version:
                              type: string
                            category:
                              type: string
                            policy_currency:
                              type: string
                        tax:
                          type: object
                          properties:
                            total_tax:
                              type: number
                              nullable: true
                            total_amount_without_tax:
                              type: number
                              nullable: true
                            total_tax_formatted:
                              type: string
                              nullable: true
                            total_amount_without_tax_formatted:
                              type: string
                              nullable: true
                        benefits:
                          type: array
                          items:
                            type: object
                            additionalProperties: true
                        commission:
                          type: object
                          properties:
                            partner_commission:
                              type: number
                              nullable: true
                            total_commission:
                              type: number
                              nullable: true
                            partner_commission_formatted:
                              type: string
                              nullable: true
                            total_commission_formatted:
                              type: string
                              nullable: true
                        created_at:
                          type: string
                          format: date-time
                        confirmed_at:
                          type: string
                          format: date-time
                        pds_url:
                          type: string
                          format: uri
                        can_be_cancelled:
                          type: boolean
                  coi:
                    type: object
                    properties:
                      url:
                        type: string
                        format: uri
                      pdf:
                        type: string
                        format: uri
                  policyholder:
                    type: object
                    properties:
                      first_name:
                        type: string
                      last_name:
                        type: string
                      email:
                        type: string
                        format: email
                      country:
                        type: string
                  total_tax:
                    type: number
                  total_tax_formatted:
                    type: string
                  total_premium:
                    type: number
                  total_premium_formatted:
                    type: string
                  fnol_link:
                    type: string
                    format: uri
              examples:
                ACMELogistics:
                  $ref: '#/components/examples/ACMELogisticsConfirmResponse'
        '403':
          description: Forbidden
          content:
            application/json:
              schema:
                type: object
                properties:
                  type:
                    type: string
                  message:
                    type: string
        '404':
          description: Not Found
          content:
            application/json:
              schema:
                type: object
                properties:
                  type:
                    type: string
                  message:
                    type: string
        '409':
          description: Conflict - Duplicate Request (Idempotent)
          content:
            application/json:
              schema:
                type: object
              examples:
                ACMELogistics:
                  $ref: '#/components/examples/ACMELogisticsConfirmResponse'
        '422':
          description: Unprocessable Entity
          content:
            application/json:
              schema:
                type: object
                properties:
                  type:
                    type: string
                  message:
                    type: string
                  errors:
                    type: array
                    items:
                      type: string
        '423':
          description: Locked - Request In Progress
          content:
            application/json:
              schema:
                type: object
                properties:
                  type:
                    type: string
                  message:
                    type: string
    parameters:
      - name: partner_code
        in: path
        required: true
        schema:
          type: string
      - name: offer_id
        in: path
        required: true
        description: The offer ID returned from the Create Offer endpoint.
        schema:
          type: string
  /partners/{partner_code}/offers/{offer_id}/opt_out/:
    post:
      summary: Opt-out Offer
      description: >-
        Record when a customer declines a shipping protection offer. Helps
        track conversion rates and customer preferences.
      tags:
        - Opt-out Offer
      responses:
        '204':
          description: No Content - Opt-out recorded successfully
        '403':
          description: Forbidden
          content:
            application/json:
              schema:
                type: object
                properties:
                  type:
                    type: string
                  message:
                    type: string
        '404':
          description: Not Found
          content:
            application/json:
              schema:
                type: object
                properties:
                  type:
                    type: string
                  message:
                    type: string
    parameters:
      - name: partner_code
        in: path
        required: true
        schema:
          type: string
      - name: offer_id
        in: path
        required: true
        description: The offer ID returned from the Create Offer endpoint.
        schema:
          type: string
  /partners/{partner_code}/bookings/{booking_id}/:
    patch:
      summary: Modify Booking
      description: >-
        Modify an existing shipping protection booking. Typical logistics
        modifications include updating the shipping date when dispatch slips,
        or adjusting carrier details. The modification is applied directly and
        may produce a small price adjustment.
      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
                      update_fields:
                        type: object
                        description: >-
                          Fields to update on the quote. For logistics, common
                          fields include shipping_date, carrier, and
                          carrier_service_name.
                        additionalProperties: true
                    required:
                      - id
                      - update_fields
            examples:
              ACMELogistics:
                $ref: '#/components/examples/ACMELogisticsModifyRequest'
      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:
                ACMELogistics:
                  $ref: '#/components/examples/ACMELogisticsModifyResponse'
        '403':
          description: Forbidden
          content:
            application/json:
              schema:
                type: object
                properties:
                  type:
                    type: string
                  message:
                    type: string
        '422':
          description: Unprocessable Entity
          content:
            application/json:
              schema:
                type: object
                properties:
                  type:
                    type: string
                  message:
                    type: string
                  errors:
                    type: array
                    items:
                      type: string
    parameters:
      - name: partner_code
        in: path
        required: true
        schema:
          type: string
      - name: booking_id
        in: path
        required: true
        description: The booking ID returned from the Confirm Offer endpoint.
        schema:
          type: string
  /partners/{partner_code}/bookings/{booking_id}/quote_for_update:
    patch:
      summary: Modify Booking - Preview
      description: >-
        Preview the price changes that would result from a modification
        without applying them. The response includes an `update_id` that can
        be used to confirm the modification.
      tags:
        - Modify Booking
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                quotes:
                  type: array
                  items:
                    type: object
                    properties:
                      id:
                        type: string
                      update_fields:
                        type: object
                        additionalProperties: true
                    required:
                      - id
                      - update_fields
            examples:
              ACMELogistics:
                $ref: '#/components/examples/ACMELogisticsModifyRequest'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
                properties:
                  id:
                    type: string
                  status:
                    type: string
                  currency:
                    type: string
                  total_price:
                    type: number
                  total_price_formatted:
                    type: string
                  quotes:
                    type: array
                    items:
                      type: object
                      properties:
                        id:
                          type: string
                        status:
                          type: string
                        price:
                          type: number
                        price_formatted:
                          type: string
                        price_diff:
                          type: number
                        price_diff_formatted:
                          type: string
                  total_price_diff:
                    type: number
                  total_price_diff_formatted:
                    type: string
                  update_id:
                    type: string
              examples:
                ACMELogistics:
                  $ref: '#/components/examples/ACMELogisticsModifyPreviewResponse'
        '403':
          description: Forbidden
          content:
            application/json:
              schema:
                type: object
                properties:
                  type:
                    type: string
                  message:
                    type: string
        '422':
          description: Unprocessable Entity
          content:
            application/json:
              schema:
                type: object
                properties:
                  type:
                    type: string
                  message:
                    type: string
                  errors:
                    type: object
    parameters:
      - name: partner_code
        in: path
        required: true
        schema:
          type: string
      - name: booking_id
        in: path
        required: true
        schema:
          type: string
  /partners/{partner_code}/bookings/{booking_id}/confirm_update/{update_id}/:
    post:
      summary: Modify Booking - Confirm
      description: >-
        Finalize a previewed modification. 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
      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:
                ACMELogistics:
                  $ref: '#/components/examples/ACMELogisticsModifyConfirmResponse'
        '403':
          description: Forbidden
          content:
            application/json:
              schema:
                type: object
                properties:
                  type:
                    type: string
                  message:
                    type: string
        '404':
          description: Not Found
          content:
            application/json:
              schema:
                type: object
                properties:
                  type:
                    type: string
                  message:
                    type: string
        '422':
          description: Unprocessable Entity
          content:
            application/json:
              schema:
                type: object
                properties:
                  type:
                    type: string
                  message:
                    type: string
    parameters:
      - name: partner_code
        in: path
        required: true
        schema:
          type: string
      - name: booking_id
        in: path
        required: true
        schema:
          type: string
      - name: update_id
        in: path
        required: true
        schema:
          type: string
  /partners/{partner_code}/bookings/{booking_id}/cancel:
    post:
      summary: Cancel Booking
      description: >-
        Cancel a shipping protection booking. Common logistics cancellation
        reasons include the shipment being cancelled before dispatch, the
        order being returned, or a duplicate booking.


        When `preview` is `true`, returns a refund preview with a
        `cancellation_id`. When `preview` is `false` (or omitted), the
        cancellation is applied immediately.
      tags:
        - Cancel Booking
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                preview:
                  type: boolean
                refund_required:
                  type: boolean
                quotes:
                  type: array
                  items:
                    type: object
                    properties:
                      id:
                        type: string
                      reason_for_cancellation:
                        type: string
                    required:
                      - id
            examples:
              ACMELogisticsDirectCancel:
                $ref: '#/components/examples/ACMELogisticsCancelRequest'
              ACMELogisticsPreviewCancel:
                $ref: '#/components/examples/ACMELogisticsCancelPreviewRequest'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
                properties:
                  id:
                    type: string
                  status:
                    type: string
                  quotes:
                    type: array
                    items:
                      type: object
                      properties:
                        id:
                          type: string
                        policy_start_date:
                          type: string
                          format: date-time
                        policy_end_date:
                          type: string
                          format: date-time
                          nullable: true
                        policy_cancellation_date:
                          type: string
                          format: date-time
                          nullable: true
                        status:
                          type: string
                        price:
                          type: number
                        refund_value:
                          type: number
                        adjustment_fee:
                          type: number
                  policyholder:
                    type: object
                    properties:
                      first_name:
                        type: string
                      last_name:
                        type: string
                      email:
                        type: string
                        format: email
                      country:
                        type: string
                  total_price:
                    type: number
                  total_price_formatted:
                    type: string
                  total_refund:
                    type: number
                  total_refund_formatted:
                    type: string
                  currency:
                    type: string
                  cancellation_id:
                    type: string
                    nullable: true
                  confirm_before:
                    type: string
                    format: date-time
                    nullable: true
                  refund_amount:
                    type: number
                  refund_amount_formatted:
                    type: string
              examples:
                ACMELogisticsDirectCancel:
                  $ref: '#/components/examples/ACMELogisticsCancelResponse'
                ACMELogisticsPreviewCancel:
                  $ref: '#/components/examples/ACMELogisticsCancelPreviewResponse'
        '403':
          description: Forbidden
          content:
            application/json:
              schema:
                type: object
                properties:
                  type:
                    type: string
                  message:
                    type: string
        '404':
          description: Not Found
          content:
            application/json:
              schema:
                type: object
                properties:
                  type:
                    type: string
                  message:
                    type: string
        '422':
          description: Unprocessable Entity
          content:
            application/json:
              schema:
                type: object
                properties:
                  type:
                    type: string
                  message:
                    type: string
                  errors:
                    type: array
                    items:
                      type: string
    parameters:
      - name: partner_code
        in: path
        required: true
        schema:
          type: string
      - name: booking_id
        in: path
        required: true
        schema:
          type: string
  /partners/{partner_code}/bookings/{booking_id}/confirm_cancellation/{cancellation_id}/:
    post:
      summary: Cancel Booking - Confirm
      description: >-
        Finalize a previewed cancellation. Use the `cancellation_id` returned
        from the Cancel Booking preview endpoint.
      tags:
        - Cancel Booking
      requestBody:
        required: false
        content:
          application/json:
            schema:
              type: object
              properties:
                reason_for_cancellation:
                  type: string
            examples:
              ACMELogistics:
                $ref: '#/components/examples/ACMELogisticsCancelConfirmRequest'
      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:
                ACMELogistics:
                  $ref: '#/components/examples/ACMELogisticsCancelConfirmResponse'
        '403':
          description: Forbidden
          content:
            application/json:
              schema:
                type: object
                properties:
                  type:
                    type: string
                  message:
                    type: string
        '404':
          description: Not Found
          content:
            application/json:
              schema:
                type: object
                properties:
                  type:
                    type: string
                  message:
                    type: string
        '422':
          description: Unprocessable Entity
          content:
            application/json:
              schema:
                type: object
                properties:
                  type:
                    type: string
                  message:
                    type: string
                  errors:
                    type: array
                    items:
                      type: string
    parameters:
      - name: partner_code
        in: path
        required: true
        schema:
          type: string
      - name: booking_id
        in: path
        required: true
        schema:
          type: string
      - name: cancellation_id
        in: path
        required: true
        schema:
          type: string
components:
  examples:
    ACMELogisticsOfferRequest:
      summary: ACME Logistics - Create Offer Request
      value:
        schema: acme-logistics-schema-v1
        placement: checkout
        customer:
          currency: USD
          country: US
          region: NY
          language: en
        partner:
          transaction_id: 'acme-{{$randomUUID}}'
          customer_id: ACME-CUST-58291
          metadata:
            merchant_id: ACME-MERCH-2041
            merchant_name: ACME Nutrition
        context:
          order_total: 10997
          shipping_cost: 999
          declared_value: 9998
          lot_url: https://acmenutrition.com/products/whey-isolate-vanilla
          carrier: UPS
          carrier_service_name: UPS Ground
          shipping_date: '2026-05-08T10:00:00+00:00'
          shipping_method: drop off
          frontend_distr: true
          dual_coverage: false
          packages:
            - type: Parcel
              width: 18
              height: 22
              length: 18
              weight: 2.5
              description: Whey Protein Isolate - Vanilla
              declared_value: 4999
              items:
                - sku: ACME-WPI-VAN-5LB
                  hs_code: '2106909998'
                  brand: ACME Nutrition
                  model: ACME Performance Whey Isolate
                  description: ACME Performance Whey Protein Isolate, Vanilla, 5lb tub
                  quantity: 1
                  price: 4999
            - type: Parcel
              width: 18
              height: 22
              length: 18
              weight: 2.5
              description: Whey Protein Isolate - Chocolate
              declared_value: 4999
              items:
                - sku: ACME-WPI-CHO-5LB
                  hs_code: '2106909998'
                  brand: ACME Nutrition
                  model: ACME Performance Whey Isolate
                  description: ACME Performance Whey Protein Isolate, Chocolate, 5lb tub
                  quantity: 1
                  price: 4999
          receiver:
            first_name: Oscar
            last_name: Linares
            address1: 245 East 63rd Street
            address2: Apt 12B
            city: New York
            postcode: '10065'
            region: NY
            country: US
            email: oscar.linares@email.com
          sender:
            first_name: Fulfillment
            last_name: Team
            company_name: ACME Fulfillment
            address1: 7000 Broadway
            address2: Suite 300
            city: Denver
            postcode: '80221'
            region: CO
            country: US
            email: shipping@acmefulfillment.com
            phone: '+1 303 558 1750'
    ACMELogisticsOfferResponse:
      summary: ACME Logistics - Create Offer Response
      value:
        id: 2b1bbc58-c050-42b6-aff3-9b20abbbec59
        offer_config_id: 86f543d2-41c3-4a14-95fb-dda6743832ab
        offer_schema: acme-logistics-schema-v1
        currency: USD
        products:
          - id: 4c783f66-c253-43cf-86d6-3a9096769679
            product_config_id: 0f876b2b-ae0f-41ec-90c7-32a4abb1924f
            name: acme-logistics-product
            type: xcover
            schema_url: https://static.xcover.com/media/product-types/schemas/xcover.json
            details:
              policy_version_id: 5c56f9cb-b851-42a8-ad53-eeb0e78a0a88
              start_date: '2026-05-08T10:00:00+00:00'
              end_date: null
              finance:
                price:
                  total_amount: 164.95
                  total_amount_without_tax: null
                  total_amount_min: null
                  total_amount_max: null
                  total_amount_formatted: US$164.95
                  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/2b1bbc58-c050-42b6-aff3-9b20abbbec59?policy_type=parcel_insurance_v1
              files:
                - name: IPID_ParcelProtection_EN
                  url: https://static.xcover.com/media/pds/a92490cd-5645-4e81-9102-629f9eff0395/IPID_ParcelProtection_EN.pdf
                  type: IPID
              extra_fields:
                shipping_type: domestic
                address_computed: 245 East 63rd Street Apt 12B New York NY 10065 US
                policy_end_date: null
                policy_duration: 20
                partner_subsidiary: null
              experiment: {}
              benefits: []
        content:
          schema_version: content:1.0
          locale: en
        errors: {}
    ACMELogisticsConfirmRequest:
      summary: ACME Logistics - Confirm Offer Request
      value:
        quotes:
          - id: 4c783f66-c253-43cf-86d6-3a9096769679
        policyholder:
          first_name: Oscar
          last_name: Linares
          email: oscar.linares@email.com
          address1: 245 East 63rd Street
          address2: Apt 12B
          city: New York
          postcode: '10065'
          region: NY
          country: US
    ACMELogisticsConfirmResponse:
      summary: ACME Logistics - Confirm Offer Response
      value:
        id: L9KQM-2NX4P-INS
        status: CONFIRMED
        currency: USD
        total_price: 164.95
        total_price_formatted: US$164.95
        partner_transaction_id: null
        created_at: '2026-05-08T10:05:00.000000Z'
        updated_at: '2026-05-08T10:05:00.150000Z'
        pds_url: https://www.xcover.com/en/pds/L9KQM-2NX4P-INS
        security_token: 7tKwX-PqLra-bcDjK-92ML4
        quotes:
          - id: 4c783f66-c253-43cf-86d6-3a9096769679
            policy_start_date: '2026-05-08T10:00:00+00:00'
            policy_end_date: null
            status: CONFIRMED
            price: 164.95
            price_formatted: US$164.95
            policy:
              policy_type: parcel_insurance
              policy_type_version: '1'
              policy_type_slug: parcel_insurance_v1
              policy_type_group_name: logistics
              policy_name: ACME Logistics Parcel Protection
              policy_code: ALPP0001
              policy_version: 5c56f9cb-b851-42a8-ad53-eeb0e78a0a88
              category: parcel_insurance
              policy_currency: USD
            tax:
              total_tax: 0
              total_amount_without_tax: 164.95
              total_tax_formatted: US$0.00
              total_amount_without_tax_formatted: US$164.95
            benefits: []
            commission:
              partner_commission: 0
              total_commission: 0
              partner_commission_formatted: US$0.00
              total_commission_formatted: US$0.00
            created_at: '2026-05-08T10:05:00.000000Z'
            confirmed_at: '2026-05-08T10:05:00.150000Z'
            pds_url: https://www.xcover.com/en/pds/L9KQM-2NX4P-INS?policy_type=parcel_insurance_v1&quote_id=4c783f66-c253-43cf-86d6-3a9096769679
            can_be_cancelled: true
        coi:
          url: https://www.xcover.com/en/coi/L9KQM-2NX4P-INS?security_token=7tKwX-PqLra-bcDjK-92ML4
          pdf: https://www.xcover.com/en/coi/L9KQM-2NX4P-INS.pdf?security_token=7tKwX-PqLra-bcDjK-92ML4
        policyholder:
          first_name: Oscar
          last_name: Linares
          email: oscar.linares@email.com
          country: US
        total_tax: 0
        total_tax_formatted: US$0.00
        total_premium: 164.95
        total_premium_formatted: US$164.95
        fnol_link: https://www.xcover.com/en/account/claims/fnol?bookingID=L9KQM-2NX4P-INS&security_token=7tKwX-PqLra-bcDjK-92ML4
    ACMELogisticsModifyRequest:
      summary: ACME Logistics - Modify Booking Request
      value:
        quotes:
          - id: 4c783f66-c253-43cf-86d6-3a9096769679
            update_fields:
              shipping_date: '2026-05-12T10:00:00+00:00'
    ACMELogisticsModifyResponse:
      summary: ACME Logistics - Modify Booking Response
      value:
        id: L9KQM-2NX4P-INS
        status: CONFIRMED
        currency: USD
        total_price: 164.95
        total_price_formatted: US$164.95
        quotes:
          - id: 4c783f66-c253-43cf-86d6-3a9096769679
            status: CONFIRMED
            price: 164.95
            price_formatted: US$164.95
            price_diff: 0
            price_diff_formatted: US$0.00
        total_price_diff: 0
        total_price_diff_formatted: US$0.00
    ACMELogisticsModifyPreviewResponse:
      summary: ACME Logistics - Modify Booking Preview Response
      value:
        id: L9KQM-2NX4P-INS
        status: CONFIRMED
        currency: USD
        total_price: 164.95
        total_price_formatted: US$164.95
        quotes:
          - id: 4c783f66-c253-43cf-86d6-3a9096769679
            status: CONFIRMED
            price: 164.95
            price_formatted: US$164.95
            price_diff: 0
            price_diff_formatted: US$0.00
        total_price_diff: 0
        total_price_diff_formatted: US$0.00
        update_id: KrXp9-MnVcQ-h2YO8
    ACMELogisticsModifyConfirmResponse:
      summary: ACME Logistics - Modify Booking Confirm Response
      value:
        id: L9KQM-2NX4P-INS
        status: CONFIRMED
        currency: USD
        total_price: 164.95
        total_price_formatted: US$164.95
        quotes:
          - id: 4c783f66-c253-43cf-86d6-3a9096769679
            status: CONFIRMED
            price: 164.95
            price_formatted: US$164.95
            price_diff: 0
            price_diff_formatted: US$0.00
        total_price_diff: 0
        total_price_diff_formatted: US$0.00
    ACMELogisticsCancelRequest:
      summary: ACME Logistics - Cancel Booking Request (Direct)
      value:
        preview: false
        refund_required: true
    ACMELogisticsCancelResponse:
      summary: ACME Logistics - Cancel Booking Response (Direct)
      value:
        id: L9KQM-2NX4P-INS
        status: CANCELLED
        quotes:
          - id: 4c783f66-c253-43cf-86d6-3a9096769679
            policy_start_date: '2026-05-08T10:00:00+00:00'
            policy_end_date: null
            policy_cancellation_date: '2026-05-09T09:00:00.000000Z'
            status: CANCELLED
            price: 164.95
            refund_value: 164.95
            adjustment_fee: 0
        policyholder:
          first_name: Oscar
          last_name: Linares
          email: oscar.linares@email.com
          country: US
        total_price: 0
        total_price_formatted: US$0.00
        total_refund: 164.95
        total_refund_formatted: US$164.95
        currency: USD
        cancellation_id: null
        confirm_before: null
        refund_amount: 164.95
        refund_amount_formatted: US$164.95
    ACMELogisticsCancelPreviewRequest:
      summary: ACME Logistics - Cancel Booking Request (Preview)
      value:
        preview: true
        refund_required: true
        quotes:
          - id: 4c783f66-c253-43cf-86d6-3a9096769679
            reason_for_cancellation: shipment cancelled before dispatch
    ACMELogisticsCancelPreviewResponse:
      summary: ACME Logistics - Cancel Booking Response (Preview)
      value:
        id: L9KQM-2NX4P-INS
        status: CANCELLED
        quotes:
          - id: 4c783f66-c253-43cf-86d6-3a9096769679
            policy_start_date: '2026-05-08T10:00:00+00:00'
            policy_end_date: null
            policy_cancellation_date: null
            status: CANCELLED
            price: 164.95
            refund_value: 164.95
            adjustment_fee: 0
        policyholder:
          first_name: Oscar
          last_name: Linares
          email: oscar.linares@email.com
          country: US
        total_price: 0
        total_price_formatted: US$0.00
        total_refund: 164.95
        total_refund_formatted: US$164.95
        currency: USD
        cancellation_id: mPq7r-31DZ5-ZZx4J-CCL
        confirm_before: '2026-05-10T09:00:00.000000Z'
        refund_amount: 164.95
        refund_amount_formatted: US$164.95
    ACMELogisticsCancelConfirmRequest:
      summary: ACME Logistics - Cancel Booking Confirm Request
      value:
        reason_for_cancellation: shipment cancelled before dispatch
    ACMELogisticsCancelConfirmResponse:
      summary: ACME Logistics - Cancel Booking Confirm Response
      value:
        id: L9KQM-2NX4P-INS
        status: CANCELLED
        quotes:
          - id: 4c783f66-c253-43cf-86d6-3a9096769679
            status: CANCELLED
            price: 164.95
            refund_value: 164.95
            cancelled_at: '2026-05-09T09:05:00.000000Z'
        total_refund: 164.95
        total_refund_formatted: US$164.95
        refund_amount: 164.95
        refund_amount_formatted: US$164.95
  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.


        ### 2. Date (Timestamp)

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

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


        ### 3. Authorization (Computed Signature)

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

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


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