RFC: Hydrogen Customer Account API

[blittle]

RFC: Hydrogen Customer Account API

Date: 2023 Aug 4

Shopify has introduced the Customer Account API that allows customers to view their orders and manage their profile. This new API uses an OAuth 2.0 PKCE authorization flow. While this API is powerful, it isn't user friendly for developers that aren't familiar with OAuth. We plan to introduce an abstraction into Hydrogen to make interacting with the Customer Account API easier.

This proposal is mostly available as an example in the Hydrogen repository.

createCustomerClient()

Similar to createStorefrontClient(), a Hydrogen app adds support for the Customer Account API by calling createCustomerClient() and adding the result to load context.

const {storefront} = createStorefrontClient({ ... });
const {customer} = createCustomerClient({
  /** A fetch Request object for the current request */
  request,
  /** The Remix session object - https://remix.run/docs/en/main/utils/sessions */
  session,
  /** These two variables should be added to your environment and are 
      defined within the Customer Account API portion of the admin **/
  customerAccountId: env.PUBLIC_CUSTOMER_ACCOUNT_ID,
  customerAccountUrl: env.PUBLIC_CUSTOMER_ACCOUNT_URL,
  /** i18n variables are automatically passed to all requests **/
  i18n: {language: 'EN', country: 'US'},
});

const handleRequest = createRequestHandler({
  ...
  // Add the customer instance to the load context
  getLoadContext: () => ({session, storefront, env, customer}),
});

Authenticating to the Customer Account API

With the customer client now on the load context, we can setup a route with an action to start the authentication process:

import {ActionArgs} from '@shopify/remix-oxygen';

export async function action({context}: ActionArgs) {
  return context.customer.login();
}

A simple Remix form request to this action route starts the authentication:

import {Form} from '@remix-run/react';

export function LoginForm() {
  return <Form method="post" action="/authorize">
    <button>Login</button>
  </Form>;
}

The customer.login() method begins authentication by redirecting to a Shopify hosted login site. If the user successfully logs in, they are redirected back to your custom storefront to a route of your choosing. In that redirect an authorization code is passed. We need to use that code to finish the authentication. Call context.customer.authorize() to finish that process:

import {ActionArgs, LoaderArgs} from '@shopify/remix-oxygen';

export async function action({context}: ActionArgs) {
  return context.customer.login();
}

export async function loader({context}: LoaderArgs) {
  // The param passed to `authorize` is the path the user should land on if everything is successful
  return context.customer.authorize('/');
}

If .authorize() fails, an error Response is thrown. Alternatively you can catch that response to custom redirect the user:

export async function loader({ context }) {
  try {
    return context.customer.authorize("/");
  } catch (e) {
    context.session.flash("error", "Error logging in");
    return redirect("/", { headers: { "Set-Cookie": await session.commit() } });
  }
}

Check if the user is logged in

Check if the user is logged in with the customer.isLoggedInMethod()

export async function loader({ context }) {
  return json({ loggedIn: await context.customer.isLoggedIn() });
}

Querying the Customer Account API

Query the Customer Account API with the .query and .mutate methods:

export async function loader({context}) {
  if (await context.customer.isLoggedIn()) {
    const user = await context.customer.query(`#graphql
      {
        personalAccount {
          firstName
          lastName
        }
      }
      `);

    return json({
      user,
    });
  }
  return json({user: null});
}

export async function action({ context }) {
  if (await context.customer.isLoggedIn()) {
    const user = await context.customer.mutate(
      `#graphql
      mutation personalInformationUpdate($input: PersonalInformationUpdateInput!) {
        personalInformationUpdate(firstname: $firstname, lastname: $lastname) {
          personalInformation {
            firstname,
            lastname
          }
        }
      }`,
      {
        variables: {
          firstName: "Chief",
          lastName: "Kondiaronk",
        },
      },
    );

    return json({
      user,
    }, {
      headers: {
        'Set-Cookie': await context.session.commit()
      }
    });
  }

  return new Response(null, { status: 401 });
}

Refreshing the authorization token

A user might be logged in, but their authorization token is expired. So before querying the API, their token needs to be refreshed. We automatically refresh the token for you when you call .query or .mutate. But if the refresh fails, the user should be considered logged out.

Automatically refreshing the authorization token means that the new token also needs to get persisted into the session. This means that any loader or action that you query or mutate data also needs to commit the session. Which is why the previous example has 'Set-Cookie': await context.session.commit() in the response.

Alternatively, you can always commit the session within server.ts:

