Retrieves customer records from a store. Use it to list customers, page through a large customer base and pull custom field values for each customer through on-demand columns.
Before you begin#
- The API token needs
CustomerList_Load_Query, either assigned directly under Functions or through a group. See Create an API token. - Requests must be signed if the token requires it. See Make a signed request with HMAC.
Example requests#
Retrieve customers#
Returns the first 10 customers.
{
"Store_Code": "{{Store_Code}}",
"Miva_Request_Timestamp": "{{$timestamp}}",
"Function": "CustomerList_Load_Query",
"Count": 10,
"Offset": 0
}
Include custom fields#
Adds every custom field value to each customer through ondemandcolumns.
{
"Store_Code": "{{Store_Code}}",
"Miva_Request_Timestamp": "{{$timestamp}}",
"Function": "CustomerList_Load_Query",
"Count": 10,
"Offset": 0,
"Filter": [
{
"name": "ondemandcolumns",
"value": ["CustomField_Values:*"]
}
]
}
Request parameters#
| Parameter | Type | Required | Description |
|---|---|---|---|
count |
Number | No | Maximum lines of data allowed to be returned in the response. This limit is used to prevent excessive amounts of data return |
filter |
String | No | A string for filtering returned data |
offset |
Number | No | Used with the Count parameter for paginating results of large datasets. Default 0 is no offset. |
sort |
String | No | The order for sorting returned data |
Example response#
{
"success": 1,
"data": {
"total_count": 5,
"start_offset": 4,
"data": [
{
"id": 3,
"account_id": 0,
"login": "test",
"pw_email": "[email protected]",
"ship_id": 2,
"ship_res": true,
"ship_fname": "Jane",
"ship_lname": "Doe",
"ship_email": "[email protected]",
"ship_comp": "Miva, Inc",
"ship_phone": "555-555-5555",
"ship_fax": "555-555-5555",
"ship_addr1": "123 abc",
"ship_addr2": "apt 123",
"ship_city": "San Diego",
"ship_state": "CA",
"ship_zip": "92127",
"ship_cntry": "US",
"bill_id": 2,
"bill_fname": "Jane",
"bill_lname": "Doe",
"bill_email": "[email protected]",
"bill_comp": "Miva, Inc",
"bill_phone": "555-555-5555",
"bill_fax": "555-555-5555",
"bill_addr1": "123 abc",
"bill_addr2": "apt 123",
"bill_city": "San Diego",
"bill_state": "CA",
"bill_zip": "92127",
"bill_cntry": "US",
"note_count": 0,
"dt_created": 1538609652,
"dt_Updated": 1538609652,
"dt_login": 0,
"credit": 0.0,
"formatted_credit": "$0.00",
"CustomField_Values": {},
"business_title": ""
}
]
}
}
Response parameters#
| Parameter | Type | Description |
|---|---|---|
total_count |
Number | total_count is the total number of records that match your search criteria. |
start_offset |
Number | Number of the starting offset number of customers to return. Used in conjunction with the Count parameter for paginating results of large datasets. |
id |
Number | Customer Id |
account_id |
Number | Business Account Id |
login |
String | Customer Login |
pw_email |
String | Customer Forgot Password Email |
ship_id |
Number | Shipping Address ID |
ship_res |
Boolean | Customer Ship Residential Flag |
ship_fname |
String | Shipping First Name |
ship_lname |
String | Shipping Last Name |
ship_email |
String | Shipping Email Address |
ship_comp |
String | Shipping Company |
ship_phone |
String | Shipping Phone Number |
ship_fax |
String | Shipping Fax Number |
ship_addr1 |
String | Shipping Address 1 |
ship_addr2 |
String | Shipping Address 2 |
ship_city |
String | Shipping City |
ship_state |
String | Shipping State. 2 digit state code |
ship_zip |
String | Shipping Zip Code |
ship_cntry |
String | Shipping Country. 2 digit country code |
bill_id |
Number | Billing Address Id |
bill_fname |
String | Billing First Name |
bill_lname |
String | Customer Last Name |
bill_email |
String | Billing Email Address |
bill_comp |
String | Billing Company |
bill_phone |
String | Billing Phone Number |
bill_fax |
String | Billing Fax Number |
bill_addr1 |
String | Billing Address 1 |
bill_addr2 |
String | Billing Address 2 |
bill_city |
String | Billing City |
bill_state |
String | Billing State. 2 digit state code |
bill_zip |
String | Billing Zip Code |
bill_cntry |
String | Billing Country. 2 digit country code |
note_count |
Number | Number of Notes assigned to customer record |
dt_created |
Unix Timestamp | Unix timestamp of the date account was created. |
dt_Updated |
Unix Timestamp | Unix timestamp of the date account was last updated. |
dt_login |
Unix Timestamp | Date Time of Last Login |
credit |
Number | Customer Account Credit |
formatted_credit |
String | Currency Formatted Customer Account Credit |
CustomField_Values |
Object | Object containing custom field modules |
customfield |
Object | Object containing custom field name value pairs |
business_title |
String | Business Account Title/Name |
Additional options#
All of these go in the Filter array. List Load Query overview explains the filter format and every operator.
Pagination#
Count and Offset page through results, and the response’s total_count says how many customers match. See Pagination.
On-demand columns#
Add columns to each customer with "name": "ondemandcolumns" and a list of column names.
Column Name |
Description |
|---|---|
CustomField_Values:* "CustomField_Values:<module code>:<field code>" "CustomField_Values:<module code>:*" |
Includes all custom fields in the output Includes that specific field in the output Includes all fields for the specified module in the output |
Related functions#
| Function | Use it to |
|---|---|
Customer_Insert |
Create a customer |
Customer_Update |
Change a customer |
Customer_Delete |
Delete a customer |
CustomerAddressList_Load_Query |
Load a customer’s saved addresses |
CustomerPriceGroupList_Load_Query |
Load the price groups a customer belongs to |
CustomerCreditHistoryList_Load_Query |
Load a customer’s credit history |
Try in Postman#
In the Miva: JSON API: Authenticated collection, open Customers > CustomerList_Load_Query. See Set Up Postman.