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:
- Install the Bold Subscriptions and Bold Checkout apps on your store.
- 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
, theline_item_id
value is theline_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.