> ## Documentation Index
> Fetch the complete documentation index at: https://mintlify.com/medusajs/medusa/llms.txt
> Use this file to discover all available pages before exploring further.

# Customer Module

> Learn about the Customer Module and how to manage customers, addresses, and customer groups in Medusa.

## Overview

The Customer Module manages customer data including profiles, addresses, and customer group memberships. It provides essential customer relationship management capabilities for your commerce platform.

**Key Features:**

* Customer profile management
* Multiple address support
* Customer groups for segmentation
* Account and guest customer tracking
* Searchable customer data
* Custom metadata storage

## When to Use

Use the Customer Module when you need to:

* Create and manage customer profiles
* Store customer contact information
* Manage multiple shipping addresses per customer
* Organize customers into groups
* Track registered vs. guest customers
* Store custom customer attributes
* Search customers by name, email, or phone

## Data Models

### Customer

The core customer entity representing a person or business.

<ResponseField name="id" type="string" required>
  Unique customer identifier (prefix: `cus_`)
</ResponseField>

<ResponseField name="email" type="string">
  Customer email address (searchable)
</ResponseField>

<ResponseField name="first_name" type="string">
  Customer first name (searchable)
</ResponseField>

<ResponseField name="last_name" type="string">
  Customer last name (searchable)
</ResponseField>

<ResponseField name="company_name" type="string">
  Company name for B2B customers (searchable)
</ResponseField>

<ResponseField name="phone" type="string">
  Customer phone number (searchable)
</ResponseField>

<ResponseField name="has_account" type="boolean">
  Whether customer has a registered account (default: false)
</ResponseField>

<ResponseField name="created_by" type="string">
  ID of user who created the customer record
</ResponseField>

<ResponseField name="metadata" type="object">
  Additional custom data
</ResponseField>

<ResponseField name="addresses" type="CustomerAddress[]">
  Customer shipping/billing addresses
</ResponseField>

<ResponseField name="groups" type="CustomerGroup[]">
  Customer groups this customer belongs to
</ResponseField>

### CustomerAddress

Represents a saved customer address.

<ResponseField name="id" type="string" required>
  Unique address identifier
</ResponseField>

<ResponseField name="customer_id" type="string" required>
  ID of the parent customer
</ResponseField>

<ResponseField name="address_name" type="string">
  Name for this address (e.g., "Home", "Office")
</ResponseField>

<ResponseField name="is_default_shipping" type="boolean">
  Whether this is the default shipping address
</ResponseField>

<ResponseField name="is_default_billing" type="boolean">
  Whether this is the default billing address
</ResponseField>

<ResponseField name="first_name" type="string">
  First name
</ResponseField>

<ResponseField name="last_name" type="string">
  Last name
</ResponseField>

<ResponseField name="phone" type="string">
  Phone number
</ResponseField>

<ResponseField name="company" type="string">
  Company name
</ResponseField>

<ResponseField name="address_1" type="string">
  Address line 1
</ResponseField>

<ResponseField name="address_2" type="string">
  Address line 2
</ResponseField>

<ResponseField name="city" type="string">
  City
</ResponseField>

<ResponseField name="country_code" type="string">
  Two-letter ISO country code
</ResponseField>

<ResponseField name="province" type="string">
  State or province
</ResponseField>

<ResponseField name="postal_code" type="string">
  Postal/ZIP code
</ResponseField>

<ResponseField name="metadata" type="object">
  Additional custom data
</ResponseField>

### CustomerGroup

Groups customers for segmentation and targeting.

<ResponseField name="id" type="string" required>
  Unique customer group identifier
</ResponseField>

<ResponseField name="name" type="string" required>
  Customer group name
</ResponseField>

<ResponseField name="metadata" type="object">
  Additional custom data
</ResponseField>

<ResponseField name="customers" type="Customer[]">
  Customers in this group
</ResponseField>

### CustomerGroupCustomer

Join entity for many-to-many customer-group relationship.

<ResponseField name="id" type="string" required>
  Unique relationship identifier
</ResponseField>

