NAV Navbar
http
  • Introduction
  • Default Behaviour
  • Subscription Types
  • Product Form Creation
  • BoldSubscriptions.js
  • Custom Subscription Flow
  • Widget API
  • 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

    Term Description
    Subscription group Subscription groups are created in the Bold Subscriptions admin and define which type of subscription is available for which products / variants.
    Group ID Unique ID for a subscription group. Never changes unless the subscription group is deleted.
    Widget Refers 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

    Default Behaviour

    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 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 choosings. 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

    $ npm install bold-subscriptions-js
    

    Using yarn

    $ yarn add bold-subscriptions-js
    

    Using CDN

    <script src="https://unpkg.com/@boldcommerce/bold-subscriptions-js"></script>
    

    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': 'Every 1 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="Every 1 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': 'Every 1 Month(s)',
        }
    });
    

    Reference

    The widgetAPI object

    The cart object

    The checkout object


    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.


    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)

    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)

    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.

    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

    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": "Every 1 Month(s)" } }

    POST Data Description
    id The 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. “Every 1 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": "Every 1 Month(s)" } }

    POST Data Description
    id The 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. “Every 1 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" Every 1 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 Data Description
    group_id The subscription group ID.
    frequency_num Any 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_text Human readable string representing the frequency of the subscription E.g. “Every 1 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": "Every 1 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 Data Description
    id The 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. “Every 1 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": "Every 1 Month(s)", "total_recurrences": 6 } }

    POST Data Description
    id The 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. “Every 1 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": "Every 1 Month(s)", "total_recurrences": 6 } }

    POST Data Description
    id The 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. “Every 1 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" Every 1 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 Data Description
    group_id The subscription group ID.
    frequency_num Any 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_text Human readable string representing the frequency of the subscription E.g. “Every 1 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_recurrences The 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": "Every 1 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 Data Description
    id The 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. “Every 1 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" Every 1 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 Data Description
    group_id The subscription group ID.
    frequency_num Any 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_text Human readable string representing the frequency of the subscription E.g. “Every 1 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_recurrences The number of orders that should process before the subscription automatically ends.
    is_prepaid Value should be 1.
    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
    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": "Every 1 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 Data Description
    id The 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. “Every 1 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": "Every 1 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 Data Description
    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": "Every 1 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 Data Description
    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"
    Every 1 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": "Every 1 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.

    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

    Element Type Description
    group_id integer Recurring 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

    Element Type Description
    group_id integer Recurring Orders subscription group ID

    GET Parameters - Get Slots

    Element Type Description
    bid integer (optional) Billing plan ID

    Data Object - Get Slots

    Element Type Description
    id integer Slot ID
    label string Internal name for the slot
    active boolean False if the slot has been deleted
    parent_slot_id integer Parent slot ID
    product object Details on the active product for the slot