Implementation of 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

There are various stages for implementing a Magento account with Brightpearl.

Install the Magento integration

The first thing you need to do is switch on Magento in your Brightpearl account.

How to install the Magento app

  1. In your Brightpearl account go to  App Store > Magento .
  2. Turn on the Magento integration.

Step Install turn on

Prepare a Magento account for integration

You will first need to confirm that your Magento account will allow Brightpearl access over API, basically, will your Magento account talk to your Brightpearl account (using what are called “Web Services”).

You will then need to give Brightpearl access to your Magento account using a role & user.

Magento Community users will also need to check the WS-I Compliance settings.

How to check the Magento SOAP extension

Type the relevant address below into your web browser using your own store name in place of the "mymagentohost":

Magento Community:

Magento Enterprise:

(change mymagentohost to the name of your store)

If you get a load of HTML code displayed it means it is working. As long as you get some message back, you have API access.

If you don’t get a response from this URL you will need to install or configure the required SOAP extention for your web server. Contact the person that installed your Magento system and ask them to enable the SOAP extension.

How to create a role in Magento

  1. In Magento, go to  System > Web Services . Then select  SOAP/XML-RPC-Roles .
  2. Click the  Add New Role  button.
  3. Enter a role name and select  All  for the resource access, then save.
    Step Install Role

How to create a user in Magento

  1. In Magento, go to  System > Web Services. Then select  SOAP/XML-RPC-Users.
  2. Click the  Add New User button.
  3. Enter some account information for your user and assign them to your new role, then save.
    Step Install User

How to set WS-I Compliance in Magento

  1. In Magento, go to  System > Configuration > Services > Magento Core API .
  2. In the WS-I Compliance field select No.
  3. Save the configuration.

Connect a Magento account to Brightpearl

You are now ready to connect a Magento account. This is done once per separate Magento account, even if the account has multiple stores set up. All of the following setup steps will need to be repeated for each Magento account connected.

If you are integrating a test environment you will need to perform the full integration process over again for your live server. It is not possible to simply switch the store setup in Brightpearl to point to a different URL.  Changing the URL in the store setup is only part of the work.

When a Magento test environment is cloned to a live server it is not guaranteed that each and every resource (products, customers, attributes, product types etc.) will have exactly the same ID number. Brightpearl works by connecting to those ID numbers. This means that if an ID number has changed, that Brightpearl will either not be able to find the record to connect to, or worse, connect to the incorrect record.

How to connect a Magento account

  1. In Brightpearl, go to  Settings > Brightpearl Apps > Magento .
  2. Click the Add a store button to begin.
  3. Use the descriptions below to define the store details.
    Step Install Channel
  • Store name
    Give your store a name, this will be used throughout Brightpearl and will become your sales channel name; used for reporting on where your orders come from.
  • Store URL
    Enter the URL for your Magento website, this will be used by Brightpearl to access your account. The URL should be of the format
    Note: If you have not fully launched your Magento webstore you will need to remove the "WWW." bit!
    Note: If you have set your own domain in Magento you will need to enter it the same here.
  • Which Magento product are you using?
    Select which Magento account type you are connecting. This ensures Brightpearl communicates with the relevant web services.
  • Magento user
    Enter the name of the User you created in Magento (in the example we gave “Brightpearl”).
  • Magento API key
    Enter the password you set as your API key when you created your user in Magento.
  • Order Status for new Orders
    Select the Order Status to be given to new orders received into Brightpearl from Magento.
  • Bank account to allocate payments into
    Select the bank account nominal code where payments received via your Magento site will be posted in accounts. You can define a separate one for PayPal payments at Settings > Brightpearl Apps > PayPal.
  • Root Category ID
    This is the top level category ID in Magento where all your categories to stem from (or will stem from); as standard it's usually "2".
    To find the root category ID in Magento, go to Catalog > Manage categories, select the top level category on the left to display the settings. Find the ID number in brackets after the category name.
  • Select Brightpearl categories to sync with Magento
    We recommend you set this to "Don't sync categories" during the implementation on Magento with Brightpearl.
  • Add option values to Magento name
    Specify whether you want to add product option values (such as small, medium, large, red, blue or green) to the product name in Magento. Not relevant for an SKU-to-SKU connection.
  • What do you want to sync between Brightpearl and Magento?
    Select what information you want to update on Magento, select from Inventory, Pricing and Orders.
    Note: Product details sync is no longer supported and will shortly be removed.

