Unlink a Customer's Identity Provider Subject with Shopify GraphQL…

A practical guide to unlinking a customer's identity provider subject with the Shopify GraphQL Admin API: scopes, mutations, error handling, privacy and recovery.

October 25, 2026Digital Executive Partner

Unlink a Customer's Identity Provider Subject with Shopify GraphQL…

To unlink a customer's identity provider subject with the GraphQL Admin API, you remove the binding between that customer record and the external login identifier (the sub claim from an OIDC provider or similar). This guide covers what that subject is, which mutation and scopes you need, how to unlink safely in a custom app, and how to handle errors, privacy requests and account recovery.

This is developer-facing work. It is not a click in the Shopify admin. You need a custom app with the right customer scopes, a clear picture of which providers you support, and a process for verifying the request before anything is deleted.

What an identity provider subject is and why unlinking matters

When a customer signs in through an external identity provider (Google, Apple, Microsoft, a corporate SSO, or your own OIDC service), Shopify stores a link between the customer record and that provider. The subject is the provider's stable, unique identifier for that person, usually the sub claim in the ID token.

That link does three things:

It lets the customer return and sign in without re-creating an account.
It prevents duplicate customer records when the same email arrives from two login paths.
It tells your app which external identity owns which Shopify customer.

Unlinking matters when the link is wrong or no longer wanted:

Account recovery. A customer lost access to the provider account (old work email, deleted Google account) and needs to log in another way.
Shared or transferred accounts. A subject was attached to the wrong customer record, often after a merge or a manual import.
Multi-provider conflicts. The same person signs in with two providers and ends up with two customer records.
Privacy requests. A customer asks you to disconnect a third-party login from their store account.

In every case the goal is the same: remove the binding, keep the customer record intact, and let the person re-link through a path you control.

The customer identity mutation: inputs, scopes and permissions

Shopify exposes customer identity operations through the GraphQL Admin API. The exact mutation name and field set can change between API versions, so always confirm against the current schema for the version you pin. The pattern is consistent: you supply the customer ID and the identity provider details, and the API returns the updated customer or a list of user errors.

What you send

Typical inputs:

