Build a sales channel onboarding and account connection flow
This guide teaches you how to onboard and connect merchants to your channel using OAuth and Shopify's Polaris components.
This guide assumes that you're familiar with the following:
Onboarding and account connection
You use OAuth to obtain permission from the merchant to install your sales channel app. The merchant clicks on a link to install your app which redirects to Shopify's OAuth screen.
After the merchant agrees to the OAuth permissions, your app requests an access token and then uses it for API access. The merchant is redirected to Shopify to complete your app's onboarding flow.
Step 1: Setup Shopify
Install a Shopify library to access the API from your app.
Step 2: Host app URL
Host an OAuth app URL on your servers so the user can give your app permissions:
Refer to Authenticate with OAuth for definitions of the app URL properties.
You can request the following OAuth access scopes for your sales channel app:
Sales channel apps can only read their own orders. This means your app can only read orders for sales that are attributed to your channel.
For more detailed information, refer to Authenticate with OAuth.
Step 3: Get a token for the shop
You can get a token for a shop by exchanging the code for a token. The following redirect URL is returned to your app server, including the code that can be exchanged for an access token:
Write a handler to extract the parameters from the URI, then verify the state against the state you saved on your server, and then send the token to Shopify's API.
You can save the returned token in your database. This the merchant account's identifier and you can use it to communicate with Shopify on behalf of the merchant.
Step 4: Redirect the user to your app's onboarding in Shopify
You need to redirect the user to your apps' account page in Shopify. To embed your app in Shopify, you need to use Shopify App Bridge. You need to use the Empty state component from Shopify Polaris to build the screen that hosts a value statement, an illustration, and a button for the account connection component.
By default your app's first onboarding screen might look similar to the following:
Step 5: Style an account connection form
You need to use the account connection component from Polaris to connect the merchant to your channel. The form needs to reflect your company branding. This clearly informs the merchant that they’re connecting to your account and helps create trust. It needs to be clear who merchants need to contact with any questions around onboarding.
Refer to the component examples to see the account connection from a user’s perspective.
For example, your account connection form might look something like the following:
Step 6: Include a setup flow for any qualifying steps or additional onboarding requirements
If you have any qualifying steps, eligibility requirements, or additional onboarding requirements, then these need to be included in the account connection form. This is also where you can surface the app's terms of service (TOS). Shopify recommends keeping your setup flow to a maximum of 3-4 separate steps to keep the onboarding process simple. Some topics that are typically included are product categories and fulfillment options. For example, if you're building a marketplace app, then you can call out expectations around fulfillment options and order management as part of this flow. This is also a good place to collect payment details from merchants so that you can pay them for sales on your marketplace. Regardless of what type of sales channel app you're building, you need to be clear and upfront about your app's pricing and fees. If your app uses the checkout API, then you need to prompt the merchant to agree to recurring billing using the AppSubscription resource. For more information, refer to Get Paid.
Your additional steps might look something like the following:
Step 7: Pre-verify merchants
MerchantApprovalSignals field on the GraphQL Admin API's
Shop object accelerates onboarding by pre-verifying merchants for the channel.
Your request to
MerchantApprovalSignals and the response body might look like the following:
After merchants have completed account connection and onboarding, then they're redirected to your app's account page in Shopify.
Build an account page
You need to build your account page using the Layout component. Pages built with the layout component include a contextual area (left of card, on desktop) and functional area (card, main/right side, on desktop). The functional area is built using the card component.
Your account page might look like the following, with the contextual area on the left and the functional area on the right:
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]”.
Account review (optional step)
If your sales channel has a review process, then you can communicate account status information to merchants using the Banner component.
If your app has a review process, then you can use the blue banner component to communicate this information.
Your account review message might look something like the following:
Account connection success
If the merchant has successfully passed the review process, then you can indicate success using a green banner component:
If the merchant has failed the review process, then you can indicate this using a red banner component.
Your sales channel needs to give the merchant the option of disconnecting from the channel from the Account section. Clicking on disconnect needs to launch a hard alert featuring a red button, because this action cannot be undone.
Your app needs to include a commission section using the card component and the annotated layout. The commission section needs to state the commission rate and state how and when merchants are charged.
Terms and conditions
Your app needs to include a Terms and conditions section. Any links in that section needs to open in a new window. The terms and conditions should be hosted outside of your sales channel app, but linked to from the terms and conditions module. The module needs to be visible after account connection, and located at the bottom of the Account page.
A help footer needs to 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.
After the merchant has been approved, you can begin to publish the merchant's products to your sales channel. This process has both front end and back end considerations.
Step 1: Manage product publishing
By default, all available products can be published to your channel. However, Shopify recommends reading the product catalog from the ProductListing resource instead, to better align with how merchants like to control where their products appear.
You can make the following call to the Shopify API to retrieve product listings:
In response, the API returns the product listings formatted as JSON.
If you wish to control which products are published to your app, then you can send a PUT request to this resource to publish a product on behalf of the merchant.
Another option is to read products in bulk by performing bulk operations with the GraphQL Admin API.
To surface product publishing status to the merchant, you need to build a status card using the card component. This status section is included as part of the account section. The status section includes the number of products published. If any products failed to publish to a channel, then merchants should see the number of products with errors clearly listed in the Publishing status card. Merchants can view all products with publishing errors directly through the channel by visiting the link found on the status card.
Your status card might look like the following:
Step 2: Manage product information
In some cases, you won't have all of the product information that you need for your channel from the product catalog. If this is the case, then you can use metafields to obtain the additional information. There is also a Metafield resource which can be used for the same purpose.
On the front end, metafields can surface under the More actions drop-down on the products page in Shopify.
By way of example, here is an example of a pattern that was used to implement metafields:
Additional fields are surfaced using the "More actions" drop-down.
Merchants can always visit the Products section in Shopify to view and manage products that are published to sales channels. From the Products section, merchants can view a solve publishing errors one-by-one or using the bulk editor.
Step 3: Manage errors
In some cases, you'll encounter errors when trying to publish the merchant's product catalog to your sales channel. If this is the case, then there are a variety of measures that you can take to resolve these errors.
To surface product publishing errors to the merchant, you need to build a status card using the card component. This status section is included as part of the channel account page.
Your status card could show products being synced or products with errors preventing their sync:
Merchants need to be allowed to view all products with publishing errors directly through the channel by visiting the link found on the Product publishing card. After all errors are resolved, you can show a success banner:
The resource feedback API provides a mechanism to prompt a merchant to solve errors. This can be useful in a variety of scenarios, such as when a product isn't valid for you to publish, or when an edit to a previously published product causes an error.
Any missing product attributes required by a channel can be listed on a Products page using the Resource feedback API. Product resource feedback is surfaced to the merchant under the channel's name in the Product availability section on the Products page.
Product resource feedback:
Product level resource feedback can be used for anything involving a product and its variants.
You can make the following call to the Shopify API to create product resource feedback:
After you create resource feedback, you need to check the product for validity whenever you receive a product update. If the error is resolved, then you can dismiss the resource feedback.
Shop resource feedback:
You can use the Shop level feedback for any account level errors that affect the entire catalog.
You can make the following call to the Shopify API to create resource feedback:
Step 4: Stay in sync with product changes
After products have been published to your channel and you've dealt with any errors, you need to keep the product catalog up-to-date with any changes in Shopify. A merchant could change a product title or images, for example, or mark a product as out of stock. In order to be notified of changes, you can subscribe to product or product listing level webhooks:
You can configure webhooks using the API by specifying the topic in the body of the request.
The following example shows a request that uses the product_listings/add webhook:
The API call returns the following response:
You can then create an HTTP endpoint on your server to monitor for events. Refer to Creating an endpoint for webhooks to learn more.