Medusa Customers

Medusa v2 Customer Management

Before writing code

Fetch live docs:

1. Web-search site:docs.medusajs.com customer module for customer data model and service methods
2. Web-search site:docs.medusajs.com auth module for authentication providers and flows
3. Web-search site:docs.medusajs.com customer group for group management and pricing rules
4. Fetch https://docs.medusajs.com/resources/references/customer and review the ICustomerModuleService interface
5. Web-search medusajs v2 auth provider social login 2026 for latest authentication patterns

Customer Data Model

Entity Relationships

Key Fields

Authentication Architecture

Medusa v2 separates customer identity from authentication via the Auth Module:

Auth Module
├── AuthIdentity
│   ├── provider_identities[] (emailpass, google, github...)
│   └── app_metadata (linked customer_id)
└── Auth Providers (built-in + custom)

Authentication Flow

Register/Login ──> Auth Module validates ──> JWT token
  ──> Token includes auth_identity_id ──> Linked to customer_id

Auth Provider Comparison

Email + Password Flow

Social Login Flow (OAuth2)

Fetch live docs for OAuth2 callback handling, redirect URIs, and token exchange flow.

Customer Groups

Use Cases

Key Service Methods

Address Management

Store API Routes

All /store/customers/me routes require a valid JWT in the Authorization header.

Admin API Routes

Fetch live docs for request body shapes and query parameters on each route.

Best Practices

Authentication

• Use the Auth Module for all authentication -- never implement custom auth logic outside it
• Support both emailpass and at least one OAuth2 provider for user convenience
• Store provider-specific data in provider_identities, not in customer metadata
• Always link auth identities to customer profiles via app_metadata.customer_id

Customer Data

• Use has_account to distinguish registered customers from guest checkouts
• Store loyalty points, preferences, and custom attributes in metadata
• Use customer groups for segmentation -- avoid duplicating group logic in app code

Address Management

• Validate addresses against country-specific requirements (postal code formats)
• Set is_default_shipping and is_default_billing to streamline checkout

Security

• Validate JWT tokens on every authenticated request
• Scope Store API customer data to the authenticated customer only
• Never expose customer lists or group memberships via the Store API

Fetch the Medusa v2 customer module and auth module documentation for exact service method signatures, auth provider configuration, and JWT handling before implementing.