Define sales channel settings

A Magento Sales Channel is created for you as soon as you have created a Magento Store (as above). Not only can the Sales Channel be used for reporting on your sales, but it defines the Brightpearl Warehouse used for inventory management (you may only have one warehouse) and the default Price List (you will learn how to connect more later), so you should confirm the settings are right before you go any further. You can change any of these settings later.

  1. Go to  Settings > Company > Channels .
  2. Locate the channel relating to the Magento account, it will have the same name as the store you added.
  3. Click the edit pencil and a pop-window is displayed.
  4. Use the descriptions below to define your channel settings.
  • Warehouse
    The channel will always automatically select your first warehouse (ID 2). The selected warehouse is where Magento will read and update inventory levels, and orders will be assigned to.
    Note: If you don't have any inventory at that warehouse when the order comes in, you can update the order and assign it to a different warehouse manually in Brightpearl.
  • Price List
    Your first "sell" price list will automatically be selected. It is this that defines what prices will be updated to Magento. You can easily amend this by clicking on the pencil icon.
  • Team
    If you want to assign all Magento orders to a Sales Team you can select it on the channel. By default, no team is selected.

Connect Brightpearl order statuses to Magento order statuses

This step is optional for using the Magento integration, but is required to control the initial status assigned to downloaded orders and to update order statuses in Magento as the order progresses.

Initial download status

The default order status assigned to downloaded orders is defined on the Magento store setup in Brightpearl. This will always be assigned to downloaded orders except when:

  • The order has a status of "canceled"
  • The order status is linked to a different status in Brightpearl

Order status update

Once the order has been downloaded into Brightpearl, any changes to the status made in Magento will not update the order in Brightpearl. However, connecting order statuses allows Brightpearl to update the status shown in Magento.

When the order in Brightpearl is moved onto a connected status the update will be sent to Magento.

Sales order statuses

Find Brightpearl sales statuses at Settings > Sales > Sales statuses.

Find Magento order statuses at System > Order statuses.

How to connect order statuses to Magento (update order statuses)

Connecting Brightpearl order statuses to Magento order statuses means that it is possible to update Magento as the status is changed in Brightpearl.

  1. Log in to your Magento admin account and go to System > Order statuses .
  2. Make a note of the Status name or  Status Code of each status that is to be connected to Brightpearl. These may differ from account to account if order statuses have been customized.
  3. In Brightpearl, go to  Settings > Sales > Sales statuses .
  4. Click the Connect link against the order status to be linked to Magento.
    Brightpearl order statuses
  5. Select the Magento store you are connecting to.
    Connect status
  6. Enter the  status name or status code  into the field exactly as it appears in Magento and click  Connect . An incorrect entry will cause orders to be assigned a blank status in Magento. If this occurs the code can be edited, but the status won't automatically update.
    enter status code2

Connect additional Brightpearl price lists to Magento customer groups

Additional Brightpearl price lists can be connected to Magento Customer Groups. This allows you to apply different pricing for each customer group as well as upload price breaks to apply volume discounts. This step is optional.

The sales channel for your Magento account in Brightpearl allows a single price list to be selected in order to update the main price on the product in Magento. Additional price lists can be connected to customer groups in Magento allowing different prices to be applied to products for certain customer groups. Connecting price lists in this way will also allow tiered pricing (price breaks or volume discounts) to be synchronized with Magento.

Prices are always uploaded at net of tax.

The main price assigned to a product on Magento is uploaded from the Brightpearl price list selected on the sales channel at  Channels > Magento > Settings .

Channel settings2

