Configuring the Brightpearl Magento extension

This article will go through each setting available for configuration.

Shared: General settings

Use these settings to specify which sales channels are applied to sales orders created in Brightpearl off the back of Magento orders.

Scope: A channel can be set globally, per website or per store or per store view, allowing for segregated reporting in Brightpearl. Brightpearl reporting will allow grouping of these channels.

Find them at:

Magento 1: Interactions > Brightpearl > Configuration

Magento 2: Brightpearl > Brightpearl integration > Configuration

Field Description
Brightpearl channel

Select the channel used in Brightpearl for recording sales

Shared: Stock settings

These settings are shared across the following interactions:

  • Import stock levels (bulk)
  • Import stock levels (real-time)

They control which Brightpearl warehouses are used for managing inventory levels in Magento. These settings apply to both the bulk and real-time stock level imports.

Scope: Magento only supports global inventory levels, so these settings will apply globally.

Find them at:

Magento 1: Interactions > Brightpearl > Configuration

Magento 2: Brightpearl > Brightpearl integration > Configuration

Field Description
Brightpearl warehouse(s) Select one or more warehouses (hold down CTRL). The combined on-hand inventory level from the selected Brightpearl warehouses will be used to update inventory quantity in Magento
Skip unmanaged

Specify whether products which are non-stock tracked, or not managed, should be skipped when attempting to update inventory. This will ensure any non-stock tracked products are not repeatedly included on error reports.

Back in stock

Specify whether products should be set to "in stock" when their quantity is greater than the out of stock threshold.

If set to "no", the quantity will be updated but the item's stock status will remain "out of stock".

Qty zero when availability missing

Specify whether quantities should be set to zero if the availability is not included in the Brightpearl response.

This setting can help prevent overselling

Interaction: Import stock levels (bulk)

These settings activate and control how bulk inventory updates occur.

When enabled, this feature will update all product quantities in Magento. It can be run on demand and also set to run automatically at a specified time and frequency.

Scope: Magento only supports global inventory levels so these settings will apply globally.

Find the settings at:

Magento 1: Interactions > Brightpearl > Configuration

Magento 2: Brightpearl > Brightpearl integration > Configuration

Field Description
General
Enabled

Enable or disable the interaction.

If disabled, inventory levels cannot not be updated in bulk even if triggered manually.

Trigger
On cron schedule Run the interaction at the time and frequency specified below.
Monitor schedule (where cron schedule = enabled)
Cron expression

Specify when the automatic bulk inventory update should run. Enter as a cron expression. Read more about using cron schedules.

Performance
Batch size

The batch size is the number of products that will be called in Brightpearl in one go. The interaction will continue to call in batches until all products have been updated.

The maximum batch size depends on SKU length - API requests are limited to 512 characters.

Recommendation: If your average SKU is 10 characters long, use batches of 40 to leave some leeway for extras.

Sleep

This setting regulates the speed at which Magento attempts to process the inventory updates received. It prevents overloading the Magento server and causing it to run slowly.

Recommendation: 5000 microseconds, but your developer may want to tweak this based on how your own server performs.

API timeout

Specify how long the extension should wait for a response from Brightpearl before the service times out and fails.

Indexing
During interaction

Specify whether to index product data during the interaction and as updates are made.

Reindex after interaction

Specify whether indexing should be done after the interaction.

Index If reindexing after the interaction, select which tables to reindex.
Email Notification
Email success report Enter one or more email addresses to receive confirmation of successful updates.
Email error report Enter one or more email addresses to receive confirmation of failed updates.

Interaction: Import stock levels (real-time)

These settings activate and control how individual inventory updates occur. When enabled, this feature will update a single product quantity in Magento.

It can be run on demand and also set to run automatically on certain triggers.

Scope: Magento only supports global inventory levels, so these settings will apply globally.

Find the settings at:

Magento 1: Interactions > Brightpearl > Configuration

Magento 2: Brightpearl > Brightpearl integration > Configuration

