Shopify's API recently (October 2021) received an update that allows for stores to both receive subscriptions for products add said subscriptions (selling plans) to the cart.

This is one of my most anticipated features and I was ecstatic to spend some time diving into the API changes and how I could use them in my project.

I'm hoping this article helps cover some of the key changes you may need to implement. Please note, we're not going into specifics of how you'd integrate these on your site but examples of how you'd query against the GraphQL API to get and send the data needed.

Prerequisites

Before you can start getting selling plan data with the API you'll need to set them up in your Shopify store.

To add subscriptions to products you can work with any multitude of apps that support the Shopify Checkout. This includes; ReCharge, Skio, Bold, and more.
Set up at least one subscription for the product or variant via the Shopify admin.
Be using Shopify Payments.

Fetching Selling Plans

Before you can do anything, you need to get the selling plans (subscriptions) available for a product. We can fetch these in a couple of ways.

Selling Plans By Product

Firstly, we can get all selling plans assigned to a single product. This is incredibly useful if you only sell simple products with no variations and want a one-off or selling plan.

The GraphQL Query for this may look something like the following.

{
	productByHandle(handle: "handle-here") {
	  id
	  sellingPlanGroups(first:1) {
	    edges {
	      node {
	        name
	        options {
	          name
	          values
	        }
	        sellingPlans(first: 3) {
	          edges {
	            node {
	              id
	              name
	              description
	              recurringDeliveries
	              options {
	                name
	                value
	              }
	            }
	          }
	        }
	      }
	    }
	  }
	}
}

Effectively, this the edges for Selling Plan Groups (which is singular if it's a simple product) and then gets all of the plans underneath that group.

If you only have one type of subscription you sell (e.g. Delivery every 4 weeks) the selling plans edge would only return one value.

We then fetch some nice information about each selling plan, including name, descriptions, etc. This is all completely optional but would allow us to architect our front-end with appropriate information.

Selling Plans by Variations

The second method to fetch the Selling Plans is to get a list of any that are assigned to a variant. I'd use this method if the site had products that are variable (e.g. T-shirts with different sizes) as you can fetch Selling Plans per each variant instead of the product as a whole.

This gives you a greater control over how you want the data to work and what should have a subscription available.

To fetch this data, we'd query something like the following.

{
	productByHandle(handle: "handle-here") {
	  id
	  variants(first: 10) {
	    edges {
	      node {
	        id
	        title
	        priceV2 {
	          amount
	          currencyCode
	        }
	        sellingPlanAllocations(first:1) {
	          edges {
	            node {
	              sellingPlan {
	                id
	                name
	                options {
	                  name
	                  value
	                }
	              }
		         }
		       }
	        }
	      }
	    }
	  }
	}
}

Both of the methods mentioned allow you to fetch the selling plans assigned to the product along with any more information needed. You can fetch much more data then the limited fields I've mentioned and can test this by playing around in the GraphQL playground here.

To actually let the user checkout, you're going to need to send that data back to the Storefront API. To do this you'll need the following data:

Selling Plan ID - ID of the Subscription
Merchandise ID - Variant/Product ID required
Quantity - How many you want to add

If you've used the Storefront API before, you've probably used the [checkout mutation]() to create a checkout for the user and pass this data back to Shopify.

However, if you're using Subscriptions you can no longer use the checkout mutation and have to use the [cart mutation](). There are a few minor differences to these but effectively they work the same.

To create a new cart for the user, your GraphQL mutation may look something like the following.

This example code was tested with using fetch in JS so the way you pass your variables may differ slightly.

Query:

mutation cartCreateMutation($cartInput: CartInput) {
	cartCreate(input: $cartInput) {
		cart {
			id,
			checkoutUrl
		}
	}
}

Variables:

cartInput: {
  lines: [
    {
      quantity: 1,
      merchandiseId: "Z2lkOi8vc2hvcGlmeS9Qcm9kdWN0VmFyaWFudC8zOTMyNzU3NjMyNjMzMg==",
      sellingPlanId: "Z2lkOi8vc2hvcGlmeS9TZWxsaW5nUGxhbi83MzI5MjIwNDQ="
    }
  ]
}

If successful, this will add the product to your cart with any necessary selling plan information. You can then use the `checkoutUrl` returned to redirect the user to the basket, or the ID to further manipulate this cart later.

Conclusion

Although this was a bit of a top-level overview, I hoped this helped you understand the way that you can use the Storefront API to both fetch and post data to your store for selling plans.

This is an awesome update to the API that allows for so much potential in the future.

Subscriptions & Selling Plans with Shopify's Storefront API

Table of Contents

Prerequisites

Fetching Selling Plans

Selling Plans By Product

Selling Plans by Variations

Conclusion