# 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](/prism/catalog/collections.md). **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](/prism/catalog/collections.md) 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](/prism/catalog/collections.md) - Learn about the Collection data model * [Catalog](/prism/catalog.md) - Understand Violet's catalog system * [Offers](/prism/catalog/offers.md) - Learn how offers relate to collections * [Handling Webhooks](/prism/webhooks/handling-webhooks.md) - 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](/prism/webhooks/managing-webhook-headers.md), 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. --- # 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/collection-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.