Menu

Customers API Routes

Customers can place orders as guest customers or register.

When a customer registers, they can manage their profile, save addresses for later usage, and more.

These API routes allow customers to create and manage their accounts.

POST /store/customers#

Register Customer

Register a customer. Use the /auth/customer/emailpass/register API route first to retrieve the registration token and pass it in the header of the request.

Authentication: cookie session, JWT bearer token.

Header parameters

x-publishable-api-keystring
Publishable API Key created in the Medusa Admin.
x-medusa-localestringOptional
The locale in BCP 47 format to retrieve localized content.
Example: en-US

Query parameters

fieldsstringOptional
Comma-separated fields that should be included in the returned data. if a field is prefixed with + it will be added to the default fields, using - will remove it from the default fields. without prefix it will replace the entire default fields.
localestringOptional
The locale in BCP 47 format to retrieve localized content.
Example: en-US

Request body (application/json)

emailstringOptional
The customer's email.
company_namestringOptional
The customer's company name.
first_namestringOptional
The customer's first name.
last_namestringOptional
The customer's last name.
phonestringOptional
The customer's phone.
metadataobjectOptional
The customer's metadata, can hold custom key-value pairs. Learn more in the Manage Metadata section.

Request examples

Responses

200 OK

customerobject
The customer's details.

400, 401, 404, 409, 422, 500: an error response is returned.

Emitted events

  • customer.created: Emitted when a customer is created.

GET /store/customers/me#

Get Logged-in Customer

Retrieve the logged-in customer. You can expand the customer's relations or select the fields that should be returned.

Authentication: cookie session, JWT bearer token.

Header parameters

x-publishable-api-keystring
Publishable API Key created in the Medusa Admin.
x-medusa-localestringOptional
The locale in BCP 47 format to retrieve localized content.
Example: en-US

Query parameters

fieldsstringOptional
Comma-separated fields that should be included in the returned data. if a field is prefixed with + it will be added to the default fields, using - will remove it from the default fields. without prefix it will replace the entire default fields. This API route restricts the fields that can be selected. Learn how to override the retrievable fields in the Retrieve Custom Links documentation.
localestringOptional
The locale in BCP 47 format to retrieve localized content.
Example: en-US

Request examples

Responses

200 OK

customerobject
The customer's details.

400, 401, 404, 409, 422, 500: an error response is returned.

POST /store/customers/me#

Update Customer

Update the logged-in customer's details.

Authentication: cookie session, JWT bearer token.

Header parameters

x-publishable-api-keystring
Publishable API Key created in the Medusa Admin.
x-medusa-localestringOptional
The locale in BCP 47 format to retrieve localized content.
Example: en-US

Query parameters

fieldsstringOptional
Comma-separated fields that should be included in the returned data. if a field is prefixed with + it will be added to the default fields, using - will remove it from the default fields. without prefix it will replace the entire default fields.
localestringOptional
The locale in BCP 47 format to retrieve localized content.
Example: en-US

Request body (application/json)

company_namestringOptional
The customer's company name.
first_namestringOptional
The customer's first name.
last_namestringOptional
The customer's last name.
phonestringOptional
The customer's phone.
metadataobjectOptional
The customer's metadata, can hold custom key-value pairs. Learn more in the Manage Metadata section.

Request examples

Responses

200 OK

customerobject
The customer's details.

400, 401, 404, 409, 422, 500: an error response is returned.

Emitted events

  • customer.updated: Emitted when a customer is updated.

GET /store/customers/me/addresses#

List Customer's Addresses

Retrieve the addresses of the logged-in customer. The addresses can be filtered by fields such as country_code. The addresses can also be sorted or paginated.

Authentication: cookie session, JWT bearer token.

Header parameters

x-publishable-api-keystring
Publishable API Key created in the Medusa Admin.
x-medusa-localestringOptional
The locale in BCP 47 format to retrieve localized content.
Example: en-US

Query parameters

citystring | string[]Optional
Filter by the address's city.
postal_codestring | string[]Optional
Filter by the address's postal code.
country_codestring | string[]Optional
Filter by the address's country code.
qstringOptional
Search term to filter the address's searchable properties.
$andobject[]Optional
Join query parameters with an AND condition. Each object's content is the same type as the expected query parameters.
$orobject[]Optional
Join query parameters with an OR condition. Each object's content is the same type as the expected query parameters.
localestringOptional
The locale in BCP 47 format to retrieve localized content.
Example: en-US
limitnumberOptional
Limit the number of items returned in the list.
offsetnumberOptional
The number of items to skip when retrieving a list.
orderstringOptional
The field to sort the data by. By default, the sort order is ascending. To change the order to descending, prefix the field name with -.
with_deletedbooleanOptional
The customer's with deleted.
fieldsstringOptional
Comma-separated fields that should be included in the returned data. If a field is prefixed with + it will be added to the default fields, using - will remove it from the default fields. Without prefix it will replace the entire default fields.

Request examples

Responses

200 OK

limitnumber
The maximum number of items returned.
offsetnumber
The number of items skipped before retrieving the returned items.
countnumber
The total number of items.
addressesobject[]
The list of addresses.
estimate_countnumberOptional
The estimated count retrieved from the PostgreSQL query planner, which may be inaccurate.

400, 401, 404, 409, 422, 500: an error response is returned.