How to connect price lists to Magento customer groups

  1. In Brightpearl, go to  Settings > Products / Inventory > Price lists .
  2. Click the  Download data now  button to open the connection between Brightpearl and Magento. This may take a few minutes. Click the refresh link to check if the process has completed. When it is completed the download button will re-appear and a time stamp will indicate the connection was made.
  3. Click the  Connect  link next to your price list.
  4. In the pop-up window click the  Connect to Magento  link to search for matching customer groups in Magento.
  5. The customer groups from Magento will be listed. Click the  Connect  link next to the result you want to connect to.
  6. Continue to connect your prices lists in this way.

Transfer & connect Brightpearl products to Magento

For all integrations, Brightpearl will hold the master product list - a complete list of all SKUs sold across all sales channels. Magento will need a record for every SKU sold through Magento and each one will be connected to the relevant record in Brightpearl.

Understand variants, configurable products, custom options & bundles

It is important that you understand how variants and bundles are handled in Brightpearl and Magento and how they are integrated.

Each variant in Brightpearl will have a matching simple product in Magento but you will need to manually create a configurable product directly in Magento to group those simple products. This configurable product is not connected to Brightpearl.

We recommend that you create bundles directly in Magento. These bundles will not be connected to Brightpearl. Alternatively you can create the bundles in Brightpearl, but there are limitations to this. If you create a bundle in Brightpearl and in Magento they should not be connected.

At this stage in the implementation process you will need to look at where your products currently exist and how you will get them to be in both applications. You will also need to be aware of the setup and structure of variants/configurable products, bundles and custom options.

Every product must pre-exist in both Brightpearl and Magento. Every product must:

  • Have an SKU
  • That SKU must be unique
  • That SKU must be less than 32 characters
  • That SKU must be the same in Brightpearl and Magento

It is not possible to automatically transfer products between systems, however, both Brightpearl and Magento provide import and export routines for creating and updating product data.

Once products have been created and SKUs updated so that they match between Brightpearl and Magento you can begin the connection process.

How to connect products to Magento SKU-to-SKU

  1. In Brightpearl, go to  Products > List products / services .
  2. Select each product to be connected / published on Magento. We recommend connecting products in batches of no more than 500 items to ensure your Magento server is not overloaded. If you encounter connection issues you should try smaller batches.
  3. Click the  Add or remove from channels  button at the top of the listing and select  Manage ecommerce channels .
  4. Select the relevant action and choose the Magento store before clicking  Update selected items .
    Magento Step Manage channels

Which option should I use?

Make available and continue selling when out of stock
Connect the selected products to Magento. The products are set to "enabled" and will continue to sell even when the item is out of stock.
If you choose this option for a product that is already "disabled" on Magento; then the product will be connected, but we won't change the status to "enabled" for you. You would need to reselect this option to show that you want the product to be "enabled" in Magento.
Make available and stop selling when out of stock
Connects the selected products to Magento. The products are set to "enabled" and but will be set as "out of stock" when the inventory level is zero, preventing customers from purchasing the item. Magento may be set to hide out of stock items so if you still want the listing to display make sure you check your inventory configuration. 
If you choose this option for a product that is already "disabled" on Magento; then the product will be connected, but we won't change the status to "enabled" for you. You would need to reselect this option to show that you want the product to be "enabled" in Magento.
Disable on channels
The selected products remain connected but the Magento product is set as "disabled" so that it no longer displays online.
Disconnect from channels
Breaks the connection between the selected Brightpearl and Magento products completely. The act of disconnection will not delete the products. This can be done to stop the synchronization of a product or will be needed if the product has been deleted in Magento and needs reconnecting.

What if I change my mind?

The above process can be repeated every time you wish to change the connection option for a product, or group of products.

Synchronize inventory levels & prices on Magento

After the products have been connected Brightpearl will be able to manage inventory levels and prices on Magento - Brightpearl becomes the inventory and price master. Note that at no point will changes made to inventory levels or prices directly on Magento update Brightpearl.

