Medusa v2 Customer Management
Before writing code
Fetch live docs:
- Web-search
site:docs.medusajs.com customer module for customer data model and service methods
- Web-search
site:docs.medusajs.com auth module for authentication providers and flows
- Web-search
site:docs.medusajs.com customer group for group management and pricing rules
- Fetch
https://docs.medusajs.com/resources/references/customer and review the ICustomerModuleService interface
- Web-search
medusajs v2 auth provider social login 2026 for latest authentication patterns
Customer Data Model
Entity Relationships
| Entity | Relationship | Key Fields |
|---|
| Customer | Root | email, first_name, last_name, phone, has_account, metadata |
| Addresses[] | Customer → many | address fields, country_code, is_default_shipping/billing |
| CustomerGroups[] | Customer ↔ many | Many-to-many group membership |
| Orders[] | Customer → many (link) | Via Order Module link |
Key Fields
| Field | Type | Description |
|---|
email | string | Unique identifier for the customer |
has_account | boolean | true for registered, false for guest |
first_name / last_name | string | Customer name |
phone | string | Phone number |
metadata | JSONB | Custom key-value data |
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
| Provider | Type | Configuration |
|---|
emailpass | Built-in | No external config needed |
google | OAuth2 | Client ID + secret |
github | OAuth2 | Client ID + secret |
| Custom | Extensible | Implement AbstractAuthModuleProvider |
Email + Password Flow
| Step | Endpoint | Purpose |
|---|
| Register | /auth/customer/emailpass/register | Create auth identity |
| Login | /auth/customer/emailpass | Authenticate, get token |
| Create customer | /store/customers | Create customer profile (with token) |
Social Login Flow (OAuth2)
| Step | Endpoint | Purpose |
|---|
| Initiate | /auth/customer/{provider} | Get redirect URL |
| Callback | /auth/customer/{provider}/callback | Exchange code for token |
| Create/Link | /store/customers | Create or link customer profile |
Fetch live docs for OAuth2 callback handling, redirect URIs, and token exchange flow.
Customer Groups
| Field | Type | Description |
|---|
name | string | Group name (e.g., "VIP", "Wholesale") |
metadata | JSONB | Custom group data |
customers | relation | Many-to-many with customers |
Use Cases
| Use Case | Mechanism |
|---|
| Group-specific pricing | Price List rules linked to customer groups |
| Conditional promotions | Promotion rules targeting customer groups |
| Access control | Custom middleware checking group membership |
Key Service Methods
| Operation | Method |
|---|
| Create group | customerModuleService.createCustomerGroups() |
| Add to group | customerModuleService.addCustomerToGroup() |
| Remove from group | customerModuleService.removeCustomerFromGroup() |
| List groups | customerModuleService.listCustomerGroups() |
Address Management
| Field | Required | Notes |
|---|
first_name / last_name | Yes | |
address_1 | Yes | Street address |
city | Yes | |
country_code | Yes | ISO 2-letter code |
postal_code | Conditional | Required by country |
is_default_shipping / is_default_billing | No | Default flags |
| Workflow | Purpose |
|---|
createCustomerAddressesWorkflow | Add new address |
updateCustomerAddressesWorkflow | Update existing address |
deleteCustomerAddressesWorkflow | Remove address |
Store API Routes
| Route Pattern | Method | Purpose |
|---|
/store/customers | POST | Create customer profile |
/store/customers/me | GET | Retrieve authenticated customer |
/store/customers/me | POST | Update customer profile |
/store/customers/me/addresses | GET/POST | List/add addresses |
/store/customers/me/addresses/:id | POST/DELETE | Update/remove address |
All /store/customers/me routes require a valid JWT in the Authorization header.
Admin API Routes
| Route Pattern | Method | Purpose |
|---|
/admin/customers | GET/POST | List/create customers |
/admin/customers/:id | GET/POST | Retrieve/update customer |
/admin/customer-groups | GET/POST | Manage groups |
/admin/customer-groups/:id/customers | POST | Add customers to group |
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.
