|
this article last updated: March 9, 2015 Due to inevitable changes that will be made to the shopping cart software over time, the cart's variable and database structure may change from time to time without advanced notice. We will attempt to keep the information in this article up-to-date, but Modular Merchant makes no guarantee as to the accuracy of the information provided in this article. Use this information at your own risk.
Modular Merchant Gold (and higher) account plans have access to a "Get Customers" APIs that allow a remotely-hosted website to search for customers and/or retrieve the details of a specified set of customers.
All requests to retrieve customer data should be submitted to the "Get Customers" API URL, located in your online store. An example of the URL for this API would look something like this: http://www.mystore.com/api/get_customers.php
When searching for customers, the search criteria should be specified in the search_rule section of the XML request. See the Search Options section below for a list of all available search options.
tip
To learn more about the cart's APIs (how requests should be structured, a sample query using PHP, etc.) we recommend looking over the Introduction to APIs article.
Sample XML Request
The XML request below will match all customers that have an email address containing @modularmerchant.com. The results will start from the 3rd matched record and return 11 results.
<?xml version="1.0" encoding="utf-8"?>
<xmlrequest>
<admin_sid>123</admin_sid>
<admin_key>23a1c9ba51d691a74b2fd</admin_key>
<api_key>9c1bc31e15423a1c9ba</api_key>
<search_type>keyword</search_type>
<start_result>3</start_result>
<number_of_results>11</number_of_results>
<any_vs_all>any</any_vs_all>
<order_by>customer.id</order_by>
<asc_vs_desc>ASC</asc_vs_desc>
<search_rule>
<search_field>customer.email</search_field>
<compare_type>*LIKE*</compare_type>
<search_string>@modularmerchant.com</search_string>
</search_rule>
...The search_rule section is repeated for each rule to search by.
</xmlrequest>
urlencode the xml data
The data contained in each XML node must be urlencoded.
For example, if you wanted the "compare_type" node to be ">" (greater than):
Wrong: <compare_type>></compare_type>
Correct: <compare_type>%3E</compare_type>
search options
The following options can be used in the submitted XML query to specify the options to search the store's customer records by:
admin_sid: The SID number of the admin submitting the query.
admin_key: The personal API Key of the admin submitting the query. (Found on the Admin Account Editor page.)
api_key: The account-wide API Key. (Found on the System Settings page.)
search_type: The type of search to perform. Currently only "keyword" is supported.
start_result: The number of the result to start with. "3" would start with the third result.
number_of_results: The number of results to include in the XML response.
any_vs_all: Specifies whether the results must match "all" or "any" of the search rules.
order_by: The database field by which to order the search results. Example: "customers.id".
asc_vs_desc: Whether the results should be ordered in ascending ("ASC") or descending ("DESC") order.
SEARCH RULES
The search_rules section is repeated for each rule to match.
search_string
The content to match against. For example, to find all customers with a Modular Merchant email address, the recommended search string would be "@modularmerchant.com".
compare_type
How the search string will be compared to the search field. Options include:
1. *LIKE* (The database record must contain the search string.)
2. *NOT LIKE* (The database record must not contain the search string.)
3. = (The database record is equal to the search string.)
4. != (The database record is not equal to the search string.)
5. > (The database record is greater than the search string.)
6. < (The database record is less than the search string.)
7. LIKE* (The database record starts with the search string.)
8. *LIKE (The database record ends with the search string.)
search_field
The database field to apply the search against. Some common options include:
customer.active: The active status of the customer's account. (Y/N format)
customer.aff_approved: Affiliate Application Approved (Y/N format)
customer.aff_company: Affiliate Company Name
customer.aff_fax: Affiliate Fax Number
customer.aff_parent_tid: Affiliate Parent Tracking ID
customer.aff_url: Affiliate Website (URL format)
customer.bill_address_1: Billing Address Line 1
customer.bill_address_2: Billing Address Line 2
customer.bill_city: Billing City
customer.bill_country: Billing Country (ISO format)
customer.bill_first_name: Billing First Name
customer.bill_last_name: Billing Last Name
customer.bill_state: Billing State (ISO format)
customer.bill_zip: Billing Zip
customer.create_date: Date Created (MM/DD/YYYY format)
customer.email: Email Address
customer.email_bounces: Number of Bounced Emails
customer.email_opt_out: Email Opt In Status (Y/N format)
customer.has_tab: Has Net Terms (Y/N format)
customer.id: SID (System ID format)
customer.is_aff: Is Affiliate? (Y/N format)
customer.phone: Phone Number
customer.phone_ac: Phone Area Code
customer.reward_points: Reward Points
customer.tab_limit: Terms Limit (example: 12.34 format)
customer.tab_terms: Net Terms (in days)
customer.tax_exempt: Tax Exempt (Y/N format)
customer_group_assoc.group_id: Customer Group (SID format)
customer_ship_addr.ship_address_1: Shipping Address Line 1
customer_ship_addr.ship_address_2: Shipping Address Line 2
customer_ship_addr.ship_city: Shipping City
customer_ship_addr.ship_country: Shipping Country (ISO format)
customer_ship_addr.ship_first_name: Shipping First Name
customer_ship_addr.ship_last_name: Shipping Last Name
customer_ship_addr.ship_state: Shipping State (ISO format)
customer_ship_addr.ship_zip: Shipping Zip
email_opt_out_date: Email Opt Out Date (MM/DD/YYYY format)
note.content: Customer Notes
The response below corresponds with the sample XML request above. The XML response contains the customers that match the search criteria.
-
The response_status node contains a flag indicating whether the query was successful or failed.
-
The data node contains the customers that match the search criteria. Each customer will be encapsulated in an customer tag.
<?xml version="1.0" encoding="utf-8"?>
<response>
<response_status>success</response_status>
<data>
<customer>
<id>1476</id>
<email>example%40modularmerchant.com</email>
<password>123ABC</password>
<bill_first_name>Dudley</bill_first_name>
<bill_last_name>Heromin</bill_last_name>
<bill_address_1>000+Paved+Road</bill_address_1>
<bill_address_2>Suite+311</bill_address_2>
<bill_city>Anytown</bill_city>
<bill_state>CA_US</bill_state>
<bill_zip>90210</bill_zip>
<bill_country>US</bill_country>
<phone_ac>555</phone_ac>
<phone>555-5555</phone>
<active>1360342757</active>
<use_prev_cc>0</use_prev_cc>
<reward_points>0</reward_points>
<has_tab>0</has_tab>
<tab_terms>0</tab_terms>
<tab_limit>0</tab_limit>
<tax_exempt>0</tax_exempt>
<memo></memo>
<is_aff>0</is_aff>
<aff_approved>0</aff_approved>
<aff_parent_tid>0</aff_parent_tid>
<aff_company></aff_company>
<aff_url></aff_url>
<aff_fax></aff_fax>
<aff_payable_to>I</aff_payable_to>
<aff_tax_class>I</aff_tax_class>
<aff_tax_id></aff_tax_id>
<email_opt_in>0</email_opt_in>
<email_bounces>0</email_bounces>
<create_date>1205441357</create_date>
<email_opt_out>1205441357</email_opt_out>
<customer_sid>1476</customer_sid>
<email_opt_out_date>1205441357</email_opt_out_date>
<num_orders>1</num_orders>
<total_spent>0.00</total_spent>
<num_ship_addr>1</num_ship_addr>
<num_cust_group>6</num_cust_group>
<num_cust_review>0</num_cust_review>
<recent_order_date>1360331130</recent_order_date>
<recent_order_id>25106</recent_order_id>
<subscription_id>1476</subscription_id>
<mod_date>1360342769</mod_date>
<login_date>1360331107</login_date>
<num_emails>0</num_emails>
<recent_subscription_date>1577824230</recent_subscription_date>
<tab_due></tab_due>
<tab_remaining>0</tab_remaining>
<customer_ship_addr>
<id>123</id>
<cid>1476</cid>
<ship_first_name>Loraine</ship_first_name>
<ship_last_name>Gershawitz</ship_last_name>
<ship_address_1>000+Gravel_Road</ship_address_1>
<ship_addresss_2></ship_addresss_2>
<ship_city>Somewhereburg</ship_city>
<ship_state>OR_US</ship_state>
<ship_zip>97479</ship_zip>
<ship_country>US</ship_country>
</customer_ship_addr>
...customer_ship_addr node is repeated for each customer ship address returned.
</customer>
...customer node is repeated for each customer returned.
</data>
</response>
tip
The XML data returned by the API is " url encoded". To improve its legibility, be sure to apply urldecode() or a similar function to it.
reference
nodes included in the customer response xml
Below are some definitions of some of the commonly used nodes of the response XML.
CUSTOMER NODE
active: Whether the customer's account is active. No if zero, otherwise yes.
aff_approved:Whether the customer is approved to be an affiliate. No if zero, otherwise yes.
aff_company: The company name associated with the customer's affiliate account (if any).
aff_fax: The fax number associated with the customer's affiliate account (if any).
aff_parent_tid: The SID number of an Affiliate Tracking ID number that was associated with the customer when they started their customer account.
aff_payable_to: Whether affiliate payments are made to an Individual or Company.
aff_tax_class: Whether the affiliate's tax class is an Individual or Company.
aff_tax_id: The affiliate's tax ID number.
aff_url: The URL of the affiliate's home page.
bill_address_1: The first line of the customer's billing address.
bill_address_2: The second line of the customer's billing address.
bill_city: The city of the customer's billing address.
bill_country: The country of the customer's billing address.
bill_first_name: The first name from the customer's billing address.
bill_last_name: The last name from the customer's billing address.
bill_state: The state from the customer's billing address.
bill_zip: The zip code from the customer's billing address.
create_date: Unix timestamp of the date the customer's account was created.
customer_sid: The SID number of the customer's account.
email: The email address associated with the customer's account.
email_bounces: The number of emails sent to the customer using the Modular Mailer email system that have bounced back as undeliverable.
email_opt_out_date: The Unix timestamp of the date that the customer opted out of the store's Modular Mailer mailing lists. Zero if opted in.
has_tab: Whether the customer has a credit limit. If this number is greater than zero, then they do.
id: The customer's SID (System ID) number.
is_aff: Whether the customer is also an affiliate. If this number is greater than zero, then they are.
login_date: Unix timestamp of the last date the customer logged in to their Customer Account Area in the storefront.
mod_date: Unix timestamp of the most recent date the customer account was edited.
num_cust_group: The number of Customer Groups that the customer belongs to.
num_cust_review: The number of Product Reviews the customer has written.
num_emails: The number of recent emails the customer has been sent.
num_orders: The number of orders that customer has placed.
num_ship_addr: The number of shipping addresses that are associated with this customer account.
password: The password associated with the customer account.
phone: The customer's phone number.
phone_ac: The area code associated with the customer (if it was entered separately from the phone number).
recent_order_date: Unix timestamp of the customer's most recent order.
recent_order_id: SID number of the customer's most recent order.
recent_subscription_date: Unix timestamp of the customer's upcoming subscription.
reward_points: The number of Reward Points assigned to the customer account.
ship_address_1: The first line of the customer's shipping address.
ship_address_2: The second line of the customer's shipping address.
ship_city: The city of the customer's shipping address.
ship_country: The country of the customer's shipping address.
ship_first_name: The first name from the customer's shipping address.
ship_last_name: The last name from the customer's shipping address.
ship_state: The state from the customer's shipping address.
ship_zip: The zip code from the customer's shipping address.
subscription_id: The SID number of the customer's subscription.
tab_due: The dollar value of any outstanding balance on the customer's credit account.
tab_limit: The maximum dollar value of the customer's credit account.
tab_remaining: The customer's "tab_limit" minus their "tab_due".
tab_terms: The number of days in a the customer's credit terms.
tax_exempt: Whether the customer's account is tax exempt. If greater than zero, then yes.
total_spent: The total this customer has spent in your store.
use_prev_cc: Whether the secure list of the customer's previously used credit cards will be displayed on the storefront's checkout page.
|
