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 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)

These claims follow the OpenID Connect standard claims specification.

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.