Customer accounts offer a secure and flexible way for customers to manage their information and orders. Accounts empower customers with greater control over post-purchase surfaces and create opportunities for merchants to drive more sales with features like offers, wishlists, product offers, and loyalty programs.

All apps should follow the general guidance provided by the [App Design Guidelines](/docs/apps/design-guidelines). This guide provides additional guidance for designing customer account UI extensions.

## Merchant-to-customer content

When you write UI content for your customer account app, you’re writing directly to a merchant’s customers. The content that you write should represent the merchant, not your app, and should optimize the customer’s online experience.

Consult Polaris for more guidelines on voice, tone, and vocabulary to consider for [merchant-to-customer](https://polaris.shopify.com/content/merchant-to-customer) content.

## Principles

**Enable self-service**: Self-service options help customers resolve issues faster and reduce merchant support interactions.

**Design for consistency**: Merchants can use different apps to enhance their customer account interface. Because your app operates alongside other apps, it's important to ensure a familiar user experience. Avoid introducing unfamiliar UX patterns, terms, or navigation paradigms that deviate from our guidelines. Aim to integrate your app seamlessly into the existing customer account experience.

![On the left is the Order index page in customer accounts, and on the right is a Wishlist page full-page extension. Both pages use the ResourceItem component to create a consistent look and feel.](/assets/apps/customer-accounts/ux-guidelines/principles_design_for_consistency.png)

**Personalize when possible**: Customer account extensions benefit from authenticated access to customer data. Use this data to personalize the customer experience and create delightful moments. For example, offer complementary products, birthday discounts, or personalize content with the customer's name. Be creative, but respect privacy.

![A card is shown at the top of the order index page that says, "Hey Michelle, enjoy 40% of all products and 1,000 bonus points with code OFF40!"](/assets/apps/customer-accounts/ux-guidelines/principles_personalize_when_possible.png)

**Don't expose your brand to the customer**: Enhance the merchant's brand subtly and effectively. At all times, aim to create a seamless and consistent experience that makes customers feel like they're interacting directly with the merchant.

![Do and Don't examples of a design for a referral program. The Don't example shows "Supported by RewardWise®" at the bottom of the card, revealing the app's branding. The Do example does not contain the app's brand name.](/assets/apps/customer-accounts/ux-guidelines/principles_dont_expose_your_brand_to_the_customer.png)

**Build for scale**: Design your app to support merchants of all sizes, from small startups to large enterprises. Ensure that your app effectively handles both low and high order volumes.

## Responsive design

Design interfaces that [adapt to different screen sizes](/docs/api/checkout-ui-extensions/unstable/components/utilities/stylehelper). Your app should offer a good UX across mobile, tablet, and desktop devices. Test the extension on various screen sizes to ensure content adjusts appropriately for each device.

<video style="width: 100%; height: auto;" autoplay muted loop controls aria-label="An animation showing how the grid view of the Order index page shifts at different breakpoints. On desktop, 3 orders are shown per row. On tablet, 2 orders are shown per row. On mobile,1 order card is shown per row.">
  <source src="/assets/apps/customer-accounts/ux-guidelines/screen-adapt-orderlist.mp4" type="video/mp4">
</video>

## Grid layouts

Grid layouts enable responsive design for different screen sizes, and streamline development while enhancing the overall aesthetics of the customer experience. Grid layouts also ensure that elements are spaced, aligned, and positioned consistently.

Customer account pages are made up of columns, gutters, and margins. The design is based on a 12-column grid.

<video style="width: 100%; height: auto;" autoplay muted loop controls aria-label="An animation showing how the grid shifts at different breakpoints per device type—desktop, tablet, and mobile.">
  <source src="/assets/apps/customer-accounts/ux-guidelines/grid-adaptive-screen.mp4" type="video/mp4">
</video>

The following are the grid breakpoints per device type:

- **Mobile**: `375 dp` breakpoint, six column grid, one column content
- **Tablet**: `750 dp` breakpoint, six column grid, one column content
- **Small laptop**: `1000 dp` breakpoint, six column grid, two column content

When you design your page layout, you should generally space the content evenly across the grid columns. For example, in a three-column layout, each column of content would span four columns of the grid. However, to create a layout similar to the **Order status** page, the first column of content should span seven columns and the second should span five columns.

![An example showing that in order to achieve a similar layout to the Order status page, the first column of content should span seven columns, and the second should span five columns.](/assets/apps/customer-accounts/ux-guidelines/layout.png)

## Fulfillment statuses

### Conditional logic based on status

Design your apps so that merchants have the flexibility to determine where an action displays.

For example, for order actions that only become relevant once the customer has received the order, like requesting a return or writing a review, ideally customer's can’t take action until the order is marked as delivered. However, when merchants don't provide a tracking number for a fulfilled order, it can be difficult for Shopify to know when the order has been delivered. In these instances, customer wouldn't have access to actions that depend on an order's delivered status. Be mindful of situations like this, and enable merchants to configure your app to suit their fulfillment processes.

### Content guidelines

#### Status names

- Aim for one to three words.
- Use sentence case.

### Test different fulfillment scenarios

We recommend testing your **Order status** page extensions across different fulfillment states. The following are some examples:

- Different delivery statuses, such as confirmed, on its way, and delivered.
- Partial fulfillments
- Multiple fulfillments
- Local pickup
- Gift cards
- Digital products
- Returns

![Various states of the order status timeline. Some examples show a tracking number and estimated delivery date, when available. One example shows a local pickup order in the Ready for pickup status. Other examples show orders in the Confirmed, Canceled, On its way, and Delivered statuses. ](/assets/apps/customer-accounts/ux-guidelines/fulfillment-statuses.png)

## Payment statuses

Depending on the payment status of an order, a payment card will display above the order summary. For example, when a customer has made a purchase with Net 90 payment terms, they have 90 days to submit payment. In this scenario, the payment card displays the amount due, the due date, and a **Pay now** button.

### Test different payment scenarios

We recommend testing your **Order status** page extensions across different payment statuses. The following are some example statuses:

- Payment terms
- Partial payment
- Refund
- Paid

![A payment status card that says CAD $550.00 Payment due Sep 14, with a Pay now button.](/assets/apps/customer-accounts/ux-guidelines/payment-statuses.png)

## User feedback and informational banners

### Error messages

Error messages should help the customer understand what went wrong and how they can resolve the error.

Create error messages using a [`Banner`](/docs/api/checkout-ui-extensions/components/feedback/banner) component with the `alert` or `critical` `status` prop.

Don't use toasts for error messages. Since toasts disappear, customers lose access to the information that they need to move forward.

Learn more about [error handling](/docs/api/checkout-ui-extensions/unstable/error-handling).

![A yellow banner in the warning status that says "Payment due in 10 days" and a red banner in the critical status that says "Internet connection lost".](/assets/apps/customer-accounts/ux-guidelines/urgent-banner.png)

### Informational banners

Create informational banners using a [`Banner`](/docs/api/checkout-ui-extensions/components/feedback/banner) component with the `info` `status` prop.

![A blue banner in the info status that says "1000 points earned".](/assets/apps/customer-accounts/ux-guidelines/info-banner.png)

To build a more neutral banner, without the icons and colors that are associated with the different props, the following are some examples of components that you can use:

- [Card](/docs/api/customer-account-ui-extensions/latest/components/card): Customer account
- [Heading](/docs/api/checkout-ui-extensions/components/titles-and-text/heading): Heading 2
- [Text](/docs/api/checkout-ui-extensions/components/titles-and-text/text): Default
- [Button](/docs/api/checkout-ui-extensions/components/actions/button): Secondary

These components adopt the merchant's branding by default, which helps your banner align with the overall look and feel of the merchant's shop.

![A card that contains a header that says "$10 off your next purchase!" with a button that says Redeem now.](/assets/apps/customer-accounts/ux-guidelines/neutral-banner.png)

## Next steps

<div class="resource-card-grid">
  <div>
  <a class="resource-card" href="https://www.figma.com/community/file/1304881365343613949/checkout-and-account-components" data-theme-mode="">
    <div class="resource-card__indicator-container"><img
     src="/assets/resource-cards/blocks"
     data-alt-src="/assets/resource-cards/blocks-dark"
     aria-hidden="true"
     class="resource-card__icon themed-image"></div>
    <h3 class="resource-card__title">
      Figma UI kit
    </h3>
    <p class="resource-card__description">Everything you need to start designing with customer account and checkout components.</p>
  </a>
</div></p>

<p><div>
  <a class="resource-card" href="https://www.figma.com/community/file/1304882873974540289/account-screens" data-theme-mode="">
    <div class="resource-card__indicator-container"><img
     src="/assets/resource-cards/blocks"
     data-alt-src="/assets/resource-cards/blocks-dark"
     aria-hidden="true"
     class="resource-card__icon themed-image"></div>
    <h3 class="resource-card__title">
      Figma: Account screens
    </h3>
    <p class="resource-card__description">Explore all the customer account screens to design your extensions.</p>
  </a>
</div></p>

<p><div>
  <a class="resource-card" href="/docs/api/customer-account-ui-extensions/components" data-theme-mode="">
    <div class="resource-card__indicator-container"><img
     src="/assets/resource-cards/library"
     data-alt-src="/assets/resource-cards/library-dark"
     aria-hidden="true"
     class="resource-card__icon themed-image"></div>
    <h3 class="resource-card__title">
      Customer account components
    </h3>
    <p class="resource-card__description">Learn about the components that you can use to build customer account UI extensions.</p>
  </a>
</div></p>

<p><div>
  <a class="resource-card" href="/docs/api/checkout-ui-extensions/components" data-theme-mode="">
    <div class="resource-card__indicator-container"><img
     src="/assets/resource-cards/cart"
     data-alt-src="/assets/resource-cards/cart-dark"
     aria-hidden="true"
     class="resource-card__icon themed-image"></div>
    <h3 class="resource-card__title">
      Checkout components
    </h3>
    <p class="resource-card__description">Learn about the checkout components that you can also use to build customer account UI extensions.</p>
  </a>
</div></p>

<p><div>
  <a class="resource-card" href="https://polaris.shopify.com/content/merchant-to-customer" data-theme-mode="">
    <div class="resource-card__indicator-container"><img
     src="/assets/resource-cards/docs"
     data-alt-src="/assets/resource-cards/docs-dark"
     aria-hidden="true"
     class="resource-card__icon themed-image"></div>
    <h3 class="resource-card__title">
      Merchant-to-customer content guidelines
    </h3>
    <p class="resource-card__description">Learn how to write UI content that represents merchants and optimizes the customer experience.</p>
  </a>
</div>
</div>