Field Description
General
Enabled Enabling real-time inventory updates will update individual product inventory levels on the selected triggers.
Trigger
On shopper view product Update the Magento product quantity when someone views it on the website.
On shopper add to basket Update the Magento product quantity when a shopper adds the item to their cart.
On shopper view basket Update the Magento product quantity when a shopper views the item in their cart.
On shopper checkout start Update the Magento product quantity when a shopper goes to checkout.
On shopper checkout place order Update the Magento product quantity when a shopper attempts to complete checkout.
Performance
Trigger(s) (TTL)

Control how frequently the each of the above triggers can send a request to Brightpearl.

For example, if five people visit the same product page within one minute, you may not want Magento to request an inventory update for each page view, so a delay of five minutes might be used.

Default time-to-live (TTL) If specific TTL times are not set for each trigger, the default will be used.
Timeout Specify how long the extension should wait for a response from Brightpearl before the service times out and fails.

Shared: Order and payment settings

These settings are shared across the following interactions:

  • Export order
  • Export order status
  • Export order payment
  • Reconcile orders
  • Import order status (real-time)
  • Import order status (bulk)

They are used for:

  • Controlling the order and payment currency applied in Brightpearl
  • Mapping order statuses for both the export and import of order status
  • Mapping payment methods so the correct bank account is used in Brightpearl

Scope: These settings can be applied per store view, allowing for store views with different currencies to be handled.

Find them at:

Magento 1: Interactions > Brightpearl > Configuration

Magento 2: Brightpearl > Brightpearl integration > Configuration

Field Description
Order settings
Send amounts in

Multi-currency Brightpearl - set to "Order Currency".

All orders and payments will be created in Brightpearl using the same currency it was created in through Magento (note the currencies must exist in Brightpearl)

Single currency Brightpearl - set to "Base Currency".

All orders and payments will be converted to the Brightpearl base currency.

Order status map

Map Magento statuses to Brightpearl order statuses.

The mapping is used by:

  • The export orders interaction so that orders are created on the correct status in Brightpearl
  • The export order status interaction to update the order status in Brightpearl when it changes in Magento
  • The import order status interaction to update the order status in Magento when it changes in Brightpearl
Default status When a new order is created with an unmapped order status, this default setting will be used to ensure it is successfully created in Brightpearl.
Payment settings
Payment method map Specify which Brightpearl payment methods should be used for each Magento payment method. Brightpearl has now introduced payment methods - the Brightpearl payment method with the same code as the bank code selected here will be used
Default nominal code When a payment is processed using an unmapped method this default will be used to ensure it is successfully created in Brightpearl. The Brightpearl payment method with the same code as the bank selected here will be used
Default create sales receipt Obsolete. This is now controlled by Brightpearl payment methods. To prevent a sales receipt from being created remove the bank account from the Brightpearl payment method

Interaction: Export Order

These settings control when new orders are sent to Brightpearl.

Use the additional options to specify how other order details are handled, such as:

  • Company name
  • Shipping method (assigned to order, mapping for shipment updates are found under shared shipment settings)
  • Custom options
  • Gift messages
  • Email subscriptions

Additional options such as order status and payments are managed in the shared order and payment settings.

Scope: These options can be controlled at a store view level.

Find them at:

Magento 1: Interactions > Brightpearl > Configuration

Magento 2: Brightpearl > Brightpearl integration > Configuration

Field Description
General
Enabled

Enable or disable the interaction.

If disabled, orders will not be sent to Brightpearl, even if manually triggered.

Update existing customers Specify whether customer records in Brightpearl should be updated with name and address changes on new orders. It is recommended that this is set to "No" when resellers are placing orders via the Magento front end.
Address company name priority

To populate the company name on the order in Brightpearl, specify where the detail can be found in Magento.

Sources will be used in sequence, until a value is found, or it will be left blank.