<ResponseField name="customer_id" type="string" required>
  ID of the customer
</ResponseField>

<ResponseField name="customer_group_id" type="string" required>
  ID of the customer group
</ResponseField>

## Service Interface

The Customer Module service is available at `@medusajs/medusa/customer`.

### Retrieve Customer

Retrieve a single customer with related data.

<CodeGroup>
  ```typescript Example theme={null}
  import { MedusaRequest, MedusaResponse } from "@medusajs/framework/http"
  import { ICustomerModuleService } from "@medusajs/framework/types"
  import { Modules } from "@medusajs/framework/utils"

  export async function GET(
    req: MedusaRequest,
    res: MedusaResponse
  ) {
    const customerModuleService: ICustomerModuleService = req.scope.resolve(
      Modules.CUSTOMER
    )

    const customer = await customerModuleService.retrieveCustomer("cus_123", {
      relations: ["addresses", "groups"],
    })

    res.json({ customer })
  }
  ```
</CodeGroup>

<ParamField path="customerId" type="string" required>
  The ID of the customer to retrieve
</ParamField>

<ParamField path="config" type="FindConfig">
  Configuration for the query

  <ParamField path="relations" type="string[]">
    Relations to load (e.g., `["addresses", "groups"]`)
  </ParamField>

  <ParamField path="select" type="string[]">
    Fields to select from the customer
  </ParamField>
</ParamField>

<ResponseField name="customer" type="CustomerDTO">
  The retrieved customer
</ResponseField>

### List Customers

List customers with filtering and search.

<CodeGroup>
  ```typescript Example theme={null}
  const [customers, count] = await customerModuleService.listAndCountCustomers(
    {
      has_account: true,
      groups: { id: ["cgroup_vip"] },
    },
    {
      relations: ["addresses"],
      take: 20,
      skip: 0,
    }
  )
  ```
</CodeGroup>

<ParamField path="filters" type="FilterableCustomerProps">
  Filters to apply

  <ParamField path="id" type="string | string[]">
    Filter by customer IDs
  </ParamField>

  <ParamField path="email" type="string | string[]">
    Filter by email (supports partial match)
  </ParamField>

  <ParamField path="has_account" type="boolean">
    Filter by account status
  </ParamField>

  <ParamField path="first_name" type="string">
    Filter by first name (searchable)
  </ParamField>

  <ParamField path="last_name" type="string">
    Filter by last name (searchable)
  </ParamField>

  <ParamField path="phone" type="string">
    Filter by phone number (searchable)
  </ParamField>

  <ParamField path="groups" type="object">
    Filter by customer group
  </ParamField>
</ParamField>

<ResponseField name="customers" type="CustomerDTO[]">
  Array of customers matching the filters
</ResponseField>

<ResponseField name="count" type="number">
  Total count of matching customers
</ResponseField>

### Create Customers

Create one or more customer profiles.

<CodeGroup>
  ```typescript Example theme={null}
  const customer = await customerModuleService.createCustomers({
    email: "customer@example.com",
    first_name: "John",
    last_name: "Doe",
    phone: "+1234567890",
    has_account: true,
    addresses: [
      {
        address_name: "Home",
        first_name: "John",
        last_name: "Doe",
        address_1: "123 Main St",
        city: "New York",
        country_code: "us",
        postal_code: "10001",
        is_default_shipping: true,
        is_default_billing: true,
      },
    ],
  })
  ```
</CodeGroup>

<ParamField path="data" type="CreateCustomerDTO | CreateCustomerDTO[]" required>
  Customer data to create

  <ParamField path="email" type="string">
    Customer email address
  </ParamField>

  <ParamField path="first_name" type="string">
    Customer first name
  </ParamField>

  <ParamField path="last_name" type="string">
    Customer last name
  </ParamField>

  <ParamField path="company_name" type="string">
    Company name for B2B
  </ParamField>

  <ParamField path="phone" type="string">
    Phone number
  </ParamField>

  <ParamField path="has_account" type="boolean">
    Whether customer has a registered account
  </ParamField>

  <ParamField path="addresses" type="CreateCustomerAddressDTO[]">
    Initial addresses for the customer
  </ParamField>

  <ParamField path="metadata" type="object">
    Custom metadata
  </ParamField>