Inventory and price synchronizing can be activated or deactivated on the store setup in Brightpearl.

It is important to note at what stage inventory and prices are synchronized, as simply connecting does not mean that Magento is completely synchronized with Brightpearl. In this section you will learn how to bring all your inventory and prices in line.

Inventory levels are updated:

  • When the product is first connected to a product in Magento
  • When the connected product is saved with or without any changes having been made
  • When the connected product is included on a product import with or without any updates being made
  • When the product is disconnected and reconnected to Magento with or without any updates being made
  • When the product price is updated in Brightpearl and uploaded to Magento - includes updates made using the price list import
  • When the on hand inventory level at the chosen warehouse changes due to sales order allocations, inventory corrections, receiving items on sales credits, purchase orders or warehouse transfers

What doesn't synchronize inventory:

  • Connecting products SKU-to-SKU (current bug BP-9552)

Prices are updated every time:

  • A product import is done (updates are made for products included on the import file regardless of whether any changes were made)
  • A price list import is done for the synchronized price list (updates are made for products included on the import file regardless of whether any changes were made)
  • A product is re-saved (regardless of whether any changes have been made)
  • A product is disconnected and reconnected to Magento with or without any updates being made

What doesn't synchronize prices:

  • Connecting SKU-to-SKU (current bug BP-9552)

Synchronize all

Since Brightpearl is the inventory master we recommend that you perform a stock take and perform an update by CSV for all products. This ensures that Brightpearl has the correct current levels and that Magento is synchronized with Brightpearl. As long as all products are included in the import file, whether the levels have changed or not an update to inventory levels and prices will be triggered.

What if I don't do a stock take?

If you choose not to do a stock take right now then you will gradually see Magento and Brightpearl figures synchronizing over time. This is because any changes to on-hand inventory levels and prices will trigger updates. As updates are sent, Brightpearl will override the values in Magento.

How to update inventory levels by CSV (importing)

Inventory levels in Brightpearl can be updating in bulk by importing a CSV file.

Where a product is connected to a sales channel, those inventory levels will be updated on the sales channel where the inventory level has changed.

Follow these steps to update inventory levels by CSV:

  1. Create your file ready for import. This can be done by first exporting a list of your products and removing unwanted columns. Export your products from Products > List products .
    Howto Update inventory by CSV 1
  2. The import file must be a CSV file, and contain only, and all of, the following columns:
    Howto Update inventory by CSV 2
  3. Save the file as a CSV type file.
  4. Now import the file at Products > Update inventory by CSV . Make the following selections:
    Product ID :
    This is the Brightpearl product number assigned by Brightpearl when a product is created. It is displayed in an exported file of products and can be used to match items during an update.
    SKU :
    This is the Brightpearl product SKU. It can be used to match items during an update instead of using the Product ID. If it is blank it cannot be used for updating. SKUs can only be updated using the Product Import, not the inventory level import.
    - Quantity :
    The import can be used to adjust the current inventory level by this quantity (increase or decrease by this quantity) or to set it to the quantity in this field.
    Location :
    If warehouse locations is activated you will need to specify into which location the items are being added or from which to be removed. If it is not activated leave the fields blank.
    Item cost price :
    When increasing or decreasing inventory levels accounting entries are made to adjust inventory asset values. The accounting entries are made using the cost price of the product set here or from the 
    Match product by :
    SKU or Brightpearl ID. Both these columns are included in your file. If you don't have SKUs use the product ID.
    Quantity :
    Specify whether the file contains the actual quantity in stock, or a figure by which the existing inventory level should be changed by (e.g. 1, or -1, to increase or decrease by 1).
    Warehouse :
    Select the warehouse your are adjusting the inventory level in.
    Use cost price from :
    A cost price is required for making the accounting entries for each stock correction. The price can be taken from a price list or from the file.
  5. Browse for and select the CSV file to import.
  6. Click the Update inventory button to update the inventory levels. This cannot be reversed.


I keep getting an error message saying, "Stock correction failed. Not enough on hand availability of product at specified location to perform stock correction". What do I need to do?

