Drupal Commerce Setup Guide

Architecture

The module listens to entity CRUD hooks (hook_entity_insert, hook_entity_update, hook_entity_delete) for Commerce products, variations, and configured node types. Events are pushed onto a dedicated Drupal queue worker and delivered to Emporiqa asynchronously, so saving a product never blocks on the network.

All translations and channels for a single product or page consolidate into one webhook event. Variations cascade up: editing a variation triggers a parent product re-sync so search always sees the full catalog state. Conversion tracking is handled by an event subscriber on Commerce order state transitions (OrderCompleteSubscriber).

Webhook delivery retries up to 3 times on transient errors (HTTP 429, 502, 503, 504) and network failures, with linear backoff between attempts. The queue is processed by Drupal's cron — if the queue grows past 10,000 items, a warning is logged (typically meaning the webhook endpoint is unreachable or cron isn't running).

Requirements

Configuration Reference

All settings live at Configuration → Web services → Emporiqa (/admin/config/services/emporiqa). The Sync tab lives at /admin/config/services/emporiqa/sync. The administer emporiqa permission is required.

Connection Settings

Sync Settings

Most stores don't need to change these.

Field Auto-detection

On install, the module auto-detects your product fields (category, brand, images, stock, attributes) from the Commerce product and variation entity schemas. The mappings are stored in config and can be adjusted on the settings form.

Page Sync via Display Modes

Pages are synced using Drupal's native display modes — no custom code needed. The module creates an Emporiqa display on install and enables it for common content types (page, article).

1. Go to Structure → Content types → [Your type] → Manage display.
2. Enable the Emporiqa tab.
3. Drag the fields you want synced into that display.

The rendered output of the Emporiqa display becomes the page content sent to the webhook. Different content types can expose different fields, all configured through Drupal's admin — no module code touched. The same approach works for product descriptions when the Emporiqa display is enabled on a product type.

Always-on capabilities

• Cart operations — add, update, and remove items from inside the chat via /emporiqa/api/cart/*. Checkout happens on your Commerce checkout page; the widget redirects when the customer is ready.
• Conversion tracking — chat sessions linked to completed Commerce orders for revenue attribution.
• Multi-store mapping — each Commerce store can be assigned a channel via hook_emporiqa_channels_alter.

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": "product-42",
    "channels": [""],
    "names":        {"": {"en": "Hiking Boots", "de": "Wanderschuhe"}},
    "descriptions": {"": {"en": "Waterproof leather boots...", "de": "Wasserdichte Lederstiefel..."}},
    "links":        {"": {"en": "https://store.com/hiking-boots", "de": "https://store.com/de/wanderschuhe"}},
    "categories":   {"": {"en": ["Footwear > Hiking"], "de": ["Schuhe > Wandern"]}},
    "attributes":   {"": {"en": {"Material": "Leather"}, "de": {"Material": "Leder"}}},
    "brands":       {"": "TrailPeak"},
    "prices":       {"": [{"currency": "EUR", "current_price": 129.99, "regular_price": 149.99}]},
    "images":       {"": ["https://store.com/files/boots-front.jpg"]},
    "availability_statuses": {"": "available"},
    "stock_quantities":      {"": 42},
    "is_parent": false,
    "parent_sku": null,
    "variation_attributes": {}
  }
}

Page Event

{
  "type": "page.created",
  "data": {
    "identification_number": "page-45",
    "channels": [""],
    "titles":   {"": {"en": "Shipping Policy", "de": "Versandrichtlinien"}},
    "contents": {"": {"en": "<p>Rendered Emporiqa display...</p>", "de": "<p>Gerenderte Emporiqa-Anzeige...</p>"}},
    "links":    {"": {"en": "https://store.com/shipping-policy", "de": "https://store.com/de/versandrichtlinien"}}
  }
}

Field Structure

Customization Hooks

The module provides Drupal alter hooks you can implement in a custom module (mymodule.module) to control sync behavior, modify payloads, and extend order tracking and cart operations. Full documentation lives in emporiqa.api.php.

Example: skip draft pages

/**
 * Implements hook_emporiqa_entity_sync_alter().
 */
function mymodule_emporiqa_entity_sync_alter(
  bool &$sync,
  \Drupal\Core\Entity\EntityInterface $entity,
  string $entity_type,
  string $operation,
): void {
  if (
    $entity_type === 'page'
    && $entity instanceof \Drupal\node\NodeInterface
    && str_contains($entity->getTitle(), '[DRAFT]')
  ) {
    $sync = FALSE;
  }
}

Example: add tax-inclusive prices

/**
 * Implements hook_emporiqa_price_entry_alter().
 */
function mymodule_emporiqa_price_entry_alter(
  array &$entry,
  array $context,
): void {
  $entry['price_incl_tax'] = round($entry['current_price'] * 1.20, 2);
  $entry['price_excl_tax'] = $entry['current_price'];
}

Example: provide tier prices

/**
 * Implements hook_emporiqa_tier_prices_alter().
 */
function mymodule_emporiqa_tier_prices_alter(
  array &$tier_prices,
  array $context,
): void {
  $variation = $context['variation'];

  if ($variation->hasField('field_tier_prices')) {
    foreach ($variation->get('field_tier_prices') as $item) {
      $tier_prices[] = [
        'min_quantity' => (int) $item->min_qty,
        'price' => (float) $item->price,
        'currency' => $context['currency'],
      ];
    }
  }
}

Example: cancel a cart operation

/**
 * Implements hook_emporiqa_cart_alter().
 */
function mymodule_emporiqa_cart_alter(array &$context): void {
  if ($context['operation'] === 'add') {
    $total_qty = 0;
    foreach ($context['items'] as $item) {
      $total_qty += $item['quantity'] ?? 1;
    }
    if ($total_qty > 10) {
      $context['cancel'] = TRUE;
      $context['cancel_message'] = 'Maximum 10 items per operation.';
    }
  }
}

Drush Commands

The module provides Drush commands for deployment pipelines, cron jobs, and debugging.

# Full sync (products + pages)
drush emporiqa:sync-all         # alias: em:sa

# Sync products only
drush emporiqa:sync-products    # alias: em:sp

# Sync pages only
drush emporiqa:sync-pages       # alias: em:spg

# Test the webhook connection (dry run with a real product)
drush emporiqa:test-connection  # alias: em:tc

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

options:
  uri: 'https://your-store-domain.com'

Order Tracking

Emporiqa can look up order status on behalf of customers during chat conversations. The module registers a signed endpoint that Emporiqa 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 Drupal site.
3. The module looks up the Commerce order, verifies the customer's email, and returns the status.
4. The salesperson presents the order information to the customer.

Endpoint

The endpoint is rate-limited to 50 requests per hour per IP using Drupal's Flood API.

Default behavior

If Commerce Order is installed, the module looks up orders by order number and returns status, items, and totals. No code needed. Email verification is always required — the customer must provide the email on the order before any data is returned.

Setup

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

Custom order systems

For non-Commerce order systems, implement hook_emporiqa_order_tracking_alter() in a custom module:

/**
 * Implements hook_emporiqa_order_tracking_alter().
 */
function mymodule_emporiqa_order_tracking_alter(
  ?array &$response,
  string $order_identifier,
  array $body,
): void {
  $order = my_erp_get_order($order_identifier);
  if ($order) {
    $response = [
      'order_id' => $order->id,
      'status' => $order->status,
      'placed_at' => $order->created_at,
      'items' => $order->items,
    ];
  }
}

Troubleshooting