Sitecore Experience Commerce

Create a custom fulfillment option

The Sitecore XC Fulfillment plugin supports default fulfillment options (as displayed in the Commerce Control Panel). Each of these fulfillment option maps to a default ShippingOptionType value defined in Commerce Connect, as summarized in the following table: 

Fulfillment option

ShippingOptionType

Deliver To Address

ShipToAddress

Deliver Items Individually - split shipments

LineShippingOption

Digital Delivery

ElectronicDelivery

Note

The "Pick Up From Store" fulfillment option type is not currently supported. 

For more information on ShippingOptionType, see the Commerce Connect Developer Reference.

In some Sitecore XC implementations, you may have a requirement for custom fulfillment options. This topic provides guidance on how to create a custom fulfillment plugin that extends the Commerce Engine to meet specific fulfillment business requirements.

You must extend the Commerce Engine to include the custom fulfillment option, and add it in the Commerce Control Panel to make it available to the storefront.

Extend the Commerce Engine for the custom fulfillment option

Once you have added your custom fulfillment option to the Commerce Control Panel, and synchronized the data with the Commerce Engine database, you must extend the Commerce Engine Fulfillment plug-in so that it can process your new custom fulfillment option.

To extend the Commerce Engine Fulfillment plug-in:

  1. Create a new class for the custom fulfillment option (for example, MyCustomFulfillmentComponent.cs) and ensure it has the appropriate properties (for example, StoreID, StoreAddress).

    You must also include a JsonConverter attribute and specify the JsonConverter you will create (in the next step).

    [JsonConverter(typeof(MyCustomFulfillmentComponentConverter))] 
        public class MyCustomFulfillmentComponent : FulfillmentComponent 
        { 
      … 
    }
    
  2. Create a  JSON converter for your new custom fulfillment component (you can use the Sitecore XC FulfillmentCOmponentConverter.cs file as a guide). 

    public class MyCustomFulfillmentComponentConverter : JsonConverter 
    { 
         … 
         public override object ReadJson(JsonReader reader, Type objectType, object existingValue, JsonSerializer serializer) 
         { 
              if (reader.TokenType == JsonToken.Null) 
              { 
                   return null; 
              } 
     
              var jObject = JObject.Load(reader); 
              var type = (string)jObject.Property("@odata.type"); 
              type = Regex.Replace(type, "[#]", string.Empty); 
              FulfillmentComponent target = null; 
              if (type.Equals("MyNamespace.MyCustomFulfillmentComponent", StringComparison.OrdinalIgnoreCase)) 
              { 
                   target = new PhysicalFulfillmentComponent(); 
              } 
    
              var jObjectReader = jObject.CreateReader(); 
              jObjectReader.Culture = reader.Culture; 
              jObjectReader.DateParseHandling = reader.DateParseHandling; 
              jObjectReader.DateTimeZoneHandling = reader.DateTimeZoneHandling; 
              jObjectReader.FloatParseHandling = reader.FloatParseHandling; 
              serializer.Populate(jObjectReader, target); 
    
              return target; 
           } 
           … 
    } 
  3. Add pipeline blocks to any pipelines that handle fulfillment (for example, adding a fulfillment to a cart or to a cart line), to ensure the pipelines can process your new custom fulfillment option.

Extend CE Connect for the custom fulfillment option

You must also extend Commerce Engine Connect to handle the new custom fulfillment option. 

To extend the CE Connect to handle the new custom fulfillment option:

  1. Extend the AddShippingInfoToCart pipeline processor to include the new custom fulfillment option. 

  2. Extend the TranslateCartToEntity pipeline processor to include the new custom fulfillment option.

  3. Extend the GetShippingOptions pipeline processor to include the new custom fulfillment option.

  4. Extend the GetShippingMethods pipeline processor to include the new custom fulfillment option.

Note

You must modify the user interface code on your storefront site to reflect the new fulfillment option. 

Add the custom fulfillment option to the Commerce Control Panel

The Commerce Control Panel is the central location in the Sitecore XP tool suite for configuring Commerce settings for the Commerce Engine, business tools, and storefronts.

Follow these steps to add your custom fulfillment option to the Commerce Control Panel:

  1. From the Sitecore Launchpad, open the Content Editor.

  2. Navigate to the sitecore/Commerce/Commerce Control Panel/Shared Settings/Fulfillment Option Types folder in the left pane, and click on Fulfillment Option Type in the main pane.

    Fulfillment-Option-Type.jpg
  3. In the dialog window, enter a name for your new fulfillment option type (for example, My Custom Fulfillment) and click OK.

  4. In the Fulfillment Option Type pane, specify a name for the fulfillment option type and an ID (for example, 5), then save your changes.

  5. Navigate to the sitecore/Commerce/Commerce Control Panel/Shared Settings/Fulfillment Options folder and click on Fulfillment Option in the main pane. 

    Fulfillment-Option.jpg
  6. In the Fulfillment Option pane, select the fulfillment option type you created earlier, and optionally add a description, then save your changes.

  7. Navigate to the sitecore/Commerce/Commerce Control Panel/Storefront Settings/Commerce Engine Default Storefront/Fulfillment Configuration folder.

  8. Select your custom fulfillment option and click the > icon to move it into the Selected pane, then save your changes.

  9. Push your changes to the Commerce Engine by synchronizing the content items between the Sitecore database and the Commerce Engine database, as described in the Synchronize content items topic. Use the Sync content path API sample to synchronize the entire content tree.