Gift messages custom field Select the Brightpearl sales order custom field to be used for recording an order gift message.
Include marketing details Specify whether the Brightpearl customer newsletter subscription should be updated.
Shipping method mapping
Standard (Isomorphic) Map specific Magento shipping methods to Brightpearl shipping methods to ensure the shipping method is correctly set on the order in Brightpearl.
Custom (non-isomorphic) Use an expression to map a group of Magento shipping methods to a specific Brightpearl shipping method to ensure it is correctly set on the order in Brightpearl.
Default shipping method Specify which Brightpearl shipping method should be used when the Magento shipping method on the order hasn't been mapped, to ensure the order is successfully created in Brightpearl.
Customization
Customization map Map Magento order fields to Brightpearl order rows or custom fields in order to capture additional information not already transferred to Brightpearl. Learn more about customization mapping
Trigger
On order placed (frontend) Send the new order to Brightpearl when checkout is complete.
On order placed (admin) Send the new order to Brightpearl when submitted in the Magento admin panel.
On order queued Send the order to Brightpearl once it has been added to the export queue.
On order status monitor (on cron schedule) Check for new orders at the time and frequency specified below.
Monitor schedule (where cron schedule = enabled)
Cron expression Specify when new orders are sent to Brightpearl. Enter as a cron expression. Read more about using cron schedules.
Order status(es) to monitor Only orders on the selected statuses will be sent to Brightpearl.
Sort field Select the field used for sorting orders into a queue. For example, choose "created date" to send orders to Brightpearl in the order they were placed.
Sort Specify how orders should be sorted into the export queue using the sort field above.
Batch size

Set the number of orders in the queue that will be exported to Brightpearl in one go. The interaction will continue to call in batches until all orders have been exported.

Ignore/Delay Use this to postpone the export of new orders placed within a certain number of minutes.

Interaction: Export order status

These settings activate and control when Magento order statuses should be reflected on the order in Brightpearl.

Scope: The triggers for sending these updates to Brightpearl can be set per website.

Find them at:

Magento 1: Interactions > Brightpearl > Configuration

Magento 2: Brightpearl > Brightpearl integration > Configuration

Field Description
General
Enabled

Enable or disable the interaction.

If disabled, order statuses will not be updated in Brightpearl, even if triggered manually.

Trigger
On order status changed Update Brightpearl order statuses when the Magento order status is changed.
On order status queued (on cron schedule) Check for updates at the time and frequency specified below.
Monitor schedule (where cron schedule = enabled)
Cron expression Enter a cron expression to define when and how frequently order status exports are run. Read more about using cron schedules.
Sort field Select the field used for sorting orders into a queue. For example, choose "created date" to send order status updates to Brightpearl in the order they were made.
Sort Specify how order status updates should be sorted into the export queue using the sort field above.
Batch size This is the number of updates in the queue that will be exported to Brightpearl in one go. The interaction will continue to call in batches until all orders statuses have been exported.
Email
Email success report Enter one or more email addresses to receive confirmation of successful updates.
Email error report Enter one or more email addresses to receive confirmation of failed updates.

Interaction: Export order payment

These settings control when Magento order payments should be sent to Brightpearl to mark orders as paid and, if necessary, create the accounting.

Scope: The triggers for sending payments to Brightpearl can be set per website.

Find them at:

Magento 1: Interactions > Brightpearl > Configuration

Magento 2: Brightpearl > Brightpearl integration > Configuration

Field Description
General
Enabled

Enable or disable the interaction.

If disabled, payments will not be sent to Brightpearl, even if triggered manually.

Trigger
On order payment update Send the payment when it is taken.
On order successfully exported Send the payment when the order has been marked as successfully exported to Brightpearl.
On order payment changed (on cron schedule) Check for new payments at the time and frequency specified below.
Monitor schedule (where cron schedule = enabled)
Cron expression Enter a cron expression to define when and how frequently order payment exports are run. Read more about using cron schedules.
Sort field Select the field used for sorting payments into a queue. For example, choose "created date" to send payments to Brightpearl in the order they were taken.
Sort Specify how payments should be sorted into the export queue using the sort field above.
Batch size This is the number of payments in the queue that will be exported to Brightpearl in one go. The interaction will continue to call in batches until all payments have been exported.
Email
Email success report Enter one or more email addresses to receive confirmation of successful updates.
Email error report Enter one or more email addresses to receive confirmation of failed updates.

