UltraCart Advanced JavaScript Checkout API


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:

  1. assemble your configuration options, including assigning your 'render' functions as listeners to ultraCart events.
  2. pass your configuration to ultraCart.init()
  3. ultraCart.init() will retrieve (or create) the shopping cart, and then fire events as it progress.
  4. 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

Object Model

Object Model
Cart
CartCoupon
CartItem
CartItemAttribute
CartItemMultimedia
CartItemMultimediaThumbnail
CartItemOption
CartItemOptionValue
CartKitComponentOption
CheckoutHandoffResult
CheckoutTerms
CustomerProfile
CustomerProfileAddress
Distance
GiftSettings
GiftWrap
Item
ItemAttribute
ItemMultimedia
ItemMultimediaThumbnail
ItemOption
ItemOptionValue
ShippingEstimate
Weight

API Methods

API Methods
addItems
applyCoupon
applyGiftCertificate
backgroundUpdateCart
clearFinalizeAfter
clearItems
checkout
checkoutHandoff
checkoutHandoffOnCustomSSL
createCart
establishCustomerProfile
establishCustomerProfileImmediately
estimateShipping
getAdvertisingSources
getAllowedCountries
getCart
getCartInstance
getCartItemMultimediaThumbnail
getCheckoutTerms
getCustomerProfile
getGiftSettings
getItem
getItemMultimediaThumbnail
getItems
getItemsForCatalogGroup
getParameterValues
getParameterValues
getRelatedItems
getReturnPolicy
getStateProvinces
getStateProvinceCodes
getTaxCounties
googleCheckoutHandoff
googleCheckoutHandoffOnCustomSSL
initializeCheckoutApi
logError
loginCustomerProfile
logoutCustomerProfile
paypalHandoff
paypalHandoffOnCustomSSL
removeCoupon
removeGiftCertificate
removeItem
removeItems
resetCustomerProfilePassword
setFinalizeAfter
subscribeToAutoResponder
updateCart
updateCustomerProfile
updateItems
validate
validateAll
validateGiftCertificate

General Notes

Making an Asynchronous Call
Global Variables
Cookie Issues
Building a Custom Upsell After Sequence
XHR Issues and the Relay Script
Automatic Updating of the Global Cart Variable
Call Logging and Javascript Error Handling
Handling Reloads with Error Messages
Performance Considerations
Using JQuery with the Mootools Framework
Working with JSON Dates
A Warning About Shipping Costs after Item Changes