It is not possible to reduce your on hand stock quantity to below zero. Although your "in stock" quantity may be remain above zero if you were to reduce it, some of the stock may be allocated to sales orders and therefore your on hand level is less and would fall below zero. Take the following example:

In stock = 10

Allocated to sales orders = 9

On hand = 1

Import attempts to reduce by 5 and fails with the error.

You will need to un-allocate your stock before reattempting the import.

Review product display & price settings in Magento

The way your products and prices display on Magento is controlled by numerous settings. Here are some key settings and controls you should check in Magento:

  • Since Brightpearl only uploads net prices, all catalog prices should be set as excluding tax. If this is not set then tax will be added twice in Magento.
  • To display prices on the website as including tax the price display needs to be set as including tax.
  • Set out of stock products to display online otherwise they will be hidden.
  • Add products to categories in Magento. If they are not in a category they will not display online.

How to display products & prices on Magento

Set catalog prices as exclusive of tax

  1. In Magento, go to System > Configuration > Sales > Tax .
  2. Expand the Calculation Settings section.
  3. For Catalog prices select  Excluding tax .
    Magento Step Catalog price net

Display prices inclusive of tax

  1. In Magento, go to System > Configuration > Sales  > Tax .
  2. Expand the Price Display Settings section.
  3. Set the Display Product Prices in Catalog field to Including tax .
    Magento Step Display prices gross

Displaying out-of-stock products

  1. In Magento, go to System > Configuration > Catalog > Inventory.
  2. Expand the Stock Options section.
  3. For the Display Out of Stock Products section select Yes .
    Magento Step Display out stock

Add products to categories

For your products to display online you will need to make sure they are in at least one category on Magento.

Check the connection & place test orders

The Magento set up is complete. You can use your Magento Dashboard to check for any connection issues.

If your Magento is currently not live then you will need to return to your set up in Brightpearl to ensure your Magento account is still connecting. Once your Magento site is launched the URL may also be changed, You will therefore need to update it in Brightpearl to maintain the connection.

Placing test orders

If you place test orders through Magento to download into Brightpearl ensure that you place the order with an email address which is different from the staff members in your Brightpearl account. An order placed using a staff members email address cannot be downloaded.

How to check if Magento is connecting

  1. Go to Channels > Magento > Dashboard .
  2. If Brightpearl is unable to connect to Magento you will see an error on your Magento dashboard:

Magento Step of Install connect Cant connect

How to check your Magento store URL

If you are seeing this image on your Magento Dashboard the issue could be as simple as an incorrect URL entered into the store setup.

Cannot connect to magento2

What is my store URL?

Your store URL is your website address. It’s how people get to your website. The URL of your store will depend on a couple of things:

  • Whether you have launched your Magento website
  • Whether you’ve set a different base URL in your Magento admin panel

You will need to enter the correct URL into the store setup in Brightpearl to open the connection with your Magento account. If your URL is wrong Brightpearl will be looking in the wrong place and won’t connect!

Which URL?

When you first get your Magento account your website URL will be the Magento default:



You get the idea!

Notice how there is no “www.” in any of those addresses. Before your store is launched and pushed live it won’t have the wwws! So this is how you enter it into the store setup in Brightpearl.

When you launch your store the connection will be lost, because your URL changes to include the www. All you need to do is edit the URL on the store setup in Brightpearl to re-establish the connection.

If you have entered your own URL into the Magento configuration then you’ll need to enter this URL into the setup in Brightpearl. You can find your base URL in Magento at System > Configuration > Web .

Changing the URL

  1. Visit your Magento Dashboard at Settings > Brightpearl Apps > Magento .
  2. Click the Edit store link in the top right, above the message.
  3. Check the Store URL is the correct URL for the Magento store. Before the Magento store is live the www. will need to be excluded, once the store is launched the connection will be lost until the www. are added.
    Store URL
  4. Save the changes.
Have more questions? Submit a request


Article is closed for comments.