Requisition List Events and Data

The Requisition List drop-in uses the event bus to emit and listen to events for communication between drop-ins and external integrations.

Version: 1.0.0

Events reference

Event	Direction	Description
requisitionList/alert	Emits and listens	Triggered when an alert or notification occurs.
requisitionList/data	Emits and listens	Triggered when data is available or changes.
requisitionList/initialized	Emits and listens	Triggered when the component completes initialization.
requisitionList/redirect	Emits and listens	Triggered when a redirect or navigation is suggested.
requisitionLists/data	Emits and listens	Triggered when data is available or changes.

Event details

The following sections provide detailed information about each event, including its direction, event payload, and usage examples.

requisitionList/alert (emits and listens)

Triggered when an alert or notification occurs. It emits and listens for alerts related to requisition list actions.

Tip

The requisitionList/alert event provides a standardized way to display feedback to users. Consider implementing a global alert handler rather than handling alerts in individual components.

When triggered

• After successful list operations (create, update, delete)
• After adding items to cart from a list
• After item operations (add, update, remove)
• On operation errors or validation failures

Usage scenarios

• Display toast notifications.
• Show inline error messages.
• Log user actions for analytics.
• Trigger accessibility announcements.
• Update status indicators.

Event payload

RequisitionListActionPayload

See RequisitionListActionPayload for full type definition.

Example

import { events } from '@dropins/tools/event-bus.js';

events.on('requisitionList/alert', (payload) => {
  const { type, message } = payload.data;

  // Display alert using your notification system
  showNotification({
    type,
    message,
    duration: type === 'error' ? 5000 : 3000
  });

  console.log(`${type.toUpperCase()}: ${message}`);
});

---

requisitionList/data (emits and listens)

Triggered when data is available or changes. It emits and listens for updates to a single requisition list.

When triggered

• After loading a requisition list
• After adding items to the list
• After removing items from the list
• After updating item quantities
• After updating list details (name, description)

Usage scenarios

• Refresh the list details view after changes.
• Update item count displays and badges.
• Recalculate list totals and pricing.
• Update caching or local storage.
• Enable/disable action buttons based on list state.
• Add entire requisition lists to the cart with one click.
• Implement selective item-to-cart workflows.
• Handle inventory availability in real-time.
• Track cart conversions from requisition lists.
• Show progress during bulk add operations.

Event payload

RequisitionList | null

See RequisitionList for full type definition.

Example 1: Basic list data handler

import { events } from '@dropins/tools/event-bus.js';

events.on('requisitionList/data', (payload) => {
  const list = payload.data;

  console.log(`List "${list.name}" updated`);
  console.log(`Total items: ${list.items.length}`);

  // Update the UI
  updateListDisplay(list);

  // Update item count badge
  updateItemCount(list.items.length);

  // Refresh totals
  calculateListTotals(list.items);
});

Example 2: Add entire requisition list to cart

import { events } from '@dropins/tools/event-bus.js';
import { addRequisitionListItemsToCart } from '@dropins/storefront-requisition-list/api.js';

class QuickCartIntegration {
  constructor() {
    events.on('requisitionList/data', this.handleListData.bind(this));
    events.on('cart/updated', this.handleCartUpdated.bind(this));
  }

  handleListData(payload) {
    const list = payload.data;

    // Add quick-add button to UI
    this.renderQuickAddButton(list);
  }

  renderQuickAddButton(list) {
    const button = document.createElement('button');
    button.className = 'quick-add-to-cart';
    button.textContent = `Add all ${list.items.length} items to cart`;
    button.onclick = () => this.addAllToCart(list);

    document.querySelector('#list-actions').appendChild(button);
  }

  async addAllToCart(list) {
    try {
      showLoadingOverlay('Adding items to cart...');

      // Add all items from requisition list to cart
      await addRequisitionListItemsToCart({
        requisitionListUid: list.uid,
        requisitionListItems: list.items.map(item => ({
          uid: item.uid,
          quantity: item.quantity
        }))
      });

      hideLoadingOverlay();
      showSuccessNotification(`Added ${list.items.length} items to cart`);

      // Redirect to cart
      setTimeout(() => window.location.href = '/cart', 1500);

    } catch (error) {
      hideLoadingOverlay();
      showErrorNotification('Failed to add items: ' + error.message);
    }
  }

  handleCartUpdated(payload) {
    // Update cart badge
    document.querySelector('.cart-count').textContent = payload.data.itemCount;
  }
}

const quickCart = new QuickCartIntegration();

Example 3: Selective cart integration with inventory check

import { events } from '@dropins/tools/event-bus.js';
import { addToCart } from '@dropins/storefront-cart/api.js';

class SelectiveCartManager {
  constructor() {
    this.selectedItems = new Set();

    events.on('requisitionList/data', this.handleListData.bind(this));
  }