Customer ID in global ID format (gid://shopify/Customer/...).
Identity provider identifier, matching what Shopify stored when the link was created.
Subject value, the provider's sub claim.

What you need

A custom app installed on the store, or a public app with the customer scopes approved during install.
Customer read and write scopes. Read alone is not enough for unlinking.
API version pinned in the endpoint URL, for example /admin/api/2025-01/graphql.json. Never call an unpinned endpoint for identity work.
Store owner consent if the app is public, since you are modifying customer authentication data.

What you get back

A payload with the updated customer and a userErrors array. Treat userErrors as the primary failure signal. A 200 response with a populated userErrors array is a failed unlink, not a success.

Step-by-step: unlinking a subject safely in a custom app

1. Confirm the link exists

Query the customer and list their identity providers before changing anything. Record the provider and subject you are about to remove. This is your audit trail and your rollback reference.

2. Verify the request

Do not unlink on an unauthenticated support email alone. Confirm identity through a channel you already trust, for example a signed-in session on another provider, an order-history challenge, or a verified email reply. Log who approved the change and when.

3. Run the mutation

Send the customer ID, provider and subject. Use an idempotency key in your own system so a retried request does not double-process. Keep the call small: one customer, one subject per request.

4. Check `userErrors` before anything else

If the array is empty, the unlink succeeded. If it is populated, read each message. Common causes are a mismatched subject, a customer ID that no longer exists, or a provider value Shopify does not recognise.

5. Re-read the customer

Query the identity providers again and confirm the subject is gone and the others remain. Do not trust the mutation payload alone.

6. Notify and re-link

Tell the customer what changed and how to sign in now. If they need a new provider, send them through your normal linking flow rather than attaching a subject manually.

7. Record it

Store the customer ID, provider, subject hash, timestamp, operator and outcome. If you handle deletion requests, this log is what you show when asked.

If you are building this inside a larger Shopify integration, our Shopify app development team can scope the identity work alongside your store automations.

Code editor showing source code on a dark screen

Handling errors, retries and partial unlinks

Identity operations fail in specific ways. Plan for each.

Situation	Symptom	What to do
Subject not found	`userErrors` mentions the provider or subject	Re-read the customer, confirm the exact stored value, do not guess
Wrong customer ID	Customer not found	Re-resolve the customer from your own mapping table
Scope missing	Access denied or auth error	Reinstall or update the app with customer write scope
Rate limited	Throttle response	Back off with jitter, retry the same single operation
Partial unlink	One provider removed, one remains	Treat as success for that subject, log the rest, do not retry blindly
Duplicate customer records	Two customers, one subject	Unlink from the wrong record first, then merge or archive deliberately

Rules that save time later:

Retry only idempotent operations. A retried unlink for a subject that is already gone should return cleanly, not create a second change.
Never batch unrelated customers in one job without per-customer error capture. One bad record should not block the rest.
Alert on repeated userErrors. A spike usually means your stored subject values are stale.
Keep a dry-run mode. Print what would be unlinked before you unlink it, especially in production.

Privacy, GDPR and account-recovery implications

Unlinking a subject is not the same as deleting a customer. Be precise about which one the person asked for.

Unlink only: removes the external login binding. The customer record, orders and history stay.
Delete customer: a separate, heavier operation with its own retention rules. Do not use unlinking as a shortcut.
Access request: unlinking may be part of the response, but you still need to disclose what identity data you held.

Practical points:

Document the lawful basis for holding subject values at all. If you do not need them, do not store them in your own database.
Minimise copies. Keep a hash or reference, not the raw subject, unless your flow requires it.
Set a retention window for unlink logs and state it in your privacy notice.
Coordinate with account recovery. After unlinking, the customer may have no login method. Give them a clear next step before you close the ticket.
Check app permissions during review. An app that can unlink identities should say so plainly in its listing.

If you would rather not maintain this yourself, our products and services overview shows how we handle Shopify-side integrations, including identity and CRM sync.

When to build this yourself vs hire a Shopify app team

Build it in-house if you have a developer who already owns your Shopify app, a small number of identity providers, and a support process that can verify requests. The mutation itself is a few lines; the work is in verification, logging and recovery.

Bring in a team if any of these are true:

You support several providers and duplicate customer records are already common.
You handle privacy requests with legal deadlines.
You need this inside a public app with review requirements.
Your current app has no audit log for customer identity changes.
You also need the same customer data flowing into Zoho CRM or another system without manual exports.

A short scoping call usually settles which side you are on. The build is small; the process around it is what protects you.

Frequently asked questions

Can I unlink a customer's identity provider in the Shopify admin?

Not as a standard admin action. Unlinking is done through the GraphQL Admin API from a custom or public app with customer write scope. The admin shows customer details but does not expose identity provider unlinking as a routine setting.

Which scopes do I need to unlink a customer identity provider subject?

You need customer read and write scopes on an installed app, plus a pinned API version. Read-only access is enough to inspect identity providers but not to remove a binding.

Does unlinking a subject delete the customer record?

No. Unlinking removes the binding between the customer and the external login identifier. The customer record, orders and history remain. Deleting a customer is a separate operation with its own retention rules.

What happens to the customer after I unlink their identity provider?

They can no longer sign in with that provider. If they have another linked provider or a password, they can use that. Otherwise they need a new linking flow, so tell them the next step before closing the request.

How do I know the unlink actually worked?

Check the userErrors array in the mutation response, then re-query the customer's identity providers and confirm the subject is gone while the others remain. Do not rely on the mutation payload alone.

Is unlinking a subject enough to satisfy a GDPR deletion request?

Usually not on its own. Unlinking disconnects a login method; a deletion request may also cover the customer record and your own stored identity data. Confirm the scope of the request and document what you removed.

Need customer identity unlinking built properly?

We build Shopify apps and integrations that handle identity changes with verification, audit logs and error handling. Tell us your providers and we will scope it.

Start a project Explore Shopify App Development