Hide menu Last updated: Mar 02 2017
Area: Episerver Commerce Applies to versions: 10 and higher
Other versions:

Shipping

This topic describes the shipping features of Episerver Commerce, including shipping methods, providers and gateways. Episerver Commerce includes two shipping options/providers which are used by two shipping methods. The shipping model supports multiple shipments per cart and per order. The provider model lets you also create and incorporate your own shipping providers and methods.

Classes in this topic are available in the following namespaces:

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
    • calling the shipping provider interface to determine the cost of each shipping method
  • IShippingGateway.cs. The interface shipping gateways must implement to be incorporated into ECF.
  • ShippingManager.cs. Provides access to shipping methods, shipping method cases, and package information.
  • CountryManager.cs. Provides access to countries defined as shipping jurisdictions.

Note: The implementation of IShippingGateway and IShippingPlugin requires a constructor which takes IMarket as a parameter.

How it works

  • 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 determine the shipping rate.
  • Each shipping method is associated with a shipping option/provider. You can associate shipping providers with multiple shipping methods.
  • 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 a shipment's shipping rate.
  • Shipping methods contain shipping scenarios representing different pricing for distinct jurisdictions (location can be as general as a country and as specific as a zip code) and shipment weight scenarios.

Examples

To retrieve available shipping methods, use the ShippingManager class, GetShippingMethods method. Because shipping methods are specific to a locale, the language name needs to be provided when calling this method. You can find an example of code to retrieve these methods in the ShippingModule.ascx (BindShippingRates() method).

The ShippingModule.ascx provides an example of retrieving and displaying 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:

  • ShippingMethod. Contains a row of data for each shipping method. This contains data displayed in the Overview tab of Commerce Manager and the IDs for the shipping methods.
  • ShippingCountry. Contains a row for each restricted country associated for a shipping method.
  • ShippingRegion. Contains a row for each restricted state or region for a shipping method.
  • ShippingPaymentRestriction. Contains a row for each payment type restricted for a shipping method.
  • ShippingMethodCase. Contains a row of data for each shipping rate scenario for a shipping method. See the Parameters tab of the Default Shipping method to see the type of data stored.
  • ShippingOption. Contains a row of data for each shipping option/provider. You can see this information on the Overview tab of a shipping provider's definition.

A shipping method can also be restricted (that is, not 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.

Example: retrieve country shipping ID

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.

Example: iterating through a shipping method's restricted countries

//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. This is required by the IShippingGateway, an interface all shipping providers must implement.

Example: retrieving the shipping rate for each available shipment method with a 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);
}

Comments