export default {
  async fetch(
    request: Request,
    env: Env,
    executionContext: ExecutionContext,
  ): Promise<Response> {
    ...
    const response = await handleRequest(request);
    response.headers.set('Set-Cookie', await session.commit());
    return response;
  }
}

Note: If the session is commited on a route, that route cannot be full-page cached. If you commit on every route, then full-page caching is completely disabled.

Logout

Logout by simply implementing an action in a route that calls and returns customer.logout(). This will redirect the user to a shopify hosted domain, log them out, and redirect them back to a route of your choice (configured within the admin):

import {ActionArgs} from '@shopify/remix-oxygen';

export async function action({context}: ActionArgs) {
  return context.customer.logout();
}

On logout, Hydrogen clears out all tokens from the session.

API Reference

function createCustomerClient(customerOptions: CustomerOptions): CustomerClient;

type CustomerOptions = {
  request: Request;
  session: Session;
  customerAccountId: string;
  customerAccountUrl: string;
  i18n?: { language: LanguageCode; country: CountryCode };
};

type CustomerClient = {
  logout: () => Promise<Response>;
  authorize: (redirectPath?: string) => Promise<Response>;
  isLoggedIn: () => Promise<boolean>;
  login: () => Promise<Response>;
  query: (query: string, variables?: any) => Promise<unknown>;
  mutate: (query: string, variables?: any) => Promise<unknown>;
};

Questions

1. How do we support TypeScript codegen?

2. The Storefront API client has both mutate and query to separate which is automatically cached. We never will automatically cache requests to the Customer Account API, so does it make sense to have both .mutate and .query when they are identical?

3. How should the Storefront API contextualize requests based on the logged in user? Should we add a simple method customer.getAuthToken() and developers manually pass that variable into their storefront queries? Or could we automatically inject the token into Storefront requests like we do for i18n? With either option, how do we make sure the token is up to date? Should we automatically refresh it?

4. Is it worth adding higher abstractions for customer.getOrders(), customer.update() and similar functionality. This was implemented in a previous PR: #743

[duncan-fairley]

This is great, very excited to start moving over.

