"Edit Customer" API


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

Modular Merchant Gold (and higher) account plans have access to a "Edit Customer" APIs that allow a remotely-hosted website to update the database information of a specified customer account.

All requests to retrieve order data should be submitted to the "Edit 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/edit_customer_profile.php

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 update the database record for customer SID 123.

<?xml version="1.0" encoding="utf-8"?>
<xmlrequest>
   <admin_sid>789</admin_sid>
   <admin_key>9c1bc31d1543a1ba51d621a74b2fd</admin_key>
   <api_key>wHiJz5VeuRdUUbOJXDSURbJtXWX</api_key>
    <id>123</id>
   <email>dudley@example.com</email>
   <password>Honduras123</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 000</bill_address_2>
   <bill_city>Anytown</bill_city>
   <bill_state>OR_US</bill_state>
   <bill_zip>00000</bill_zip>
   <bill_country>US</bill_country>
   <phone_ac>555</phone_ac>
   <phone>555-5555</phone>
   <active>1</active>
   <reward_points>456</reward_points>
   <has_tab>1</has_tab>
   <tab_terms>90</tab_terms>
   <tab_limit>10000</tab_limit>
   <tax_exempt>0</tax_exempt>
   <is_aff>1</is_aff>
   <aff_approved>1</aff_approved>
   <aff_parent_tid>789</aff_parent_tid>
   <aff_company>Super Affiliate Co.</aff_company>
   <aff_url>http://www.example.com</aff_url>
   <aff_fax>(555) 555-5555</aff_fax>
   <aff_payable_to>I</aff_payable_to>
   <aff_tax_class>I</aff_tax_class>
   <aff_tax_id>123-45-6789</aff_tax_id>
   <ship_addresses>
       <ship_address>
           <id>8</id>
           <ship_first_name>D.</ship_first_name>
           <ship_last_name>H.</ship_last_name>
           <ship_address_1>000 Shipping Lane</ship_address_1>
           <ship_address_2>Shipping Department 1</ship_address_2>
           <ship_city>Shipton</ship_city>
           <ship_state>CA_US</ship_state>
           <ship_zip>90210</ship_zip>
           <ship_country>US</ship_country>
       </ship_address>
        ...The ship_address section is repeated for each of the customer's ship addresses to be modified.
   </ship_addresses>
</xmlrequest>

urlencode the xml data

The data contained in each XML node must be urlencoded. For example, spaces would be translated into plus signs:

Wrong: <bill_first_name>Dudley Heromin</bill_first_name>

Correct: <bill_first_name>Dudley+Heromin</bill_first_name>

tip: only include what you want to modify

The XML sample above lists all of the fields that can be included in a request. However, it's possible to include only the ones you want to modify.

For example, if submitting a request that would only update the customer's email address and password, then the request would look like this:

<?xml version="1.0" encoding="utf-8"?>
<xmlrequest>
   <admin_sid>789</admin_sid>
   <admin_key>9c1bc31d1543a1ba51d621a74b2fd</admin_key>
   <api_key>wHiJz5VeuRdUUbOJXDSURbJtXWX</api_key>
    <id>123</id>
   <email>dudley@example.com</email>
   <password>Honduras123</password>
</xmlrequest>

xml request fields

The following fields can be used in the submitted XML query to specify the fields in the customer's database record to modify:

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.)

id: The SID (System ID) number of the customer record to be modified.

email: The customer's email address. Every customer record must have a unique email address.

password: The customer account's password.

bill_first_name: The first name of the customer's billing address.

bill_last_name: The last name of the customer's billing address.

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 customer's billing city.

bill_state: The customer's billing state. Must be formatted as: the two-character ISO code of the customer's billing state, followed by an underscore, followed by the two-character ISO code for the customer's country. For example, the bill_state for a customer in Washington, USA would be WA_US. The bill_sate for a customer in Western Australia would be WA_AU.

bill_zip: The customer's billing zip/postal code.

bill_country: The two-character ISO code of the customer's billing country.

phone_ac: The area code of the customer's phone number.

phone: The customer's phone number.

active: Whether the customer account is active. If zero, then the customer account is inactive, and will not be able to place orders in the storefront or log in to their customer account area. If set to any value greater than zero, then the customer account is active.

reward_points: The number of Reward Points the customer has.

has_tab: Whether or not the customer has a credit account. If zero, then the customer does not have a credit account. If greater than zero, then the do.

tab_terms: The number of days in the term for the customer's credit account.

tab_limit: The dollar value of the customer's credit account.

tax_exempt: Whether or not the customer is tax exempt. If zero, then the customer is not tax exempt. If greater than zero, then they are.

is_aff: Whether or not the customer is also an affiliate. If zero, then the customer is not an affiliate. If greater than zero, then they are.

aff_approved: Whether or not the customer's affiliate status has been approved. If zero, then the customer is not approved, and will not earn commissions, even on eligible purchases. If greater than zero, then they are.

aff_parent_tid: The affiliate TID (Tracking ID) number, if any, that the customer is associated with.

aff_company: The name of the affiliate's company.

aff_url: The URL (web address) of the affiliate's website.

aff_fax: The affiliate's fax number.

aff_payable_to: Whether the affiliate is considered an individual or company. Acceptable values for this field are "I" or "C".

aff_tax_class: Whether the affiliate's tax class is an Individual, Corporation or Non-profit organization. Acceptable values for this field are "I", "C" or "N".

aff_tax_id: The affiliate's tax ID number.

SHIPPING ADDRESSES
The shipping_addresses section contains the "ship_address" node, which is repeated for each shipping address to be modified.

id: The SID number of the shipping address.

ship_first_name: The first name of the customer's shipping address.

ship_last_name: The last name of the customer's shipping address.

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 customer's shipping city.

ship_state: The customer's shipping state. Must be formatted as: the two-character ISO code of the customer's shipping state, followed by an underscore, followed by the two-character ISO code for the customer's country. For example, the ship_state for a customer in Washington, USA would be WA_US. The ship_sate for a customer in Western Australia would be WA_AU.

ship_zip: The customer's shipping zip/postal code.

ship_country: The two-character ISO code of the customer's shipping country.

Sample XML Response

The response below corresponds with the sample XML request above. The XML response contains the results of the query, and any corresponding messages.

The response_status node contains a flag indicating whether the query was successful or failed.
If the query failed, then the error_message node will be included. It will contain each error encountered.
If the query was successful, then the success_message node will be included. It will contain each message generated.

a sample success response

<?xml version="1.0" encoding="utf-8"?>
<response>
<response_status>success</response_status>
<success_message>The+database+record+for+customer+SID+123+has+been+updated.</success_message>
</response>

a sample failure response

<?xml version="1.0" encoding="utf-8"?>
<response>
<response_status>error</response_status>
<error_message>Could+not+validate+the+submitted+API+key.</error_message>
</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

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