Implementing custom shipping carrier providers | Kentico Xperience 8.2 Documentation

This content cannot be displayed without JavaScript.
Please enable JavaScript and reload the page.

Implementing custom shipping carrier providers | Kentico Xperience 8.2 Documentation

Create a custom module and a module project to represent your carrier.

See an example to get more integral view.
(Optional) In the Modules application, edit the module representing your carrier, and on the User interface tab, create a UI element which will be then used as a configuration tab of your carrier (for example, with a login form for communication with an API of its shipping company).
- You must create the UI element in the same module, otherwise it won't be included in the installation package.
- If your carrier doesn't need any configuration, you don't have to create any UI element.
- Since every carrier can have only one configuration tab, create only one UI element for it.
  
  To calculate shipping costs, shipping companies usually require an address of the place from where the bought items are sent. You can create a text box on the configuration tab for the address.
(Optional) As you did for the carrier, you can also create UI elements as configuration tabs for services of the carrier. Configuration tabs of services are then displayed while editing any shipping option based on the given service.
- Every service can have one configuration tab.
(Optional) If you need to communicate with an API of a shipping company, you may need to add their API web references to your Kentico instance:
1. Download a WSDL file from a website of the shipping company (for example, FedEx offers its WSDL files in their Documentation and Downloads⁠ (opens in a new tab) section).
2. Right-click References in your carrier project in the Visual Studio Solution Explorer and click Add Service Reference.
3. Click Advanced in the Add Service Reference dialog.
4. In the Service Reference Settings dialog, click Add Web Reference.
5. Enter the path of your downloaded WSDL file, and click Add Reference.
  - Visual Studio will then generate a new class according to the reference file automatically. You can then use its methods to implement the carrier provider, for example in the GetPrice method and the CanDeliver method.
Create a new class in your project in Visual Studio, for example MyCustomCarrier.cs, that Implements the ICarrierProvider interface.
1. Label the class with the following assembly attribute:
  C#
```
[assembly: RegisterCustomClass("MyCustomCarrier", typeof(MyCustomCarrier))]
public class MyCustomCarrier : ICarrierProvider
{
}
```
2. Implement the CarrierProviderName property.
  C#
```
string CarrierProviderName
{
        get;
}
```
Create the module installation package.

You can see the already mentioned example.

Implement the GetServices method.

C#

List<KeyValuePair<string, string>> GetServices()

The method returns a list of code names (the first element in the list) and display names (the second element in the list) of services of the carrier. You can use the code names in the code and in macros; the display names are used when working with shipping options in the administration interface.

If you have a multilingual site, create resource strings for display names of your services.

Example:

C#

// Returns 2-day, priority and standard overnight FedEx shipping services.
public List<KeyValuePair<string, string>> GetServices()
{
      SortedDictionary<string, string> mServices = new SortedDictionary<string, string>
      {
            {"PRIORITY_OVERNIGHT", "{$com.fedexcarrierprovider.priorityovernight$}"},
            {"STANDARD_OVERNIGHT", "{$com.fedexcarrierprovider.standardovernight$}"},
            {"FEDEX_2_DAY", "{$com.fedexcarrierprovider.2day$}"}
      };

      return mServices.ToList();
}

Implement the GetPrice method.

C#

decimal GetPrice(Delivery delivery, string currencyCode)

The method calculates shipping costs of the delivery specified in the input parameters and then returns the total shipping cost in the currency also set in the input parameters.

Parameters of GetPrice – the Delivery class

The Delivery class represents a set of items intended to be shipped using a shipping option. The class contains the following properties:

IEnumberable<DeliveryItem> Items – shipped items. Only products and product options of the Products type are present,
DateTime ShippingDate – the date when the store pass the package to the shipping company which provides its shipping,
decimal Weight – total weight of the shipped package in unit specified in the ECommerceSettings.MassUnit() setting,
ShippingOptionInfo ShippingOption – the shipping option used for the delivery,
IAddress DeliveryAddress – the address where the package is delivered,
IDataContainer CustomData – this property is set for your custom data.

Remember, you have also to take care of exchange rates when it comes to communication with an API of a shipping company when currency of a given order is not in the currency supported by carrier and the API of the shipping company.

You can use exchange rates entered in the Store configuration application by using the CurrencyConverter.Convert(decimal amount, string inCurrencyCode, string toCurrencyCode, int siteID) method in the CMS.Ecommerce namespace, where:

decimalamount – sets the price in the original currency,
string inCurrencyCode – sets the code of the original currency,
string toCurrenceCode – sets the code of the result currency to which the decimal amount is to be converted,
int siteID – ID of the current site.

Example:

C#

CurrencyConverter.Convert(shippingPrice, "USD", currencyCode, delivery.ShippingOption.ShippingOptionSiteID);

Implement the CanDeliver method.

C#

bool CanDeliver(Delivery delivery)

The method checks if the shipping option (specified in the Delivery parameter) is available for shipping. See implementing theGetPricemethod above to learn more about parameters.

If you want your services to be always available, return true.

C#

public bool CanDeliver(Delivery delivery)
{
      return true;
}

Implement the GetConfigurationUIElementGUID method.

C#

Guid GetConfigurationUIElementGUID()

The method returns GUID of an UI element that is used as a configuration tab of the carrier (which you created in the step 2). The configuration tab is then displayed while editing a carrier on the Shipping -> Carriers tab in the Store configuration application.

If the carrier doesn't have any configuration tab, return Guid.Empty. To determine the GUID of a UIElement, you can use the UIElementInfoProvider.GetUIElementInfo(string resourceName, string elementName) function in the CMS.Modules namespace.

Example:

C#

using CMS.Modules;

/// <summary>
/// Returns Guid of the configuration tab of the carrier where moduleName is the code name
/// of the module and elementName is the code name of the UIElement.
/// </summary>
public Guid GetConfigurationUIElementGUID()
{
      UIElementInfo ui = UIElementInfoProvider.GetUIElementInfo(moduleName, elementName);
      return ui.ElementGUID;
}

Implement the GetServiceConfigurationUIElementGUID method.

C#

Guid GetServiceConfigurationUIElementGUID(string serviceName)

The method returns GUID of an UI element that is used as a configuration tab of the service specified with its code name in the serviceName property (which you created in the step 3). You can determine the GUID as in the GetConfigurationUIElementGUID method. The configuration tab is then displayed while editing a shipping option in the Store configuration application on the Shipping -> Shipping options tab. For example, the Weight based shipping service of the Default carrier has the Shipping costs tab.

If services don't have any configuration tabs, return Guid.Empty.