Create Subscriptions

The Create Subscription endpoint enables you to create subscriptions for a customer at any point in their user journey. Customers can subscribe in a myriad of ways: through email funnels, after one-time purchases, and many more.

This document contains reference information to help you call the Create Subscription endpoint of the Bold Subscriptions API and understand the potential error behavior.

note

Bold provides an open source example project that demonstrates the capabilities of this endpoint on the BigCommerce platform.

Before you make a request

1. Complete the steps outlined in the Subscriptions Getting Started guide.
2. Capture and tokenize the customer's payment details within your payment gateway. Connect the payment gateway account used to capture that information to the checkout you are using with Bold Subscriptions.

Making a request

In order to call the Create Subscription endpoint, your request must include the following:

• Customer data — including basic information about the customer.
• Subscription data — including information about the subscription, such as line items and the appropriate addresses.
  • Payment processing data — including information about your payment gateway and the corresponding payment method for the customer.

note

The Bold Subscriptions API requires a complete payload for the Create Subscription endpoint.

Handling the response

Idempotency

After receiving a request to create a subscription, Bold Subscriptions creates a subscription_creation_log_id for the request. This log maintains a record of which steps have been taken in the process of building a subscription. The log is also tied directly to the idempotency_key in your request. Therefore, if the API receives multiple requests for the same key, it always picks up where it left off, and no duplicate subscriptions are created.

If a subscription is successfully created and you post a subsequent request with the same idempotency_key, then the response you receive will contain a 200 status code and return the subscription that was previously created.

If your request fails and you receive an error response, the response contains the subscription_creation_log_id as well as current_subscription_creation_step, which indicates which step of the subscription creation process failed. All the possible values for this property, in the order in which they occur, are listed below:

Value	Always occurs?	Description
validation	Yes	Validating the payload for validity and completeness.
customer_creation	Yes	Checking whether the customer already exists on the platform (by customer email). If the customer already exists, no changes are made to the existing customer profile. If the customer does not exist, the customer is created.
customer_shipping_address_creation	Yes	Checking whether the shipping address for the customer already exists on the platform. Adding the customer shipping address if it does not.
customer_billing_address_creation	Yes	Checking whether the billing address for the customer already exists on the platform. Adding the customer billing address if it does not.
checkout_customer_creation	No	Creating a payment method for the customer.
subscription_creation	Yes	Creating the subscription for the customer. For Shopify Checkout users, the Bold Subscriptions API creates a subscription within the Shopify platform.

Choosing an idempotency key

Bold has the following recommendations for your choice of idempotency key:

• If you are coming from a third-party subscriptions app — Construct a string that includes the subscription ID from the legacy system. For example, you could use a value of "legacy-id-4328" to indicate that 4328 is the ID of the subscription on the old system.
• If you are creating a brand new subscription — Construct a unique alphanumeric string. If your request to create a subscription initially fails, reuse the same key for subsequent attempts to create the same subscription. This prevents duplicate subscriptions from being created due to network-related issues and allows you to save time on further attempts.

If you would like to repeat a Create subscription call with changes to the payload you provide, change the idempotency_key, and the Subscription API will start over with the process of creating a subscription.

Unexpected error responses

You may receive an error with a message that reads "Unexpected error." In this case, a step of subscription creation failed in a way the API did not account for.

If you experience an unexpected error, reach out to the Bold Commerce Partners Team, and provide the complete error response.

Frequently asked questions

How do I find payment gateway information for the PaymentDetails object?

Refer to the following table for details on how to find information about your checkout and gateway combination:

