Product Details Data & Events

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

Events reference

Event	Direction	Description
pdp/valid	Emits	Emitted when validation state changes.
pdp/setValues	Listens	Fired by PDP (pdp) when values are set programmatically.
pdp/data	Emits and listens	Triggered when data is available or changes.
pdp/values	Emits and listens	Triggered when form or configuration values change.

Event details

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

pdp/data (emits and listens)

Triggered when data is available or changes.

Event payload

ProductModel | null

See ProductModel for full type definition.

Example

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

events.on('pdp/data', (payload) => {
  console.log('pdp/data event received:', payload);
  // Add your custom logic here
});

pdp/setValues (listens)

Fired by PDP (pdp) when values are set programmatically.

Event payload

Example

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

events.on('pdp/setValues', (payload) => {
  console.log('pdp/setValues event received:', payload);
  // Add your custom logic here
});

pdp/valid (emits)

Emitted when validation state changes.

Event payload

boolean

Example

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

events.on('pdp/valid', (payload) => {
  console.log('pdp/valid event received:', payload);
  // Add your custom logic here
});

pdp/values (emits and listens)

Triggered when form or configuration values change.

Event payload

ValuesModel

See ValuesModel for full type definition.

Example

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

events.on('pdp/values', (payload) => {
  console.log('pdp/values event received:', payload);
  // Add your custom logic here
});

Data Models

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

ProductModel

Used in: pdp/data.

interface ProductModel {
  name: string;
  sku: string;
  isBundle: boolean;
  addToCartAllowed: boolean;
  inStock: boolean | null;
  shortDescription?: string;
  metaDescription?: string;
  metaKeyword?: string;
  metaTitle?: string;
  description?: string;
  images?: Image[];
  prices: Prices;
  attributes?: Attribute[];
  options?: Option[];
  optionUIDs?: string[];
  url?: string;
  urlKey?: string;
  externalId?: string;
  externalParentId?: string;
  variantSku?: string;
  productType?: ProductType | undefined;
}

Attribute

Used in: ProductModel.attributes.

interface Attribute {
  id: string;
  label: string;
  value: string;
  roles?: string[];
}

value is a JSON string or, for some attributes, an already-parsed object. Its shape depends on the attribute’s id. Attributes whose id starts with ac_, such as ac_giftcard, ac_downloadable, and ac_customizable_options, contain attribute-specific JSON payloads.

ac_customizable_options

This attribute contains Magento Customizable Options attached to a product. These include priced selectable choices (dropdown menus, radio buttons, checkboxes, and multi-select options) and shopper-input fields (text, multiline text, date, date/time, and time):

{
  "schemaVersion": 1,
  "selectable": [
    {
      "id": "1",
      "label": "Add Pressure Gauges?",
      "renderType": "drop_down",
      "type": "custom_option",
      "required": "1",
      "sortOrder": "1",
      "values": [
        {
          "id": "Y3VzdG9tLW9wdGlvbi8xLzE=",
          "label": "No Thanks",
          "price": "0.000000",
          "priceType": "fixed",
          "sku": "PG-NO",
          "sortOrder": "1",
          "isDefault": false
        },
        {
          "id": "Y3VzdG9tLW9wdGlvbi8xLzI=",
          "label": "Yes - 3 x GT16-3S",
          "price": "108.000000",
          "priceType": "fixed",
          "sku": "PG-YES",
          "sortOrder": "2",
          "isDefault": false
        }
      ]
    }
  ],
  "shopperInput": [
    {
      "id": "Y3VzdG9tLW9wdGlvbi8y",
      "label": "Engraving text",
      "renderType": "field",
      "required": "0",
      "price": "15.000000",
      "sku": "ENGRAVE",
      "sortOrder": "2",
      "range": { "to": "30" },
      "productSku": "TEST-CUSTOPT-SIMPLE"
    }
  ]
}

• The example shows a parsed Catalog Service payload before prices are converted to numbers. The typed PDP accessor converts price fields from numeric strings (for example, "108.000000") to numbers for rendering. If you read the raw attribute yourself, parse its JSON and convert prices before calculations or formatting.
• schemaVersion identifies the attribute payload format. The selectable array contains predefined choices, and shopperInput contains fields for shopper-entered values.
• required is a string flag, not a boolean. A value of "1" or "true" marks a required option. The sortOrder field defines the display order.
• selectable[].values[].id and shopperInput[].id are base64-encoded custom-option/<optionId>[/<valueId>] tokens. The cart drop-in’s addProductsToCart expects these tokens in optionsUIDs for selectable choices and enteredOptions for shopper-input values. No mapping step is required before adding the product to the cart.
• A product with no customizable options has no ac_customizable_options entry in attributes.

Note

The ProductCustomizableOptions container renders selectable choices and field, area, date, date_time, and time shopper-input fields. Shopper inputs update enteredOptions with the encoded option UID and string value. Clearing a field removes its entry. File options appear disabled. The container does not enforce required options or update the displayed product total when options change. See Render customizable options for customization steps.

ValuesModel

Used in: pdp/values.

interface ValuesModel {
  sku: string;
  quantity: number;
  optionsUIDs?: string[];
  enteredOptions?: Array<{ uid: string; value: string }>;
}

For customizable options, optionsUIDs contains encoded selectable-value UIDs, and enteredOptions contains encoded shopper-input option UIDs with string values. Text is preserved, including whitespace and line breaks. Date and time inputs use the cart-compatible formats produced by the container.