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
: Leavenull
. There is no previous transaction in this subscription because it is new.processing_initiator
: Set toinitial_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 tofollowing_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.