no way to compare when less than two revisions

Differences

This shows you the differences between two versions of the page.

@@ Line 1: / Line 1: @@
+====== 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.
+<wrap important>It is your responsibility to keep this key secure.</wrap> 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:
+<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_masked>xxxxxxxxxxxx1111</cc_number_masked>
+  <cc_exp_month>12</cc_exp_month>
+  <cc_exp_year>2011</cc_exp_year>
+  <cc_start_date_month>10</cc_start_date_month>
+  <cc_start_date_year>2005</cc_start_date_year>
+  <cc_issue_number>01</cc_issue_number>
+  <shipto_addresses/>
+</foxydata>
+</code>
+===== API Actions =====
+==== Global Notes, Methods, and Parameters ====
+  * 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.
+=== Notes about _list Methods ===
+  * <wrap tip>NEW!</wrap> All ''_list'' methods now support wildcard searching. Use an asterisk (''*'') when filtering to do partial matches.
+  * All ''_list'' methods 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''.
+  * You can also pass in an ''entries_per_page'' value to override it.
+==== Store ====
+=== Methods ===
+  ; ''store_template_cache''
+  : **Notes:** This method will use our [[.:templates|"automagicache" automatic template caching]] programmatically. On success, the store's template will be updated, and the corresponding URL will also be saved.
+  : **Required Fields:**
+    * ''template_type'': Accepts ''cart'', ''checkout'', ''receipt'', ''html_email'', ''email''
+  : **Optional Fields:**
+    * ''template_url'': A complete, well-formed URL, such as ''http://example.tld/path/to/template.ext''. If omitted, the existing URL stored in the admin (for the ''template_type'' as passed in) will be used.
+    * ''email_subject'': A text string to be used for email receipts. Only valid if ''template_type'' is ''html_email'' or ''email''.
+    * ''send_html_email'': Accepts a ''1'' or ''0''. To use text only email receipts, send a ''0''. To have both text and html emails sent, set to ''1''. Note that this corresponds to the radio button in the admin. If this is a ''1'', you should have a ''html_email'' template configured.
+  ; ''store_includes_get''
+  : **Notes:** Returns the FoxyCart javascript (and other required javascript or CSS files) for the store's version of FoxyCart. This is also available in the admin under the "sample code" section.
+  : **WARNING:** <wrap important>This call should //not// be run on every pageload on your site.</wrap> If you use this, cache it locally so you can serve your pages quickly and without needing to make an external request to the FoxyCart API. For the performance of our entire system, we may have to deny access for any stores that make excessive calls to this method.
+  : **Optional Fields:**
+    * ''javascript_library'': Accepts ''none'' and ''jquery''. If you're already loading jQuery elsewhere in your site, you can set this to ''none'' and the code returned will not include jQuery. Note that the ''foxycart.js'' files do require jQuery.
+    * ''cart_type'': Accepts ''none'', ''colorbox''. This parameter determines how the cart will function by default. If you don't want the default [[http://colorpowered.com/colorbox|Colorbox]]-powered cart, set this to ''none''.
+  : **Response:**
+    * ''code_block'': The appropriate ''<script>'' and ''<style>'' tags are returned inside a ''CDATA'' block.
+    * ''javascript_library_version_required'': This node contains the minimum required version of the javascript library requested. At this point jQuery is required, so the value returned (''1.7.1'' at the launch of FoxyCart v1.0) refers to jQuery.
+  ; ''attribute_save''
+  : **Notes:** This API method allows you to attach name/value pairs to ''customer'', ''transaction'', or ''subscription'' records. These values can then be used for filtering, so you could attach fulfillment status to transactions in FoxyCart, then query against the data directly in FoxyCart.
+  : **Required Fields:**
+    * ''name'', ''value''
+    * ''type'': Accepts ''transaction'', ''customer'', ''subscription''
+    * ''identifier'': Accepts a valid ''transaction_id'', ''customer_id'', ''sub_token'', ''sub_token_url'' (depending on what was passed in as the ''type'')
+  : **Optional Fields:**
+    * ''append'': Accepts ''0'' (default), ''1''. If ''1'', the ''value'' will be appended to the existing ''value'' for any matched ''name'' attributes. If ''0'' or left blank, all ''<attribute>'' nodes will be replaced with the value set.
+  : **Passing in XML:** You can also save multiple name/value pairs by passing in XML. You can view the XSD of the expected input (and output), or you can view this example: <code>curl -d "api_token=YOUR_API_KEY_HERE&api_action=attribute_save&type=customer&identifier=193&attributes=<attributes><attribute><name>foo</name><value>bar</value></attribute><attribute><name>cake</name><value>lie</value></attribute></attributes>" https://your_store_domain.foxycart.com/api</code> That XML looks like this, pretty printed: <code xml><attributes>
+  <attribute>
+    <name>foo</name>
+    <value>bar</value>
+  </attribute>
+  <attribute>
+    <name>isla</name>
+    <value>pie</value>
+  </attribute>
+</attributes>
+</code>
+  ; ''attribute_list''
+  : **Required Fields:**
+    * ''type'', ''identifier'' (as described above)
+  ; ''attribute_delete''
+  : **Required Fields:**
+    * ''type'', ''identifier'' (as described above)
+  : **Optional Fields:**
+    * ''name'': If passed in, all ''attribute'' values for this named/value pair will be deleted. If ''name'' is not passed in, ''all'' is required.
+    * ''all'': Accepts ''0'' (default), ''1''. If ''1'' is passed in, all attributes (ie. all names) will be removed for the specified record. If ''all'' is not set to ''1'', a ''name'' value will be required. If both ''all'' and a ''name'' are passed in, the ''all'' will take precedence.
+  ; ''category_list''
+  : **Required Fields:** None.
+  : **Response:** XML with ''id'', ''code'', ''description'', and ''product_delivery_type'' for all categories.
+  ; ''downloadable_list''
+  : **Required Fields:** None.
+  : **Response:** XML with ''id'', ''category_id'', ''category_code'', ''product_name'', ''product_code'', ''product_price'', ''file_size'', and ''upload_date'' for all downloadables.
+==== 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).
+    * ''customer_password_salt'' //may// be required depending on your store's [[.:customers#synchronizing_users_and_passwords|password hashing settings]].
+    * ''customer_country'' should be considered required, and must be a valid [[wp>ISO_3166-1_alpha-2|2 character ISO country code]]. If a ''customer_country'' isn't provided, the store's country (pulled from the store settings) will be used instead.
+  ; ''customer_list''
+  : **Filter Options:** ''customer_id_filter'', ''customer_email_filter'', ''customer_first_name_filter'', ''customer_last_name_filter'', ''customer_state_filter''. Use an asterisk (''*'') when filtering to do partial matches.
+  ; ''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.
+  ; ''attribute_save''
+  : **Notes:** See the ''attribute_save'' documentation under the [[#store|store]] API section.
+  ; ''attribute_list''
+  : **Notes:** See the ''attribute_list'' documentation under the [[#store|store]] API section.
+  ; ''attribute_delete''
+  : **Notes:** See the ''attribute_delete'' documentation under the [[#store|store]] API section.
+=== Notes ===
+  * <wrap tip>If you're using the API to create or update customer records, see our [[.:sso#best_practices|SSO Best Practices]].</wrap>
+  * 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 user-specific, though the store's configuration will be used by default if no hashing method is specified.
+    * 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'' //and// the ''customer_password_salt'' (if applicable per your store's [[.:customers#synchronizing_users_and_passwords|password hashing method]]. 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'', ''attribute_name_filter'', ''attribute_value_filter''
+    * ''custom_field_name_filter'', ''custom_field_value_filter'' allow filtering based on //transaction// (not product) custom fields (as entered on the checkout).
+    * ''category''
+    * ''sub_token''
+    * Use an asterisk (''*'') when filtering to do partial matches.
+  ; ''transaction_modify''
+  : **Required Fields:** ''transaction_id''
+  : **Accepts:** ''data_is_fed'' (0 or 1), ''hide_transaction'' (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)
+  ; ''transaction_datafeed''
+  : **Required Fields:** ''transaction_id''
+  : **Notes:** Triggers a refeed of the [[.:transaction_xml_datafeed|transaction datafeed]] for the specified transaction.
+  ; ''attribute_save''
+  : **Notes:** See the ''attribute_save'' documentation under the [[#store|store]] API section.
+  ; ''attribute_list''
+  : **Notes:** See the ''attribute_list'' documentation under the [[#store|store]] API section.
+  ; ''attribute_delete''
+  : **Notes:** See the ''attribute_delete'' documentation under the [[#store|store]] API section.
+  ==== 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'' This is a block of XML which will replace your existing subscription cart details. If you'd like to validate the XML on your server before sending it to us, you can use this XSD file: [[http://admin.foxycart.com/v/1.0.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)
+    * ''paypal_profile_id_filter'' (for PayPal Express Checkout recurring payments) You can enter 'all' to view all subscriptions with a PayPal Profile ID
+    * ''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''
+    * ''custom_field_name_filter'', ''custom_field_value_filter'' allow filtering based on //subscription's transaction// (not product) custom fields (as entered on the checkout).
+    * ''category''
+    * Use an asterisk (''*'') when filtering to do partial matches.
+  ; ''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.
+  ; ''attribute_save''
+  : **Notes:** See the ''attribute_save'' documentation under the [[#store|store]] API section.
+  ; ''attribute_list''
+  : **Notes:** See the ''attribute_list'' documentation under the [[#store|store]] API section.
+  ; ''attribute_delete''
+  : **Notes:** See the ''attribute_delete'' documentation under the [[#store|store]] API section.
+==== 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.
+=== Examples ===
+Here's an example **to retrieve a transaction**:
+<code>
+curl -d "api_token=PUT_YOUR_API_KEY_HERE&api_action=transaction_get&transaction_id=1234567890" https://example.foxycart.com/api
+</code>
+And here's how **to refeed the [[.:subscription_xml_datafeed|subscription XML datafeed]]**:
+<code>
+curl -d "api_token=PUT_YOUR_API_KEY_HERE&api_action=subscription_datafeed" https://example.foxycart.com/api
+</code>
+And how **to change a customer's email address**:
+<code bash>
+# First, run this to get the customer ID based on the email:
+curl -d "api_token=PUT_YOUR_API_KEY_HERE&api_action=customer_get&customer_email=john.doe@example.com" https://example.foxycart.com/api
+# Then once you have the ID, enter the ID and the _new_ email address. Below we assume the ID is 193
+curl -d "api_token=PUT_YOUR_API_KEY_HERE&api_action=customer_save&customer_id=193&customer_email=john.doh@example.com" https://example.foxycart.com/api
+</code>

Differences

Page Tools

Site Tools

User Tools