Downloading Orders (Magento)

 All documentation in this document relates to a previous version of the Brightpearl Magento extension which will be deactivated in 2018. If you are using this previous version, please contact us about upgrading.

For help with the current extension, please see the Magento section. 

All new orders placed through Magento will be automatically downloaded into Brightpearl every 15 minutes and the download can be manually triggered from the recent sales list. Each order download will check the last 7 days for any orders which don't already exist in Brightpearl. This means that if a downloaded order is subsequently deleted in Brightpearl, it will be re-downloaded if it was placed within the last 7 days.

A new order is placed on the sales order status assigned to the Magento sales channel in Brightpearl, unless an alternative order status is connected. An order will be downloaded even if it has already been marked as canceled in Magento, but will be placed on the canceled status in Brightpearl. 


Match existing contacts

When an order downloads from Magento it will search for an existing contact using the customer email address.

If an existing customer is found the Brightpearl record becomes permanently linked to the Magento customer record. The order, and all future orders, will be created against that customer record.

Note that orders cannot be downloaded against supplier (vendor) records.

Create new contacts

If no contact is matched in Brightpearl a new customer record is created and permanently linked to the Magento customer record. The order, and all future orders from this customer, will be created against this customer record.

Updated emails

If a customer changes their email address on their account with Magento it will not be updated on the customer record in Brightpearl. However, orders will continue to download against the same customer record since they are permanently linked. When this occurs a notification is added to the integration alerts and a warning message is visible within the order that indicates to the user that the customer email address no longer matches the one on Magento and needs updating in Brightpearl.

It is not possible to unlink a Brightpearl customer from a Magento customer.

Newsletter setting

Contacts are added to Brightpearl with the opt-in for email marketing on by default, regardless of anything that the user chose during your Magento checkout.

Products & inventory

Connected products

Where the Magento product is connected to a product in Brightpearl that item will be added to the downloaded order. If inventory is available for that item then it will be allocated to the order.

Unconnected products

If the Magento product is not connected to a product in Brightpearl then a miscellaneous and non-stock tracked line item is added using the item name from Magento.

Custom options

Custom options added to simple products in Magento within the “Custom Options” tab will display on orders download into Brightpearl. These custom options are often used for things such as gift messages, engraving or customized printing services. These types of custom options are created directly on the product in Magento but will be included with the product name once an order for the item downloads into Brightpearl.

This feature is currently available for options defined directly against a simple product in Magento. We will be adding the ability to download custom options set on a configurable product in our next release.

Example product setup in Magento and online visibility:

release notes customer options

Order for the product downloaded into Brightpearl:

release notes custom option

Prices & tax amounts

All prices and tax values on the order are provided by Magento and ignore Brightpearl price lists and tax calculations.

Price mode

Each order in Brightpearl has a price mode which indicates whether the displayed "prices include tax" or "prices exclude tax". This will be automatically set for a Magento order initially based on the Brightpearl price list setting "show prices as gross". Where a price list is set to "Yes" show prices as gross, the price mode will be "prices include tax", if the setting is "No" the price mode will be "prices exclude tax". When the price mode = "prices exclude tax" the tax column becomes available on the product table.

price mode

However, in some cases the "prices include tax" mode based on the price list can be overridden and the order will show a price mode of "price exclude tax". This will happen when Brightpearl notices that its own tax calculation would have given a different tax value than Magento has provided - this happens due to differences in rounding rules between the systems. When this happens the tax column is required so the tax value applied can be displayed - the tax column is only displayed when the price mode = "prices exclude tax". Evidence that this has happened can be seen where the tax value field for a line on the order is shaded yellow.

manual tax

Discounts & coupons

Discounts and coupons can be created and applied when orders are placed through Magento. When a discounted order is downloaded into Brightpearl the discount or coupon detail will not be included. The list price will be the original price (before the discount), and the price column will show the new discounted price.

