Written by UC Pro Services
Copyright© 2009-2011 BPS Info Solutions, Inc.

History

How it Was

Through the many years that UltraCart has been around we have found the customers have always wanted a wide variety of features in their checkout. UltraCart has been built to accommodate almost all the requests people have submitted, but they're represented in a standard way. The regular checkout is at least six pages long and the single page checkout is three pages long including the receipt and in progress page. This is necessary to accommodate all the different business rules associated with the large numbers of features.

The Problem

We found that most merchants would do a nice job branding up their checkout and choose either the single page checkout or regular checkout based upon their business scenario. We then started noticing that a new group of merchants started forming. These merchants either tried to heavily manipulate the screens on the checkout using CSS and JavaScript or created their own custom forms on their website that posted the information into the checkout process. There are two main drawbacks to this style of customization. For the merchants that used CSS and JavaScript to customize the checkout there always were inherent limitations as to how far they could take it. For merchants that built custom forms on their website they always dumped the customer into the normal checkout if there were any errors associated with the form.

The Solution

There had to be a better way to provide the merchant near complete flexibility to build whatever checkout best suits their business, and that's what the Javascript Checkout is. We've seen custom checkouts increase sales 15-20%. When that translates to six or seven figure sales increases, it's bad business sense to not pursue building one. The ROI on the development time required to build one can quickly be recorded.

Our solution was the JavaScript Checkout API.

The JavaScript Checkout API is a lightweight API that allows the web page to control the UltraCart shopping cart process. Merchants can develop almost any kind of checkout using the API. The API is built around popular cross-browser compatible frameworks like MooTools and JQuery to make sure it operates robustly and efficiently.

Version 3.0

Version 3.0 aims to be a lightweight REST interface. The feedback from version 2.0 was that it was too heavy of a framework. The documentation for version 3.0 lives here. Make sure to check out our GitHub page for checkout 3.0 located at https://www.ultracart.com/api/

Troubleshooting & Support

Troubleshooting and Support is provided to developers via our developer community forums on Github.com Join the conversion there.

Version 2.0

Version 2.0 is a complete overhaul of the structure of the checkout. The remote calls are the same. But version 2.0 no longer pollutes the global namespace. Version 2 is constructed using a module design pattern. This makes the ultraCart objet the only global object, and a singleton as well. Everything is accessed via the ultraCart variable. Also, the ultraCart object fires events which allow for easy page updates.

The basic program flow is:

assemble your configuration options, including assigning your 'render' functions as listeners to ultraCart events.
pass your configuration to ultraCart.init()
ultraCart.init() will retrieve (or create) the shopping cart, and then fire events as it progress.
You create html elements and bind them to functions which make ultraCart calls. As the calls execute, ultraCart knows which events to fire.

While the above is admittedly an indirect way of going about things, the result is a very pleasing experience.
As events happen, parts of your page automatically update themselves.

Change Log

Version	Date	Comments
2.0.4	Jun 22,2011	General Release
2.0.5	Jun 24,2011	Several methods, if called async, would not update cart variable with changes (it would be rare if those methods were called async given their nature, but still... fixed in 2.0.5
2.0.9	Oct 24,2011	Some minor bug fixes, added a method call that checks to setup to determine configuration errors right from the start. Helps diagnose issues.
2.0.9	Oct 24,2011	Added variations support to the js checkout

Object Model

version 2.0 uses the same object model as version 1.0, but is self contained within a single object to provide a more 'turn-key' solution. See the demo application for a good approximation of its abilities.
Its strength is event driven page management.
See the online demo for a test drive.

Here is a stripped down example showing the bare essentials of talking to UltraCart:

<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
    "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html>
<head>
  <script type='text/javascript' src='https://secure.ultracart.com/checkoutapi/jquery-1.4.2.min.js'></script>
  <script type='text/javascript' src='https://secure.ultracart.com/checkoutapi/jquery.json-2.2.min.js'></script>
  <script type='text/javascript' src='https://secure.ultracart.com/checkoutapi/checkoutapi-2.0.12.js'></script>

  <script type='text/javascript'>
    var merchantCartConfig =
    {
      merchantId: "DEMO",
      isCheckoutPage: true,
      remoteApiUrl:  location.protocol + "//" + location.hostname + "/proxy.php",
      debugMode: true,
      verboseAjax: true,
      listeners:{
        "cartready":[updatePage]
      }
    };

    function updatePage() {
      var cart = ultraCart.getCart();
      jQuery('#sessionId').html(cart.cartId);
      jQuery('#itemCount').html(cart.items.length);
    }

    jQuery(document).ready(function() {
      ultraCart.init(merchantCartConfig);
    });

  </script>
</head>
<body>
Hello. Your shopping cart session id is: <span id='sessionId'></span>.<br/>
You have <span id='itemCount'></span> item(s) in your cart.<br/>
<br/>
Since debugMode and verboseMode is set, you should open your browsers console (firebug, etc) and check out the
debugging.

</body>
</html>

Prerequisite skills for using the API
Support
Setting up the API on your page

Version 1.1

Version 1 is still widely popular, but is no longer being developed.

Change Log

Version	Date	Comments
1.2.1	Jun 22,2011	Added `applyCoupons` code
1.2.1	Oct 24,2011	Added variations support to the js checkout

Browser not supported