ID token claim import

When customers authenticate through a third-party identity provider, you can automatically import their profile data from ID token claims into Shopify customer records. This eliminates the need for separate API calls to populate customer information.

Anchor to RequirementsRequirements

• A Shopify Plus plan
• A third-party identity provider configured through the Shopify admin
• The identity provider must verify that the customer owns their email address and return an email_verified claim set to true

Anchor to How it worksHow it works

During the identity provider login flow, your identity provider returns an ID token containing claims about the customer. Shopify extracts supported claims from this token and writes them to the customer record. After authentication completes, the customer record is populated with the imported data.

Only email and email_verified are required for authentication. Validation of all other claims is silent: invalid values are ignored and never block login. HTML content in any field is rejected to prevent cross-site scripting.

Anchor to Request the required scopesRequest the required scopes

Standard OIDC claims are only returned by your identity provider when the matching scope is requested during sign-in. Shopify requests openid and email by default. To import other standard claims, add the scopes they require to the Additional scopes field in the Shopify admin under Settings > Customer accounts > Third-party identity provider:

When you request a scope, your identity provider is permitted to return the claims that scope covers, and Shopify imports the supported claims it recognizes. When you don't request a scope, the provider omits its claims and the matching customer fields are left unchanged. A sample Additional scopes value that requests every importable standard claim (along with a refresh token) is profile phone address offline_access.

Anchor to Userinfo backfill for skinny ID tokensUserinfo backfill for skinny ID tokens

Some identity providers issue "skinny" ID tokens that omit standard profile claims to keep the token small, and instead expose those claims from the provider's /userinfo endpoint. When this happens, Shopify backfills the missing claims from /userinfo, so requesting the right scope is all you need to do — whether the provider delivers the claim in the ID token or from /userinfo.

The backfill follows a strict contract:

• Scope-gated. A claim is fetched and imported only when its OIDC scope (from the table above) is in your Additional scopes. Adding the scope is how you opt in.
• The signed ID token always wins. /userinfo fills only a claim that's blank or absent in the ID token. A value that's present in the signed ID token is never overwritten by /userinfo.
• Provider-agnostic. The backfill works for any third-party OIDC provider that has Sync customer data enabled and exposes a userinfo_endpoint in its discovery document. It isn't specific to any one provider.
• Best-effort. If the /userinfo request fails for any reason — an unreachable endpoint, a malformed response, or a subject that doesn't match the ID token — sign-in still succeeds. The customer is signed in without the enriched fields, and Shopify retries the backfill on their next sign-in.

Only given_name, family_name, phone_number, and the standard OIDC address are eligible for /userinfo backfill.

Anchor to Email and email verificationEmail and email verification

The ID token must include email and email_verified. Shopify uses the email to find an existing customer record or create a new one.

If email_verified is not true, the login is blocked and the customer sees an error page. The identity provider is responsible for verifying that the customer controls the email address before setting this claim to true.

Anchor to ConfigurationConfiguration

In the identity provider settings in Shopify admin there are a few options that control how claim data is imported listed in the table below:

Anchor to Supported claimsSupported claims

The following claims can be mapped from your identity provider's ID token to Shopify customer fields.

Anchor to NameName

given_name and family_name map to the customer's first and last name. These are imported together and treated as a group. When overwriting, both values are replaced.

Anchor to Phone numberPhone number

phone_number maps to the customer's phone number in E.164 format (+16135551234). Phone numbers that fail validation are silently ignored.

Anchor to AddressAddress

address maps a single address to the customer record using the OIDC address claim field names:

• street_address → address1
• locality → city
• region → province_code (must be an ISO 3166-2 subdivision code like ON or CA-ON)
• postal_code → zip
• country → country_code (must be an ISO 3166-1 alpha-2 code like CA or US)

Anchor to TagsTags

The urn:shopify:customer:tags claim is a comma-separated string of tags. Tags are treated as a group. When overwriting, all existing tags are replaced with the values from the claim.

Anchor to AddressesAddresses

The urn:shopify:customer:addresses claim is an array of address objects that follows the Admin API customer address format. The first_name, last_name, and phone fields on each address are distinct from the customer-level given_name, family_name, and phone_number claims and can differ from them.

Addresses are treated as a group. When overwriting, all existing addresses are replaced with the values from the claim. Sending an empty array ([]) clears all addresses from the customer record.

Anchor to Default addressDefault address

When both the OIDC address claim and custom urn:shopify:customer:addresses are provided, Shopify determines the default shipping address using this priority:

1. If any custom address has default: true, that address is used.
2. If no custom address has default: true, the OIDC standard address becomes the default.
3. If only custom addresses are provided with no default flag, the first address in the array is used.

Anchor to Additional resourcesAdditional resources

• OpenID Connect Core 1.0 — Requesting claims using scope values (§5.4)
• OpenID Connect Core 1.0 — Standard claims
• OpenID Connect Core 1.0 — Address claim
• OpenID Connect Core 1.0 — UserInfo endpoint