Method Definition

Method Signature	`String[] applyCoupons(String[] couponCodes);`
Description	Applies multiple coupons to the cart.
Result	String[] - The errors associated with applying the coupon code. These could range from invalid coupon codes to coupon conflicts. If this array contains any values then you should display them to the customer. Even if the errors array contained something the global cart variable is updated automatically.
As Of	Version 1.2.1, Version 2.0.4

Discussion

Make the remote call
Check to see if the result is non-null. If it is not, it will be an array of errors. Display those errors to the customer.

Examples

As with all Checkout API examples, remember to install the relay script on your local web server before attempting to run these examples. Browsers will not allow cross site scripting.
For more information, please see the discussion on XHR issues.

There are two attachments to this page containing working examples for applyCoupons.
The html is also listed below.

Version 1 applyCoupons Example

apply_coupons_1.2.1.html

Checkout API v1.2.1

<html>
<head>
  <script type='text/javascript' src='js/jquery-1.4.2.min.js'></script>
  <script type='text/javascript' src='js/jquery.json-2.2.min.js'></script>
  <script type='text/javascript' src='js/checkoutapi-1.2.1.js'></script>

  <script type='text/javascript'>

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

    window.onload = function() {
      log('initializing checkout');
      initializeCheckoutAPI({merchantId: "DEMO", secureHostName:'secure.ultracart.com', callbackUrl:'http://www.mystore.com/proxy.php', debugMode:true, verboseAjax:true});
      log('getting cart instance');
      getCartInstance();
    };

    function addCoupons() {
      var coupon1 = document.getElementById('coupon1');
      var coupon2 = document.getElementById('coupon2');
      var coupon3 = document.getElementById('coupon3');

      var coupons = [];
      if (coupon1 && coupon1.value) {
        coupons.push(coupon1.value.trim());
      }
      if (coupon2 && coupon2.value) {
        coupons.push(coupon2.value.trim());
      }
      if (coupon3 && coupon3.value) {
        coupons.push(coupon3.value.trim());
      }

      log('sending these coupons => ' + jQuery.toJSON(coupons));

      //Method 1: Asynchronously

      applyCoupons(coupons, {async:true, onComplete:function(result) {
            if (result == null) {
              log('result of remote call was null. something went wrong on the server.');
            } else {
              if (result.errors) {
                for (var i = 0; i < result.errors.length; i++) {
                  log('err msg:' + result.errors[i]);
                }
              }

              if (result.cart.coupons) {
                for (var j = 0; j < result.cart.coupons.length; j++) {
                  log('coupons in cart => ' + jQuery.toJSON(result.cart.coupons));
                }
              }
            }
          }});


      //Method 2: Synchronous
      /*
      var result = applyCoupons(coupons);
      if (result == null) {
        log('result of remote call was null. something went wrong on the server.');
      } else {
        if (result) {
          for (var i = 0; i < result.length; i++) {
            log('err msg:' + result[i]);
          }
        }

        if (cart.coupons) {
          for (var j = 0; j < cart.coupons.length; j++) {
            log('coupons in cart => ' + jQuery.toJSON(cart.coupons));
          }
        }
      }
      */

    }

    function log(msg) {
      var div = document.getElementById('log');
      var txtNode = document.createTextNode(msg);
      var br = document.createElement('br');
      div.appendChild(txtNode);
      div.appendChild(br);
    }

  </script>
</head>
<body>

<table>
  <tr>
    <td>Coupon 1:</td>
    <td><input type='text' id='coupon1' value='afa'/></td>
  </tr>
  <tr>
    <td>Coupon 2:</td>
    <td><input type='text' id='coupon2' value='1BONE'/></td>
  </tr>
  <tr>
    <td>Coupon 3:</td>
    <td><input type='text' id='coupon3' value='5OFF'/></td>
  </tr>
  <tr>
    <td colspan='2'><input type='button' value='Add Coupons' onclick='addCoupons()'/></td>
  </tr>
</table>
<div id='log' style='margin-top:20px;'>
  <div style='font-weight:bold'>Log Events Will Appear Below:</div>
</div>


</body>
</html>

Version 2 applyCoupons Example

apply_coupons_2.0.4.html

Checkout API v2.0.4

