Calling 3rd party shipping provider plugins- Monday, May 27, 2024

If you're trying to use a 3rd party shipping plugin by putting the plugin's System Name in the Option rule's Rate Expression but get an error e.g., "Error=No property or field 'ThirdParty' exists in type 'QueryContext'", then you need to prefix the name with "Shipping".

For example if your Rate Expression has


Then change it to read


Comments (0)
Using [$ShippingOptionsCount] to check for failed carrier APIs- Wednesday, January 31, 2024

Sometimes calling a carrier plugin (API) can fail because the carrier’s service is temporarily down. In Shipping Director, after an Option rule you can reference the $ShippingOptionsCount variable in expressions to check the number of shipping methods returned by an external shipping provider.  If no methods are returned, then you can have alternate shipping methods/rates so that your customer can continue checkout.  For example, you could have

100    Option    FedEx    true                         Shipping.FedEx

120    Option    UPS      [$ShippingOptionsCount] = 0  Shipping.UPS

Note that you can't use OptionExit on your plugin's rule (because Exit will stop processing further rules), so you do have to be careful about what rules follow.  An alternative would be to have an "End" rule which you could $Goto - e.g.

100    Option    FedEx    true                         Shipping.FedEx

110    Integer   $Goto    [$ShippingOptionsCount] = 0 ? 0 : 9999    

100    Option    UPS      true                         Shipping.UPS

...  other rules ...

9999   String    "The End"

( $Goto 0 just goes to the next line.  I.e., "if no options then go to next line else got to the end")

P.S. You may want to consider “normalizing” the carrier method names using the Name Expression on the Option rule – e.g. both “FedEx Ground” and “UPS Ground” can be shown to the customer as “Economy Shipping”, and “FedEx Priority” and “UPS Next Day” can show as “Priority Shipping”.

Comments (0)
Prevent showing shipping methods when there are products that require pickup in store- Sunday, October 29, 2023

NopCommerce won't show the "Pickup in store" if all items in the cart have shipping disabled.

In Shipping Director, you can workaround that by using an Unpublished Category - e.g., "Pickup Only".  First, be sure to select shipping enabled on the product (and add the product to the category).  Then SD can show an error message in the cart (and prevent checkout from continuing) if the cart contains any such item:


Check pickup only

Items.Any(Product.HasCategory("Pickup Only"))

"Sorry, you have product(s) that require pickup in store."

