The Shopify Polaris component library includes styled modules and components that you can use within your sales channel for merchant onboarding and account configuration, including notice banners, setting controls, form inputs, and modals.
If merchants need to take specific actions to interact with your platform, then your sales channel app requires a screen where they can do so. For example, merchants might need create content (such as posts or adds) or listings for individual products. Use this empty state when merchants have successfully set up the sales channel and can publish content to your platform, but haven’t done so yet. The empty state has the following content guidelines:
Title: A concise explanation of why the merchant is seeing this screen.
Subtitle: A short sentence that communicates what the merchant has to do next.
Illustration: A visual to represent what the merchant needs to do.
Call to action (CTA): A button that directs the merchant to perform their primary task in this channel, such as “Add product” or “Create listing”.
Help footer: see Help footer section.
Basic page layout
Sales channels use the annotated layout component to build out the Contextual and Functional areas.
Contextual area (left of card, on desktop)
The title and description of each section is used to give the merchant the context that they need to make decisions in your sales channel.
Section heading: What information, feature, or functionality is the merchant dealing with in this section? Be concise, and use your own platform’s terminology where possible, such as “Inventory management”.
Description: A one-sentence description of why this information or functionality is important, and how it benefits the merchant. You can also include a text link that points to documentation or more information on your platform’s site, such as “Learn more about [feature name]”.
Functional area (card, main/right side, on desktop)
The main area of each section in a sales channel is used to give the merchant control over some part of their experience using your platform, or to communicate vital information such as product publishing status, errors, or settings. Use the card component to build out this section.
The components below outline best practices for the functional area of a sales channel.
The account connection component appears at the top of the Account page. It enables merchants to connect or disconnect their store to various accounts, such as your platform, or a third-party site. The account connection component also enables merchants to see which accounts are connected to Shopify through your channel. It should always be visible, even if an account's status is disconnected.
Before an account is successfully connected, this section must link out to your channel or platform’s terms and conditions, and specify all charges or fees that a merchant incurs by using your channel. Clicking on the Terms and conditions link should open the terms, which must be hosted on your platform’s website, in a new browser window.
The account connection component has the following design guidelines:
Section title: Name the platform or service that you are asking the merchant to authenticate to, such as “Facebook account”, or “[your platform] account”.
Section description: Explain what the merchant benefit is for authenticating with the account. For example, “Connect your [sample] account to list your products” provides a clear reason why the merchant should connect their account.
Connect button: Use consistent terminology in both the Connect button and the Section description, so that button actions match the requested merchant action (such as “Connect”).
Clicking Connect should open your platform or service’s authorization page within a popup window. Within this window, merchants should clearly recognize your brand and be able to log in or sign up for your service. If your platform requires additional personal details, then prompt merchants for that information within this popup.
After the merchant has successfully authorized, the popup should automatically close. Refresh the sales channel page to show the successful account connection.
If merchants must complete any additional setup steps or go through a review process, then communicate this directly after successful account connection.
Otherwise, if there are no additional setup steps, then your sales channel can display a success banner at the top of the page. The success banner appears once, and should not reappear if the merchant refreshes or returns to the page later.
Your sales channel can include settings or features that merchants can enable, disable, configure, or review. This can include settings for your platform that you choose to make available to merchants through your sales channel. Settings functionality includes the setting toggle, generic information, and customization options.
The setting toggle component is used to give the merchant control over specific features or options in your sales channel.
Be sure to include specific body content for both Enabled and Disabled states of the feature toggle.
Clearly state whether the feature is “enabled” or “disabled,” and then explain what the implications are to the merchant (for example, “Automatic messages are disabled. Your customers will not receive automatic shipping updates”).
Unless it does not make sense for your specific use case, use “Enable” and “Disable” language consistently across your feature toggles, body content, and buttons.
Sometimes features or options will be unavailable to merchants, and cannot be toggled. In this case, clearly state that the feature is “not available” and then provide a reason why. Also include, if possible, an actionable next step that merchants can take to make the functionality available.
Information areas are used to communicate static content to merchants using your sales channel. For example, this could include cost or fee structure, review status, or account status. Each information area has a title and a body area. Follow the same guidelines as the Contextual areas above for this content.
Customization options enable merchants to make complex configurations of your sales channel, and extend beyond the single feature scope of the setting toggle. Customization dropdown menus should have smart default settings that are clearly labeled and require titles, such as “Position” or “Color”.
Banners can be implemented with four different colors, each used for different purposes:
- Blue: Basic messages (Welcome messages, feature announcements, explaining next steps)
- Green: Success messages (channel setup, product publishing, successful content creation)
- Yellow: Low-impact status messages (store being reviewed, products being reviewed)
- Red: High-impact messages (Errors, products rejected/banned from the platform, store rejected/banned from the platform)
Banners have the following content guidelines:
Message: The main body of the banner. Maximum of two sentences, unless the banner communicates multiple discrete elements, in which case a bullet list is used.
Call to action: Banner CTAs can be inline text links (lower priority) or buttons (higher priority). Use a button for directing merchants to resolve errors. Use inline links for additional links, such as helpful information, documentation, or pertinent sections of your channel or Shopify.
Bolding: Use bold text sparingly to set parts of the banner message apart for clarity. Bold things like product names or important information like waiting times.
Banners are usually shown at the top of the page. For highly contextual messaging, banners can be shown within sections. These banners typically refer to settings or features within that same section.
Forms use form areas to help user flow and lighten the burden on merchants. Refrain from using multi-step forms in your sales channel, and ask for necessary information only.
If your sales channel publishes products to a storefront, then merchants will need to be notified of any relevant errors related to the products being displayed. The status box tells merchants how many of their products have been successfully published and the errors table lists all products that aren't displaying, as well as publication issues related to each product. This enables merchants to resolve issues and publish blocked products.
Within the Status card, show a count of products published to your sales channel. That count should link to Shopify's bulk editor, where merchants can easily see and manage published products.
The errors table should have no more than six products per page before paginating the table and displaying the page navigation controls.
Terms and conditions
Merchants using your sales channel should have access to your terms and conditions at all times. These should be hosted outside of your sales channel app, but linked to from the terms and conditions module. The module must be visible after account connection, and located at the bottom of the Account page.
The help footer must appear on every page of your sales channel. It's a convenient way to provide your user with links to documentation or support for your sales channel.