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

# Customers

> Admin API endpoints for managing customer accounts, addresses, and groups.

## Overview

The Customers API allows administrators to create, update, and manage customer accounts, their addresses, and customer group memberships.

**Base Path:** `/admin/customers`

**Source:** `packages/medusa/src/api/admin/customers/route.ts`

## List Customers

Retrieve a list of customers with filtering and pagination.

```bash theme={null}
GET /admin/customers
```

### Query Parameters

<ParamField query="fields" type="string">
  Comma-separated list of fields to include.
</ParamField>

<ParamField query="limit" type="number" default="15">
  Maximum number of customers to return.
</ParamField>

<ParamField query="offset" type="number" default="0">
  Number of customers to skip.
</ParamField>

<ParamField query="q" type="string">
  Search query for customer name or email.
</ParamField>

<ParamField query="email" type="string">
  Filter by exact email address.
</ParamField>

<ParamField query="has_account" type="boolean">
  Filter by whether customer has an account.
</ParamField>

<ParamField query="groups" type="string[]">
  Filter by customer group IDs.
</ParamField>

<ParamField query="created_at" type="object">
  Filter by creation date range.
</ParamField>

### Request

```bash theme={null}
curl -X GET http://localhost:9000/admin/customers \
  -H "Authorization: Bearer {token}" \
  -G \
  --data-urlencode "q=john" \
  --data-urlencode "limit=20"
```

### Response

```json theme={null}
{
  "customers": [
    {
      "id": "cus_123",
      "email": "john@example.com",
      "first_name": "John",
      "last_name": "Doe",
      "has_account": true,
      "phone": "+1234567890",
      "metadata": {},
      "addresses": [
        {
          "id": "addr_123",
          "first_name": "John",
          "last_name": "Doe",
          "address_1": "123 Main St",
          "address_2": "Apt 4",
          "city": "New York",
          "province": "NY",
          "postal_code": "10001",
          "country_code": "us",
          "phone": "+1234567890"
        }
      ],
      "groups": [],
      "created_at": "2024-03-03T10:00:00.000Z",
      "updated_at": "2024-03-03T10:00:00.000Z",
      "created_by": "user_123"
    }
  ],
  "count": 250,
  "offset": 0,
  "limit": 20
}
```

<ResponseField name="customers" type="Customer[]">
  Array of customer objects.
</ResponseField>

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

**Source:** `packages/medusa/src/api/admin/customers/route.ts:15`

## Create Customer

Create a new customer account.

```bash theme={null}
POST /admin/customers
```

### Request Body

<ParamField body="email" type="string" required>
  The customer's email address.
</ParamField>

<ParamField body="first_name" type="string">
  The customer's first name.
</ParamField>

<ParamField body="last_name" type="string">
  The customer's last name.
</ParamField>

<ParamField body="phone" type="string">
  The customer's phone number.
</ParamField>

<ParamField body="company" type="string">
  The customer's company name.
</ParamField>

<ParamField body="metadata" type="object">
  Key-value pairs of custom metadata.
</ParamField>

### Request

```bash theme={null}
curl -X POST http://localhost:9000/admin/customers \
  -H "Authorization: Bearer {token}" \
  -H "Content-Type: application/json" \
  -d '{
    "email": "newcustomer@example.com",
    "first_name": "Jane",
    "last_name": "Smith",
    "phone": "+1987654321"
  }'
```

### Response

```json theme={null}
{
  "customer": {
    "id": "cus_456",
    "email": "newcustomer@example.com",
    "first_name": "Jane",
    "last_name": "Smith",
    "phone": "+1987654321",
    "has_account": false,
    "created_by": "user_123",
    "created_at": "2024-03-03T12:00:00.000Z"
  }
}
```

**Source:** `packages/medusa/src/api/admin/customers/route.ts:40`

**Note:** The `created_by` field is automatically set to the authenticated admin user's ID (see line 53).

## Get Customer

Retrieve a single customer by ID.

```bash theme={null}
GET /admin/customers/{id}
```

### Path Parameters

<ParamField path="id" type="string" required>
  The customer's ID.
</ParamField>

### Request

```bash theme={null}
curl -X GET http://localhost:9000/admin/customers/cus_123 \
  -H "Authorization: Bearer {token}"
```

### Response

```json theme={null}
{
  "customer": {
    "id": "cus_123",
    "email": "john@example.com",
    "first_name": "John",
    "last_name": "Doe",
    "addresses": [...],
    "groups": [...],
    "orders": [...]
  }
}
```

