orcaqubits/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

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