Skip to main content

Build Custom Widgets

Building a custom widget allows you to take control of your customer's subscription checkout experience. Build a dedicated landing page for your product, make a custom widget on your product page, or change the way discounts are displayed on your cart page.

You can create custom widgets on your store using either Bold Subscriptions JavaScript or the Bold Subscriptions API endpoints.

Use the steps on this page to create a custom widget from scratch using JavaScript.

note

Prerequisites

  1. Install the Bold Subscriptions and Bold Checkout applications on your store.
  2. Complete the Getting Started with the Bold Subscriptions API guide, including installing storefront JavaScript.

Disable the out-of-the-box widget

Widgets are automatically added to addToCart forms based on the CSS selectors in the window.BOLD.subscriptions.config.addToCartFormSelectors array. You can overwrite this value in your theme files. If there are no selectors in that array, the widget will not be added to the addToCart forms.

To disable the widget in an addToCart form, add the class bold-subscriptions-no-widget to the form.

Retrieve subscription group data

A helper method window.BOLD.subscriptions.getSubscriptionGroupFromProductId(productId) is available to retrieve the subscription group for your product ID. Since this method will only ever return one subscription group, if you have chosen to put your product in multiple subscription groups you can retrieve your subscription group data directly from the window.BOLD.subscriptions.data.subscriptionGroups array.

Display the widget to customers

Once you retrieve the proper subscription group information, you can display the choices to your customers however you see fit. Use keys from the subscription group like is_subscription_only, is_prepaid_only, and can_add_to_cart to inform your widget what to render. The information for the intervals configured in your subscription group is found inside the billing_rules array. See the SubscriptionGroup schema in the API specifications for the full object definition.

Inform Bold Subscriptions of add to carts

When a customer adds a subscription product to their cart, you must inform Bold Subscriptions of what was chosen using the window.BOLD.subscriptions.app.addPendingAddToCart(addToCartData) method. The addToCartData parameter is a JavaScript object with the following keys:

KeyTypeDescription
subscription_group_idNumberThe subscription group ID, determined by the interval frequency selected by the customer.
interval_idNumberThe interval/billing rule ID chosen by the customer.
quantityNumberThe quantity chosen by the customer.
interval_textStringThe human-readable text of the interval chosen by the customer (usable on cart pages).
variant_idNumberThe variant ID chosen by the customer.

The following keys are available only on the BigCommerce platform:

KeyTypeDescription
variantIdNumberThe variant ID corresponding to the customer's selections.
v3VariantIdNumberThe v3 variant ID corresponding to the customer's selections.
optionSelectionsArrayAn array of option selections made by the customer.
optionSelections.optionIdNumberThe ID of the option selection.
optionSelections.optionValueNumberThe value of the option selection.
note

On BigCommerce, using the variantId or v3VariantId is preferred. If you use optionSelections, the variant ID is automatically looked up on next page load. Use the following function to manually trigger this lookup if you plan to send customers to checkout before the next page load:

async window.BOLD.subscriptions.app.platformWidgetAdapter.resolvePendingAddToCartsVariantIds

If the variantId or v3VariantId are not present when checking out, the line item is not correctly identified as a subscription in the checkout page and no subscription is created.

Display subscription information in the cart

Once a subscription line item is added to the cart, the Bold Subscriptions JavaScript stores information about the customer's selections and how each maps to the line items.

Use the window.BOLD.subscriptions.app.successfulAddToCarts array to look up each line item by its ID and get the subscription information for that line item. The entries in this array are JavaScript objects with the following keys:

KeyTypeDescription
subscription_group_idNumberThe subscription group ID, determined by the interval frequency selected by the customer.
interval_idNumberThe interval/billing rule ID chosen by the customer.
interval_textStringThe human-readable text of the interval chosen by the customer.

Inform Bold Checkout of subscription information

note

This step is only required if you chose not to load the Bold Subscriptions JavaScript on your storefront.

After modifying the cart with a subscription product, you must sync the data for the Bold Checkout app. The following functions are available to keep the subscription data in sync:

window.BOLD.addCartParam(pluginId, name, value);
window.BOLD.deleteCartParam(pluginId, name);
window.BOLD.getCartParams(pluginId);

Use the following values to sync data for Bold Subscriptions:

KeyValue
pluginIdbold_subscriptions
nameline_items_subscription_info
valueSee table below

The value of the cart parameter is an array of objects that represents subscription products in the cart. These JavaScript objects have the following keys:

KeyTypeDescription
line_item_idNumberThe line item ID assigned to each product in the cart by the platform.
variant_idNumberThe variant ID chosen by the customer.
quantityNumberThe quantity chosen by the customer.
subscription_group_idNumberThe subscription group ID, determined by the interval frequency selected by the customer.
interval_idNumberThe interval/billing rule ID chosen by the customer.
interval_textStringThe human-readable text of the interval chosen by the customer (usable on cart pages).
prepaid_selectedBooleanWhether or not the customer choose to prepay for their subscription (also requires prepaid_duration_id).
prepaid_duration_idNumberWhether the prepaid duration chosen by the customer (also requires prepaid_selected).