Blog

If one of your suppliers (manufacturers) charges a handling fee for orders, you can pass that fee on to your customers.

Order	Type	Name	Expression	Rate Expression	Surcharge Expression
10	Reference	HasManufacturer	Product.ProductManufacturers.Any
20	Reference	hasManufacturerX	[@HasManufacturer](Manufacturer.Name = "X")
50	Decimal	SurchargeForX	Items.Any([@hasManufacturerX]) ? 10 : 0
100	Option	Shipping	true	Shipping.Fedex	[SurchargeForX]

Additionally, you can show the customer a description explaining that a fee has been added (it appears to customer under the shipping option name).  Just include a Description Expression on the Option line:

[SurchargeForX] = 0 ? "" : "A $" + [Surcharge].ToString() + " has been added because your cart contains a product from manufacturer X"

If you only want to charge the fee if the total amount of merchandise from that particular manufacturer is under $250, then we need to calculate the total $ amount of the items for that manufacturer, and then the expression for SurchargeForX would need to check if that total less than $250:

Modify the above - add line 30 for the total $ calculation and change line 50 to use the total:

Order	Type	Name	Expression	Rate Expression	Surcharge Expression
…
30	Decimal	TotalForX	Items.Where([@hasManufacturerX]) .Sum(Product.Price  * Quantity)
50	Decimal	SurchargeForX	[TotalForX] < 250 ? 10 : 0

Note, that the “the total amount of merchandise from that particular manufacturer” is the full price amount – i.e. does not include any discounts.

(Updated Aug. 2014.  If using nopCommerce versions prior to 3.00, then use ProductVariant.Product in plasce of just Product, and ProductVariant.Price in place of Product.Price)

In this Payment Director example, we only want to allow COD if the cart contains an IPod.

Set up a variable to calculate the condition, and then suppress all options except COD if the condition is not met.  For example, let’s say that you generally offer two payment methods – COD, and Credit Card (e.g. Authorize.net).  However, if the cart contains an IPod, then you only want to offer COD:

Order	Type	Name	Expression	Fee Expression	Friendly Name Expression
10	Boolean	Only_COD_Allowed	Items.Any( Product.HasCategory("IPods") )
20	Option	Payments.CashOnDelivery	Show
30	Option	Payments.AuthorizeNet	![Only_COD_Allowed]

(The “!” is the NOT operator)

Above we use a Category to distinguish IPod products.  But, you can do it any number of ways…

Product SKU(s)

                Items.Any( Product.Sku  = "12345" or Product.Sku  = "56789"  )

                Items.Any( "12345, 56789, 55555".Contains(Product.Sku) )

Product Name

                Items.Any( Product.Name.StartsWith("iPod nano") )

----------------------------------------------------------------------------------------------------------------------------------------------------------------

Here's the same for older versions of nopCommerce having Product Variants:

Order	Type	Name	Expression	Fee Expression	Friendly Name Expression
10	Boolean	Only_COD_Allowed	Items.Any( ProductVariant.Product.HasCategory("IPods") )
20	Option	Payments.CashOnDelivery	Show
30	Option	Payments.AuthorizeNet	![Only_COD_Allowed]

(The “!” is the NOT operator)

Above we use a Category to distinguish IPod products.  But, you can do it any number of ways…

Product SKU(s)

                Items.Any( ProductVariant.Sku  = "12345" or ProductVariant.Sku  = "56789"  )

                Items.Any( "12345, 56789, 55555".Contains(ProductVariant.Sku) )

Product Name

                Items.Any( ProductVariant.Product.Name.StartsWith("iPod nano") )

In evaluation mode, the Director plugins will allow 5 rate calculations from the front end store.   However, you can use the "Test" button in the Director configuration page as many times as you want; it's much easier to test from this page.  I suggest you "Test" as much as possible in the configuration page, and then do a final check when ready in the front end store. 

When you click on the Test button, you are presented with a dialog.  The default "0" means the currently logged in Customer (You, the admin :) .  You can enter a different Customer using Id, Username, or Email:

First, though, you must add items to cart for that user and go thru the checkout process to the point of selecting your shipping address*.  Then return to Director configuration page to test.  You can do this for the currently logged in user (you as admin), or as admin you can also "Impersonate" users and do same.  This allows you to set up many different test cases.

