Shipping gateways and providers (Commerce 7.5)

Introduction

Shipping gateways and providers are used to provide shipping rates for a cart. They return the appropriate shipping charge for carts during checkout.Two shipping gateways/providers are included by default, and you can also add your own shipping gateway and provider. Under Shipping Providers, a Shipping Gateway is the specific class that you select (Generic Gateway or Weight/Jurisdiction Gateway).

Classes referred to here are available in the following namespaces:

Mediachase.Commerce.Orders - contains IShippingGateway
Mediachase.Commerce.Catalog.Data - contains CurrencyAdmin
Mediachase.Commerce.Orders.Dto - contains ShippingMethodDto

Refer also to Shipping Methods for related information.

Shipping gateways

These are the two out-of-the-box options for shipping gateways:

Generic Gateway - flat shipping rate
Weight/Jurisdiction Gateway - base price + additional fee depending on weight and shipping location

You select the Shipping Gateway in the Shipping Provider screen, and then configure the actual values for that gateway/provider in the Shipping Methods area.

Shipping Jurisdictions - an option which allows you to define values for region-specific Shipping Rates; this is only used when you select the Weight/Jurisdiction Gateway, for instance "California".
Shipping Jurisdiction Groups - group of Jurisdictions; this is needed because this is a required field when configuring the Shipping Method parameters, for instance "Southwest region".

Shipping providers

The shipping provider classes interact directly with one or more actual shipping services such as USPS, UPS, or FedEX. It retrieves shipping price information from the shipping service(s) its associated with. One typical scenario would be to have a provider that represents a particular service, for instance USPS.

A provider can also represent a particular type of shipping situation. One example is that you could have a provider for overnight delivery. The provider could retrieve pricing for that service to determine the lowest price given the location of the customer. A provider could also represent other specific scenarios with one or more services such as price by weight or ground shipping.

Key classes and files

IShippingGateway - interface implemented in creating a shipping gateway
WeightJurisdictionGateway - example implementation
GenericGateway - example implementation
CurrencyAdmin - provides a lookup for currency codes
ShippingMethodDto - DTO for shipping method configuration information
JurisdictionManager - provides methods to retrieve jurisdictions

Creating shipping options

To provide shipping options during the checkout process, you need to add shipping methods, and each method must use a shipping provider. Below are the steps to create a custom shipping provider and method.

1. Create a separate project in the solution to store custom business logic implementations for your application.

2. Create a class in this project that inherits from IShippingGateway. This interface only has one method, GetRate(). This method returns the rate for shipping associated with the LineItems from the shopping cart submitted for pricing. This method provides whatever interface is required to the actual shipping services/rate provider to determine the shipping cost.

Example: the signature for the method:

public ShippingRate GetRate(Guid methodId, LineItem[] items, ref string message)

The return value is a ShippingRate instance, which contains several properties:

GUID for the associated shipping method. This value is passed into the method (first parameter).
Price. This value needs to be looked up through the rest of the implementation of this method which connects to the shipping company.
Currency code. This value should correspond to one of the currencies associated with the application. Currency information can be retrieved from the database using the CurrencyAdmin object.
Shipping method name. This is the name of the shipping method associated with the shipping method ID.

Example: retrieving the shipping method ID

ShippingMethodDto methods;
            ShippingMethodDto.ShippingMethodRow row;
            string name;

            //Look up payment method
            methods = ShippingManager.GetShippingMethods(Thread.CurrentThread.CurrentCulture.Name);
            //the methodId was passed into the method as one of the method parameters_
            row = methods.ShippingMethod.FindByShippingMethodId(methodId);

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

3. Copy the .dlls associated with the project where the shipping gateway is implemented into the bin folders of both the Commerce Manager and public web sites.

4. In Commerce Manager, go to the Admin tab.

5. Go to Order System/Shipping Providers.

6. Click New.

7. Enter a name for the gateway and a system keyword. The system keyword has to be unique.

8. Select the gateway which implements IShippingGateway you created in the previous step.