Be sure to sequence (order / line #)  that ErrorExit rule before Option type rules.

Note that the above is using Items.Any() so if cart contains any "pickup only" items, the customer must backup to select Pickup.  Thta's because nopCommerce by default shows the "Pickup" checkbox in the shipping address page.  However, there is a setting that will instead show the "Pickup" checkbox in the shipping methods page.  In Administration > Settings > All Settings, search for ordersettings.displaypickupinstoreonshippingmethodpage, Edit it and change the Value to True.  Then when you have the above ErrorExit, the customer would see this in the shipping method selection page:

Tags :  Pickup
Comments (0)
Payment Director - checking the selected shipping method- Saturday, October 21, 2023

In Payment Director, you can check which shipping method/option was selected by the customer and use it to conditionally show a payment method.  For example, you might have



ShippingOption != null and ShippingOption.ShippingRateComputationMethodSystemName = "Shipping.ByWeightByTotal"

Note that that we prefix the expression with ShippingOption != null  (or you can write  ShippingOption <> null).  This is good practice, because if you have (or ever plan to get) a "button payment method" (that appears in the cart as a button under the chekout button), then Payment Director may get called "prematurely" with respect to not having the selected shipping method.  Having the null check will prevent erros being logged.

(See this blog for additional information: Payment Director and PayPal Express)

Comments (0)
Check if the customer used a coupon code,- Saturday, January 7, 2023

To check if the customer used a coupon code, you could use one of these examples:




Comments (2)
Exclude shipping methods - Product and Country- Thursday, July 2, 2020

As an example, let's say you have products that require "cold" shipping.  So, you offer both standard shipping and cold shipping, and you've set up different rates in the Fixed/ByWeight shipping provider.  If the cart contains any items that require cold shipping, then that's the only shipping method the customer can see.  Similarly, if the cart does not contain any items that require cold shipping, then Standard is the only shipping method the customer can see. 

Set up the two methods in Fixed/ByWeight:  Standard Shipping and Cold Shipping.  We'lI assume you've already accounted for the additional charge for Cold, so SD won't need to calculate the surcharge. 

SD will handle whether to show the Standard or Cold.  Addiitonally, let's set up some country restrictions that we can't cold ship to, and we'll put up an error message if the cart needs Cold, yet the country does not support it.  (Using the ErrorExit rule)

I recommend that you set up an unpublished category for the cold products. (Products can be in more than one category.)  For example, call the category "Cold Shipping".  Then we can detect if the cart contains items requiring cold shipping:  Items.Any(Product.HasCategory("Cold Shipping"))

We'll set up a variable for it:



Items.Any(Product.HasCategory("Cold Shipping"))

The Option rule's Name Expression field can suppress a method when the expression evaluates to blank ("").  We use the ternary if-then-else operator ( ? : )  to evaluate whether the method for the cart should be Cold or Standard.  Only one method with show, never both.

(NOT [NeedsColdShipping] and [$Name].Contains("Cold")) OR ([NeedsColdShipping] and NOT [$Name].Contains("Cold")) ? "" : [$Name]

Finally, since we have two methods configured in Fixed/ByWeight, then normally it will return those two methods.  Yet since we have a Restriction set up on Country, it would only return one method if the country does not support cold shipping.  Shipping Director has a special variable that can be examined after another shipping rate provider is called - [$ShippingOptionsCount],  Thus if we check that variable, and it is equal to 1, then we know the country is restricted.  Thus if only 1 method is returned and also the cart requires Cold, we can use the ErrorExit rule to show the message.



[NeedsColdShipping] and [$ShippingOptionsCount] = 1

"Sorry, your cart contains items requiring cold shipping, bu we cant do cold shipping for your country"

(Note that $ShippingOptionsCount is the actual count of returned other rate provider methods, not the count after any Name Expression exclusion.)

You can download the above configuration that you can then import into Shipping Director.

Comments (4)
Exclude Ground Shipping Based on State UPDATED- Friday, December 29, 2017

This is an update to the old blog

First, I recommend checking if a Country/State/Zip has been provided, because the “Estimate Shipping” will work even if they are not selected, and depending on rate calculation method (shipping plugin), you could get funny results, or an error. (Only US and Canada have states.)   For this, we use the ErrorExit record Type.  This will Exit if the Expression (condition) evaluates to true, and the customer will see the message calculated in the Description Expression.  Note, that this is a String Expression, so be sure to include quotes for a literal value.






Missing Country State Zip


Country = "" or Zip = "" or ("US,CA".Contains(Country) and State = "")

Description Expression

"Please Enter Country, State, and Postal Code"

Then, let’s say we want to prevent shipping if the State is Alaska or Hawaii.  We would use the ErrorExit type here too:






No Shipping to Alaska and Hawaii



Description Expression

"Sorry, we can’t ship to Alaska or Hawaii"

The condition Expression could have also been written as


State = "HI" or State = "AK"

But when using an “or”, be sure to use parenthesis if you have a more complex expression that includes “and”s too.

Alternately, you may just want to exclude just Ground shipping to Alaska and Hawaii.  For example, you want to use the Shipping.FixedOrByWeight rate calculation method, but don’t want to offer Ground to Alaska or Hawaii.  Then the above would instead be entered with an Option type:






Ship By Weight but no Ground for AK and HI



Rate Expression


Name Expression

"AK,HI".Contains(State) and [$Name].Contains("Ground") ? "" : [$Name]

For the Option type, the Expression field is a condition.  If it evaluates to true, then the option record is processed, otherwise it's skipped.  The Rate Expression can either be a decimal expression calculating the actual rate you want to charge, or the name of a shipping plugin.  The Name Expression calculates the shipping option Name shown to the customer.  However, if the Name Expression evaluates to blank (""), then Shipping Director will exclude the Option.  The [$Name] is a built-in variable that contains the Name of the shipping option as returned by the other rate calculation plugin.  So, here we are saying "if the state is Alaska or Hawaii, then exclude the named option, else show the named option".  The If-Then-Else is achieved using the " ? : " ternary operator -  condition ? if-true : if-false.

Comments (2)
A Product's Additional Shipping Charge is the only charge- Saturday, June 10, 2017

Let's say you've assigned Products their own "Additional shipping charge" and you want that charge to be the only charge for those products, and for any other prodcucts in the cart you want to calculate shipping using some 'standard' provider (like FedEx, or By Weight, etc.).    Shipping Director's Packing with Exclude Expression can handle it.  Here's the general idea:




Rate Expression

Description Expression


Exclude Addl Charge items

Items.Any(Product.AdditionalShippingCharge > 0)


Product.AdditionalShippingCharge > 0






Using Packing's Exclude Expression removes those items from "the cart", so that the Shipping.ByWeight provider does not see them.

Note, that nopCommerce will always add Product.AdditionalShippingCharge AFTER the shipping providers return their methods/rates.  Also, be aware the the AdditionalShippingCharge is per quantity - E.g. if quantity of an item in cart is "3", then 3 times the addl charge is added.  (You can read more about that in this blog about "Product Additional Shipping Charges apply only once to the cart item regardless of the Quantity".

Comments (2)
Per Item Shipping by Zone and Category- Saturday, June 10, 2017
Calculation Per item shipping charges can be a bit tricky.  Consider that the complexity is that the cart can contain multiple items in different categories, and thus you need to have some kind of "per item" shipping calculation that group items by category.  There are two ways to do this with Shipping Director.

1) "Configure" in Shipping Director all the zone/rate calculations.  See this basic example about per item shipping

Here's some basic configuration using an "if then else" operator " ? :" to calculate Zone from Zip (postal code) - e.g.

Integer       Zone      Zip <= "1000" ? 1 : Zip < "2000" ? 2 : Zip < "3000" ? 3 : 4

then for each category either count the items, or sum the Quantity - e.g.

Decimal     Category1Count         Items.Where(Product.HasCategory("Category1")).Sum(Quantity)
Decimal     Category2Count         Items.Where(Product.HasCategory("Category2")).Sum(Quantity)

then calculate total rate by summing individual category rates by zone:

Decimal     Rate            0
Decimal     Rate            [Rate] + Category1Count * ([Zone] = 1 ? 5.00 : [Zone] = 2 ? 7.00 : [Zone] = 3 ? 9.00 : 10.00)
Decimal     Rate            [Rate] + Category2Count * ([Zone] = 1 ? 6.00 : [Zone] = 2 ? 8.00 : [Zone] = 3 ? 11.00 : 13.00)
Option       Shipping       true         [Rate]

The above example does not take into account any consideration for different rates for the first item vs. additional items.  For example, if the first item ships for $5.00 and each additional item ships for $2.00.   First, you need to consider if the calculation is specific for Product quantity or Category quantity (as per above example "counts").

2)  If you have so many Zones and Categories and you frequently need to change rates, then you may want to set up some tables in SQL Server, and a custom Stored Procedure can be written to do the calculation.  Here's a blog with an example using Zone/Weight, but note it's 'total cart weight' and doing individual categories would need different coding.  Note that Shipping Director does not have a GUI to maintain the lookup tables.  You (or your IT person) would need some time of tool (like SSMS) to maintain (insert or update) rates.  (In the future, we plan on adding a feature to SD to allow uploading such data into SQL tables.)

