Build a sales channel onboarding and account connection flow
Onboarding is the process of merchants connecting to your sales channel so that they can publish products and start selling on your platform.
You'll use OAuth to obtain permission from the merchant to install your sales channel app. When the merchant clicks on a link to install your sales channel app, they'll be redirected to Shopify's OAuth screen. After the merchant agrees to the OAuth permissions, your sales channel app requests an access token and then uses it for API access.
You'll use the Account connection component from Polaris to connect the merchant to your sales channel and provide any qualifying steps or additional onboarding requirements.
Access scopesAnchor link to section titled "Access scopes"
Your sales channel app requires the following access scopes:
Sales channels can only read their own orders. This means that your sales channel app will only read orders for sales that are attributed to the channel.
Learn more about authenticating with OAuth.
RequirementsAnchor link to section titled "Requirements"
- You're familiar with Shopify channels.
- You've turned your app to a sales channel app and requested payment processing.
Step 1: Setup ShopifyAnchor link to section titled "Step 1: Setup Shopify"
Install a Shopify library to access the API from your sales channel.
Step 2: Host app URLAnchor link to section titled "Step 2: Host app URL"
Host an OAuth app URL on your servers so that the merchant can give your sales channel permissions.
For app URL properties, refer to authenticating with OAuth.
Step 3: Get a token for the shopAnchor link to section titled "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 sales channel's 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 sales channel app's onboarding in ShopifyAnchor link to section titled "Step 4: Redirect the user to your sales channel app's onboarding in Shopify"
You need to redirect the user to your sales channel app's 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 sales channel app's first onboarding screen might look similar to the following:
Step 5: Style an account connection formAnchor link to section titled "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.
To see the account connection from a user’s perspective, refer to the component examples.
For example, your account connection form might look similar to the following:
Step 6: Include a setup flowAnchor link to section titled "Step 6: Include a setup flow"
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 object. For more information, refer to Sales channel app billing.
Your additional steps might look similar to the following:
Step 7: Pre-verify merchantsAnchor link to section titled "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 similar to the following: