Create Offer

post

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.

Authorizations

AuthorizationstringRequired

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.

Path parameters

partner_codestringRequired

Partner code identifier. Client Solutions Engineer (CSE) should provide this value.

Query parameters

active_onlybooleanOptional

When using a test API key, only return active offers

Default: false

include_contentbooleanOptional

Include localized content in the response

Default: true

extra_fieldsstringOptional

Comma-separated list of specific extra fields to include. Available fields: tax, commission, benefits, surcharge

exclude_offer_idsstringOptional

Comma-separated list of Offer Config IDs to exclude from the response

Body

schemastringRequired

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

placementstringOptional

Where the offer is being displayed in the partner flow (e.g., checkout, cart, post-purchase).

Responses

200

application/json

idstringOptional

Offer ID

offer_config_idstringOptional

offer_schemastringOptional

currencystringOptional

403

Forbidden

application/json

422

Unprocessable Entity

application/json

post/partners/{partner_code}/offers/

POST /x/partners/{partner_code}/offers/ HTTP/1.1
Host: api.xcover.com
Authorization: YOUR_API_KEY
Content-Type: application/json
Accept: */*
Content-Length: 1822

{
  "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": "[email protected]"
    },
    "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": "[email protected]",
      "phone": "+1 303 558 1750"
    }
  }
}

{
  "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": {}
}

PreviousParcel / Shipping NextConfirm Offer

Last updated 2 months ago

Was this helpful?