Event Notifications

SnowBee can send real-time notifications to your Azure Service Bus queue or topic when important events occur, such as inventory changes or product updates. This allows your e-commerce platform to stay synchronized with SnowBee without polling the API.

Configuration

Event notifications are configured per eCom Store in the SnowBee application. To set up Azure Service Bus notifications, you'll need the following information:

• Endpoint - Your Azure Service Bus namespace (e.g., your-namespace.servicebus.windows.net)
• Entity Path - The queue or topic name to send messages to
• Shared Access Key Name - The name of your SAS policy (e.g., send)
• Shared Access Key - The SAS key for authentication

Message Format

All event notifications are sent as JSON messages to your Azure Service Bus queue or topic. Each message contains a subject property that indicates the event type, and a message body with event details.

Message Structure

{
  "entityId": "019c1234-5678-7abc-8def-123456789012",
  "eventId": "019c5678-1234-7abc-8def-987654321098",
  "datetime": "2025-01-20T10:30:00.000Z"
}

The message subject property (accessible via ServiceBusReceivedMessage.Subject in C# or similar in other languages) indicates the event type.

Event Types

Products & Inventory

ProductUpdated

Triggered when a product is created or updated. This includes changes to product attributes, SKUs, images, or prices.

Recommended action: Call GET /products/:productId to fetch the updated product details.

Subject: ProductUpdated

{
  "entityId": "019c1234-5678-7abc-8def-123456789012",  // Product ID
  "eventId": "019c5678-1234-7abc-8def-987654321098",
  "datetime": "2025-01-20T10:30:00.000Z"
}

InventoryUpdated

Triggered when inventory availability changes for a SKU. This can happen due to:

• Stock received or adjusted in the warehouse
• Inventory reserved or released for orders
• Stock transfers between locations

The event is only sent if the SKU is in your eCom store's assortment.

Recommended action: Call GET /skus/:skuId/inventory to fetch the updated inventory levels.

Subject: InventoryUpdated

{
  "entityId": "019c1234-5678-7abc-8def-123456789012",  // SKU ID
  "eventId": "019c5678-1234-7abc-8def-987654321098",
  "datetime": "2025-01-20T10:30:00.000Z"
}

CampaignUpdated

Triggered when a campaign is created or updated. This includes changes to campaign dates, pricing, or SKU assignments.

Recommended action: Call GET /campaigns to fetch the updated campaign list.

Subject: CampaignUpdated

{
  "entityId": "019c1234-5678-7abc-8def-123456789012",  // Campaign ID
  "eventId": "019c5678-1234-7abc-8def-987654321098",
  "datetime": "2025-01-20T10:30:00.000Z"
}

Orders

OrderReadyForPaymentCapture

Triggered when a picking list is closed for an order on an eCom store that has payment capture enabled. This indicates that the order (or part of it) has been picked and is awaiting payment capture before shipment can proceed. An order may have multiple picking lists (e.g., partial fulfillment), each with its own independent capture lifecycle.

Shipment of each picking list is blocked until its payment capture is confirmed. Call GET /orders/:orderId to fetch the order with line-level pickedQuantity and the pickingLists array (which includes each picking list's id and paymentCaptureStatus), then call POST /orders/:orderId/picking_lists/:pickingListId/payment_capture with status CONFIRMED or FAILED.

Required action: Call GET /orders/:orderId to get picked quantities, pricing, and picking list IDs, capture payment externally, then call POST /orders/:orderId/picking_lists/:pickingListId/payment_capture with the capture result.

Subject: OrderReadyForPaymentCapture

{
  "entityId": "019c1234-5678-7abc-8def-123456789012",  // Order ID
  "eventId": "019c5678-1234-7abc-8def-987654321098",
  "datetime": "2025-01-20T10:30:00.000Z"
}

OrderFulfilled

Triggered when an invoice is created for an order, indicating the order (or part of it) has been fulfilled and is ready for shipping.

Recommended action: Call GET /orders/:orderId to fetch the order with invoice details.

Subject: OrderFulfilled

{
  "entityId": "019c1234-5678-7abc-8def-123456789012",  // Order ID
  "eventId": "019c5678-1234-7abc-8def-987654321098",
  "datetime": "2025-01-20T10:30:00.000Z"
}

Stores

RetailStoreUpdated

Triggered when a retail store's name, store number, or visit address changes. This event is only sent for retail stores that belong to a company linked to your eCom store via click & collect.

Recommended action: Call GET /retail_stores to fetch the updated store details.

Subject: RetailStoreUpdated

{
  "entityId": "019c1234-5678-7abc-8def-123456789012",  // Retail Store ID
  "eventId": "019c5678-1234-7abc-8def-987654321098",
  "datetime": "2025-01-20T10:30:00.000Z"
}

Product Schema

These events are triggered when product schema data (lookup tables) are updated. The entityId will be null for these events since they affect the entire schema.

Best Practices

Idempotency

Each event includes a unique eventId (UUIDv7). Store processed event IDs to avoid reprocessing the same event if it's delivered multiple times (at-least-once delivery).

Event Ordering

Events may arrive out of order. Use the datetime field to determine the chronological order of events. For inventory updates, always fetch the latest state from the API rather than applying incremental changes.

Handling High Volume

During bulk imports or updates, you may receive many events in a short period. Consider:

• Batching API calls to fetch multiple products at once
• Implementing a delay/debounce to coalesce multiple events for the same entity
• Using Azure Service Bus sessions or partitioning for ordered processing per entity

Error Handling

If your message handler fails, the message will be returned to the queue for retry (depending on your Azure Service Bus configuration). Implement proper dead-letter queue handling for messages that consistently fail.

Example: C# Message Handler

using Azure.Messaging.ServiceBus;
using System.Text.Json;

public class SnowBeeEventHandler
{
    private readonly SnowBeeApiClient _apiClient;

    public async Task ProcessMessageAsync(ServiceBusReceivedMessage message)
    {
        var subject = message.Subject;
        var body = JsonSerializer.Deserialize<SnowBeeEvent>(message.Body);

        switch (subject)
        {
            case "InventoryUpdated":
                await HandleInventoryUpdated(body.EntityId);
                break;
            case "ProductUpdated":
                await HandleProductUpdated(body.EntityId);
                break;
            case "CampaignUpdated":
                await HandleCampaignUpdated();
                break;
            case "OrderReadyForPaymentCapture":
                await HandleOrderReadyForPaymentCapture(body.EntityId);
                break;
            case "OrderFulfilled":
                await HandleOrderFulfilled(body.EntityId);
                break;
            case "RetailStoreUpdated":
                await HandleRetailStoreUpdated(body.EntityId);
                break;
            case "BrandsUpdated":
            case "ProductCategoriesUpdated":
            case "SizesUpdated":
                // ... other schema events
                await HandleSchemaUpdated(subject);
                break;
        }
    }

    private async Task HandleInventoryUpdated(string skuId)
    {
        var inventory = await _apiClient.GetSkuInventory(skuId);
        // Update your local inventory cache/database
    }

    private async Task HandleProductUpdated(string productId)
    {
        var product = await _apiClient.GetProduct(productId);
        // Update your local product catalog
    }

    private async Task HandleCampaignUpdated()
    {
        var campaigns = await _apiClient.GetCampaigns();
        // Update your local campaign/pricing data
    }

    private async Task HandleOrderReadyForPaymentCapture(string orderId)
    {
        var order = await _apiClient.GetOrder(orderId);
        // Find picking lists with PENDING payment capture
        foreach (var pickingList in order.PickingLists.Where(pl => pl.PaymentCaptureStatus == "PENDING"))
        {
            // Calculate capture amount from line items using pickedQuantity and pricing
            // Capture payment via your payment provider
            // Then report capture result to SnowBee:
            // POST /orders/{orderId}/picking_lists/{pickingListId}/payment_capture
            // { "status": "CONFIRMED", "capturedAmount": "1499.00" }
            // or { "status": "FAILED" } if capture failed
            await _apiClient.UpdatePaymentCapture(orderId, pickingList.Id, "CONFIRMED", capturedAmount);
        }
    }

    private async Task HandleOrderFulfilled(string orderId)
    {
        var order = await _apiClient.GetOrder(orderId);
        // Process fulfillment, update order status, trigger shipping
    }

    private async Task HandleRetailStoreUpdated(string retailStoreId)
    {
        var stores = await _apiClient.GetRetailStores();
        // Update your local store data (name, number, address)
    }

    private async Task HandleSchemaUpdated(string schemaType)
    {
        // Refresh the relevant schema data
        // e.g., reload brands, categories, sizes, etc.
    }
}

public record SnowBeeEvent(
    string? EntityId,
    string EventId,
    string Datetime
);

Triggering Initial Sync

When setting up a new integration, you can trigger events for all entities in your eCom store assortment to populate your local data without polling.

Trigger Product Events

POST /v1/tenants/TENANT_ID/ecom_stores/ECOM_STORE_ID/products/trigger_events
Authorization: Bearer YOUR_ACCESS_TOKEN

Response:
{
  "eventsTriggered": 1250,
  "message": "Successfully triggered 1250 product events"
}

This triggers ProductUpdated events for all products in your assortment.

Trigger Inventory Events

POST /v1/tenants/TENANT_ID/ecom_stores/ECOM_STORE_ID/inventory/trigger_events
Authorization: Bearer YOUR_ACCESS_TOKEN

Response:
{
  "eventsTriggered": 3500,
  "message": "Successfully triggered 3500 inventory events"
}

This triggers InventoryUpdated events for all SKUs in your assortment, allowing you to sync current inventory levels.

Related Links

• Getting Started - Authentication and first API calls
• API Reference - Full OpenAPI documentation
• Azure Service Bus Documentation