Shipping gateways and providers

A shipping gateway is the .NET class that calculates shipping rates. A shipping provider is the configured Commerce Connect entity that wraps a gateway and exposes it to shipping methods.

Optimizely Commerce Connect includes two shipping gateway providers by default:

Generic Gateway – Flat shipping rate.
Weight/Jurisdiction Gateway – Base price plus an additional fee that depends on weight and shipping location.

Add your own shipping gateway and provider when neither built-in option fits. Under Shipping Providers, Shipping Gateway identifies the class you select (Generic Gateway or Weight/Jurisdiction Gateway).

Classes in this topic are available in the following namespaces:

Mediachase.Commerce.Orders – Contains IShippingGateway and IShippingPlugin.
Mediachase.Commerce.Catalog.Data – Contains CurrencyAdmin.
Mediachase.Commerce.Orders.Dto – Contains ShippingMethodDto.

For details about shipping methods, see Shipping methods.

Shipping gateways

Select a Shipping Gateway from the Shipping Provider view in Commerce Connect Admin. Configure the gateway values on the Shipping Methods page.

Shipping Jurisdictions – Defines region-specific shipping rate values. Used only when you select the Weight/Jurisdiction Gateway — for example, California.
Shipping Jurisdiction Groups – A group of jurisdictions, such as Southwest region. Required when configuring shipping method parameters.

Shipping providers

Shipping provider classes retrieve shipping prices from one or more shipping services, such as USPS, UPS, or FedEx. A provider typically represents one service (for example, USPS), but it can also represent a shipping scenario such as overnight delivery, price-by-weight, or ground shipping. The provider can compare prices across services to find the lowest rate for a customer location.

Key classes and files

IShippingGateway – Interface that a shipping gateway must implement.
IShippingPlugin – Same functionality as IShippingGateway, but uses the abstraction API instead of the concrete classes.
WeightJurisdictionGateway – Example implementation.
GenericGateway – Example implementation.
CurrencyAdmin – Provides lookup for currency codes.
ShippingMethodDto – DTO for shipping method configuration information.
JurisdictionManager – Provides methods to retrieve jurisdictions.

📘
Note
Use IShippingPlugin for new gateways. IShippingGateway is retained for backward compatibility.

Create shipping options

To provide shipping options during checkout, add shipping methods, each of which uses a shipping provider. The procedure has two parts: implement the shipping plugin, then register the gateway and method in Commerce Connect Admin.

Implement the shipping plugin

Create a separate project in the solution to store custom business logic for your application.
In that project, create a class that implements IShippingPlugin. The interface defines one method, GetRate, which returns the shipping rate for an IShipment from the cart. GetRate is where you call the shipping service or rate provider that determines the cost.

📘
Note
Remember to register the class with the service container as a service of IShippingPlugin.

The method signature is:

public ShippingRate GetRate(Guid methodId, IShipment shipment, ref string message);

The return value is a ShippingRate instance, which exposes the following properties:

Id – The associated shipping method ID. This value is passed to the method as the first parameter.
Money – The price for the shipping service. The currency must be one of the currencies configured for the application. To retrieve currency information from the database, use CurrencyAdmin.
Name – The name of the shipping method associated with the shipping method ID.

The following example retrieves the shipping method ID:

// Look up shipping method.
ShippingMethodDto methods = ShippingManager.GetShippingMethods(Thread.CurrentThread.CurrentCulture.Name);
// methodId was passed into GetRate as one of the method parameters.
ShippingMethodDto.ShippingMethodRow row = methods.ShippingMethod.FindByShippingMethodId(methodId);

string name;
if (row != null)
{
    name = row.Name;
}
else
{
    name = "";
}

Register the gateway and method in Commerce Connect Admin

Copy the DLLs from the shipping gateway project to the bin folders of Commerce Manager and the public website.
Go to Commerce > Administration > Shipping > Shipping Providers.
Click Create.
Enter a name for the gateway and a system keyword. The keyword must be unique.
Select the gateway that implements IShippingPlugin (the class you created earlier).
Click Save.
Go to Shipping > Shipping Methods.
Click Create.
Fill in the shipping method fields, including the provider you created earlier. To make the shipping method available, set IsActive to Yes.
Click Save.

Access shipping provider information

ShippingManager lets you retrieve the case rows that apply to the current scenario. Call this code from GetRate, or from a method that GetRate calls.

The following example retrieves shipping provider information:

// methodId is passed into GetRate.
DataTable casesTable = ShippingManager.GetShippingMethodCases(
    methodId,
    shippingAddress.CountryCode,
    shippingAddress.State,
    shippingAddress.PostalCode,
    shippingAddress.RegionCode,
    null,
    shippingAddress.City,
    weight);

For an example of using this DataTable, see the GetRate implementation in WeightJurisdictionGateway.cs.

Packages

Create packages and associate them with shipping providers. Define a generic package size, associate it with a product, and then map it to a provider-specific package. For example, a generic LARGE package can map to a 25 kg Large FedEx box and a USPS Large Flat Rate box.

To associate a package with a shipping provider, open the provider in Commerce Manager, go to the Packages tab, and click Add Item. To associate a package with a SKU, change the Package property on the SKU's Pricing/Inventory tab.

To retrieve package information for a shipping provider, use ShippingMethodDto. It contains two typed data tables with the package information:

ShippingPackage – Contains the relationship between shipping providers and packages.
Package – Contains the package information.

The following example retrieves package information for a shipping provider:

ShippingMethodDto shippingMethods = ShippingManager.GetShippingMethods("en-us");

foreach (System.Data.DataRow row in shippingMethods.ShippingOption.Rows)
{
    // A shipping option is a shipping provider.
    ShippingMethodDto.ShippingOptionRow shippingProviderRow = (ShippingMethodDto.ShippingOptionRow)row;

    // Access the packages associated with the shipping provider.
    ShippingMethodDto.ShippingPackageRow[] packageRows = shippingProviderRow.GetShippingPackageRows();

    // Access each package's name and ID:
    // packageRows[0].ShippingPackageId
    // packageRows[0].PackageName

    // Retrieve the individual package row with additional information.
    ShippingMethodDto method = ShippingManager.GetShippingPackage(packageRows[0].PackageId);

    // GetShippingPackage populates the Package table with the applicable shipping package.
    if (method.Package.Rows.Count > 0)
    {
        ShippingMethodDto.PackageRow packageRow = (ShippingMethodDto.PackageRow)method.Package.Rows[0];

        // Retrieve the package properties:
        // packageRow.Length
        // packageRow.Height
        // packageRow.Width
        // packageRow.Description
    }
}