Getting started with the Customer Account API

In this tutorial, you'll learn how to do the following tasks:

• Enable new customer accounts.
• Configure Customer Account API access on the Headless and Hydrogen sales channels.
• Perform authorization requests and make queries.
• Rotate credentials.

• You have Apps and channels permissions on the Shopify store that you're working with.
• You have installed the Headless or Hydrogen sales channel from the Shopify App Store.

Shopify's new customer accounts is required to use the Customer Account API. New customer accounts allow you to seamlessly persist customer logins across online store, Hydrogen, and checkout.

1. From your Shopify admin, click Settings.
2. Click Customer accounts.
3. Under Accounts in online store and checkout section, click on Edit.
4. Choose New customer accounts.
5. Click Save.

To use the Customer Account API, you first need to enable it and get your access credentials.

1. From your Shopify admin, under Sales channels, click Headless or Hydrogen.
2. Select your storefront.
3. Complete one of the following steps:
   • If you selected Headless, then navigate to Customer Account API settings.
   • If you selected, Hydrogen, then navigate to Storefront settings.
4. Optional: Modify the client type.
   • Public clients: For applications that are strictly client-side, or that don't have a server-side session where they can store the refresh token safely, for example, SPA, mobile applications, or Hydrogen.
     • Web clients: Suitable for web applications where the client-side environment is the primary interface for user interactions.
     • Mobile clients: Designed for mobile applications that require access to the API and don't have a server-side session for securely storing refresh tokens, for example, iOS and Android.
   • Confidential clients: For applications that have a back-end to perform the authorization request and a server-side session to hold the refresh token, for example, Express.js, ASP.NET, or Rails.
5. From the Credentials section, copy the client ID (and client secret, if applicable) to use in your requests.
6. From the Permissions section, verify that the right permission controls are set for your custom storefront.
7. Under Application endpoints, record the Authorization, Token, and Logout endpoints to be used in your requests.
8. In the Application setup section, specify the following client application settings:
   • Callback URL(s): The allowable list of URLs to redirect to after logging in.
     • Web applications: Callback URLs must be in the HTTPS scheme to ensure security.
     • Mobile applications: Callback URLs must use the custom scheme 'shop.{shop_id}.*' to make the scheme universally unique in accordance with Shopify's mobile application authorization standards.
   • Javascript origins: Specifies the origins that are allowed to use a client's OAuth credentials in a JavaScript application. Applies specifically to web-type public clients.
   • Logout URL (Optional): The URL to redirect to after logging out. This setting is not applicable to mobile public clients. For mobile clients, a successful logout returns a success message. Following this, any subsequent actions, such as navigating to a specific screen or displaying a confirmation message, are determined by the specific behaviors programmed into the mobile application.

To authenticate and use the Customer Account API, the OAuth 2.0 authorization specification needs to be implemented by the client as shown below.

Begin the flow by redirecting a user to the Authorization endpoint (recorded in Step 2 above) and specify the following required parameters:

• scope : Determine what data the access token will be able to retrieve from the API endpoints
• client_id : Recorded from Step 2 above
• response_type : Set to code to specify the authorization code flow
• redirect_uri : Specify one of the callback URLs defined in Step 2 above
• state : A string of characters which will be returned along with the code during callback/redirect

In addition to the parameters above, public clients need to implementing a code challenge and verifier and specify the code_challenge which is a string derived from the code_verifier using a hashing algorithm and the code_challenge_method defining the type of hashing algorithm used (ie. S256).

To obtain an access token, the client must make a POST request to the Token endpoint specified in Step 2 above, including the following required parameters:

• grant_type : Set to authorization_code
• client_id : The same client_id as used in the Authorize step
• code : The authorization code received in the Authorize step
• redirect_uri : The same URL specified in the Authorize step

Confidential clients are required to send their client_id and client_secret in the Authorization header.

If successful, the client will receive an access token. More details on the Obtain access token step can be found in the reference guide.

The final step in the authorization flow involves securing a new access token through the Token exchange by specifying the following required parameters:

• grant_type : Set to urn:ietf:params:oauth:grant-type:token-exchange
• client_id : The same client_id as used in previous steps
• audience : Set to 30243aa5-17c1-465a-8493-944bcc4e88aa
• subject_token : The access token received in the previous step
• subject_token_type : Set to urn:ietf:params:oauth:token-type:access_token
• scopes : Set to https://api.customers.com/auth/customer.graphql

Confidential clients are required to send their client_id and client_secret in the Authorization header.

If successful, the client will receive an access token that can now be used to make queries to the Customer Account API. Learn more about Use access token.

After you've completed the OAuth 2.0 authorization flow for the Customer Account API and you have received a token from a logged-in customer, you can now make queries using the Customer Account API.

For an example of how to use the Customer Account API with a Hydrogen storefront, refer to the Using Customer Account API with Hydrogen tutorial and consult the Customer Account API reference for available objects, queries, and mutations.

1. In the Credentials section, under Rotate credentials, click Generate new credentials.
2. Update any applications or scripts with the new credentials. The old credentials remain valid until you revoke them.
3. When all applications or scripts have been updated, click Revoke next to the old credentials.
4. When prompted, click Revoke credentials.

• Follow the Using Customer Account API with Hydrogen tutorial.
• Learn more about the Customer Account API.