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 and Catalog overview.

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 - Learn about the Offer data model

• Catalog - Understand Violet's catalog system

• Handling Webhooks - Process offer webhook events properly

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