How It Works

Understanding how the app works can help you configure it correctly and troubleshoot when something doesn’t look right on the storefront.

You don’t need to know these technical details to use the app. This page is for merchants who want to understand what’s happening under the hood — useful if you’re troubleshooting a sync issue or trying to understand how options appear on your orders.

From your settings to your customer’s order

1. You configure options in the dashboard — labels, values, pricing, and logic.
2. When you apply an Option Set to a product, the app automatically sets up the matching records in BigCommerce (you’ll see a “Synced” status when it’s done).
3. When a customer visits the product page, the app displays your options using its own options widget (the panel of options that appears on your product page).
4. When the customer clicks Add to Cart, their choices are submitted to BigCommerce in exactly the same format as native BigCommerce options — the cart, checkout, and orders all work normally.

The three-layer stack

Layer 1 — Option Set & Elements

Everything you configure in the dashboard lives in this app’s own database. An Option Set is a container. Inside it, Elements are the individual fields (text inputs, dropdowns, etc.). Element Values are the choices within a selection-type element.

None of this is stored in BigCommerce yet — it’s all in the app.

Layer 2 — BigCommerce setup

When you apply an Option Set to a product, the app sets up the corresponding records in BigCommerce on that product for each element that needs to carry a value through the cart.

• A Text Input element → a text-type record in BigCommerce
• A Dropdown element → a dropdown-type record with one option per value
• A File Upload element → a file-type record

Some element types (Heading, Paragraph, Divider, Raw HTML, Tab, Accordion, Option Group) are display-only and don’t record any value on the order — setup skips them.

You can see each element’s assigned ID in the dashboard next to the element. If it shows no ID shown, setup is either still running or failed.

Layer 3 — Storefront rendering

The app uses a standard BigCommerce feature to place the options widget on your product pages. When a customer visits a product page, the widget:

1. Fetches the Option Set data for this product from the app
2. Hides the natively-rendered BigCommerce form fields (to avoid showing them twice)
3. Renders the app’s own options widget with the full configured set of elements
4. On “Add to Cart”, the customer’s choices are submitted to BigCommerce normally — exactly what BigCommerce’s own cart handler expects

This means the cart, checkout, and order all work natively through BigCommerce. The app only controls the product-page UI and the configuration experience.

Applying an Option Set to products

An Option Set can be applied three ways:

When the application is saved, the setup process runs in the background. It creates the necessary records in BigCommerce. Until it completes, the status shows as Pending. On success it becomes Synced; on failure, Failed with an error message.

Why two names? (Label vs. Internal name)

Each element has:

• Label — shown to the customer on the product page and carried through to the order
• Internal name — The internal name is only visible to you in the dashboard.

If you need a shorter or different name in the order than what’s displayed on the storefront, the cleanest approach is to use the Label for the storefront display and note the mismatch — this is a current limitation.

What happens when you re-apply

If you change an element (e.g., add a new dropdown value) and click “Re-apply”, the app:

1. Removes all the old records it created in BigCommerce on that product
2. Creates new ones from the updated configuration
3. Rolls back the new ones if any step fails, so the product is never left half-configured

After re-applying, any existing orders are unaffected. New visits to the product page use the updated options.