For discounts to be correctly downloaded into Brightpearl, you will need the following tax settings in Magento:

US Magento account settings

At System > Configuration > Sales > Tax .

US Magento tax settings.png

UK Magento account settings

At System > Configuration > Sales > Tax .

UK Magento tax settings.png

How to report on discounts in Magento

To report on discounts in Magento, go to Reports > Sales > Coupons .

shipping charges

Shipping charges

A shipping charge is added as a line item on the order.

Tax codes

Tax codes are assigned to line items by Brightpearl - using the integration tax rules.

The  "T9 Not rated" for UK and "- Not rated" for US tax code will always be applied to shipping charges where tax is not applicable for shipping in the Magento settings.

The company default tax code set at Settings > Company > Accounting: tax will always be applied to shipping charges if tax is applicable to shipping charges in the Magento settings. The tax value is always provided by Magento.

Shipping method

Each order in Brightpearl can be assigned a shipping method, which can be used for filtering the sales list. If a shipping method exists in Brightpearl with a code matching the shipping method in Magento then it will be automatically assigned to downloaded orders.

Shipping methods must be named using the Magento API format of Carrier_method, e.g. “UPS_XPD” is used for UPS Worldwide Expedited and Flat rate is “Flat rate_flat rate”. 


Captured payments will download into Brightpearl with an order. This will mark the order as paid, create a sales receipt and accounting journal.

Captured only payments (charge at point of shipping)

Payments that are authorized when the order is placed but only captured later, for example when the order is shipped, cannot currently be downloaded into Brightpearl.

Part payments / deposits

Part payments and deposits cannot currently be downloaded. Only payments for the total order value are downloaded.

Order status of new orders

Downloaded Magento orders will automatically be assigned the sales order status chosen on the sales channel setup in Brightpearl. However, this will be overridden if the status of the order in Magento has been linked to a different order status in Brightpearl.

If an order has a status of "canceled" on Magento at the point it is downloaded, Brightpearl will automatically assign the canceled status as defined in the sales settings.

Order references

Downloaded Magento orders will display the Magento order reference in the Customer ref field of the Brightpearl order. This can be used for searching and can also be included on templates.

customer ref

Order comments & gift messages

Order comments added during checkout will download with the order into Brightpearl. They can be seen within the notes and payment history tab on the Brightpearl order.

notes payment history

Order comments can be added using extensions like  Magemaven OrderComment .

magento order comments

Order comments can also be made visible in Brightpearl directly on the sales list by opting to "show items and notes on order listings" at Settings > Sales > Sales settings .

show comments

Magento gift messages entered at checkout are not downloaded.

Custom fields

Brightpearl custom fields cannot be connected to Magento, for customers, products or orders.

SmartForms can be added to the Magento site in order to capture additional customer information straight into Brightpearl.

Related how to guides - Downloading orders from Magento

How to download Magento orders

Brightpearl will check for new orders every 15 minutes, but the order download can be manually triggered:

  1. Go to  Sales > Recent Sales/Quotes .
  2. Click the  Download orders now  button.
  3. Leave the program to run and click the  Refresh  link to check if it is complete and see your new orders. Once the "Refresh" link changes back to "Download" the process is complete.

You can continue to work whilst waiting for orders to download.

Note : Do not create orders using the same email address as a staff member. These orders will not download.

How to connect Magento & Brightpearl order statuses

  1. Go to  Settings > Sales > Order statuses .
  2. Click the  Connect  link next to the relevant status.
  3. In the pop-up window click the  Connect to link.
  4. Enter the Magento order  status code  into the blank field and click  Connect . These can be found in Magento at System > Order statuses .

What happens if an incorrect status code is used?

You will not be notified if an incorrect status code is entered. It will appear as though it is connected. However, when you update an order to this status in Brightpearl it will be give a blank order status in Magento. This means that no email confirmations you have set will be sent.

Have more questions? Submit a request


Please sign in to leave a comment.