Adding shop eligibility requirements

After finishing this tutorial, you'll know how to do the following:

• Add handlers to retrieve requirements data

• Check and store whether a shop meets marketplace requirements

• Add webhook handlers for updates to shop data regarding the requirements

• You've completed the Getting started tutorials.

Your channel app requires the following access scopes:

• read_shipping

• read_legal_policies

• write_resource_feedbacks

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 development store, ensure that you visit the authentication URL that was 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 resource.

   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.

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, you can add a requirements check when the merchant installs your channel app and store the shop's eligibility in your database.

1. Create a new sequelize migration that adds a new column to your Shop data model to track whether the marketplace requirements are met.

   The command creates a new file in your channel app's /migrations folder named {TIMESTAMP}-add-shop-requirements.js.

2. Update the migration file to add a new column to your Shops data table.

3. Add the new attribute to your Shop data model.

4. Run the migration to write the changes to your database.

5. In server/helpers.js, create a function that accepts all fields required for the requirements check and returns whether the shop is approved.

   You'll also create separate functions for the more complex checks, which will be useful when adding the checklist to your channel app's UI.

6. Create a function that accepts whether the requirements are met and writes resource feedback with the appropriate state and message using the handler that you created.

7. In server/index.js, update the /auth/callback handler to get the shop details using the handlers that 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'll also save whether the shop meets the requirements in your database using the meetsRequirements field that you created.

If the channel app is installed on a shop that doesn't meet the requirements, then the resource feedback banner should display on the shop’s admin homepage. In these cases, the shop shouldn't display on your marketplace homepage.

Your app is already 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 merchants have in their Shopify admin. This webhook is also triggered when merchants have either added or removed their online stores, 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 that you 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.

You also need to handle changes to the shop's shipping countries using webhooks, which will be triggered 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:

• PROFILES_CREATE

• PROFILES_UPDATE

• PROFILES_DELETE

Since there are a few webhooks, you'll create a new handler for shipping profile updates.

1. In the 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 the profile webhooks and call the handler created above in the webhook’s callback function.

   The resource banner on the shop’s homepage 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.

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.

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 Shop type that returns the new type and a Boolean to indicate whether the shop meets requirements.

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

   You don't need to define an explicit resolver for the meetsRequirements field, since it can be automatically resolved from the field of that name in the database's Shop data model.

   You can use the helpers and handlers that you created to fetch the relevant data and run the requirements checks.

You can use the new fields from your internal GraphQL API to surface the requirements checklist in your channel app.

1. In app/src/sections/Onboarding/components create an OnboardingChecklistCard.jsx file.

2. In app/src/sections/Onboarding/components/OnboardingChecklistCard.jsx create a component that will render an OnboardingCard component that contains an OnboardingChecklist component.

   The component should accept props to indicate whether each requirement is met and ensure each requirement redirects to the relevant section in the Shopify admin.

3. In app/src/sections/Onboarding/components/index.js, export the OnboardingChecklistCard component created above from the components module.

4. In app/src/sections/Onboarding/Onboarding.jsx, update the Onboarding component to render the OnboardingChecklistCard created above.

   The requirements checklist should now be visible on the onboarding page.

   

5. In app/src/sections/Settings.jsx, update the Settings component to render a Checklist component with the requirements.

   You can also render a loading state.

   The requirements checklist should now be visible on the settings page.

   

6. In app/src/sections/Home.jsx, update the query to retrieve the meetsRequirements field and pass it into the Overview component.

7. In app/src/sections/Home/components/Overview.jsx, update the Overview component to render a banner with a link to the settings page if the requirements are not met.

   If one or more requirement is not met, then an error banner should appear on the overview page.

   

• Learn about creating post-checkout functionality for your marketplace, including storing order details in your database and billing merchants a fee for sales on the marketplace.

• Share feedback on Marketplace Kit.