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.

After the initial requirements check when the merchant installs your app, you want to check whether any required changes have been made. For example, if you reject a shop for not having a privacy policy, and they subsequently add one, then you should mark the shop as approved. To do so, you can subscribe to specific webhooks.

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.

An image of a feedback banner in Shopify admin indicating requirements are not meet for the marketplace

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

Requirements

Access scopes

Your app will require the following access scopes:

  • read_shipping

  • read_legal_policies

  • write_resource_feedbacks

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

  1. In your .env file, add the read_shipping, read_legal_policies, and write_resource_feedbacks access scopes.

    Since the app is already installed on your developer store, ensure you visit the authentication URL logged when you ran the Shopify CLI serve command.

  2. In server/handlers/rest, create a file called get-shop-configuration.js.

  3. In server/handlers/rest/get-shop-configuration.js, query the REST Admin API's Shop object.

    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.

  4. In server/handlers/queries/, create a file called get-shop-shipping-countries.js.

  5. In server/handlers/queries/get-shop-shipping-countries.js, query the GraphQL Admin API's shop field for a list of countries that the shop ships to.

  6. In server/handlers/queries, create a file called get-shop-policy-types.js.

  7. In server/handlers/queries/get-shop-policy-types.js, query the GraphQL Admin API's ShopPolicyType object to retrieve a list of the shop's available policy types.

  8. In server/handlers/rest, create a file called post-resource-feedback.js.

  9. In server/handlers/rest/post-resource-feedback.js, accept an object with the resource feedback data, and send it in a POST request to the ResourceFeedback resource.

  10. Update server/handlers/index.js to 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.

  1. In server/helpers.js create 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.

  2. 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.

  3. In server/server.js, update the afterAuth callback 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 meetsRequirements field 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.

An image of a feedback banner in Shopify admin indicating requirements are not meet for the marketplace

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.

  1. In server/handlers/webhooks/shop-update.js update the handleShopUpdate function 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 meetsRequirements field.

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.

  1. In server/handlers/webhooks folder, create a shipping-profile.js file.

  2. In 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 meetsRequirements field.

  3. In server/handlers/webhooks/setup.js register 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.

  1. In server/graphql/schema.js add a new type that returns Boolean fields for each of the marketplace requirements.

    You'll also add a new field to the AdminShop type that returns the new type.

  2. Update server/graphql/resolvers.js with a set of resolvers for the AdminShop configuration fields.

    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.

Next steps

  • Learn how to build an onboarding page for a channel app so that merchants can onboard to a marketplace.