Custom Subscriptions Implementation Guide

Use this guide to connect your existing or custom subscription solution to Bolt Checkout.

Before You Start

These instructions assume that you:

• Have an active Bolt Merchant Account
• Have reviewed Bolt’s API collection, particularly the authorization endpoint

Tag Products as Subscriptions

You’ll need to tag products as subscriptions so the checkout page displays subscription frequencies correctly to shoppers.

Implementation

Display Subscriptions in Checkout

When you call the /v1/merchant/orders endpoint, include subscription properties with a CartItem:

"subscription": {
    "frequency": {
      "unit": "month",
      "value": 2
    }
  }

Bolt Checkout then displays the product to the shopper as a recurring subscription.

Setting a Frequency

Use the parameters in frequency to set the subscription’s frequency. The subscription in this example recurs every 2 months.

unit: 
  type: string
  description: The unit that expresses this subscription's frequency.
  enum: 
    - day
    - week
    - month
    - year
  example: month

value: 
  type: integer
  description: The value applied to the unit of frequency.
  example: 2

Authorization

To request authorization for a transaction that establishes a new subscription, go to Initial Authorization Request.

To request authorization for a recurring transaction in an existing subscription, go to Subsequent Authorization Request.

Initial Authorization Request

A call to v1/merchant/transactions/authorize for the initial subscription transaction requires the following parameters:

• previous_transaction_id: Leave null. There is no previous transaction in this subscription because it is new.
• processing_initiator: Set to initial_recurring. This indicates that this transaction will be linked to recurring subscription transactions in the future.

The request body may use either of the following schemas, depending on whether it is an unsaved or saved payment method:

• MerchantCreditCardAuthorization: For authorizing a new, unsaved card. This can be for a guest checkout flow, one-time payment, or an existing Bolt user.
• MerchantCreditCardAuthorizationRecharge: For logged-in checkout flows using saved payment methods.

Subsequent Authorization Request

A call to v1/merchant/transactions/authorize for a subsequent subscription transaction must include the following parameters:

• previous_transaction_id: Set to the ID of the initial subscription transaction.
• processing_initiator: Set to following_recurring. This indicates that the merchant is initiating a subscription transaction and has permission from the cardholder to do so.

The request body should use the schema described in MerchantCreditCardAuthorizationRecharge with the same credit card ID as the initial transaction.

Optional Configuration

Embed Payment Method Selector

To enable shoppers to update their payment method from their merchant storefront account, refer to Select a New Payment Method for a Shopper’s Account and add this component to the page where a shopper can manage their subscriptions.

Considerations

In the guest checkout flow, when a shopper purchases a subscription, they must create a Bolt account. This is required because Bolt needs the ability to recharge the user for subsequent billing periods and store the correct payment information when a shopper updates their subscription payment method.

The account creation displays as required in checkout when a guest shopper has a subscription included in their cart. No further implementation steps are required to support this.