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.
Adding a Subscription to the Cart
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.
Have some thoughts? Let me know on twitter @jackabox.