• Any word on how persistence will work? Hoping it's a simple as associating a access token to a cart buyer identity?
• Is there a provision in the new account system for 3rd party (4th party?) auth / SSO? Looks like maybe we'll need an action that is capable of a server-side call to obtain an access token? Could we then feed this into the Customer Account API?
• I feel like the delineation between mutate and query is helpful even if they are the same under the hood.
• Love the idea of injecting the customer into storefront requests like country and language. Feels very powerful.
• I was initially feeling like higher level abstractions would be unnecessary but I think the case could be made that over-fetching is actually preferable to having to define all of the queries for simple use-cases (especially since they'll likely be called on a very small sub-section of sessions).
• I think something like getCustomerData() and separately, getOrders() with all fields included would meet 90% of use cases (with direct querying handling the rest).

[mathieulag]

Is there a provision in the new account system for 3rd party (4th party?) auth / SSO? [...] Could we then feed this into the Customer Account API?

I can answer this one. Currently there is not, but we're looking at supporting 3rd party identity provider in the future. We'll be abstracting this away behind our customer authentication, so your hydrogen store will not have to change. It should only require some configuration in the Admin.

Looks like maybe we'll need an action that is capable of a server-side call to obtain an access token?

Obtaining an access token can be done server-side or client-side for public clients, which Hydrogen is. Because of the way Remix works though, it makes more sense to do it server-side in this case.

[duncan-fairley]

Admin-managed social sign on would be a huge win. Doesn't seem like it's possible to obtain a token on behalf of a user on the server which I guess would it difficult to handle SSO ourselves in the short-term (by handling our own auth and then exchanging for a Shopify token server-side).

[blittle]

@duncan-fairley by persistence, do you mean maintaining the authenticated user all the way to checkout? This will happen automatically, without you doing anything.

[duncan-fairley]

Making my year @blittle!

[matthewford]

Is there a way to create a customer account before they order? (we're looking at adding wishlists etc)

[blittle]

@matthewford yes, this flow can be followed to create an account and login before an order is made. The orders GraphQL query would just come back empty.

[richardscarrott]

Is it worth considering the use of remix-auth here? I've created a Shopify strategy which extends remix-auth-oauth2 which is nice because it uses a more familiar API?

[blittle]

@richardscarrott great question. I'd love to see your Shopify strategy, and using the Authenticator approach I need to think through how it would work with a client for the customer account API as well.

[richardscarrott]

Hi @blittle 👋, I've pushed up a working example here https://github.com/richardscarrott/remix-shopify-customer-account-api/blob/main/app/services/remix-auth-shopify.server.ts

There's two things it doesn't yet handle, but should be relatively easy to add:

1. Logout from shopify session
2. Check expiration date of access tokens + refresh them (both shopify auth and customer API tokens).

[blittle]

@richardscarrott I've done some PoC work building a Strategy to work with remix-auth, and I'm not sure it fits our use case well. Part of the issue is that the whole purpose of authenticating is to be able to make requests to a new GraphQL API. If we produce a Strategy, we'll also need to create a separate GraphQL client that you'd pass a an authenticator reference to. While this would be convenient if the GraphQL client could be composed with any authenticator strategy, it can't. The GraphQL authentication can only happen with this particular oauth2 flow. It feels more ergonomic to me to have a single utility to create the client, put it on your context, then you interact with it in your routes with a single instance.

[blittle]

To be clear, the Customer Account API hopes to support 3p identity providers down the road. But activating a 3p provider should be seamless on the frontend. There won't be any new "strategy" to configure in your Hydrogen app. There is only ever one strategy, so I don't think we need the infrastructure to support many strategies.

[richardscarrott]

re: codegen, do you know how to run introspection on the Customer Account API graphql endpoint? It seems it needs an access token which isn't practical given you want to be able to introspect for IDE / codegen purposes?

{
  "errors": "Not a valid access token"
}

[richardscarrott]

👋 @blittle, I don't suppose you have any insight here?

[blittle]

@richardscarrott I know it's a very poor DX at the moment. I've raised it internally. Hopefully I can get traction on making the introspection schema public 🤞

[lynchv]

Quick alignment decision on the environment variables naming. We already utilize the following environment variables for the Storefront API:

• PRIVATE_STOREFRONT_API_TOKEN
• PUBLIC_STOREFRONT_API_TOKEN

I would suggest following the same naming structure and slightly deviate from the naming as seen in the description:

• 🚫 PUBLIC_CUSTOMER_ACCOUNT_ID -> ✅ PUBLIC_CUSTOMER_API_CLIENT_ID
• 🚫 PUBLIC_CUSTOMER_ACCOUNT_URL -> ✅ PUBLIC_CUSTOMER_API_URL

If anyone has differing opinion would love to hear them.

[mathieulag]

I would recommend keeping the ACCOUNT part of it as the name of the API is the Customer Account API. Customer API is a bit ambiguous as we sometimes refer to the customer part of the Admin API as that. Adding API to it makes sense though PUBLIC_CUSTOMER_ACCOUNT_API_CLIENT_ID.

[graygilmore]

I'd prefer to drop the PUBLIC_ prefix entirely. We only have that for the Storefront API to be able to differentiate them.

[lynchv]

If we look at some other environment variables we have been using unrelated with APIs we have PUBLIC_STORE_DOMAIN & PUBLIC_STOREFRONT_ID. I think the "private"/"public" nomenclature is more to tell the user which variable can be safely shared instead of differentiating between 2 values.

[graygilmore]

Bummer! Might as well keep the pattern then.

[benjaminsehl]

One of those times I wish we'd documented the decision and put it in the Vault — but I do recall this whole thing coming up about a year ago when we moved to standardize nomenclature for Env variables. Though most of that was driven by inconsistent usage of STORE STOREFRONT SHOP SHOPIFY, I recall we did talk about PUBLIC / PRIVATE prefixes. Agree that it is a bit of a bummer as I can't remember if we really hammered on that part of the decision much.

[danielmoraes]

How long will it take for the API to become stable, so we can use it on production?

[mathieulag]

We have a release candidate version out for 2024-01, you can see the details in our changelog.

[blittle]

Hydrogen's implementation on top of it is also hoping to be stable by 2024-01 release

[mathieulag]

Version 2024-01 is live!

[richardscarrott]

We use Remix for our custom storefront (but not Hydrogen), however we've been using Hydrogen as a good reference 🙏.

I wonder if you could help with a few questions re: Hydrogen and the Customer Account API:

1. Why does Hydrogen authenticate as a public client rather than confidential?
2. Is it safe to use refresh tokens more than once?
   • Remix's parallel data loaders make single-use refresh tokens very difficult to work with as the client makes n fetches which may all need to refresh the access token and update it in the session.
     • If it can only be used once then 1 loader will succeed and the others will fail (and in turn delete the login session), resulting in a race condition between each loader's Set-Cookie response header; last one wins.
   • Having said that, I've observed in our Shopify development store that refresh tokens can be used multiple times (both the refresh token in the refresh token flow and the access token in the token exchange flow).
     • However, the refresh token response includes a newly minted refresh token which has me worried refresh token rotation will eventually be enforced?
     • UPDATE: I can confirm refresh tokens can be used multiple times when using a confidential client. However they can only be used once when using a public client
3. How do you plan to handle a user logging out directly in Shopify's checkout?
   • If the user logs out within checkout, it kills the shopify session and surprisingly-to-me revokes the access token (not just the refresh token), but obviously Remix knows nothing about it so the user remains "logged in" on the headless site.
     • I worry we'll end up having to test the access token on every single request just to confirm they are fully logged in 🤔
     • Unless perhaps there's a way to configure the checkout logout link to hit Remix before hitting Shopify so we can kill the Remix session too?

[blittle]

1. Because the Hydrogen implementation is only in server actions/loaders, there is no requirement to use the public client. It just as easily could use the confidential flow. We opted for the public flow, because it didn't add much complexity, and gives us the flexibility to also make requests from the client down the road.
2. The refresh token can only be used once. On refresh, you get a new refresh token. This is why our implementation has a lock, to make sure that only on refresh request is sent at a time.
3. This is a good callout, but on logout, the Shopify should redirect the user to the configured logout URI. We probably need to update the logout route to have a loader export, that clears the session. cc @michenly

[richardscarrott]

The refresh token can only be used once. On refresh, you get a new refresh token. This is why our implementation has a lock, to make sure that only on refresh request is sent at a time.

I saw that lock impl. and perhaps I'm misreading it, but it appears to be in-memory? For SPA navigations, Remix makes separate network requests for each loader so I don't think it'll solve the problem? I think single data fetch would solve it, but that's probably a long way off.

@mathieulag mentioned in Discord that, when using the confidential client as we are, refresh tokens are reusable which is what I'm seeing, are you able to confirm this is by design?

This is a good callout, but on logout, the Shopify should redirect the user to the configured logout URI. We probably need to update the logout route to have a loader export, that clears the session. cc @michenly

Is this something Shopify still needs to work on as this doesn't happen on our development store, the logout URL links to https://example.com/customer_identity/logout (our logout URI is ngrok). Aside -- we're using the Headless app, not the Hydrogen app so I wonder if that's a factor?

[michenly]

RE: how Hydrogen handle user logging out directly in Shopify's checkout

the currently implementation will check for 401 response when querying the Customer Account API and clear the session.

From the UX side, this means that when a customer logout in Shopify's checkout, and go backs to a Hydrogen site. The customer will continue to look like they are login (from the top menu bar) until the customer goes to /account (which trigger a query >> follow by clearing session) and automatically be redirecting to login page. At this point the menu item will also show logout.

[osseonews]

Not sure if this is the correct place to post this, but when using the new Customer Accounts API, if you log in a customer, the cart on the headless site cannot be updated with the customer identification. Specifically, I figured that you can use the customerAccessToken returned during the Token Exchange to update the Cart in the Storefront API with the buyerIdentity Argument, passing the customerAccessToken received in the Customer Accounts API to that field in the buyerIdentity. However, this does not work, as the token is considered invalid. Apparently, there customerAccessToken required in the Storefront API for the cartBuyerIdentityUpdate mutation, is different than the customerAccessToken created by the Customer Accounts API, and a separate one must be created with the Storefront API using username/password mutation. However, if you use the Customer Accounts API, you can't and won't use the username/password mutation. So how can you update the cart with the buyerIdentity using the new Customer Accounts API? Will you provide a basic mutation to do this in the Customer Accounts API? Currently, there doesn't seem to be any sort of Cart Mutations in the Customer Accounts API and the only way to apply the customer to the cart is to redirect them to the checkout with logged_in=true parameter. Then the cart will apply the customer specific options to the cart, and if the customer comes back to the headless site, then the cart will be updated with the customer data. Of course, this is kind of a terrible UI, as you should be able to set the customer on the cart on the headless site without first redirecting to the checkout.

[osseonews]

I noticed in the skeleton component that you now use updateBuyerIdentity and update the token in the customerAccessToken: customerAccessToken?.accessToken, so does this functionality now work correctly so that the customerAccessToken required in the Storefront API for the cartBuyerIdentityUpdate mutation, is now able to accept the customerAccessToken created by the Customer Accounts API ? Do we need to update the API version for this to work?

[blittle]

It does not work quite yet, but it's high priority to make this seamless.

[hydrogenrun]

@blittle do you have any new information? I’m facing a similar issue when updating cartBuyerIdentifier using cart.updateBuyerIdentity (the accessToken I passed is obtained from customerAccount.getAccessToken), but it seems like the accessToken generated from the CA API is not compatible—it always returns null.

[NickHazen]

@blittle Is there an update on this issue. Is there a workaround? I'm struggling to understand how to use the CA API with the Cart Handler. Any feedback would be greatly appreciated.

[coryagami]

I was able to get this working recently, by virtue of needing B2B features and stumbling across a recently added unstable B2B example - https://github.com/Shopify/hydrogen/tree/main/examples/b2b and then digging through this PR to piece everything together.

The main thing seems to be opting into the unstable featureset by adding unstableB2b: true to createCustomerAccountClient, which then triggers a newly added branch in the login code here that automatically swaps your customerAccount access token using storefrontCustomerAccessTokenCreate. Make sure you pass the customerAccount client into your createCartHandler as per the PR and that was enough to get it working for me with B2B features (contextual pricing / catalogs / B2B checkout experience, etc.)

If you don't need B2B features you could likely skip some of the steps of the example / PR but just reading through this PR should be enough to get you started in the right direction - #1886

Disclaimer - this did stop working for me earlier today, after working for the last few weeks just fine. Seems a bug was introduced resulting in Internal error. Looks like something went wrong on our end. errors when hydrogen calls storefrontCustomerAccessTokenCreate so it definitely is still "unstable"... very unfortunate as we are paying a lot for shopify plus specifically for B2B features. @coryagami

@blittle if you see this an example failing request id is c69fc27a-a306-4b42-b676-44d7e722ed16-1725920084 if you can help me get this resolved and B2B working again.

[osseonews]

How long are the refresh tokens good for? Example: A customer logs in to our app, and we save the refresh token to a cookie. Then let's say they come back 24 hours later, will the refresh token still work to get a new access token or does it have an expiry date?

[osseonews]

BTW, according to the docs here: https://shopify.dev/docs/api/customer a request for the refresh token will return a new id_token. However, this is not true. When you send in a request for a refresh_token, you do not get back a new id_token. I assume the id_token from the initial access token request should be used as the id_token? Because the refresh_token endpoint does not send back an id_token per above.

[coryyeakelacdc]

@blittle @michenly Can one of you please clarify what to do about the above comment?

I'm seeing the same issue where the Use refresh token docs state that this request will return the same response as the initial Obtain access token step, but this is not true, id_token is not returned. However, the ID token is necessary for Logging out, and without it, Shopify will redirect to shopify.com instead of the provided redirect URI, which obviously isn't ideal.

With that said, can you clarify the following: Is the API response incorrect? Or are the docs incorrect?

Additionally, depending on above, can you recommend how to handle this? My current "solution" is to only set the ID token during the Obtain step, and not update it during a refresh. Additionally, I'm keeping the ID token for as long as I keep the refresh token so that it can be used during logout. If this is acceptable, I'll keep things this way, but I'm curious whether you think I should handle it differently.

[michenly]

I believe you found a 🐛 in our docs & utility! Thank you so much

I have confirmed with the CA API team that the id_token from the original auth call is the one to keep for logout and it does NOT get updated with a refresh.
I will update the utility and I have notify the CA API team to do a doc update as well.

[coryyeakelacdc]

@michenly Awesome, thank you for confirming this and taking the time to follow up. Much appreciated!

[michenly]

The fix: #2112, this will be release in June.

[marnauortega]

I'm not sure if this is the place to ask about this, but do you have any idea if we can expect the login page and the verification code email to be translatable to other languages anytime soon? Otherwise I'll scare my clientbase by suddenly changing the website language. Thanks a lot!

[michenly]

The login page does support some languages right now, and hydrogen had added support for this recently. You can expect this to be release in April 2024. Hope that helps!

[osseonews]

The customer account API pages on Shopify now have a very annoying "Cloudflare checking if you are human" flag for every login and logout. This is very confusing to customers and renders the entire experience totally suboptimal. Sometimes customers can wait a few seconds to see the login.

[blittle]

Hi @osseonews, do you have reports of customers running into this? It's more likely as a developer, loading the page over and over again, but should be very unlikely for real customers.

[osseonews]

Hey, thank for the reply. Yes, you are correct, I haven't heard any customers complain yet. But, we see it alot in development, so was worried about it carrying over to production.

[blittle]

We are still researching on our end, to make sure that customers aren't affected. If they are, it will be high priority to fix ASAP.

[michenly]

Closing this discussion since the API is officially in Hydrogen now