Collections

Collection webhooks notify your application about changes to product collections, including creation, updates, removal, and modifications to the offers within collections.

What are Collections?

Collections are curated groups of offers (products) that merchants create to organize their inventory and enhance the shopping experience. Learn more in the Collections documentation.

Important Distinction:

• Collections: Merchant-curated groups of products (e.g., "Summer Sale", "Best Sellers"). Can be manually curated (CUSTOM) or rule-based (AUTOMATED)

• Categories: Product taxonomy classifications based on Google Product Taxonomy (e.g., "Shirts", "Jackets")

• Tags: Product-level metadata for filtering and organization

Note: Collection syncing is not enabled by default and must be enabled per merchant. Currently only supported on Shopify. See Collections documentation for details.

Available Events

COLLECTION_CREATED

Trigger: When a new collection is created.

Use Case: Subscribe to this event to:

• Add new collections to your catalog structure

• Create collection landing pages

• Organize navigation menus

• Build collection hierarchies

• Initialize collection-specific settings

Note: When a collection is first created, it may not yet contain any offers. Use COLLECTION_OFFERS_UPDATED to track when offers are added.

COLLECTION_UPDATED

Trigger: When an update is made to a collection.

Use Case: Monitor this event to:

• Update collection metadata

• Refresh collection names and descriptions

• Update collection images

• Modify collection attributes

• Sync collection changes to your systems

Examples of Updates:

• Collection name changes

• Description modifications

• Image updates

• Metadata changes

• Status changes (active/inactive)

Note: This event fires for changes to collection properties but not for changes to the offers within the collection. For offer changes, use COLLECTION_OFFERS_UPDATED.

COLLECTION_REMOVED

Trigger: When a collection is no longer available.

Use Case: Subscribe to this event to:

• Remove collection pages

• Clean up navigation menus

• Archive collection data

• Update search indexes

• Reorganize product displays

Note: When a collection is removed, the individual offers within it are not automatically removed—they may still be available through other collections or as standalone offers.

COLLECTION_OFFERS_UPDATED

Trigger: When offers in a collection are added or removed.

Use Case: Monitor this event to:

• Update collection product listings

• Refresh collection pages

• Recalculate collection metrics (item count, price ranges)

• Update collection search indexes

• Trigger collection-specific promotions

Important: This is a critical event for maintaining accurate collection content. It fires when:

• Offers are added to the collection

• Offers are removed from the collection

• The composition of the collection changes

Payload Details: The webhook payload includes information about which offers were added or removed from the collection.

Related Documentation

• Collections - Learn about the Collection data model

• Catalog - Understand Violet's catalog system

• Offers - Learn how offers relate to collections

• Handling Webhooks - Process collection webhook events properly

Best Practices

1. Separate collection metadata from offers - Use COLLECTION_UPDATED for collection properties and COLLECTION_OFFERS_UPDATED for collection contents. Don't confuse the two.

2. Handle large collections efficiently - Collections may contain hundreds or thousands of offers. Implement pagination when fetching collection details after receiving a webhook.

3. Track offer-collection relationships - Maintain a mapping of which offers belong to which collections, as a single offer can appear in multiple collections.

4. Process COLLECTION_OFFERS_UPDATED incrementally - Rather than refreshing entire collection data, process the specific offers that were added or removed.

5. Consider collection hierarchy - Some platforms support nested collections. Ensure your system can handle collection relationships if applicable.

6. Update collection displays promptly - When receiving COLLECTION_OFFERS_UPDATED, update collection pages quickly to reflect the latest products.

7. Handle empty collections - A collection may temporarily have zero offers during reorganization. Ensure your UI handles empty collections gracefully.

Webhook Headers

Collection webhooks include the default webhook headers, which contain:

• X-Violet-Entity-Id - The Violet Collection ID

• X-Violet-Topic - The event type (COLLECTION_CREATED, COLLECTION_UPDATED, etc.)

• X-Violet-Event-Id - Unique event identifier for idempotency

Common Integration Patterns

Collection Lifecycle Management

COLLECTION_CREATED → Create collection page → Add to navigation
COLLECTION_OFFERS_UPDATED → Fetch offer details → Update product grid
COLLECTION_UPDATED → Refresh metadata → Update SEO
COLLECTION_REMOVED → Archive collection → Remove from navigation

Real-time Collection Updates

COLLECTION_OFFERS_UPDATED → Parse changes → Update only modified offers
COLLECTION_UPDATED → Fetch latest data → Update cached collection info

Navigation Management

COLLECTION_CREATED → Add to menu structure → Update sitemap
COLLECTION_REMOVED → Remove from menu → Update navigation cache

Coordinating with Other Events

Collection events often occur alongside sync and offer events:

Initial Collection Sync (Merchant Onboarding)

MERCHANT_CONNECTED → Merchant onboarded
PRODUCT_SYNC_COMPLETED → Products synced
COLLECTION_SYNC_STARTED → Collections sync begins
COLLECTION_CREATED (for each collection) → Collections being added
COLLECTION_OFFERS_UPDATED (for each collection) → Offers added to collections
COLLECTION_SYNC_COMPLETED → All collections synced

Merchant Updates Collection

Merchant modifies collection in platform → Change detected
COLLECTION_UPDATED → Collection metadata changed
COLLECTION_OFFERS_UPDATED → Collection contents changed

Product Changes Affect Collections

OFFER_UPDATED → Product updated in platform
COLLECTION_OFFERS_UPDATED → Automated collections recalculated
(Only fires if offer changes trigger collection rule changes)

Collection Removal Flow

Merchant deletes collection → Deletion detected
COLLECTION_REMOVED → Collection no longer available
(Offers within collection remain available)

Monitor collection events alongside sync and offer events for complete catalog organization visibility.