New Customer Account API Migration

Follow these steps to migrate from the legacy customer accounts to the new Customer Account API.

This migration is required before integrating the Shopify B2B logic into the codebase.

Migration Caveats:

  • The logged in experience will no longer be supported while in the Pack Customizer due to the nature of customer authentication
  • Customer accounts doesn't support the use of localhost due to security concerns. In order to use customer accounts while in development, localhost must be hosted on a public URL via ngrok (see below for instructions)
  • Multipass is currently not supported, though if a customer is logged in and goes to checkout, logging in will be a one click action

Local Development and Hydrogen Settings

For official Shopify documentation for Customer Account API with Hydrogen, it can be referenced here, but the pertinent steps are re-outlined below.

Set up ngrok

ngrok has a free plan but is limited by the number of HTTP requests that can be made monthly. The free plan may be sufficient to get through this migration, but upgrading to a paid plan may be a likely scenario for the long term maintenance of the store, due to the added convenience to create your own domain and to not be limited by your usage. In later steps, the ngrok domain will need to be added officially into Hydrogen settings.

  1. Set up an ngrok account
  2. If you have a paid account, add a static domain in your ngrok settings. If you are using the free plan, a random domain is generated for you after every instance as seen in the terminal, e.g. https://abc123def456.ngrok-free.app
  3. Install the ngrok CLI
  4. In a terminal, start ngrok using the following command:

Paid account: ngrok http --domain=<your-ngrok-domain> 8080

Free account: ngrok http 8080

Notes:

  • Working off ngrok is only needed for using customer accounts, all other development can still be viewed on localhost directly
  • Stopping or restarting localhost does not kill the ngrok instance
  • If you using the free plan and the ngrok instance is stopped, upon starting again, a new random domain will be generated, thus this new domain will need to replaced with the one added in Hydrogen settings

Update the application setup

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

  1. The panel can be found in Storefront settings for the Hydrogen store, then under Customer Account API
  2. Under Application setup, click Edit to edit the endpoints
  3. Under Callback URI(s), click Add Callback URI, add all the /account/authorize url's prefixed with their domain
  • First add https://<your-main-domain>.com/account/authorize, e.g. https://storefront.com/account/authorize
  • Next add one with the ngrok domain as in https://<your-ngrok-domain>.app/account/authorize, e.g. https://abc123def456.ngrok-free.app/account/authorize

    If you are using the free ngrok plan, this domain will repeatedly change on every instance, so this value will continually be replaced during development. This is when the paid account will prove convenient.

  1. Under JavaScript origin(s), click Add origin, and all your domains
  • First add the main domain, e.g. https://storefront.com
  • Next add the ngrok domain, e.g. https://abc123def456.ngrok-free.app
    • As mentioned above, this value will likely be replaced out during development if using a free ngrok account
  1. Under Logout URI, click Add Logout URI, and all your domains
  • First add the main domain, e.g. https://storefront.com
  • Next add the ngrok domain, e.g. https://abc123def456.ngrok-free.app
    • As mentioned above, this value will likely be replaced out during development if using a free ngrok account

Code Migration

Most steps will link to part of the Blueprint release that it is in reference to. These steps will require copying these code changes as a guide of what exactly to do.

When opening a link, it may take 2-5 seconds for it to scroll to the intended block of code.

Env variables:

Add both PUBLIC_CUSTOMER_ACCOUNT_API_CLIENT_ID and PUBLIC_CUSTOMER_ACCOUNT_API_URL to the .env file, if not already added. The values can be found under the "Ready-only variables" in Hydrogen settings Environment and variables

Add Customer Account client:

  1. In server.ts, add createCustomerAccountClient and pass customerAccount into getLoadContext [commit]
  2. In root.tsx, remove customerAccessToken logic and replace with customerAccount client logic [commit]
  3. In remix.env.d.ts or env.d.ts, add new Env and client types [commit]
  4. In useCustomer.ts, remove logic pertaining to previewModeCustomer [commit]
  5. Create a new file for the new Customer Account API Graphql queries [commit]
  • For Blueprint, the new Graphql file exists in a new customer-account folder created under app/data/graphql, but matching this folder structure is not important, rather just ensure all Graphql imports from this file are imported correctly after the migration

Customer folder and hooks bulk actions:

  1. Delete the entire customer folder in the app/lib folder**
  2. Download this customer folder and paste the folder into the app/lib folder
  3. For customer hooks, download this customer folder and paste the folder into the app/hooks folder; then add the export to the index.ts file [commit]

When deleting the entire app/lib/customer folder at once, the assumption is that additional logic has not been added to these files or folders to accommodate custom functionality, i.e. code that is not default on Blueprint. Check your git changes to ensure these deleted files do not contain any pertinent code custom to the store. If so, manual intervention will be required to incorporate them into the migration.

Examples include:

  • Additional fields queried with Graphql for the customer. Reference the new Customer Account API Customer object to see what Graphql fields are accepted
  • Additional hooks or logic added for additional customer integrations

