# Merchants Merchant webhooks notify your application about changes to merchant connection status, availability, and health. These events are essential for tracking which merchants are actively connected to your application and ready to process orders. ## Overview Merchant webhooks track the complete lifecycle of merchant connections, from initial onboarding through disconnection. These events enable you to monitor merchant status, connection health, and availability for order processing. Learn more about merchant connections in the [Violet Connect documentation](https://docs.violet.io/prism/violet-connect) and [Connection Health guide](https://docs.violet.io/prism/violet-connect/guides/connection-health). ## Understanding Merchant States Merchants progress through several connection states: * **Connected** - Merchant has completed Violet Connect onboarding * **Disconnected** - Merchant has uninstalled your app or terminated connection * **Enabled** - Merchant is active and can process orders * **Disabled** - Merchant is temporarily inactive (app uninstalled, platform issues, etc.) * **Complete** - All connection health requirements satisfied, ready for orders * **Needs Attention** - Connection health check has incomplete or missing items A merchant can be connected but disabled (credentials still valid but temporarily inactive), or connected and enabled but needing attention (minor setup issues to resolve). ## Available Events ### MERCHANT\_CONNECTED **Trigger:** When a merchant completes the Violet Connect onboarding experience and is successfully connected to your app. **Use Case:** Subscribe to this event to: * Welcome new merchants to your platform * Initialize merchant-specific settings * Trigger catalog syncs * Send onboarding confirmation emails * Track merchant acquisition metrics **Payload Data:** The webhook payload contains all non-sensitive data related to that merchant, including: * Merchant name * Merchant ID * Platform information * Connection timestamp ### MERCHANT\_DISCONNECTED **Trigger:** When a merchant explicitly disconnects from your application or uninstalls your app from their platform. **Common Causes:** * Merchant uninstalls your app from their e-commerce platform * Merchant explicitly requests disconnection through your interface * Merchant terminates their store or platform account * Platform-level app connection revoked **Impact:** * Your app loses all access to the merchant's catalog data * All API credentials for the merchant are invalidated * Merchant's offers are no longer available through your platform * The merchant-app connection is permanently terminated * If the merchant reconnects later, a new connection is established with potentially different terms (e.g., new commission rate) **Use Case:** Subscribe to this event to: * Clean up merchant-specific data and cache * Pause or remove active campaigns and product listings * Send disconnect confirmation to merchant * Track churn metrics and merchant retention * Archive merchant information for historical records * Disable merchant-facing features and dashboards * Update internal systems to reflect disconnection ### MERCHANT\_ENABLED **Trigger:** When an existing disabled merchant in Violet is updated to enabled status. **Use Case:** Monitor this event to: * Resume merchant operations * Reactivate catalog listings * Notify internal teams of merchant reactivation * Update merchant status in your systems **Additional Context:** May include `X-Violet-Reason` header with: * `APP_INSTALLED_ON_PLATFORM` - Merchant reinstalled your app on their platform ### MERCHANT\_DISABLED **Trigger:** When an existing enabled merchant in Violet is updated to disabled status. **Use Case:** Subscribe to this event to: * Pause merchant operations * Remove catalog listings * Stop processing orders * Alert internal teams * Update merchant status **Additional Context:** May include `X-Violet-Reason` header with reasons such as: * `APP_UNINSTALLED_FROM_PLATFORM` - Merchant uninstalled your app from their platform * `MERCHANT_PLATFORM_PLAN_INACTIVE` - Merchant's platform subscription is inactive ### MERCHANT\_NEEDS\_ATTENTION **Trigger:** When a merchant has any `INCOMPLETE` or `NEEDS_ATTENTION` items during the connection health check. **Use Case:** Monitor this event to: * Alert merchants about required actions * Display in-app notifications * Send reminder emails * Track onboarding completion rates * Provide support to struggling merchants **Payload Details:** The payload includes: * List of incomplete items * Health check status * Required actions * Merchant contact information **Example:** See the [Merchant Needs Attention example](https://docs.violet.io/prism/handling-webhooks#merchant-needs-attention-complete-webhooks) in the Handling Webhooks guide. ### MERCHANT\_COMPLETE **Trigger:** When a merchant has completed all required items to begin processing orders. This means their connection health check has all items marked `COMPLETE`. **Use Case:** Subscribe to this event to: * Enable order processing for the merchant * Congratulate merchants on completing setup * Activate merchant in your platform * Begin catalog syncing and order fulfillment * Update merchant dashboard status **Payload Format:** Uses the same format as [MERCHANT\_NEEDS\_ATTENTION](https://docs.violet.io/prism/handling-webhooks#merchant-needs-attention-complete-webhooks). ## Related Documentation * [Violet Connect](https://docs.violet.io/prism/violet-connect) - Learn about the merchant onboarding process * [Connection Health](https://docs.violet.io/prism/violet-connect/guides/connection-health) - Understand connection health checks * [Detecting Merchant Connections](https://docs.violet.io/prism/violet-connect/guides/detecting-merchants-post-connection) - Best practices for tracking merchant connections * [Handling Webhooks](https://docs.violet.io/prism/webhooks/handling-webhooks) - Process merchant webhook events properly ## Common Integration Patterns ### Merchant Onboarding Flow ``` MERCHANT_CONNECTED → Store merchant data → Trigger PRODUCT_SYNC PRODUCT_SYNC_COMPLETED → Catalog available → Check connection health MERCHANT_COMPLETE → Enable order processing → Notify merchant of go-live ``` ### Merchant Lifecycle Management ``` MERCHANT_CONNECTED → Active merchant tracking MERCHANT_NEEDS_ATTENTION → Alert merchant → Provide guidance MERCHANT_COMPLETE → Enable features → Send congratulations ``` ### Merchant Offboarding ``` MERCHANT_DISABLED (X-Violet-Reason: APP_UNINSTALLED) → Pause operations → Archive data MERCHANT_DISCONNECTED → Clean up credentials → Remove from active merchants ``` ### Merchant Re-enabling ``` MERCHANT_ENABLED (X-Violet-Reason: APP_INSTALLED) → Trigger re-sync → Reactivate features PRODUCT_SYNC_COMPLETED → Catalog refreshed → Resume operations ``` ## Coordinating with Other Events Merchant events typically trigger or coordinate with other webhook events: ### Initial Connection Flow ``` MERCHANT_CONNECTED → Merchant onboarded PRODUCT_SYNC_STARTED → Catalog sync begins PRODUCT_SYNC_COMPLETED → Products available MERCHANT_COMPLETE → Ready for orders ``` ### Merchant Disablement Flow ``` MERCHANT_DISABLED (app uninstalled) → Merchant inactive OFFER_UPDATED (all offers) → Offers marked disabled Catalog operations paused → No new syncs ``` ### Merchant Re-enablement Flow ``` MERCHANT_ENABLED (app reinstalled) → Merchant reactivated PRODUCT_SYNC_STARTED → Catalog re-sync begins OFFER_UPDATED (all offers) → Offers re-enabled PRODUCT_SYNC_COMPLETED → Merchant fully operational ``` Monitor merchant events alongside sync and offer events for complete merchant lifecycle visibility. ## Best Practices 1. **Track merchant lifecycle** - Subscribe to all merchant events to maintain an accurate view of merchant status across their entire lifecycle. 2. **Handle health checks proactively** - When receiving `MERCHANT_NEEDS_ATTENTION` events, proactively reach out to merchants with guidance on completing their setup. 3. **Validate merchant state before operations** - Always check that a merchant is in `COMPLETE` status before attempting to process orders or sync catalogs. 4. **Monitor reason headers** - Pay attention to the `X-Violet-Reason` header to understand why status changes occurred and take appropriate action. 5. **Implement merchant re-enabling** - Have processes in place to handle merchants who disable and re-enable your app, ensuring smooth reactivation. 6. **Update internal systems promptly** - When merchants disconnect or become disabled, update your systems immediately to prevent attempting operations on unavailable merchants. 7. **Coordinate with sync events** - Merchant connection events often trigger sync events. Monitor both to understand when catalogs are ready. 8. **Handle connection vs enablement separately** - A merchant can be connected but disabled. Design your system to handle these states independently. ## Webhook Headers Merchant webhooks include the [default webhook headers](https://docs.violet.io/prism/webhooks/managing-webhook-headers), plus: ### X-Violet-Reason Provides additional context about why the event was triggered (available on `MERCHANT_ENABLED` and `MERCHANT_DISABLED` events).