WooCommerce Setup Guide

Architecture

The plugin listens to WooCommerce and WordPress hooks (woocommerce_update_product, save_post, woocommerce_order_status_completed, etc.) and sends webhook events to Emporiqa using deferred delivery: product and page events are queued during the request and flushed on shutdown, while order conversion events are scheduled via Action Scheduler. Saving a product completes locally; the webhook delivery runs asynchronously after the response.

All translations and channels for a single product or page consolidate into one webhook event. Variable products sync the parent plus each variation, and changes cascade: saving a variation triggers a parent re-sync so search always sees the full catalog state. The plugin declares WooCommerce High-Performance Order Storage (HPOS) compatibility.

Requirements

Configuration Reference

All settings live at Settings → Emporiqa. Connection Settings is the main section and is expanded by default. Sync toggles and advanced settings (languages, page post types, webhook URL, batch size) are collapsed under Advanced.

Connection Settings

Advanced Settings

Most stores don't need to change these.

Always-on capabilities

• Cart operations — add, update, remove from inside the chat via AJAX endpoints that talk directly to WooCommerce's cart.
• Conversion tracking — chat sessions linked to completed orders for revenue attribution.
• Multi-currency — detects the active currency from WOOCS, WPML Multi-Currency, WooCommerce Payments, and Aelia Currency Switcher; override with the emporiqa_active_currency filter.

Features

Webhook Payload

Each product or page is sent as a single webhook event containing all languages and channels. Translatable fields are nested by channel and language code.

Product Event

{
  "type": "product.updated",
  "data": {
    "identification_number": "product-42",
    "sku": "SKU-001",
    "channels": ["default"],
    "names":        {"default": {"en": "Hiking Boots", "de": "Wanderschuhe"}},
    "descriptions": {"default": {"en": "Waterproof leather boots...", "de": "Wasserdichte Lederstiefel..."}},
    "links":        {"default": {"en": "https://store.com/hiking-boots", "de": "https://store.com/de/wanderschuhe"}},
    "categories":   {"default": {"en": ["Footwear > Hiking"], "de": ["Schuhe > Wandern"]}},
    "attributes":   {"default": {"en": {"Material": "Leather"}, "de": {"Material": "Leder"}}},
    "brands":       {"default": "TrailPeak"},
    "prices":       {"default": [{"currency": "EUR", "current_price": 129.99, "regular_price": 149.99}]},
    "images":       {"default": ["https://store.com/wp-content/uploads/boots-front.jpg"]},
    "availability_statuses": {"default": "available"},
    "stock_quantities":      {"default": 42},
    "is_parent": false,
    "parent_sku": null,
    "variation_attributes": {}
  }
}

Field Structure

Customization Filters

The plugin exposes WordPress filters you can hook from a custom plugin or your theme's functions.php to control sync behavior and modify data before it's sent.

Example: skip draft products

add_filter('emporiqa_should_sync_product', function ($should_sync, $product) {
    if (str_contains($product->get_name(), '[DRAFT]')) {
        return false;
    }
    return $should_sync;
}, 10, 2);

Example: add a custom attribute to the product payload

// Attributes are nested: {channel: {lang: {key: value}}}.
add_filter('emporiqa_product_data', function ($data, $product) {
    foreach ($data['attributes'] as $channel => &$languages) {
        foreach ($languages as $lang => &$attrs) {
            $attrs['material'] = get_field('material', $product->get_id());
        }
    }
    return $data;
}, 10, 2);

WP-CLI Commands

The plugin registers a wp emporiqa command for automation and debugging. A reference is also available in the plugin's Sync tab.

# Sync all products
wp emporiqa sync-products

# Sync all pages
wp emporiqa sync-pages

# Full sync (products + pages)
wp emporiqa sync-all

# Test webhook connection (also available as a button in the Sync tab)
wp emporiqa test-connection

# Adjust batch size for large catalogs
wp emporiqa sync-products --batch-size=25

Order Tracking

Emporiqa can look up order status on behalf of customers during chat conversations. The plugin registers a signed REST route that WordPress calls when a customer asks about their order.

Flow

1. Customer asks "Where is my order #12345?" in the chat.
2. Emporiqa sends an HMAC-SHA256 signed POST to your store.
3. The plugin looks up the order with wc_get_order(), verifies the billing email matches, and returns the status.
4. The salesperson presents the order information to the customer.

Endpoint

Setup

The endpoint is always active once the plugin is installed. To enable order lookup from chat, set the Order Tracking API URL in your Emporiqa dashboard (Store Settings → Integration) to:

Troubleshooting