Skip to main content

Bold Subscriptions V1 Storefront

caution
  • The documentation found on this page applies only to Bold Subscriptions V1. If you are looking for Bold Subscriptions V2 documentation, visit the Bold Subscriptions V2 section.
  • All new installations of the app are Bold Subscriptions V2 — you can see which version you have installed by visiting the app admin. To learn more about the feature differences between Bold Subscriptions V1 and V2, refer to the Help Center.

Introduction​

This documentation is intended to walk you through the steps in developing a custom subscription flow for your Bold Subscriptions customers to interact with.

We recommend reading through all of the sections before Custom Subscription Flow in order to gain an understanding of how Bold Subscriptions works by default, which subscription type(s) will work best for you and any important restrictions to be aware of.

Definitions​

TermDescription
Subscription groupSubscription groups are created in the Bold Subscriptions admin and define which type of subscription is available for which products / variants.
Group IDUnique ID for a subscription group. Never changes unless the subscription group is deleted.
WidgetRefers to a form on a Shopify storefront that allows the customer to choose the type of subscription for a product, and add that product to their cart or go directly to checkout.

Prerequisites​

  • You have set up a subscription group in Bold Subscriptions for the product or variants you wish to offer on subscription.
  • Familiarity with the chrome/firefox dev tools, mainly the network tab.
  • Basic liquid understanding.
  • Intermediate Javascript, HTML, CSS knowledge.
  • Have a theme you can reference with the original subscription widget loaded. At any point you can also view the Bold Subscriptions and Cashier demo store: http://bold-subscriptions-cashier.myshopify.com

Default Behavior​

To better understand how to build a custom subscription flow you should be familiar with how Bold Subscriptions works by default on a storefront.

Subscription Group Metafields​

Subscription groups are set up in the Bold Subscriptions admin and allow you to define a subscription and which products should have that subscription available on it. At the moment you save your subscription group in the admin we will add a metafield to each of the variants you selected that is the subscription group ID.

Learn about Shopify product and variant metafields

Since we add metafields on the variant level, a single product can technically belong to multiple subscription groups if that fits the use case. The metafield we add is bold_rp.rp_group_id and is an integer value.

Liquid Installation​

bold-common.liquid​

As part of the installation for Bold Subscriptions we install bold-common.liquid into the <head> of the document which includes a script tag for https://ro.boldapps.net/v2_ui/js/ro.js . You can reach out to support@boldcommerce.com if you have not had the liquid installation done yet.

In addition to our JS asset bold common will also take the responsibility to use a combination of liquid and Javascript to populate the window variable window.BOLD.common.Shopify.products and window.BOLD.common.Shopify.variants with the metafields of the products on the page.

When we load the subscription widget​

The javascript loaded from bold-common.liquid will then look for product forms on the current page and which variant is currently selected by the customer. We will check if that variant ID is tied to a subscription group and then build a widget based on the group.

Checkout Buttons​

When a variant has been added to the cart with subscription properties tied to it (which come from the subscription widget) we need to ensure the customer goes through Bold’s checkout instead of Shopify. To achieve this we use Javascript to identify checkout buttons on the page using various selectors, and we attach event listeners to those buttons. When the customer clicks on a checkout button we do a quick look at the current Shopify cart and if we find a subscription in the cart we will direct to either the Bold Subscriptions checkout or the Cashier checkout if you’ve integrated Cashier.

Learn about integrating Bold Cashier for your subscriptions

Subscription Types​

Below you will find a description of each type of subscription in Bold Subscriptions. Understanding the difference between each will help you become familiar with form data you need to submit. Multiple types of subscriptions could also exist in the same widget.

Standard​

Can they be added to the cart and be purchased alongside other products?
> YES

Can they go directly to checkout and skip the cart?
> YES

Standard subscriptions are the most popular subscriptions we encounter, also the simplest to set up. They are subscriptions that simply recur over and over until the customers or store owner wishes to cancel the subscription. E.g. A monthly subscription, a semi-monthly subscription, a quarterly subscription, etc.

Limited Length​

Can they be added to the cart and be purchased alongside other products?
> YES

Can they go directly to checkout and skip the cart?
> YES

Limited length subscriptions are the exact same as a standard subscription with the only difference being that the subscription will automatically get cancelled after X number of orders process. E.g. A monthly subscription that automatically expires (cancels) after 6 orders.

Prepaid​

Can they be added to the cart and be purchased alongside other products?
> NO

Can they go directly to checkout and skip the cart?
> YES

Prepaid subscriptions are special, but similar to limited length subscriptions. A prepaid subscription is when the customer pays for X number of orders upfront. The initial order price will be the price of a single order times the number of orders to prepay for. If the customer prepays for 6 orders they will be charged on the first order and the next 5 orders will be $0.00 but still generate in Shopify on the appropriate dates. When setting up the subscription group settings you can decide if the customer’s subscription should expire or renew for another 6 orders in the end. You can also give the customer the option to choose this when setting up the group.

Build-a-Box​

Can they be added to the cart and be purchased alongside other products?
> NO

Can they go directly to checkout and skip the cart?
> YES

Build-a-Box is a unique type of subscription that is only fitting for some businesses, most commonly meal plan businesses. It’s important to know Build-a-Box does not extend from any other type of subscription and behaves quite differently. With this subscription type customers are subscribing to a box of various products with quantities for each of their choosing. Imagine a meal plan box that allows the customer to select 10 meals from a list, and any quantity of each that they want (up to 10 selections in total); Then get those meals on a recurring basis, with the ability to change their selections as they wish or as the business offers new selections and removes old ones.

Convertible​

Can they be added to the cart and be purchased alongside other products?
> YES

Can they go directly to checkout and skip the cart?
> YES

Convertible subscriptions are generally used by shops that offer a base product on the first order, followed by a recurring subscription product on subsequent orders. For example, selling an oil diffuser with one sample oil on the first order, and then having the customer automatically subscribed to a monthly oil subscription product on subsequent orders. Convertible subscriptions can only be in the form of a Standard or Limited Length Subscription (see above).The only factor that makes it convertible is the group_id POST data.

Product Form Creation​

To build a custom subscription flow you will likely want to start by building a product form. There is a good tutorial on this written by Shopify below.

Shopify Tutorial: The product.liquid template

BoldSubscriptions.js​

This is the API reference for BoldSubscriptions.js. Use these Javascript APIs to easily build custom subscription flows, add subscriptions to the cart and navigate to the Bold Subscriptions or Cashier checkout. The available methods are a fast alternative to and largely based off of the Custom Subscription Flow and Widget API documentation. Included with these API methods are detailed exceptions and error messages to help you quickly and reliably develop custom subscription flows.

Installing​

BoldSubscriptions.js can be included in your application in various ways depending on how you are working with it. Whether that be including a CDN script in the document or importing directly from our npm package.

Using npm​

```shell $ npm install @boldcommerce/bold-subscriptions-js ```

Using yarn​

```shell $ yarn add @boldcommerce/bold-subscriptions-js ```

