====== The FoxyCart API ====== ===== Before You Get Started With the API ===== Like any API, FoxyCart's API is geared towards advanced users only. If you're not comfortable with programming, you should probably get familiar with your language of choice first or look for professional assistance. Never test on a live store, as you can certainly create problems that could impact your customers or your revenue. ===== Connecting to the API ===== FoxyCart's API is partially RESTful, but for security reasons only supports ''POST'' requests at this point. **''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.). The endpoint URL for your FoxyCart store will look like ''https://example.foxycart.com/api'' or ''https://secure.example.tld/api'', 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. A successful API request will return a response similar to this: SUCCESS Customer Found 51 2009-02-10 13:16:11 brett florio 555 Mulberry Dr. Happyville CA 55555 US example@example.tld US 97fad3230c7bca8cc37515c3de12e509 xxxxxxxxxxxx1111 12 2009 ===== API Actions ===== ==== Global Notes, Methods, and Parameters ==== * All ''_list'' methods support a ''pagination_start'' parameter for paginating through your filtered result set. Along with the '''' node with useful pagination information, there will be a '''' node which includes total records, ''filtered_total'', ''pagination_start'', and ''pagination_end''. 070 shows 50 entries at a time, 071 defaults to 300 but in 071 you can also pass in an ''entries_per_page'' value to override it. * All ''_list'' methods can accept multiple filters. * Make sure you've selected the appropriate hashing method in the "advanced" tab in your FoxyCart admin, especially if you're using any ''customer_'' API calls. ==== Customer ==== === Methods === ; ''customer_get'' : **Required Fields:** ''customer_id'' //or// ''customer_email'' : **Notes:** Cannot be used to retrieve guest customer accounts. ; ''customer_save'' : **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). : **Notes:** When creating a user or updating a password it is strongly recommended to send the cleartext password in the ''customer_password'' parameter, due to the way FoxyCart handles password resets. Please see the notes below for additional information. ; ''customer_list'' : **Filter Options:** ''customer_id_filter'', ''customer_email_filter'', ''customer_first_name_filter'', ''customer_last_name_filter'', ''customer_state_filter'' ; ''customer_address_get'' : **Required Fields:** ''customer_id'' //or// ''customer_email'' : **Notes:** Only applicable for stores using multi-ship. ; ''customer_address_save'' : **Required Fields:** ''customer_id'' //or// ''customer_email'' : **Notes:** Only applicable for stores using multi-ship. === 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. * When using the ''customer_save'' method you can pass the customer's password as cleartext. FoxyCart will create the password hash for you based on your chosen hashing method. * 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. * The ''cc_number'' field will return a //masked// card number if a payment method is saved. Otherwise it will be empty. ==== Transactions ==== ; ''transaction_get'' : **Required Fields:** ''transaction_id'' ; ''transaction_list'' : **Filter Options:** * ''transaction_date_filter_begin'' (YYYY-MM-DD), ''transaction_date_filter_end'' (YYYY-MM-DD) * ''is_test_filter'', ''hide_transaction_filter'', ''data_is_fed_filter'' (0 or 1), ''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'' ; ''transaction_modify'' : **Required Fields:** ''transaction_id'' : **Accepts:** ''data_is_fed'' (0 or 1) : **Notes:** Changing this bit has no impact on anything other than the value of this bit. (ie. It does not tell FoxyCart to refeed the datafeed to your endpoint) ==== Subscriptions ==== ; ''subscription_get'' : **Required Fields:** ''sub_token'' (either the token by itself or the complete ''sub_token'' URL) ; ''subscription_cancel'' : **Required Fields:** ''sub_token'' (either the token by itself or the complete ''sub_token'' URL) : **Notes:** Sets the ''sub_enddate'' to the next day, effectively canceling the subscription. This way the subscription cancellation will still be included in the [[.:subscription_xml_datafeed|Subscription XML Datafeed]]. To deactivate a subscription immediately you can use the ''subscription_modify'' method. ; ''subscription_modify'' : **Required Fields:** ''sub_token'' (either the token by itself or the complete ''sub_token'' URL) : **Accepts:** * ''start_date'' (YYYY-MM-DD) (The ''start_date'' is somewhat historical, and indicates the very first date a subscription processed.) * ''end_date'' (YYYY-MM-DD) * ''next_transaction_date'' (YYYY-MM-DD) (The ''next_transaction_date'' is reset with every subscription processing, whether successful or erroring.) * ''frequency'' ([[..:cheat_sheet#subscription_product_options|available options]]) * ''past_due_amount'' (decimal) * ''is_active'' (0, 1) * ''transaction_template'' ([[http://admin.foxycart.com/v/0.7.0/xsd/transaction_template.xsd|XSD]]) ; ''subscription_list'' : **Filter Options:** * ''is_active_filter'' * ''frequency_filter'' * ''past_due_amount_filter'' (if you include this filter and give it a value (such as ''1'') it will return subscriptions with past due amounts greater than 0) * ''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'' (YYYY-MM-DD) * ''third_party_id_filter'' (for PayPal Express Checkout recurring payments) * ''last_transaction_id_filter'' * ''customer_id_filter'', ''customer_email_filter'', ''customer_first_name_filter'', ''customer_last_name_filter'' * ''product_code_filter'', ''product_name_filter'', ''product_option_name_filter'', ''product_option_value_filter'' ; ''subscription_datafeed'' : **Notes:** Passing the ''subscription_datafeed'' as the ''api_action'' to the API endpoint will immediately re-feed the [[.:subscription_xml_datafeed|Subscription XML Datafeed]] to your already configured XML datafeed endpoint. ==== Example ==== Here's a //very rough// example of how to use the API using 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 "
";
var_dump($foxyResponse);
print "
";
===== 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: curl -d "api_token=PUT_YOUR_API_KEY_HERE&api_action=customer_get&customer_email=john.doe@example.com" https://example.foxycart.com/api 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. Here's an example to retrieve a transaction: curl -d "api_token=PUT_YOUR_API_KEY_HERE&api_action=transaction_get&transaction_id=1234567890" https://example.foxycart.com/api And here's how to refeed the [[:static:redirect:subscription_datafeed|subscription XML datafeed]]: curl -d "api_token=PUT_YOUR_API_KEY_HERE&api_action=subscription_datafeed" https://example.foxycart.com/api