Headless Storefront Setup

This guide outlines how to integrate Bold Subscriptions with an existing headless Bold Checkout store. Setting up Bold Subscriptions on a store with a self-hosted checkout flow instead of the out-of-the-box Checkout requires a few additional steps.

Prerequisites

Before you get started, complete the following steps:

1. Install the Bold Subscriptions and Bold Checkout apps on your store.
2. Create your own checkout flow using the instructions outlined in the Create a Self-Hosted Checkout Flow.

Display the option to subscribe

There are various methods to present subscription products to your shoppers. You can use the out-of-the-box Bold Subscriptions widget, or you can create your own widget.

In either scenario, begin by retrieving all subscription groups. The following code snippet shows an example of this call:

curl --request GET 'https://sub.boldapps.net/api/storefront/subscription_groups?shop={shop_domain}'

Once you retrieve the list of subscription groups, you can display the subscription choices to your customers however you see fit. Each subscription group has a list of selection_options that contains products in that group. 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 billing_rules array contains information about the intervals configured in your subscription group.

See the SubscriptionGroup resource in the Subscriptions API specification for the full object definition. For more information about widgets, refer to Build Custom Widgets.

Inform Bold Checkout of subscription data

In order to indicate which products in an order are subscriptions, you must attach additional data to the Bold Checkout order. Add this data as cart parameters, which appear in the nested order_meta_data object of the application_state.

You can add cart parameters in one of two ways, based on how you populate a Bold Checkout order:

• Using the Initialize an Order endpoint.
• Using the Append Order Metadata endpoint.

In either of these scenarios, you must add an object within the existing cart_parameters object called bold_subscriptions. This object contains an array with the key line_items_subscriptions_info. The values in line_items_subscriptions_info identify each of the products in the order that is a subscription.

Required Bold Subscriptions data

The bold_subscriptions cart parameter contains an array called line_items_subscription_info. Each item in this array is an object with the following keys:

Key	Type	Description
subscription_group_id	number	ID of the subscription group that the product belongs to.
interval_id	number	ID of the selected billing rule.
interval_text	string	Name of the selected billing rule.
line_item_id	string	Line item ID that associates this line_items_subscriptions_info object with the line item in the Bold Checkout order.
quantity	number	Quantity of the subscription product that exist in the cart.
variant_id	string	Product ID of the subscription product. If the product has variants, then this value is the variant ID that was added to cart.

The line_item_id value can be generated two ways, depending on how you initialized your Bold Checkout order:

• If you provided a cart ID, the line_item_id value is the ID of the cart item in your commerce platform.
• If you provided an array of cart_items, the line_item_id value is the line_item_key that you provided for each line item.

Example cart_parameters

The following snippet shows an example of the order_meta_data for an order that contains one subscription product:

{
  order_meta_data: {
    cart_parameters: {
      bold_subscriptions: {
        line_items_subscription_info: [
          {
            subscription_group_id: 1,
            interval_id: 1,
            interval_text: "Monthly",
            line_item_id: "abc-01",
            quantity: 1,
            variant_id: "xyz-01",
          },
        ];
      }
    }
  }
}

You can test whether the cart parameters have been properly added at any time using the Get Application State endpoint.

If you do not properly add the Bold Subscriptions cart parameters to the order, it is processed as a one-time order, and no recurring orders will be generated.