# Syncs

Sync webhooks notify your application about the status of product and collection synchronization operations. These events are essential for tracking when merchant catalogs are being updated and when fresh data is available.

## Understanding Sync Events Lifecycle

**Initial Merchant Onboarding:** When a merchant first connects to your application, sync events fire in this sequence:

1. `MERCHANT_CONNECTED` event fires
2. `PRODUCT_SYNC_STARTED` fires shortly after (first catalog sync begins)
3. `PRODUCT_SYNC_COMPLETED` fires when initial sync finishes (catalog now available)
4. If collections are enabled: `COLLECTION_SYNC_STARTED` → `COLLECTION_SYNC_COMPLETED`

**Ongoing Syncs:** After the initial sync, these events continue to fire regularly:

* **Scheduled syncs**: Violet performs periodic syncs based on platform and configuration (e.g., daily)
* **Manual syncs**: Triggered via API or dashboard
* **Platform-triggered syncs**: Some platforms notify Violet of changes, triggering immediate syncs

**Important:** Sync events fire throughout a merchant's entire lifecycle, not just during onboarding. Each sync operation (initial or recurring) generates a new set of STARTED → COMPLETED/FAILED events.

## Product Sync Events

### PRODUCT\_SYNC\_STARTED

**Trigger:** When the merchant's products begin syncing. This occurs:

* Shortly after initial merchant connection (first sync)
* During scheduled periodic syncs (e.g., daily)
* When manually triggered via API or dashboard
* When the platform notifies Violet of catalog changes

**Use Case:** Subscribe to this event to:

* Display "syncing" status to users
* Pause catalog-dependent operations
* Log sync start times
* Track sync frequency and patterns
* Notify internal teams of sync initiation