Interaction: Reconcile orders

These settings control when an order reconciliation is carried out. The order reconciliation will export any orders in Magento that have bypassed all the usual trigger points and were never queued for export - perhaps they were created in an untypical way.

This interaction is subtly different from downloading orders using the order export - the export orders interaction will only attempt to download orders which are known to Brightpearl and are queued but haven't yet been successfully created in Brightpearl.

Scope: This interaction can be enabled globally.

Find them at:

Magento 1: Interactions > Brightpearl > Configuration

Magento 2: Brightpearl > Brightpearl integration > Configuration

Field Description
General
Enabled

Enable or disable the interaction.

If disabled, order reconciliations will not occur.

Trigger
On cron schedule Check for updates at the time and frequency specified below.
Monitor schedule (where cron schedule = enabled)
Cron expression Enter a cron expression to define when and how frequently order reconciliations occur. Read more about using cron schedules.
Performance
Batch size The number of orders that will be processed in one go. The interaction will continue to call in batches of this size until all orders have been reconciled.
Sleep

The sleep time regulates the speed at which Magento attempts to process the order reconciliation. It prevents overloading the Magento server and causing it to run slowly.

Ignore/Delay Use this to postpone the export of new orders placed within a certain number of minutes.
Fallback start date

Specify how far back reconciliations should look (cannot be earlier than the authorization date).

This should be set as the go-live date.

Requeue errors Indicate whether orders with Brightpearl errors should be queued to be processed again - they may be waiting for further details.
Email
Email success report Enter one or more email addresses to receive confirmation of successful updates.
Email error report Enter one or more email addresses to receive confirmation of failed updates.

Shared: Shipment settings (goods notes and drop-ship notes)

These settings are shared across the following interactions:

  • Import shipments
  • Reconcile shipments

This is where Brightpearl shipping methods are mapped to Magento shipping methods for shipping updates. When details of a shipment are received from Brightpearl, the relevant shipping method will be assigned to the shipment in Magento. (The shipping method assigned to the order in Brightpearl is controlled by the mapping under order export settings.)

This interaction requires webhooks to be registered. See Interaction : Register interaction webhooks.

Scope: These settings can be applied per store view allowing for different mapping per store.

Find them at:

Magento 1: Interactions > Brightpearl > Configuration

Magento 2: Brightpearl > Brightpearl integration > Configuration

Field Description
Shipping method mapping Map Magento shipping methods to Brightpearl shipping methods so that the relevant shipping method is applied to the shipments made in Magento.
Notify customer Specify whether Magento should send an email to the customer to notify them of the shipping update.

Interaction: Import shipments (real-time)

These settings activate and control when a shipping details are sent to Magento from Brightpearl.

Scope: This interaction can be enabled per website.

Find them at:

Magento 1: Interactions > Brightpearl > Configuration

Magento 2: Brightpearl > Brightpearl integration > Configuration

Field Description
General
Enabled

Enable or disable the interaction.

If disabled, shipping updates will not be sent to Magento, even if triggered manually.

Trigger
On goods out note notification (webhook) Import shipment details from Brightpearl when items are marked as shipped.
On drop-ship note notification (webhook) Import shipment details from Brightpearl when drop-ship items are marked as shipped.

Interaction: Reconcile shipments

The reconcile shipments settings control when a shipment reconciliation is performed.

This interaction will ask Brightpearl for a shipping status update on open orders. If any of the orders are fully shipped in Brightpearl they will get updated as such in Magento. This interaction ensures that the orders are marked as shipped in Magento for the following cases:

  • The order contains a non-stock tracked item
  • The shipping webhook was missed

Shipment updates made by this interaction will not include tracking references or shipping method details (if different from original order method).

