# Create Offer

## Create Offer

> 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.

```json
{"openapi":"3.0.0","info":{"title":"Offers API - Logistics","version":"1.0.0"},"servers":[{"url":"https://api.xcover.com/x"}],"security":[{"CustomAPISignature":[]}],"components":{"securitySchemes":{"CustomAPISignature":{"type":"apiKey","name":"Authorization","in":"header","description":"**Composite Authentication Scheme (Client Key, Date, and Signature)**\n\nThis scheme requires the client to provide **three** mandatory headers in every request:\n\n### 1. X-Api-Key (Client Key)\n* **Purpose:** Public identifier for the API consumer.\n\n### 2. Date (Timestamp)\n* **Purpose:** Timestamp used for generating the signature and preventing replay attacks.\n* **Format:** RFC 7231 format (e.g., in GMT).\n\n### 3. Authorization (Computed Signature)\n* **Purpose:** Cryptographic signature that verifies the request's authenticity and integrity.\n* **Format:** `SIGNATURE [authHeader]`\n\nThe `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**.\n"}}},"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."},"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"]}}}},"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}}}}}},"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"}}}}}}}}}}}}}}
```


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://partner-docs.covergenius.com/offers/vertical-examples/parcel-shipping/create-offer.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.