A split shipping web form allows users to populate shipping options for each cart item. The shippingGroupRelationships property (which is an observable array) captures the split shipping options for each cart item. Each instance of a ShippingGroupRelationships object associates a quantity of cart item with a given shipping address and shipping method. A single cart item can have several ShippingGroupRelationships instances, allowing the cart item to be split across several shipping groups.

Quantity field

The Quantity field allows the shopper to specify the portion of cart item to be associated with a given shipping group. The following code shows a sample UI binding pattern for this feature:

<!-- ko foreach: cart().items -->
  <!-- ko foreach: shippingGroupRelationships -->
    <input type="number" name="quantity" class="form-control" data-bind="
      value: quantity,
      event: {change: $parents[1].priceSplitShippingCartForCheckout}">
  <!-- /ko -->
<!-- /ko -->

Note: A change of Quantity will cause the widget to make a pricing call, provided the split shipping form is complete and valid.

Shipping Address field

The Shipping Address field allows the shopper to select a shipping address for the specified quantity of the cart item. The following code shows a sample UI binding pattern for this feature:

<!-- ko foreach: cart().items -->
  <!-- ko foreach: shippingGroupRelationships -->
    <select
      class="form-control"
      name="shippingAddress"
      data-bind="options: $parents[1].user().shippingAddressBook(),
                 optionsText: $parents[1].getOptionTextForAddress,
                 value: shippingAddress,
                 optionsCaption: 'Select shipping address',
                 event: {change: $parents[1].lookupShippingOptions}">
    </select>
  <!-- /ko -->
<!-- /ko -->

Shipping Address options should be retrieved from the profile’s shipping address book so that updates to the shipping address book will automatically be reflected in the options list. A change of Shipping Address must trigger a method in your widget that makes an AJAX service call to retrieve the valid shipping options for the selected address and product. The product ID must be passed in this call because some products may have a shipping surcharge and not all shipping methods can be used for products with surcharges.

Shipping Method field

The Shipping Method field allows the shopper to select a shipping method for the specified quantity of the cart item. The following code shows a sample UI binding pattern for this feature:

<!-- ko foreach: cart().items -->
  <!-- ko foreach: shippingGroupRelationships -->
    <select
      class="form-control"
       name="shippingMethod"
       data-bind="options: shippingOptions,
                  optionsText: 'displayName',
                  value: shippingMethod,
                  optionsCaption: 'Select shipping method',
                  enable: shippingAddress,
                  event: {change: $parents[1].priceSplitShippingCartForCheckout}">
    </select>
  <!-- /ko -->
<!-- /ko -->

The Shipping Method options displayed to the shopper must be populated by a method in your widget that makes an AJAX service call to retrieve the valid shipping options for the selected address. A change of Shipping Address should trigger this method.

A change of Shipping Method should cause the widget to make a pricing call, provided the split shipping form is complete and valid.

Split Items button

The Split Items button creates another shipping group relationship instance for this cart item, allowing the same cart item to be associated with more than one shipping group. The following code shows a sample UI binding pattern for this feature:

<!-- ko foreach: cart().items -->
  <!-- ko if: $parent.canAddShippingGroupRelationship($parent) -->
    <button class="btn btn-link" data-bind="click: addShippingGroupRelationship">
      Split items
    </button>
  <!-- /ko -->
<!-- /ko -->

It is only possible to split a cart item if the cart item quantity is greater than shippingGroupRelartionships.length.

Remove Item (X) button

The Remove Item button, shown as an X in the sample UI displayed in this section, removes a shipping group relationship instance. The following code shows a sample UI binding pattern for this feature:

<!-- ko foreach: cart().items -->
  <!-- ko foreach: shippingGroupRelationships -->
    <button class="btn btn-sm btn-link" data-bind="click:
       parents[1].removeShippingGroupRelationship.bind($parent)">
      <span class="glyphicon glyphicon-remove"></span>
    </button>
  <!-- /ko -->
<!-- /ko -->

The removeShippingGroupRelationship method, used in the click binding above, is a widget method and not the CartItem.removeShippingGroupRelationship method. It does, however, delegate to CartItem.removeShippingGroupRelationship, and also makes a pricing call, provided the split shipping form is complete and valid.

Add Address button

The Add Address button opens an address form where a shopper can save a new address to his profile address book. Once created, the new address will automatically appear in the Shipping Address options in the split shipping form. Apart from the inclusion of an alias field, no new address management APIs are required for split shipping. Re-using existing address management functionality is wholly sufficient to for this purpose.

The following illustration shows what an Add Address form might look like with fields for name, address, and phone number information. Note the addition of the Alias field.

ShippingGroupsRelationships array validation

The shippingGroupRelationships property has two predefined custom Knockout validators:

The above validators are computed automatically. The illustration below shows an error message that indicates to the shopper when a validation has failed.

To output the error message on screen, use the validationMessage binding shown below:

<!-- ko foreach: cart().items -->
  <div class="text-danger" data-bind="validationMessage:
   shippingGroupRelationships" role="alert"></div>
<!-- /ko -->