Scope: This interaction can be enabled per website and the cron schedule can also be set per website.

Find them at:

Magento 1: Interactions > Brightpearl > Configuration

Magento 2: Brightpearl > Brightpearl integration > Configuration

Field Description
General
Enabled

Enable or disable the interaction.

If disabled, shipping reconciliations will not occur and real-time shipment imports will be relied upon.

Trigger
On cron schedule Check for updates at the time and frequency specified below.
Monitor schedule (where cron schedule = enabled)
Cron expression Enter a cron expression to define when and how frequently shipment reconciliations occur. Read more about using cron schedules.
Performance
Look behind Specify how far back to check for shipments.
Sort field Select the field used for sorting the open orders into a queue. For example, choose created date to check orders for shipments in the order they were placed.
Sort Specify how the orders should be sorted into the export queue using the sort field above.
Batch size The batch size is the number of orders that will be processed in one go. The interaction will continue to call in batches of this size until all orders have been checked for shipping updates.
Sleep

The sleep time regulates the speed at which Magento attempts to process the shipment reconciliation. It prevents overloading the Magento server and causing it to run slowly.

Email
Email success report Enter one or more email addresses to receive confirmation of successful updates.
Email error report Enter one or more email addresses to receive confirmation of failed updates.

Interaction: Import order statuses (real-time)

These settings control when order status changes made in Brightpearl update the order in Magento. These updates will be made using the order status mapping within the shared order and payment settings.

Scope: This interaction can be enabled per website. Emails to customers can be controlled per store view.

Find them at:

Magento 1: Interactions > Brightpearl > Configuration

Magento 2: Brightpearl > Brightpearl integration > Configuration

Field Description
General
Enabled

Enable or disable the interaction.

If disabled, order status updates from Brightpearl to Magento will not occur even if triggered manually.

Notify customer Specify whether an email should be sent to the customer each time a status update is made using this interaction.
Trigger
On status modified notification (webhook) Check for updates at the time and frequency specified below.
Email
Email success report Enter one or more email addresses to receive confirmation of successful updates.
Email error report Enter one or more email addresses to receive confirmation of failed updates.

Interaction : Import order statuses (bulk)

This interaction will check back over a given period and check that all orders have the correct order status, using the mapping within the shared order and payment settings. Orders will be updated based on the current status in Brightpearl. These settings activate and control when this order status reconciliation occurs and how far back to check orders.

Scope: This interaction can be enabled per website.

Find them at:

Magento 1: Interactions > Brightpearl > Configuration

Magento 2: Brightpearl > Brightpearl integration > Configuration

Field Description
General
Enabled Enable or disable the interaction. If disabled, bulk order status imports will not occur and real-time status imports will be relied upon.
Trigger
On cron schedule Check for updates at the time and frequency specified below.
Monitor schedule (where cron schedule = enabled)
Cron expression Enter a cron expression to define when and how frequently status import reconciliations should occur. Read more about using cron schedules.
Performance
Look behind Specify how far back to check orders. All orders within this time frame will be checked to ensure the status is correct.
Sort field Select the field used for sorting the orders into a queue. For example, choose created date to check orders for status updates in the order they were placed.
Sort Specify how the orders should be sorted into the export queue using the sort field above.
Batch size This is the number of orders that will be processed in one go. The interaction will continue to call in batches of this size until all orders have been checked for changes.
Sleep

This regulates the speed at which Magento attempts to process the order status import. It prevents overloading the Magento server and causing it to run slowly.

Email
Email success report Enter one or more email addresses to receive confirmation of successful updates.
Email error report Enter one or more email addresses to receive confirmation of failed updates.

Shared: Price settings

These settings control which prices are updated in Magento. Brightpearl is able to manage prices across custom attributes, customer groups and using tier pricing (while setups differ slightly between Magento 1 and 2, both are handled).

Scope: These settings can be managed per website. Tier pricing depends on the catalog price scope which may be global or website.

Find them at:

Magento 1: Interactions > Brightpearl > Configuration

