Skip to main content

Manage subscription products on storefronts

You can use the Storefront API to retrieve subscription products on a storefront. Subscription products can be accessed from the sellingPlan object.

This guide shows you how to use the Storefront API to retrieve information about selling plans, including price adjustments and selling plan allocations. It also shows how to create a cart with a subscription line item.

Anchor to RequirementsRequirements

Note

You must use the cart workflow to retrieve subscription products.

Anchor to Step 1: Query selling plans for a productStep 1: Query selling plans for a product

To retrieve information about selling plans, query a product by its handle (handle). The sellingPlanGroups object associated with the product contains the individual selling plans, which include information such as delivery frequencies.

Anchor to Individual selling plansIndividual selling plans

Within the sellingPlans object, you can query the selling plan ID. This ID is used to identify which selling plan a customer has picked when they add a subscription product to their cart. You can also query whether purchasing the selling plan will result in multiple deliveries (recurringDeliveries).

The options field represents the selling plan options available in the drop-down list in the storefront.

Anchor to ExampleExample

The following example shows how to query a selling plan group associated with a product, and its individual selling plans. The requiresSellingPlan field is true, which means that the product can be purchased only as part of a selling plan.

Individual selling plans contribute their options to the associated selling plan group. In the following example, a selling plan group has an option called Delivery every. Each individual selling plan that belongs to the group contributes an option (1 week, 2 weeks, and 3 weeks) to the selling plan group.

POST https://{shop}.myshopify.com/api/{api_version}/graphql.json

GraphQL query

{
product(handle:"granola") {
requiresSellingPlan
sellingPlanGroups(first:1) {
edges {
node {
name
options {
name
values
}
sellingPlans(first: 3) {
edges {
node {
id
name
description
recurringDeliveries
options {
name
value
}
}
}
}
}
}
}
}
}

JSON response

{
"data": {
"product": {
"requiresSellingPlan": true,
"sellingPlanGroups": {
"edges": [
{
"node": {
"name": "Prepaid 6 weeks of granola",
"options": [
{
"name": "Delivery every",
"values": [
"1 week",
"2 weeks",
"3 weeks"
]
}
],
"sellingPlans": {
"edges": [
{
"node": {
"id": "gid://shopify/SellingPlan/1",
"name": "6 weeks of prepaid granola, delivered weekly",
"description": null,
"recurringDeliveries": true,
"options": [
{
"name": "Delivery every",
"value": "1 week"
}
]
},
}
{
"node": {
"id": "gid://shopify/SellingPlan/2",
"name": "6 weeks of prepaid granola, delivered every two weeks",
"description": null,
"recurringDeliveries": true,
"options": [
{
"name": "Delivery every",
"value": "2 weeks"
}
]
},
}
{
"node": {
"id": "gid://shopify/SellingPlan/3",
"name": "6 weeks of prepaid granola, delivered every three weeks",
"description": null,
"recurringDeliveries": true,
"options": [
{
"name": "Delivery every",
"value": "3 weeks"
}
]
}
}
]
}
}
}
]
}
}
}
}

Anchor to Step 2: Query price adjustments on variantsStep 2: Query price adjustments on variants

A product can have multiple variants and each variant can have up to two price adjustments. The priceAdjustments field represents how a selling plan affects pricing when a variant is purchased with a selling plan.

If a variant has multiple price adjustments, then the first price adjustment applies when the variant is initially purchased. The second price adjustment applies after a certain number of orders (specified by the orderCount field) are made.

If a selling plan doesn't have any price adjustments, then the unadjusted price of the variant is the effective price.

Anchor to Price adjustment valuesPrice adjustment values

The adjustmentValue field represents the type of price adjustment.

A variant can have the following types of price adjustment values:

  • SellingPlanPercentagePriceAdjustment: A percentage amount deducted from the original variant price when it's purchased with a selling plan. For example, 10% off.
  • SellingPlanFixedAmountPriceAdjustment: A specific amount deducted from the original variant price when it's purchased with a selling plan. For example, 10.00 USD off.
  • SellingPlanFixedPriceAdjustment: A fixed price adjustment for a variant that's purchased with a selling plan. For example, if the selling plan offers a 10% discount on a variant that's regularly priced at 60.00 USD, then the price is 54.00 USD (60.00 USD x 0.90).

Anchor to ExampleExample

The following example retrieves the price adjustment value types on a variant. The response shows a variant that has a 20% discount when it's purchased with a selling plan.

POST https://{shop}.myshopify.com/api/{api_version}/graphql.json

GraphQL query

{
product(handle:"granola") {
sellingPlanGroups(first: 1) {
edges {
node {
name
sellingPlans(first: 1) {
edges {
node {
id
name
description
recurringDeliveries
priceAdjustments {
orderCount
adjustmentValue {
__typename
... on SellingPlanPercentagePriceAdjustment {
adjustmentPercentage
}
... on SellingPlanFixedAmountPriceAdjustment {
adjustmentAmount {
amount
currencyCode
}
}
... on SellingPlanFixedPriceAdjustment {
price {
amount
currencyCode
}
}
}
}
}
}
}
}
}
}
}
}

JSON response

{
"data": {
"product": {
"requiresSellingPlan": true,
"sellingPlanGroups": {
"edges": [
{
"node": {
"name": "Prepaid 6 weeks of granola",
"sellingPlans": {
"edges": [
{
"node": {
"id": "gid://shopify/SellingPlan/1",
"name": "6 weeks of prepaid granola, delivered weekly",
"description": null,
"recurringDeliveries": true,
"priceAdjustments": [
{
"orderCount": null,
"adjustmentValue": {
"__typename": "SellingPlanPercentagePriceAdjustment",
"adjustmentPercentage": 20
}
}
]
}
}
]
}
}
}
]
}
}
}
}

Anchor to Step 3: Query selling plan allocations and variant pricesStep 3: Query selling plan allocations and variant prices

A selling plan allocation describes the effect that each selling plan has on variants when they're purchased. It other words, it represents the combination of a variant and a selling plan.

Anchor to PricesPrices

Selling plan allocations contain the resulting prices for variants when they're purchased with a specific selling plan:

  • price: The price that's paid when the purchase is made. For example, for a prepaid plan for 6 deliveries of 10.00 USD granola, where the customer gets 20% off, the price is 6 x 10 USD x 0.80 = 48.00 USD.

  • compareAtPrice: The price of the variant when it's purchased without a selling plan for the same number of deliveries. For example, 6 deliveries x 10 USD granola = 60.00 USD.

  • perDeliveryPrice: The effective price for a single delivery. For example, for a prepaid plan for 6 deliveries, where the price is 48.00 USD, the per delivery price is 8.00 USD.

  • unitPrice: The unit price of the variant associated with the selling plan. For example, a merchant might sell a subscription product in quantities or measurements. If the variant has no unit price, then this field returns null.

    Prices display in the customer's currency if the shop is configured for it. For example, if a customer in Canada tries to pay for a product on a storefront based in the United States, then prices display in CAD.

Anchor to ExampleExample

The following query shows how to retrieve information about a variant associated with a selling plan. The response shows the prices of the variant.

Without the selling plan, the variant price is 60.00 CAD (compareAtPrice). If the variant is purchased with a selling plan that provides a 20% discount, then the price is 48.00 CAD. The perDeliveryPrice is determined the price (48.00 CAD) divided by the number of deliveries (6), which equals 8.00 CAD per delivery.

POST https://{shop}.myshopify.com/api/{api_version}/graphql.json

GraphQL query

{
product(handle: "granola") {
variants(first: 1) {
edges {
node {
id
title
price {
amount
currencyCode
}
sellingPlanAllocations(first:1) {
edges {
node {
sellingPlan {
id
name
options {
name
value
}
}
priceAdjustments {
price {
amount
currencyCode
}
compareAtPrice {
amount
currencyCode
}
perDeliveryPrice {
amount
currencyCode
}
unitPrice {
amount
currencyCode
}
}
}
}
}
}
}
}
}
}

JSON response

{
"data": {
"product": {
"variants": {
"edges": [
{
"node": {
"id": "gid://shopify/ProductVariant/1",
"title": "Yummy granola!",
"price": {
"amount": "10.0",
"currencyCode": "CAD"
},
"sellingPlanAllocations": {
"edges": [
{
"node": {
"sellingPlan": {
"id": "gid://shopify/SellingPlan/1",
"name": "6 weeks of prepaid granola, delivered weekly",
"options": [
{
"name": "Delivery weekly",
"value": "Week"
}
]
},
"priceAdjustments": [
{
"price": {
"amount": "48.00",
"currencyCode": "CAD"
},
"compareAtPrice": {
"amount": "60.00",
"currencyCode": "CAD"
},
"perDeliveryPrice": {
"amount": "8.00",
"currencyCode": "CAD"
},
"unitPrice": null
}
]
}
}
]
}
}
}
]
}
}
}
}

Anchor to Step 4: Create a cart and a subscription line itemStep 4: Create a cart and a subscription line item

You can use the cartCreate mutation to create a cart that contains the purchase of a variant with a selling plan. In your input to the mutation, provide the line item quantity, variant ID, and selling plan ID.

In the following example, the response returns each cart line with the quantity, the variant (merchandise) purchased, and the selling plan that's associated with the variant. The resulting prices for the variant when it's purchased with the selling plan are also returned.

POST https://{shop}.myshopify.com/api/{api_version}/graphql.json

GraphQL mutation

mutation cartCreateMutation($cartInput: CartInput) {
cartCreate(input: $cartInput) {
cart {
id
lines(first: 250) {
edges {
node {
quantity
merchandise {
__typename
... on ProductVariant {
id
}
}
sellingPlanAllocation {
sellingPlan {
id
name
}
priceAdjustments {
price {
amount
}
compareAtPrice {
amount
}
perDeliveryPrice {
amount
}
}
}
}
}
}
}
}
}

Variables

{
"cartInput": {
"lines": [
{
"quantity": 1,
"merchandiseId": "gid://shopify/ProductVariant/3",
"sellingPlanId": "gid://shopify/SellingPlan/2"
}
]
}
}

JSON response

{
"data": {
"cartCreate": {
"cart": {
"id": "8a9des87d7f8s76a7s6d66f7s6",
"lines": [
{
"quantity": 1,
"merchandise": {
"__typename": "ProductVariant",
"id": "gid://shopify/ProductVariant/3"
},
"sellingPlanAllocation": {
"sellingPlan": {
"id": "gid://shopify/SellingPlan/2",
"name": "12 weeks of prepaid granola, delivered weekly"
},
"priceAdjustments": [
{
"price": {
"amount": "79.92"
},
"compareAtPrice": {
"amount": "120.0"
},
"perDeliveryPrice": {
"amount": "6.66"
}
}
]
}
}
]
}
}
}
}

Anchor to Next stepsNext steps

Was this page helpful?