Customers Last updated: 2020-06-05

The Customer resource stores information about a shop's customers, such as their contact details, their order history, and whether they've agreed to receive email marketing.

The Customer resource also holds information on the status of a customers's account. Customers with accounts save time at checkout when they're logged in because they don't need to enter their contact information. You can use the Customer API to check whether a customer has an active account, and then invite them to create one if they don't.

What you can do with a Customer:

GET/api/v3/customers?firstname=Bob
Searches for Customers that match a supplied query
GET/api/v3/customers/{customer_oid}
Retrieves a single Customer
POST/api/v3/customers
Creates a single Customer
PUT/api/v3/customers/{customer_oid}
Updates an existing Customer

Customer Properties

Property	Description
OID	"OID": 12321 The marketAgility ID for the customer
SiteID	"SiteID": 1 The marketAgility ID for the site
Status	"Status": "Active" Active Status, can be represented as an integer (1 = Active, 0 = Inactive) or a string
Created	"Created": "2019-04-21T12:43:12" The date the customer was created
Modified	"Modified": "2020-05-12T08:03:00" The date the customer was last modified
LastLogin	"LastLogin": "2020-05-05T18:03:00" The date the customer was last logged in
CustomerNumber	"CustomerNumber": "1432" The customer-friendly customer number
EmployeeNumber	"EmployeeNumber": "321" The Employee number that assisted the order (if provided)
IsTaxFree	"IsTaxFree": false Indicates wheter the customer should be charged tax on orders
IsClubMember	"IsClubMember": true Indicates wheter the customer is a member of the loyalty club (True or False)
Username	"Username": "[email protected]" The customer's email address
FullName	"FullName": "John Mark Doe" The customer's full name
FirstName	"Username": "John" The customer's first name
MiddleName	"MiddleName": "Mark" The customer's middle name
LastName	"LastName": "Doe" The customer's last name
Address	"Address": "12005 Sunrise Valley Drive" The customer's mailing address
Company	"Company": "Virid, Inc" The customer's place of work
Address2	"Address2": "Suite 400" An additional field for the customer's mailing address
City	"City": "Reston" The customer's city
StateOrProvince	"StateOrProvince": "VA" The customer's state or province
PostalCode	"PostalCode": "20147" The customer's postal code
Country	"Country": "US" The customer's country
Phone	"Phone": "7031010101" The customer's phone number
Fax	"Fax": "18884732963" The customer's fax number
MobilePhone	"MobilePhone": "2025550188" The customer's mobile phone number
Email	"Email": "[email protected]" The customer's email address
EmailHash	"EmailHash": "0706...8a6b8b" A hashed 32-character hexadecimal string representation of a customer's email
IsRegistered	"IsRegistered": true Indicates whether the customer is registered (True or False)
FailureCount	"FailureCount": 1 Failure count associated with the customer account
BirthDate	"BirthDate": "1982-05-12T00:00:00" The customer's birth date
ReminderQuestion	"ReminderQuestion": "In what city were you born?" A question selected by the customer to help them in password recovery
ReminderAnswer	"ReminderAnswer": "San Antonio" The reminder answer to the password reminder question
PreferredBilling	"PreferredBilling": "PersonalCard" The customer's preferred billing profile
PreferredShipping	"PreferredShipping": "Primary" The customer's preferred shipping profile
Gender	"Gender": "Male" The customer's preferred gender
Custom1	Free custom field 1
Custom2	Free custom field 2
Custom3	Free custom field 3
Custom4	Free custom field 4
Custom5	Free custom field 5

Search Customers

Retrieves a list of customers that share a common element. The following parameters are available:

GET	/api/v3/customers?firstname=bob

Parameter	Description
Firstname	Type: String The customer's first name
Lastname	Type: String The customer's last name
Username	Type: String The customer's email address
UpdatedSince	Type: DateTime Include customers modified on or after this date
UpdatedThrough	Type: DateTime Include customers modified on or before this date
PageRows	Type: Numeric How many results do you want back (default: 25)
PageNumber	Type: Numeric Which page of results do you want to retrieve (default: 1)