POST /store/customers/me/addresses#

Create Address for Logged-In Customer

Create an address for the logged-in customer.

Authentication: cookie session, JWT bearer token.

Header parameters

x-publishable-api-keystring
Publishable API Key created in the Medusa Admin.
x-medusa-localestringOptional
The locale in BCP 47 format to retrieve localized content.
Example: en-US

Query parameters

fieldsstringOptional
Comma-separated fields that should be included in the returned data. if a field is prefixed with + it will be added to the default fields, using - will remove it from the default fields. without prefix it will replace the entire default fields. This API route restricts the fields that can be selected. Learn how to override the retrievable fields in the Retrieve Custom Links documentation.
localestringOptional
The locale in BCP 47 format to retrieve localized content.
Example: en-US

Request body (application/json)

first_namestringOptional
The customer's first name.
last_namestringOptional
The customer's last name.
phonestringOptional
The customer's phone.
companystringOptional
The address's company.
address_1stringOptional
The address's first line.
address_2stringOptional
The address's second line.
citystringOptional
The address's city.
country_codestringOptional
The address's country code.
provincestringOptional
The address's ISO 3166-2 province code. Must be lower-case.
Example: us-ca
postal_codestringOptional
The address's postal code.
address_namestringOptional
The address's name.
is_default_shippingbooleanOptional
Whether the address is used by default for shipping during checkout.
is_default_billingbooleanOptional
Whether the address is used by default for billing during checkout.
metadataobjectOptional
Holds custom key-value pairs.

Request examples

Responses

200 OK

customerobject
The customer's details.

400, 401, 404, 409, 422, 500: an error response is returned.

GET /store/customers/me/addresses/{address_id}#

Get Customer's Address

Retrieve an address of the logged-in customer. You can expand the address's relations or select the fields that should be returned.

Authentication: cookie session, JWT bearer token.

Path parameters

address_idstring
The address's ID.

Header parameters

x-publishable-api-keystring
Publishable API Key created in the Medusa Admin.
x-medusa-localestringOptional
The locale in BCP 47 format to retrieve localized content.
Example: en-US

Query parameters

fieldsstringOptional
Comma-separated fields that should be included in the returned data. if a field is prefixed with + it will be added to the default fields, using - will remove it from the default fields. without prefix it will replace the entire default fields. This API route restricts the fields that can be selected. Learn how to override the retrievable fields in the Retrieve Custom Links documentation.
localestringOptional
The locale in BCP 47 format to retrieve localized content.
Example: en-US

Request examples

Responses

200 OK

addressobject
The customer address's details

400, 401, 404, 409, 422, 500: an error response is returned.

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

Update Customer's Address

Update the logged-in customer's address.

Authentication: cookie session, JWT bearer token.

Path parameters

address_idstring
The address's ID.

Header parameters

x-publishable-api-keystring
Publishable API Key created in the Medusa Admin.
x-medusa-localestringOptional
The locale in BCP 47 format to retrieve localized content.
Example: en-US

Query parameters

fieldsstringOptional
Comma-separated fields that should be included in the returned data. if a field is prefixed with + it will be added to the default fields, using - will remove it from the default fields. without prefix it will replace the entire default fields. This API route restricts the fields that can be selected. Learn how to override the retrievable fields in the Retrieve Custom Links documentation.
localestringOptional
The locale in BCP 47 format to retrieve localized content.
Example: en-US

Request body (application/json)

first_namestringOptional
The customer's first name.
last_namestringOptional
The customer's last name.
phonestringOptional
The customer's phone.
companystringOptional
The address's company.
address_1stringOptional
The address's first line.
address_2stringOptional
The address's second line.
citystringOptional
The address's city.
country_codestringOptional
The address's country code.
provincestringOptional
The address's ISO 3166-2 province code. Must be lower-case.
Example: us-ca
postal_codestringOptional
The address's postal code.
address_namestringOptional
The address's name.
is_default_shippingbooleanOptional
Whether the address is used by default for shipping during checkout.
is_default_billingbooleanOptional
Whether the address is used by default for billing during checkout.
metadataobjectOptional
Holds custom key-value pairs.

Request examples

Responses

200 OK

customerobject
The customer's details.

400, 401, 404, 409, 422, 500: an error response is returned.

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

Remove Customer's Address

Remove an address of the logged-in customer.

Authentication: cookie session, JWT bearer token.

Path parameters

address_idstring
The address's ID.

Header parameters

x-publishable-api-keystring
Publishable API Key created in the Medusa Admin.
x-medusa-localestringOptional
The locale in BCP 47 format to retrieve localized content.
Example: en-US

Query parameters

fieldsstringOptional
Comma-separated fields that should be included in the returned data. if a field is prefixed with + it will be added to the default fields, using - will remove it from the default fields. without prefix it will replace the entire default fields. This API route restricts the fields that can be selected. Learn how to override the retrievable fields in the Retrieve Custom Links documentation.
localestringOptional
The locale in BCP 47 format to retrieve localized content.
Example: en-US

Request examples

Responses

200 OK

idstring
The address's ID.
objectstring
The name of the deleted object.

Default: "address"

deletedboolean
Whether the address was deleted.
parentobjectOptional
The customer's details.

400, 401, 404, 409, 422, 500: an error response is returned.

Found a problem with this page?Report Issue
Edited Nov 14·Edit this page