CartItemOption

This object represents an option on one of the items in the shopping cart. See item configuration for details on managing items.

Local currency fields are only available to the REST API.

Field	Type	Description	Required when adding an item to cart
name	string	Option name	YES
selectedValue	string	Seleted value on the option	YES

costPerLetter costPerLetterLocalized costPerLetterLocalizedFormatted	number number string	Fee per letter specified in a single or multiline option	NO
costPerLine costPerLineLocalized costPerLineLocalizedFormatted	number	Fee per line of text specified in a multiline option	NO
costIfSpecified costIfSpecifiedLocalized costIfSpecifiedLocalizedFormatted	number	Fee if specified	NO
ignoreIfDefault	boolean	True if option will be ignored on the order if the default value is selected	NO
label	label	Option display label	NO
oneTimeFee	boolean	True if the fee is only applied once (irregardless of quantity)	NO
optionOid	integer	A unique option object identifier. This is provided to easy debugging with UltraCart premium support.	NO
required	boolean	True if required	NO
type	string	Type of option. See OPTION_TYPE_ constants in the checkoutapi.js for a list of valid values.	NO
values	CartItemOptionValue[ ]	Values that the customer can select from for radio or drop down style options	NO

Short Example of creating a CartItem with options:

      // create my cart item.  just the bare required properties: itemId, quantity.
      // see: http://docs.ultracart.com/display/ucdoc/CartItem
      var item = {'itemId': myItem.itemId, 'quantity': 1};
      item.options = []; // create the (initially empty) options placeholder.
      var opt = {'name': 'Option1', 'selectedValue': 'Large'};
      item.options.push(opt);
      opt = {'name': 'Option2', 'selectedValue': 'Skittles'};
      item.options.push(opt);
      // add items takes an array.  I've only got one item, so I'll surround it by brackets to create a single element array.
      ultraCart.addItems([item]);

Full example of downloading an item from the server, creating select boxes for it, and then adding an item with options to a cart:
(You may download this example as a zip file. See this page's attachments.)

<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
<html>
<head>
  <meta http-equiv="Content-Type" content="text/html; charset=UTF-8">
  <script type='text/javascript' src='js/jquery-1.7.2.js'></script>
  <script type='text/javascript' src='js/jquery.json-2.2.min.js'></script>
  <script type='text/javascript' src='js/checkoutapi-2.1.2.js'></script>

  <style type='text/css'>
    #log{
      font-family: Courier, Serif;
      font-size: 0.7em;
    }
  </style>

  <script type='text/javascript'>

    if (typeof String.prototype.trim === 'undefined') {
      String.prototype.trim = function() {
        return this.replace(/^\s+|\s+$/g, '');
      };
    }

    var myItem = null; // this will hold a reference to my item after it is loaded.

    var merchantCartConfig =
    {
      merchantId: "DEMO",
      isCheckoutPage: false,
      checkoutSite: 'secure.ultracart.com',
      // remoteApiUrl: 'http://staging.moraicecream.com/wp-content/themes/minimatica/ultracart-scripts/' + 'proxy.php',
      remoteApiUrl: location.protocol + "//" + location.hostname + "/proxy.php",
      debugMode: true,
      verboseAjax: true
    };

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

      loadShirtOptions();