View Sample Response


HTTP/1.1 200 OK
[
    {
            "OID": 12321,
            "SiteID": 0,
            "Status": 0,
            "Created": "0001-01-01T00:00:00",
            "Modified": "0001-01-01T00:00:00",
            "LastLogin": "2020-05-05T18:03:00",
            "CustomerNumber": null,
            "EmployeeNumber": "",
            "IsTaxFree": false,
            "IsClubMember": true,
            "Username": "[email protected]",
            "FullName": "Bob Smith",
            "FirstName": "Bob",
            "MiddleName": "",
            "LastName": "Smith",
            "Address": "12005 Sunrise Valley Drive",
            "Company": "Virid, Inc",
            "Address2": "Suite 400",
            "City": "Reston",
            "StateOrProvince": "VA",
            "PostalCode": "20147",
            "Country": "US",
            "Phone": "7036892121",
            "Fax": "",
            "MobilePhone": "",
            "Email": "[email protected]",
            "EmailHash": "0706...598a6b8b",
            "IsRegistered": true,
            "FailureCount": 1,
            "BirthDate": "1901-01-01T00:00:00Z",
            "ReminderQuestion": "",
            "ReminderAnswer": "",
            "PreferredBilling": "PersonalCard",
            "PreferredShipping": "Primary address",
            "Gender": "",
            "Custom1": "",
            "Custom2": "",
            "Custom3": "",
            "Custom4": "",
            "Custom5": ""
    }
]

Get Customer

Gets a single customer by ID

GET	/api/v3/customers/12321

View Sample Response


HTTP/1.1 200 OK
{
            "OID": 12321,
            "SiteID": 0,
            "Status": 0,
            "Created": "0001-01-01T00:00:00",
            "Modified": "0001-01-01T00:00:00",
            "LastLogin": "2020-05-05T18:03:00",
            "CustomerNumber": null,
            "EmployeeNumber": "",
            "IsTaxFree": false,
            "IsClubMember": true,
            "Username": "[email protected]",
            "FullName": "Bob Smith",
            "FirstName": "Bob",
            "MiddleName": "",
            "LastName": "Smith",
            "Address": "12005 Sunrise Valley Drive",
            "Company": "Virid, Inc",
            "Address2": "Suite 400",
            "City": "Reston",
            "StateOrProvince": "VA",
            "PostalCode": "20147",
            "Country": "US",
            "Phone": "7036892121",
            "Fax": "",
            "MobilePhone": "",
            "Email": "[email protected]",
            "EmailHash": "0706...598a6b8b",
            "IsRegistered": true,
            "FailureCount": 1,
            "BirthDate": "1901-01-01T00:00:00Z",
            "ReminderQuestion": "",
            "ReminderAnswer": "",
            "PreferredBilling": "PersonalCard",
            "PreferredShipping": "Secondary Address",
            "Gender": "",
            "Custom1": "",
            "Custom2": "",
            "Custom3": "",
            "Custom4": "",
            "Custom5": ""
}

Create Customer

Creates a new customer

POST	/api/v3/customers
{ "Username": "[email protected]", "FirstName": "Bob", "LastName": "Smith", "BirthDate": "1982-05-12T00:00:00" }

View Sample Response