9. Click OK.

10. Go to Order System/Shipping Methods/[applicable language].

11.Click New.

12. Fill in the fields for the method, including the name of the provider created in the previous step. To make the shipping method available, set IsActive to Yes.

13. Click OK.

Adding a configuration tab

You can create a configuration tab for your shipping method. This will allow you to use multiple instances of a custom shipping provider you create and then set custom parameters for each instance. To do this, you need to create a user control that will render in Commerce Manager as the Parameters tab for a shipping method.

The control you create will create/update/retrieve shipping scenario data about different circumstances based on weight, number of items, and jurisdiction that your custom shipping gateway will use to calculate the shipping rate. Below are the steps to create a configuration tab.

1. Add a new control to your custom shipping provider project. Call the controlConfigureShippingMethod.ascx.

2. Make sure the new control inherits from OrderBaseUserControl and implements the IGatewayControl interface.

3. Add references to your project for Mediachase.Commerce.dll and Mediachase.Webconsolelib.dll.

4. The IGatewayControl interface has two methods and a required property.

Example: methods of IGatewayControl

public interface IGatewayControl
            {
              void SaveChanges(object dto);
              void LoadObject(object dto);

              string ValidationGroup { get;set;}
            }

These two methods are called by Commerce Manager. The DTOobject that is passed into both methods is, in the case of a shipping provider configuration tab, an instance of a ShippingMethodDto.cs. This DTO contains a table, ShippingMethodCase, which holds all of the shipping rate scenarios you store for your shipping method.

The code in the control simply needs to update the ShippingMethodCase rows to reflect each of the scenarios the user adds in Commerce Manager. Commerce Manager takes care of retrieving the data and saving the data back to the database.

Each shipping scenario is a row of data. The framework provides this scenario storage for your implementation. In other words, the scenario data you store for a shipping method in the ShippingMethodCase table will not be used by the framework during the checkout.

Each row of date include these fields:

Total - a number which can represent weight or item count or some other number indicator.
Charge - represents the cost.
StartDate, EndDate - allows you to specify the date range of the rate validity.
JurisdictionGroupId - maps to a jurisdiction group configured in the Jursidictions/Jurisdiction Groups section of Commerce Manager.
ShippingMethodId - the ID for the shipping method.

Jurisdiction groups can be retrieved using the JurisdictionManager.

Example: retrieving jurisdiction groups

//retrieve the data; get shipping jurisdictions, not tax jurisdictions
            JurisdictionDto jDto = JurisdictionManager.GetJurisdictionGroups(JurisdictionType.Shipping);
            //bind to a dropdownlist
            ddlJurisdiction.DataSource = jDto.JurisdictionGroup;

5. Implement the SaveChanges() and LoadObject() methods.

Example: minimum code for SaveChanges() and LoadObject() methods

_ShippingMethodDto = dto as ShippingMethodDto;

The _ShippingMethodDto is a class member of type ShippingMethodDto. Either in the aforementioned methods or in other event handler methods, data entered by the customer needs to be retrieved/saved to this DTO.

Example: adding and retrieving data from ShippingMethodDto

//Adding a row of data
                if (_ShippingMethodDto != null && _ShippingMethodDto.ShippingMethod.Count > 0)
                {
                    ShippingMethodDto.ShippingMethodCaseRow row = _ShippingMethodDto.ShippingMethodCase.NewShippingMethodCaseRow();
                    row.Total = Double.Parse(Weight.Text, _NumberFormat);
                    row.Charge = Double.Parse(Price.Text, _NumberFormat);
                    row.StartDate = StartDate.Value;
                    row.EndDate = EndDate.Value;

                    //the ShippingMethodDto will only contain one row for the ShippingMethod row, which
                    //represents the shipping method information stored on the first tab of the shipping method in
                    //commerce manager
                    row.ShippingMethodId = _ShippingMethodDto.ShippingMethod[0].ShippingMethodId;
                    row.JurisdictionGroupId = Int32.Parse(JurisdictionGroupList.SelectedValue);

                    // add the row to the dto
                    if (row.RowState == DataRowState.Detached)
                        _ShippingMethodDto.ShippingMethodCase.Rows.Add(row);
                }

                //retrieving a row of data to populate controls
                //set the properties of the controls in the configuration
                //tab
                if (_ShippingMethodDto.ShippingMethodCase.Count > 0)
                {
                    //in this scenario, we're only supporting a single row
                    //to serve as a simple example
                    row = _ShippingMethodDto.ShippingMethodCase.Rows[0];
                    txtRate.Text = row.Charge.ToString();
                    txtWeight.Text = row.Total.ToString();
                    ddlJurisdiction.SelectedValue = row.JurisdictionGroupId;
                }