Cleanup account components:

  1. Delete GuestAccountLayout.tsx from the app/components/AccountLayout folder; then delete its export from the index.ts file [commit]
  2. Delete the Login folder, Register folder, Activate.tsx file and ResetPassword.tsx file from the app/components/Account folder; then delete their exports from the index.ts file [commit]
  3. In Layout.tsx, remove usePreviewModeCustomerInit() [commit]
  4. In CustomerAccountLayout.tsx, customerPending logic can be removed because it is no longer relevant [commit]

Delete old customer routes and replace with new ones:

  1. Delete all the current customer routes:
  • ($locale).account.$.tsx (will be added back in next step)
  • ($locale).account.addresses.tsx (will be added back in next step)
  • ($locale).account.orders._index.tsx (will be added back in next step)
  • ($locale).account.orders.$id.tsx (will be added back in next step)
  • ($locale).account.profile.tsx (will be added back in next step)
  • ($locale).account.tsx (will be added back in next step)
  • ($locale).account.activate.$id.$activationToken.tsx
  • ($locale).account.login.multipass.tsx
  • ($locale).account.login.tsx
  • ($locale).account.logout.tsx
  • ($locale).account.register.tsx
  • ($locale).account.reset.$id.$resetToken.tsx
  • ($locale).api.customer.tsx
  1. Download new/updated account routes and paste each route into the app/routes folder

When deleting the files, ensure that any custom functionality specific to the store has not just been wiped by checking the git changes. If so, add it back into the code accordingly.

Update instances of customer email:

  1. Find instances of customer?.email or customer.email and replace the .email with .emailAddress?.emailAddress, e.g. customer.emailAddress?.emailAddress
    • In Blueprint, these changes happen in the following files. They may exist elsewhere for different repos:

Add useProductById hook:

  1. In the app/hooks/product folder, add useProductById.ts [commit]
  2. Add the export to the index.ts file [commit]
  3. Add ($locale).api.product-by-id.tsx to the app/routes folder [commit]
  4. Add this new Graphql query to the Storefront API graphql file [commit]

Update address properties:

  1. In AddressForm.tsx make these changes to the code. Changes include:
  • Update province and country useState default
  • Update countries useMemo
  • Add countriesByShortCode useMemo
  • Update provinces useMemo
  • Add provincesByShortCode useMemo
  • Update the useEffect
  • Update name for inputs for province, country, and phone accordingly
  • Update label for selectedOption for each Select input
  1. In AddressesItem.tsx make these changes to the code. Changes include:
  • Update properties destructured from address
  • Update name to firstName and lastName
  • Map out new formatted address

Update order and order properties:

  1. In Order.tsx, destructure order from useLoaderData instead of useCustomerOrder, which is now deprecated [commit]
  2. In OrderAddressAndStatus.tsx (or wherever address and status info is displayed), make these changes to the code. Changes include:
  • Update properties destructured from order and shippingAddress
  • Update shippingUrl
  • Map out new formatted address
  • Update old variables with corresponding new properties
  1. In OrderItem.tsx, make these changes to the code. Changes include:
  • Update properties destructured from order and item
  • Update originalPrice and discountedPrice useMemo
  • Fetch full product using the new useProductById hook
  • Update old variables with corresponding new properties
  1. In OrderTotals.tsx, make these changes to the code. Changes include:
  • Update currencyCode
  • Update totals useMemo
  1. In Orders.tsx, grab customer orders from customer from useCustomer instead of useCustomerOrders, which is now deprecated [commit]

Add new constants:

  1. Add new constants to the constants file or folder [commit]

Remove Multipass checkout button:

  1. Delete MultipassCheckoutButton from app/components/Cart folder
  2. In CartTotals.tsx replace MultipassCheckoutButton with a Link, which simply links to the checkoutUrl [commit]

Update customer types:

  1. Replace types from @shopify/hydrogen/storefront-api-types with types from @shopify/hydrogen/customer-account-api-types, i.e.
    • Customer (e.g. root.ts, useCustomer.ts)
    • Order (check the order related pages)
    • CustomerAddress (formerly MailingAddress) (check the addressses related pages)

Remove deprecated global state variables:

  1. In either SettingsProvider.tsx or GlobalProvider.tsx (depending on what version Blueprint the store was built on), remove deprecated previewModeCustomer variables [commit]
  2. If it exists, delete usePreviewMode.ts
  3. In either context.types.ts or global.types.ts, delete deprecated types [commit]

Update Analytics components to accommodate new customer object:

  1. In Analytics.tsx, customerPending can be removed because it is no longer relevant [commit]
  2. For any in use XYZEvents.tsx, update the customer prop type from generic Record<string, any> to Customer type imported from @shopify/hydrogen/customer-account-api-types. Example
  3. In any relevant events.ts or utils.ts files, swap the following customer properties with the new corresponding property. Example
  • customer.email -> customer.emailAddress?.emailAddress
  • customer.numberOfOrders -> flattenConnection(customer.orders)?.length
  • customer.defaultAddress?.countryCodeV2 -> customer.defaultAddress?.territoryCode
  • customer.defaultAddress?.phone - > customer.defaultAddress?.phoneNumber
  • customer.defaultAddress?.provinceCode -> customer.defaultAddress?.zoneCode
  1. Explicitly type customer where needed. Example

Was this page helpful?