HTTP/1.1 201 Created
{
            "OID": 880166,
            "SiteID": 0,
            "Status": 0,
            "Created": "0001-01-01T00:00:00",
            "Modified": "0001-01-01T00:00:00",
            "LastLogin": "2020-06-04T18:03:00",
            "CustomerNumber": null,
            "EmployeeNumber": "",
            "IsTaxFree": false,
            "IsClubMember": false,
            "Username": "[email protected]",
            "FullName": "Bob Smith",
            "FirstName": "Bob",
            "MiddleName": "",
            "LastName": "Smith",
            "Address": "",
            "Company": "",
            "Address2": "",
            "City": "",
            "StateOrProvince": "",
            "PostalCode": "",
            "Country": "",
            "Phone": "",
            "Fax": "",
            "MobilePhone": "",
            "Email": "",
            "EmailHash": "",
            "IsRegistered": true,
            "FailureCount": 0,
            "BirthDate": "1982-05-12T00:00:00Z",
            "ReminderQuestion": "",
            "ReminderAnswer": "",
            "PreferredBilling": "",
            "PreferredShipping": "",
            "Gender": "",
            "Custom1": "",
            "Custom2": "",
            "Custom3": "",
            "Custom4": "",
            "Custom5": ""
}

Update Customer

Updates an existing customer

PUT	/api/v3/customers/12321
{ "Username": "[email protected]", "FirstName": "John", "LastName": "Smith", "BirthDate": "1982-05-12T00:00:00" }

View Sample Response


HTTP/1.1 204 No Content

Metadata

Metadata are custom elements added to a customer to aid in integrating with 3rd party systems or to simply collect additional information not available in a standard cyustomer record.

What you can do with Metadata:

GET/api/v3/customers/{customer_oid}/metadata
Gets all metadata for a customer
GET/api/v3/customers/{customer_oid}/metadata/{metadata_oid}
Gets a single metadata element
POST/api/v3/customers/{customer_oid}/metadata
Creates a new metadata element for the customer.
PUT/api/v3/customers/{customer_oid}/metadata/{metadata_oid}
Updates an existing metadata element.
DELETE/api/v3/customers/{customer_oid}/metadata/{metadata_oid}
Dletes an existing metadata elements.

Metadata Properties

Property	Description
OID	"OID": 12321 The marketAgility ID for the metadata element
Group	"Group": My Group The group name for the metadata element
Name	"Name": MyName The name for the metadata element
Value	"Value": MyValue The value for the metadata element

List Metadata

List all metadata elements for the customer.

GET	/api/v3/customers/{customer_oid}/metadata

View Sample Response


HTTP/1.1 200 OK
[
   {
            "OID": 12321,
            "Group": "MyGroup",
            "Name": "MyName",
            "Value": "MyValue",
   }
]

Get Metadata

Retrieves a metadata element by its ID.

GET	/api/v3/customers/{customer_oid}/metadata/{metadata_oid}

View Sample Response


HTTP/1.1 200 OK
 {
            "OID": 12321,
            "Group": "MyGroup",
            "Name": "MyName",
            "Value": "MyValue",
   }

Creates a Metadata element

Creates a metadata element for a customer

POST	/api/v3/customers/{customer_oid}/metadata
{ "Group": "MyGroup", "Name": "MyName", "Value": "MyValue", }

View Sample Response


HTTP/1.1 200 OK
 {
            "OID": 456,
            "Group": "MyGroup",
            "Name": "MyName",
            "Value": "MyValue",
   }

Updates a Metadata element

Creates a metadata element for a customer

PUT	/api/v3/customers/{customer_oid}/metadata/{metadata_oid}
{ "Group": "MyGroup", "Name": "MyName", "Value": "MyValue", }

View Sample Response


HTTP/1.1 204 No Content

Deletes a Metadata element

Creates a metadata element for a customer

DELETE	/api/v3/customers/{customer_oid}/metadata/{metadata_oid}

View Sample Response


HTTP/1.1 204 No Content

Addresses

An Address is a physical location linked to a customer. It is used during checkout to allow the customer to select from predefined shipping locations, saving time and effort.

What you can do with an Address:

GET/api/v3/customers/{customer_oid}/addresses/{address_oid}
Gets a single address for a customer
GET/api/v3/customers/{customer_oid}/addresses/
Lists all addresses linked to a customer
POST/api/v3/customers/{customer_oid}/addresses
Creates an address, indicating one or more addresses have been linked to the customer.
PUT/api/v3/customers/{customer_oid}/addresses/{address_oid}
Updates an address for a customer