(Also, note: if your products have Product Attributes that need special shipping rate calculations / additional $, then it becomes more complex.  And, you may want to 'validate' the postal code, because it is just a free form text field.)

Tags :  RatePerItem
Comments (2)
Product Additional Shipping Charges apply only once to the cart item regardless of the Quantity- Saturday, May 6, 2017

nopCommerce always adds the Additional Shipping Charges after getting rates from the Shipping Providers.  I've blogged about how to use the Shipping Director to conditionally negate the Additional Shipping Charges.  It's easily done by using the Surcharge Expression as described here:

In this example, we’ll show how to have the Product Additional Shipping Charge apply only once to the cart item regardless of the Quantity entered by customer.

The ‘magic’ is to calculate the Product Additional Shipping Charges that would be added by nopCommerce and use the Surcharge Expression to negate them.  But in this case, to also calculate, and add back, those charges as if only one charge per item rather than one charge per Quantity.










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






Items.Where(Product.AdditionalShippingCharge > 0).Sum( Product.AdditionalShippingCharge)





Shipping By Total



-[TotalAddlShippingCharge] + [PerItemAddlShippingCharge]

You can download the configuration import file by clicking on this link ShippingDirector (By Total - Only One Product Addl Ship Charge per item).txt

(UPDATE.  The above FixedByWeightByTotal used to be just ByTotal in older versions of nopCommerce)

Comments (2)
1 2 3 4 5 Next ... Last