JSON stands for JavaScript Object Notation ¹⁾, and can be thought of as a very flexible method to store data. Conceptually it is similar to XML, but since it's actually a javascript object it's trivially easy to work with in javascript (whereas XML requires much more work to process by javascript).

FoxyCart's JSON includes the details of the customers cart, as well as store configuration settings and other variables relating to both the customer and the page. For an overview of all the different variables that are included within the FoxyCart JSON, see the Templates View Data page.

JSONP is a magical tool that allows for relatively easy cross-domain javascript calls, which is impossible in most other ways (barring HTML5 functionality). We recommend getting a thorough understanding, but the basic idea is this: You make a call to an endpoint (your FoxyCart cart) and you get back JSON wrapped inside of a function call. The reason for the function is so that your javascript can actually do something with the JSON you retrieve.

Triggering a JSONP call to the cart is easy in 2.0 - there's a simple helper to make the request and get back the JSON you need to update things on your end. All you need to do is pass it a URL like this:

FC.client.request('https://'+FC.settings.storedomain+'/cart?name=My+Product&price=20');

That function call will add a product called “My Product” to the cart priced at $20. On completion, client.updateJSON(); is called, as well as FC.session.initialize() or FC.session.reset() to ensure the correct session ID and cookie are set.

If you need to perform some custom actions after the request is completed though, you simply append a done() handler to the end, like this:

FC.client.request('https://'+FC.settings.storedomain+'/cart?name=My+Product&price=20').done(function(dataJSON) {
  // Perform custom code here 
});

In that example, dataJSON will contain the up to date version of the JSON object, which will also match FC.json.

If you want to render the cart or checkout after a request, put the render() function call in the done() callback, like this:

FC.client.request('https://'+FC.settings.storedomain+'/cart?empty=true').done(function() {
            FC[FC.json.context].render();
            });

If you want to update the quantity of a specific item, send this with the add to cart URL:

&cart=update&quantity=<new quantity>&id=<product id from json>

If you want to modify multiple quantities at once you can prefix the separate products with a number prefix, similar to adding multiple products to the cart at the same time. Note that if you take this approach you must start at 1 and count up from there.

&cart=update&1:quantity=0&1:id=<product id from json>&2:quantity=0&2:id=<product id from json>

Note that the cart=update is required for these operations to function.

Unfortunately, modifying products in the cart beyond the quantity is not currently possible.

If you want to add a coupon code, affiliate tracking value, member group, user ID, or any other value to your visitor's FoxyCart session automatically and in the background you could use something like this:

FC.client.on('ready.done', function () {
  if ($.isEmptyObject(FC.json.coupons)) {
    FC.client.request('https://'+FC.settings.storedomain+'/cart?coupon=YOUR_COUPON_CODE').done(function() {
        if (FC.util.hasError('coupon')) {
            FC.util.removeError('coupon');
        }
    });
  }
});

This function hooks into the ready.done event to ensure that the FoxyCart JSON object has been loaded, and checks if the coupons object is empty. If it is, it then triggers the request to add a coupon to the cart, and removes any coupon errors in case it's expired or removed. This is just a simple example, but hopefully gives you an idea of how to get started.

If you want to run code like that on pageload, you'd need to wrap it in the FC.onLoad() wrapper, like this:

var FC = FC || {};
FC.onLoad = function () {
	FC.client.on('ready.done', function () {
		FC.client.request('https://'+FC.settings.storedomain+'/cart?h:foo=bar');
	});
};

The most critical thing about making successful JSON(P) calls to FoxyCart is remembering to include the fcsid (FoxyCart Session ID) in the request. You can get this from FC.json.session_name and FC.json.session_id, or the complete URL parameter like this like fcsid=nf0237u4ng0ed7 through FC.session.get():

var url = "https://" + FC.settings.storedomain + "/cart?name=My+Product&price=25&" + FC.session.get();