====== FoxyCart's E-Commerce API ======

<note warning>Like any API, FoxyCart's API is for advanced users only. If you're not comfortable with programming, you should probably get familiar with your language of choice first, and never test on a live store. FoxyCart cannot be held responsible for any misuse of the API.</note>

===== Need to Know =====
  * The API is only available on v050 and above.
  * Make sure you've selected the appropriate hashing method (MD5 or SHA-1) in the "advanced" tab in your FoxyCart admin.
  * All ''_list'' methods (v070+) support a "pagination_start" parameter for paginating through your filtered result set. Along with the ''<messages>'' node with useful pagination information, there will be a ''<statistics>'' node which includes total records, filtered_total, pagination_start and pagination_end.
===== REST Request Format =====
REST is the simplest request format to use - it's a simple HTTP POST action. **GET** requests are //NOT// supported, which cuts down on potential security risks (particularly with regard to how GET requests tend to get logged, cached, stored, and etc.).

== Endpoint ==
The REST Endpoint URL is ''https:/ /example.foxycart.com/api'' or ''https:/ /custom.subdomain.tld/api'' (spaces added to prevent indexing), depending on what your FoxyCart store URL is set to. **All requests need the ''api_token'' passed in along with any request.** Your API Token is the same as your datafeed encryption key, and can be set in the Advanced tab in your FoxyCart admin.

**It is your responsibility to keep this key secure.** If a malicious person finds your API key they will have access that they definitely should //not// have.

== REST Response ==
By default, REST requests will send a response that looks something like this:
<code xml>
<?xml version='1.0' encoding='UTF-8'?>
<foxydata>
	<result>SUCCESS</result>
	<messages>
		<message>Customer Found</message>
	</messages>
	<customer_id>51</customer_id>
	<last_modified_date>2009-02-10 13:16:11</last_modified_date>
	<customer_first_name>brett</customer_first_name>
	<customer_last_name>florio</customer_last_name>
	<customer_company/>
	<customer_address1>555 Mulberry Dr.</customer_address1>
	<customer_address2/>
	<customer_city>Happyville</customer_city>
	<customer_state>CA</customer_state>
	<customer_postal_code>55555</customer_postal_code>
	<customer_country>US</customer_country>
	<customer_phone> </customer_phone>
	<customer_email>example@example.tld</customer_email>
	<shipping_first_name/>
	<shipping_last_name/>
	<shipping_company/>
	<shipping_address1/>
	<shipping_address2/>
	<shipping_city/>
	<shipping_state/>
	<shipping_postal_code/>
	<shipping_country>US</shipping_country>
	<shipping_phone/>
	<customer_password>97fad3230c7bca8cc37515c3de12e509</customer_password>
	<cc_number>xxxxxxxxxxxx1111</cc_number>
	<cc_exp_month>12</cc_exp_month>
	<cc_exp_year>2009</cc_exp_year>
	<shipto_addresses/>
</foxydata>
</code>

===== Request Methods =====
==== Customer Records ====
== Methods ==
  * ''customer_get'' (v050+)
  * ''customer_save'' (v050+)
== Required Fields ==
  * ''customer_id'' //OR// ''customer_email''
  * ''customer_password'' //OR// ''customer_password_hash'' is required for a ''customer_save'' action if the customer record is a new record (but is //not// required for updating an existing record).
== Data Retrieval ==
  * ''customer_list'' (v070+)
    * filter options: ''customer_id_filter'', ''customer_email_filter'', ''customer_first_name_filter'', ''customer_last_name_filter'', ''customer_state_filter'' 
== Notes: ==
  * The ''customer_password'' value:
    * When using ''customer_get'' method: Returns a //HASH// of the customer's password, //NOT THE ACTUAL PASSWORD//. You can set the hashing method in the Advanced tab in your FoxyCart admin. This setting is store-wide, not a per-user setting.
    * When using the ''customer_save'' method: Can accept a password as cleartext.  FoxyCart will create the password hash for you based on your chosen hashing method. **Sending the cleartext is recommended**, if you have access to it when you make the API request.
  * The ''customer_password_hash'' value: If you do not have the password in cleartext but would like to update the password, pass in ''customer_password_hash''. Whether you pass in a ''customer_password'' or a ''customer_password_hash'', the end result is the same: A hashed password will be returned on ''_get'' requests for the ''customer_password'' field.

==== Customer Addresses ====
== Methods ==
  * ''customer_address_get'' (v050+) (for multiple ship-to addresses)
  * ''customer_address_save'' (v050+) (for multiple ship-to addresses)