</ParamField>

<ResponseField name="customer" type="CustomerDTO | CustomerDTO[]">
  The created customer(s)
</ResponseField>

### Update Customers

Update customer information.

<CodeGroup>
  ```typescript By ID theme={null}
  const customer = await customerModuleService.updateCustomers("cus_123", {
    first_name: "Jane",
    phone: "+0987654321",
  })
  ```

  ```typescript By Selector theme={null}
  const customers = await customerModuleService.updateCustomers(
    { has_account: false },
    { has_account: true }
  )
  ```
</CodeGroup>

<ParamField path="idOrSelector" type="string | string[] | FilterableCustomerProps" required>
  Customer ID(s) or filter selector
</ParamField>

<ParamField path="data" type="CustomerUpdatableFields" required>
  Fields to update
</ParamField>

### Create Customer Addresses

Add addresses to a customer.

<CodeGroup>
  ```typescript Example theme={null}
  const address = await customerModuleService.createCustomerAddresses({
    customer_id: "cus_123",
    address_name: "Office",
    first_name: "John",
    last_name: "Doe",
    company: "Acme Corp",
    address_1: "456 Business Ave",
    city: "San Francisco",
    country_code: "us",
    postal_code: "94102",
    is_default_shipping: false,
    is_default_billing: false,
  })
  ```
</CodeGroup>

<ParamField path="data" type="CreateCustomerAddressDTO | CreateCustomerAddressDTO[]" required>
  Address data

  <ParamField path="customer_id" type="string" required>
    ID of the customer
  </ParamField>

  <ParamField path="address_name" type="string">
    Name for this address
  </ParamField>

  <ParamField path="is_default_shipping" type="boolean">
    Set as default shipping address
  </ParamField>

  <ParamField path="is_default_billing" type="boolean">
    Set as default billing address
  </ParamField>

  <ParamField path="first_name" type="string">
    First name
  </ParamField>

  <ParamField path="last_name" type="string">
    Last name
  </ParamField>

  <ParamField path="address_1" type="string">
    Address line 1
  </ParamField>

  <ParamField path="city" type="string">
    City
  </ParamField>

  <ParamField path="country_code" type="string">
    Two-letter ISO country code
  </ParamField>

  <ParamField path="postal_code" type="string">
    Postal/ZIP code
  </ParamField>
</ParamField>

### Update Customer Addresses

Modify existing addresses.

<CodeGroup>
  ```typescript Example theme={null}
  const address = await customerModuleService.updateCustomerAddresses(
    "addr_123",
    {
      is_default_shipping: true,
      phone: "+1234567890",
    }
  )
  ```
</CodeGroup>

### Delete Customer Addresses

Remove addresses from a customer.

<CodeGroup>
  ```typescript Example theme={null}
  await customerModuleService.deleteCustomerAddresses(["addr_123", "addr_456"])
  ```
</CodeGroup>

### Create Customer Groups

Create customer groups for segmentation.

<CodeGroup>
  ```typescript Example theme={null}
  const group = await customerModuleService.createCustomerGroups({
    name: "VIP Customers",
    metadata: {
      discount_percentage: 10,
    },
  })
  ```
</CodeGroup>

<ParamField path="data" type="CreateCustomerGroupDTO | CreateCustomerGroupDTO[]" required>
  Customer group data

  <ParamField path="name" type="string" required>
    Customer group name
  </ParamField>

  <ParamField path="metadata" type="object">
    Custom metadata
  </ParamField>
</ParamField>

### Add Customers to Group

Assign customers to a customer group.

<CodeGroup>
  ```typescript Example theme={null}
  await customerModuleService.addCustomerToGroup([
    {
      customer_id: "cus_123",
      customer_group_id: "cgroup_vip",
    },
    {
      customer_id: "cus_456",
      customer_group_id: "cgroup_vip",
    },
  ])
  ```
