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.

POST /store/customers

Request Body

email · string · required

The customer’s email address.

password · string · required

The customer’s password.

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.

Request

curl -X POST http://localhost:9000/store/customers \
  -H "Content-Type: application/json" \
  -d '{
    "email": "[e-mail]",
    "password": "securepassword123",
    "first_name": "John",
    "last_name": "Doe"
  }'

Response

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

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.

Authenticate

After registration, authenticate to obtain a JWT token. See Authentication for details.

POST /auth/customer/emailpass

Get Current Customer

Retrieve the authenticated customer’s profile.

GET /store/customers/me

Request

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

Response

{
  "customer": {
    "id": "cus_123",
    "email": "[e-mail]",
    "first_name": "John",
    "last_name": "Doe",
    "has_account": true,
    "phone": "[phone]",
    "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"
  }
}

Requires authentication. Include the JWT token in the Authorization header.

Update Customer

Update the authenticated customer’s profile.

POST /store/customers/me

Request Body

email · string

Update email address.

first_name · string

Update first name.

last_name · string

Update last name.

phone · string

Update phone number.

company · string

Update company name.

metadata · object

Update custom metadata.

Request

curl -X POST http://localhost:9000/store/customers/me \
  -H "Authorization: Bearer {token}" \
  -H "Content-Type: application/json" \
  -d '{
    "phone": "[phone]",
    "company": "Acme Inc"
  }'

Response

{
  "customer": {
    "id": "cus_123",
    "email": "[e-mail]",
    "phone": "[phone]",
    "company": "Acme Inc"
  }
}

Customer Addresses

List Addresses

Retrieve all addresses for the authenticated customer.

GET /store/customers/me/addresses

Request

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

Response

{
  "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": "[phone]",
      "metadata": {},
      "created_at": "2024-03-01T11:00:00.000Z"
    }
  ]
}

Create Address

Add a new address to the customer’s account.

POST /store/customers/me/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 or province.

postal_code · string · required

Postal or ZIP code.

country_code · string · required

Two-letter ISO country code (e.g., “us”).

phone · string

Phone number.

is_default_shipping · boolean

Set as default shipping address.

is_default_billing · boolean

Set as default billing address.

metadata · object

Custom metadata.

Request

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

{
  "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.

POST /store/customers/me/addresses/{address_id}

Path Parameters

address_id · string · required

The address ID to update.

Request Body

Accepts the same fields as Create Address, all optional.

Request

curl -X POST http://localhost:9000/store/customers/me/addresses/addr_456 \
  -H "Authorization: Bearer {token}" \
  -H "Content-Type: application/json" \
  -d '{
    "phone": "[phone]"
  }'

Delete Address

Remove an address from the customer’s account.

DELETE /store/customers/me/addresses/{address_id}

Request

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

Response

{
  "id": "addr_456",
  "object": "address",
  "deleted": true
}

Customer Orders

List Orders

Retrieve all orders for the authenticated customer.

GET /store/customers/me/orders

Query Parameters

limit · number · default: "15"

Maximum number of orders to return.

offset · number · default: "0"

Number of orders to skip.

fields · string

Comma-separated list of fields to include.

Request

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

Response

{
  "orders": [
    {
      "id": "order_789",
      "display_id": 1001,
      "status": "completed",
      "payment_status": "captured",
      "fulfillment_status": "fulfilled",
      "email": "[e-mail]",
      "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.

POST /auth/customer/emailpass/reset-password

Request Body

email · string · required

The customer’s email address.

Request

curl -X POST http://localhost:9000/auth/customer/emailpass/reset-password \
  -H "Content-Type: application/json" \
  -d '{
    "email": "[e-mail]"
  }'

A password reset email will be sent to the customer with a reset token.

Update Password

Update password using a reset token.

POST /auth/customer/emailpass/update

Request Body

email · string · required

The customer’s email address.

token · string · required

The reset token from email.

password · string · required

The new password.

Change Password (Authenticated)

Change password for the authenticated customer.

POST /store/customers/me/password

Request Body

old_password · string · required

Current password.

new_password · string · required

New password.

Request

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

Authentication

Learn about customer authentication

Order Module

Learn about order management