Skip to main content

Create Selection Flow

note

Subscription Builder requires Bold Checkout to be installed on your store. Therefore, it is not available to merchants using Shopify. For information on build-a-box subscriptions on Shopify, refer to the Help Center.

For stores with Subscription Builder integrations, merchants may want to allow customers to log into a customer portal and make selections for their upcoming orders. For example, a meal subscription service may allow customers to select their meals for the upcoming month.

This document explains how to enable an existing customer to make their selections for a future subscription order using Subscription Builder and a customer portal. This document covers the following high-level steps:

  1. Authenticate the customer with a JWT.
  2. Get the customer's subscriptions.
  3. Display future orders.
  4. Find the right time slot for an upcoming order.
  5. Allow the customer to make selections.
  6. Display the customer's selections.

Prerequisites​

Before you get started, complete the following steps:

  1. Complete the steps in Getting Started with the Bold Subscriptions API.
  2. Install the Subscription Builder integration on your store.
  3. Create a first-time checkout flow using Subscription Builder Initial Checkout Flow.
  4. Implement your own customer portal using the guidelines on the Customer Portal page.

Authenticate the customer with a JWT​

When a customer logs into the customer portal, you must acquire a JSON Web Token (JWT) in order to make authenticated API calls on behalf of the customer. Refer to the Authenticate the customer with JWT section of the Customer Portal documentation.

Use the customer JWT in the Authorization header for calls to the Subscription Builder Customer API.

Get the customer's subscriptions​

Once the customer is logged into the customer portal, display their subscription(s) to them. You can identify which subscription groups a customer is subscribed to using the List Customer Subscriptions endpoint.

Refer to the following sample call for an example of getting a customer's subscriptions, given the shop_identifier and customer_id:

curl --request GET 'https://api.boldcommerce.com/subscriptions/v1/shops/{shop_identifier}/customers/{customer_id}/subscriptions' \
     --header 'Authorization: Bearer {jwt}' \
     --header 'Bold-API-Version-Date: 2022-05-01'

The response from this endpoint is a list of subscription objects.

Display future orders​

You can then choose to display the boxes the customer is subscribed to in various ways. You can use the List Future Orders endpoint to identify and display the future orders for each box.

Refer to the Build the Customer Portal page for more information and guidelines on displaying customer orders.

Find the right time slot for an upcoming order​

From the customer portal page that displays a customer's subscriptions, the customer can choose the subscription box and the time frame for the order that they would like to customize. For example, a customer might indicate they want to make selections for next month's meal subscription box.

The following JavaScript snippet shows how to find the appropriate time slot from a given box and time.

note
  • Assume that apiClient is an Axios client instantiated with a base URL that aligns with the base URL of the Subscription Builder Storefront API reference for listing box time slots.
  • Assume orderDatetime parameter is a valid UTC datetime found when the customer selects which future order they want to customize.
// API client (e.g., Axios) for talking with Bold APIs
const apiClient = ...;

async function getBoxTimeSlotByOrderDatetime(box, orderDatetime) {
  const errMsg = 'Failed to get time slot for given order datetime.';

  try {
    const timeSlotsResponse = await apiClient.get(`/boxes/${box.id}/time_slots?order_datetime=${orderDatetime}`);
    const {
      data: {
        data: {
          time_slots
        }
      }
    } = timeSlotsResponse;
  } catch (e) {
    throw new Error(errMsg);
  }

  if (!time_slots.length) {
    throw new Error(errMsg);
  }

  return time_slots[0];
}

Allow the customer to make selections​

Use the time slot options found in previous step to display a selections screen for your customers to make box product choices for their order.

note

The code used to create the selection screen in the initial checkout flow can likely be reused as a selection screen for future orders. For more information, refer to the Display time slot options section of the Subscription Builder Initial Checkout Flow page.

Instead of sending the line item selections to Bold Checkout as cart params, you must store the customer's selections in the Subscription Builder server using the Create Customer Selection endpoint. When it is time to charge the customer's card, Bold Checkout retrieves these stored selections and places an order on the customer's behalf.

The following JavaScript code snippet shows an example of storing the customer's selections.

note
  • Assume that authenticatedApiClient is an Axios client instantiated with a base URL that aligns with the base URL of the Subscription Builder Storefront API reference for listing box time slots. It is configured using the customer JWT retrieved in previous steps.
  • Replace the parameters in the following snippet with the information you found in the previous step.
// Authenticated API client (e.g., Axios) for talking with Subscription Builder customer APIs
const authenticatedApiClient = ...;

function makeSelectionLineItem(boxProductId, choiceQuantity) {
  return {
    box_product_id: boxProductId,
    choice_quantity: choiceQuantity
  }
}

async function makeSelections(platformCustomerId, boxSizeId, timeSlotId, subscriptionLineItemId, orderDatetime, selectionLineItems) {
  const shopIdentifier = '13579082'; // Your shopIdentifier from the Bold API

  const response = await apiClient.post(`/customer/v1/shops/${shopIdentifier}/customers/${platformCustomerId}/selections`, {
    bold_platform_subscription_line_item_id: subscriptionLineItemId,
    order_datetime: orderDatetime,
    box_size_id: boxSizeId,
    time_slot_id: timeSlotId,
    line_items: selectionLineItems
  });

  return response;
}

Display the customer's selections​

Once the customer has made their selections for the upcoming order, you can redirect the customer back to the homepage of the customer portal or another page.

You may want to display the customer's selections so that they can see what their upcoming orders contain. You can do so using the Customer: List Selections endpoint.