# Create Offer

## Create Offer

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

```json
{"openapi":"3.0.0","info":{"title":"Offers API","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* **Example:** `X-Api-Key: a1b2c3d4e5f6g7h8`\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* **Example:** `Date: Sun, 09 Nov 2025 04:04:00 GMT`\n\n### 3. Authorization (Computed Signature)\n* **Purpose:** The cryptographic signature that verifies the request's authenticity and integrity.\n* **Format:** `SIGNATURE [authHeader]`\n\n**Signature Generation Logic:**\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 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}},{"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."},"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","description":"Customer's email address"},"ip":{"type":"string","description":"Customer's IP address"},"postcode":{"type":"string","description":"Customer's postal code"}},"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"},"sales_channel":{"type":"string","description":"Sales channel (e.g., online, in-store)"},"device":{"type":"string","description":"Device type (e.g., desktop, mobile, tablet)"}},"additionalProperties":true}}},"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"},"estimated_shipping_date":{"type":"string","format":"date-time","description":"Estimated shipping date of the product"},"estimated_delivery_date":{"type":"string","format":"date-time","description":"Estimated delivery date of the product"},"product":{"type":"object","description":"Product being protected","properties":{"sku":{"type":"string","description":"Product SKU"},"brand":{"type":"string","description":"Product brand"},"model":{"type":"string","description":"Product model"},"title":{"type":"string","description":"Product title"},"variant":{"type":"string","description":"Product variant identifier (e.g., warranty term such as 2y)"},"category":{"type":"string","description":"Product category name"},"category_id":{"type":"string","description":"Product category identifier"},"quantity":{"type":"integer","description":"Quantity purchased"},"condition":{"type":"string","description":"Product condition (e.g., new, refurbished, used)"},"description":{"type":"string","description":"Product description"},"retail_value":{"type":"number","description":"Retail price of the product"},"wholesale_value":{"type":"number","description":"Wholesale price of the product"},"term":{"type":"string","description":"Coverage term for the product (e.g., 2y)"}},"required":["sku","title","quantity","retail_value"]},"warranty":{"type":"object","description":"Warranty details for the product","properties":{"manufacturer_duration":{"type":"string","description":"Duration of the manufacturer warranty (e.g., 1y)"},"term":{"type":"string","description":"Extended warranty term (e.g., 2y)"},"benefit":{"type":"string","description":"Benefit type (e.g., accidental damage and extended warranty)"}}}},"additionalProperties":true}},"required":["schema","customer","context"]}}}},"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"}},"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"},"offer_config_id":{"type":"string","description":"Offer configuration identifier"},"offer_schema":{"type":"string","description":"Schema identifier for the offer"},"currency":{"type":"string","description":"Currency code for the offer pricing"},"products":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","description":"Product (quote) ID"},"product_config_id":{"type":"string","description":"Product configuration identifier"},"name":{"type":"string","description":"Product name"},"type":{"type":"string","nullable":true,"description":"Product type"},"schema_url":{"type":"string","nullable":true,"format":"uri","description":"URL to the product schema definition"},"details":{"type":"object","properties":{"policy_version_id":{"type":"string","description":"Policy version identifier"},"start_date":{"type":"string","format":"date-time","description":"Coverage start date"},"end_date":{"type":"string","format":"date-time","description":"Coverage end date"},"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"},"files":{"type":"array","description":"Associated documents (e.g., IPID)","items":{"type":"object","properties":{"name":{"type":"string","description":"File name"},"url":{"type":"string","format":"uri","description":"File URL"},"type":{"type":"string","description":"File type (e.g., IPID, OTHER)"}}}},"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}},"appliance":{"type":"string","description":"Appliance classification (e.g., appliance, non-appliance)"},"retail_ex_tax":{"type":"number","nullable":true,"description":"Retail price excluding tax"},"retail_inc_tax":{"type":"number","nullable":true,"description":"Retail price including tax"},"retail_ex_tax_rounded":{"type":"number","nullable":true,"description":"Retail price excluding tax (rounded)"},"retail_inc_tax_rounded":{"type":"number","nullable":true,"description":"Retail price including tax (rounded)"},"taxes":{"type":"object","description":"Tax breakdown","additionalProperties":true},"tax_rate":{"type":"number","nullable":true,"description":"Applied tax rate"},"benefit_type":{"type":"string","description":"Benefit type for this product"},"partner_commission":{"type":"number","nullable":true,"description":"Partner commission amount"},"variant":{"type":"string","description":"Variant identifier (e.g., 2y)"}},"additionalProperties":true},"experiment":{"type":"object","description":"Experiment metadata (if applicable)","additionalProperties":true},"benefits":{"type":"array","description":"Coverage benefits associated with the product","items":{"type":"object","additionalProperties":true}}}}}}},"content":{"type":"object","properties":{"schema_version":{"type":"string","description":"Content schema version"},"locale":{"type":"string","description":"Content locale (e.g., en, en-US)"},"slug":{"type":"string","description":"Content slug identifier for the offer"},"title":{"type":"string","description":"Main title for the offer"},"extras":{"type":"object","description":"Additional content fields specific to the offer","additionalProperties":true},"heading":{"type":"string","description":"Heading text"},"sub_heading":{"type":"string","description":"Sub-heading text"},"disclaimer":{"type":"string","description":"Legal disclaimer text"},"disclaimer_html":{"type":"string","description":"HTML formatted disclaimer"},"price_unit":{"type":"string","description":"Price unit descriptor (e.g., per person)"},"description":{"type":"string","description":"Offer description"},"positive_cta":{"type":"string","description":"Text for accept/yes button"},"negative_cta":{"type":"string","description":"Text for decline/no button"},"negative_cta_warning":{"type":"string","description":"Warning shown when user declines"},"required_message":{"type":"string","description":"Message shown when selection is required"},"credibility_message":{"type":"string","description":"Trust/credibility message (deprecated, use credibility)"}}},"errors":{"type":"object","description":"Any errors encountered during offer creation","additionalProperties":true}}}}}},"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}},"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"}}}}}},"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}},"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"}}}}}}}}}}}}}}
```


---

# 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/product-retail/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.