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 and Connection Health guide.

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

Related Documentation

• Violet Connect - Learn about the merchant onboarding process

• Connection Health - Understand connection health checks

• Detecting Merchant Connections - Best practices for tracking merchant connections

• 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, plus:

X-Violet-Reason

Provides additional context about why the event was triggered (available on MERCHANT_ENABLED and MERCHANT_DISABLED events).