Documentation Index

Fetch the complete documentation index at: https://docs.mercurjs.com/llms.txt

Use this file to discover all available pages before exploring further.

​

Core Subscribers Reference

​

Payout Subscribers

​

payout-order-handler

​

Functionality

1. Receives the order ID from the event payload
2. Executes the processPayoutForOrderWorkflow to create and process the payout
3. Uses the order ID as a transaction ID for idempotency

​

Event Payload

{
  order_id: string // The ID of the order to process for payout
}

​

Use Cases

• Automated payout processing triggered by scheduled jobs
• Manual payout retries for failed orders
• Catch-up processing for orders missing payouts

​

payout-webhook-handler

​

Functionality

1. Deserializes the webhook data (handles Buffer serialization)
2. Uses the payout service to parse and validate the webhook
3. Determines the appropriate action (account authorized, deauthorized, requires action)
4. Executes the processPayoutWebhookActionWorkflow with the parsed data

​

Event Payload

{
  rawData: Buffer | ArrayBuffer, // Raw webhook data from payment provider
  signature: string // Webhook signature for verification
}

​

Use Cases

• Stripe Connect account status updates
• Payment provider webhook processing
• Payout account authorization changes
• Account requirement notifications

​

Order and Payment Subscribers

​

order-set-placed-payment-capture

​

Functionality

1. Retrieves the order set and associated payment collection
2. Validates that payment exists
3. Executes the capturePaymentWorkflow to capture the payment
4. Marks all split order payments as captured via markSplitOrderPaymentsAsCapturedWorkflow
5. Throws an error if payment capture fails

​

Event Payload

{
  id: string // The ID of the order set
}

​

Use Cases

• Multi-seller order payment capture
• Split payment processing
• Payment validation and error handling

​

split-payment-payment-captured

​

Functionality

1. Retrieves the payment and its associated payment collection
2. Executes the markSplitOrderPaymentsAsCapturedWorkflow to update all related split order payments

​

Event Payload

{
  id: string // The ID of the captured payment
}

​

Use Cases

• Synchronizing split payment statuses
• Tracking payment capture across multiple seller orders
• Maintaining payment consistency

​

Notification Subscribers

​

notification-seller-new-order

​

Functionality

1. Retrieves order details including seller and customer information
2. Validates that the order and seller email exist
3. Creates a notification in the seller feed
4. Includes order ID and customer name in the notification

​

Event Payload

{
  id: string // The ID of the placed order
}

​

Use Cases

• Seller order notifications
• In-app notification feed updates
• Email notifications to sellers
• Order management alerts

​

notification-admin-new-order-set

​

Functionality

1. Retrieves the order set and counts the number of orders
2. Only proceeds if the order set contains 2 or more orders (multi-seller)
3. Creates an admin UI notification
4. Includes a redirect link to the orders page

​

Event Payload

{
  id: string // The ID of the order set
}

​

Use Cases

• Admin dashboard notifications
• Multi-seller order monitoring
• Order management alerts
• Administrative oversight

​

Seller Management Subscribers

​

seller-creation-request-accepted

​

Functionality

1. Extracts seller, member, and authentication data from the request
2. Executes the createSellerWorkflow to create the seller account
3. Logs the successful creation with seller and request IDs

​

Event Payload

{
  id: string, // The request ID
  data: {
    member: object, // Member information
    seller: object, // Seller information
    auth_identity_id: string // Authentication identity ID
  }
}

​

Use Cases

• Automated seller onboarding
• Request approval workflow completion
• Seller account provisioning

​

seller-status-changed

​

Functionality

1. Retrieves all products associated with the seller
2. Emits an algolia.products.changed event with the product IDs
3. Skips processing if the seller has no products

​

Event Payload

{
  id: string, // The seller ID
  store_status: StoreStatus // The new store status (active, inactive, etc.)
}

​

Use Cases

• Search index synchronization
• Product visibility updates
• Store status propagation
• Marketplace product filtering

​

Algolia Search Index Subscribers

​

algolia-fulfillment-set-changed

​

Functionality

1. Retrieves the seller associated with the fulfillment set
2. Fetches all products belonging to that seller
3. Emits algolia.products.changed event to update product indexes

​

algolia-inventory-item-changed

​

Functionality

1. Retrieves inventory items and their associated product variants
2. Extracts unique product IDs from variants
3. Emits algolia.products.changed event to update product indexes

​

algolia-service-zone-changed

​

Functionality

1. Retrieves the seller associated with the service zone
2. Fetches all products belonging to that seller
3. Emits algolia.products.changed event to update product indexes

​

algolia-shipping-option-changed

​

Functionality

1. Retrieves the seller associated with the shipping option
2. Fetches all products belonging to that seller
3. Emits algolia.products.changed event to update product indexes

​

algolia-stock-location-changed

​

Functionality

1. Retrieves the seller associated with the stock location
2. Fetches all products belonging to that seller
3. Emits algolia.products.changed event to update product indexes

​

Notes

​

Event-Driven Architecture

• Decoupling: Workflows emit events without knowing who will handle them
• Scalability: Multiple subscribers can react to the same event
• Reliability: Event bus handles retries and delivery guarantees
• Extensibility: New subscribers can be added without modifying existing code

​

Subscriber Configuration

• event: The event name to listen for
• subscriberId: A unique identifier for the subscriber
• context: Optional metadata for the subscriber

​

Error Handling

• Failed subscribers are automatically retried based on event bus configuration
• Critical failures should be logged for monitoring
• Validation errors should return early to avoid unnecessary processing

​

Algolia Synchronization Pattern

1. Intermediate Events: Emitted when shipping, inventory, or fulfillment data changes
2. Subscriber Processing: Identifies affected products
3. Product Events: Emits consolidated algolia.products.changed events
4. Index Updates: Separate Algolia module subscriber handles actual index updates

​

Performance Considerations

• Subscribers run asynchronously and don’t block the main application flow
• Heavy operations should be delegated to workflows for better error recovery
• Batch operations where possible (e.g., processing multiple product IDs at once)
• Use early returns to skip unnecessary processing