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

> Store API endpoints for customer registration, authentication, and account management.

## Overview

The Store Customers API enables customers to create accounts, manage their profile, addresses, and view their order history.

**Base Path:** `/store/customers`

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

## Register Customer

Create a new customer account.

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

### Request Body

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

<ParamField body="password" type="string" required>
  The customer's password.
</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>

### Request

```bash theme={null}
curl -X POST http://localhost:9000/store/customers \
  -H "Content-Type: application/json" \
  -d '{
    "email": "customer@example.com",
    "password": "securepassword123",
    "first_name": "John",
    "last_name": "Doe"
  }'
```

### Response

```json theme={null}
{
  "customer": {
    "id": "cus_123",
    "email": "customer@example.com",
    "first_name": "John",
    "last_name": "Doe",
    "has_account": true,
    "phone": null,
    "company": null,
    "metadata": {},
    "created_at": "2024-03-03T10:00:00.000Z"
  }
}
```

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

<Warning>
  This endpoint returns an error if the request is already authenticated as a customer (see line 19-24). Users must log out before creating a new account.
</Warning>

## Authenticate

After registration, authenticate to obtain a JWT token. See [Authentication](/api/authentication#store-authentication) for details.

```bash theme={null}
POST /auth/customer/emailpass
```

## Get Current Customer

Retrieve the authenticated customer's profile.

```bash theme={null}
GET /store/customers/me
```

### Request

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

### Response

```json theme={null}
{
  "customer": {
    "id": "cus_123",
    "email": "customer@example.com",
    "first_name": "John",
    "last_name": "Doe",
    "has_account": true,
    "phone": "+1234567890",
    "company": null,
    "addresses": [
      {
        "id": "addr_456",
        "first_name": "John",
        "last_name": "Doe",
        "address_1": "123 Main St",
        "city": "New York",
        "postal_code": "10001",
        "country_code": "us"
      }
    ],
    "orders": [
      {
        "id": "order_789",
        "display_id": 1001,
        "status": "completed",
        "total": 6978,
        "created_at": "2024-03-02T15:30:00.000Z"
      }
    ],
    "metadata": {},
    "created_at": "2024-03-01T10:00:00.000Z"
  }
}
```

<Note>
  Requires authentication. Include the JWT token in the Authorization header.
</Note>

## Update Customer

Update the authenticated customer's profile.

```bash theme={null}
POST /store/customers/me
```

### Request Body

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

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

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

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

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

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

### Request

```bash theme={null}
curl -X POST http://localhost:9000/store/customers/me \
  -H "Authorization: Bearer {token}" \
  -H "Content-Type: application/json" \
  -d '{
    "phone": "+1987654321",
    "company": "Acme Inc"
  }'
```

### Response

```json theme={null}
{
  "customer": {
    "id": "cus_123",
    "email": "customer@example.com",
    "phone": "+1987654321",
    "company": "Acme Inc"
  }
}
```

## Customer Addresses

### List Addresses

Retrieve all addresses for the authenticated customer.

```bash theme={null}
GET /store/customers/me/addresses
```

### Request

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

### Response

```json theme={null}
{
  "addresses": [
    {
      "id": "addr_456",
      "customer_id": "cus_123",
      "first_name": "John",
      "last_name": "Doe",
      "company": null,
      "address_1": "123 Main St",
      "address_2": "Apt 4",
      "city": "New York",
      "province": "NY",
      "postal_code": "10001",
      "country_code": "us",
      "phone": "+1234567890",
      "metadata": {},
      "created_at": "2024-03-01T11:00:00.000Z"
    }
  ]
}
```

### Create Address

Add a new address to the customer's account.

```bash theme={null}
POST /store/customers/me/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 or province.
</ParamField>

<ParamField body="postal_code" type="string" required>
  Postal or 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="is_default_shipping" type="boolean">
  Set as default shipping address.
</ParamField>

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

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

### Request

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

### Response

```json theme={null}
{
  "customer": {
    "id": "cus_123",
    "addresses": [
      {
        "id": "addr_789",
        "address_1": "456 Oak Ave",
        "city": "Los Angeles",
        "postal_code": "90001",
        "country_code": "us",
        "is_default_shipping": true
      }
    ]
  }
}
```

### Update Address

Update an existing address.

```bash theme={null}
POST /store/customers/me/addresses/{address_id}
```

### Path Parameters

<ParamField path="address_id" type="string" required>
  The address ID to update.
</ParamField>

### Request Body

Accepts the same fields as Create Address, all optional.

### Request

```bash theme={null}
curl -X POST http://localhost:9000/store/customers/me/addresses/addr_456 \
  -H "Authorization: Bearer {token}" \
  -H "Content-Type: application/json" \
  -d '{
    "phone": "+1555555555"
  }'
```

### Delete Address

Remove an address from the customer's account.

```bash theme={null}
DELETE /store/customers/me/addresses/{address_id}
```

### Request

```bash theme={null}
curl -X DELETE http://localhost:9000/store/customers/me/addresses/addr_456 \
  -H "Authorization: Bearer {token}"
```

### Response

```json theme={null}
{
  "id": "addr_456",
  "object": "address",
  "deleted": true
}
```

## Customer Orders

### List Orders

Retrieve all orders for the authenticated customer.

```bash theme={null}
GET /store/customers/me/orders
```

### Query Parameters

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

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

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

### Request

```bash theme={null}
curl -X GET http://localhost:9000/store/customers/me/orders \
  -H "Authorization: Bearer {token}" \
  -G \
  --data-urlencode "limit=10"
```

### Response

```json theme={null}
{
  "orders": [
    {
      "id": "order_789",
      "display_id": 1001,
      "status": "completed",
      "payment_status": "captured",
      "fulfillment_status": "fulfilled",
      "email": "customer@example.com",
      "currency_code": "usd",
      "items": [...],
      "shipping_address": {...},
      "subtotal": 5998,
      "total": 6978,
      "created_at": "2024-03-02T15:30:00.000Z"
    }
  ],
  "count": 5,
  "offset": 0,
  "limit": 10
}
```

## Password Management

### Request Password Reset

Request a password reset token.

```bash theme={null}
POST /auth/customer/emailpass/reset-password
```

### Request Body

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

### Request

```bash theme={null}
curl -X POST http://localhost:9000/auth/customer/emailpass/reset-password \
  -H "Content-Type: application/json" \
  -d '{
    "email": "customer@example.com"
  }'
```

<Note>
  A password reset email will be sent to the customer with a reset token.
</Note>

### Update Password

Update password using a reset token.

```bash theme={null}
POST /auth/customer/emailpass/update
```

### Request Body

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

<ParamField body="token" type="string" required>
  The reset token from email.
</ParamField>

<ParamField body="password" type="string" required>
  The new password.
</ParamField>

### Change Password (Authenticated)

Change password for the authenticated customer.

```bash theme={null}
POST /store/customers/me/password
```

### Request Body

<ParamField body="old_password" type="string" required>
  Current password.
</ParamField>

<ParamField body="new_password" type="string" required>
  New password.
</ParamField>

### Request

```bash theme={null}
curl -X POST http://localhost:9000/store/customers/me/password \
  -H "Authorization: Bearer {token}" \
  -H "Content-Type: application/json" \
  -d '{
    "old_password": "currentpassword",
    "new_password": "newpassword123"
  }'
```

## Next Steps

<CardGroup cols={2}>
  <Card title="Authentication" icon="lock" href="/api/authentication">
    Learn about customer authentication
  </Card>

  <Card title="Order Module" icon="receipt" href="/modules/order">
    Learn about order management
  </Card>
</CardGroup>