You are here: Order System > Checkout Process > Shipping Options

Shipping Options

Overview

In EPiServer Commerce the shipping model supports multiple shipments per cart and per order. Each shipment (represented by the Shipment class) contains one or more LineItem references, a shipping address, a shipping method, and a rate. The lineitems, shipping address, and shipping method can all determine the shipping rate. Each shipping method is associated with a shipping option/provider. Shipping providers can be associated with multiple shipping method. The shipping provider contains the logic to use whatever required information is needed (line item properties like weight or size, other order properties, the shipping address, and/or any other properties or external services your implementation includes) to determine the shipping rate for a shipment. Shipping methods contain shipping scenarios representing different pricing for distinct jurisdictions (location which can be as general as a country and specific as a zip code) and shipment weight scenarios.

EPiServer Commerce includes two shipping options/providers which are used by two shipping methods. One provider/method is a flat fee shipping provider; in this case, all of the shipping charges are the same regardless of the Cart contents or shipping address. The other is a WeightJurisdiction provider and method which provides shipping rates for shipments based on the shipping address and weight of the SKUs in the package. See these two links to learn more about configuring the existing shipping providers and methods included with EPiServer Commerce:

Shipping Providers

Shipping Methods

The provider model allows you to also create and incorporate your own shipping providers and methods as well.

Key classes and files

Shipment.cs represents the class in an order for each shipment in the order.

ShippingModule.ascx provides an example implementation of using the shipping API to retrieve available shipping methods for user display and calling the shipping provider interface to determine the cost for each shipping method.

IShippingGateway.cs is the interface all shipping gateways must implement to be incorporated into EPiServer Commerce.

ShippingManager.cs provides access to shipping methods, shipping method cases, package information.

CountryManager.cs provides access to the countries defined as shipping jurisdictions.

Implementation Details

To retrieve available shipping methods, use the ShippingManager class, GetShippingMethods method. Because shipping methods are specific to a local, the language name needs to be provided when calling this method. An example of the code to retrieve these methods ca be found in the ShippingModule.ascx (BindShippingRates() method) is below. The ShippingModule.ascx provides an example of retrieving and displaying the available shipping methods for a cart with the associated rates.

ShippingMethodDto methods = ShippingManager.GetShippingMethods(SiteContext.Current.LanguageName);


The ShippingMethodDto typed dataset provides several tables that are useful for different aspects of shipment option display:

In Commerce Manager, a shipping method can also be restricted to not be available to configured restricted countries and regions/states associated with the shipping method. In addition, a shipping method can be restricted for certain types of payment. To match, for example, a country from a shipping address with the restricted countries associated with a shipping method, you need to know the ids of the shipping country. To retrieve this information, use the CountryManager, as in this example:

CountryDto country = CountryManager.GetCountry(OrderAddress.CountryCode, true);
    if (country.Country != null && country.Country.Rows.Count > 0)
    {
        shippingCountryId = country.Country[0].CountryId;
        countryFound = true;
    }

The CountryManager also returns regions. Regions map to either an addresses State or RegionCode properties.

An example of iterating through a shipping method's restricted countries is:

//first check the restricted countries
    ShippingMethodDto.ShippingCountryRow[] paymentCountryRestrictions = method.GetShippingCountryRows();
    if (paymentCountryRestrictions != null && paymentCountryRestrictions.Length > 0)
    {
        foreach (ShippingMethodDto.ShippingCountryRow restrictedCountryRow in paymentCountryRestrictions)
        {
            if (restrictedCountryRow.CountryId == shippingCountryId)
            {
                isRestricted = true;
                break;
            }
        }
    }

 

To retrieve the shipping rate for a shipping method, given the order's address and items in the cart, you need to call the shipping provider's GetRate method (which is required by the IShippingGateway, an interface all shipping providers must implement). Here's an example of how to retrieve the shipping rate for each available shipment method with a particular cart:

foreach (ShippingMethodDto.ShippingMethodRow row in shippingRows)
    {
        //The ShippingMethodDto maintains relationships between rows. This means that a ShippingMethodRow contains
        //a reference to the parent shipping option/provider row. This allows us to retrieve the class name
        //for the shipping provider so that we can instantiate an instance of the provider and execute the
        //GetRate method for a particular cart.
        Type type = Type.GetType(row.ShippingOptionRow.ClassName);
        if (type == null)
        {
            throw new TypeInitializationException(row.ShippingOptionRow.ClassName, null);
        }
 
        string message = String.Empty;
        IShippingGateway provider = (IShippingGateway)Activator.CreateInstance(type);
 
        //now we retrieve all of the line items in the cart which are associated with the same shipping address
        List<LineItem> items = new List<LineItem>();
        foreach(LineItem lineItem in CartHelper.LineItems)
        {
            if(lineItem.ShippingAddressId == shipmentAddress.Name.ToString())
                items.Add(lineItem);
        }
 
        //now call the GetRate method to retrieve the rate for this shipment
        if (items.Count > 0)
            ShippingRate rate = provider.GetRate(row.ShippingMethodId, items.ToArray(), ref message);
    }

 

Namespaces

Mediachase.SampleSite.Templates.Everything.BusinessControls.CheckoutControls.SharedModules contains the ShippingModule.ascx.

Mediachase.Commerce.Orders contains the Shipment class.

Mediachase.Commerce.Orders.Managers contains the ShippingManager and CountryManager classes.

Creating a Shipping Gateway

 


Version: EPiServer Commerce 1 R2 SP2| Last updated: 2012-06-29 | Copyright © EPiServer AB | Send feedback to us