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.

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": "[e-mail]",
      "first_name": "John",
      "last_name": "Doe",
      "has_account": true,
      "phone": "[phone]",
      "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": "[phone]"
        }
      ],
      "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": "[e-mail]",
    "first_name": "Jane",
    "last_name": "Smith",
    "phone": "[phone]"
  }'

Response

{
  "customer": {
    "id": "cus_456",
    "email": "[e-mail]",
    "first_name": "Jane",
    "last_name": "Smith",
    "phone": "[phone]",
    "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": "[e-mail]",
    "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": "[phone]",
    "metadata": {
      "vip": true
    }
  }'

Response

{
  "customer": {
    "id": "cus_123",
    "phone": "[phone]",
    "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