</CodeGroup>

<ParamField path="data" type="GroupCustomerPair | GroupCustomerPair[]" required>
  Customer-group associations

  <ParamField path="customer_id" type="string" required>
    ID of the customer
  </ParamField>

  <ParamField path="customer_group_id" type="string" required>
    ID of the customer group
  </ParamField>
</ParamField>

### Remove Customers from Group

Remove customer group associations.

<CodeGroup>
  ```typescript Example theme={null}
  await customerModuleService.removeCustomerFromGroup([
    {
      customer_id: "cus_123",
      customer_group_id: "cgroup_vip",
    },
  ])
  ```
</CodeGroup>

## Integration Examples

### With Cart Module

Associate carts with customers.

<CodeGroup>
  ```typescript Example theme={null}
  import { Modules } from "@medusajs/framework/utils"

  const customerModule = container.resolve(Modules.CUSTOMER)
  const cartModule = container.resolve(Modules.CART)

  // Retrieve customer
  const customer = await customerModule.retrieveCustomer("cus_123", {
    relations: ["addresses"],
  })

  // Create cart with customer data
  const cart = await cartModule.createCarts({
    customer_id: customer.id,
    email: customer.email,
    currency_code: "usd",
    shipping_address: customer.addresses.find(a => a.is_default_shipping),
  })
  ```
</CodeGroup>

### With Order Module

Link orders to customers.

<CodeGroup>
  ```typescript Example theme={null}
  import { Modules } from "@medusajs/framework/utils"

  const orderModule = container.resolve(Modules.ORDER)

  // List customer orders
  const orders = await orderModule.listOrders({
    customer_id: "cus_123",
  })

  // Create order for customer
  const order = await orderModule.createOrders({
    customer_id: customer.id,
    email: customer.email,
    // ... other order data
  })
  ```
</CodeGroup>

### With Auth Module

Manage customer authentication.

<CodeGroup>
  ```typescript Example theme={null}
  import { Modules } from "@medusajs/framework/utils"

  const authModule = container.resolve(Modules.AUTH)
  const customerModule = container.resolve(Modules.CUSTOMER)

  // Create customer with account
  const customer = await customerModule.createCustomers({
    email: "customer@example.com",
    first_name: "John",
    last_name: "Doe",
    has_account: true,
  })

  // Create auth identity
  await authModule.create({
    entity_id: customer.id,
    provider: "emailpass",
    provider_metadata: {
      email: customer.email,
    },
  })
  ```
</CodeGroup>

### With Pricing Module

Customer group-based pricing.

<CodeGroup>
  ```typescript Example theme={null}
  import { Modules } from "@medusajs/framework/utils"

  const pricingModule = container.resolve(Modules.PRICING)

  // Calculate prices with customer group context
  const prices = await pricingModule.calculatePrices(
    { id: ["variant_123"] },
    {
      context: {
        customer_group_id: "cgroup_vip",
        currency_code: "usd",
      },
    }
  )
  ```
</CodeGroup>

## Best Practices

1. **Email Uniqueness**: Enforce unique emails for accounts by using the `has_account` flag. Guests can share emails, but registered customers must have unique email/has\_account combinations.

2. **Address Management**: Use `is_default_shipping` and `is_default_billing` to mark primary addresses for quick access.

3. **Customer Groups**: Leverage customer groups for:
   * Price list targeting
   * Promotion eligibility
   * Custom business logic
   * Reporting and analytics

4. **Searchable Fields**: Take advantage of searchable fields (email, first\_name, last\_name, company\_name, phone) for customer lookup.

5. **Guest to Account Conversion**: When converting a guest to a registered customer, update `has_account` to `true` and ensure email uniqueness.

6. **Metadata Usage**: Store custom attributes in metadata for flexibility without schema changes.

## Related Modules

* [Cart Module](/modules/cart) - Associate carts with customers
* [Order Module](/modules/order) - Track customer orders
* [Auth Providers](/providers/auth) - Customer authentication
* [Pricing Module](/modules/pricing) - Customer group pricing