November Happy Hour will be moved to Thursday December 5th.
AI OnAI Off
November Happy Hour will be moved to Thursday December 5th.
Shipping gateways and providers provide shipping rates for a cart. They return the appropriate shipping charge for carts during checkout. Two shipping gateways/providers are included by default.
You also can 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 in this topic are available in the following namespaces:
See also Shipping Methods.
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.
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 services its associated with. One typical scenario would be to have a provider that represents a particular service, for instance USPS.
A provider also can 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.
To provide shipping options during the checkout process, you need to add shipping methods, and each method must use a shipping provider. The following steps create a custom shipping provider and method.
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:
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 = "";You can create a configuration tab for your shipping method. This lets you use multiple instances of a custom shipping provider you create and then set custom parameters for each instance. To do this, create a user control that renders 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. The following steps show how to create a configuration tab.
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 is not used by the framework during the checkout.
Each row of date include these fields:
You can retrieve jurisdiction groups 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;
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 dataif (_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 dtoif (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//tabif (_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;
}Example: implementing ValidationGroup
public string ValidationGroup
{
get
{
return _ValidationGroup;
}
set
{
_ValidationGroup = value;
}
}The ShippingManager class lets you retrieve the appropriate case rows, depending on your scenario. This code is 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 information about using this DataTable, see the WeightJurisdictionGateway.cs GetRate() implementation.
You can create packages and associate them with shipping providers. That way you can have a generic package sizes defined and associated with product 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:
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
}
}Last updated: Oct 12, 2015