Overview The Store Customers API enables customers to create accounts, manage their profile, addresses, and view their order history.
Base Path: /store/customersSource: packages/medusa/src/api/store/customers/route.tsRegister Customer Create a new customer account.
Request Body The customer’s email address.
The customer’s first name.
The customer’s last name.
The customer’s phone number.
The customer’s company name.
Request curl -X POST http://localhost:9000/store/customers \ -H "Content-Type: application/json" \ -d '{ "email": "[email protected] ", "password": "securepassword123", "first_name": "John", "last_name": "Doe" }'
Response { "customer" : { "id" : "cus_123" , "email" : "[email protected] " , "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:11This 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.
Request curl -X GET http://localhost:9000/store/customers/me \ -H "Authorization: Bearer {token}"
Response { "customer" : { "id" : "cus_123" , "email" : "[email protected] " , "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" } }
Requires authentication. Include the JWT token in the Authorization header.
Update Customer Update the authenticated customer’s profile.
Request Body Request 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 { "customer" : { "id" : "cus_123" , "email" : "[email protected] " , "phone" : "+1987654321" , "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" : "+1234567890" , "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 for the address.
Last name for the address.
Two-letter ISO country code (e.g., “us”).
Set as default shipping address.
Set as default billing address.
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 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": "+1555555555" }'
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 Maximum number of orders to return.
Number of orders to skip.
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" : "[email protected] " , "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 The customer’s email address.
Request curl -X POST http://localhost:9000/auth/customer/emailpass/reset-password \ -H "Content-Type: application/json" \ -d '{ "email": "[email protected] " }'
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 The customer’s email address.
The reset token from email.
Change Password (Authenticated) Change password for the authenticated customer.
POST /store/customers/me/password
Request Body 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