6. Implement the ValidationGroup property. This property is used internally by the framework.

Example: implementing ValidationGroup

public string ValidationGroup
            {
                get
                {
                    return _ValidationGroup;
                }
                set
                {
                    _ValidationGroup = value;
                }
            }

7. Build your shipping provider project containing the configuration control. You may separate the shipping provider and the configuration control, there is no need for them to be in the same project except for convenience.

8 .Add a reference to your shipping provider method in the Commerce Manager project, if this has not been done.

9. Copy the ConfigurateShippingMethod.ascx into a new folder under the Shared folder locationApps/Order/Shipping/Plugins/Shipping Method Name. The shipping method name does not have to be the name of the shipping provider, it can be more informational, representing a shipping provider or shipping type for instance FedEx24Hour.

10. Build the site.

11. Go to Commerce Manager/Administration/Order System/Shipping/Shipping Methods/Language.

12. Click New.

13. Configure the new shipping method. Select your new shipping provider from the list of shipping providers, use the same system name as you named the folder in step 9, set it to active.

14. Save the shipping method, re-open, and navigate to the parameters tab. You should see your new shipping provider.

15. Enter parameter information and save the shipping method.

Accessing shipping provider information

The ShippingManager class allows you retrieve the appropriate case rows, depending on your scenario. This code would be used in your GetRate method, or in a method which is called by GetRate().

Example: retrieving shipping provider information

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

For more information on how to use this DataTable, see the WeightJurisdictionGateway.cs GetRate() implementation.

Packages

You can create packages and associate them with shipping providers. That way you can have a generic package sizesdefined and associated withproduct and then map this generic package to a provider specific package. For example the generic "LARGE" package can map to a 25 Kg Large FedExbox and an USPS Large Flat Rate box.

You can associate them with shipping providers by opening a shipping provider in Commerce Manager, clicking on the Packages tab, and selecting Add Item. You can also associate packages with SKUs by changing the Package property on the Pricing/Inventory tab of a SKU in Commerce Manager.

You can retrieve package information for a shipping provider by retrieving the ShippingMethodDto. This contains two typed data tables with the package information:

ShippingPackage - contains the relationship information between shipping providers and packages
Package - contains all of the package information

Example: retrieving package information for a shipping provider

Mediachase.Commerce.Orders.Dto.ShippingMethodDto shippingMethods =
              Mediachase.Commerce.Orders.Managers.ShippingManager.GetShippingMethods("en-us");

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

              //now you have access to packages associated with the shipping provider
              Mediachase.Commerce.Orders.Dto.ShippingMethodDto.ShippingPackageRow[] packageRows =
                shippingProviderRow.GetShippingPackageRows();

              //now you have access to the packages' names and id's
              //packageRows[0].ShippingPackageId
              //packageRows[0].PackageName

              //now you can retrieve the individual Package row with additional information
              Mediachase.Commerce.Orders.Dto.ShippingMethodDto method =
                Mediachase.Commerce.Orders.Managers.ShippingManager.GetShippingPackage(packageRows[0].PackageId);

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

              //here we can retrieve the package properties
              //packageRow.Length
              //packageRow.Height
              //packageRow.Width
              //packageRow.Description
              }

            }

Try our conversational search powered by Generative AI!

Shipping gateways and providers