The FoxyCart 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.

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. The API key is available from the “advanced” settings page in the FoxyCart administration, from the "store secret" value.

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:

<?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>

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

• NEW! 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_template_cache

Notes: This method will use our "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: This call should not be run on every pageload on your site. 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 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.9.0 at the launch of FoxyCart v1.1) 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:

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

That XML looks like this, pretty printed:

<attributes>
  <attribute>
    <name>foo</name>
    <value>bar</value>
  </attribute>
  <attribute>
    <name>isla</name>
    <value>pie</value>
  </attribute>
</attributes>

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_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 password hashing settings.
• customer_country should be considered required, and must be a valid 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
• address_id or address_name (address_name is the shipto name assigned to each multi-ship address (as specified in the add to cart), a customers default shipping address is recorded as “Me”)

Notes: Only applicable for stores using multi-ship.

customer_address_save

Required Fields:

• customer_id or customer_email
• address_id or address_name (address_name is the shipto name assigned to each multi-ship address (as specified in the add to cart), a customers default shipping address is recorded as “Me”)

Notes: Only applicable for stores using multi-ship.

Record Fields: address_name, shipto_first_name, shipto_last_name, shipto_company, shipto_address1, shipto_address2, shipto_city, shipto_state, shipto_postal_code, shipto_country

attribute_save

Notes: See the attribute_save documentation under the store API section.

attribute_list

Notes: See the attribute_list documentation under the store API section.

attribute_delete

Notes: See the attribute_delete documentation under the store API section.

• If you're using the API to create or update customer records, see our SSO Best Practices.
• 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 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.

transaction_get

Required Fields: transaction_id

transaction_list

Filter Options:

• transaction_date_filter_begin (YYYY-MM-DD), transaction_date_filter_end (YYYY-MM-DD)
• date_modified_filter_begin (YYYY-MM-DD), date_modified_filter_end (YYYY-MM-DD) (dates are modified when external IPN updates Amazon FPS transaction)
• 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_filter
• sub_token_filter
• 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 datafeed for the specified transaction.

transaction_sendemail

Required Fields: transaction_id

Notes: Triggers a resend of the transaction receipt email for the specified transaction.

attribute_save

Notes: See the attribute_save documentation under the store API section.

attribute_list

Notes: See the attribute_list documentation under the store API section.

attribute_delete

Notes: See the attribute_delete documentation under the store API section.

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. 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 (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: 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_filter
• 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 to your already configured XML datafeed endpoint.

attribute_save

Notes: See the attribute_save documentation under the store API section.

attribute_list

Notes: See the attribute_list documentation under the store API section.

attribute_delete

Notes: See the attribute_delete documentation under the store API section.

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 "<pre>";
var_dump($foxyResponse);
print "</pre>";

If you have difficulty with httparty or ActiveResource, try putting the POST request in the :body and not the :query.

You can always use 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 subscription XML datafeed:

curl -d "api_token=PUT_YOUR_API_KEY_HERE&api_action=subscription_datafeed" https://example.foxycart.com/api

And how to change a customer's email address:

# 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