Shipping (dev)

Optimizely Commerce Connect includes two shipping providers, used by two shipping methods. The shipping model supports multiple shipments per cart and per order. You can also create your own shipping providers and methods.

Use this article to retrieve, restrict, and price shipping methods at run time from custom checkout or order processing code.

Key classes

Classes in this topic are available in the following namespaces:

• Mediachase.Commerce.Orders – Contains the Shipment class.
• Mediachase.Commerce.Orders.Managers – Contains the ShippingManager and CountryManager classes.

The shipping API surface includes:

• Shipment – Represents one shipment within an order.
• ShippingGateway – The interface that shipping gateways must implement to integrate with Commerce Connect.
• ShippingManager – Provides access to shipping methods, shipping method cases, and package information.
• CountryManager – Provides access to countries defined as shipping jurisdictions.

📘

Note

Implementations of IShippingGateway and IShippingPlugin must declare a constructor that takes IMarket as a parameter.

How shipping works

• Each shipment (represented by the Shipment class) contains one or more LineItem references, a shipping address, a shipping method, and a rate. The line items, shipping address, and shipping method together determine the shipping rate.
• Each shipping method is associated with a shipping provider. A shipping provider can serve multiple shipping methods.
• The shipping provider contains the logic that determines a shipment's rate. It can use line item properties (such as weight or size), other order properties, the shipping address, or any other data or external service your implementation requires.
• Shipping methods contain shipping scenarios that represent different pricing for distinct jurisdictions (the location can be as general as a country or as specific as a ZIP code) and shipment weight ranges.

Retrieve shipping methods

To retrieve available shipping methods, call ShippingManager.GetShippingMethods. Shipping methods are locale-specific, so pass the language name when you call the method.

The following example retrieves the available shipping methods for a cart, with their associated rates:

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

The ShippingMethodDto typed dataset provides several tables that support different aspects of displaying shipping options:

• ShippingMethod – Contains one row per shipping method, including the ID and the data shown on the Overview tab in Commerce Connect Admin (Commerce Manager in version 13 and earlier).
• ShippingCountry – Contains one row for each restricted country associated with a shipping method.
• ShippingRegion – Contains one row for each restricted state or region for a shipping method.
• ShippingPaymentRestriction – Contains one row for each payment type restricted for a shipping method.
• ShippingMethodCase – Contains one row for each shipping rate scenario on a shipping method. See the Parameters tab of the Default Shipping method for the data stored on each row.
• ShippingOption – Contains one row per shipping provider. The Overview tab of a shipping provider shows this information.

Restrict shipping methods

A shipping method can be restricted by country, by region or state, or by payment type. To match a shipping address country to the restricted countries on a shipping method, you need the country ID. Use CountryManager to retrieve it.

The following example retrieves the 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;
}

CountryManager also returns regions. Regions map to the address State or RegionCode properties.

The following example iterates through the restricted countries on a shipping method:

// 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;
        }
    }
}

Retrieve shipping rates

To retrieve the shipping rate for a shipping method, call GetRate on the shipping provider, passing the order address and the cart items. GetRate is defined on IShippingGateway, which every shipping provider must implement.

The following example retrieves the shipping rate for each available shipping method in the cart:

foreach (ShippingMethodDto.ShippingMethodRow row in shippingRows)
{
    // ShippingMethodDto maintains relationships between rows, so a ShippingMethodRow has
    // a reference to its parent shipping provider row. Retrieve the provider class name
    // from there, instantiate the provider, and call GetRate 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);

    // Retrieve the line items in the cart that 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);
        }
    }

    // Call GetRate to retrieve the rate for this shipment.
    if (items.Count > 0)
    {
        ShippingRate rate = provider.GetRate(row.ShippingMethodId, items.ToArray(), ref message);
    }
}