The %Order.CustomValues% Token in nopCommerce 5.0: What Replaces It

A small change in nopCommerce 5.00 that customers notice before you do: an order email that says %Order.CustomValues% where details used to be. This page explains the new tokens, how to find the templates that need changing, and the replacement, based on the 4.90 and 5.00 source code.

What order custom values are

Custom values are extra details a plugin saves on an order: a payment reference, an invoice number, a pickup point, a delivery note from a custom checkout field. They appear on the order page in the admin area and, if the plugin marks them as visible to the customer, in the customer’s order details.

Up to 4.90, the %Order.CustomValues% token put all of them in an email as one list, one “Name: value” per line. None of the default templates used it, so it’s only in templates that you or a developer edited.

What changed in nopCommerce 5.00

In 5.00, each custom value belongs to a group, so a template can show payment details in one place and address details in another. The single token is replaced by one token per group:

Scroll the table sideways to see every column.

Each one uses the same “Name: value” format as before and is empty when the order has no values in that group.

Find the templates that use it

Check before upgrading, on 4.90. The free StorePulse plugin lists every message template that uses the old token, including translated versions, as part of its 5.00 upgrade check. Or run this on the database:

-- SQL Server. Read only.
SELECT Id, Name FROM MessageTemplate
WHERE Subject LIKE '%[%]Order.CustomValues[%]%'
   OR Body LIKE '%[%]Order.CustomValues[%]%';

-- Translated templates
SELECT EntityId AS TemplateId, LanguageId, LocaleKey FROM LocalizedProperty
WHERE LocaleKeyGroup = 'MessageTemplate'
  AND LocaleValue LIKE '%[%]Order.CustomValues[%]%';

Translated templates matter: a store with several languages can have the token in the German version of a template but not the English one.

Replace the token

In the admin area

1. 1Go to Content management → Message templates and open each template from the list.
2. 2Find %Order.CustomValues% in the body, on every language tab.
3. 3Replace it with the group you need, or with all four to keep the old result.
4. 4Save, then place a test order and check the email.

%Order.CustomValues.BillingAddress%
%Order.CustomValues.ShippingAddress%
%Order.CustomValues.Payment%
%Order.CustomValues.Shipping%

If you only need the details from orders placed before the upgrade, %Order.CustomValues.Payment% is enough: those orders didn’t record a group, and 5.00 shows their values as payment values.

You can make the change on 4.90 just before upgrading, but the new tokens show nothing on 4.90. Do it as part of the upgrade, or straight after.

With SQL, for many templates

-- SQL Server. Back up first. Shows every group where the old token was.
DECLARE @all nvarchar(200) = N'%Order.CustomValues.BillingAddress%'
  + N'%Order.CustomValues.ShippingAddress%'
  + N'%Order.CustomValues.Payment%'
  + N'%Order.CustomValues.Shipping%';

UPDATE MessageTemplate
SET Body = REPLACE(Body, N'%Order.CustomValues%', @all)
WHERE Body LIKE '%[%]Order.CustomValues[%]%';

UPDATE LocalizedProperty
SET LocaleValue = REPLACE(LocaleValue, N'%Order.CustomValues%', @all)
WHERE LocaleKeyGroup = 'MessageTemplate'
  AND LocaleValue LIKE '%[%]Order.CustomValues[%]%';

Then click Clear cache in the admin header so the changed templates are used straight away. Plugin developers who add custom values should set the group when saving them; values saved without one are treated as payment values. Our nopCommerce 5.0 overview lists the other changes that affect existing stores.

Frequently asked questions

Next steps

Run StorePulse on your 4.90 store to see whether any template uses the old token, along with the other 5.00 checks. The upgrade guide covers the upgrade itself, or you can have us handle the 5.0 upgrade, templates included.