## Update Customer

Update customer information.

```bash theme={null}
POST /admin/customers/{id}
```

### Path Parameters

<ParamField path="id" type="string" required>
  The customer's ID.
</ParamField>

### Request Body

<ParamField body="email" type="string">
  Update the email address.
</ParamField>

<ParamField body="first_name" type="string">
  Update the first name.
</ParamField>

<ParamField body="last_name" type="string">
  Update the last name.
</ParamField>

<ParamField body="phone" type="string">
  Update the phone number.
</ParamField>

<ParamField body="company" type="string">
  Update the company name.
</ParamField>

<ParamField body="metadata" type="object">
  Update custom metadata.
</ParamField>

### Request

```bash theme={null}
curl -X POST http://localhost:9000/admin/customers/cus_123 \
  -H "Authorization: Bearer {token}" \
  -H "Content-Type: application/json" \
  -d '{
    "phone": "+1555555555",
    "metadata": {
      "vip": true
    }
  }'
```

### Response

```json theme={null}
{
  "customer": {
    "id": "cus_123",
    "phone": "+1555555555",
    "metadata": {
      "vip": true
    }
  }
}
```

## Delete Customer

Delete a customer (soft delete).

```bash theme={null}
DELETE /admin/customers/{id}
```

### Path Parameters

<ParamField path="id" type="string" required>
  The customer's ID.
</ParamField>

### Request

```bash theme={null}
curl -X DELETE http://localhost:9000/admin/customers/cus_123 \
  -H "Authorization: Bearer {token}"
```

### Response

```json theme={null}
{
  "id": "cus_123",
  "object": "customer",
  "deleted": true
}
```

## Customer Addresses

### Create Address

Add a new address to a customer.

```bash theme={null}
POST /admin/customers/{id}/addresses
```

### Request Body

<ParamField body="first_name" type="string">
  First name for the address.
</ParamField>

<ParamField body="last_name" type="string">
  Last name for the address.
</ParamField>

<ParamField body="company" type="string">
  Company name.
</ParamField>

<ParamField body="address_1" type="string" required>
  Address line 1.
</ParamField>

<ParamField body="address_2" type="string">
  Address line 2.
</ParamField>

<ParamField body="city" type="string" required>
  City name.
</ParamField>

<ParamField body="province" type="string">
  State/province.
</ParamField>

<ParamField body="postal_code" type="string" required>
  Postal/ZIP code.
</ParamField>

<ParamField body="country_code" type="string" required>
  Two-letter ISO country code (e.g., "us").
</ParamField>

<ParamField body="phone" type="string">
  Phone number.
</ParamField>

<ParamField body="metadata" type="object">
  Custom metadata.
</ParamField>

### Request

```bash theme={null}
curl -X POST http://localhost:9000/admin/customers/cus_123/addresses \
  -H "Authorization: Bearer {token}" \
  -H "Content-Type: application/json" \
  -d '{
    "address_1": "456 Oak Ave",
    "city": "Los Angeles",
    "postal_code": "90001",
    "country_code": "us"
  }'
```

### Update Address

Update a customer's address.

```bash theme={null}
POST /admin/customers/{id}/addresses/{address_id}
```

### Delete Address

Remove an address from a customer.

```bash theme={null}
DELETE /admin/customers/{id}/addresses/{address_id}
```

**Source:** `packages/medusa/src/api/admin/customers/[id]/addresses/[address_id]/route.ts`

## Customer Groups

### Add to Group

Add a customer to a customer group.

```bash theme={null}
POST /admin/customer-groups/{group_id}/customers
```

### Request Body

<ParamField body="customer_ids" type="string[]" required>
  Array of customer IDs to add to the group.
</ParamField>

### Remove from Group

Remove a customer from a customer group.

```bash theme={null}
DELETE /admin/customer-groups/{group_id}/customers
```

### Request Body

<ParamField body="customer_ids" type="string[]" required>
  Array of customer IDs to remove from the group.
</ParamField>

**Source:** `packages/medusa/src/api/admin/customer-groups/[id]/customers/route.ts`

## Next Steps

<CardGroup cols={2}>
  <Card title="Orders" icon="shopping-cart" href="/api/admin/orders">
    View customer orders
  </Card>

  <Card title="Customer Module" icon="user" href="/modules/customer">
    Learn about customer management
  </Card>
</CardGroup>