  handleListData(payload) {
    const list = payload.data;

    // Render list with selection checkboxes
    this.renderSelectableList(list);
  }

  renderSelectableList(list) {
    const container = document.querySelector('#list-items');

    container.innerHTML = list.items.map(item => `
      <div class="list-item ${item.available ? '' : 'out-of-stock'}">
        <input
          type="checkbox"
          data-sku="${item.sku}"
          ${item.available ? '' : 'disabled'}
          onchange="window.cartManager.toggleItem('${item.sku}', this.checked)"
        />
        <div class="item-info">
          <h4>${item.name}</h4>
          <p>SKU: ${item.sku} | Qty: ${item.quantity}</p>
          ${!item.available ? '<span class="badge">Out of Stock</span>' : ''}
        </div>
      </div>
    `).join('');

    // Add bulk action button
    this.addBulkActionButton();
  }

  toggleItem(sku, checked) {
    if (checked) {
      this.selectedItems.add(sku);
    } else {
      this.selectedItems.delete(sku);
    }
    this.updateBulkButton();
  }

  addBulkActionButton() {
    const button = document.createElement('button');
    button.id = 'add-selected';
    button.textContent = 'Add selected to cart';
    button.disabled = true;
    button.onclick = () => this.addSelectedToCart();

    document.querySelector('#bulk-actions').appendChild(button);
  }

  updateBulkButton() {
    const button = document.querySelector('#add-selected');
    const count = this.selectedItems.size;

    button.disabled = count === 0;
    button.textContent = count > 0
      ? `Add ${count} selected items to cart`
      : 'Select items to add';
  }

  async addSelectedToCart() {
    const items = Array.from(this.selectedItems);

    try {
      showLoadingOverlay(`Adding ${items.length} items...`);

      for (const sku of items) {
        const item = this.findItemBySku(sku);
        await addToCart({
          sku: item.sku,
          quantity: item.quantity,
          selectedOptions: item.selectedOptions
        });
      }

      hideLoadingOverlay();
      showSuccessNotification(`Added ${items.length} items to cart`);

      // Clear selection
      this.selectedItems.clear();
      this.updateBulkButton();

      // Redirect
      window.location.href = '/cart';

    } catch (error) {
      hideLoadingOverlay();
      showErrorNotification('Failed to add items: ' + error.message);
    }
  }

  findItemBySku(sku) {
    // Helper to find item data
    return this.currentList.items.find(item => item.sku === sku);
  }
}

// Make globally accessible
window.cartManager = new SelectiveCartManager();

---

requisitionList/initialized (emits and listens)

Triggered when the component completes initialization.

When triggered

• After initialize() function completes
• On drop-in first load
• After configuration is applied

Note

This event does not include a payload. It serves as a signal that initialization is complete.

Example

import { events } from '@dropins/tools/event-bus.js';

events.on('requisitionList/initialized', () => {
  console.log('Requisition List drop-in ready');

  // Load initial data
  loadRequisitionLists();

  // Enable UI interactions
  enableRequisitionListFeatures();

  // Track analytics
  trackRequisitionListEnabled();
});

Usage scenarios

• Load initial requisition lists.
• Enable feature-specific UI elements.
• Initialize dependent components.
• Track feature availability.
• Set up additional event listeners.

---

requisitionList/redirect (emits and listens)

Triggered when a redirect or navigation is suggested after a requisition list operation.

Note

The requisitionList/redirect event is advisory - your application controls whether to honor the redirect request. This allows you to implement custom routing logic or prevent navigation in certain scenarios.

When triggered

• After successfully adding items to cart from a list
• After completing a list operation that requires navigation
• When the drop-in suggests moving to a different page

Usage scenarios

• Redirect to cart after adding items.
• Navigate to list details after creation.
• Implement custom routing logic.
• Prevent navigation in modal contexts.
• Track navigation flows.

Event payload

{
  url: string;
}

The payload contains a url property indicating the suggested redirect destination.

Example

import { events } from '@dropins/tools/event-bus.js';

events.on('requisitionList/redirect', (payload) => {
  const { url } = payload.data;

  console.log(`Redirect suggested to: ${url}`);

  // Option 1: Honor the redirect
  window.location.href = url;

  // Option 2: Use custom routing (e.g., SPA router)
  // router.push(url);

  // Option 3: Conditional redirect
  if (shouldAllowNavigation()) {
    window.location.href = url;
  } else {
    console.log('Navigation prevented');
  }
});

---

requisitionLists/data (emits and listens)

Triggered when data is available or changes. It emits and listens for updates to the collection of requisition lists.

When triggered

• After loading requisition lists
• After creating a new list
• After deleting a list
• After list collection changes
• On pagination or filtering

