# 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](https://docs.violet.io/prism/catalog/collections). **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](https://docs.violet.io/prism/catalog/collections) 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](https://docs.violet.io/prism/catalog/collections) - Learn about the Collection data model * [Catalog](https://docs.violet.io/prism/catalog) - Understand Violet's catalog system * [Offers](https://docs.violet.io/prism/catalog/offers) - Learn how offers relate to collections * [Handling Webhooks](https://docs.violet.io/prism/webhooks/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](https://docs.violet.io/prism/webhooks/managing-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.