Addresses Properties

Property	Description
OID	"OID": 12321 The marketAgility ID for an address
Alias	"Alias": "Work" The designated address type for the customer
FirstName	"FirstName": "John" The customer's first name
MiddleName	"MiddleName": "Mark" The customer's middle name
LastName	"LastName": "Doe" The customer's last name
FullName	"FullName": "John Mark Doe" The customer's full name
Company	"Company": "Virid, Inc" The customer's place of work
Address	"Address": "12005 Sunrise Valley Drive" The customer's mailing address
Address2	"Address2": "Suite 400" An additional field for the customer's mailing address
City	"City": "Reston" The customer's city
StateOrProvince	"StateOrProvince": "VA" The customer's state or province
PostalCode	"PostalCode": "20147" The customer's postal code
Country	"Country": "US" The customer's country
Phone	"Phone": "7031010101" The customer's phone number
Fax	"Fax": "18884732963" The customer's fax number
MobilePhone	"MobilePhone": "2025550188" The customer's mobile phone number
Email	"Email": "[email protected]" The customer's email address
ShipType	"ShipType": "STD" The customer's preferred shipping type
DestinationType	"DestinationType": 2 The name of the shipping method as defined in the administration tools

Get Addresses

Gets a single address by its ID

GET	/api/v3/customers/123/addresses/12321

View Sample Response


HTTP/1.1 200 OK
  {
            "OID": 12321,
            "Alias": "Work",
            "FirstName": "Bob",
            "MiddleName": "",
            "LastName": "Smith",
            "FullName": "Bob Smith",
            "Company": "Virid, Inc",
            "Address": "12005 Sunrise Valley Drive",
            "Address2": "Suite 400",
            "City": "Reston",
            "StateOrProvince": "VA",
            "PostalCode": "20147",
            "Country": "US",
            "Phone": "7036892121",
            "Fax": "",
            "MobilePhone": "",
            "Email": "[email protected]",
            "ShipType": "STD",
            "DestinationType": " Business"
  }

Get Addresses

Lists all addresses for a customer.

GET	/api/v3/customers/12321/addresses

View Sample Response


HTTP/1.1 200 OK
[
   {
            "OID": 12321,
            "Alias": "Work",
            "FirstName": "Bob",
            "MiddleName": "",
            "LastName": "Smith",
            "FullName": "Bob Smith",
            "Company": "Virid, Inc",
            "Address": "12005 Sunrise Valley Drive",
            "Address2": "Suite 400",
            "City": "Reston",
            "StateOrProvince": "VA",
            "PostalCode": "20147",
            "Country": "US",
            "Phone": "7036892121",
            "Fax": "",
            "MobilePhone": "",
            "Email": "[email protected]",
            "ShipType": "STD",
            "DestinationType": " Business"
   }
]

Creates an Address

Creates an address associated with a customer.

POST	/api/v3/customers/12321/addresses
{ "Alias": "Work", "Address": "123 Testing Avenue", "City": "Reston", "StateOrProvince": "VA", "PostalCode": "20191", "Country": "US" }

View Sample Response


HTTP/1.1 201 Created
{
            "OID": 12321,
            "Alias": "Work",
            "FirstName": "",
            "MiddleName": "",
            "LastName": "",
            "FullName": "",
            "Company": "",
            "Address": "123 Testing Avenue",
            "Address2": "",
            "City": "Reston",
            "StateOrProvince": "VA",
            "PostalCode": "20191",
            "Country": "US",
            "Phone": "",
            "Fax": "",
            "MobilePhone": "",
            "Email": "",
            "ShipType": "",
            "DestinationType": ""
}

Updates an Address

Updates an address for a customer

PUT	/api/v3/customers/12321/addresses/10321
{ "Alias": "Vacation", "Address": "123 Secondary Dr", "City": "Reston", "StateOrProvince": "VA", "PostalCode": "20191", "Country": "US" }

View Sample Response


HTTP/1.1 204 No Content