A great customer-facing user experience (UX) for purchasing a subscription is important to the success of our merchants. This guide explains the key principles of subscription needs and component-level guidelines for implementing subscription user interfaces (UIs).

> Note:
> In order to be eligible for Built for Shopify status, subscription apps must adhere to the [subscription app Built for Shopify design requirements](/docs/apps/design/user-experience/subscription-apps).

## User experience principles

To provide a good experience when purchasing subscriptions and gain trust from customers, make sure to implement the following UX principles:

- **Create a visible hierarchy**: Customers should be able to clearly identify the savings of a subscription plan, the selling plan options, and the terms and conditions.
- **Disclose information progressively and logically**: Customers should have a sense of progression in subscription selection as their decisions clearly influence subsequent choices. Adapt the information shown in the customer flow to communicate subscriptions clearly and concisely.
- **Provide a seamless integration**: The subscriptions UI should be integrated into the theme’s existing design system.
- **Work with merchants' existing workflows**: Shopify provides the tooling for apps to build subscription experiences. Subscription experiences can be accessed directly from the Shopify admin. This allows merchants to access your app from the surface areas they are familiar with.
- **If a resource exists in Shopify, don't duplicate it in your app**: Shopify-managed resources such as customers, discounts, and products should be managed in a single place to reduce complex workflows and duplication.

## User interface guidelines

Before you integrate your subscription app into a theme, familiarize yourself with the UI guidelines and best practices that are associated with each component.

Apps should consider how subscription products appear in multiple places on the online store, such as product pages, collection pages, search results, featured product sections on the home page, and quick view modals on product cards. Surfacing potential subscription savings and pricing in these areas can further encourage customers to subscribe.

Subscription information is displayed in the following components of the online store:

- [Product forms](#product-forms)
- [Cart items](#cart-items)
- [Order details](#order-details)

The following sections include guidance for displaying prices, styling subscription UI components, and presenting multiple subscriptions. In each section, the relevant [Liquid](/docs/api/liquid) properties needed to create each component are also referenced.

## Product forms

The product form allows a customer to select their subscription. This is where the merchant can provide clarity and more details for a product and its available variants. Product forms are used in product pages, featured product sections on home pages, and quick view modals on product cards.

The subcomponents of a product form include the following:

- A. [Price](#price)
- B. [Selling plan selection](#selling-plan-selection)
- C. [Selling plan details](#selling-plan-details)
- D. [Main call-to-action](#main-call-to-action)

![Product form subcomponents screenshot](/assets/api/subscriptions/product-form-subcomponents.png)

### Price

Customers should be able to clearly identify the price of a subscription.

![Price subcomponent screenshot](/assets/api/subscriptions/price-subcomponent.png)

<table>
  <tr>
    <th>#</th>
    <th>UI element</th>
    <th>Liquid properties and information</th>
    <th>UI guidelines</th>
  </tr>
  <tr>
    <td>1</td>
    <td>Price</td>
    <td><code>selling_plan_allocation.price</code></td>
    <td rowspan="4">Reflect the price details from the selected subscription.</td>
  </tr>
  <tr>
    <td>2</td>
    <td>Compare at price</td>
    <td><code>selling_plan_allocation.compare_at_price</code></td>
  </tr>
  <tr>
    <td>3</td>
    <td>Per delivery price</td>
    <td><code>selling_plan_allocation.per_delivery_price</code>
    <br></br>
    Displays only when the value is different from <code>price</code>. This occurs when the selling plan is a prepaid subscription.</td>
  </tr>
  <tr>
    <td>4</td>
    <td>Unit price</td>
    <td><code>selling_plan_allocation.unit_price</code>
    <br></br>
    Unit price values may differ between <code>sellingPlanAllocations</code>. Unit measurement information is on the <code>variant</code> object, as it does not change based on <code>sellingPlan</code>.</td>
  </tr>
  <tr>
    <td>5</td>
    <td>Subscription badge</td>
    <td><code>selling_plan.recurring_deliveries</code>
    <br></br>
    The badge shown when the selling plan involves recurring deliveries (subscription).</td>
    <td>Provide a contextual subscription badge or label to help differentiate against a one-time subscription.
    <br></br>
    To reduce the clutter on a product page, don't display a badge when the item can only be purchased as a subscription. Rely on other ways to express this detail.
    </td>
  </tr>
  <tr>
    <td>6</td>
    <td>Price adjustment</td>
    <td><code>selling_plan.price_adjustment</code>
    <br></br>
    The object includes information on whether the adjustment is price or percentage based. This is used instead of sale price.</td>
    <td>
    Consider adding "subscription savings" details to highlight the subscription's value. For example, "Subscription - Save $3.00" or "Subscription - Save 10%".
    <br></br>
    For subscriptions with a pricing policy that changes over time, express the largest savings. For example, "Save up to 30%". For more information, refer to <a href="#communicating-changes-in-price-over-time">Communicating changes in price over time</a>.
    </td>
  </tr>
</table>

#### Pricing patterns

A subscription usually comes with savings to encourage customers to purchase products. Two common patterns for displaying a subscription's pricing information are a [main price component](#main-price-component) and [inline pricing](#inline-pricing). These patterns can be implemented at the same time in a design, but this can be a challenge in situations where you don't have control over the codebase for both the app and the theme.

> Tip:
> The [inline pricing pattern](#inline-pricing) is useful for subscription apps that integrate into a third-party theme codebase.

Regardless of your approach to displaying prices to customers, the following points should guide your implementation:

- The price of a subscription is clearly visible when a customer has selected a selling plan from a product form.
- For products with [unit pricing](https://help.shopify.com/en/manual/intro-to-shopify/initial-setup/sell-in-germany/price-per-unit), ensure that any change to the unit price from a subscription is displayed.
- If an item is a prepaid item, then display the price per delivery. This enables customers to better compare the price difference between one-time purchases and prepaid items.

##### Main price component

In this approach, there is a main price component on the page that's updated when a customer interacts with a selling plan selector and product variant selection.

To help customers understand the price of products that they purchase, do the following:

- Clearly display the subscription item's price and any applicable savings compared to the price of a one-time purchase.
- Add a subscription badge to the component to help clarify that the savings are conditional to the purchase of a subscription.

![Main price component screenshot](/assets/api/subscriptions/main-price-component.png)

##### Inline pricing

In this approach, pricing information is displayed inline or close to the selling plan selection. The price updates in response to changes in selling plan and product variant selection.

![Inline pricing screenshot](/assets/api/subscriptions/inline-pricing.png)

This approach makes a strong association between the effects of choosing a selling plan and the price. The positioning of the price is also preferable for mobile shopping, where smaller screen sizes mean that the main price component and price updates might not be in view.

This approach is useful for [subscription apps](/docs/apps/build/purchase-options/subscriptions) that integrate into the codebase of third-party themes. Because the pricing information is contained within a selling plan selector that the app controls and injects, this approach can help to avoid conflicts between the app's and the theme's respective scripts.

### Selling plan selection

Customers should be able to clearly identify their subscription options:

![Selling plan selection subcomponent screenshot](/assets/api/subscriptions/selling-plan-selection-subcomponent.png)

<table>
  <tr>
    <th>#</th>
    <th>UI element</th>
    <th>Liquid properties and information</th>
    <th>UI guidelines</th>
  </tr>
  <tr>
    <td>1</td>
    <td>subscriptions label</td>
    <td><code>product.requires_selling_plan</code>
    <br></br>
    <code>product.selling_plan_groups</code>
    </td>
    <td>One-time subscriptions and selling plan groups are considered different subscriptions. Use the term <strong>subscriptions</strong> in your own designs.</td>
  </tr>
  <tr>
    <td>2</td>
    <td>One-time subscription</td>
    <td><code>product.requires_selling_plan</code>
    <br></br>
    If the property is <code>false</code>, then at least 1 variant can be purchased as a one-time purchase and the one-time subscription should be presented in the UI.
    </td>
    <td rowspan="2"><strong>Group behavior</strong>
    <br></br>
    On the first page load, select the one-time subscription by default. When the customer interacts with the UI, consider collapsing the unselected group to make good usage of space. Disable the selling plan group selection when it isn't available for a given variant.
    <br></br>
    <strong>Group layout</strong>
    <br></br>
    Prioritize displaying subscriptions in a vertically stacked list to make them readable on all devices. When displayed side-by-side, the information can be crowded on smaller screens.
    <br></br>
    <strong>Group style</strong>
    <br></br>
    Consider displaying subscriptions as radio inputs instead of buttons. Buttons can easily compete with the product form’s call-to-action (submit button).
    </td>
  </tr>
  <tr>
    <td>3</td>
    <td>Selling plan group name</td>
    <td><code>selling_plan_group.name</code>
    <br></br>
    Always make this value visible. For more information, refer to <a href="#selling-plan-group-name">Selling plan group name</a>.</td>
  </tr>
  <tr>
    <td>4</td>
    <td>Inline price</td>
    <td><code>selling_plan_allocation.per_delivery_price</code>
    <br></br>
    Using the <code>per_delivery_price</code> is a more relevant comparison between prepaid subscriptions and one-time purchases.</td>
    <td>Showing the price of selling plans inline makes it easier for customers to compare subscriptions.
    <br></br>
    Show "each" next to the price for both one-time subscriptions and selling plan groups to maintain consistency and clarity among similar text information.
    <br></br>
    For subscriptions with a pricing policy that changes over time, add "from" before the inline pricing to clearly communicate the lowest price of the selling plan group. For example, "from $7.00". For more information, refer to <a href="#communicating-changes-in-price-over-time">Communicating changes in price over time</a>.
    </td>
  </tr>
  <tr>
    <td>5</td>
    <td>Selling plan option name</td>
    <td><code>selling_plan_option.name</code>
    <td>Contextualize the type of selling plan option.
    <br></br>
    <strong>Displaying selling plan options</strong>
    <br></br>
    Selling plan option values are often written in a way that assumes that the option name is also visible to the customer. For example:
    <br></br>
    <ul>
    <li>Name: "Delivery every"</li>
      <ul>
        <li>Option: "Month"</li>
        <li>Option: "Week"</li>
        </ul>
    </ul>
    Never hide the option names. Certain site designs will hide form labels to make a page look clean, but this can result in the values being presented with no context.
    </td>
  <tr>
    <td>6</td>
    <td>Selling plan option value</td>
    <td><code>selling_plan_option.value</code>
    <br></br>
    For more information, refer to <a href="#display-selling-plan-option-values">Display selling plan option values</a>.</td>
    <td>Don't express exact prices in option values, such as "Save $5 a week", because the values won't be accurate if the currency changes.
    <br></br>
    Expressing percentages is possible because they stay consistent even if the currency changes. For more information, refer to <a href="#considerations-for-currency-switching-and-price-rounding">Considerations for currency switching and price rounding</a>.</td>
  </tr>
</table>

#### subscriptions label

Show the **subscriptions** label when the following conditions apply:

- A one-time purchase exists and there's at least one `sellingPlanGroups`.
- A one-time purchase isn't an option, but there are multiple `sellingPlanGroups`.

Shopify doesn't show the **subscriptions** label when the following conditions apply:

- There are no selling plan groups.
- The product is subscription-only and there's only 1 selling plan group. In this case, the `sellingPlanGroup`’s name remains in its position, but without the radio input.

#### Subscription-only use case

Keep the selling group name and the inline price within the selector container. This sustains a stronger relationship between subscription selection and `per_delivery_price`, and  maintains a consistent approach across different use cases:

![Subscription-only use case screenshot](/assets/api/subscriptions/subscription-only-use-case.png)

#### Selling plan group name

Selling plan names should make clear the benefit of signing up for a subscription. For example, "Subscribe and save 10%". This incentivizes customers to make a bigger commitment in comparison to one-time subscriptions.

Because the [Selling plan API](/docs/api/admin-graphql/latest/objects/sellingplan) allows for multiple selling plan groups on a product, selling plan group names are used to differentiate subscriptions.

#### Display selling plan option values

It's required to display all of the option values at a glance from a group. Consider adapting the component layout to optimize readability.

Components should adapt to the number of options being shown. When there are many options to choose from, an appropriate component should be selected to enable customers to view all options easily. Where there is a small number of options, a different component may be used. When possible, apply the appropriate layout to all values within a selling plan group for consistency:

- **4 options or less**: Show each option as a radio button to allow customers to view what’s available.
- **More than 4 options**: Use a select dropdown to emphasize the customer's selection and hide other options within the collapsed dropdown.

##### UI update on variant change

A product’s variants might not all support the same subscription options. As a customer changes their variant selection, the components should update to make clear which subscription options are available and unavailable.

When a selected option within a selling plan group is unavailable, three events should happen:

- The unavailable options become unselected and require the customer to make a new selection to successfully submit the form.
- The unavailable options for the selected variant are disabled.
- The form submission button is enabled. Disabling the button removes the ability to display an error message and instead displays the product as unavailable, which is false. Let the customer click the button but prevent them from adding the product to the cart. Then, anchor and scroll back to the faulty UI area and display a message that describes why the process can't complete and what the customer needs to do to proceed.

### Selling plan details

Display important subscription terms and selections to customers. The subscription summary confirms a customer's selections, shows any conditions, and helps build trust in the brand.

![Selling plan details subcomponent screenshot](/assets/api/subscriptions/selling-plan-details-subcomponent.png)

<table>
  <tr>
    <th>#</th>
    <th>UI element</th>
    <th>API properties and information</th>
    <th>UI guidelines</th>
  </tr>
  <tr>
    <td>1</td>
    <td>Recurring price line</td>
    <td><code>selling_plan_allocation.price_adjustments</code>
    <br></br>
    <code>selling_plan.price_adjustments </code>
    <br></br>
    The <code>selling_plan</code> contains information on how a plan affects product prices, while the <code>selling_plan_allocation</code> describes the price for the variant to which the selling plan is applied.</td>
    <td>Express the number of payment cycles at the current price, and communicate what the price will be in the future. For example, first payment $6.00, then $9.00.
    <br></br>
    Include the word "each" to clarify when the number of independent recurring payment cycles is greater than 1. For example, first 3 payments $7.00 each, then $9.00.
    <br></br>
    Use "free" when the value is $0.00. This mirrors natural speech and helps customers understand the element. For example, first payment free, then $9.00.
    </td>
  </tr>
  <tr>
    <td>2</td>
    <td>Selling plan description</td>
    <td><code>selling_plan.description</code>
    <br></br>
    Merchants might use this field for promotional text. For example, they might use it for marketing terms, a call-to-action, or preemptively answering questions about cancellation policies or refunds.
    <br></br>
    For more information, refer to <a href="#subscription-policy-link">Subscription policy link</a>.
    </td>
    <td>Don't express exact prices in option values, for example, "Save $5 a week". For more information, refer to <a href="#considerations-for-currency-switching-and-price-rounding">Considerations for currency switching and price rounding</a>.
    <br></br>
    Consider including a link to the subscription policy in the description. Merchants might have a more detailed subscription policy that needs to be accessed by customers.
    <br></br>
    For subscriptions with a pricing policy that changes over time, for example, "First month free, then save 10% on renewals", communicate any future price changes clearly on the product page. For more information, refer to <a href="#communicating-changes-in-price-over-time">Communicating changes in price over time</a>.
    </td>
  </tr>
</table>

#### Communicating changes in price over time

Selling plans can have multiple price policies, which allows for the price of a subscription item to change after a certain period. A common approach is to encourage purchases with a lower initial price, for example, "Save $10 on the first 3 deliveries."

If an initial price incentive is applied to a subscription, then explain the current payment and how payments will change in the future.

It’s important to be transparent. A lack of information can cause customer mistrust and might appear misleading. Certain states and countries have laws around price clarity, which means that merchants might be subject to lawsuits.

#### Subscription policy link

In the [mockup](#selling-plan-details), the link to **View subscription policy** is part of the selling plan description and therefore in the merchant’s or app’s control to provide. The intention is to allow individual selling plans to provide a link out to a dedicated URL, if available.

The`shop.subscription_policy` object available in Liquid makes it possible to link to a dedicated `/policies/subscription-policy` page. The content of the page is editable by the merchant in the Shopify admin under Legal settings (`/admin/settings/legal`). The content of the subscription policy is also available at checkout.

### Main call-to-action

Having a call-to-action that reflects the subscription type helps customers differentiate between subscription options and the one-time subscription.

![Main call to action subcomponent screenshot](/assets/api/subscriptions/main-call-to-action-subcomponent.png)

<table>
  <tr>
    <th>#</th>
    <th>UI element</th>
    <th>API properties and information</th>
    <th>UI guidelines</th>
  </tr>
  <tr>
    <td>1</td>
    <td>Call-to-action</td>
    <td>On first page load, if the product requires a selling plan or one is selected, then switch the call-to-action string to something subscription-specific that merchants can customize.
    </td>
    <td>Update the call-to-action label to <strong>Add subscription to cart</strong> for a subscription subscription.
    </td>
  </tr>
</table>

## Cart items

Each subscription item displays the most important subscription details to help customers understand their purchase. Customers should be able to understand a subscription’s delivery frequency and, if applicable, the commitment period. The price should also match what is represented on the product page.

The subcomponents of a cart item include the following:

- [Cart page](#cart-page)
- [Cart notification](#cart-notification)

### Cart page

Customers tend to scan the cart page and review the information before proceeding to checkout:

![Cart page screenshot](/assets/api/subscriptions/cart-page.png)

<table>
  <tr>
    <th>#</th>
    <th>UI element</th>
    <th>API properties and information</th>
    <th>UI guidelines</th>
  </tr>
  <tr>
    <td>1</td>
    <td>Selling plan information</td>
    <td><code>line_item.selling_plan_allocation.selling_plan.name</code>
    <br></br>
    Use <code>selling_plan.name</code> in the cart line item. This same text is used at checkout. For more information, refer to <a href="#using-the-selling-plan-name">Using the selling plan name</a>.
    </td>
    <td>Because the selling plan name is meant to accurately summarize the subscription, don't list the individual selling plan option values alongside the selling plan name.
    </td>
  </tr>
</table>

### Cart notification

The cart notification returns information about the item that was just added to the cart:

![Cart notification screenshot](/assets/api/subscriptions/cart-notification.png)

<table>
  <tr>
    <th>#</th>
    <th>UI element</th>
    <th>API properties and information</th>
    <th>UI guidelines</th>
  </tr>
  <tr>
    <td>1</td>
    <td>Selling plan information</td>
    <td><code>line_item.selling_plan_allocation.selling_plan.name</code>
    <br></br>
    This information comes from a Cart API JSON response.
    <br></br>
    Use <code>selling_plan.name</code> in the order line item. The same text is used at checkout. For more information, refer to <a href="#using-the-selling-plan-name">Using the selling plan name</a>.
    </td>
    <td>Because the selling plan name is meant to accurately summarize the subscription, don't list the individual selling plan option values alongside the selling plan name.
    </td>
  </tr>
</table>

#### Using the selling plan name

The `selling_plan.name` should be a succinct description of the selling plan that can be easily understood by customers. The text is displayed in multiple areas of the online store, such as cart line items, checkout, and past order details. The value is also displayed in the merchant’s internal admin on order pages.

> Note:
> The selling plan name shouldn't be an additional opportunity to write marketing text.

Shopify doesn't control the value of the name, which means that merchants can enter any text value they want using an app.

When creating selling plan names, implement the following recommended guidelines:

- State the delivery frequency and a prepaid period, if applicable.
- Don't state exact dollars amounts, for example, "$9 a month". Use percentages when applicable.

#### Considerations for currency switching and price rounding

Merchants can sell in [multiple currencies on their online store](https://help.shopify.com/en/manual/payments/shopify-payments/multi-currency/setup).

When a customer visits the online store, Shopify presents the currency that's determined appropriate for the customer. Online stores can offer [a currency selector](/docs/api/liquid/tags/form#form-localization) to customers to enable them to manually switch the currency. Shopify also offers a price rounding feature to merchants, which allows merchants to set custom rounding rules for converted prices.

Apps and merchants shouldn't write any prices in the various strings that are shown to customers, for example, selling plan names that say "$9.99 a month" or "Save $5". Any prices that are written in these strings won't reflect currency switching or price rounding, and might be incorrect or misleading to customers.

When an app or merchant wants to express savings in a text field, use percentages whenever possible. For example, `"Deliver every week (Save 20%)"`.

> Note:
> Price properties returned from APIs of the Online Store (Liquid or JSON) reflect the currency of the customer's session and any price rounding rules.

## Order details

Customers logged in to the store can view the details of each past order. It's important to let the customer easily identify the subscription product.

![Order details screenshot](/assets/api/subscriptions/order-details.png)

<table>
  <tr>
    <th>#</th>
    <th>UI element</th>
    <th>API properties and information</th>
    <th>UI guidelines</th>
  </tr>
  <tr>
    <td>1</td>
    <td>Selling plan information</td>
    <td><code>line_item.selling_plan_allocation.selling_plan.name</code>
    <br></br>
    Use <code>selling_plan.name</code> in the cart notification line item. The same text is used at checkout. For more information, refer to <a href="#using-the-selling-plan-name">Using the selling plan name</a>.
    </td>
    <td>Because the selling plan name is meant to accurately summarize the subscription, don't list the individual selling plan option values alongside the selling plan name.
    </td>
  </tr>
</table>

## Next steps

- [Create and manage selling plans](/docs/apps/build/purchase-options/subscriptions/selling-plans): Follow a step-by-step workflow to create and manage selling plans in your subscription app.
- [Getting started building a product subscription app extension](/docs/apps/build/purchase-options/product-subscription-app-extensions/start-building): Learn how to create a new product subscription app extension with App Bridge Admin, connect the extension to Shopify, and render your working code inside Shopify's UI.