== Required Fields ==
  * ''customer_id'' //OR// ''customer_email''
==== Transactions ====
== Methods ==
  * ''transaction_get'' (v051+)
== Required Fields ==
  * ''transaction_id''
== Data Retrieval ==
  * ''transaction_list'' (v070+)
    * filter options: ''transaction_date_filter_begin'', ''transaction_date_filter_end'', ''is_test_filter'', ''hide_transaction_filter'', ''data_is_fed_filter'', ''id_filter'', ''order_total_filter'', ''coupon_code_filter'', ''customer_id_filter'', ''customer_email_filter'', ''customer_first_name_filter'', ''customer_last_name_filter'', ''customer_state_filter'', ''shipping_state_filter'', ''customer_ip_filter'', ''product_code_filter'', ''product_name_filter'', ''product_option_name_filter'', ''product_option_value_filter''

==== Subscriptions ====
== Methods ==
  * ''subscription_get'' (v060+)
  * ''subscription_cancel'' (v060+) Sets the ''sub_enddate'' to the next day, effectively canceling the subscription.
  * ''subscription_modify'' (v070+) Lets you modify any of the following subscription values: ''start_date'', ''end_date'', ''next_transaction_date'', ''frequency'', ''past_due_amount'',  ''is_active'', ''transaction_template''. For more details on the ''transaction_template'' format, see this XSD: http://admin.foxycart.com/v/0.7.0/xsd/transaction_template.xsd
== Required Fields ==
  * ''sub_token'', can be either the token itself or the complete URL
== Data Retrieval ==
  * ''subscription_list'' (v070+)
    * filter options: ''is_active_filter'', ''frequency_filter'', ''past_due_amount_filter'' (send 1 as the value to this filter and it will return subscriptions with past due amounts), ''start_date_filter_begin'', ''start_date_filter_end'', ''next_transaction_date_filter_begin'', ''next_transaction_date_filter_end'', ''end_date_filter_begin'', ''end_date_filter_end'', ''third_party_id_filter'' (currently only supports PayPal recurring payments), ''last_transaction_id_filter'', ''customer_id_filter'', ''customer_last_name_filter'', ''product_code_filter'', ''product_name_filter'', ''product_option_name_filter'', ''product_option_value_filter''

==== Example ====
Here's a //very rough// example of how to use the API using PHP:
<code php>
$foxy_domain = "myfoxydomain.foxycart.com";
$foxyData = array();
$foxyData["api_token"] = "XXXXX your api / datafeed key here XXXXXX";
$foxyData["api_action"] = "customer_save";
$foxyData["customer_id"] = "12345";
// OR use the email:
//$foxyData["customer_email"] = "customer@example.com";
$foxyData["customer_password"] = "my new password";

$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, "https://" . $foxy_domain . "/api");
curl_setopt($ch, CURLOPT_POSTFIELDS, $foxyData);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, 1);
curl_setopt($ch, CURLOPT_CONNECTTIMEOUT, 5);
curl_setopt($ch, CURLOPT_TIMEOUT, 15);
// If you get SSL errors, you can uncomment the following, or ask your host to add the appropriate CA bundle
// curl_setopt($ch, CURLOPT_SSL_VERIFYPEER, false);
$response = trim(curl_exec($ch));

// The following if block will print any CURL errors you might have
if ($response == false) {
	print "CURL Error: \n" . curl_error($ch);
} else {
	print "Response to customer save of " . $foxyData['customer_email'] . "\n";
	print $response;
}
curl_close($ch);

$foxyResponse = simplexml_load_string($response, NULL, LIBXML_NOCDATA);
print "<pre>";
var_dump($foxyResponse);
print "</pre>";
</code>


===== Language Specific Considerations =====

==== Ruby on Rails (RoR) ====
If you have difficulty with ''httparty'' or ''ActiveResource'', try putting the POST request in the '':body'' and not the '':query''.

==== Using CURL to Test the API ====
You can always use [[http://curl.haxx.se/docs/httpscripting.html|CURL]] to test the API. Here is an example command line CURL request:
<code>
curl -d "api_token=PUT_YOUR_API_KEY_HERE&api_action=customer_get&customer_email=john.doe@example.com" https://example.foxycart.com/api
</code>
You'd obviously need to insert your own values in that call, but it's provided here for reference. Using CURL can be handy if you just want to get a customer ID quickly, or test to ensure data is being returned as expected.