Using CDN​

```html```

Usage​

Example Node.js usage​

import { cart } from "@boldcommerce/bold-subscriptions-js";
cart.standard
  .addToCart({
    id: 1250183643165,
    properties: {
      group_id: 1234,
      frequency_num: 1,
      frequency_type: 3,
      frequency_type_text: "Month(s)",
    },
  })
  .then(() => alert("Successfully added!"));

Example CDN usage​

<form>
  <input type="hidden" name="group_id" value="1234" />
  <input type="hidden" name="frequency_num" value="1" />
  <input type="hidden" name="frequency_type" value="3" />
  <input type="hidden" name="frequency_type_text" value="Month(s)" />
  <input type="hidden" name="quantities[]" value="1" />
  <input type="hidden" name="variant_id[]" value="1250183643165" />
  <input type="hidden" name="product_id[]" value="103180140573" />
  <button onclick="BoldSubscriptions.cart.standard.directlyToCheckout(event)">Checkout</button>
</form>

Example error message​

Invalid method arguments will result in errors thrown like the below example.

import { cart } from "@boldcommerce/bold-subscriptions-js";
cart.standard.addToCart({
  id: 1250183643165,
  properties: {
    frequency_num: 1,
    frequency_type: 3,
    frequency_type_text: "Month(s)",
  },
});

Reference​

The widgetAPI object

* buildABox * getSlots* subscriptionGroups * getGroupInfo* translations * getTranslations

The cart object

* standard * addToCart* addToCartCashier* directlyToCheckout* directlyToCheckoutCashier* limitedLength * addToCart* addToCartCashier* directlyToCheckout* directlyToCheckoutCashier* prepaid * directlyToCheckout* directlyToCheckoutCashier* convertible * addToCart* addToCartCashier* directlyToCheckout* directlyToCheckoutCashier

The checkout object

* goToCheckout* goToCheckoutCashier* recurringCartCheckout* recurringCartCheckoutCashier

widgetAPI​

// Import
import { widgetAPI } from "@boldcommerce/bold-subscriptions-js";
// CDN
const widgetAPI = BoldSubscriptions.widgetAPI;
buildABox.getSlots(groupId, bid = null)​

Use buildABox.getSlots(...) to fetch slot data for a Build-a-Box subscription group.

See related documentation

This method returns a promise which resolves with a json response object.

subscriptionGroups.getGroupInfo(groupId)​

Use subscriptionGroups.getGroupInfo(...) to fetch subscription group data by its group ID.

See related documentation

This method returns a promise which resolves with a json response object.

translations.getTranslations()​

Use translations.getTranslations() to fetch translations that are entered in the Bold Subscriptions admin language settings.

See related documentation

This method returns a promise which resolves with a json response object.

cart​

// Import
import { cart } from "@boldcommerce/bold-subscriptions-js";
// CDN
const cart = BoldSubscriptions.cart;
standard.addToCart(options)​

Use standard.addToCart({...}) to asynchronously add a standard subscription product to the Shopify cart.

See related documentation for required options

This method returns a promise which resolves with a Response object.

standard.addToCartCashier(options)​

Use standard.addToCartCashier({...}) to asynchronously add a standard subscription product to the Shopify cart. Only use this method if you have Cashier integrated for your subscriptions.

See related documentation for required options

This method returns a promise which resolves with a Response object.

standard.directlyToCheckout(e)​

Use standard.directlyToCheckout(e) to proceed directly to the Bold Subscriptions checkout with a standard subscription. This method should be attached as a button click event within a form on the storefront.

See related documentation for required form data

Calling this method ultimately submits the form from the passed in event and proceeds to checkout.

standard.directlyToCheckoutCashier(e)​

Use standard.directlyToCheckout(e) to proceed directly to the Cashier checkout with a standard subscription. This method should be attached as a button click event within a form on the storefront. Only use this method if you have Cashier integrated for your subscriptions.

See related documentation for required form data

Calling this method ultimately submits the form from the passed in event and proceeds to the Cashier checkout.

limitedLength.addToCart(options)​

Use limitedLength.addToCart({...}) to asynchronously add a limited length subscription product to the Shopify cart.

See related documentation for required options

This method returns a promise which resolves with a Response object.

limitedLength.addToCartCashier(options)​

Use limitedLength.addToCartCashier({...}) to asynchronously add a limited length subscription product to the Shopify cart. Only use this method if you have Cashier integrated for your subscriptions.

See related documentation for required options

This method returns a promise which resolves with a Response object.

limitedLength.directlyToCheckout(e)​

Use limitedLength.directlyToCheckout(e) to proceed directly to the Bold Subscriptions checkout with a limited length subscription. This method should be attached as a button click event within a form on the storefront.

See related documentation for required form data

Calling this method ultimately submits the form from the passed in event and proceeds to checkout.

limitedLength.directlyToCheckoutCashier(e)​

Use limitedLength.directlyToCheckout(e) to proceed directly to the Cashier checkout with a limited length subscription. This method should be attached as a button click event within a form on the storefront. Only use this method if you have Cashier integrated for your subscriptions.

See related documentation for required form data

Calling this method ultimately submits the form from the passed in event and proceeds to the Cashier checkout.

prepaid.directlyToCheckout(e)​

Use prepaid.directlyToCheckout(e) to proceed directly to the Bold Subscriptions checkout with a prepaid subscription. This method should be attached as a button click event within a form on the storefront.

See related documentation for required form data

Calling this method ultimately submits the form from the passed in event and proceeds to checkout.

prepaid.directlyToCheckoutCashier(e)​

Use prepaid.directlyToCheckout(e) to proceed directly to the Cashier checkout with a prepaid subscription. This method should be attached as a button click event within a form on the storefront. Only use this method if you have Cashier integrated for your subscriptions.

See related documentation for required form data

Calling this method ultimately submits the form from the passed in event and proceeds to the Cashier checkout.

convertible.addToCart(options)​

Use convertible.addtoCart({...}) to asynchronously add a convertible subscription product to the Shopify cart.

See related documentation for required options

This method returns a promise which resolves with a Response object.

convertible.addToCartCashier(options)​

Use convertible.addToCartCashier({...}) to asynchronously add a convertible subscription product to the Shopify cart. Only use this method if you have Cashier integrated for your subscriptions.

See related documentation for required options

This method returns a promise which resolves with a Response object.

convertible.directlyToCheckout(e)​

Use convertible.directlyToCheckout(e) to proceed directly to the Bold Subscriptions checkout with a convertible subscription. This method should be attached as a button click event within a form on the storefront.

See related documentation for required form data

Calling this method ultimately submits the form from the passed in event and proceeds to checkout.

convertible.directlyToCheckoutCashier(e)​

Use convertible.directlyToCheckout(e) to proceed directly to the Cashier checkout with a convertible subscription. This method should be attached as a button click event within a form on the storefront. Only use this method if you have Cashier integrated for your subscriptions.

See related documentation for required form data

