Table of Contents
The FoxyCart API
NOTE: This XML API will be deprecated Though this legacy XML API works and will continue to function in the future, it will not see any new functionality. We recommend any new integrations are built on top of our new Hypermedia API: https://api.foxycart.com/
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. 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>
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
- NEW! All
_list
methods now support wildcard searching. Use an asterisk (*
) when filtering to do partial matches. - All
_list
methods support apagination_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
, andpagination_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 "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
: Acceptscart
,checkout
,receipt
,html_email
,email
- Optional Fields:
template_url
: A complete, well-formed URL, such ashttp://example.tld/path/to/template.ext
. If omitted, the existing URL stored in the admin (for thetemplate_type
as passed in) will be used.email_subject
: A text string to be used for email receipts. Only valid iftemplate_type
ishtml_email
oremail
.send_html_email
: Accepts a1
or0
. To use text only email receipts, send a0
. To have both text and html emails sent, set to1
. Note that this corresponds to the radio button in the admin. If this is a1
, you should have ahtml_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
: Acceptsnone
andjquery
. If you're already loading jQuery elsewhere in your site, you can set this tonone
and the code returned will not include jQuery. Note that thefoxycart.js
files do require jQuery.cart_type
: Acceptsnone
,colorbox
. This parameter determines how the cart will function by default. If you don't want the default Colorbox-powered cart, set this tonone
.
- Response:
code_block
: The appropriate<script>
and<style>
tags are returned inside aCDATA
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
, orsubscription
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
: Acceptstransaction
,customer
,subscription
identifier
: Accepts a validtransaction_id
,customer_id
,sub_token
,sub_token_url
(depending on what was passed in as thetype
)
- Optional Fields:
append
: Accepts0
(default),1
. If1
, thevalue
will be appended to the existingvalue
for any matchedname
attributes. If0
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, allattribute
values for this named/value pair will be deleted. Ifname
is not passed in,all
is required.all
: Accepts0
(default),1
. If1
is passed in, all attributes (ie. all names) will be removed for the specified record. Ifall
is not set to1
, aname
value will be required. If bothall
and aname
are passed in, theall
will take precedence.
-
category_list
- Required Fields: None.
- Response: XML with
id
,code
,description
, andproduct_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
, andupload_date
for all downloadables.
Customer
Methods
-
customer_get
- Required Fields:
customer_id
orcustomer_email
- Notes: Cannot be used to retrieve guest customer accounts.
-
customer_save
- Required Fields:
customer_id
orcustomer_email
customer_password
orcustomer_password_hash
is required for acustomer_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 acustomer_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
orcustomer_email
address_id
oraddress_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
orcustomer_email
address_id
oraddress_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.
Notes
- 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 incustomer_password_hash
and thecustomer_password_salt
(if applicable per your store's password hashing method. Whether you pass in acustomer_password
or acustomer_password_hash
, the end result is the same: A hashed password will be returned on_get
requests for thecustomer_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)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.
Subscriptions
-
subscription_get
- Required Fields:
sub_token
(either the token by itself or the completesub_token
URL) -
subscription_cancel
- Required Fields:
sub_token
(either the token by itself or the completesub_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 thesubscription_modify
method. -
subscription_modify
- Required Fields:
sub_token
(either the token by itself or the completesub_token
URL) - Accepts:
start_date
(YYYY-MM-DD) (Thestart_date
is somewhat historical, and indicates the very first date a subscription processed.)end_date
(YYYY-MM-DD)next_transaction_date
(YYYY-MM-DD) (Thenext_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 as1
) 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 IDlast_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 theapi_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.
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 "<pre>"; var_dump($foxyResponse); print "</pre>";
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 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.
Examples
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