Skip to main content

​
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. 
GET /admin/customers

​
Query Parameters

​
fields
string
Comma-separated list of fields to include.
​
limit
number
default:"15"
Maximum number of customers to return.
​
offset
number
default:"0"
Number of customers to skip.
​
q
string
Search query for customer name or email.
​
email
string
Filter by exact email address.
​
has_account
boolean
Filter by whether customer has an account.
​
groups
string[]
Filter by customer group IDs.
​
created_at
object
Filter by creation date range.

​
Request

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

​
Response

{
  "customers": [
    {
      "id": "cus_123",
      "email": "[email protected]",
      "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
}
​
customers
Customer[]
Array of customer objects.
​
count
number
Total number of customers matching the filters.
Source: packages/medusa/src/api/admin/customers/route.ts:15

​
Create Customer

Create a new customer account. 
POST /admin/customers

​
Request Body

​
email
string
required
The customer’s email address.
​
first_name
string
The customer’s first name.
​
last_name
string
The customer’s last name.
​
phone
string
The customer’s phone number.
​
company
string
The customer’s company name.
​
metadata
object
Key-value pairs of custom metadata.

​
Request

curl -X POST http://localhost:9000/admin/customers \
  -H "Authorization: Bearer {token}" \
  -H "Content-Type: application/json" \
  -d '{
    "email": "[email protected]",
    "first_name": "Jane",
    "last_name": "Smith",
    "phone": "+1987654321"
  }'

​
Response

{
  "customer": {
    "id": "cus_456",
    "email": "[email protected]",
    "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. 
GET /admin/customers/{id}

​
Path Parameters

​
id
string
required
The customer’s ID.

​
Request

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

​
Response

{
  "customer": {
    "id": "cus_123",
    "email": "[email protected]",
    "first_name": "John",
    "last_name": "Doe",
    "addresses": [...],
    "groups": [...],
    "orders": [...]
  }
}

​
Update Customer

Update customer information. 
POST /admin/customers/{id}

​
Path Parameters

​
id
string
required
The customer’s ID.

​
Request Body

​
email
string
Update the email address.
​
first_name
string
Update the first name.
​
last_name
string
Update the last name.
​
phone
string
Update the phone number.
​
company
string
Update the company name.
​
metadata
object
Update custom metadata.

​
Request

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

{
  "customer": {
    "id": "cus_123",
    "phone": "+1555555555",
    "metadata": {
      "vip": true
    }
  }
}

​
Delete Customer

Delete a customer (soft delete). 
DELETE /admin/customers/{id}

​
Path Parameters

​
id
string
required
The customer’s ID.

​
Request

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

​
Response

{
  "id": "cus_123",
  "object": "customer",
  "deleted": true
}

​
Customer Addresses

​
Create Address

Add a new address to a customer. 
POST /admin/customers/{id}/addresses

​
Request Body

​
first_name
string
First name for the address.
​
last_name
string
Last name for the address.
​
company
string
Company name.
​
address_1
string
required
Address line 1.
​
address_2
string
Address line 2.
​
city
string
required
City name.
​
province
string
State/province.
​
postal_code
string
required
Postal/ZIP code.
​
country_code
string
required
Two-letter ISO country code (e.g., “us”).
​
phone
string
Phone number.
​
metadata
object
Custom metadata.

​
Request

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. 
POST /admin/customers/{id}/addresses/{address_id}

​
Delete Address

Remove an address from a customer. 
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. 
POST /admin/customer-groups/{group_id}/customers

​
Request Body

​
customer_ids
string[]
required
Array of customer IDs to add to the group.

​
Remove from Group

Remove a customer from a customer group. 
DELETE /admin/customer-groups/{group_id}/customers

​
Request Body

​
customer_ids
string[]
required
Array of customer IDs to remove from the group.
Source: packages/medusa/src/api/admin/customer-groups/[id]/customers/route.ts

​
Next Steps

Orders

View customer orders

Customer Module

Learn about customer management

Build docs developers (and LLMs) love

Get started for freeTalk to us