Configuring the Brightpearl Magento module 3

This article will go through each setting available for configuration of the Brightpearl Magento module 3.

Shared: GENERAL

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 Brightpearl > Brightpearl integration > Configuration

Field	Description
Brightpearl channel	Select the channel used in Brightpearl for recording sales

Shared: ORDER

These settings are shared across the following interactions:

• ORDER: export
• ORDER: status / export
• ORDER: payment / export
• ORDER: export / reconcile
• ORDER: status / import / live
• ORDER: status / import / bulk
• ORDER: creditmemo / export

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 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 and credit memo method map	Specify which Brightpearl payment methods should be used for each Magento payment method and credit memo 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

ORDER: export

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 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.
Customer 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.
Default allocation warehouse	Select the warehouse to use for orders exported from Magento. The selected warehouse will populate the "Warehouse" field on an order.
Earliest permitted date	Set a date before which orders will not be exported. Should coincide with the order reconciliation fallback date.
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.
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.

ORDER: export / reconcile

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 Brightpearl > Brightpearl integration > Configuration

Field	Description
General
Enabled	Enable or disable the interaction. If disabled, order reconciliations will not occur.
Batch	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.
Delay	Use this to postpone the export of new orders placed within a certain number of minutes.
Limit 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.
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.

ORDER: payment / export

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 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 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.

ORDER: status / export

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 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 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.

ORDER: status / import / live

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 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 changed (webhook)	Check for updates at the time and frequency specified below.

ORDER: status / import / 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 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.
Notify customer	Specify whether an email should be sent to the customer each time a status update is made using this interaction.
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 by	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 direction	Specify how the orders should be sorted into the export queue using the sort field above.
Batch	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.
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.

Shared: ORDER: shipment

These settings are shared across the following interactions:

• ORDER: shipment / import / live
• ORDER: shipment / import / bulk

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 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.

ORDER: shipment / import / live

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 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.

ORDER: shipment / import / bulk

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 it at 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.
Look behind	Specify how far back to check for shipments.
Sort by	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 direction	Specify how the orders should be sorted into the export queue using the sort field above.
API query size	The API query 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.
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.

ORDER: creditmemo / export

The creditmemo export interaction controls when to create sales credits in Brightpearl.

Use the additional options to specify how the credit details are handled, including:

• What status to assign to them
• Whether they should be automatically refunded
• Whether goods should be automatically returned into inventory

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

Find it at Brightpearl > Brightpearl integration > Configuration

Field	Description
General
Enabled	Enable or disable the interaction. If disabled, credit memos will not be exported into Brightpearl and refunds must be handled directly in Brightpearl.
Sales credit order status	Specify which status new credits should be assigned once they're created.
Enable refunds	Specify whether the credits should be marked as refunded within Brightpearl.
Refund shipping nominal code	Use this field to identify the shipping line item on a Magento order if it differs from your default shipping method nominal code.
Enable quarantine	Specify whether inventory should be received directly into stock or whether it should be received into a quarantine location. Note that if this setting is enabled, inventory will be received into quarantine regardless of whether it is received in on the credit memo in Magento.
Quarantine warehouse (if enable quarantine = yes)	Select the warehouse to assign to sales credits if receiving goods into quarantine.
Quarantine location (if enable quarantine = yes)	Choose which location to receive the items into.
Quarantine price list (if enable quarantine = yes)	Select the price list to use for returned goods.
Trigger
On creditmemo created (admin)	Enable to import credit notes when a credit memo is created by an administrator in Magento.
On creditmemo created (webapi_rest)	Enable to import credit notes when a credit memo is created using Magento's API.
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.
Monitor creditmemo queue
Sort	Choose the order in which to process queued credit memos.
Batch size	Choose how many credit memos to process in a batch.

Shared: INVENTORY

These settings are shared across the following interactions:

• INVENTORY: import / bulk
• INVENTORY: import / 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 Brightpearl > Brightpearl integration > Configuration

Field	Description
Standard import behavior
Inventory source map	Map your MSI sources to your warehouses in Brightpearl.
Put in stock	Set to "Yes" to change the source item status to "in stock" when the item's availability is over zero.
Put out of stock	Set to "Yes" to change the source item status to "out of stock" when the item's availability is zero or lower.
When warehouse data is missing for a SKU source
Source level	Choose what action to take if the Brightpearl API returns no data for a SKU. "Leave unchanged" to maintain the current level or "Zero" to set the source level to zero.
Report	Choose whether to increase the failure count in the logs when no data is returned for a SKU.
Drop-ship
Drop-ship manages stock source	Normally drop-shipped Magento products should be configured with "Manage stock" set to "No". If you drop-ship products within Brightpearl that have "Manage Stock" set to "Yes", Magento may not deduct stock when you import a drop-ship (shipping) note. In that case, this setting controls which Inventory source to use for deducting stock. Note that Magento will not create a shipping note when insufficent stock is available, and will instead report an error (the shipping note import will fail).

INVENTORY: import / live

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 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 page	Update the Magento product quantity when a shopper goes to checkout.
On admin view product	Update the Magento product quantity when an admin views a product.
On admin place order	Update the Magento product quantity when an admin places an order.
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.
Batch	Choose how many source items to include in each batch.
Sleep	Choose the speed at which Magento attempts to process the shipment reconciliation in milliseconds.

INVENTORY: import / 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 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.
Performance
Batch	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.
TTL filter	Only update records older than the number of time-to-live seconds.
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.

Shared: PRICE

These settings control which prices are updated in Magento. Brightpearl is able to manage prices across custom attributes, customer groups and using tier pricing.

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 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).

PRICE: import

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

Scope: These settings can be controlled per website.

Find them at Brightpearl > Brightpearl integration > Configuration

Field	Description
General
Enabled	Enable or disable the interaction. If disabled, prices will not be updated by Brightpearl.
Perform tax configuration check	(Magento 1 only) Specify whether compatibility between the Magento tax settings and Brightpearl price list should be checked.
Skip apply attribute prices	Specify whether mapped attributes should be updated or skipped.
Skip apply tier prices	Specify whether mapped tier prices should be updated or skipped.
Batch	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.
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.

WEBHOOKS: activate

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 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 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 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.

Log reporting

Configure what to include in the logs under Brightpearl > Hotlink framework > Configuration > Reporting.

Field	Description
Report log path	Choose where to create the logs, making sure the path exists and is read- and writable by the web server user and the cron user.
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
Email report content limit	Enter the maximum size for a log email in bytes.
Write report gzip header	This setting is set to Yes as default, but your developer may want to tweak this based on the server configuration.
Report cron triggers	Report on the cron launcher's activity. Enable to diagnose cron-related issues.

LOG: clean

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 Brightpearl > Hotlink framework > Configuration

Field	Description
General
Enabled	Enable the log cleaner.
Count	Enter either the number of records to retain (a positive integer) or remove (a negative integer). For example, entering 1000 will keep 1000 records and delete the others, while entering -1000 will delete 1000 records and keep the others.
Sleep	Enter the length of time in milliseconds to wait between database deletes to avoid MySQL locking bugs.
Trigger
On cron schedule	Run the interaction 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 the logs are cleaned. Read more about using cron schedules.

API and email settings

Every interaction also shares two kinds of settings that are configured the same way.

API

API
API timeout connect	Enter the number in milliseconds allowed to establish a connection with Brightpearl.
API timeout respond	Enter the number in milliseconds allowed to wait for a response from Brightpearl.

Email

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.