Blog

Use the Surcharge Expression to negate the rate if the shipping option name contains the word “Ground”.



Add two 'Shipping Director' records

(This is an old blog.  If using nopCommerce 3.x or greater, note that "ProductVariant." should be removed if you copy these expressions)

You can exclude items from packing - the Packing option now has a "Exclude Item Expression" (shows in Description Expression column).  It should evaluate as a boolean (true, false).  Items that are not packed do not contribute to the weight/dimensions of a package, therefore you can create complex free shipping scenarios like "Free shipping for product x if quantity n or more".   Note that Packing expressions are always with respect to the item as it's being packed (unlike other record types where expressions relate to the entire cart - e.g. Items).  So, if you need to count the quantity of something in the cart to determine if exclusion should apply, then you need to do it with a variable before you pack.  Then, use that variable in the Exclude Item Expression with any other item specific expression.  For example, below, we sum the quantity of a particular item and if greater than 10, the "Exclude From Packing" variable is true.  Then in packing expression, we use the variable to check if exclusion should be considered, and then check the item condition.

Note also, that we initially check for Free Shipping - no point in checking expressions, packing, etc., if all items in cart are free shipping.  (An alternate, and better although a little slower, way to check free shipping for the entire cart is to use the $IsFreeShipping variable; this uses the nopC core OrderTotalCalcService.IsFreeShipping to check all the possible cart ships free possibilities including customer roles).  Also, we check variable $PackageCount after we pack - [$PackageCount is set by the system with the # of packages that result from packing - if nothing was packed (everything was excluded), then the entire cart ships free.

[updated 10/2014 - replaced ProductVariant with Product]

In the NopCommerce forums, someone had noticed that if you use Fixed Rate shipping but some of your products have "Additional Shipping Charge", that In Store Pickup would still include those charges:

    "...One gotcha - We have items that may individually use the "Additional Shipping Charge" field, and that still factors in.  I had to modify the code and recompile to set this to zero for in-store pickup..."

To remedy this, the user had to modify some code in the core ShippingService module to zero out the rate.    With the Shipping Director, it's easy to modify the rate.

Let's say we have set up Fixed Shipping rate for In Store Pickup ($0.00) and Ground ($9.95).   Then, we set up a Shipping Director option to use the Shipping.FixedRate plugin

If we have a product with an Additional Shipping Charge of $0.99, and add two of those in my shopping cart and estimate shipping I see:

We can negate the Additional Shipping Charge easily by using the Surcharge Expression with a minus sign prefix:

 -(Items.Where(Product.AdditionalShippingCharge > 0).Sum(Quantity * Product.AdditionalShippingCharge))

But, we only want to negate it when the rate option name is "In-Store Pickup", so we use the ternary if-then-else operator "  ?  :  "

  [$Name].Contains("Pickup") ? -(Items.Where(Product.AdditionalShippingCharge > 0).Sum(Quantity * Product.AdditionalShippingCharge)) : 0

When Packing "FirstFit", the Shipping Director will put an item in the first open box that will fit it.   Sometimes, though, you want an item to be packed in its own box.  This might be the case if the item already has its own box suitable for shipping - i.e. it does not need to be shipped inside another box.  Setting a "Requires Own Package Expression" will tell the Packing to put the item it its own package, and consider the box "full", so that no other items will be packed in the same box.

Another scenario that might pertain to you or your client is shipping from multiple source addresses - e.g. direct from your supplier/distributor, or from different warehouses.  If the order contains mutiple items from different senders, then setting a "Sender Expression" will tell the Packing not to mix items from different senders in the same box.

UPDATE 2019  - There's a helper method for Product.HasCategory(), so you don't need the below category Reference any more.  Your Packing rule's "Requires Own Package Expression"  can look like this

Product.HasCategory("ShippingRequiresOwnBox")

Also, nopCommerce now supports Warehouses, so you probably won't need that "Sender Expression".  See the other blogs about warehouses.  We'll write some new blogs soon.

In the following example, we will use a Category "ShippingRequiresOwnBox", and a Product SpecificationAttribute "Shipping Warehouse"

The Category is set up with Published=False, so that it is not visible to customers:

A Product Specification Attribute is setup for "Shipping Warehouse", and a "Warehouse One" option is created in it.  Also, Show on Product Page is set to false, so the customer won't see it.

Now, in Shipping Director, we use Reference types as shortcuts to the category and attribute properties:

(Note, that the 'sender' reference will be set to "Main" if the product does not have a Shipping Warehouse attribute)

and set up appropriate packing expressions:



Also note above the $Debug special variable.  During packing, and during calls to other shipping plugins, extra debug information will be logged in the system log.  (Since logged messages are plain text and not HTML, they will not appear nicely in the Log page - right click the page and choose view source, then on the source page scroll down about half way and look for the formatted message)

Beta 2 introduced the "Reference" type.  A reference is a type of variable that is really just a shortcut.  References will typically be used to specify the NopC objects you want to use in your expressions; it makes the expressions more readable, and also prevents you from having to repeatedly type the same object path.    You define a Reference variable with the Reference type, and you access a Reference by prefixing the variable name with "@".  For example:

You can see above that references can themselves access references.  And they can also be used in other expressions like when Packing:

The packing method built in to Shipping Director is FirstFitSingleBox - Packing is based on "First Fit" using a Single Box Size.  Products fit into first avail box that will take the volume and weight of products.  If no existing box will fit the product, then a new box is started.  It does check that the product will fit in the box's dimensions, but otherwise fit is based on volume of product vs. volume remaining in box, or weight of product vs weight remaining in the box.  (If the product item's dimensions don't fit the box's dimensions, then a new box is created with the product's dimensions, and is considered "full" - no other items will go in that box.)

Here is a sample setup for Shipping Director to do packing.

All should be marked Active, and be sure to spell exactly as above including case, and quote or leading $ if any.  The items with 0 in Expression can be left out if you like - their defaults are 0 anyway, but shown above so you know what all the special variable names (packing parameters) are.   When adding the Packing-type record the Add Form will say "Packing Method" rather than Rate.  (It always says Rate in the grid).

If box dimensions are not specified by above variables, then all items are packed in one box.

Update:

The $PackageBox variable is a shorthand for setting many package attributes in one line.
 e.g. $PackageBox   "MaxWeight:40,Height:15,Width:15,Length:15"
 Here's how each shorthand attribute corresponds to the built in variable:
    MaxWeight    => $PackageBoxMaxWeight
    Height       => $PackageBoxHeight
    Width        => $PackageBoxWidth
    Length       => $PackageBoxLength
    Weight       => $PackageBoxWeight
    AddWeight    => $PackageItemAddWeight
    AddDimension => $PackageItemAddDimension
    ShrinkPercent=> $PackageShrinkPercent

The /APPENDPACKAGES Switch (Update 10/6/2018)

If a Packing rule is called multiple times, then each time it is called the set of packages are cleared and new packages are generated.  To override that behavior and instead append addiitonal packages to the current set of packages, then use the /AppendPackages option following the packing method name:

   Packing.FirstFitSingleBox /APPENDPACKAGES

Typically, you you append packages, you would also use the Packing method "Packing.ClearPackages" and/or use the Exclude Expression.  Otherwise, you would double-pack the same items and that would increase the shipping rates that are caclulated by weight/dimensions.  An example scenario for the AppendPackages would be to use a different $PackageBoxWeight for different types of items; be sure to use the Exclude Expression on each packing rule.

Do customers miss your "We can't ship to PO Boxes" message?  You can now prevent them from placing the order...

You'll also need to prefix the above expression with a check for null, because during a Shipping Estimate (as opposed to checkout), there is no Address1.  So, the final expression looks like this:

  ShippingAddress.Address1 != null and Regex.IsMatch(ShippingAddress.Address1, "(?i)\b(?:Post\ (?:Office\ )?|P[.\ ]?O\.?\ )?Box\b")

You can allow your customer to add insurance to the shipping.   In the example below, we add 10% (of subtotal $) using the Surcharge Expression.  Also, by using the Name Expression, it will be clear to the customer what the shipping option is, and you will be able to see that when you goto the order's Shipping Info tab.

nopCommerce's "Shipping By Weight" is a bit confusing (see my post).  And additionally, it can't enforce a minimum charge if using "Use percentage:".   Brackets are easy to set up in Shipping Director:

You can even show the actual weight in the description if you like

"Weight = " + [$TotalWeight].ToString() + " lbs."  

Also, if you want to add a fixed cost to the per unit rate, then additionally at the bottom of the configuration page, in section Shipping Director Settings, put your fixed cost in theSurcharge: field.  E.g. To have a base rate of $5.00 the enter 5 in Surcharge field, and click Save button