Calling this method ultimately submits the form from the passed in event and proceeds to the Cashier checkout.

checkout​

// Import
import { checkout } from "@boldcommerce/bold-subscriptions-js";
// CDN
const checkout = BoldSubscriptions.checkout;
checkout.goToCheckout(e)​
<form action="/cart" method="post">
  <button name="checkout" onclick="BoldSubscriptions.checkout.goToCheckout(event)"></button>
</form>

In Multiple Product Mode of the application, use checkout.goToCheckout(e) to proceed directly to the Bold Subscriptions checkout with the current cart of products. This method should be attached as a button click event within a form on the storefront. Only call this method if you know the current cart contains a subscription.

checkout.goToCheckoutCashier(e)​
<form action="/cart" method="post">
  <button name="checkout" onclick="BoldSubscriptions.checkout.goToCheckoutCashier(event)"></button>
</form>

In Multiple Product Mode of the application, use checkout.goToCheckoutCashier(e) to proceed directly to the Cashier checkout with the current cart of products. This method should be attached as a button click event within a form on the storefront. Only call this method if you have Cashier integrated for your subscriptions and know the current cart contains a subscription.

checkout.recurringCartCheckout(e)​
<form>
  <input type="hidden" name="frequency_num" value="1" />
  <input type="hidden" name="frequency_type" value="3" />
  <input type="hidden" name="frequency_type_text" value="Month(s)" />
  <button onclick="BoldSubscriptions.checkout.recurringCartCheckout(event)">Subscribe to Cart</button>
</form>

In Recurring Cart Mode of the application, use checkout.recurringCartCheckout(e) to proceed directly to the Bold Subscriptions checkout with the current cart of products. This method should be attached as a button click event within a form on the storefront and assumes products are already in the Shopify cart. Only call this method if the customer intends to subscribe to the entire cart of products. Find all of the required form data below.

Form DataDescription
frequency_numAny integer value to define the frequency of the subscription (paired with frequency_type).
frequency_type
  • 1 for days
  • 2 for weeks
  • 3 for months
  • 5 for years
frequency_type_textHuman readable string representing the frequency type of the subscription E.g. “Month(s)”.
billing_plan
(optional)		Only applicable to weekly billing plans (E.g. Every 2 weeks on Wednesday), representing the week day to use for the subscription. You can retrieve this ID through the frontend Widget API.
checkout.recurringCartCheckoutCashier(e)​
<form>
  <input type="hidden" name="frequency_num" value="1" />
  <input type="hidden" name="frequency_type" value="3" />
  <input type="hidden" name="frequency_type_text" value="Month(s)" />
  <button onclick="BoldSubscriptions.checkout.recurringCartCheckoutCashier(event)">Subscribe to Cart</button>
</form>

In Recurring Cart Mode of the application, use checkout.recurringCartCheckoutCashier(e) to proceed directly to the Cashier checkout with the current cart of products. This method should be attached as a button click event within a form on the storefront and assumes products are already in the Shopify cart. Only call this method if you have Cashier integrated for your subscriptions and the customer intends to subscribe to the entire cart of products. Find all of the required form data below.

Form DataDescription
frequency_numAny integer value to define the frequency of the subscription (paired with frequency_type).
frequency_type
  • 1 for days
  • 2 for weeks
  • 3 for months
  • 5 for years
frequency_type_textHuman readable string representing the frequency type of the subscription E.g. “Month(s)”.
billing_plan
(optional)		Only applicable to weekly billing plans (E.g. Every 2 weeks on Wednesday), representing the week day to use for the subscription. You can retrieve this ID through the frontend Widget API.

Custom Subscription Flow​

Looking to build a custom subscription flow for your customers? We highly recommended to install and use our BoldSubscriptions.js Javascript API which will take care of much of the careful work behind developing a solution. Feel free to reference all of the following documentation for required POST data and steps involved before adding to cart or submitting ot checkout.

Important Notes​

  • Even though you are building a custom subscription flow we recommend having the liquid installation for Bold Subscriptions completed on your theme either by your developer or by contacting our team. The javascript we install on the theme will take care of navigating to the appropriate checkout when you are using add to cart functionality. This works for both the Bold Subscriptions’s native checkout and the Cashier checkout. If you are solely operating on subscriptions through a custom widget that navigates directly to checkout then the liquid installation is not necessary.
  • When combining multiple types of subscriptions in the same page or widget, it’s important that when you submit to checkout you exclude any POST data you’re not using. For example, instead of submitting is_prepaid=”0” for a non-prepaid subscription, you should just not submit is_prepaid at all.
  • To prevent Bold Subscriptions from loading the default subscription widget into your form, you can add the class no_ro_widget to your form element.

Standard Subscription​

Add to Cart (No Cashier) - Standard​

POST https://your-store.myshopify.com/cart/add HTTP/1.1
Content-Type: application/json

{
    "id": 135792468,
    "properties": {
        "group_id": 1234,
        "frequency_num": 1,
        "frequency_type": 3,
        "frequency_type_text": "Month(s)"
    }
}
POST DataDescription
idThe Shopify variant ID the customer is subscribing to.
properties[group_id]The subscription group ID.
properties[frequency_num]Any integer value to define the frequency of the subscription (paired with frequency_type).
properties[frequency_type]
  • 1 for days
  • 2 for weeks
  • 3 for months
  • 5 for years
properties[frequency_type_text]Human readable string representing the frequency of the subscription E.g. “Month(s)”.
properties[_ro_billing_plan]
(optional)		Only applicable to weekly billing plans (E.g. Every 2 weeks on Wednesday), representing the week day to use for the subscription. You can retrieve this ID through the frontend Widget API.
properties[_ro_discount_percentage]
(optional)		Integer value of discount percentage. Only used for display purposes on Shopify cart pages.
properties[_ro_unformatted_price]
(optional)		Unformatted discounted price in integer form. Only used for display purposes on Shopify cart pages.
properties[discounted_price]
(optional)		Formatted price after discount is applied. Only used for display purposes on Shopify cart pages.
properties[_secondary_discount_percent]
(optional)		Integer value of the secondary discount value. Only used for display purposes on Shopify cart pages if the subscription group has a dynamic discount.
properties[_secondary_discount_required_orders]
(optional)		Number of orders until the secondary discount is applied. Only used for display purposes on Shopify cart pages if the subscription group has a dynamic discount.

Add to Cart (Cashier Integrated) - Standard​

POST https://your-store.myshopify.com/cart/add HTTP/1.1
Content-Type: application/json

{
    "id": 135792468,
    "properties": {
        "group_id": 1234,
        "frequency_num": 1,
        "frequency_type": 3,
        "frequency_type_text": "Month(s)"
    }
}
POST DataDescription
idThe Shopify variant ID the customer is subscribing to.
properties[group_id]The subscription group ID.
properties[frequency_num]Any integer value to define the frequency of the subscription (paired with frequency_type).
properties[frequency_type]
  • 1 for days
  • 2 for weeks
  • 3 for months
  • 5 for years
