Skip to main content

Shopping cart integration guide

Let customers add their entire show to your site's cart in one step. When you pass an onAddToCart function to glow.createShowBuilder(), the Show Builder displays an Add Show to Cart button. When a customer clicks it, GLOW calls your function with the show's shopping list, and your code adds those items to your cart. GLOW never touches your cart directly, so this works with any cart system.

Troubleshooting

Something not working? Always check your browser's JavaScript console for informative error messages provided by GLOW.

Before you start​

Add the show to your cart​

Add an onAddToCart function to your existing glow.createShowBuilder() call. GLOW calls it with the shopping list and shows the customer a loading state until the promise your function returns settles. In this example, your backend maps the GLOW IDs to your products and updates the cart:

JavaScript
glow.createShowBuilder({
onAddToCart: async ({ items, mode }) => {
// TODO: Replace with a request to your own cart system.
const response = await fetch('/api/glow/add-to-cart', {
method: 'POST',
headers: { 'Content-Type': 'application/json' },
body: JSON.stringify({ items, mode })
});
if (!response.ok) {
throw new Error(`Cart update failed with status ${response.status}`);
}
}
});

Your function receives an object with two properties:

  • items is the show's shopping list. Each item has a brandId, a productId, and a quantity. Each product appears once, with the total quantity the show needs. An assortment appears as a single item with its own ID, not as the products inside it.
  • mode is either 'append' or 'replace'. The customer picks one in the Show Builder before adding the show. For 'append', keep the current cart contents and add the show's items. For 'replace', empty the cart first. Your code must handle both.
Example payload
{
mode: 'append',
items: [
{ brandId: '62', productId: 'BP2455', quantity: 1 },
{ brandId: '68', productId: 'RA54522', quantity: 1 },
{ brandId: '53', productId: 'P5586', quantity: 3 }
]
}

Map GLOW IDs to your products​

GLOW identifies each firework with a brand ID and a product ID, and provides these IDs for your catalog. Store both in your database alongside the matching product. When onAddToCart runs, look up each item by its brandId and productId, then add your product to the cart.

A product ID is only guaranteed to be unique within its brand, so the lookup needs both IDs.

If you already store these IDs for 3D previews and add-to-show buttons, use that same mapping. The Advanced integration guide explains how GLOW identifies products.

Report success or failure​

When the promise your function returns resolves, the Show Builder tells the customer that their cart has been updated and shows a link to your cart, so you don't need to redirect them yourself.

To report a failure, throw an error, or reject the promise. The Show Builder detects this, shows the customer a generic error message with a link to your cart, and lets them try again. Your error's message is not shown to the customer. Instead, GLOW logs it to the console and records it, so use an Error with a clear diagnostic message to help us troubleshoot issues with you.

There is no partial success. If you can add only some of the items, for example because some are out of stock, you can still report a success. To show the customer what will and won't be added before you update the cart, add your own confirmation step (see next section).

If your cart is slow to respond, the Show Builder keeps waiting. After a short wait, it tells the customer that this is taking longer than expected. After a couple of minutes, it stops waiting and asks the customer to check their cart before trying again.

Development and staging sites

By default, the Show Builder's cart links use the production cart URL GLOW has on file for your site. To point them at the cart on a development or staging site, you can pass cartUrlOverride:

JavaScript
glow.createShowBuilder({
onAddToCart: async ({ items, mode }) => {
// ...
},
cartUrlOverride: 'https://staging.your-domain.com/cart'
});

Add your own confirmation step​

Want to show the customer prices or items that are out of stock before the cart is updated? You can integrate your own UI to display information the Show Builder doesn't have. This is an optional enhancement.

Here is the flow from start to finish:

  1. The customer clicks "Add show to cart", and GLOW calls your onAddToCart function with the shopping list and a controller object.
  2. Your function calls controller.deferProcessing() and opens your popup. The Show Builder waits behind it with no time limit.
  3. If the customer confirms with your UI, your function calls controller.beginProcessing(), updates the cart, and the promise resolves. Throw an error, or reject the promise, if the update fails.
  4. If the customer closes the popup instead, your function resolves with { status: 'canceled' }. The Show Builder goes back to its add-to-cart dialog without showing an error.

The two controller calls tell GLOW when the real cart update starts. Without them, the Show Builder counts the time the customer spends in your popup as cart processing, and shows its "taking longer than expected" message behind your popup.

Here's a complete example:

JavaScript
glow.createShowBuilder({
onAddToCart: async ({ items, mode }, controller) => {
// The customer is still in your UI. The cart update has not started.
controller.deferProcessing();

// TODO: Replace with your own popup. It must resolve to true when the
// customer confirms, and to false on every other way of closing it.
const confirmed = await openCartReviewPopup(items);
if (!confirmed) {
return { status: 'canceled' };
}

// The cart update starts now.
controller.beginProcessing();
// TODO: Replace with a request to your own cart system.
const response = await fetch('/api/glow/add-to-cart', {
method: 'POST',
headers: { 'Content-Type': 'application/json' },
body: JSON.stringify({ items, mode })
});
if (!response.ok) {
throw new Error(`Cart update failed with status ${response.status}`);
}
}
});

Call controller.deferProcessing() at the top of your function, before you open your popup. Keep your function async, as in the example. GLOW reads { status: 'canceled' } only from a promise, and treats the same object returned without a promise as a success.

Settle the promise on every way out

While your function defers, the Show Builder waits with no time limit and the customer can't dismiss its dialog. If the returned promise never settles, the customer is stuck on a loading screen. Make sure every way of closing your popup settles the promise, including the confirm button, a cancel button, the close icon, the Escape key, and a click on the backdrop.

Show your popup above the Show Builder​

The Show Builder fills the page with a fixed-position iframe that uses the highest possible z-index, 2147483647. To show your popup on top of it, give your popup the same z-index, ensure it uses position: fixed, and append it to the end of <body> when you open it, so it comes after the Show Builder in the page.

Test your integration​

  • Add a show in 'append' mode and confirm that your existing cart items remain.
  • Add a show in 'replace' mode and confirm that your cart contains only the show's items.
  • Confirm that each product in the show, including any assortment, maps to the right product in your cart.
  • Make your cart update fail, and confirm that the Show Builder shows an error.
  • If you built a confirmation step, close your popup in every possible way, and confirm that the Show Builder returns to its add-to-cart dialog each time.

Troubleshooting​

  • Error messages: GLOW provides clear, actionable error messages in the browser console – always check there first.

  • Your popup doesn't appear? It's probably behind the Show Builder. See Show your popup above the Show Builder above.

  • Customer stuck on a loading screen? Your function deferred, and the promise never settled. Every way of closing your popup must resolve or reject the promise. If the customer backed out, resolve with { status: 'canceled' }.