<html>
<head>
  <script type='text/javascript' src='js/jquery-1.4.2.min.js'></script>
  <script type='text/javascript' src='js/jquery.json-2.2.min.js'></script>
  <script type='text/javascript' src='js/checkoutapi-2.0.4.js'></script>

  <script type='text/javascript'>

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


    var merchantCartConfig =
    {
      merchantId: "DEMO",
      screenBrandingThemeCode: 'DFLT', // doesn't affect these pages, but will determine how receipt and upsell pages appear.
      isCheckoutPage: false, // if true, additional code is run during init() to populate shipping methods and such.  This must
                            // be true if you are collecting address information, displaying shipping, or finalizing an order.
      checkoutSite: 'secure.ultracart.com', // this site is only used during checkout. You may omit this, and checkout will proceed to secure.ultracart.com
                                          // if you provide a value, it must be an SSL alias that points to secure.ultracart.com (Custom SSL Certificate)
                                          // if isCheckoutPage = false, this value doesn't matter.

      remoteApiUrl: location.protocol + "//" + location.hostname + "/proxy.php",
                                                              // this url is used for all remote calls. It may point to secure.ultracart.com, a custom SSL site, or your own proxy script.
                                                             // you may omit this, and the default url is used (points to a path at secure.ultracart.com)
                                                             // see the top of the checkoutapi script for the path info if you have a custom ssl cert.
      debugMode: true,
      verboseAjax: true
    };

    jQuery('document').ready(function(){
      log('initializing checkout');
      ultraCart.init(merchantCartConfig);
    });

    function addCoupons() {
      var coupon1 = document.getElementById('coupon1');
      var coupon2 = document.getElementById('coupon2');
      var coupon3 = document.getElementById('coupon3');

      var coupons = [];
      if (coupon1 && coupon1.value) {
        coupons.push(coupon1.value.trim());
      }
      if (coupon2 && coupon2.value) {
        coupons.push(coupon2.value.trim());
      }
      if (coupon3 && coupon3.value) {
        coupons.push(coupon3.value.trim());
      }

      log('sending these coupons => ' + jQuery.toJSON(coupons));

      //Method 1: Synchronous
      log("BEGINNING SYNCH METHOD");
      var result = ultraCart.applyCoupons(coupons);
      if (result == null) {
        log('result of remote call was null. something went wrong on the server.');
      } else {
        if (result) {
          for (var i = 0; i < result.length; i++) {
            log('err msg:' + result[i]);
          }
        }

        var cart = ultraCart.getCart();
        if (cart.coupons) {
          for (var j = 0; j < cart.coupons.length; j++) {
            log('coupons in cart => ' + jQuery.toJSON(cart.coupons));
          }
        }
      }

      //Method 2: Asynchronously
      log("BEGINNING ASYNC METHOD");
      ultraCart.applyCoupons(coupons, {async:true, onComplete:function(result) {
            if (result == null) {
              log('result of remote call was null. something went wrong on the server.');
            } else {
              if (result.errors) {
                for (var i = 0; i < result.errors.length; i++) {
                  log('err msg:' + result.errors[i]);
                }
              }

              if (result.cart.coupons) {
                for (var j = 0; j < result.cart.coupons.length; j++) {
                  log('coupons in cart => ' + jQuery.toJSON(result.cart.coupons));
                }
              }
            }
          }});




    }

    function log(msg) {
      var div = document.getElementById('log');
      var txtNode = document.createTextNode(msg);
      var br = document.createElement('br');
      div.appendChild(txtNode);
      div.appendChild(br);
    }

  </script>
</head>
<body>

<table>
  <tr>
    <td>Coupon 1:</td>
    <td><input type='text' id='coupon1' value='afa'/></td>
  </tr>
  <tr>
    <td>Coupon 2:</td>
    <td><input type='text' id='coupon2' value='1BONE'/></td>
  </tr>
  <tr>
    <td>Coupon 3:</td>
    <td><input type='text' id='coupon3' value='5OFF'/></td>
  </tr>
  <tr>
    <td colspan='2'><input type='button' value='Add Coupons' onclick='addCoupons()'/></td>
  </tr>
</table>
<div id='log' style='margin-top:20px;'>
  <div style='font-weight:bold'>Log Events Will Appear Below:</div>
</div>


</body>
</html>

UltraCart Documentation

applyCoupons - Checkout API Method

Method Definition

Discussion

Examples

Version 1 applyCoupons Example

Version 2 applyCoupons Example