properties[frequency_type_text]Human readable string representing the frequency of the subscription E.g. “Month(s)”.
properties[_ro_billing_plan]
(optional)		Only applicable to weekly billing plans (E.g. Every 2 weeks on Wednesday), representing the week day to use for the subscription. You can retrieve this ID through the frontend Widget API.
properties[_ro_discount_percentage]
(optional)		Integer value of discount percentage. Only used for display purposes on Shopify cart pages.
properties[_ro_unformatted_price]
(optional)		Unformatted discounted price in integer form. Only used for display purposes on Shopify cart pages.
properties[discounted_price]
(optional)		Formatted price after discount is applied. Only used for display purposes on Shopify cart pages.
properties[_secondary_discount_percent]
(optional)		Integer value of the secondary discount value. Only used for display purposes on Shopify cart pages if the subscription group has a dynamic discount.
properties[_secondary_discount_required_orders]
(optional)		Number of orders until the secondary discount is applied. Only used for display purposes on Shopify cart pages if the subscription group has a dynamic discount.

Directly to Checkout (No Cashier) - Standard​

POST https://recurringcheckout.com/s/your-store/checkout/recurring_product?shop_url=your-store.myshopify.com HTTP/1.1
Content-Type: multipart/form-data

--------------------------x
Content-Disposition: form-data; name="group_id"
1234
--------------------------x
Content-Disposition: form-data; name="frequency_num"
1
--------------------------x
Content-Disposition: form-data; name="frequency_type"
3
--------------------------x
Content-Disposition: form-data; name="frequency_type_text"
Month(s)
--------------------------x
Content-Disposition: form-data; name="quantities[]"
1
--------------------------x
Content-Disposition: form-data; name="variant_id[]"
135792468
--------------------------x
Content-Disposition: form-data; name="product_id[]"
246813579
--------------------------x
POST DataDescription
group_idThe subscription group ID.
frequency_numAny integer value to define the frequency of the subscription (paired with frequency_type).
frequency_type
  • 1 for days
  • 2 for weeks
  • 3 for months
  • 5 for years
frequency_type_textHuman readable string representing the frequency of the subscription E.g. “Month(s)”.
quantities[]The quantity of the product the customer is subscribing to.
variant_id[]The Shopify variant ID the customer is subscribing to. This should be a single index array.
product_id[]The Shopify product ID the customer is subscribing to. This should be a single index array.
billing_plan
(optional)		Only applicable to weekly billing plans (E.g. Every 2 weeks on Wednesday), representing the week day to use for the subscription. You can retrieve this ID through the frontend Widget API.

Directly to Checkout (Cashier Integrated) - Standard​

To submit to Cashier’s checkout there is a unique set of steps listed below. Cashier relies on products being added to the cart before going directly to checkout, which is a bit different than how it works without Cashier.

Clear the cart - Standard​
POST https://your-store.myshopify.com/cart/clear HTTP/1.1

To start you should make a POST request (see fetch API) to /cart/clear.js to clear any existing products in the Shopify cart.

Add to cart - Standard​
POST https://your-store.myshopify.com/cart/add HTTP/1.1
Content-Type: application/json

{
    "id": 135792468,
    "properties": {
        "group_id": 1234,
        "frequency_num": 1,
        "frequency_type": 3,
        "frequency_type_text": "Month(s)",
        "_ro_single_product_recurring_item": true
    }
}

Next you should add the subscription product to the cart by making a request to /cart/add with all of the following POST data:

POST DataDescription
idThe Shopify variant ID the customer is subscribing to.
properties[group_id]The subscription group ID.
properties[frequency_num]Any integer value to define the frequency of the subscription (paired with frequency_type).
properties[frequency_type]
  • 1 for days
  • 2 for weeks
  • 3 for months
  • 5 for years
properties[frequency_type_text]Human readable string representing the frequency of the subscription E.g. “Month(s)”.
properties[_ro_single_product_recurring_item]Value should be true
properties[_ro_billing_plan]
(optional)		Only applicable to weekly billing plans (E.g. Every 2 weeks on Wednesday), representing the week day to use for the subscription. You can retrieve this ID through the frontend Widget API.
Fetch the latest cart ID - Standard​
GET https://your-store.myshopify.com/cart.json?ts=102359812 HTTP/1.1

Before you go to checkout you need to make one extra GET request to /cart.js?ts={current_unix_timestamp}. You should grab the entire JSON body of the response and store it into a variable using JSON.stringify(cart). The response of this request will also update your browser’s cookies with a new value for the cart cookie. Now that the cookie is updated, you should pull out the value of the cart cookie from document.cookie and then store that value in a variable. This value represents the cart ID.

Submit to the Cashier checkout - Standard​
POST https://your-store.myshopify.com/apps/checkout/begin-checkout?shop=your-store.myshopify.com HTTP/1.1
Content-Type: multipart/form-data

--------------------------x
Content-Disposition: form-data; name="cart_id"

f24e49648c2aa1c5054e712057c0ccc7
--------------------------x
Content-Disposition: form-data; name="cart"

{"token":"f24e49648c2aa1c5054e712057c0ccc7","note":null,"attributes":{},"original_total_price":0,"total_price":0,"total_discount":0,"total_weight":0,"item_count":0,"items":[],"requires_shipping":false,"currency":"CAD","items_subtotal_price":0,"cart_level_discount_applications":[]}
--------------------------x

Finally, you should submit a form on the page or one that you’ve created to the Cashier checkout.

Limited Length Subscription​

Add to Cart (No Cashier) - Limited Length​

POST https://your-store.myshopify.com/cart/add HTTP/1.1
Content-Type: application/json

{
    "id": 135792468,
    "properties": {
        "group_id": 1234,
        "frequency_num": 1,
        "frequency_type": 3,
        "frequency_type_text": "Month(s)",
        "total_recurrences": 6
    }
}
POST DataDescription
idThe Shopify variant ID the customer is subscribing to.
properties[group_id]The subscription group ID.
properties[frequency_num]Any integer value to define the frequency of the subscription (paired with frequency_type).
properties[frequency_type]
  • 1 for days
  • 2 for weeks
  • 3 for months
  • 5 for years
properties[frequency_type_text]Human readable string representing the frequency of the subscription E.g. “Month(s)”.
properties[total_recurrences]The number of orders that should process before the subscription automatically ends.
properties[_ro_billing_plan]
(optional)		Only applicable to weekly billing plans (E.g. Every 2 weeks on Wednesday), representing the week day to use for the subscription. You can retrieve this ID through the frontend Widget API.
properties[_ro_discount_percentage]
(optional)		Integer value of discount percentage. Only used for display purposes on Shopify cart pages.
properties[_ro_unformatted_price]
(optional)		Unformatted discounted price in integer form. Only used for display purposes on Shopify cart pages.
properties[discounted_price]
(optional)		Formatted price after discount is applied. Only used for display purposes on Shopify cart pages.
properties[_secondary_discount_percent]
(optional)		Integer value of the secondary discount value. Only used for display purposes on Shopify cart pages if the subscription group has a dynamic discount.
properties[_secondary_discount_required_orders]
(optional)		Number of orders until the secondary discount is applied. Only used for display purposes on Shopify cart pages if the subscription group has a dynamic discount.

