# Create Offer

The Create Offer endpoint generates personalized product offerings based on partner business context and customer information. This endpoint uses a schema-driven approach to validate requests and returns one or more products with detailed pricing, policy information, and content for display to customers.

> For the full request/response schema, query parameters, and field definitions, see the [Create Offer API Specification](/offers/api/reference.md).

### What You Get in the Response

The response from the Create Offer endpoint includes:

* **Offer ID** - Unique identifier (UUID) for the offer that can be used to confirm the purchase or opt out
* **Offer Config ID** - The Offer configuration used to generate this Offer. Can be used in subsequent requests to exclude previously shown offers
* **Currency** - The currency code for all pricing
* **Products** - List of available products with their configurations. For each product:
  * Quote ID - Used for booking confirmation via the Confirm Offer endpoint
  * Product Type (e.g., `xcover-product`)
  * Finance Information - Price breakdown including total, tax, surcharge, and commission (each with formatted display values)
  * Policy Dates (start and end dates)
  * Policy Disclosure Statement (PDS) URL
  * Attached Files (documents related to the product)
  * Extra Fields and Experiment data (when requested)
  * Benefits from the pricing engine
* **Product Rules** - Selection rules controlling how products behave in the UI (visibility, required/optional, interactions between products). Only present when rules are configured for the offer.
* **Content** - Localized display content including:
  * Offer-level: title, description, terms URL
  * Per-product: title, description, benefits, inclusions, exclusions, extras, disclaimers
* **Metadata** - Additional response metadata such as experiment data. Only present when applicable.
* **Errors** - Empty on success

### Making a Create Offers Request

The request structure is defined by your partner's Offer Schema, which validates all incoming data using JSON Schema Draft 7. Every request typically includes:

* **schema** - Schema identifier for the Offer type. If omitted, the default schema for the partner will be used. If the partner does not have a default schema, omitting this field will return a validation error.
* **customer** - Customer information (language, currency, country, and optional fields like email, IP address, region, postcode)
* **context** - Business context data required for offer selection and pricing (product-specific fields defined by your schema)
* **partner** (optional) - Partner-specific information such as subsidiary, transaction ID, customer ID, and metadata

> For the complete field definitions, required vs. optional fields, and query parameters, see the [Create Offer API Specification](/offers/api/reference.md).

### Response Status Codes

<table><thead><tr><th width="241.5">Status</th><th>Description</th></tr></thead><tbody><tr><td><strong>200 OK</strong></td><td>Offer successfully created with available products</td></tr><tr><td><strong>400 Bad Request</strong></td><td>Malformed or unparseable request body</td></tr><tr><td><strong>401 Unauthorized</strong></td><td>Missing or invalid API key</td></tr><tr><td><strong>403 Forbidden</strong></td><td>Access denied</td></tr><tr><td><strong>404 Not Found</strong></td><td>Partner not found, no offers exist, no offers match the request context, or no offers pass access control</td></tr><tr><td><strong>422 Unprocessable Entity</strong></td><td>Request validation failed, all quotes failed to generate, or expression evaluation errors</td></tr><tr><td><strong>429 Too Many Requests</strong></td><td>Rate limit exceeded</td></tr><tr><td><strong>500 Internal Server Error</strong></td><td>Unexpected server error</td></tr></tbody></table>

### Important Notes

* The `id` field in each product is the quote ID that must be used when confirming the offer via the Confirm Offer endpoint.
* **Performance Tip:** For optimal performance and dynamic pricing, always request fresh offers rather than caching offer responses. Server-side configuration is cached for 5 minutes, so very recent config changes may not be reflected immediately.
* **Schema Validation:** All requests are validated against your partner's Offer Schema. Contact your integration team to understand your specific schema requirements.
* **Exclude Offers:** Use the `exclude_offer_ids` query parameter to request a different offer later in a customer journey by excluding a previously shown offer using the `offer_config_id` returned in the response.

### Next Steps

After receiving an Offer response:

1. Display the product information and pricing to your customer
2. Present the content (benefits, inclusions, exclusions, disclaimers)
3. When the customer decides to purchase, use the **Confirm Offer** endpoint with:
   * The offer `id` from the response
   * The quote `id` (from each product) of the selected product(s)
   * Policyholder details (first name, last name, country)
4. If the customer declines, use the **Opt-Out** endpoint with the offer `id` for conversion tracking


---

# 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/guides/purchase-workflow-overview/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.