Customization mapping in Magento

Customization mapping allows any extra information captured on the Magento side to be included on the order in Brightpearl. These can be captured in Brightpearl custom fields, or in some cases in the correct Brightpearl field:

Capture in Brightpearl custom field:

  • Delivery instructions
  • Lead source
  • Coupon code
  • Gift messages*
  • Comments (not in 'Order comments')
  • Custom fields added in Magento code
  • Custom fields added to Magento by an extension

Capture in the Brightpearl field:

  • Delivery date

* There are specific configuration options for gift messages if preferred

Note: Order comments will automatically be captured in the Brightpearl order notes and payment history without mapping.

Configuring customization mapping

Customization mapping is done within the Brightpearl Magento extension at:

Magento 1: Interactions > Brightpearl > Configuration > Interaction : Export order

Magento 2: Brightpearl > Brightpearl integration > Configuration > Interaction : Export order

The customization mapping:

  • Evaluate is where to look on the Magento order to get the information. This could be just one, or several places. Enter a comma separated list of field names as 'getMagentoDatabaseFieldName'. And to define a default to use when the field(s) is empty use [square brackets].
  • Transform can be used to specify whether the information should be formatted, like changing how a date is displayed.
  • Output is where the destination field in Brightpearl is defined.
  • On failure controls what happens when nothing is found in the fields and no default is set, such as skip to leave it blank.

Read more detailed explanations below.



The evaluate field is used to specify where in Magento the information can be found, and if it's empty what should be used instead.

How to complete the evaluate field

  1. Enter the Magento field name, or names, where the information is stored.

    Note: Field names are for demonstration purposes only and may not be the same in your system. Check field names with your Magento developer.

    For example:

    'getCouponCode' will look in the coupon code field.

    'getBillingCompanyName' will look for company name within the billing address**

    Enter a comma separated list of fields names to check more than one place on the order. They will each be checked in turn until an entry is found. For example, enter:

    'getBillingCompanyName,getShippingCompanyName,getDefaultCompanyName' will check the billing company name first and if there is nothing in that field the shipping company name will be checked, if there is something stored in that field then the evaluation is complete and that entry will be transferred into Brightpearl.

  2. (Optional) Use square brackets to define a default. The default is used when all the fields specified are blank. For example, enter:

    'getShippingComments,getOrderComments,[No delivery details included]'

    When both fields are blank 'No delivery details included' will be added to the relevant field in Brightpearl. To leave the field blank in Magento, do not provide a default.




This defines how to format the information found in the evaluate field.

This can be used to change the Magento data into a format accepted by Brightpearl, for example, ensuring a date is formatted in the correct way. It can also be used to perform a lookup from a list or include some additional string of text.

How to complete the transform field

To format a date:

Enter the date format to be applied within square brackets, for example, a date of 8th December 2017 could be transformed using:

  • [d M Y] to post '08 Dec 2017'
  • [M d Y] to post 'Dec 08 2017'
  • [d/m/y] to post '08/12/17'

To include a string:

Using sprintf expressions, the detail can be altered in ways such as adding the detail into a sentence. For example, when there isn't a specific field in Brightpearl and instead a generic custom field is used, it could be useful to label the type of information that's being posted, such as prefixing coupon codes with 'Coupon code:' - this transformation would be entered as 'Coupon code: %s'.

To do a look up from a list:

When the field in Magento could contain multiple different results, which each need to be transformed into something different the lookup list can be used. This might be used where the Magento database field stores details in a way which isn't useful to the user, such as a zero to mean no, a 1 to mean yes. To show 'Yes' or 'No' in Brightpearl use this transformation: {0=No,1=Yes} 


This field is used to specify where the information should be recorded on the Brightpearl order.

Use the output section to specify which field should be populated when the order is created in Brightpearl. This could be a standard Brightpearl order header field (i.e. not an order row), or it could be a sales order custom field.

How to complete the output field

  1. Enter a Brightpearl custom field

    If the information is to be entered into a custom field on the Brightpearl order use the following:


    The custom field code can be found in Brightpearl at Settings > Custom fields > Sales orders.

  2. Or, enter a standard Brightpearl field

    If the information is to be entered into a standard Brightpearl field enter:


    Fields supported: deliveryDate

On failure

An evaluation is considered a failure when no detail is found in any of the defined Magento fields and no default has been specified. Use this section to specify what should happen when this occurs, either:

  • Skip the field and continue
  • Warn with an alert on the Magento exceptions report
  • Stop the order from downloading 


What happens if I map to the same field twice?

The mapping table is read in order, this means that the field will continue to to override the field each time a mapping item is read. The last entry will be the one preserved and seen in Brightpearl.

Will updates made in Magento be shown on the mapped fields in Brightpearl?

No. The fields will only be set in Brightpearl when the order is first created.

Will updates made in Brightpearl be shown on the mapped fields in Magento?

No. Changes made in Brightpearl will not be reflected in Magento.

Have more questions? Submit a request


Please sign in to leave a comment.