Get started with Marketplace Kit

You're ready to create a marketplace. You want to showcase products from multiple merchant shops on your platform and direct buyers towards a sale. You'll get started with a simple framework, and build up buyer and merchant experiences from there.

In this tutorial, you'll set up a routing, access, and data query framework for your marketplace.

A workflow diagram of products in a marketplace and the redirect to the storefront

What you'll learn

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

  • Create routes to render merchant-facing and buyer-facing pages

  • Retrieve and store Storefront API access tokens for multiple shops

  • Add an internal GraphQL API endpoint

Requirements

Step 1: Add routes

Your app will need to have a merchant-facing channel and a buyer-facing marketplace. In this tutorial, both are handled using the app that you generated with Shopify CLI. All merchant-facing pages will be rendered at /admin routes, and all buyer-facing pages will be rendered at root /.

  1. In server/server.js, create a handler for /admin routes.

  2. Update the fallback route handler to redirect to /admin if the shop and host parameters are in the URL query.

  3. Update the afterAuth callback to redirect to /admin with the shop and host parameters.

  4. In pages/_app.js, use a different provider for the merchant-facing and buyer-facing routes.

  5. Create pages/admin/index.js with a basic Polaris page for your channel app.

    Navigate to the link provided by ngrok in your terminal to open the channel app within the Shopify admin to display the merchant-facing, channel app page:

    An image of the Shopify admin, merchant-facing page for the channel app

  6. Update pages/index.js to render a basic buyer-facing page.

    Navigating to the root URL displays the buyer-facing, marketplace page:

    An image of the initial buyer-facing page for the channel

Step 2: Get and store Storefront API access tokens

To authenticate with the Storefront API, your app needs a mechanism for storing and retrieving the domains and Storefront API access tokens for all shops that have installed your channel app. You'll need the generated Storefront API access tokens to access the storefronts of shops on your marketplace.

  1. Create a shop data model with domain and storefrontAccessToken fields. You'll use these fields to retrieve shop data and products on the marketplace.

  2. In your .env file, under scopes, add the unauthenticated_read_product_listings scope.

  3. In the server/handlers/queries folder, add a get-storefront-access-token.js file that queries the GraphQL Admin API's Shop object for the first Storefront API access token.

  4. In the server/handlers/mutations folder, create a create-storefront-access-token.js file that creates a new Storefront API access token.

  5. In server/handlers/index.js, export the functions created from the handlers module.

    The file should now look something like the following:

  6. In the server folder where you used the query and mutation, create a helpers.js file.

  7. In server/helpers.js, add a helper function that creates a Storefront API access token if one doesn't already exist.

  8. In server/server.js, in the afterAuth function, use the code written above to retrieve the Storefront API access tokens and store them in the database.

    The afterAuth should now look something like the following:

Step 3: Add an internal GraphQL API endpoint

After you've updated your authentication callback to save the shop domains and Storefront API access tokens, your channel app needs to be able to retrieve them so that it can fetch shop and product details for multiple merchant shops using the Storefront API.

For this tutorial, you'll build an internal GraphQL API using Apollo Server.

  1. Add Apollo Server.

  2. Create a server/graphql folder to contain the files for the internal GraphQL API.

  3. In the server/graphql folder, create a schema.js file with a schema that consists of a shops field on Query root.

  4. In the server/graphql folder, create a resolvers.js file with the resolvers that'll fetch the data to be returned for the shops field.

  5. In server/graphql/index.js, export the schema and resolver constants from the server/graphql folder using an index.js file.

  6. In server/server.js, add Apollo Server middleware to the koa app to make the GraphQL endpoint available at /graphql.

  7. Restart your server and navigate to your app’s GraphQL endpoint. This should redirect you to a GraphQL playground where you can see the schema and query your API.

    An image of a sample query and response in the GraphQL playground

Next steps

  • Learn how to build up the merchant-facing channel app page for the Shopify admin.