header

Magento 1.x Software Support Notice

For Magento Commerce 1, Magento is providing software support through June 2020. Depending on your Magento Commerce 1 version, software support may include both quality fixes and security patches. Please review our Magento Software Lifecycle Policy to see how your version of Magento Commerce 1 is supported.

For Magento Open Source 1.5 to 1.9, Magento is providing software security patches through June 2020 to ensure those sites remain secure and compliant. Visit our information page for more details about our software maintenance policy and other considerations for your business.

Customers

Edit this page on GitHub

JSON responses on this page contributed by Tim Reynolds

REST API: Customers

URI: /customers

Allows you to create and retrieve customers.

URL Structure: http://magentohost/api/rest/customers
Version: 1

HTTP Method: GET /customers

Description: Allows you to retrieve the list of existing customers.
Notes:: Only Admin user can retrieve the list of customers with all their attributes.

Authentication: Admin
Default Format: XML
Parameters:
No Parameters

Example

GET http://magentohost/api/rest/customers

Response Body:

<?xml version="1.0"?>
<magento_api>
  <data_item>
    <entity_id>2</entity_id>
    <website_id>1</website_id>
    <email>test@example.com</email>
    <group_id>1</group_id>
    <created_at>2012-03-22 14:15:54</created_at>
    <disable_auto_group_change>1</disable_auto_group_change>
    <firstname>john</firstname>
    <lastname>Doe</lastname>
    <created_in>Default Store View</created_in>
  </data_item>
  <data_item>
    <entity_id>4</entity_id>
    <website_id>1</website_id>
    <email>earl@example.com</email>
    <group_id>1</group_id>
    <created_at>2012-03-28 13:54:04</created_at>
    <disable_auto_group_change>0</disable_auto_group_change>
    <firstname>Earl</firstname>
    <lastname>Hickey</lastname>
    <created_in>Admin</created_in>
  </data_item>
</magento_api>

response example: json

get http://magentohost/api/rest/customers

response body:

		
{
  "2": {
    "entity_id": "2",
    "website_id": "1",
    "email": "test@example.com",
    "group_id": "1",
    "created_at": "2012-03-22 14:15:54",
    "disable_auto_group_change": "1",
    "firstname": "john",
    "lastname": "Doe",
    "created_in": "Admin",
    "prefix": null,
    "suffix": null,
    "taxvat": null,
    "dob": "2001-01-03 00:00:00",
    "reward_update_notification": "1",
    "reward_warning_notification": "1",
    "gender": "1"
  },
  "4": {
    "entity_id": "4",
    "website_id": "1",
    "email": "earl@example.com",
    "group_id": "1",
    "created_at": "2013-03-28 18:59:41",
    "disable_auto_group_change": "0",
    "firstname": "Earl",
    "lastname": "Hickey",
    "created_in": "Admin",
    "prefix": null,
    "suffix": null,
    "taxvat": null,
    "dob": "2012-03-28 13:54:04",
    "reward_update_notification": "1",
    "reward_warning_notification": "1",
    "gender": "1"
  }
HTTP Method: POST /customers

Description: Allows you to create a new customer.
Authentication: Admin
Default Format: XML
Parameters:

Name Description Required Type Example Value
firstname The customer first name required string John
lastname The customer last name required string Doe
email The customer email address required string johny@example.com
password The customer password. The password must contain minimum 7 characters required string 123123q
website_id Website ID required int 1
group_id Customer group ID required int 1
disable_auto_group_change Defines whether the automatic group change for the customer will be disabled optional int 0
prefix
 Customer prefix optional
 string Mr.
middlename
 Customer middle name or initial optional
 string R.
suffix
 Customer suffix optional
 string Sr.
taxvat
 Customer Tax or VAT number optional
 string GB999 9999 73

Notes: The list of parameters may change depending on the attributes settings in Customers > Attributes > Manage Customer Attributes page in Magento Admin Panel. For example, a required status of the middlename attribute (Middle Name/Initial) may be changed to 'YES". Please note that managing customer attributes is available only in Magento Enterprise Edition.

Example:

POST http://magentohost/api/rest/customers

Request Body:

<?xml version="1.0"?>
<magento_api>
    <firstname>Earl</firstname>
    <lastname>Hickey</lastname>
    <password>123123q</password>
    <email>earl@example.com</email>
    <website_id>1</website_id>
    <group_id>1</group_id>
</magento_api>

Response:
If the customer was created successfully, we receive Response HTTP Code = 200, empty Response Body and Location header like '/api/rest/customers/555' where '555' - an entity id of the new customer.

HTTP Method: PUT /customers

Description: Not allowed

HTTP Method: DELETE /customers

Description: Not allowed

REST API: Customer

URI: /customers/:customerId

Allows you to manage existing customers.

URL Structure: http://magentohost/api/rest/customers/:customerId
Version: 1

HTTP Method: GET /customers/:customerId

Description: Allows you to retrieve information on an existing customer.
Notes:: The list of attributes that will be returned for customers is configured in the Magento Admin Panel. The Customer user type has access only to his/her own information. Also, Admin can add additional non-system customer attributes by selecting Customers > Attributes > Manage Customer Attributes. If these attributes are set as visible on frontend, they will be returned in the response. Also, custom attributes will be returned in the response only after the customer information is updated in the Magento Admin Panel or the specified custom attribute is updated via API (see the PUT method below). Please note that managing customer attributes is available only in Magento Enterprise Edition.

Authentication: Admin, Customer
Default Format: XML
Parameters:
No Parameters

Example:

GET http://magentohost/api/rest/customers/2

Response Body:

<?xml version="1.0"?>
<magento_api>
  <entity_id>2</entity_id>
  <website_id>1</website_id>
  <email>test@example.com</email>
  <group_id>1</group_id>
  <created_at>2012-03-22 14:15:54</created_at>
  <disable_auto_group_change>1</disable_auto_group_change>
  <created_in>Default Store View</created_in>
  <firstname>john</firstname>
  <lastname>Doe</lastname>
  <last_logged_in>2012-03-22 14:15:56</last_logged_in>
</magento_api>

response example: json

get http://magentohost/api/rest/customers/141

response body:

		
{
  "entity_id": "2",
  "website_id": "1",
  "email": "test@example.com",
  "group_id": "1",
  "created_at": "2012-03-22 14:15:54",
  "disable_auto_group_change": "1",
  "created_in": "English",
  "firstname": "john",
  "lastname": "Doe"
}
HTTP Method: POST /customers/:customerId

Description: Not allowed.

HTTP Method: PUT /customers/:customerId

Description: Allows you to update an existing customer.
Notes: The list of attributes that will be updated for customer is configured in the Magento Admin Panel. The Customer user type has access only to his/her own information.

Authentication: Admin, Customer
Default Format: XML
Parameters:
You must specify only those parameters which you want to update. Parameters that are not defined in the request body will preserve the previous values. The website_id and created_in attributes are not allowed for updating.

Example:

PUT http://magentohost/api/rest/customers/2

Request Body:

<?xml version="1.0"?>
<magento_api>
    <firstname>Earl</firstname>
    <lastname>Hickey</lastname>
    <email>customerss@example.com</email>
    <group_id>1</group_id>
</magento_api>
HTTP Method: DELETE /customers/:customerId

Description: Allows you to delete an existing customer.
Notes: Admin only can delete a customer.

Authentication: Admin
Default Format: XML
Parameters:
No Parameters

Example:

DELETE http://magentohost/api/rest/customers/2