Customer Accounts

In this document, you’ll learn how registered and unregistered accounts are distinguished in the MedusaGo application.

has_account Property#

The Customer data model has a has_account property, which is a boolean that indicates whether a customer is registered.

When a guest customer places an order, a new Customer record is created with has_account set to false.

When this or another guest customer registers an account with the same email, a new Customer record is created with has_account set to true.

Email Uniqueness#

The above behavior means that two Customer records may exist with the same email address. However, the main difference is the has_account property's value.

So, there can only be one guest customer (having has_account=false) and one registered customer (having has_account=true) with the same email address.

Change a Guest Customer to a Registered Customer#

You can only set the has_account property when you create a customer. The updateCustomersWorkflow and the Customer Module's updateCustomers method don't accept it. So, you can't change an existing guest customer to a registered customer.

This affects flows that link a new auth identity to an existing guest customer. For example, a custom auth provider that sets the customer_id in the auth identity's app metadata to the guest customer's ID. The customer can log in, but the Medusa Admin still shows them as a guest.

Instead, use one of the following approaches.

Set has_account When Importing Customers#

If you're migrating customers from another platform, set has_account to true for customers that have accounts when you create them. How you do that depends on whether the customer's auth identity already exists at import time.

Register a New Customer Account#

When a guest customer registers, use the createCustomerAccountWorkflow to create a registered customer with the same email. The workflow also sets the customer's ID in the auth identity's app metadata. It doesn't change the existing guest customer.

The guest customer's orders stay linked to the guest customer. To move them to the registered customer, the customer can request an order transfer using the Request Order Transfer API route.

Email Must Match the Auth Identity#

When you pass an authIdentityId to the createCustomerAccountWorkflow, the workflow retrieves the auth identity and its provider identities. It then checks that the customer's email matches one of the following values of a provider identity:

• The entity_id of an emailpass provider identity, or of any provider identity whose entity_id is a valid email.
• The email property in the user_metadata, which third-party providers like Google set.

The comparison ignores letter case and leading or trailing whitespace. If the email doesn't match, the workflow throws an unauthorized error with the message The customer's email must match the email of the authenticated identity.

This check prevents a customer from creating an account with an email they didn't authenticate with. If you use a custom auth provider, make sure it stores the customer's email in the provider identity's entity_id or user_metadata.email.

Customer Deletion and Email Reuse#

When a merchant deletes a customer, the Customer record is soft-deleted, meaning it is not permanently removed from the database.

When using the MedusaGo Application with the Auth Module, possible confusion may arise in the following scenarios:

1. An admin user is using the email address john@example.com, and a customer tries to register with the same email address.
2. An admin user has deleted a customer with the email address jane@example.com, and another customer tries to register with the same email address.

In these and similar scenarios, the customer trying to register will receive an error message indicating that the email address is already in use:

{
  "type": "unauthorized",
  "message": "Identity with email already exists"
}

To resolve this, you can amend the registration flow to:

1. Retrieve the login token of the existing identity with the same email address.
2. Use the login token when registering the new customer. This will not remove the existing identity but will allow the new customer to register with the same email address.

You can learn more about how to implement this flow in the following guides:

• Conceptual guide on how to implement this flow with Medusa's authentication routes.
• How-to guide on how to implement this in a storefront.