> ## Knowledge Base Index
> Fetch the complete knowledge base index at: https://help.optis.me/sitemap.xml
> Use this file to discover available pages before exploring further.
> Pure-Markdown content can be obtained by appending a '.md' suffix to the content URLs listed in the sitemap (without the trailing slash).

# OPTIS Product Options - Developer Integration Guide

1. [OPTIS Product Options, Variant](/product-options)
2. [Advanced Setup](/product-options/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.)