Checkout Type	Payment Gateways	gateway_name	gateway_customer_id	gateway_payment_id
Bold Checkout	Amazon Pay	Amazon Pay	Use the chargePermissionId or AmazonBillingAgreementId as the gateway_customer_id. For example, "C04-1234567-7654321".	N/A
Bold Checkout	Authorize.net	In the left-hand menu of the Bold Checkout app, click Payment options, then click Payment gateways. Under each of the payment gateways you connected to Bold Checkout, the gateway_name is the second line underneath the bolded text.	Use the format: {Customer Profile ID}-{Payment Profile ID}. For example, 12345678-87654321.	N/A
Bold Checkout	Braintree	Braintree Credit Card	Use the BraintreePaymentMethod.legacyId as the gateway_customer_id. For example, "6gbkd76".	N/A
Bold Checkout	Braintree PayPal	Braintree PayPal	Use the BraintreePaymentMethod.legacyId as the gateway_customer_id. For example, "94w7ycr".	N/A
Bold Checkout	Stripe	In the left-hand menu of the Bold Checkout app, click Payment options, then click Payment gateways. Under each of the payment gateways you connected to Bold Checkout, the gateway_name is the second line underneath the bolded text.	Use the Stripe customer ID as the gateway_customer_id. For example, "cus_a1b2c3d4e5f6g7h8".	N/A
Shopify Checkout	Shopify Payments (Shopify Payment Method)	shopify	Use the payment method ID as the gateway_customer_id. For example, "gid://shopify/CustomerPaymentMethod/[id]"	N/A
Shopify Checkout	Shopify Payments (Legacy Stripe)	stripe	Use the Stripe customer ID as the gateway_customer_id. For example, "cus_a1b2c3d4e5f6g7h8".	Use the Shopify payment method ID as the gateway_payment_id. For example, "pm_a1b2c3d4e5f6g7h8" or "card_a1b2c3d4e5f6g7h8".
Shopify Checkout	Shopify Payments (Legacy Braintree)	braintree	Use the customer ID as the gateway_customer_id. For example, gateway_customer_id: "6gbkd76"	Use the payment method token as the gateway_payment_id. For example, gateway_payment_id: "87654321"
Shopify Checkout	PayPal (Express)	paypal	Use the billing agreement ID as the gateway_customer_id. For example, gateway_customer_id: "B-1A2B3C4D5E6F7G8H"	N/A
Shopify Checkout	Authorize.net	authorize.net	Use the customer profile ID as the gateway_customer_id. For example, gateway_customer_id: "12345678"	Use the payment profile ID as the gateway_payment_id. For example, gateway_payment_id: "87654321"

Set up a secondary payment gateway with Shopify

If you currently use Stripe and are moving to use Bold Subscriptions for Shopify Checkout, you must connect Stripe as a secondary payment gateway. Failure to connect your legacy Stripe account to your store may result in payments not being processed. Use the following steps to make this connection:

1. Follow the instructions on the Connect a Legacy Stripe Account Before Migrating page in the Bold Help Center.
2. Follow the instructions on the Migrate Customer Information to Shopify page in the Shopify developer docs.

If you currently use Braintree and are moving to use Bold Subscriptions for Shopify Checkout, you must connect Braintree as a secondary payment gateway. Failure to connect your legacy Braintree account to your store may result in payments not being processed. Use the following steps to make this connection:

1. Request that Shopify enables the legacy_subscriptions_braintree beta flag on your store. Submit a support ticket if you would like the Bold Subscriptions Migrations team to coordinate this on your behalf.
2. Follow the instructions on the Migrate Customer Information to Shopify page in the Shopify developer docs.
3. Follow the instructions on the Connect a Legacy Braintree Account before Migrating page in the Bold Help Center.

Can I use a customer's card number, expiration date, and security code directly to create a subscription?

No. Bold does not directly handle customer payment information and instead requires the payment gateway's customer payment method tokens. These tokens are available for any customer who has a payment method registered in the payment gateway connected to your checkout provider. Learn more about PaymentDetails requirements.

How do I make phone numbers optional when using Shopify checkout?

If you're using Shopify Checkout and seeing errors that the phone number is required, there may be a conflicting phone number setting in the Shopify admin. In the left-hand menu of the Shopify admin, click Settings, then Checkout. In the Shipping address phone number section, you can configure phone number requirements. Keep in mind that this setting affects the customer storefront experience as well.

How do I find the subscription_group_id for a line item?

There are two ways to find the subscription_group_id of a line item:

• Programmatically, through the List Subscription Groups endpoint.
• Manually, in the Bold Subscriptions App: In the left-hand menu, click Subscription groups. In the table of subscription groups you see, you can find the subscription_group_id under the name of each subscription group.

How do I find the platform_product_id and platform_variant_id for a line item?

There are two ways to find these attributes of a line item:

• Programmatically:
  • Get the product's platform_product_id by calling the List Products endpoint; the platform_id returned in the data.products object of the List Products endpoint is the platform_product_id for that product.
  • After obtaining the platform_id using the List Products endpoint, call the List Product Variants endpoint and use the platform_id as the platform_product_id parameter. The response returns all the product variants for that platform_product_id.
• Manually, through the applicable platform: You can retrieve these attributes through the platform admin you are using:
  • Shopify instructions
  • BigCommerce instructions

What currencies are supported for creating subscriptions?

The base_currency is the base currency you configured in your platform's configuration. The charged_currency depends on the supported currencies based on your checkout type.

• For stores using Bold Checkout: In the left-hand menu of the Bold Checkout app, click Payment options, then Payment gateways. The supported currencies are listed beneath with the payment gateway(s) you have connected.
• For stores using Shopify Checkout: In the left-hand menu of the Shopify admin, click Settings, then General. The Store currency section shows the currency your store uses.