A sales channel is a web-store, marketplace or point-of-sale system where the customer can purchase products from the merchant.
In its simplest form, a sales channel integration allows sales made on the channel to be automatically created as new orders in Brightpearl, and inventory levels to be updated from Brightpearl to the channel.
For the most common sales channels, like eBay and Amazon, we have native features that allow consultants to quickly hook them up to Brightpearl and start using them. For any sales channel that we haven’t integrated ourselves, you have the option of developing an integration over our API. We also have an App store that’s worth checking out to see if a connector already exists.
This document 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 that finishes with an FAQ.
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. Visit our partner listings to check them out.
What would the integration actually do?
In the most simple scenario, an integration would pass orders to Brightpearl and receive stock updates back. Or you could go down a much more complex route by adding features such as price management and shipping updates back to the channel from Brightpearl.
Building the integration
A good model for any sales channel app is our own Shopify integration. This takes form as a connector between the two systems utilising their API’s. A few key concepts to embed deep within your design process before we dive into the detail:
Brightpearl is the master
Regardless of how deeply integrated you wish to go, it’s imperative that Brightpearl is the master system, since that’s the system that controls inventory, accounting and is linked up with your other sales channels.
SKU, SKU, SKU.
Everything in Brightpearl is designed around the importance of using a SKU as a unique product identifier. Through the API you’ll be using product IDs, but these are auto-generated and can’t be changed. SKUs are controlled by the merchant, can be changed at any time, and are used to identify the product between multiple systems.
On Hand, not In Stock
With regards to availability, Brightpearl breaks down products in stock into further groupings; allocated and on hand. On hand is the amount of stock that is actually available for new sales, and is therefore the value all integrations should use when judging availability.
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 sales channel integration is replicated over and over throughout the app store. Here’s the most common, wide serving features we’re going to cover within this document:
- Order creation
- Stock updates.
In order to support as many businesses as we do, Brightpearl allows a high level of configuration throughout the key elements of stock and order management. As such, reference data changes from account to account, and as a sales channel has financial implications, many users will also want to disable certain features.
In addition, many merchants exercise multiple websites under the same platform. Any sales channel integration should offer its customers with the below options, and do so at a channel level (rather than an integration level), so that different rules and presets can be set per channel.
- Create sales orders in Brightpearl?
- Create payments in Brightpearl?
- Brightpearl controls the inventory for this store?
These will allow merchants to opt in or out of the integrations key features, which can be very useful during trial and implementation stages.
Create sales against which channel?
Dropdown list with options obtained via Channel GET.
Order status for new orders?
Dropdown list obtained with options obtained via Status GET.
*Note that many sales platforms allow users to configure their own set of order statuses, if so consider a mapping feature in place of this setting.
Payment method for posting payments?
Dropdown list obtained with options obtained via Payment Method GET.
*Note that many sales platforms support multiple payment methods, if so, consider a mapping feature in place of this setting.
Warehouse(s) used to sync inventory to store?
Multi-select Dropdown with warehouses obtained via Warehouse GET.
Warehouse to use for allocating orders?
Multi-select Dropdown with warehouses obtained via Warehouse GET.
In addition to the two notes of consideration for mapping features, a nice (and technically beneficial!) setting would be a shipping method mapping. Merchants can create multiple shipping methods for their customers to select from when proceeding through a checkout, and these may related to a slightly different list within Brightpearl. Through the use of a mapping tool, customers can select which Brightpearl shipping method should be assigned for each of the sales platforms shipping methods. You can obtain a list of all the shipping methods in the merchants Brightpearl account via a Shipping method GET.
An additional setting that’s particularly relevant for Point of Sale integrations would be the ability to set an Anonymous Contact Id. Fast paced environments mean that customer details don’t always change hands. As Brightpearl requires a contact for the order to be placed against, if you allow customers to set a backup here, you can always fall back to that.
Starting with a new order, we first need to determine whether the order needs to be created in Brightpearl or not, to avoid duplication. Using our Order SEARCH, you can investigate whether an order already exists with the same reference in Brightpearl. If the search returns an order id, then the order has already been dealt with, and there’s no need to continue.
Applying the same principle as above, we’ll then check if the contact already exists in the account. We’ll achieve this using a Contact SEARCH, and the contact’s email address.
If the contact can’t be found, we’ll need to create it. First you’ll need to generate address id’s using an Postal Address POST, and then you can use these within the subsequent Contact POST, which will allow us to proceed to the actual order.
Now we have our contact id, along with all other id’s such as Channel and warehouse from the merchants configuration, we can create the order with a Sales-order POST.
Within this message you tell us which products you’d like to add to the order within the rows array and you’ll be identifying products using Brightpearl’s product id rather than SKU. Using a Product SEARCH, You can retrieve a products id using its SKU. If this search doesn’t return any results, it’s likely that the product doesn’t exist in Brightpearl, and therefore you’ll need to include the row without the id, This will result in a non stock tracked product line being added to the order.
Once the entire contents have been added to the order in Brightpearl, we can attempt to reserve stock against any stock tracked products that we have added, and we do this using a Reservation POST. This will result in stock being allocated against this order, so that the merchant doesn’t oversell against their available inventory.
Now we’re done with the order, we can record the payment. We do this using a Customer Payment POST.
The above walkthrough will take you through the majority of scenarios, however some nice features to consider:
- You can capture additional information to an order using an Order Note POST, a common implementation of this is to store any information that a payment gateway has captured during checkout.
- 99% of the time, shipping is represented as an order row, along with any charge it incurred to the end customer. Many merchants recognise their shipping income against a different account code to their inventory sales. To find out which account code they’d like this recorded against, you’d need another setting within the configuration, and then you can use this for the order row posts.
- Most sales platforms allow end customers to register for future promotional emails, this can be represented in Brightpearl during the contact creation, by setting isReceiveEmailNewsletter appropriately.
The last item on the previous flowchart, ‘Create payment against the order’, can be expanded out into better detail. Brightpearl supports several types of payments; the main ones to call out here being AUTHORIZE, CAPTURE and RECEIPT.
If the payment gateway on the sales channel is authorising payment to be captured later on in the merchant’s workflow, then this can be recognised by creating the payment in Brightpearl with a type ‘AUTH’, and then when the gateway subsequently captures it later on, you can post another for ‘CAPTURE’, resulting in an integration that mimics the merchant’s actual financial movements against the order! For gateways that don’t support this or at least haven’t been configured to, create payments that immediately recognise funds by creating them with type ‘RECEIPT’.
Tax within order row posts: UK accounts
Whilst adding items to an order, you can state the tax code you’d like attributed to the row. You can design your own logic around this, but here’s how we decipher which tax code needs to be used:
Rule 1: Use the customer tax code
This rule is only applicable where the customer already exists in Brightpearl and has been set with a specific code. New customers created as a result of Shopify order downloads will have no code set against them and so rule 2 will be applied.
Rule 2: Where the customer has no tax code, use the tax code applicable to the billing address country
This rule is applied by tax zones in Brightpearl. Each country can be assigned to a tax zone, and the tax zone is set to apply a specific tax code.
Sales to the rest of Europe will require the T4 tax code so that a zero VAT rate is applied and the sales figures are displays in the correct boxes on the VAT return.
Ensure no tax code is set against the UK tax zone so that rule 3 is always applied.
Rule 3: If the country has no associated tax code, use the product code
In the UK tax is applied based on the category of product. Setting no tax code against the UK tax zone ensure this rule will be applied for customers purchasing in the UK.
Tax within order row posts: US accounts
...and here’s how we do it for US accounts:
Rather than polling Brightpearl every 10 minutes or so, you can subscribe to webhooks so that the Brightpearl account can make a callback to your integration upon various events occurring. This approach proves for a better integration, as it will be as near to real-time as possible, and we’ll be grateful for fewer requests to our servers. We have a webhook for product On Hand (available) modified, which means that as a customer sells an item via one of their sales channels, the webhook will be triggered and therefore alert all channels of the change (so they can then get the new availability using a Product Availability GET).
How should I handle Guest Checkout?
Even if the end customer chooses guest checkout, you’ll still have their email address. We recommend creating a new contact for every email address you get, but if you wanted to you could opt the contact out of future correspondence by setting their newsletter preferences accordingly.
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 API itself, so any questions about documentation or issues you find can be sent our way, but as for “How do I code...”, your developer will need to seek help elsewhere. We also have an API forum, where internal and external developers field questions and offer advice.1
Can I show expected delivery dates on my webstore?
You can. You won’t see the ‘on order’ amounts within the standard product availability message, but you can go hunting for purchase orders using Order SEARCH - which is actually better as it allows you to filter out the purchase orders that are actually calculated (ignoring drafts, for example). Once you have your order selection, an Order GET will give you the detail required and then you can use the combination of order row quantities and the order’s Delivery Date to get your info.
How can I handle failover allocation?
Failover allocation is a concept that enables merchants to state ‘backup’ warehouses to allocate orders against, should the first attempt fail. By allowing merchants to state multiple warehouses, in an order of preference, your integration could first investigate the availability of all products that need to have stock allocated, and then work through the stated warehouses until the desired criteria has been met.
Let’s take an example order where I’ve stated I’d like to allocate from Bristol Warehouse if possible, and then London Warehouse if not. The order contains 10 of SKU A, and 10 of SKU B. In my account, I have 10 of SKU A in Bristol, and 100 of both SKU A and B in London. My integration will investigate the availability of both SKU A and B in my account, realise that I haven’t enough stock in Bristol, and instead reserve against London.
This gets tricky when it comes to multiple failovers, and there’s additional settings to include. For example, merchants should opt into failover triggers such as ‘Failover if stock is not completely available’, versus ‘Failover if any stock is not available. Brightpearl automation handles this well, so you could save a load of development effort by having us do this part.
How does an integration change for POS?
For point of sale integrations, you may want to consider additional features within the order download to acknowledge the inventory having already walked away with the customer. The section above leaves inventory on orders in a reserved state, ready to be processed. The next step is to fulfil and mark them as shipped (bypassing the warehouse team). This is done by creating a Goods out note, and then a Goods Out Note Event to mark it as shipped. Note that once a Goods out note has been shipped, this cannot be undone.