Connect Brightpearl: pull orders in, check inventory

First get app_ref and dev_ref from your app in the Brightpearl developer portal, then run the OAuth authorization for your account to get the access token and the api_domain for datacenter, fill all five fields into Integration, test, map and activate — sales orders come in and inventory can be checked.

The Brightpearl connector pulls sales orders from Brightpearl into this system, and can check product inventory availability held in Brightpearl. It reads from Brightpearl: it does not pull customers from Brightpearl, and it does not push inventory or any other changes back to Brightpearl. The order of work matters here — the datacenter value is not chosen from a list, it is returned as api_domain in the OAuth token response, so you complete the authorization first and fill in the connection afterwards.

Prerequisites#

• A Brightpearl account, and its account code: the subdomain part of your Brightpearl address. For example, in acme.brightpearl.com the account code is acme.
• Access to the Brightpearl developer portal at developer.brightpearl.com, and an app there for this integration — you need its app reference and your developer reference.
• You can complete the OAuth2 Authorization Code flow for that Brightpearl account, starting from the authorization address given in the credentials step.
• You understand the reversed order for datacenter: it comes from the token response, as api_domain, after authorization. Do not guess it and do not fill in the account subdomain there.

Get your credentials#

1. Note your account code first: the subdomain part of your Brightpearl address, for example acme from acme.brightpearl.com.
2. Open the Brightpearl developer portal at developer.brightpearl.com, open your app, and note its app reference. This is the app_ref value, and the same app reference is also used as the client_id in the OAuth flow.
3. Note your developer reference at the same time. This is the dev_ref value — it is sent with each request as the brightpearl-dev-ref header, just as app_ref is sent as the brightpearl-app-ref header.
4. Start the OAuth authorization for your account from https://oauth.brightpearl.com/authorize/{account}, using your own account code in place of {account}, and complete the Authorization Code Grant flow to obtain the access token.
5. From that same token response, note two values: the access_token itself, and the api_domain value. The api_domain, for example use1.brightpearlconnect.com, is exactly what goes into the datacenter field — copy it from the response, do not construct it yourself.

Fill it into Integration#

1. Open Integration → Connector Marketplace → Brightpearl → New connection. All five fields below are required.
2. account — required, Brightpearl account code: the subdomain part of your Brightpearl address, for example acme.
3. datacenter — required, API datacenter domain: fill in the api_domain returned in the OAuth token response, for example use1.brightpearlconnect.com. Do not fill in the account subdomain here.
4. app_ref — required, App reference: the app reference of your app in the Brightpearl developer portal at developer.brightpearl.com.
5. dev_ref — required, Developer reference: your Brightpearl developer reference. It is sent as the brightpearl-dev-ref header on each request.
6. access_token — required, OAuth2 access token: paste the access token obtained from the Authorization Code Grant flow. It is a password-type field and is stored as a secret.

Test the connection#

Click Test connection. The test first checks all five fields — account, datacenter, app_ref, dev_ref and access_token — and if any one is missing it stops and reports the missing field before sending any request. Otherwise it sends a request with three headers, Authorization: Bearer with your token, brightpearl-dev-ref and brightpearl-app-ref, to read the order status reference data: GET https://{datacenter}/public-api/{account}/order-service/order-status, with your own datacenter and account values in the address. That is the lightest read-only check in Brightpearl. A 200 response means the connection works. A 401 response points to the token. A 403 response points to permission. The test times out after 12 seconds.

Mapping / pick a template#

Pick the Brightpearl standard mapping. Sales orders are found through the Brightpearl order service search and then read in full, and inventory checks read product availability from the warehouse service. After the test passes, run one pull and check a real order side by side — order number, customer name shown on the order, lines and quantities — and check one product availability against what Brightpearl shows, before activating. If a field on your orders differs, adjust that field in the mapping instead of changing records in Brightpearl.

Activate#

After activation, the connection pulls sales orders from Brightpearl into this system on the schedule you set, and inventory checks read the current product availability from Brightpearl. Watch the first pulls in Runs / Logs and compare them with Brightpearl before leaving the connection unattended. When the access token stops working, run the OAuth authorization again for the same account, then update access_token and datacenter together from the new token response.

What this connection does not do: it does not pull customers from Brightpearl, and it does not push inventory, order status or fulfillment results back to Brightpearl. Keep handling those in Brightpearl itself, or through the other systems where the work actually happens.

FAQ#

Test fails with 401 — the token is the problem

Brightpearl did not accept the access token sent with the test. The token in the access_token field is wrong, incomplete, or was not obtained for this account through the Authorization Code Grant flow — the test reads order status reference data as a Bearer token check, and a token Brightpearl cannot accept fails there first.

Run the authorization again from https://oauth.brightpearl.com/authorize/{account} with your own account code, complete the Authorization Code Grant flow, paste the new access token in full, and copy datacenter again from that same token response as api_domain. Save, and test again.

Test fails with 403 — a permission problem

This is different from 401: the token was accepted, but the app or the account behind it is not allowed to read the order status reference data used by the test. Re-running the authorization with the same app and the same access will keep returning 403.

Check in Brightpearl what the app identified by app_ref is allowed to access for this account, and check that dev_ref and app_ref are the exact pair used with the token. Give the app the read access the connection needs, or use an app that already has it, then authorize again, update the fields from the new token response, and test again.

Test stops before sending a request and reports a missing field

One of the five required fields — account, datacenter, app_ref, dev_ref or access_token — is empty. The test checks all five first, because the request address needs account and datacenter, and the request headers need app_ref, dev_ref and the token.

Fill in the missing field from its own source: account from your Brightpearl address, app_ref and dev_ref from the developer portal, and access_token plus datacenter from the OAuth token response. Save, and test again.

I filled in the account subdomain as datacenter and the test fails

account and datacenter are different values with different shapes. account is the subdomain of your Brightpearl address, for example acme. datacenter is the api_domain returned in the OAuth token response, in the shape of use1.brightpearlconnect.com. With the account value in the datacenter field, the test request goes to the wrong address.

Go back to the token response from your OAuth authorization, copy the api_domain value exactly into the datacenter field, leave account as the subdomain only, save, and test again.

Connected, but no sales orders are pulled in

The connection is working — the test read the order status reference data successfully — but there is nothing new to pull: Brightpearl has no new sales orders in the pull range for this account, or those orders sit under a different account than the account code in the connection.

Create or confirm one sales order in Brightpearl under the same account code as the connection, then run a manual pull and confirm the order appears in the preview or in Runs / Logs.

Inventory check returns no availability for a product

The connection can read product availability in Brightpearl, but that product has no matching availability record to read, or the product code in the mapping does not match the product in Brightpearl. The test can pass while a single product still has nothing to return.

Check the product and its availability in Brightpearl first, then check the product code for that item in the mapping and correct it to match Brightpearl. Run the inventory check again for that one product.