* Required for Shipping Director, for Payment Director, it depends on if you reference the shipping address, or cart items, or order totals in any Expressions.

The results of the test will appear in the upper left portion of the configuration page.   Green check marks are valid Options that the customer would see (rate amounts are not formatted for currency).  Red X's would be Errors (the messages that the customer would see, not the Fatal Errors that get logged in the System > Log).

Note!  Test calculation results will not take into account any nopCommerce core shipping "adjustments" - such as "Free shipping over X", "Free shipping if all items in cart are marked as Free Shipping", shipping discounts, etc.

In certain scenarios, you may want to look at Checkout Attributes to do some conditional processing.  For example, your shipping carrier might charge extra to ship to a residential address.  You could just add a Price adjustment to the Attribute Value, however there are some drawbacks to that:

1) The Price Adjustment shows up in the sub total area as an itemized item.  You may want it to just be included right in the shipping rate, and/or you may not want your customer to know what the surcharge is.

2) You can't apply it conditionally - e.g. don't want to include it for customers with certain roles.

3) You can't calculate the surcharge value (the price adjustment is fixed)

Older versions of Shipping Director required that you use  XML parsing via SelectSingleNode().  As of version 1.07 Shipping Director has the following built in variables (and Payment Director too):

$CheckoutAttributeValues

$CheckoutAttributeLocalizedValues

These are variables that contain the checkout attributes returned as a String of concatenated name:value pairs (colon separator).  Each pair is terminated with "|".

For our residential address example, we would set up a checkout attribute named "Shipping Address Type" using control type "radio button list", and we would add two Attribute Values: Residential Address and Commercial Address

Then, this could be used in the Option's Surcharge Expression:

   ([$CheckoutAttributeValues].Contains("Shipping Address Type:Residential Address") ? [Fedex Residential Surcharge] : 0)

(The decimal variable [Fedex Residential Surcharge] would be declared beforehand)

You use ErrorExit rather than OptionExit when you want to show an error message to the customer, and not allow them to continue the checkout process.   In nopCommerce 2.50, they introduced a hidden setting:  shippingsettings.returnvalidoptionsifthereareany; the default is 'true' which is to show successful options if any.   The setting was added so that when using multiple external shipping plugins\carriers, and one of the carriers returns with successful shipping methods, that it would still present them to the customer, rather than showing the failed carrier's error message.

If you check all your error conditions up front, then the default setting is OK.  If however, you check for errors in the middle of Option records, then you may want to change the setting to 'false' if using ErrorExit.

If you've set up your records as multiple OptionExit records expecting that the first matching one will be the only shipping method offerred to the customer, you might follow it with a final ErrorExit in case none of the conditions match:

OptionExit  <some condition> ...

OptionExit  <some condition> ...

ErrorExit     true ... "Error Message"

In this case either setting is OK.

For large $ orders, it may be desirable to enforce that the shipping address is the same as the billing address.  Use an ErrorExit to check it:

Type:	ErrorExit
Name:	Billing & Shipping must be same over X
Expression:	ShippingAddress.Address1 != null and [$SubTotalWithDiscounts] > 300 and Customer.ShippingAddress.Id != Customer.BillingAddress.Id
Description Expression:	"Sorry, for orders over $300 the shipping address must be the same as the billing address"

In the Expression, the term "ShippingAddress.Address1 != null" checks to see that we are not in "Estimate Shipping".  The Customer object is used by nopC to "save" the addresses selected during checkout.

P.S. The match above is done with the Address.Id .  That means it's the exact same address record.  If the customer may have entered two different address records with the same Street/City/Zip, then you can adjust the above to check the individual fields instead - e.g.

!(Customer.ShippingAddress.Address1 = Customer.BillingAddress.Address1 and Customer.ShippingAddress.ZipPostalCode = Customer.BillingAddress.ZipPostalCode)

Shipping Director introduced a Sort Expression in version 1.07.  The sort expression should evaluate to a string that represents an 'ordering clause'.  The ordering clause is one or more (comma separated) shipping option fields: Rate, Name, Description.  Each field can optionally be followed by ASC or DESC (the default is ASC = Ascending).   

