Brightpearl hosts a range of tools and features to help merchants fulfill their orders, and get items out to customers in time. Over time, as more and more orders need fulfilling, additional features and levels of automation move from being a nice addition to a core requirement, and there is a plethora of options available; ranging from SaaS products dedicated to aggregating orders to a single carrier, to complete third party logistics services.
Whether it’s a simple order transfer, or a full scale outsourced operation, using our API you can connect Brightpearl to your chosen solution, offering you the levels of automation you need. We also have an App store that’s worth checking out to see if a connector already exists (we’ve put a few in there ourselves!).
This guide serves as both an introduction to how you can go about getting such a connection built, as well as an overview to a best practice integration.
Is an integration even possible?
The Brightpearl side of things is covered, using our API you can retrieve and post all of the information required. As long as one of the following two are true, you can keep this document open..
- The platform you’re looking to connect has an API. If so, you can create a connector that sits in between the two.
- You can directly edit the code of your platform.
How do I go about getting it done?
If you have your own experienced development team, they could take a look. If not, we have accredited Brightpearl partners who are well versed in our API.
What would the integration actually do?
That’s up to you and what you’re looking to achieve. In the most common scenario, an integration would replicate Brightpearl’s goods-out notes as shipments in your chosen carrier software, and update Brightpearl with tracking references in return.
Integrations to third party fulfillment software would need to be a little more heavy handed; receiving goods-in against purchase orders and customer returns, as well as stock checks.
A good model for any fulfillment integration is our own ShipStation integration. This takes form as a connector between the two system’s utilising their API’s. A few key concepts to embed deep within your design process before we dive into the detail:
- Orders vs goods-out notes
A ‘goods-out note’ is Brightpearl’s term for shipment. A goods-out note can only ever belong to one order (or warehouse transfer). However, a single sales order can be fulfilled via multiple goods-out notes. Once a goods-out note has been created, its contents cannot be amended (merchants would need to delete and create another instead).
- Goods-out note events
Goods-out notes can go through a series of events within Brightpearl: creation, printing, picking, packing and shipping (we also have the ability to un-print, un-pick or un-pack and delete). Once created, the only compulsory action to eventually close a goods-out note is shipping, as when you ship inventory levels are adjusted and accounting journals are posted. For a deeper look at how this is handled, see our help documentation.
- SKU, SKU, SKU
Everything in Brightpearl is designed around the importance of using SKU as a unique product identifier. Through the API you’ll be using product ID’s, but these are auto-generated and can’t be changed. SKU’s are controlled by the merchant, can be changed at any time, and are used to identify the product between multiple systems.
Designing the integration
Every merchant is different, and there will always be bespoke requests to amend integrations to adhere to different business logic, however a large portion of a carrier integration is replicated over and over throughout our customer base. In this section we’re going to cover the most common scope, wherein an app takes goods-out notes from Brightpearl to be entered into external software, then applies updates back to Brightpearl, broken into the following areas:
- Goods-out note retrieval
- Goods-out note updates
Any multi-tenanted integration needs to be configurable to different workflows if it is to be successful. The following options should be available for each merchant’s connection:
Event at which to pickup goods-out notes from Brightpearl?
To signify which webhook event you’ll need to register against. The options will be creation, printed, picked or packed.
- Stage at which to update goods-out notes when shipped?
Options available will be packed or shipped. Whilst the majority will select ship, some merchants prefer to control this process within Brightpearl due to the accounting journals that get created.
- Weight units
An integration needs to know which unit of measure the merchant has used within their data, so that the appropriate data can be entered into the carrier software. Brightpearl does offer this as an internal setting, however it’s not compulsory. You can see if the merchant has selected anything via an account configuration GET, however it’s good practice to capture this within your own integration, as getting this wrong could prove quite costly for the business!
- Pickup goods-out notes from which channels?
An additional filtering option, wherein the user can select which of their Brightpearl sales channels (such as Amazon, Shopify, telephone) are relevant for this integration. Many merchants operate with different brands or stationary for their different channels, as such anything printed or supplied from the carrier software should reflect this as well. You can retrieve a list of all the merchant's channels via a channel GET.
An additional consideration would be a shipping method mapping option, where merchants could map their Brightpearl shipping methods to the shipping services in their carrier software. Due to the nature of Brightpearl’s shipping methods being customer facing, they are often named along the lines of ‘Free’ or ‘Quick’ ...which won’t really matchup with the carriers anticipated name of ‘X4 Overnight UK Mainland’. Many carrier aggregators have a mapping feature as a native feature, so there’s no need for your connector to map them, but worth it if the don’t! You can retrieve a full list of shipping methods in the merchants Brightpearl account using a shipping method GET.
Goods-out note retrieval
To get goods-out notes from Brightpearl, you need to use a goods-out note GET, which can be performed upon resource events occurring within Brightpearl and notified to your integration via the registered Webhook (as outlined in the configuration stage). If you need to query Brightpearl for goods-out notes directly in addition to this, then you can do so via a goods-out note SEARCH.
The ‘transfer’ boolean flag on a goods-out note (see the documentation for a full explanation), Brightpearl has a feature wherein a user can move stock from one warehouse to another via an inventory transfer, which creates a goods-out note in the process (so that the transfer may enter the user’s shipping routine). The goods-out note will otherwise be in the same format as a regular goods-out note.
If you need to get additional information about the product, in example ShipStation stores the products SKU locally, you can do so via a product GET.
Goods-out note updates
As the carrier system updates and completes shipments, relevant updates need to be reflected back in Brightpearl, so that the merchant has visibility and that Brightpearl can update the sales channels where relevant.
There are two types of updates to send back to Brightpearl. The first is an update to give the goods-out note a tracking reference, and update the shipping method if applicable. Both and more are achieved via a goods-out note PUT.
The second update concerns moving the goods-out note through the stages of print, pick, pack and ship. Depending on what the merchant has selected within their configuration, the relevant even code of packed or shipped can be actioned via a goods-out note event POST.
That’s the minimum that needs doing in order to update Brightpearl, and any sales channels. However, the majority of Brightpearl’s merchants have customer service teams logged in, and using Brightpearl’s order screens should a customer call in; as such, a nice finishing touch within this process would be to also add an order note to the order stating its progression, and any additional information that’s relevant. You can do this using an order note POST.
Building the integration | Receiving stock
When deciding how to facilitate third party fulfillment with your Brightpearl account, you have a few options. The first being that you grant the team with a login to your account, with just enough access that they can fulfill and process orders.
Next up, you can always export sales orders and send them to the third party fulfillment provider via email or other means manually, which means that there’s no technical link and therefore cost. There will of course, be a manual task required and a time dependency on that task (orders that come in a minute after you run your exports will have to wait until the next day or time you process).
Finally, and most importantly for this guide, you can integrate with the third party fulfillment system. The goods-out processes detailed in the previous section carries over, but if your outsourced team are also managing your goods-in process, then the integration will need to manage that by picking up your inbound purchase orders and receiving stock directly against them.
Picking up purchase orders
Firstly, an additional setting within configuration would be handy here to determine which purchase orders qualify to the order. The best way to get this would be to ask the merchant which order statuses signify orders actually being placed with a vendor, as opposed to draft orders or those not yet approved. Some merchants may even go as far as to have an order status setup for ‘ASN received’. To cater for all, their choice of bat signal would come to life in your configuration as a drop-down select setting, with all the account’s purchase order statuses available. To generate this, you can perform order status GET and then filter the results to order type code PO.
To pickup the purchase order, you can perform an order GET just as if it were a sales order. The key bits of information to be captured into the warehouse solution would be the vendor, order reference, delivery date and the order rows. Should you need any additional information about the vendor or the products on the order, you can retrieve a full contact record using contact GET, or a product’s details using product GET.
To receive stock in over API, you’ll need to perform a goods-in note POST against the order. Brightpearl supports multiple goods-in notes per order, so in the likely event that the vendor doesn’t send everything in one hit you can still update Brightpearl with the goods that did arrive. Just as we discussed with Sales orders, additional notes or relevant information can be added to the order using an order note POST, and are a welcome finishing touch that keeps Brightpearl’s merchants in the know.
For the scenario of receiving more than was originally ordered, Brightpearl will need amending in order to post the goods-in (as you can’t over-receive stock on an order row). A couple of options on handling this..
The first would be to add a new order row to the order via an order row POST for the unexpected amount. Note that this is only possible if an invoice hasn’t been received against the order - if it has, you could go as far as creating a new order entirely for the overage using order POST.
The next, and our recommended option, would be to amend the quantity value on the original order row via an order row PATCH.
Building the integration | Stock takes
Even if the merchants stock is being maintained in another location, and primarily through the outsourced team’s software, Brightpearl still needs to be kept up to date with stock availability in real-time in order to feed integrated sales channels.
As stock takes occur, it’s inevitable that there will be discrepancies between Brightpearl and the external system. You can use product availability GET to find out how much stock Brightpearl is currently holding, and you can make amendments via a stock correction POST.
At the time of writing this (January 2016), Brightpearl’s concept of operating FIFO is not yet available over the API. This means that if the merchant has paid a different prices for each unit of the same stock, then the stock correction message outlined above will not respect the exact cost price of a particular batch of stock.
However, it is possible to directly amend a particular batch of stock from Brightpearl’s inventory detail report; so whilst we work on our API it’s best to alert and let the merchant amend their stock themselves, instead of risking the financial integrity of their stock.
What support is available for embedding shipping labels?
For merchants who wish to embed their shipping label within their packing notes, or other stationary, we have a field entitled ‘labelURI’ that does just that. The field is held against the goods-out notes, and can be updated via a goods-out note PUT. The field allows you to store the url of an image within Brightpearl, and can be rendered as part of a Brightpearl template. So, this enables merchants to generate goods-out notes, which can prompt your integration to register it with their carrier, who will generate the label URL, which you can then ‘PUT’ back into Brightpearl ready to be printed.
A nice touch here would be to offer an order status update at the time of successfully label submission. Brightpearl’s goods-out note listing allows users to filter out and prioritise their workload by order status, so enabling them to ‘Update order status to X upon receipt of label’ would serve this functionality well.
Who will support the integration?
Our internal support teams don’t support bespoke integrations, it’ll be down to your chosen developer to do that. We of course support the Brightpearl and our API itself, so any questions about documentation or issues you find can be sent our way, but as for “How do I write code to...”, your developer will need to seek help elsewhere. We also have an API forum, where internal and external developers field questions and offer advice.