📍 Bolt Help / Add-Ons / Subscriptions / Bolt Subscriptions Implementation Guide

Bolt Subscriptions Implementation Guide

Bolt Subscriptions enables your shoppers to subscribe to recurring digital content purchases. This offering is available through direct API integration.

Before You Start

These instructions assume that you:

  • Have an active Bolt Merchant Account
  • Have reviewed Bolt’s API collection, specifically the Subscriptions endpoints /v1/subscriptions/
  • Have implemented Bolt SSO
  • Are directly offering subscriptions for digital goods

A Bolt administrator must enable the following feature flag for your merchant division:

  • DivisionFeatureWebhooksV2

Set Up Webhooks

Use the Webhook Configuration API to subscribe to the following event types:

  • subscription_created
  • subscription_cancelled
  • subscription_renewed

Implementation Overview

  1. Merchant configures subscription offers in their own system.
  2. Merchant configures the payment method updater embedded component on their user-facing subscription management page.
  3. When a shopper subscribes to an offer, the merchant’s system sends information about the offer to Bolt via the Subscription API.
    • Example offer information: Alex’s Best Subscription (#1234) at $5 initial month with $20 monthly rebill.
  4. Bolt subscription engine creates subscription and order records in our system.
    • Example subscription information: Jane Doe, #1234, CC**4584, $5/month, $20/month
    • Example order information: Jane Doe, #1234, CC**4584, 05-01-2022, $5
  5. Bolt subscription engine generates order renewal transactions at the specified frequency to keep the subscription current.

1. Set Up Offers

Use your subscription management system to configure subscription offers. Your system manages this information, and you’ll pass offer details to Bolt when a shopper subscribes.

2. Set Up Payment Method Selector

To enable subscribers to update the payment method associated with their subscriptions, add the payment method selector component to your storefront.

3. Create Subscription

Call Create Subscription /v1/subscriptions when a shopper signs up for a subscription.

Request

Send details about the subscription offer in the following objects:

offer.trial

Some offers may include an initial trial period during which the shopper receives a discount for a period of time. This optional object describes the price and duration for the trial period.

{
   "cart": {
      "total_amount": 500,
      "currency": "USD"
   },
   "frequency": {
      "unit": "week",
      "value": 1
   },
   "cycles": 1
}

offer.recurring

Describes the price and frequency that the subscription renews at, after any configured trial period.

{
   "cart": {
      "total_amount": 1000,
      "currency": "USD"
   },
   "frequency": {
      "unit": "month",
      "value": 1
   }
}

Webhooks

Subscription creation triggers a webhook notification.

{
   "type": "subscription_created",
   "object": "subscription",
   "data": {
      // bolt subscription id
      "id": "sb_a5109a5qa10519a11",
      // merchant subscription id
      "reference": "MERCH02222022",
      "merchant_division_id": "Mdiv90Abqzh",
      "subscriber_consumer_id": "AB3rJKam5DhYE",
      // bolt offer id
      "offer_id": "sf_bf871a59fx8gyy99u",
      // merchant offer id
      "offer_reference": "offer_jane_merchant.com_2",
      "status": "active",
      "initial_order_id": "sr_678az8auwsqa0290"
   }
}

Set up a handler to parse the following webhook data, at minimum:

  • id
  • offer_id
  • initial_order_id
  • status

You’ll need to store this data to keep your subscription management system updated with active subscriptions.

Subscriber Notification

Bolt notifies subscribers via email of a successful subscription.

4. Place Orders

Bolt manages subscription and order information, and handles rebills for each subscription renewal.

Since you have already provided the offer details, you don’t need to call an API to place orders — Bolt handles this automatically.

Initial Order

If the shopper placed their initial order at the time of subscription, Bolt also creates a subscription order.

Payment

The initial subscription order charges to the shopper’s default payment method. If a shopper does not have a card saved to their Bolt account, they need to enter their card information.

Renewal Orders

Bolt’s internal order engine automatically generates a new subscription order according to the frequency and price specified at the offer level.

Webhooks

Initial and renewal orders trigger webhook notifications:

{
   "type": "subscription_renewed",
   "object": "subscription_order",
   "data": {
      // for the first order, this is `initial_order_id` from the `subscription_created` hook
      "id": "sr_678az8auwsqa0290",
      "merchant_division_id": "Mdiv90Abqzh",
      // `id` from the `subscription_created` hook
      "subscription_id": "sb_a5109a5qa10519a11",
      // bolt order token
      "order_token": "a2b3dDc4cA5e6fg78Bg9hj0kl",
      // merchant order reference
      "order_reference": "offer_jane_merchant.com_2",
      "transaction_reference": "AAAA-FFFF-0000",
      "status": "charged",
      "next_bill_date": "2022-05-05"
   }
}

Set up a handler to parse the following webhook data, at minimum:

  • id
  • subscription_id
  • order_token

You’ll need to store this data to keep your subscription management system updated with renewal activity.

Subscriber Notification

Bolt sends the following notification emails to subscribers regarding renewals:

Notification When?
Alert that their subscription is about to renew 5 days prior to rebill
Confirmation of renewal On successful payment method recharge
Alert that their renewal was unsuccessful and a prompt to update their payment method On failed payment method recharge

Subscription Management

To enable shoppers to manage their own subscriptions, you must provide a subscription management user interface on your site.

Cancel Subscription

Call Cancel Subscription /v1/subscriptions/{api-id}/cancel when either the shopper or merchant terminates the subscription.

Parameters

You’ll pass the subscription ID as a path parameter. You can obtain this value from one of the following:

Webhooks

Subscription cancellation triggers a webhook notification:

{
   "type": "subscription_cancelled",
   "object": "subscription",
   "data": {
      // bolt id
      "id": "sb_a5109a5qa10519a11",
      // merchant id
      "reference": "MERCH02222022",
      "merchant_division_id": "Mdiv90Abqzh",
      "subscriber_consumer_id": "AB3rJKam5DhYE",
      // bolt id
      "offer_id": "sf_bf871a59fx8gyy99u",
      // merchant id
      "offer_reference": "offer_jane_merchant.com_2",
      "status": "cancelled"
   }
}

Set up a handler to parse the following webhook data, at minimum:

  • id
  • offer_id
  • status

You’ll need this data to keep your subscription management system updated with inactive subscriptions.

Cancel Offer

Call Cancel Offer /v1/subscriptions/offers/{api_id}/cancel to deactivate an offer and all associated subscriptions.

Parameters

You’ll pass the offer ID as a path parameter. You can obtain this value from the Create Subscription /v1/subscriptions API response or webhook payload.

Response

Set up a handler to parse the returned object data. You’ll need this data to handle offer cancellation in your subscription management system, and to keep your system updated with inactive subscriptions.

Because this endpoint processes a batch of cancellations, it is possible that a non-200 response could have successfully cancelled some of the subscriptions. If this is the case, the response body includes data about the cancelled subscriptions.

Subscriber Notification

Bolt notifies subscribers via email that their subscription to this offer has been cancelled.

Limitations

Bolt Subscriptions does not support the following:

  • Alternative payment methods
  • Physical goods
  • Commerce platforms
📖On This Page
Filter by Section
Filter by Topic