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>[email protected]</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>[email protected]</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": "[email protected]",
"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": "[email protected]",
"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 |
| The customer email address | required | string | [email protected] | |
| 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>[email protected]</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>[email protected]</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
response body:
{
"entity_id": "2",
"website_id": "1",
"email": "[email protected]",
"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>[email protected]</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 |