"Check Customer" API


	"Check Customer" API
	Last Edited - 03/9/2015 8:37am PDT
	Category Path - Developer's Guide > APIs

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.

Sample 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

The PHP website includes some tutorials on how to turn XML data into an object that PHP can use.

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.