Add to Cart (Cashier Integrated) - Limited Length​

POST https://your-store.myshopify.com/cart/add HTTP/1.1
Content-Type: application/json

{
    "id": 135792468,
    "properties": {
        "group_id": 1234,
        "frequency_num": 1,
        "frequency_type": 3,
        "frequency_type_text": "Month(s)",
        "total_recurrences": 6
    }
}
POST DataDescription
idThe Shopify variant ID the customer is subscribing to.
properties[group_id]The subscription group ID.
properties[frequency_num]Any integer value to define the frequency of the subscription (paired with frequency_type).
properties[frequency_type]
  • 1 for days
  • 2 for weeks
  • 3 for months
  • 5 for years
properties[frequency_type_text]Human readable string representing the frequency of the subscription E.g. “Month(s)”.
properties[total_recurrences]The number of orders that should process before the subscription automatically ends.
properties[_ro_billing_plan]
(optional)		Only applicable to weekly billing plans (E.g. Every 2 weeks on Wednesday), representing the week day to use for the subscription. You can retrieve this ID through the frontend Widget API.
properties[_ro_discount_percentage]
(optional)		Integer value of discount percentage. Only used for display purposes on Shopify cart pages.
properties[_ro_unformatted_price]
(optional)		Unformatted discounted price in integer form. Only used for display purposes on Shopify cart pages.
properties[discounted_price]
(optional)		Formatted price after discount is applied. Only used for display purposes on Shopify cart pages.
properties[_secondary_discount_percent]
(optional)		Integer value of the secondary discount value. Only used for display purposes on Shopify cart pages if the subscription group has a dynamic discount.
properties[_secondary_discount_required_orders]
(optional)		Number of orders until the secondary discount is applied. Only used for display purposes on Shopify cart pages if the subscription group has a dynamic discount.

Directly to Checkout (No Cashier) - Limited Length​

POST https://recurringcheckout.com/s/your-store/checkout/recurring_product?shop_url=your-store.myshopify.com HTTP/1.1
Content-Type: multipart/form-data

--------------------------x
Content-Disposition: form-data; name="group_id"
1234
--------------------------x
Content-Disposition: form-data; name="frequency_num"
1
--------------------------x
Content-Disposition: form-data; name="frequency_type"
3
--------------------------x
Content-Disposition: form-data; name="frequency_type_text"
Month(s)
--------------------------x
Content-Disposition: form-data; name="quantities[]"
1
--------------------------x
Content-Disposition: form-data; name="variant_id[]"
135792468
--------------------------x
Content-Disposition: form-data; name="product_id[]"
246813579
--------------------------x
Content-Disposition: form-data; name="total_recurrences"
6
--------------------------x
POST DataDescription
group_idThe subscription group ID.
frequency_numAny integer value to define the frequency of the subscription (paired with frequency_type).
frequency_type
  • 1 for days
  • 2 for weeks
  • 3 for months
  • 5 for years
frequency_type_textHuman readable string representing the frequency of the subscription E.g. “Month(s)”.
quantities[]The quantity of the product the customer is subscribing to.
variant_id[]The Shopify variant ID the customer is subscribing to. This should be a single index array.
product_id[]The Shopify product ID the customer is subscribing to. This should be a single index array.
total_recurrencesThe number of orders that should process before the subscription automatically ends.
billing_plan
(optional)		Only applicable to weekly billing plans (E.g. Every 2 weeks on Wednesday), representing the week day to use for the subscription. You can retrieve this ID through the frontend Widget API.

Directly to Checkout (Cashier Integrated) - Limited Length​

To submit to Cashier’s checkout there is a unique set of steps listed below. Cashier relies on products being added to the cart before going directly to checkout, which is a bit different than how it works without Cashier.

Clear the cart - Limited Length​
POST https://your-store.myshopify.com/cart/clear HTTP/1.1

To start you should make a POST request (see fetch API) to /cart/clear.js to clear any existing products in the Shopify cart.

Add to cart - Limited Length​
POST https://your-store.myshopify.com/cart/add HTTP/1.1
Content-Type: application/json

{
    "id": 135792468,
    "properties": {
        "group_id": 1234,
        "frequency_num": 1,
        "frequency_type": 3,
        "frequency_type_text": "Month(s)",
        "_ro_single_product_recurring_item": true,
        "total_recurrences": 6
    }
}

Next you should add the subscription product to the cart by making a request to /cart/add with all of the following POST data:

POST DataDescription
idThe Shopify variant ID the customer is subscribing to.
properties[group_id]The subscription group ID.
properties[frequency_num]Any integer value to define the frequency of the subscription (paired with frequency_type).
properties[frequency_type]
  • 1 for days
  • 2 for weeks
  • 3 for months
  • 5 for years
properties[frequency_type_text]Human readable string representing the frequency of the subscription E.g. “Month(s)”.
properties[_ro_single_product_recurring_item]Value should be true
properties[total_recurrences]The number of orders that should process before the subscription automatically ends.
properties[_ro_billing_plan]
(optional)		Only applicable to weekly billing plans (E.g. Every 2 weeks on Wednesday), representing the week day to use for the subscription. You can retrieve this ID through the frontend Widget API.
Fetch the latest cart ID - Limited Length​
GET https://your-store.myshopify.com/cart.json?ts=102359812 HTTP/1.1

Before you go to checkout you need to make one extra GET request to /cart.js?ts={current_unix_timestamp}. You should grab the entire JSON body of the response and store it into a variable using JSON.stringify(cart). The response of this request will also update your browser’s cookies with a new value for the cart cookie. Now that the cookie is updated, you should pull out the value of the cart cookie from document.cookie and then store that value in a variable. This value represents the cart ID.

Submit to the Cashier checkout - Limited Length​
POST https://your-store.myshopify.com/apps/checkout/begin-checkout?shop=your-store.myshopify.com HTTP/1.1
Content-Type: multipart/form-data

--------------------------x
Content-Disposition: form-data; name="cart_id"

f24e49648c2aa1c5054e712057c0ccc7
--------------------------x
Content-Disposition: form-data; name="cart"

{"token":"f24e49648c2aa1c5054e712057c0ccc7","note":null,"attributes":{},"original_total_price":0,"total_price":0,"total_discount":0,"total_weight":0,"item_count":0,"items":[],"requires_shipping":false,"currency":"CAD","items_subtotal_price":0,"cart_level_discount_applications":[]}
--------------------------x

Finally, you should submit a form on the page or one that you’ve created to the Cashier checkout.

Prepaid Subscription​

Directly to Checkout (No Cashier) - Prepaid​

POST https://recurringcheckout.com/s/your-store/checkout/recurring_product?shop_url=your-store.myshopify.com HTTP/1.1
Content-Type: multipart/form-data

