Subscription example

In this tutorial, you'll learn how to update your app server and extension code to make the following offers:

  • add a subscription to an order from the post-purchase page
  • add a one-time purchase to an order when a subscription is in the initial purchase

This tutorial builds on the upsell example tutorial, and we recommend that you familiarize yourself with that tutorial first.

Overview of a post-purchase subscription added to a single item

Limitations

You can't create a post-purchase subscription that does the following:

  • modifies a subscription on an order with an existing subscription
  • adds a subscription to an order with an existing subscription
  • converts a one-time purchase into a subscription order

Requirements

Before you add a subscription to your post-purchase app extension you need to create a subscription selling plan group. For this tutorial, make sure that the selling plan group is associated to the same product you used for the upsell example.

Step 1: Add subscriptions to your server code

Update the app server code that you created in the post-purchase upsell example to add a query for selling plan information. The app server code is available in the GraphQL Admin API version 2021-10 and higher.

SellingPlanID

When you define your post-purchase funnel you can use the Shopify GraphQL Admin API to query the SellingPlanGroup and select the appropriate selling plans to offer using the SellingPlanID.

Step 2: Update your extension code to add a subscription request

Replace the content of your extension script with the following code.

How the example extension code works

The following sections explain how different parts of the example extension code in Step 2 works.

Creating a list of purchase options

To let buyers decide which selling plan to use with their product, Shopify generates a list of purchase options based on the selling plans and disponibility of the product. Since some products are only available with a selling plan, Shopify also checks the requiresSubscription field provided by the GraphQL Admin API to add a one-time purchase option.

To add a selling plan during a post-purchase offer, you need to use the add_subscription change when calculating and applying a changeset. This lets you provide the selected selling plan and also add a discount, an initialShippingPrice, and a recurringShippingPrice.

Showing the selling plan options

To show the selling plan options to buyers, you need to use the Select component. When a buyer selects a new selling plan, we update the value of the selected purchase option.

After you've updated the code, the selling plan option renders as follows:

Selling plan option picker

Updating the price breakdown

To show the price breakdown matching the currently selected purchase option, you need to call calculateChangeset when the buyer selects a selling plan:

After you've updated the code, the price breakdown renders as follows:

Price breakdown including subtotal, shipping and taxes

Showing a recurring subtotal

When a purchase option contains a selling plan and has a billing interval, you need to display the recurring subtotal of the order.

After you've updated the code, the recurring subtotal renders as follows:

Recurring subtotal price and explanation

To add a subscription item to an order, the buyer’s payment method must be vaulted for future billing cycles of the subscription. Before you can vault the buyer's payment method, the buyer has to explicitly give consent to the subscription policies. Use the BuyerConsent component in App Bridge to collect consent:

This component creates a checkbox and a link to the subscription policies.

The checkbox where buyers can give their consent to adding a subscription

Applying the AddSubscription change

For the add_subscription change to be accepted, the value of the buyer consent checkbox needs to be provided as a new parameter to the applyChangeset method. Without this parameter, the changeset won’t be applied and an error is returned.

Next steps