**Example Payload:** See the [Product Sync Webhooks example](https://docs.violet.io/prism/handling-webhooks#product-sync-webhooks) in the Handling Webhooks guide.

**For New Merchants:** This is one of the first events you'll receive after `MERCHANT_CONNECTED`. The merchant's catalog is not yet ready for use—wait for `PRODUCT_SYNC_COMPLETED`.

### PRODUCT\_SYNC\_COMPLETED

**Trigger:** When the merchant's products sync is completed successfully. This signals that:

* All product data has been fetched from the merchant's platform
* Offers have been created or updated in Violet
* The catalog is ready for querying and display
* Any offer-level webhooks (OFFER\_CREATED, OFFER\_UPDATED) have been sent

**Use Case:** Monitor this event to:

* Refresh catalog data in your system
* Update product listings and search indexes
* Trigger post-sync operations (indexing, analytics, caching)
* Notify users that new products are available
* Calculate sync duration and performance metrics
* Enable catalog-dependent features for new merchants

**Example Payload:** See the [Product Sync Webhooks example](https://docs.violet.io/prism/handling-webhooks#product-sync-webhooks) in the Handling Webhooks guide.

**Critical:** This is your definitive signal that catalog data has been refreshed and is ready for use. Always wait for this event before querying a merchant's catalog after `PRODUCT_SYNC_STARTED`.

**For New Merchants:** Once you receive this event after initial connection, the merchant's products are available for display and purchase in your platform.

### PRODUCT\_SYNC\_FAILED

**Trigger:** If the merchant's products sync fails due to:

* Platform API errors or downtime
* Invalid merchant credentials
* Network connectivity issues
* Platform rate limiting
* Merchant account issues

**Use Case:** Monitor this event to:

* Alert internal teams to sync issues immediately
* Notify merchants of sync problems with actionable guidance
* Log error details for debugging and support
* Trigger retry mechanisms (with exponential backoff)
* Track sync reliability metrics per merchant and platform
* Escalate repeated failures

**Example Payload:** See the [Product Sync Webhooks example](https://docs.violet.io/prism/handling-webhooks#product-sync-webhooks) in the Handling Webhooks guide.

**Note:** The webhook payload typically includes error information to help diagnose the failure.

**For New Merchants:** If the initial sync fails, the merchant's catalog will not be available. You should proactively reach out to resolve the issue before they can begin selling.

## Collection Sync Events

### COLLECTION\_SYNC\_STARTED

**Trigger:** When the merchant's collections begin syncing.

**Use Case:** Subscribe to this event to:

* Display collection syncing status
* Track collection sync operations
* Coordinate with product syncs
* Log sync initiation

### COLLECTION\_SYNC\_COMPLETED

**Trigger:** When the merchant's collections sync is completed successfully.

**Use Case:** Monitor this event to:

* Refresh collection data
* Update collection navigation
* Trigger collection-based operations
* Update collection indexes
* Verify collection structure

**Important:** Collections and products may sync independently. Don't assume that a product sync also updates collections.

### COLLECTION\_SYNC\_FAILED

**Trigger:** If the merchant's collections sync fails.

**Use Case:** Monitor this event to:

* Alert teams to collection sync issues
* Notify merchants of problems
* Log error details
* Implement fallback strategies
* Track collection sync reliability

## Related Documentation

* [Catalog](https://docs.violet.io/prism/catalog) - Understand how catalog syncing works
* [Offers](https://docs.violet.io/prism/catalog/offers) - Learn about product data syncing
* [Collections](https://docs.violet.io/prism/catalog/collections) - Understand collection syncing
* [Handling Webhooks](https://docs.violet.io/prism/webhooks/handling-webhooks) - Process sync webhook events with examples

## Best Practices

1. **Don't fetch data during STARTED events** - Wait for the `COMPLETED` event before refreshing catalog data to ensure you get the complete updated dataset.
2. **Track sync pairs** - Match each `STARTED` event with its corresponding `COMPLETED` or `FAILED` event using the merchant ID to track sync duration and success rates.
3. **Handle partial syncs** - Products and collections sync independently. A product sync may complete while a collection sync is still in progress or fails.
4. **Implement sync status tracking** - Maintain a sync status for each merchant to avoid triggering operations on stale catalog data.
5. **Set timeouts** - If you don't receive a `COMPLETED` or `FAILED` event within a reasonable timeframe after `STARTED`, investigate and potentially alert.
6. **Batch post-sync operations** - After receiving `COMPLETED` events, batch your catalog refresh operations to avoid overwhelming your systems with individual offer/collection updates.
7. **Monitor sync failures** - Track `FAILED` events closely and implement alerting for repeated failures, which may indicate merchant integration issues.
8. **Use sync events for caching strategies** - Leverage sync completion events to invalidate and refresh catalog caches efficiently.

## Webhook Headers

Sync webhooks include the [default webhook headers](https://docs.violet.io/prism/webhooks/managing-webhook-headers), which contain:

* `X-Violet-Entity-Id` - The identifier for the sync operation
* `X-Violet-Topic` - The event type (PRODUCT\_SYNC\_STARTED, etc.)
* `X-Violet-Event-Id` - Unique event identifier for idempotency

## Common Integration Patterns

### Full Catalog Refresh

```
PRODUCT_SYNC_STARTED → Set status "syncing"
PRODUCT_SYNC_COMPLETED → Fetch all offers → Update catalog → Index data
COLLECTION_SYNC_COMPLETED → Fetch collections → Update navigation
```

### Sync Monitoring

```
PRODUCT_SYNC_STARTED → Record start time → Update dashboard
PRODUCT_SYNC_COMPLETED → Calculate duration → Log metrics
PRODUCT_SYNC_FAILED → Log error → Alert team → Notify merchant
```

### Coordinated Sync Operations

```
PRODUCT_SYNC_COMPLETED + COLLECTION_SYNC_COMPLETED → Both complete → Trigger full refresh
Either FAILED → Log failure → Use cached data → Alert team
```

## Coordinating with Other Events

Sync events typically occur alongside merchant and offer events:

### Initial Merchant Onboarding

```
MERCHANT_CONNECTED → Connection established
PRODUCT_SYNC_STARTED → Catalog sync begins
OFFER_CREATED (for each product) → Products being added
PRODUCT_SYNC_COMPLETED → All products synced
COLLECTION_SYNC_STARTED → Collections sync begins (if enabled)
COLLECTION_SYNC_COMPLETED → Collections available
MERCHANT_COMPLETE → Merchant ready for orders
```

### Scheduled Sync Flow

```
PRODUCT_SYNC_STARTED → Daily sync begins
OFFER_UPDATED (for changed products) → Product changes detected
PRODUCT_SYNC_COMPLETED → Sync finished
```

### Merchant Re-enablement

```
MERCHANT_ENABLED → Merchant reactivated
PRODUCT_SYNC_STARTED → Re-sync triggered
OFFER_UPDATED (all offers) → Offers re-enabled
PRODUCT_SYNC_COMPLETED → Catalog current
```

### Failed Sync Recovery

```
PRODUCT_SYNC_STARTED → Sync initiated
PRODUCT_SYNC_FAILED → Error encountered
(Wait for retry interval)
PRODUCT_SYNC_STARTED → Retry begins
PRODUCT_SYNC_COMPLETED → Success
```

Monitor sync events alongside merchant and offer events for complete catalog lifecycle visibility.

## Sync Timing Considerations

* **Initial merchant connection**: Expect sync events shortly after merchant connection completes
* **Scheduled syncs**: Violet performs periodic syncs based on platform and configuration
* **Manual syncs**: Syncs can be triggered manually through the API or dashboard
* **Platform-triggered syncs**: Some platforms notify Violet of changes, triggering immediate syncs