Magento 2: Brightpearl > Brightpearl integration > Configuration

Field Description
Magento product type Select the product types which will have prices managed by Brightpearl.
Bundle base price list Specify which price is used for calculating the discount percentage on bundled products.
Price list attribute mapping Custom Magento attributes can be updated with Brightpearl prices. Use this section to map the fields that should be updated.
Tier price mapping Use this section to map customer groups to their own price list and to create price breaks in Magento (generally Break should be set to 'exclude break 1' - the first break in Brightpearl is the main product price in Magento which is already handled using the main mapping above).

Interaction : Import prices

These settings activate and control when prices are updated in Magento.

Scope: These settings can be controlled per website.

Find them at:

Magento 1: Interactions > Brightpearl > Configuration

Magento 2: Brightpearl > Brightpearl integration > Configuration

Field Description
General
Enabled

Enable or disable the interaction.

If disabled, prices will not be updated by Brightpearl.

Check tax compatibility

(Magento 1 only) Specify whether compatibility between the Magento tax settings and Brightpearl price list should be checked.

Apply attribute prices

Specify whether mapped attributes should be updated or skipped.

Apply tier prices Specify whether mapped tier prices should be updated or skipped.
Trigger
On cron schedule Check for updates at the time and frequency specified below.
Monitor schedule (where cron schedule = enabled)
Cron expression Enter a cron expression to define when and how frequently price import occurs. Read more about using cron schedules.
Performance
Batch size This is the number of prices that will be processed in one go. The interaction will continue to call in batches of this size until all prices have been checked for changes.
Sleep

The sleep time regulates the speed at which Magento attempts to process the price import. It prevents overloading the Magento server and causing it to run slowly.

Indexing
During interaction

Specify whether to index product data during the interaction and as updates are made.

Reindex after interaction

Specify whether indexing should be done after the interaction.

Index If reindexing after the interaction, select which tables.
Email
Email success report Enter one or more email addresses to receive confirmation of successful updates.
Email error report Enter one or more email addresses to receive confirmation of failed updates.

Interaction: Register integration webhooks

Webhooks must be enabled to allow Magento to "listen" out for real-time updates from Brightpearl, such as notifications of shipping and order status updates.

Find them at:

Magento 1: Interactions > Brightpearl > Configuration

Magento 2: Brightpearl > Brightpearl integration > Configuration

Field Description
General
Enabled

This interaction must be enabled to be able to register for webhooks.

Once enabled, the interaction must be executed to complete the registration with Brightpearl.

Go to:

Magento 1: Interactions > Brightpearl > Configuration

Magento 2: Brightpearl > Configuration

API

These settings are used for controlling the size of API calls made to Brightpearl to ensure they are within the accepted character limit.

Currently the Brightpearl API limit is 512, so this is the maximum which can be set at this time. Any batches that exceed this value will automatically be split into smaller batches that respect this character limit.

Find them at:

Magento 1: Interactions > Brightpearl > Configuration

Magento 2: Brightpearl > Brightpearl integration > Configuration

Field Description
Query string limit This is the number of characters allowed by the Brightpearl API in a GET request query string. Currently the limit is 512.

Interaction: Log cleaning

The interaction log will use up Magento storage space over time and should be cleaned down. These settings activate and control when the interaction log gets cleaned up.

Find them at:

Magento 1: Interactions > Brightpearl > Configuration

Magento 2: Brightpearl > Hotlink framework > Configuration

Field Description
Reporting
Interaction reports email levels

Select what type of messages emails should be included in the email. Choose one or more from:

  • Fatal
  • Error
  • Warning
  • Information
  • Debug
  • Trace

For example, if you do not select DBG the email will not contain Debug messages

Write report gzip header This setting is set to Yes as default, but your developer may want to tweak this based the server configuration.
Scheduler
Email success report Enter one or more email addresses to receive confirmation of successful updates.
Email error report Enter one or more email addresses to receive confirmation of failed updates.
Have more questions? Submit a request