Usage scenarios

• Render lists grid or table.
• Update list count displays.
• Handle pagination.
• Show/hide empty states.
• Update filters and sorting.
• Cache lists data.

Event payload

RequisitionList[] | null

See RequisitionList for full type definition.

Example

import { events } from '@dropins/tools/event-bus.js';

events.on('requisitionLists/data', (payload) => {
  const { items, totalCount } = payload.data;

  console.log(`${totalCount} requisition lists loaded`);

  // Update lists display
  renderRequisitionLists(items);

  // Update pagination
  updatePagination({
    total: totalCount,
    current: payload.data.currentPage,
    pageSize: payload.data.pageSize
  });

  // Update empty state
  if (items.length === 0) {
    showEmptyState();
  } else {
    hideEmptyState();
  }
});

---

Listening to events

All Requisition List events are emitted through the centralized event bus:

import { events } from '@dropins/tools/event-bus.js';

// Listen to list data events
events.on('requisitionList/data', handleListUpdate);
events.on('requisitionLists/data', handleListsUpdate);

// Listen to UI events
events.on('requisitionList/alert', handleAlert);
events.on('requisitionList/redirect', handleRedirect);

// Listen to initialization
events.on('requisitionList/initialized', handleInit);

// Clean up listeners when done
events.off('requisitionList/data', handleListUpdate);
events.off('requisitionList/alert', handleAlert);

Event flow examples

The following examples demonstrate common event flow patterns when working with requisition lists.

Creating a new requisition list

When a user creates a new requisition list, the following events occur in sequence:

1. The requisitionList/alert event fires with a success notification
2. The requisitionLists/data event fires with the updated collection of lists

import { events } from '@dropins/tools/event-bus.js';
import { createRequisitionList } from '@dropins/storefront-requisition-list/api.js';

// Set up event listeners before creating the list
events.on('requisitionList/alert', (payload) => {
  const { type, message } = payload.data;
  console.log(`Alert: ${type} - ${message}`);
  showNotification(type, message);
});

events.on('requisitionLists/data', (payload) => {
  const lists = payload.data;
  console.log(`Lists updated: ${lists.length} total lists`);
  renderListsGrid(lists);
});

// Create the list
async function handleCreateList(name, description) {
  try {
    await createRequisitionList({ name, description });
    // Events will fire automatically after successful creation:
    // 1. requisitionList/alert (success notification)
    // 2. requisitionLists/data (updated lists collection)
  } catch (error) {
    console.error('Failed to create list:', error);
  }
}

Adding items to cart from a list

When adding all items from a requisition list to the cart, multiple events fire in sequence:

1. The requisitionList/alert event fires with a success notification
2. The requisitionList/redirect event fires suggesting navigation to the cart
3. The cart/updated event fires from the Cart drop-in (if integrated)

import { events } from '@dropins/tools/event-bus.js';
import { addRequisitionListItemsToCart } from '@dropins/storefront-requisition-list/api.js';

// Set up event listeners
events.on('requisitionList/alert', (payload) => {
  const { type, message } = payload.data;
  showNotification(type, message);
});

events.on('requisitionList/redirect', (payload) => {
  const { url } = payload.data;
  console.log(`Redirect suggested to: ${url}`);

  // Honor the redirect after a short delay
  setTimeout(() => {
    window.location.href = url;
  }, 1500);
});

events.on('cart/updated', (payload) => {
  const cart = payload.data;
  console.log(`Cart updated: ${cart.items.length} items`);
  updateCartBadge(cart.items.length);
});

// Add all items from list to cart
async function handleAddAllToCart(listUid, items) {
  try {
    await addRequisitionListItemsToCart({
      requisitionListUid: listUid,
      requisitionListItems: items.map(item => ({
        uid: item.uid,
        quantity: item.quantity
      }))
    });
    // Events will fire automatically after successful addition:
    // 1. requisitionList/alert (success notification)
    // 2. requisitionList/redirect (suggested navigation to /cart)
    // 3. cart/updated (if Cart drop-in is integrated)
  } catch (error) {
    console.error('Failed to add items to cart:', error);
  }
}

Data models

The following data models are used in event payloads for this drop-in.

RequisitionList

Used in: requisitionList/data, requisitionLists/data.

interface RequisitionList {
  uid: string;
  name: string;
  description: string;
  updated_at: string;
  items_count: number;
  items: Item[];
  page_info?: PageInfo;
}

RequisitionListActionPayload

Used in: requisitionList/alert.

interface RequisitionListActionPayload {
    action: 'add' | 'delete' | 'update' | 'move';
    type: 'success' | 'error';
    context: 'product' | 'requisitionList';
    skus?: string[]; // for product-related actions
    message?: string[]; // for uncontrolled/custom messages
  }