Skip to main content

Getting Started

Use the Bold Subscriptions API to create custom subscriptions models for your customers. You can add, update, and monitor all store subscriptions through the API and webhooks.

In this guide, you will get started with the Bold Subscriptions API by accomplishing the following tasks:

  1. Install Bold Subscriptions on your store.
  2. Create an API access token that is scoped to access Bold Subscriptions.
  3. Update a subscription with the Subscriptions API.
  4. Add the Bold Subscriptions JavaScript library to your storefront.

Prerequisites​

  1. For all platforms except Shopify, Bold Checkout must be installed on your store. For Shopify, you can use the native Shopify Checkout, and Bold Cashier is available on a case-by-case basis only. Refer to What checkout can I use? for more information.

Install Bold Subscriptions on your store​

You must have the Bold Subscriptions app installed on your store to access the API. The installation process varies slightly based on your store's platform. Refer to the following links in the Help Center for more information:

note

If you are developing a Bold Subscriptions integration, Bold Commerce can provide an extended (3 month) free trial of the app while you build your integration. Reach out to the Support Team with your store info to request an extended trial.

Create an API access token​

An API access token gives you access to the Bold APIs. The process to generate this token depends on the type of integration you build:

  • For private integrations, which are installed on a single store and are not available in the Integrations Marketplace, create your API access token through the Bold Account Center. Complete the steps in the Quick Start guide to generate this token and make your first API calls.
  • For public integrations, which can be made available in the Integrations Marketplace, create your API access token through an OAuth flow. Complete the steps in the Building Public Integrations guide to generate this token and make your first API calls.

When prompted to specify the scopes of your API access token, select the following scopes:

CategoryScopePermissions
CoreProductsRead & Write
CoreCustomersRead & Write
CoreOrdersRead & Write
CoreShop SettingsRead & Write
CoreShopsRead
SubscriptionsSubscriptionsRead & Write
SubscriptionsSubscription GroupsRead & Write
SubscriptionsShopsRead
SubscriptionsActivity LogsRead & Write

Update a subscription with the Subscriptions API​

The Subscriptions API enables you to update subscriptions orders as the merchant or on behalf of the customer. Refer to the following steps for an example of updating a subscription.

List subscriptions​

The Bold Subscriptions API identifies each store using a unique shopIdentifier, which can be found through the Get Shop Info endpoint. Once retrieved, it may be useful to store the shopIdentifier as a variable, where it can be easily accessed.

The shopIdentifier allows you to find information stored about each store, such as a list of subscriptions associated with it. Access this list through the List Subscriptions endpoint, and pass in optional parameters such as subscription_status, bold_platform_customer_id, or expand.

The following example shows a request to get 10 paused subscriptions on a store, with expanded details about the customer for each:

curl --request GET 'https://api.boldcommerce.com/subscriptions/v1/shops/{shopIdentifier}/subscriptions?subscription_status=paused&expand=customer&limit=10' \
     --header 'Authorization: Bearer {api_token}' \
     --header 'Bold-API-Version-Date: 2022-05-01'

When you find the subscription you were looking for, make note of its subscriptionId.

Update subscription​

Using the subscription_id, you can make changes to a subscription through various endpoints, such as Update Subscription, Partial Update Subscription, or Swap Line Items, among others.

For example, you could use the following request to update the status of a "paused" subscription to "active":

curl --request PATCH 'https://api.boldcommerce.com/subscriptions/v1/shops/{shop_identifier}/subscriptions/{subscription_id}' \
     --header 'Authorization: Bearer {api_token}' \
     --header 'Bold-API-Version-Date: 2022-05-01' \
     --header 'Content-Type: application/json' \
     --data '{
         "subscription": {
             "subscription_status": "active"
         }
     }'

If your request was successful, the endpoint will return a JSON object with the details of the updated subscription.

Add the Bold Subscriptions JavaScript library to your storefront​

The Bold Subscriptions JavaScript (BS JS) library is responsible for many of the interactions that occur with your shop's storefront. It places the product widget, displays the line item's subscription properties, and displays subscription discounts on the cart page. It also defines a set of helper methods and shop data under the window.BOLD.subscriptions object.

Once available, the BS JS allows you to add custom storefront widgets and a custom customer portal.

Automatic Script Delivery​

Some platforms (including BigCommerce and Shopify) allow Bold Subscriptions to create a JavaScript file on the platform itself, which is done automatically at installation. This script is served from the platform to the browser when a customer visits your storefront. You can confirm that your storefront has the BS JS by visiting your storefront code and looking for the presence of the following line in the head tag of the HTML:

<script id="bold-subscriptions-script" type="text/javascript" />

Manual Script Delivery​

note

This method of script delivery is invalid for Shopify and BigCommerce and will cause an error to be thrown.

If you are creating a storefront on a custom platform or one that does not allow automatic JS installation, you can manually add the BS JS to your store.

Add a script tag within the head tag of your HTML with the appropriate src value:

<script
  id="bold-subscriptions-script"
  src="https://sub.boldapps.net/api/storefront/shop_script?shop={shop_domain}"
></script>

This API endpoint accepts {shop_domain} as a query parameter that represents your shop platform domain or custom domain.

Next steps​

Now that you understand the basics of finding the subscriptions for a store and updating them, you can dive in using the Subscriptions API specification or keep reading to learn more: