1. OPTIS Product Options, Variant
2. Advanced Setup

OPTIS Product Options - Developer Integration Guide

Overview

The OPTIS Product Options app exposes a global JavaScript object BSS_PO.currentSelectedOptions that contains real-time information about customer-selected product options, including prices, validation status, quantities, and detailed breakdowns. This guide explains how third-party developers can integrate with and read data from our app.

Data Structure

BSS_PO.currentSelectedOptions

The main data object contains the following structure:

BSS_PO.currentSelectedOptions = {
  byOptionId: {},              // Options indexed by option ID  byLabel: {},                 // Options indexed by label name  byOptionSetId: {},           // Options grouped by option set ID  allValues: [],               // Flat array of all selected options  quantities: {},              // NEW: Quantity data for each option value  totalPriceAddOn: 0,          // Total price add-on from all options  totalVariantPriceAddOn: 0,   // Total variant-based price add-on  variantPriceAddOn: [],       // Array of variant price add-ons  priceBreakdown: {},          // Detailed price breakdown by option  validation: {                // Validation status for required options    isValid: true,    requiredOptions: [],    missingOptions: [],    validOptions: [],    errors: []  },  timestamp: "2023-..."        // Last update timestamp
}

NEW: Quantity Data Structure

The quantities object stores quantity information for each option value:

Enhanced Option Value Structure

Each option value now includes quantity and pricing information:

API Methods

We provide a comprehensive API through BSS_PO.getSelectedOptions for easy data access:

Basic Data Access

Get All Selected Options

Get Options by Label

Check Option Selection

NEW: Quantity Methods

Get Quantity Information

Enhanced Price Information

Get Price Data with Quantity

Get Comprehensive Price Summary with Quantities

Validation

Check Validation Status

Get Validation Errors

Enhanced Formatted Output

Get Formatted Strings with Quantities

NEW: Complete API Methods for Quantity Support

Here are the additional methods added to support quantity functionality:

Event System

Listen for Option Changes with Quantity Information

Cart Page Integration

Detecting Option Changes on Cart Page

On the cart page, customers can edit their product options and quantities. To detect these changes:

Enhanced Cart Data Structure

Cart items now include quantity information for options:

Practical Examples

Example 1: Quantity-Aware Price Calculator

Example 2: Inventory Management Integration

Example 3: Dynamic Pricing Based on Quantity

Troubleshooting

Common Issues

1. BSS_PO is undefined: The app hasn't loaded yet. Make sure OPTIS is installed and enabled in the theme app extension.
2. Quantity data is missing: Ensure you're using the updated version of OPTIS that supports quantity tracking. Check that quantity inputs are properly configured for your option types.
3. Price calculations seem incorrect: Remember that prices in the API are already multiplied by quantities. Use unitPrice if you need the per-unit cost.
4. Quantity not updating: Quantity changes trigger the same events as other option changes. Listen for BSSOptionSelectionChanged events to detect quantity modifications.
5. Validation not working with quantities: Validation checks if options are selected, not their quantities. Implement custom quantity validation based on your business rules.
6. Cart quantities vs option quantities: Cart line item quantity is different from individual option quantities. A single cart item can have multiple option values with different quantities each.

Best Practices

1. Always check for quantity data: Not all option types support quantities. Default to 1 if quantity data is unavailable.
2. Use unit prices for custom calculations: When implementing custom pricing logic, use unitPrice and multiply by quantity yourself.
3. Listen to events for real-time updates: Don't poll for changes; use the provided event system for better performance.
4. Cache expensive calculations: If you're doing complex quantity-based calculations, cache results and only recalculate when the BSSOptionSelectionChanged event fires.
5. Validate quantities in your code: Implement business logic to ensure quantities make sense for your use case (minimum/maximum quantities, inventory checks, etc.)

Updated on: 24/09/2026