Using the Customer Account API with Hydrogen

After you've completed this tutorial, you'll be able to authenticate a Customer and make Customer Account API queries within a Hydrogen storefront.

• You have completed the Getting started with the Customer Account API guide.
• You have completed Getting started with Hydrogen guide.
• You've installed the Hydrogen or Headless sales channel.

• Multipass currently doesn't support Customer Account API. If you require single sign-on from an external website in your storefront, then you should use the code in our multipass example, which uses the legacy customer account flow.
• mock.shop, which provides example product data, doesn't support the Customer Account API. You must use a production store's credentials to work with the Customer Account API.

Customer Account API authentication doesn't support the use of localhost due to security concerns. For development purposes, use a tunnelling service, such as ngrok.

In this step, you'll learn how to use ngrok to set up a public HTTPS domain that connects to your local Hydrogen application.

Install and run ngrok in your development environment.

1. Set up an ngrok account.
2. In your ngrok settings, add a static domain.
3. Install the ngrok CLI.
4. In a terminal, start ngrok using the following command:

Modify your Hydrogen app’s content security policy to allow the development domain as a connect-src. Your content security policy is typically located in /app/entry.server.tsx.

Configure the necessary Customer Account API settings in the Shopify admin so you can send the initial authentication request to Shopify.

1. In the Shopify admin, open the Hydrogen sales channel.
2. Click the storefront you're adding the customer account API functionality for.
3. Click Storefront settings.
4. Click Customer Account API to open the API settings.

For the Customer Account API to recognize your domain as a valid authentication host, edit your Customer Account API settings.

1. Under Application setup, click Edit ✎ to edit the endpoints.

2. Under Callback URI(s), click Add Callback URI, and add your ngrok domain, with /account/authorize appended:

   This is the URI your application will redirect to to continue the OAuth process after a successful customer login.

3. Under JavaScript origin(s), click Add origin, and then add your ngrok domain.

4. Under Logout URI, click Add Logout URI, and then add your ngrok domain.

The two environment variables needed to set up Customer Account API in your application are:

When deploying to Oxygen, these variables are automatically created and used in your production environment.

When developing Hydrogen locally, store your environment variables in an .env file. You can automatically download the required variables with Shopify CLI:

1. Run npx shopify hydrogen link in your Hydrogen project to link it to your Shopify store.
2. Run npx shopify hydrogen env pull to download your environment variables and write them to your local .env file.

Create a new Customer Account API client in your server file using the createCustomerAccountClient utility.

Pass the new client to createCartHandler to ensure that the logged-in customer is persisted from your store through to checkout.

Pass the new client to the application's context so the utility can be accessed throughout the application.

createCustomerAccountClient expects a session, implemented based on HydrogenSession, to persist auth tokens and the customer's logged-in state.

You can view an example of a Hydrogen session in the Hydrogen GitHub repo.

Your application requires three routes for customer login and logout operations.

The default routes are as follows:

• /account/login: A route that redirects the user to a Shopify login.
• /account/authorize: A route that authorizes the customer after they log in.
• /account/logout: A route that logs the customer out.

Follow the following steps to create a customer login route in your Hydrogen storefront:

1. In the routes folder, create a new file called account_.login.[js|ts].
2. In the new file, add the context.customerAccount.login() function in the loader.

This function is responsible for redirecting users to Shopify to log in.

Note the use of underscore in account_.login.ts. This is to ensure that no layout is rendered when this route is accessed.

Follow the following steps to create an auth route in your Hydrogen storefront:

1. In the routes folder, create a new file called account_.authorize.[js|ts].
2. In the new file, add the context.customerAccount.authorize() function in the loader.

After a successful login, Shopify redirects to this authorize route. It continues the OAuth process, exchanges the access token, and persists the result to your application session.

If you choose to place this route somewhere else in the application, then use the authUrl option with a relative url, and add the full public domain auth path in the Callback URI of the Customer Account API application setup

At the end of this authorization step, the application redirects back to the page that initiated the login.

Use the customAuthStatusHandler option to change this behavior.

Follow the following steps to create a logout route in your Hydrogen storefront:

1. In the routes folder, create a new file called account_.logout.[js|ts].
2. In the new file, add the context.customerAccount.logout() function in the action. Avoid including this function in the loader.

The logout action should be triggered by a user event, like clicking a logout button, not when a component is being loaded that can occur by page load or prefetching. This is because logging out is a significant action that can disrupt the user's workflow, so it should only happen when the user explicitly requests it.

You can set up a redirect that takes place after the logout step using the admin setting in the application setup step.

After you've set up your auth routes, you can start querying the Customer Account API.

In this step, you'll create a new account route that queries for a logged in customer's first and last name.

1. In the routes folder, create a new file called account.[jsx|tsx].

2. Add the following code.

   This code fetches the customer's first and last name from their account. If the customer isn't logged in, calling query() will trigger an automatic redirect to the login page, and redirect back to current page at the end of the auth process.

The query and mutate functions follow GraphQL standards and return both data and errors objects. The errors object typically returns GraphQL errors such as a syntax error for querying for unknown field name.

Most of the time, the existence of the errors object means that the query isn't successful and there is nothing to show. However, during a mutation, it is possible to receive partial data while still experiencing errors.

You should always handle errors gracefully, either by showing a message to the user, or re-throwing them for your application's ErrorBoundary to catch.

You can check whether a visitor is logged in without triggering an automatic login redirect. For instance, you might want to conditionally display a Log in or Account details link in a menu.

1. In the root file of your application, add customerAccount.isLoggedIn() in the loader.
2. Return this promise using Remix's deferred data loading pattern. This allows the user interface to render before the login check is complete.

Note that you need to commit() the session at the end of any loader or action that checks a customer's logged-in state. This is because a logged-in check can trigger an access token refresh, which won't persist in your application unless the session is committed to the Set-Cookie header.

• Explore the GraphQL Customer Account API reference.
• Explore the createCustomerAccountClient reference, including additional examples.
• Explore an end-to-end Customer Account API implementation example in the default Hydrogen template.
• Learn how to Manage customer accounts with the Customer Account API