|
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 "Check Customer" APIs that allow a remotely-hosted website to validate a customer's account using its login credentials, and return that customer's account info, optionally including a list of the products they are subscribed to, and their recent order history.
All requests to retrieve customer data should be submitted to the "Check Customer" 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/check_customer.php
When searching for customers, the customer's email address and password should be specified in the the XML request. See the XML sample request below for a list of all available 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 verify the account for customer "example@email.com". The results will also include a list of the products the customer is subscribed to, and a list of all the orders that they have placed within the last 90 days.
<?xml version="1.0" encoding="utf-8"?>
<xmlrequest>
<admin_sid>123</admin_sid>
<admin_key>23a1c9ba51d691a74b2fd</admin_key>
<api_key>9c1bc31e15423a1c9ba</api_key>
<email>example@email.com</email>
<password>123ABC</password>
<get_subscription>Yes</get_subscription>
<order_history>90</order_history>
</xmlrequest>
how do i use this xml data?
If you're uncertain how to submit a request full of XML data to your store's API, then refer to the Introduction to APIs article for an example on how to use PHP's cURL functions to send an XML request to your store.
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>
request 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.)
email: The email address associated with the customer account.
password: The password associated with the customer account.
get_subscription: If set to "Yes", then a list of the products that the customer is subscribed to will be included in the XML response.
order_history: If a number greater than zero is specified, then a list of the customer's orders within that many days will be included in the XML response.
The Check Customers API will respond with XML data that contains:
-
The customer's account information (billing address, shipping address, custom fields, etc.)
-
When $get_subscription is set to Yes, a list of the products in the customer's subscription will be included.
-
When $order_history is set to greater than zero, a list of the orders in the customer's purchase history will be included.
The XML data returned by the shopping cart is contained in a variable named $results.
Here is an example of the format of the XML data contained within the $results variable:
code <?xml version="1.0" encoding="utf-8"?>
<results>
<customer_data>
<cid>12345</cid>
<email>user%40email.com</email>
<password>qRyP2mrnCrclhZ%2Bw%2BRPv5ds89uvr35gb</password>
<bill_first_name>Dudley</bill_first_name>
<bill_last_name>Heromin</bill_last_name>
<bill_address1>000+Paved+Road</bill_address1>
<bill_address2>Suite+000</bill_address2>
<bill_city>Anytown</bill_city>
<bill_state>OR_US</bill_state>
<bill_zip>00000</bill_zip>
<bill_country_iso>US</bill_country_iso>
<bill_state_iso>OR</bill_state_iso>
<bill_state_long>Oregon</bill_state_long>
<bill_country_long>United States</bill_country_long>
<phone_ac>000</phone_ac>
<phone>555-5555</phone>
<cid_active>Y</cid_active>
<cmr_custom_1>customer+field+one</cmr_custom_1>
<cmr_custom_2>customer+field+two</cmr_custom_2>
<cmr_custom_3>customer+field+three</cmr_custom_3>
<cmr_custom_4>customer+field+four</cmr_custom_4>
<cmr_custom_5>customer+field+five</cmr_custom_5>
<cmr_custom_6>customer+field+six</cmr_custom_6>
<cmr_custom_7>customer+field+seven</cmr_custom_7>
<cmr_custom_8>customer+field+eight</cmr_custom_8>
<cmr_custom_9>customer+field+nine</cmr_custom_9>
<cmr_custom_10>customer+field+ten</cmr_custom_10>
<use_prev_cc>0</use_prev_cc>
<has_tab>N</has_tab>
<tab_terms>0</tab_terms>
<tab_limit>0.00</tab_limit>
<tax_exempt>N</tax_exempt>
<notes>notes+about+this+customer+account</notes>
<cmr_news>news+alerts+for+this+customer</cmr_news>
<create_date>1211994000</create_date>
<edit_date>1277335992</edit_date>
<edited_by>000</edited_by>
<ship_addr_id>123</ship_addr_id>
<ship_nick_name>Dudley+Heromin</ship_nick_name>
<ship_first_name>Heromin</ship_first_name>
<ship_last_name>Heromin</ship_last_name>
<ship_address1>000+Gravel+Road</ship_address1>
<ship_address2>Suite+000</ship_address2>
<ship_city>Anytown</ship_city>
<ship_state>CA_US</ship_state>
<ship_zip>00000</ship_zip>
<ship_country_iso>US</ship_country_iso>
<ship_state_iso>CA</ship_state_iso>
<ship_state_long>California</ship_state_long>
<ship_country_long>United+States</ship_country_long>
</customer_data>
<order_data>
<order_item>
<order_id>56789</order_id>
<order_date>1222122161</order_date>
<order_product>
<product_sid>123</product_sid>
<product_name>Sample+Product</product_name>
</order_product>
</order_item>
</order_data>
<subscription_data>
<subscription_item>
<product_sid>123</product_sid>
<product_name>Sample+Product</product_name>
<bill_date>1222122161</bill_date>
</subscription_item>
</subscription_data>
</results>
The <order_data>...</order_data> section is only included when the $order_history value in the request is greater than zero.
The <order_item>...</order_item> section will be repeated for every order found within the specified date range in the customer's purchase history.
The <subscription_data>...</subscription_data> section is only included when the $get_subscription value in the request is set to Yes.
The <subscription_item>...</subscription_item> section will be repeated for every product in the customer's subscription.
tip The XML data 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 DATA 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_in: The Unix timestamp of the date that the customer opted in to 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.
memo: Administrative memo for 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).
reward_points: The number of Reward Points assigned to the customer account.
tab_limit: The maximum dollar value of the customer's credit account.
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.
use_prev_cc: Whether the secure list of the customer's previously used credit cards will be displayed on the storefront's checkout page.
SUBSCRIPTION DATA NODES
product_sid: The System ID number of the product.
product_name: The name of the product.
bill_date: Unix timestamp of the bill date of the customer's subscription to the product.
ORDER DATA NODES
order_id: The System ID number of the order.
order_date: Unix timestamp of the date of the order was created.
product_sid: The System ID number of the product.
product_name: The name of the product.
|