--------------------------x
Content-Disposition: form-data; name="group_id"
1234
--------------------------x
Content-Disposition: form-data; name="frequency_num"
1
--------------------------x
Content-Disposition: form-data; name="frequency_type"
3
--------------------------x
Content-Disposition: form-data; name="frequency_type_text"
Month(s)
--------------------------x
Content-Disposition: form-data; name="quantities[]"
1
--------------------------x
Content-Disposition: form-data; name="variant_id[]"
135792468
--------------------------x
Content-Disposition: form-data; name="product_id[]"
246813579
--------------------------x
Content-Disposition: form-data; name="total_recurrences"
6
--------------------------x
Content-Disposition: form-data; name="is_prepaid"
1
--------------------------x
Content-Disposition: form-data; name="prepaid_length_id"
135792
--------------------------x
POST DataDescription
group_idThe subscription group ID.
frequency_numAny integer value to define the frequency of the subscription (paired with frequency_type).
frequency_type
  • 1 for days
  • 2 for weeks
  • 3 for months
  • 5 for years
frequency_type_textHuman readable string representing the frequency of the subscription E.g. “Month(s)”.
quantities[]The quantity of the product the customer is subscribing to.
variant_id[]The Shopify variant ID the customer is subscribing to. This should be a single index array.
product_id[]The Shopify product ID the customer is subscribing to. This should be a single index array.
total_recurrencesThe number of orders that should process before the subscription automatically ends.
is_prepaidValue should be 1.
prepaid_length_idThis is the unique integer ID associated to the total_recurrences value that the customer is subscribing to. To retrieve this value you will need to make a GET request to our frontend Widget API for the group data associated to the group_id for this subscription. The full request URL looks like:

https://ro.boldapps.net/api/widget/group/<GROUP_ID>?shop=your-store.myshopify.com
is_gift
(optional)		Only send this in the POST data, with a value of 1, if you would like a normally auto-renewing subscription to end / expire after the last order. E.g. Prepay for 6 months and automatically expire afterwards. Otherwise, if the subscription group is set to auto-renew, it will charge the customer for an additional X orders and continue the subscription.

Directly to Checkout (Cashier Integrated) - Prepaid​

To submit to Cashier’s checkout there is a unique set of steps listed below. Cashier relies on products being added to the cart before going directly to checkout, which is a bit different than how it works without Cashier.

Clear the cart - Prepaid Subscription​
POST https://your-store.myshopify.com/cart/clear HTTP/1.1

To start you should make a POST request (see fetch API) to /cart/clear.js to clear any existing products in the Shopify cart.

Add to cart - Prepaid Subscription​
POST https://your-store.myshopify.com/cart/add HTTP/1.1
Content-Type: application/json

{
    "id": 135792468,
    "properties": {
        "group_id": 1234,
        "frequency_num": 1,
        "frequency_type": 3,
        "frequency_type_text": "Month(s)",
        "_ro_single_product_recurring_item": true,
        "total_recurrences": 6,
        "is_prepaid": 1,
        "prepaid_length_id": 135792
    }
}

Next you should add the subscription product to the cart by making a request to /cart/add with all of the following POST data:

POST DataDescription
idThe Shopify variant ID the customer is subscribing to.
properties[group_id]The subscription group ID.
properties[frequency_num]Any integer value to define the frequency of the subscription (paired with frequency_type).
properties[frequency_type]
  • 1 for days
  • 2 for weeks
  • 3 for months
  • 5 for years
properties[frequency_type_text]Human readable string representing the frequency of the subscription E.g. “Month(s)”.
properties[_ro_single_product_recurring_item]Value should be true
properties[total_recurrences]The number of orders that should process before the subscription automatically ends.
properties[is_prepaid]Value should be 1.
properties[prepaid_length_id]This is the unique integer ID associated to the total_recurrences value that the customer is subscribing to. To retrieve this value you will need to make a GET request to our frontend Widget API for the group data associated to the group_id for this subscription. The full request URL looks like:

https://ro.boldapps.net/api/widget/group/<GROUP_ID>?shop=your-store.myshopify.com
properties[is_gift]
(optional)		Only send this in the POST data, with a value of 1, if you would like a normally auto-renewing subscription to end / expire after the last order. E.g. Prepay for 6 months and automatically expire afterwards. Otherwise, if the subscription group is set to auto-renew, it will charge the customer for an additional X orders and continue the subscription.
Fetch the latest cart ID - Prepaid Subscription​
GET https://your-store.myshopify.com/cart.json?ts=102359812 HTTP/1.1

Before you go to checkout you need to make one extra GET request to /cart.js?ts={current_unix_timestamp}. You should grab the entire JSON body of the response and store it into a variable using JSON.stringify(cart). The response of this request will also update your browser’s cookies with a new value for the cart cookie. Now that the cookie is updated, you should pull out the value of the cart cookie from document.cookie and then store that value in a variable. This value represents the cart ID.

Submit to the Cashier checkout - Prepaid Subscription​
POST https://your-store.myshopify.com/apps/checkout/begin-checkout?shop=your-store.myshopify.com HTTP/1.1
Content-Type: multipart/form-data

--------------------------x
Content-Disposition: form-data; name="cart_id"

f24e49648c2aa1c5054e712057c0ccc7
--------------------------x
Content-Disposition: form-data; name="cart"

{"token":"f24e49648c2aa1c5054e712057c0ccc7","note":null,"attributes":{},"original_total_price":0,"total_price":0,"total_discount":0,"total_weight":0,"item_count":0,"items":[],"requires_shipping":false,"currency":"CAD","items_subtotal_price":0,"cart_level_discount_applications":[]}
--------------------------x

Finally, you should submit a form on the page or one that you’ve created to the Cashier checkout.

Convertible Subscription​

Add to Cart (No Cashier) - Convertible​

POST https://your-store.myshopify.com/cart/add HTTP/1.1
Content-Type: application/json

{
    "id": 135792468,
    "properties": {
        "group_id": 1234,
        "frequency_num": 1,
        "frequency_type": 3,
        "frequency_type_text": "Month(s)",
        "total_recurrences": 6,
        "_convertible_discount_percent": 10,
        "_convertible_product_handle": "monthly-subscription-product"
    }
}

Convertible subscriptions can be in the form of a Standard or Limited Length subscription (see definitions). The only factor that makes it convertible is the group_id parameter. Thus, you should reference all of the same POST data you would use for any of these subscription types:

In addition to the regular POST data you can also include these two parameters for cosmetic purposes on the Shopify cart page.

POST DataDescription
properties[_convertible_discount_percent]
(optional)		Integer value of the discount percentage for the convert-to product.
properties[_convertible_product_handle]
(optional)		Shopify product handle for the convert-to product.

Add to Cart (Cashier Integrated) - Convertible​

POST https://your-store.myshopify.com/cart/add HTTP/1.1
Content-Type: application/json

