# 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](/prism/catalog/offers.md) and [Catalog overview](/prism/catalog.md). ## 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](/prism/catalog/offers.md) - Learn about the Offer data model * [Catalog](/prism/catalog.md) - Understand Violet's catalog system * [Handling Webhooks](/prism/webhooks/handling-webhooks.md) - Process offer webhook events properly * [Simulating Webhook Events](/prism/webhooks/simulating-webhook-events.md) - 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](/prism/webhooks/managing-webhook-headers.md), 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. --- # 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://docs.violet.io/prism/webhooks/events/offer-webhooks.md?ask= ``` 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.