Examples (Don't forget, it's a string Expression, so it's typically enclosed in double quotes):
"Rate ASC" 
"Name DESC" 

Example using ternary if-then-else  - If the cart weight <= 150, then sort by Rate, otherwise use the default sort. (The default is used when the expression results in blank string):
[$TotalWeight] <= 150 ? "Rate ASC" : "" 

In this example, we'd like to sort by Rate, but we want the "Pick up ..." option at the end, so sort by Name "prefix" then Rate:

"Name.SubstringBefore("" ""), Rate" 

FedEx Ground ($15.23) 
FedEx Express Saver ($51.51) 
FedEx Standard Overnight ($88.95) 
FedEx Priority Overnight ($108.35) 
Pick up at our warehouse ($0.00) 

UPDATE 2020-09-17  More example sort expressions:

Explicit sort of names (using ' ? : '  if-then-else operator):  

"Name = ""Ground"" ? 1 : Name = ""Priority"" ? 2 : Name = ""Special"" ? 3 : 4"

NOTE:  This is an old blog.  nopCOmmerce no longer has ProductVariant.  Just use Product.  E.g.  (Product.Height * Product.Length * Product.Width)

In a previous blog, I showed how in SD you can calculate the shipping method name to show the customer using the Name Expression field on an Option record.  If the expression evaluates to a blank string, then SD will suppress the method.  Here's another example of how, for external shipping rate methods (carrier plugins like FedEx, USPS, etc.) which can return many options, it may be desirable to conditionally eliminate some options - or only show a single option.

In this example we'll offer the following USPS methods

USPS Priority Mail® Large Flat Rate Box
USPS Priority Mail® Medium Flat Rate Box
USPS Priority Mail® Small Flat Rate Box
USPS Priority Mail®

But we only want to show one - the best match based on the volume of items in the cart:

Order	Type	Name	Expression	Rate Expression	Name Expression
10	Reference	ItemVolume	(ProductVariant.Height * ProductVariant.Length * ProductVariant.Width)
20	Reference	CartVolume	Items.Sum([@ItemVolume] * Quantity)
30	Option	US Mail	true	Shipping.USPS	[$Name].Contains("Small") and [@CartVolume] <= 75 ? [$Name] : [$Name].Contains("Medium") and [@CartVolume] > 75 and [@CartVolume] <= 546 ? [$Name] : [$Name].Contains("Large") and [@CartVolume] > 546 and [@CartVolume] <= 792 ? [$Name] : [$Name] = "Priority Mail" and [@CartVolume] > 792 ? [$Name] : ""

(Note!!  This blog has been updated. Due to changes in nopCommerce, use just "Product", not "ProductVariant.Product".)

A little while back we introduced some new functions that you can use to query your cart when creating complex shipping scenarios.  These are also available in Payment Director.  Here's some more details:

You can check if a product is in a particular category (or any category matching a pattern):

Product.HasCategory(categoryName)

Product.HasCategory(categoryId)

Product.HasCategoryMatch(regular_expression)

For example, you can check if there are any items in the cart that have a category that includes the word “Brushes”:

Items.Any(Product.HasCategoryMatch("Brushes"))

You can test if an item has a specific attribute/value (e.g. “Color”,”Blue”), or the specific attribute with any value (“Color”):

HasAttributeValue(attributeName, valueName)

HasAttributeValue(attributeName)

For example, you can get the quantity of items in cart that have the Vanilla scent:

Items.Where(HasAttributeValue("Scent","Vanilla")).Sum(Quantity)

 You can use the value id (integer) if you prefer (in case you change the name)

HasAttributeValue(valueId)

You can get a list of attribute values that the customer has applied to a cart item:

Item.GetAttributeValues(attributeName, valueSeparator)

Item.GetAttributeValues(attributeName)  // value separator defaults to “,”

Of course it does not need to be a list – for example, if you have a “Size” attribute, then you can just get the value the customer entered for the Size.  For example, if you have many products in the cart with a Size attribute, you can calculate a shipping rate based on the size values – let’s say you want the rate to be on a per item basis, for each ($3.33 * Size * Quantity)

Items.Where(HasAttributeValue("Size")) .Sum(3.33 * Decimal.Parse(GetAttributeValues("Size")) * Quantity)

(You can do date/time calculations too – e.g. … .Min(DateTime.Parse(GetAttributeValues("DeliveryDate")) )

Here’s an example of how the new methods make your expressions shorter and more readable:

We’ve blogged before about “Free Shipping over $X - unless there are any excluded items”.  We used a Reference type variable to shorten the query:

Order	Type	Name	Expression	Rate Expression
10	Reference	categories	Product.ProductCategories
20	Reference	hasExcludeFromFreeOverX	[@categories].Any(Category.Name = "Exclude from Free Over X")
30	OptionExit	Free Shipping	[$SubTotalWithDiscounts] > 50 and !Items.Any([@hasExcludeFromFreeOverX])	0
40	Option	Standard	true	10

Here the same scenario as above with new HasCategory method -

Order	Type	Name	Expression	RateExpression
30	OptionExit	Free Shipping	[$SubTotalWithDiscounts] > 50 and !Items.Any(Product.HasCategory("Exclude from Free Over X"))	0
40	Option	Standard	true	10

Payment Director allows a store owner to conditionally determine which payment methods to show the customer and to calculate additional payment fees.  Let’s start with the basics…

By default, all Payment Methods that are marked Active in admin > Configuration > Payment Methods are available to your customers.   Then, you set up Payment Director Option records as needed to hide options and calculate fees.   Each option’s Expression field is evaluated, and if ‘true’ (or ‘Show’) then the option will be presented to the customer.  If ‘false’ (or ‘Hide’), then the payment option is removed.  You can include an Option record for all your active payment methods, but if only some are conditional, then it’s easiest to just have Option records for those;  if an active payment method is not included in payment director, then it will automatically be shown to the customer.

Here are some example scenarios for offering payment methods, and their Option records/expressions:

Offer 'payment in store' method only when "In-Store Pickup" shipping method selected:

  Option  Payments.PayInStore         ShippingOptionName = "In-Store Pickup"

Local Deliveries can include CashOnDelivery:

  Option  Payments.CashOnDelivery Customer.ShippingAddress.ZipPostalCode.StartsWith("100")

Customers in role "Members" can include PurchaseOrder  (use the role's System Name):

  Option  Payments.PurchaseOrder      Customer.IsInCustomerRole("Members")

If an admin is impersonating a Customer, then use Manual Credit Card, otherwise the customer enters a credit card that Authorize.Net will process:

  Option  Payments.Manual             OriginalCustomerIfImpersonated != null

  Option  Payments.AuthorizeNet       OriginalCustomerIfImpersonated = null

Only offer Paypal if a FedEx shipping method was selected (a method that has tracking :)

  Option  Payments.PayPalStandard     ShippingOptionName.StartsWith("FedEx")

Only offer credit card if there are  no Gift Cards in the cart

  Option  Payments.Manual           NOT Items.Any(Product.IsGiftCard)

When entering records in the Add new 'Payment Director' record dialog, select Option in the Type  field drop down, and then the Payment Name field will present a drop down with only active payment methods.    

Then, enter an expression that evaluates to a Boolean (true or false) using one or more or more of the following operands:

• Customer  (also has function IsInRole("systemname") )
• ShippingAddress
• ShippingOption  (.ShippingRateComputationMethodSystemName, .Rate, .Name, .Description)
• ShippingOptionName
• Items  (shopping cart items collection)
• OriginalCustomerIfImpersonated (if != null then you are impersonating)
• WorkingLanguage  (.Name, and .LanguageCulture)
• WorkingCurrency (.Name, .CurrencyCode, .Rate, and .DisplayLocale)
• TaxDisplayType  (IncludingTax = 0, ExcludingTax = 10)
• CreditCardType  (e.g. for Authorize.NET :  "Visa", "MasterCard", "Discover", "Amex")
• PurchaseOrderNumber
• OrderTotalWithoutPaymentFee
• FriendlyName

   (UPDATE: Here are more operands added added from 3.60 and on)

• CurrentStoreId
• CurrentStoreName
• IsImpersonating (Boolean)
• CustomValues  
  • (The nopC PaymentInfoCustomValues is a Dictionary of Key/Values set by other payment plugins.  This variable converts that dictionary to a string of "key:value|key:value|...".  You can use CustomValues.StringBetween("key:","|") to get a value.

Here are some examples:

We'll introduce more features in the next blog :)