{
    "id": 135792468,
    "properties": {
        "group_id": 1234,
        "frequency_num": 1,
        "frequency_type": 3,
        "frequency_type_text": "Month(s)",
        "total_recurrences": 6,
        "_convertible_discount_percent": 10,
        "_convertible_product_handle": "monthly-subscription-product"
    }
}

Convertible subscriptions can be in the form of a Standard or Limited Length subscription (see definitions). The only factor that makes it convertible is the group_id parameter. Thus, you should reference all of the same POST data you would use for any of these subscription types:

In addition to the regular POST data you can also include these two parameters for cosmetic purposes on the Shopify cart page.

POST DataDescription
properties[_convertible_discount_percent]
(optional)		Integer value of the discount percentage for the convert-to product.
properties[_convertible_product_handle]
(optional)		Shopify product handle for the convert-to product.

Directly to Checkout (No Cashier) - Convertible​

POST https://recurringcheckout.com/s/your-store/checkout/recurring_product?shop_url=your-store.myshopify.com HTTP/1.1
Content-Type: multipart/form-data

--------------------------x
Content-Disposition: form-data; name="group_id"
1234
--------------------------x
Content-Disposition: form-data; name="frequency_num"
1
--------------------------x
Content-Disposition: form-data; name="frequency_type"
3
--------------------------x
Content-Disposition: form-data; name="frequency_type_text"
Month(s)
--------------------------x
Content-Disposition: form-data; name="quantities[]"
1
--------------------------x
Content-Disposition: form-data; name="variant_ids[]"
135792468
--------------------------x
Content-Disposition: form-data; name="product_ids[]"
246813579
--------------------------x
Content-Disposition: form-data; name="total_recurrences"
6
--------------------------x

Convertible subscriptions can be in the form of a Standard or Limited Length subscription (see definitions). The only factor that makes it convertible is the group_id parameter. Thus, you should reference all of the same POST data you would use for any of these subscription types:

Directly to Checkout (Cashier Integrated) - Convertible​

To submit to Cashier’s checkout there is a unique set of steps listed below. Cashier relies on products being added to the cart before going directly to checkout, which is a bit different than how it works without Cashier.

Clear the cart - Convertible​
POST https://your-store.myshopify.com/cart/clear HTTP/1.1

To start you should make a POST request (see fetch API) to /cart/clear.js to clear any existing products in the Shopify cart.

Add to cart - Convertible​
POST https://your-store.myshopify.com/cart/add HTTP/1.1
Content-Type: application/json

{
    "id": 135792468,
    "properties": {
        "group_id": 1234,
        "frequency_num": 1,
        "frequency_type": 3,
        "frequency_type_text": "Month(s)",
        "_ro_single_product_recurring_item": true,
        "total_recurrences": 6
    }
}

Convertible subscriptions can be in the form of a Standard or Limited Length subscription (see definitions). The only factor that makes it convertible is the group_id parameter. Thus, you should reference all of the same POST data you would use for any of these subscription types:

Fetch the latest cart ID - Convertible​
GET https://your-store.myshopify.com/cart.json?ts=102359812 HTTP/1.1

Before you go to checkout you need to make one extra GET request to /cart.js?ts={current_unix_timestamp}. You should grab the entire JSON body of the response and store it into a variable using JSON.stringify(cart). The response of this request will also update your browser’s cookies with a new value for the cart cookie. Now that the cookie is updated, you should pull out the value of the cart cookie from document.cookie and then store that value in a variable. This value represents the cart ID.

Submit to the Cashier checkout - Convertible​
POST https://your-store.myshopify.com/apps/checkout/begin-checkout?shop=your-store.myshopify.com HTTP/1.1
Content-Type: multipart/form-data

--------------------------x
Content-Disposition: form-data; name="cart_id"

f24e49648c2aa1c5054e712057c0ccc7
--------------------------x
Content-Disposition: form-data; name="cart"

{"token":"f24e49648c2aa1c5054e712057c0ccc7","note":null,"attributes":{},"original_total_price":0,"total_price":0,"total_discount":0,"total_weight":0,"item_count":0,"items":[],"requires_shipping":false,"currency":"CAD","items_subtotal_price":0,"cart_level_discount_applications":[]}
--------------------------x

Finally, you should submit a form on the page or one that you’ve created to the Cashier checkout.

Recurring Cart Mode (No Cashier)​

POST https://recurringcheckout.com/s/your-store/checkout/recurring_full_cart?shop_url=your-store.myshopify.com HTTP/1.1
Content-Type: multipart/form-data

--------------------------x
Content-Disposition: form-data; name="frequency_num"
1
--------------------------x
Content-Disposition: form-data; name="frequency_type"
3
--------------------------x
Content-Disposition: form-data; name="frequency_type_text"
Month(s)
--------------------------x
Content-Disposition: form-data; name="shopify_cart"
{"token":"f24e49648c2aa1c5054e712057c0ccc7","note":null,"attributes":{},"original_total_price":0,"total_price":0,"total_discount":0,"total_weight":0,"item_count":0,"items":[],"requires_shipping":false,"currency":"CAD","items_subtotal_price":0,"cart_level_discount_applications":[]}
--------------------------x

If your store is operating in Recurring Cart mode then you can POST to the Bold Subscriptions checkout using a form with all of the required data below and form action from the example.

Form DataDescription
frequency_numAny integer value to define the frequency of the subscription (paired with frequency_type).
frequency_type
  • 1 for days
  • 2 for weeks
  • 3 for months
  • 5 for years
frequency_type_textHuman readable string representing the frequency type of the subscription E.g. “Month(s)”.
shopify_cartJSON string representing the current cart object just before to going to checkout. This should be retrieved by making a request to Shopify's /cart.json?ts=<CURRENT_TIMESTAMP> endpoint, replacing <CURRENT_TIMESTAMP> appropriately to prevent caching issues. It's recommend that you iterate over the line items in the cart object and remove any product descriptions before using JSON.stringify(cart).
billing_plan
(optional)		Only applicable to weekly billing plans (E.g. Every 2 weeks on Wednesday), representing the week day to use for the subscription. You can retrieve this ID through the frontend Widget API.

Recurring Cart Mode (Cashier Integrated)​

POST https://your-store.myshopify.com/apps/checkout/begin-checkout?shop=your-store.myshopify.com HTTP/1.1
Content-Type: multipart/form-data

--------------------------x
Content-Disposition: form-data; name="cart_id"
f24e49648c2aa1c5054e712057c0ccc7
--------------------------x
Content-Disposition: form-data; name="cart"
{"token":"f24e49648c2aa1c5054e712057c0ccc7","note":null,"attributes":{},"original_total_price":0,"total_price":0,"total_discount":0,"total_weight":0,"item_count":0,"items":[],"requires_shipping":false,"currency":"CAD","items_subtotal_price":0,"cart_level_discount_applications":[]}
--------------------------x
Content-Disposition: form-data; name="bold_cart_params[b065901c-bf09-11e7-b98f-42010afe0607][frequency_num]"
1
--------------------------x
Content-Disposition: form-data; name="bold_cart_params[b065901c-bf09-11e7-b98f-42010afe0607][frequency_type]"
3
--------------------------x
Content-Disposition: form-data; name="bold_cart_params[b065901c-bf09-11e7-b98f-42010afe0607][frequency_type_text]"
Month(s)
--------------------------x
Content-Disposition: form-data; name="bold_cart_params[b065901c-bf09-11e7-b98f-42010afe0607][recurring_selected]"
1
--------------------------x