//      ultraCart.clearItems();
//      var Options = [
//        {name: "Michael Flavor", label: "Michael Label"},
//        {name:
//            "Michael Flavor", label: "Michael Label"},
//        {name: "Michael Flavor", label:
//            "Michael Label"},
//        {name: "Michael Flavor", label: "Michael Label"}
//      ];
//      var itemToAdd = {itemId: '001', quantity: 1, options:Options};
//      var errors = ultraCart.addItems([itemToAdd]);
//      console.log(errors);
//      var cart = ultraCart.getCart();
//      console.log(jQuery.toJSON(cart.items));

    });


    function sortOptionValues(a, b) {
      // I'm sorting option values on their displayOrder property.
      // see: http://docs.ultracart.com/display/ucdoc/ItemOptionValue
      return (a.displayOrder - b.displayOrder);
    }


    function loadShirtOptions() {
      var shirt = ultraCart.getItem('TSHIRT', {async:true,onComplete:function(result) {

            // when the shirt item returns, load up some options with it.
            if (result) {
              myItem = result;
              log('Loading options for item [' + result.itemId + ']');

              // see: http://docs.ultracart.com/display/ucdoc/Item
              var shirtOptions = result.options;
              if (shirtOptions && shirtOptions.length) {

                // loop through each option and create a row in the table containing a drop down box with options
                var html = '';
                for (var i = 0; i < shirtOptions.length; i++) {
                  // see: http://docs.ultracart.com/display/ucdoc/ItemOption
                  var opt = shirtOptions[i];
                  log("&nbsp;&nbsp;&nbsp;Loading item option: [" + opt.name + "], label: [" + opt.label + "]");

                  html += '<tr><td>' + opt.label + '<\/td>';
                  html += '<td><select class="item_option" name="' + opt.name + '">';

                  opt.values.sort(sortOptionValues);
                  for (var j = 0; j < opt.values.length; j++) {
                    // see: http://docs.ultracart.com/display/ucdoc/ItemOptionValue
                    var val = opt.values[j];
                    log("&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;Loading option value: [" + val.value + "], is default: [" + val.defaultValue + "]");
                    html += '<option value="' + val.value + '"' + (val.defaultValue ? " selected='selected'" : "") + '>' + val.value + '<\/option>';
                  }

                  html += "<\/select>";
                  html += '<\/td><\/tr>';

                } // end of for-each-option-loop

                jQuery('#options_table').html(html);

              } // end of if-result-has-options
            } // end of if-result-is-value
          } // end of onComplete
          } // end of opts hash
      );
    }

    function addShirt() {

      // Pay Attention Here!  We're adding to the cart.
      // The cart item objects are different from regular items.  The regular items are concerned about displaying
      // information.  The cart item objects are concerned about maintain cart state.
      // So we've switched from Item => CartItem.
      // ItemOption => CartItemOption


      // create my cart item.  just the bare required properties: itemId, quantity.
      // see: http://docs.ultracart.com/display/ucdoc/CartItem
      var item = {'itemId': myItem.itemId, 'quantity': 1};
      item.options = []; // create the (initially empty) options placeholder.

      // get all the options and add the selected values to my item.
      // each select field has a class of 'item_option'.  Use that to find them all.
      jQuery('.item_option').each(function(idx, el){

        // the *only* things we care about with the items are the name and the selected value.
        // the server doesn't care about the label, etc.
        // step 1. get the name of the element.
        // step 2. get the selected value (jQuery makes this easy)
        // add the item to the array.
        var $el = jQuery(el); // wrap the element in a jQuery object for easy value retrieval.

        // see: http://docs.ultracart.com/display/ucdoc/CartItemOption
        var opt = {'name': el.name, 'selectedValue': $el.val()};
        item.options.push(opt);
      });

      // add items takes an array.  I've only got one item, so I'll surround it by brackets to create a single element array.
      ultraCart.addItems([item]);

      log("Item was added to the cart.");
      log("run this in your browser console: ultraCart.getCart().items");
    }

    function log(msg) {
      jQuery('#log').append(msg).append("<br />");
    }

  </script>
</head>
<body>

<h4>Add a T-SHIRT to Your Cart</h4>
<table id='options_table'>
  <tr>
    <td colspan='2'><em>loading options...please wait.</em></td>
  </tr>
</table>
<br />
<input type='button' value='Add Shirt' onclick='addShirt()'/>

<div id='log' style='margin-top:20px;'>
  <div style='font-weight:bold'>Log Events Will Appear Below:</div>
</div>


</body>
</html>