# Offers

### What is an Offer?

An **Offer** represents a merchant's specific listing of a product in Violet's catalog. It contains the merchant's pricing, availability, descriptions, media, and purchasable variations ([SKUs](https://docs.violet.io/api-reference/catalog/skus)). When browsing products from a merchant, you're viewing their Offers.

### Data Model Hierarchy

```
Merchant
   └── Offer (merchant's product listing)
         └── SKU (specific purchasable variant)
```

* **Merchant**: The seller providing products
* **Offer**: A merchant's listing with their pricing, descriptions, and media
* **SKU**: Individual purchasable variants within the Offer (e.g., size/color combinations)

A single Merchant can have many Offers, and each Offer can contain multiple SKUs.

### Key Offer Properties

| Property           | Type    | Description                                          |
| ------------------ | ------- | ---------------------------------------------------- |
| `id`               | integer | Violet's unique Offer identifier                     |
| `external_id`      | string  | The merchant's own product identifier                |
| `merchant_id`      | integer | The merchant selling this Offer                      |
| `name`             | string  | Product name                                         |
| `description`      | string  | Plain text description                               |
| `html_description` | string  | HTML-formatted description                           |
| `min_price`        | integer | Lowest SKU price in minor units (cents)              |
| `max_price`        | integer | Highest SKU price in minor units                     |
| `currency`         | string  | ISO 4217 currency code                               |
| `available`        | boolean | Whether any SKUs are in stock                        |
| `visible`          | boolean | Whether the Offer is visible to customers            |
| `source`           | enum    | Origin platform (e.g., `SHOPIFY`, `AMAZON`, `OTHER`) |
| `seller`           | string  | Seller name                                          |
| `vendor`           | string  | Product vendor/brand                                 |
| `external_url`     | string  | Link to the product on the merchant's site           |

### Offer Status

Offers have two independent status dimensions that control their lifecycle:

#### Status

The operational state of the Offer:

| Status         | Description                                |
| -------------- | ------------------------------------------ |
| `AVAILABLE`    | Active and operational                     |
| `DISABLED`     | Temporarily disabled by merchant or system |
| `ARCHIVED`     | Removed from active catalog                |
| `FOR_DELETION` | Marked for permanent deletion              |

#### Publishing Status

Controls visibility to apps and webhook delivery:

| Status          | Description                                   |
| --------------- | --------------------------------------------- |
| `PUBLISHED`     | Visible to subscribed apps, triggers webhooks |
| `NOT_PUBLISHED` | Hidden from apps, no webhook notifications    |

An Offer must be both `available=true` AND `publishing_status=PUBLISHED` to appear in app catalogs.

### Variants and SKUs

Offers support product variants through two related concepts:

#### Variants

Define the available options for a product:

```json
{
  "variants": [
    { "name": "Size", "values": ["Small", "Medium", "Large"] },
    { "name": "Color", "values": ["Red", "Blue", "Green"] }
  ]
}
```

#### SKUs

Represent specific purchasable combinations of variants, each with its own inventory and pricing:

```json
{
  "skus": [
    {
      "id": 12345,
      "name": "T-Shirt - Small - Red",
      "sale_price": 2500,
      "in_stock": true,
      "variant_values": [
        { "name": "Size", "value": "Small" },
        { "name": "Color", "value": "Red" }
      ]
    }
  ]
}
```

### Media and Albums

Offers include media organized into albums:

* **Albums**: Collections of images and videos for the Offer
* **Primary Image**: The main product image displayed in listings
* **SKU-level Media**: Individual SKUs can have their own images

### Pricing

* Prices are stored in **minor units** (cents for USD)
* `min_price` and `max_price` represent the price range across all SKUs
* Individual SKU prices are available on each SKU object
* Currency conversion is available by passing your desired currency

### Common Use Cases

#### Retrieving an Offer

Use `GET /catalog/offers/{offer_id}` to fetch complete Offer details including SKUs, variants, and media.

#### Listing Merchant Offers

Use `GET /catalog/offers/merchants/{merchant_id}` to retrieve paginated Offers from a specific merchant.

#### Searching Offers

Use `POST /catalog/offers/search` to search across Offers with filters for price, availability, category, and more.

{% hint style="warning" %}
Offer Search returns eventually consistent data and is not real-time consistent. Use Offer Search for discovery, then use non-search Offer endpoints for real-time Offer data.
{% endhint %}

### Webhooks

When Offers change, webhooks notify subscribed apps:

| Event           | Trigger                      |
| --------------- | ---------------------------- |
| `OFFER_ADDED`   | Offer becomes published      |
| `OFFER_UPDATED` | Published Offer is modified  |
| `OFFER_REMOVED` | Offer is unpublished         |
| `OFFER_DELETED` | Offer is permanently deleted |

Webhooks only fire for Offers with `publishing_status=PUBLISHED`.

### Relationship to Orders

When customers add items to a cart, they're adding specific SKUs from an Offer. The Offer provides the product context (name, description, media) while the SKU determines the exact variant, price, and inventory.

Changes to Offer availability or SKU inventory are automatically communicated to active carts and orders containing those items.

***

**Available endpoints:**

```
 GET /v1/catalog/offers/merchants/{merchant_id}
 GET /v1/catalog/offers/merchants/{merchant_id}/count
 GET /v1/catalog/offers/{offer_id}
POST /v1/catalog/offers/search
```