If your store is operating in Recurring Cart mode then you can POST to the Cashier checkout using a form with all of the required data below and form action from the example.

Form DataDescription
cartJSON string representing the current cart object just before to going to checkout. This should be retrieved by making a request to Shopify's /cart.json?ts=<CURRENT_TIMESTAMP> endpoint, replacing <CURRENT_TIMESTAMP> appropriately to prevent caching issues. It's recommend that you iterate over the line items in the cart object and remove any product descriptions before using JSON.stringify(cart).
cart_idThe token from the current JSON cart object.
bold_cart_params[UUID][frequency_num]Any integer value to define the frequency of the subscription (paired with frequency_type). Replace UUID with b065901c-bf09-11e7-b98f-42010afe0607.
bold_cart_params[UUID][frequency_type]
  • 1 for days
  • 2 for weeks
  • 3 for months
  • 5 for years

Replace UUID with b065901c-bf09-11e7-b98f-42010afe0607.

bold_cart_params[UUID][frequency_type_text]Human readable string representing the frequency type of the subscription E.g. “Month(s)”. Replace UUID with b065901c-bf09-11e7-b98f-42010afe0607.
bold_cart_params[UUID][recurring_selected]Value should be 1. Replace UUID with b065901c-bf09-11e7-b98f-42010afe0607.
bold_cart_params[UUID][billing_plan] (optional)Only applicable to weekly billing plans (E.g. Every 2 weeks on Wednesday), representing the week day to use for the subscription. You can retrieve this ID through the frontend Widget API. Replace UUID with b065901c-bf09-11e7-b98f-42010afe0607.

Widget API​

This API documentation describes the endpoints available when customizing the frontend widgets for Bold Subscriptions. As a simple means of interacting with these endpoints we recommend installing and using our BoldSubscriptions.js Javascript API.

The Bold Subscriptions widget can be in various places depending on how you use the app; widgets could appear on the product page, cart page or select choices page (for Build-a-Box subscriptions). Use these endpoints to customize existing widgets or create your own.

Variables​

Request Parameter variables are displayed as {parameter} with the documentation.

You can find the associated response definitions along side the examples in the element tables.

Group Endpoints​

Get Group Info​

GET https://ro.boldapps.net/api/widget/group/{group_id}?shop=your-store.myshopify.com HTTPS/1.1
Content-Type: application/json

HTTPS/1.1 200 OK

Example response has been truncated for brevity

{
    "recurring_group": true,
    "discount_percentage": 1,
    "group_discount": 0,
    "group_id": 5589,
    "s_shop_url": "https://ro.boldapps.net/s/recurring-order-live-demo/",
    "shop_url": "recurring-order-live-demo.myshopify.com",
    "app_root": "https://ro.boldapps.net",
    "money_format": "${{amount}}",
    "anonymous_login": true,
    "subscription_type": 1,
    "recurring_mode": {...},
    "secondary_discount": false,
    "subscription_box": false,
    "conversion": false,
    "standard": {...},
    "details_tooltip": "<p><strong>Cancel, pause, or modify your subscription any time!</strong></p>\n<p><em>P.S. - You can put any text in here you like!</em></p>",
    "subscription_only": false,
    "prepaid": false,
    "limited_subscription": {...},
    "fixed_interval": true,
    "frequency_too_large": false,
    "frequency_num": 1,
    "frequency_type": [
        {...},{...}
    ]
}

This endpoint retrieves all information for a Recurring Orders subscription group id.

GET https://ro.boldapps.net/api/widget/group/{group_id}?shop=your-store.myshopify.com

URL Parameters - Get Group Info​
ElementTypeDescription
group_idintegerRecurring Orders Subscription Group ID

Build-a-Box Endpoints​

Get Slots​

GET https://ro.boldapps.net/api/widget/group/{group_id}/build_a_box/slots?shop=your-store.myshopify.com HTTPS/1.1
Content-Type: application/json

HTTPS/1.1 200 OK

Example response has been truncated for brevity

{
    "slots": [
        {
            "id": 1,
            "label": "Product A",
            "active": true,
            "parent_slot_id": null,
            "product": {
                "start_date": "2019-08-27 00:00:00",
                "product_id": 11218024196,
                "variant_id": 43216935492,
                "shopify_details": {...}
            }
        },
        {
            "id": 2,
            "label": "Product B",
            "active": true,
            "parent_slot_id": null,
            "product": {
                "start_date": "2019-08-27 00:00:00",
                "product_id": 11218026052,
                "variant_id": 43216944772,
                "shopify_details": {...}
            }
        }
    ]
}

This endpoint retrieves slot information for a Build a Box subscription group

GET https://ro.boldapps.net/api/widget/group/{group_id}/build_a_box/slots?shop=your-store.myshopify.com

URL Parameters - Get Slots​
ElementTypeDescription
group_idintegerRecurring Orders subscription group ID
GET Parameters - Get Slots​
ElementTypeDescription
bidinteger(optional) Billing plan ID
Data Object - Get Slots​
ElementTypeDescription
idintegerSlot ID
labelstringInternal name for the slot
activebooleanFalse if the slot has been deleted
parent_slot_idintegerParent slot ID
productobjectDetails on the active product for the slot

Translation Endpoints​

Get Translations​

GET https://ro.boldapps.net/api_public/translations?shop_url=your-store.myshopify.com HTTPS/1.1
Content-Type: application/json

HTTPS/1.1 200 OK

Example response has been truncated for brevity

{
    "translations": {
        "add_subscription_to_cart": "Add subscription to cart",
        "auto_replenish_cart": "Make this entire cart recurring?",
        "auto_replenish_product": "Subscribe and Save!",
        "billing_plan_select": "Place order every [interval_number] [interval] on [billing_day]",
        "box_selections_required": "Minimum [num_required] Selection(s) Remaining",
        "box_subtotal": "Subtotal: [subtotal]",
        "complete_subscription": "Complete subscription",
        ...
    },
    "days_of_week": [
        "Sunday",
        "Monday",
        "Tuesday",
        "Wednesday",
        "Thursday",
        "Friday",
        "Saturday"
    ],
    "display_settings": {
        "hover_modal": "<div align=\"left\">\n<div><strong>Subscription Details</strong></div>\n<div>\n<ul>\n<li>Set it and forget it!</li>\n<li>Pause, edit or cancel anytime.</li>\n</ul>\n</div>\n</div>"
    }
}

This endpoint retrieves translations that are entered in the Bold Subscriptions admin language settings.

GET https://ro.boldapps.net/api_public/translations?shop_url=your-store.myshopify.com