# Offers

Offer webhooks notify your application about changes to product offers, including creation, updates, availability changes, and removal. These events are crucial for maintaining an accurate and up-to-date product catalog.

## Overview

Offer webhooks track individual product-level changes in real-time. While sync events (`PRODUCT_SYNC_STARTED`, `PRODUCT_SYNC_COMPLETED`) signal catalog-wide operations, offer webhooks fire for specific products as they're added, modified, or removed.

Learn more about offers in the [Offers documentation](https://docs.violet.io/prism/catalog/offers) and [Catalog overview](https://docs.violet.io/prism/catalog).

## Understanding Offer Status

Offers can have several status values that affect availability:

* **AVAILABLE** - Active and can be purchased
* **UNAVAILABLE** - Exists but not available for purchase (out of stock, draft, etc.)
* **DISABLED\_AVAILABLE** - Temporarily disabled (merchant disabled) but was available
* **DISABLED\_UNAVAILABLE** - Temporarily disabled and was unavailable
* **ARCHIVED** - Deleted by merchant but kept temporarily (allows restoration)

Offer webhooks fire when offers transition between these states or when offer data changes.

## Available Events

### OFFER\_CREATED

**Status:** This event is deprecated and no longer actively used.

**Migration:** Use `OFFER_ADDED` instead, which provides more comprehensive coverage of when offers become available.

**Note:** While `OFFER_CREATED` still exists in the system for backward compatibility, new integrations should use `OFFER_ADDED` exclusively. The event remains defined in the backend but is not emitted for new offers.

### OFFER\_ADDED

**Trigger:** Whenever an offer becomes available for purchase. This includes:

* Newly created offers that are immediately published
* Existing offers that are updated to a "published" status
* Pre-existing offers that become available when a merchant and channel first connect

**Use Case:** Subscribe to this event to:

* Add new products to your catalog
* Update product listings
* Index offers in search systems
* Trigger catalog refresh
* Notify users of new inventory

**Coverage:** This event provides the most comprehensive availability information and should be your primary event for tracking new offers.

### OFFER\_UPDATED

**Trigger:** When an update is made to an offer.

**Use Case:** Monitor this event to:

* Sync product information changes
* Update prices
* Refresh product descriptions
* Update inventory quantities
* Modify product attributes
* Adjust product images or media

**Note:** This event fires for any change to offer data, including:

* Price changes
* Inventory updates
* Description modifications
* Image updates
* SKU changes
* Variant modifications

### OFFER\_REMOVED

**Trigger:** When an offer is no longer available for purchase (single offer removal).

**Use Case:** Subscribe to this event to:

* Remove products from active listings
* Hide out-of-stock items
* Archive discontinued products
* Update search indexes
* Clean up catalog data

**Note:** This event indicates the offer is no longer available but may not be permanently deleted. The merchant may republish it later.

**Distinction:** This event fires for individual offer removals. For bulk deletions, see `OFFER_DELETED`.

### OFFER\_DELETED

**Trigger:** When offers are bulk deleted from the system.

**Use Case:** Subscribe to this event to:

* Handle bulk product removals efficiently
* Clean up multiple products at once
* Update search indexes in batch
* Archive multiple products
* Optimize catalog cleanup operations

**When This Occurs:**

* Bulk delete operations triggered via API
* Multiple offers removed simultaneously
* Merchant performs mass product deletion

**Important:** This event fires for each individual offer within a bulk delete operation. If 100 offers are deleted in a single bulk operation, you'll receive 100 `OFFER_DELETED` events.

**Distinction:** `OFFER_DELETED` is used specifically for bulk delete operations, while `OFFER_REMOVED` is used for single offer removals or when an offer becomes unavailable. Both events serve similar purposes but indicate different deletion contexts.

## Related Documentation

* [Offers](https://docs.violet.io/prism/catalog/offers) - Learn about the Offer data model
* [Catalog](https://docs.violet.io/prism/catalog) - Understand Violet's catalog system
* [Handling Webhooks](https://docs.violet.io/prism/webhooks/handling-webhooks) - Process offer webhook events properly
* [Simulating Webhook Events](https://docs.violet.io/prism/webhooks/simulating-webhook-events) - Test offer webhooks

## Best Practices

1. **Use OFFER\_ADDED over OFFER\_CREATED** - Since `OFFER_CREATED` is deprecated, always use `OFFER_ADDED` to track new offers becoming available.
2. **Handle rapid updates** - Products may receive multiple `OFFER_UPDATED` events in quick succession. Implement debouncing or queuing to avoid unnecessary processing.
3. **Verify availability before display** - When receiving `OFFER_ADDED` events, verify the offer's availability and inventory before displaying it to shoppers.
4. **Process OFFER\_REMOVED and OFFER\_DELETED promptly** - Remove or hide offers quickly when receiving removal events to avoid showing unavailable products to customers.
5. **Optimize bulk deletions** - When receiving multiple `OFFER_DELETED` events in quick succession, consider batching the cleanup operations for better performance rather than processing each individually.
6. **Sync incrementally** - Use offer webhooks for incremental catalog updates instead of full catalog refreshes to improve performance.
7. **Track offer lifecycle** - Monitor both `OFFER_ADDED` and `OFFER_REMOVED`/`OFFER_DELETED` events for each offer to maintain accurate availability status.
8. **Handle republishing** - An offer that was previously removed may be added again. Ensure your system can handle this scenario gracefully.
9. **Distinguish removal contexts** - While both `OFFER_REMOVED` and `OFFER_DELETED` result in offer removal, understanding the context (single vs. bulk) can help optimize your processing logic.

## Webhook Headers

Offer webhooks include the [default webhook headers](https://docs.violet.io/prism/webhooks/managing-webhook-headers), which contain:

* `X-Violet-Entity-Id` - The Violet Offer ID
* `X-Violet-Topic` - The event type (OFFER\_ADDED, OFFER\_UPDATED, etc.)
* `X-Violet-Event-Id` - Unique event identifier for idempotency

## Common Integration Patterns

### Real-time Catalog Updates

```
OFFER_ADDED → Add to catalog → Index in search
OFFER_UPDATED → Fetch latest data → Update catalog
OFFER_REMOVED → Mark unavailable → Remove from search
```

### Inventory Management

```
OFFER_UPDATED → Check inventory field → Update availability
OFFER_REMOVED → Mark out of stock → Notify interested customers
```

### Price Monitoring

```
OFFER_UPDATED → Compare price delta → Trigger price alerts
OFFER_UPDATED → Log price history → Update analytics
```

## Coordinating with Other Events

Offer events often occur alongside sync and merchant events:

### Initial Product Sync (Merchant Onboarding)

```
MERCHANT_CONNECTED → Merchant onboarded
PRODUCT_SYNC_STARTED → Catalog sync begins
OFFER_ADDED (for each product) → Products being added to catalog
PRODUCT_SYNC_COMPLETED → All offers synced
```

### Scheduled Product Sync

```
PRODUCT_SYNC_STARTED → Daily sync begins
OFFER_UPDATED (for changed products) → Modified products detected
OFFER_ADDED (for new products) → New products detected
OFFER_REMOVED (for deleted products) → Removed products detected
PRODUCT_SYNC_COMPLETED → Sync finished
```

### Merchant Disablement

```
MERCHANT_DISABLED → Merchant becomes inactive
OFFER_UPDATED (all merchant offers) → All offers marked DISABLED_AVAILABLE
Catalog operations paused → No new offer changes until re-enabled
```

### Merchant Re-enablement

```
MERCHANT_ENABLED → Merchant reactivated
PRODUCT_SYNC_STARTED → Re-sync triggered
OFFER_UPDATED (all merchant offers) → Offers re-enabled (back to AVAILABLE)
PRODUCT_SYNC_COMPLETED → Catalog current
```

### Individual Product Changes

```
Merchant updates product in platform → Change detected by sync or webhook
OFFER_UPDATED → Specific product updated
(No sync events for individual changes between scheduled syncs)
```

Monitor offer events alongside sync and merchant events to distinguish between bulk operations (syncs) and individual product changes.