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.
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": "customer@example.com", "password": "securepassword123", "first_name": "John", "last_name": "Doe" }'
Response { "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: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" : "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" } }
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" : "customer@example.com" , "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" : "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.
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": "customer@example.com" }'
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