Add eligibility requirements for shops
You've setup the channel apps onboarding foundations. You want the shops to meet specific requirements before merchants can publish products to the marketplace. You also want to provide merchants with feedback for how they can meet your marketplace requirements and start selling.
In this tutorial, you'll add the following requirement checks to your channel app:
The shop must have an online store.
The shop must ship to Canada.
The shop must support CAD.
The shop must have refund and privacy policies.
You'll also use the GraphQL Admin API's
ResourceFeedback object to surface a warning banner on the merchant’s homepage, alerting them that they do not meet the marketplace’s requirements.
What you'll learn
After finishing this tutorial, you'll know how to do the following:
Add handlers to retrieve requirements data
Check whether a shop meets the marketplace requirements
Add webhook handlers for updates to shop data regarding the requirements
- You've completed the Set up onboarding foundations tutorial.
Your app will require the following access scopes:
Step 1: Add handlers to interact with the Admin API
After you've determined the requirements to enforce, you can create various handlers to retrieve the data from the GraphQL Admin API. You'll also add the access scopes required to query the data
.envfile, add the
server/handlers/rest, create a file called
server/handlers/rest/get-shop-configuration.js, query the REST Admin API's
The code requests the shop and presentment currencies and whether the shop has an online storefront. The return also provides other shop data that might be useful for your requirements checks.
server/handlers/queries/, create a file called
server/handlers/queries/get-shop-shipping-countries.js, query the GraphQL Admin API's
shopfield for a list of countries that the shop ships to.
server/handlers/queries, create a file called
server/handlers/queries/get-shop-policy-types.js, query the GraphQL Admin API's
ShopPolicyTypeobject to retrieve a list of the shop's available policy types.
server/handlers/rest, create a file called
server/handlers/rest/post-resource-feedback.js, accept an object with the resource feedback data, and send it in a POST request to the
server/handlers/index.jsto export the new function from the handlers module.
Step 2: Add requirements check when the app is installed
After you've set the handlers to pull all shop data relevant to your marketplace requirements, and you've set the handler to submit resource feedback, then you can add a requirements check when the merchant installs your channel app.
server/helpers.jscreate a function that accepts all fields required for the requirements check and returns whether the shop is approved or not.
You'll also create separate functions for the more complex checks, which will be useful when building the onboarding UI in subsequent tutorials.
Create a function that accepts whether the requirements are met and writes resource feedback with the appropriate state and message using the handler you created.
server/server.js, update the
afterAuthcallback to get the shop details using the handlers you created.
You'll then use the helper methods that you created to write resource feedback to the shop based on whether it meets the eligibility requirements.
You'lll also save whether the shop meets the requirements in your database using the
meetsRequirementsfield that you created during setup.
If you install the app on a shop that does not meet the requirements, then you should see the resource feedback banner on the shop’s admin home page. The shop should also not appear on your marketplace home page.
Step 3: Add shop update webhook handlers
Previously, you subscribed to the
SHOP_UPDATE webhook topic to ensure that the shop name stored in your database stays in sync with the shop name that the merchant has in their Shopify admin. This webhook is also triggered if the merchant has either added or removed their online store, changed their presentment currencies, or updated their shop policies. You can update the handler to also run the requirements check and write resource feedback accordingly.
handleShopUpdatefunction to fetch the relevant data using the handlers you've created and write resource feedback.
The webhook body already contains some of the information you need, so you don’t need to fetch the shop’s configuration.
You can also update whether the shop meets the requirements in your database by updating the
Step 4: Add shipping profile webhook handlers
You also need to handle changes to the shop's shipping countries using webhooks, which will be fired when a shop makes changes to their shipping profiles. Changes to shipping profiles can impact the shop's shipping countries.
You'll subscribe to the following profile-related webhooks:
Since there are a few webhooks, you'll create a new handler for shipping profile updates.
server/handlers/webhooksfolder, create a
server/handlers/webhooks/shipping-profile.js, export a function that will fetch the requirement-related shop data, and write the appropriate resource feedback.
You'll also update whether the shop meets the requirements in your database by updating the
server/handlers/webhooks/setup.jsregister for the profile webhooks and call the handler created above in the webhook’s callback function.
The resource banner on the shop’s home page should now dynamically update based on changes made to the shop’s payment, shipping, policy, and online store settings. The shop’s database field should also be updated accordingly.
Step 5: Add requirements to the internal GraphQL API
Now that you have the handlers and helpers required to check each requirement, you can expose whether the requirements are met using your internal GraphQL API. This is necessary to build the requirements checklist in a subsequent tutorial.
server/graphql/schema.jsadd a new type that returns Boolean fields for each of the marketplace requirements.
You'll also add a new field to the
AdminShoptype that returns the new type.
server/graphql/resolvers.jswith a set of resolvers for the
You can use the helpers and handlers that you created in the onboarding framework tutorial to fetch the relevant data and run the requirements checks.
- Learn how to build an onboarding page for a channel app so that merchants can onboard to a marketplace.