Subscriptions in Hydrogen
This recipe lets you sell subscription-based products on your Hydrogen storefront by implementing selling plan groups. Your customers will be able to choose between one-time purchases or recurring subscriptions for any products with available selling plans.
In this recipe you'll make the following changes:
- Set up a subscriptions app in your Shopify admin and add selling plans to any products that will be sold as subscriptions.
- Modify product detail pages to display subscription options with accurate pricing using the
SellingPlanSelectorcomponent. - Enhance GraphQL fragments to fetch all necessary selling plan data.
- Display subscription details on applicable line items in the cart.
- Add a Subscriptions page where customers can manage their subscriptions, which includes the option to cancel active subscriptions.
Anchor to RequirementsRequirements
To implement subscriptions in your own store, you need to install a subscriptions app in your Shopify admin. In this recipe, we'll use the Shopify Subscriptions app.
Anchor to IngredientsIngredients
New files added to the template by this recipe.
| File | Description |
|---|---|
| app/components/SellingPlanSelector.tsx | Displays the available subscription options on product pages. |
| app/graphql/customer-account/CustomerSubscriptionsMutations.ts | Mutations for managing customer subscriptions. |
| app/graphql/customer-account/CustomerSubscriptionsQuery.ts | Queries for managing customer subscriptions. |
| app/routes/account.subscriptions.tsx | Subscriptions management page. |
| app/styles/account-subscriptions.css | Subscriptions management page styles. |
| app/styles/selling-plan.css | Styles the SellingPlanSelector component. |
Anchor to Step 1: Set up the Shopify Subscriptions appStep 1: Set up the Shopify Subscriptions app
- Install the Shopify Subscriptions app.
- In your Shopify admin, use the Subscriptions app to create one or more subscription plans.
- On the Products page, open any products that will be sold as subscriptions and add the relevant subscription plans in the Purchase options section.
The Hydrogen demo storefront comes pre-configured with an example subscription product with the handle
shopify-wax.
Anchor to Step 2: Update CartLineItem to display subscription detailsStep 2: Update Cart
- Update import paths to use absolute paths for better consistency.
- Extract
sellingPlanAllocationfrom cart line data to access subscription information. - Display the subscription plan name when items have an active selling plan.
import {CartForm, Image, type OptimisticCartLine} from '@shopify/hydrogen';
import {useVariantUrl} from '~/lib/variants';
import {Link} from 'react-router';
-import {ProductPrice} from './ProductPrice';
-import {useAside} from './Aside';
+import {ProductPrice} from '~/components/ProductPrice';
+import {useAside} from '~/components/Aside';
import type {CartApiQueryFragment} from 'storefrontapi.generated';
type CartLine = OptimisticCartLine<CartApiQueryFragment>;
layout: CartLayout;
line: CartLine;
}) {
- const {id, merchandise} = line;
+ // Get the selling plan allocation
+ const {id, merchandise, sellingPlanAllocation} = line;
const {product, title, image, selectedOptions} = merchandise;
const lineItemUrl = useVariantUrl(product.handle, selectedOptions);
const {close} = useAside();
</Link>
<ProductPrice price={line?.cost?.totalAmount} />
<ul>
+ {/* Optionally render the selling plan name if available */}
+ {sellingPlanAllocation && (
+ <li key={sellingPlanAllocation.sellingPlan.name}>
+ <small>{sellingPlanAllocation.sellingPlan.name}</small>
+ </li>
+ )}
{selectedOptions.map((option) => (
<li key={option.name}>
<small>
Anchor to Step 3: Show subscription options on product pagesStep 3: Show subscription options on product pages
In this step we'll implement the ability to display subscription options on product pages, alongside the existing one-off purchase options.
Anchor to Step 3.1: Create a SellingPlanSelector componentStep 3.
Create a new SellingPlanSelector component that displays the available subscription options for a product.
File
import type {
ProductFragment,
SellingPlanGroupFragment,
SellingPlanFragment,
} from 'storefrontapi.generated';
import {useMemo} from 'react';
import {useLocation} from 'react-router';
/* Enriched sellingPlan type including isSelected and url */
export type SellingPlan = SellingPlanFragment & {
isSelected: boolean;
url: string;
};
/* Enriched sellingPlanGroup type including enriched SellingPlan nodes */
export type SellingPlanGroup = Omit<
SellingPlanGroupFragment,
'sellingPlans'
> & {
sellingPlans: {
nodes: SellingPlan[];
};
};
/**
* A component that simplifies selecting sellingPlans subscription options
* @example Example use
* ```ts
* <SellingPlanSelector
* sellingPlanGroups={sellingPlanGroups}
* selectedSellingPlanId={selectedSellingPlanId}
* >
* {({sellingPlanGroup}) => ( ...your sellingPlanGroup component )}
* </SellingPlanSelector>
* ```
**/
export function SellingPlanSelector({
sellingPlanGroups,
selectedSellingPlan,
children,
paramKey = 'selling_plan',
selectedVariant,
}: {
sellingPlanGroups: ProductFragment['sellingPlanGroups'];
selectedSellingPlan: SellingPlanFragment | null;
paramKey?: string;
selectedVariant: ProductFragment['selectedOrFirstAvailableVariant'];
children: (params: {
sellingPlanGroup: SellingPlanGroup;
selectedSellingPlan: SellingPlanFragment | null;
}) => React.ReactNode;
}) {
const {search, pathname} = useLocation();
const params = new URLSearchParams(search);
const planAllocationIds: string[] =
selectedVariant?.sellingPlanAllocations.nodes.map(
(node) => node.sellingPlan.id,
) ?? [];
return useMemo(
() =>
(sellingPlanGroups.nodes as SellingPlanGroup[])
// Filter out groups that don't have plans usable for the selected variant
.filter((group) => {
return group.sellingPlans.nodes.some((sellingPlan) =>
planAllocationIds.includes(sellingPlan.id),
);
})
.map((sellingPlanGroup) => {
// Augment each sellingPlan node with isSelected and url
const sellingPlans = sellingPlanGroup.sellingPlans.nodes
.map((sellingPlan: SellingPlan) => {
if (!sellingPlan?.id) {
console.warn(
'SellingPlanSelector: sellingPlan.id is missing in the product query',
);
return null;
}
if (!sellingPlan.id) {
return null;
}
params.set(paramKey, sellingPlan.id);
sellingPlan.isSelected =
selectedSellingPlan?.id === sellingPlan.id;
sellingPlan.url = `${pathname}?${params.toString()}`;
return sellingPlan;
})
.filter(Boolean) as SellingPlan[];
sellingPlanGroup.sellingPlans.nodes = sellingPlans;
return children({sellingPlanGroup, selectedSellingPlan});
}),
// eslint-disable-next-line react-hooks/exhaustive-deps
[
sellingPlanGroups,
children,
selectedSellingPlan,
paramKey,
pathname,
selectedVariant,
],
);
}
Anchor to Step 3.2: Add styles for the SellingPlanSelector componentStep 3.
Add styles for the SellingPlanSelector component.
File
.selling-plan-group {
margin-bottom: 1rem;
}
.selling-plan-group-title {
font-weight: 500;
margin-bottom: 0.5rem;
}
.selling-plan {
border: 1px solid;
display: inline-block;
padding: 1rem;
margin-right: 0.5rem;
line-height: 1;
padding-top: 0.25rem;
padding-bottom: 0.25rem;
border-bottom-width: 1.5px;
cursor: pointer;
transition: all 0.2s;
}
.selling-plan:hover {
text-decoration: none;
}
.selling-plan.selected {
border-color: #6b7280; /* Equivalent to 'border-gray-500' */
}
.selling-plan.unselected {
border-color: #fafafa; /* Equivalent to 'border-neutral-50' */
}
Anchor to Step 3.3: Update ProductForm to support subscriptionsStep 3.
- Add conditional rendering to display subscription options alongside the standard variant selectors.
- Implement
SellingPlanSelectorandSellingPlanGroupcomponents to handle subscription plan selection. - Update
AddToCartButtonto include selling plan data when subscriptions are selected.
File
} from '@shopify/hydrogen/storefront-api-types';
import {AddToCartButton} from './AddToCartButton';
import {useAside} from './Aside';
-import type {ProductFragment} from 'storefrontapi.generated';
+import type {
+ ProductFragment,
+ SellingPlanFragment,
+} from 'storefrontapi.generated';
+import {
+ SellingPlanSelector,
+ type SellingPlanGroup,
+} from '~/components/SellingPlanSelector';
export function ProductForm({
productOptions,
selectedVariant,
+ sellingPlanGroups,
+ selectedSellingPlan,
}: {
productOptions: MappedProductOptions[];
selectedVariant: ProductFragment['selectedOrFirstAvailableVariant'];
+ selectedSellingPlan: SellingPlanFragment | null;
+ sellingPlanGroups: ProductFragment['sellingPlanGroups'];
}) {
const navigate = useNavigate();
const {open} = useAside();
>
{selectedVariant?.availableForSale ? 'Add to cart' : 'Sold out'}
</AddToCartButton>
+ {sellingPlanGroups.nodes.length > 0 ? (
+ <>
+ <br />
+ <hr />
+ <br />
+ <h3>Subscription Options</h3>
+ <SellingPlanSelector
+ sellingPlanGroups={sellingPlanGroups}
+ selectedSellingPlan={selectedSellingPlan}
+ selectedVariant={selectedVariant}
+ >
+ {({sellingPlanGroup}) => (
+ <SellingPlanGroup
+ key={sellingPlanGroup.name}
+ sellingPlanGroup={sellingPlanGroup}
+ />
+ )}
+ </SellingPlanSelector>
+ <br />
+ <AddToCartButton
+ disabled={!selectedSellingPlan}
+ onClick={() => {
+ open('cart');
+ }}
+ lines={
+ selectedSellingPlan && selectedVariant
+ ? [
+ {
+ quantity: 1,
+ selectedVariant,
+ sellingPlanId: selectedSellingPlan.id,
+ merchandiseId: selectedVariant.id,
+ },
+ ]
+ : []
+ }
+ >
+ {selectedSellingPlan ? 'Subscribe' : 'Select Subscription'}
+ </AddToCartButton>
+ </>
+ ) : null}
</div>
);
}
</div>
);
}
+
+// Update as you see fit to match your design and requirements
+function SellingPlanGroup({
+ sellingPlanGroup,
+}: {
+ sellingPlanGroup: SellingPlanGroup;
+}) {
+ return (
+ <div className="selling-plan-group" key={sellingPlanGroup.name}>
+ <p className="selling-plan-group-title">
+ <strong>{sellingPlanGroup.name}:</strong>
+ </p>
+ {sellingPlanGroup.sellingPlans.nodes.map((sellingPlan) => {
+ return (
+ <Link
+ key={sellingPlan.id}
+ prefetch="intent"
+ to={sellingPlan.url}
+ className={`selling-plan ${
+ sellingPlan.isSelected ? 'selected' : 'unselected'
+ }`}
+ preventScrollReset
+ replace
+ >
+ <p>
+ {sellingPlan.options.map(
+ (option) => `${option.name} ${option.value}`,
+ )}
+ </p>
+ </Link>
+ );
+ })}
+ </div>
+ );
+}
Anchor to Step 3.4: Update ProductPrice to display subscription pricingStep 3.
- Add a
SellingPlanPricefunction to calculate adjusted prices based on subscription plan type (fixed amount, fixed price, or percentage). - Add logic to handle different price adjustment types and render the appropriate subscription price when a selling plan is selected.
File
+import type {CurrencyCode} from '@shopify/hydrogen/customer-account-api-types';
+import type {
+ ProductFragment,
+ SellingPlanFragment,
+} from 'storefrontapi.generated';
import {Money} from '@shopify/hydrogen';
import type {MoneyV2} from '@shopify/hydrogen/storefront-api-types';
export function ProductPrice({
price,
compareAtPrice,
+ selectedSellingPlan,
+ selectedVariant,
}: {
price?: MoneyV2;
compareAtPrice?: MoneyV2 | null;
+ selectedVariant?: ProductFragment['selectedOrFirstAvailableVariant'];
+ selectedSellingPlan?: SellingPlanFragment | null;
}) {
+ if (selectedSellingPlan) {
+ return (
+ <SellingPlanPrice
+ selectedSellingPlan={selectedSellingPlan}
+ selectedVariant={selectedVariant}
+ />
+ );
+ }
+
return (
<div className="product-price">
{compareAtPrice ? (
</div>
);
}
+
+type SellingPlanPrice = {
+ amount: number;
+ currencyCode: CurrencyCode;
+};
+
+/*
+ Render the selected selling plan price is available
+*/
+function SellingPlanPrice({
+ selectedSellingPlan,
+ selectedVariant,
+}: {
+ selectedSellingPlan: SellingPlanFragment;
+ selectedVariant: ProductFragment['selectedOrFirstAvailableVariant'];
+}) {
+ if (!selectedVariant) {
+ return null;
+ }
+
+ const sellingPlanPriceAdjustments = selectedSellingPlan?.priceAdjustments;
+
+ if (!sellingPlanPriceAdjustments?.length) {
+ return selectedVariant ? <Money data={selectedVariant.price} /> : null;
+ }
+
+ const selectedVariantPrice: SellingPlanPrice = {
+ amount: parseFloat(selectedVariant.price.amount),
+ currencyCode: selectedVariant.price.currencyCode,
+ };
+
+ const sellingPlanPrice: SellingPlanPrice = sellingPlanPriceAdjustments.reduce(
+ (acc, adjustment) => {
+ switch (adjustment.adjustmentValue.__typename) {
+ case 'SellingPlanFixedAmountPriceAdjustment':
+ return {
+ amount:
+ acc.amount +
+ parseFloat(adjustment.adjustmentValue.adjustmentAmount.amount),
+ currencyCode: acc.currencyCode,
+ };
+ case 'SellingPlanFixedPriceAdjustment':
+ return {
+ amount: parseFloat(adjustment.adjustmentValue.price.amount),
+ currencyCode: acc.currencyCode,
+ };
+ case 'SellingPlanPercentagePriceAdjustment':
+ return {
+ amount:
+ acc.amount *
+ (1 - adjustment.adjustmentValue.adjustmentPercentage / 100),
+ currencyCode: acc.currencyCode,
+ };
+ default:
+ return acc;
+ }
+ },
+ selectedVariantPrice,
+ );
+
+ return (
+ <div className="selling-plan-price">
+ <Money
+ data={{
+ amount: `${sellingPlanPrice.amount}`,
+ currencyCode: sellingPlanPrice.currencyCode,
+ }}
+ />
+ </div>
+ );
+}
Anchor to Step 3.5: Update the product page to display subscription optionsStep 3.
- Add the
SellingPlanSelectorcomponent to display subscription options on product pages. - Add logic to handle pricing adjustments, maintain selection state using URL parameters, and update the add-to-cart functionality.
- Fetch subscription data through the updated cart GraphQL fragments.
File
useLoaderData,
} from 'react-router';
import type {Route} from './+types/products.$handle';
+import type {SellingPlanFragment} from 'storefrontapi.generated';
import {
getSelectedProductOptions,
Analytics,
import {ProductForm} from '~/components/ProductForm';
import {redirectIfHandleIsLocalized} from '~/lib/redirect';
+import sellingPlanStyle from '~/styles/selling-plan.css?url';
+
+export const links: Route.LinksFunction = () => [
+ {rel: 'stylesheet', href: sellingPlanStyle},
+];
+
export const meta: Route.MetaFunction = ({data}) => {
return [
{title: `Hydrogen | ${data?.product.title ?? ''}`},
// The API handle might be localized, so redirect to the localized handle
redirectIfHandleIsLocalized(request, {handle, data: product});
+ // Initialize the selectedSellingPlan to null
+ let selectedSellingPlan = null;
+
+ // Get the selected selling plan id from the request url
+ const selectedSellingPlanId =
+ new URL(request.url).searchParams.get('selling_plan') ?? null;
+
+ // Get the selected selling plan bsed on the selectedSellingPlanId
+ if (selectedSellingPlanId) {
+ const selectedSellingPlanGroup =
+ product.sellingPlanGroups.nodes?.find((sellingPlanGroup) => {
Anchor to Step 4: Show subscription details in the cartStep 4: Show subscription details in the cart
In this step we'll implement support for showing subscription info in the cart's line items.
Anchor to Step 4.1: Add selling plan data to cart queriesStep 4.
Add sellingPlanAllocation field with the plan name to both the standard cart line and componentizable cart line GraphQL fragments. This ensures subscription details are fetched when querying cart data.
}
}
}
+ sellingPlanAllocation {
+ sellingPlan {
+ name
+ }
+ }
}
fragment CartLineComponent on ComponentizableCartLine {
id
}
}
}
+ sellingPlanAllocation {
+ sellingPlan {
+ name
+ }
+ }
}
fragment CartApiQuery on Cart {
updatedAt
Anchor to Step 5: Add subscription management to the account pageStep 5: Add subscription management to the account page
In this step we'll implement support for subscription management through an account subpage that lists existing subscription contracts.
Anchor to Step 5.1: Add queries to retrieve customer subscriptionsStep 5.
Create GraphQL queries that retrieve the subscription info from the customer account client.
File
// NOTE: https://shopify.dev/docs/api/customer/latest/queries/customer
const SUBSCRIPTION_CONTRACT_FRAGMENT = `#graphql
fragment SubscriptionContract on SubscriptionContract {
id
status
createdAt
billingPolicy {
...SubscriptionBillingPolicy
}
discounts(first: 20) {
nodes {
...SubscriptionDiscountFragment
}
}
}
fragment SubscriptionBillingPolicy on SubscriptionBillingPolicy {
interval
intervalCount {
count
precision
}
}
fragment SubscriptionDiscountFragment on SubscriptionDiscount {
id
title
recurringCycleLimit
value {
__typename
... on SubscriptionDiscountFixedAmountValue {
amount {
amount
}
}
... on SubscriptionDiscountPercentageValue {
percentage
}
}
}
` as const;
export const SUBSCRIPTIONS_CONTRACTS_QUERY = `#graphql
query SubscriptionsContractsQuery {
customer {
subscriptionContracts(first: 100) {
nodes {
...SubscriptionContract
lines(first: 100) {
nodes {
name
id
}
}
}
}
}
}
${SUBSCRIPTION_CONTRACT_FRAGMENT}
` as const;
Anchor to Step 5.2: Add mutations to cancel customer subscriptionsStep 5.
Create a GraqhQL mutation to cancel an existing subscription.
File
// NOTE: https://shopify.dev/docs/api/customer/latest/queries/customer
export const SUBSCRIPTION_CANCEL_MUTATION = `#graphql
mutation subscriptionContractCancel($subscriptionContractId: ID!) {
subscriptionContractCancel(subscriptionContractId: $subscriptionContractId) {
contract {
id
}
userErrors {
field
message
}
}
}
` as const;
Anchor to Step 5.3: Add an account subscriptions pageStep 5.
Create a new account subpage that lets customers manage their existing subscriptions based on the new GraphQL queries and mutations.
File
import type {
SubscriptionBillingPolicyFragment,
SubscriptionDiscountFragmentFragment,
SubscriptionsContractsQueryQuery,
} from 'customer-accountapi.generated';
import {
data,
useActionData,
useFetcher,
useLoaderData,
} from 'react-router';
import type {Route} from './+types/account.subscriptions';
import {SUBSCRIPTIONS_CONTRACTS_QUERY} from '../graphql/customer-account/CustomerSubscriptionsQuery';
import {SUBSCRIPTION_CANCEL_MUTATION} from '../graphql/customer-account/CustomerSubscriptionsMutations';
import accountSubscriptionsStyle from '~/styles/account-subscriptions.css?url';
export type ActionResponse = {
error: string | null;
};
export const meta: Route.MetaFunction = () => {
return [{title: 'Subscriptions'}];
};
export const links: Route.LinksFunction = () => [
{rel: 'stylesheet', href: accountSubscriptionsStyle},
];
export async function loader({context}: Route.LoaderArgs) {
await context.customerAccount.handleAuthStatus();
const {data: subscriptions} = await context.customerAccount.query(
SUBSCRIPTIONS_CONTRACTS_QUERY,
);
Add a Subscriptions link to the account menu so customers can easily access their subscription management page.
Addresses
</NavLink>
|
+ <NavLink to="/account/subscriptions" style={isActiveStyle}>
+ Subscriptions
+ </NavLink>
<Logout />
</nav>
);
Anchor to Step 5.5: Add styles for the Subscriptions pageStep 5.
Add styles for the Subscriptions page.
File
.account-subscriptions {
display: flex;
flex-direction: column;
gap: 10px;
}
.account-subscriptions .subscription-row {
display: flex;
gap: 10px;
align-items: center;
border: 1px solid lightgray;
padding: 10px;
}
.account-subscriptions .subscription-row .subscription-row-content {
display: flex;
gap: 10px;
flex: 1;
}
.account-subscriptions .subscription-row .subscription-row-actions {
display: flex;
gap: 10px;
align-items: center;
}
.account-subscriptions .subscription-row .subscription-status-active {
color: green;
}
.account-subscriptions .subscription-row .subscription-status-inactive {
color: gray;
}
.subscription-discounts {
margin-top: 0.5rem;
}
.subscription-discount {
display: inline-block;
background-color: #f0f0f0;
color: #333;
padding: 0.25rem 0.5rem;
border-radius: 4px;
font-size: 0.875rem;
margin-right: 0.5rem;
}
Anchor to Next stepsNext steps
- Test your implementation by going to your store and adding a subscription-based product to the cart. Make sure that the product's subscription details appear on the product page and in the cart.
- (Optional) Place a test order to see how orders for subscription-based products appear in your Shopify admin.
Was this page helpful?