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.
- Bold Subscriptions comes with standard widgets that are automatically installed. You can customize these with CSS styling.
- This page only covers widgets on shops using Bold Checkout. For creating custom widgets using the Shopify checkout, refer to the following Shopify articles:
Prerequisites
Before you get started, complete the following steps:
- Install the Bold Subscriptions and Bold Checkout applications on your store.
- 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:
| Key | Type | Description |
|---|---|---|
subscription_group_id | Number | The subscription group ID, determined by the interval frequency selected by the customer. |
interval_id | Number | The interval/billing rule ID chosen by the customer. |
quantity | Number | The quantity chosen by the customer. |
interval_text | String | The human-readable text of the interval chosen by the customer (usable on cart pages). |
variant_id | Number | The variant ID chosen by the customer. |
The following keys are available only on the BigCommerce platform:
| Key | Type | Description |
|---|---|---|
variantId | Number | The variant ID corresponding to the customer's selections. |
v3VariantId | Number | The v3 variant ID corresponding to the customer's selections. |
optionSelections | Array | An array of option selections made by the customer. |
optionSelections.optionId | Number | The ID of the option selection. |
optionSelections.optionValue | Number | The value of the option selection. |
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:
| Key | Type | Description |
|---|---|---|
subscription_group_id | Number | The subscription group ID, determined by the interval frequency selected by the customer. |
interval_id | Number | The interval/billing rule ID chosen by the customer. |
interval_text | String | The human-readable text of the interval chosen by the customer. |
Inform Bold Checkout of subscription information
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:
| Key | Value |
|---|---|
pluginId | bold_subscriptions |
name | line_items_subscription_info |
value | See 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:
| Key | Type | Description |
|---|---|---|
line_item_id | Number | The line item ID assigned to each product in the cart by the platform. |
variant_id | Number | The variant ID chosen by the customer. |
quantity | Number | The quantity chosen by the customer. |
subscription_group_id | Number | The subscription group ID, determined by the interval frequency selected by the customer. |
interval_id | Number | The interval/billing rule ID chosen by the customer. |
interval_text | String | The human-readable text of the interval chosen by the customer (usable on cart pages). |
prepaid_selected | Boolean | Whether or not the customer choose to prepay for their subscription (also requires prepaid_duration_id). |
prepaid_duration_id | Number | Whether the prepaid duration chosen by the customer (also requires prepaid_selected). |