How Brightpearl customers, trade price lists, credit terms, products, sales orders, shipments, returns and payments connect to HubSpot contacts, companies, deals, products and orders, so marketing and sales work from real buying history and operations keeps Brightpearl as the book of record.
Brightpearl runs the operations side of a retail or wholesale business: orders from every sales channel, stock across warehouses, fulfilment, and the accounting behind them. HubSpot holds the people, the pipeline and the marketing. Connecting the two puts every order, shipment and return on the customer record.
Public documentation. The client's own admin issues credentials, with no vendor approval needed.
Open API. The API reference is public. The client's Brightpearl admin creates a private app and staff token inside its own account; a public OAuth app instead needs a developer account that Brightpearl approves.
Based on the vendor's public documentation. Access terms are confirmed with the vendor and the client in discovery.
Brightpearl exposes customers, orders, products, fulfilment and payments through a documented REST API, so HubSpot can market and sell from what each customer actually buys.
Campaign Creators assessment
Brightpearl's REST API is split into services: contact, order, product, warehouse, accounting and integration. Each one supports reads, searches and writes, and the integration service adds webhooks for change events. Brightpearl connects to the client's sales channels, such as its webstore and marketplaces, so its orders already cover every channel. The CC build reads that order history into HubSpot for B2C and B2B customers, and sends won B2B deals back to Brightpearl as sales orders on the right price list.
Ratings are CC judgments from Brightpearl's and HubSpot's public documentation. Request limits, webhook events and the client's channel and warehouse setup are confirmed in discovery.
Brightpearl collects orders from the client's webstore, marketplaces and wholesale accounts. One order service and one search endpoint give HubSpot the full buying history, whatever channel it came from.
Brightpearl throttles API requests per account, and other apps in the account draw on the same budget. The sync module reads in ID sets, uses webhooks for changes and writes rollups, not every row.
The client's Brightpearl admin creates a private app and staff token, and operations and sales sign off which system owns customers, price lists and orders before the build starts.
Seven surfaces matter for a HubSpot build. Four carry the integration, two support it, and one is a scope decision made with the client.
Customers, suppliers and the companies they belong to, with the trade terms that decide how a B2B account buys.
financialDetails: price list, credit limit, credit term dayscontact-search with updatedOn and lastOrderedOnSales orders and sales credits from every channel, with status, payment status, shipping status and order rows.
order-search by status, channel and updatedOnexternalRef to prevent duplicatesThe product catalog, its SKUs and the price lists used for retail and trade customers.
identity.sku, barcodes and sales channel namesGoods-out notes record stock leaving a warehouse to fulfil a sales order, through picked, packed and shipped events.
status: picked, packed, shippedshipping.reference and shipping methodCustomer payments and contact balances give HubSpot the finance view of each trade account.
customer-payment-search by order and dateWebhook subscriptions tell the sync module when a Brightpearl resource changes, so it reads only what changed.
subscribeTo, uriTemplate, idSetAcceptedqualityOfService 1 for at-least-once deliveryDecide where trade orders start. Some clients quote and close wholesale deals in HubSpot and send them to Brightpearl as sales orders. Others keep order entry in Brightpearl and send only history to HubSpot.
A CC-built integration layer sits between Brightpearl and HubSpot. It listens for Brightpearl changes, reads in batches within the request budget, applies ownership rules, and writes to one HubSpot data model.
HubSpot owns marketing contacts, consent, deals and quotes. Brightpearl owns price lists, credit terms, products, orders, stock and payments. The other system reads them.
HubSpot gets orders, status and rollups such as lifetime value and last order date. Stock levels, ledgers and journals stay in Brightpearl.
Webhooks trigger reads, reads use ID sets, and writes go in batches, so the sync module never crowds out the client's sales channel apps.
Each phase ends on a gate the client signs off before the next begins. Operations and sales both sign the ownership rules, because both teams depend on them.
List the sales channels, warehouses, price lists, order statuses and custom fields in use, the HubSpot hubs and tiers, and the decisions each team should make from HubSpot.
The client's Brightpearl admin creates a private app and staff token. CC measures the requests other apps already use and plans the sync module's share.
Agree which system owns each record and field, the match keys (email for people, Brightpearl contact ID for accounts), and how B2B and B2C customers are told apart.
Create custom properties, order and line item mappings, product properties, custom events for shipments and returns, and the deal stages that create orders.
Build webhook intake, change reads, rollups, sales order creation by externalRef and the error replay queue. Test won-deal-to-order and shipment messages end to end.
Load customers, products and an agreed window of order history, then compute lifetime value and RFM once.
Run two weeks with order creation in review mode and customer messages paused, compare daily, then switch on.
Brightpearl field names follow its API reference. Custom fields, order statuses, channels and price lists differ in every account and are read during discovery.
| Brightpearl field | HubSpot property | Object | Direction | Notes |
|---|---|---|---|---|
| Customers & companies | ||||
| communication.emails.PRI | Contact | ↔ Both | Match key for people. HubSpot owns contact details once matched. | |
| contactId | bp_contact_id | Contact | BP → HS | Brightpearl key. Unique. |
| firstName, lastName | firstname, lastname | Contact | ↔ Both | Fill blanks only after the first sync. |
| organisation.name / company | name | Company | ↔ Both | Trade accounts become HubSpot companies with their contacts associated. |
| financialDetails.priceListId | bp_price_list | Company | BP → HS | Trade or retail price list. Read-only in HubSpot. |
| financialDetails.creditLimit | bp_credit_limit | Company | BP → HS | Read-only in HubSpot. |
| financialDetails.creditTermDays | bp_credit_term_days | Company | BP → HS | Payment terms for trade accounts. |
| marketingDetails.isReceiveEmailNewsletter | Subscription status | Contact | ↔ Both | HubSpot owns consent. Confirm the rule with the client's privacy lead. |
| assignment.current.staffOwnerContactId | hubspot_owner_id | Company | BP → HS | Matched on staff email. |
| contact balance (per currency) | bp_balance_owed | Company | BP → HS | From the accounting service. |
| Products & pricing | ||||
| identity.sku | hs_sku | Product | BP → HS | Match key for products. |
| salesChannels product name, description | name, description | Product | BP → HS | Brightpearl owns the catalog. |
| product price on the price list in scope | price, bp_trade_price | Product | BP → HS | Retail price and trade price. Confirm price list codes in discovery. |
| status | bp_product_status | Product | BP → HS | Archived products are hidden from quotes. |
| Orders, shipments & returns | ||||
| order (orderTypeCode SO) | Order | Order | BP → HS | One HubSpot order per Brightpearl sales order, associated to contact and company. |
| orderStatus.name | bp_order_status | Order | BP → HS | Statuses are set per account. |
| assignment.channelId | bp_channel | Order | BP → HS | Webstore, marketplace or wholesale. |
| totalValue, currency | Order total and currency | Order | BP → HS | In order currency. Confirm field names in discovery. |
| orderRows: productSku, quantity, rowValue | Line items | Line item | BP → HS | Associated to the HubSpot order and product. Confirm field names in discovery. |
| goods-out note status.shipped | Custom event: Order shipped | Contact | BP → HS | Triggers shipping messages. |
| goods-out note shipping.reference | bp_tracking_reference | Order | BP → HS | Carrier reference for customer messages. |
| sales credit (orderTypeCode SC) | Custom event: Return credited | Contact | BP → HS | Rolls up to bp_return_count. |
| orderPaymentStatus | bp_payment_status | Order | BP → HS | Paid, partially paid or unpaid. |
| B2B deals to orders | ||||
| sales-order POST: customer.id, priceListId, rows | Deal + line items | Deal | HS → BP | Created at closed-won for trade accounts. Prices from the customer's price list. |
| externalRef | hs_object_id (deal) | Deal | HS → BP | Stops duplicate orders on retry. |
| new contact (contact POST) | Company + contact | Company | HS → BP | Creates the trade customer in Brightpearl when it does not exist yet. |
| order ID | bp_order_id | Deal | BP → HS | Written back after the order is created. |
| Rollups | ||||
| sum of sales orders less credits | bp_lifetime_value | Contact, Company | BP → HS | Computed in the integration layer, in base currency. |
| lastOrderedOn | bp_last_order_date | Contact, Company | BP → HS | From contact search. |
| count of sales orders | bp_order_count | Contact, Company | BP → HS | Computed in the integration layer. |
| recency, frequency, value | bp_rfm_segment | Contact | BP → HS | Segment rules agreed with marketing. |
Brightpearl and HubSpot both publish their API rules. Values Brightpearl sets per account, or does not list in its reference, are marked for confirmation.
| Topic | Brightpearl | HubSpot |
|---|---|---|
| Interfaces | REST API split into services: contact-service, order-service, product-service, warehouse-service, accounting-service and integration-service. Base URL: https://{datacenter}.brightpearlconnect.com/public-api/{account}/. | REST APIs: CRM objects, associations, products, line items, orders, custom events. |
| Authentication | Private app: the client's admin creates it in Brightpearl and requests carry the app reference and staff token headers (brightpearl-app-ref, brightpearl-account-token). Public app: OAuth 2.0 authorization code, tokens valid seven days with refresh. Confirm header names in discovery. | Private app access token or OAuth 2.0 public app, scoped per object. |
| Datacenters | Each account lives in one datacenter, named in the base URL. The OAuth token response returns the api_domain to use, which can change on refresh. | One portal; region is set by the HubSpot account. |
| Rate limits | Brightpearl's help center describes a cap of 200 requests per rolling minute per account, with 503 returned when exceeded, shared by the account's private apps. Confirm with Brightpearl. | Per-10-second burst and daily limits by subscription tier. Batch endpoints for volume. |
| Batch reads | ID sets in the URL: order GET returns up to 200 orders per call; goods-out note ID sets take up to 500 IDs. Searches return IDs and changed dates. | Batch read and upsert endpoints; search returns up to 10,000 results per query. |
| Change detection | Webhooks on the integration service, with at-least-once delivery when qualityOfService is 1. Searches on updatedOn catch anything missed. | Webhooks on deal stage and company changes trigger outbound writes. |
| Duplicate protection | A sales order's externalRef with the installed integration instance forms a unique key, so retries never create a second order. | Upsert by unique property (bp_contact_id, hs_sku). |
Severity reflects impact on the SOW, not technical difficulty alone.
Sales channel, shipping and accounting apps already call the API. Measure their use in discovery and design the sync module around webhooks, ID sets and rollups.
If both HubSpot and Brightpearl users enter trade orders without a rule, orders duplicate. The ownership table names one system for order entry.
Retail customers and trade accounts both live as Brightpearl contacts. Agree the rule (company, contact group or price list) that decides whether a record becomes a HubSpot company.
Some marketplaces pass masked or relay emails. Those customers sync for reporting but are left out of marketing lists unless consent is clear.
Order statuses, channels, price lists and custom fields are set per account. Budget discovery time to read them and agree the list.
Brightpearl publishes its subscribable events in its help center. Confirm the contact, order, product and goods-out note events in discovery and keep search-based checks as a backstop.
Order history from every channel becomes lifetime value, order count and RFM segments, so marketing targets on real buying behaviour.
Last order date and the products a customer buys drive reorder reminders and cross-sell sequences timed to each buying cycle.
A closed-won trade deal creates the Brightpearl sales order on the customer's price list. No re-keying, and no orders lost between teams.
Shipped goods-out notes and sales credits trigger HubSpot emails and service tickets with the tracking reference and order attached.
Price list, credit limit, credit term days and balance owed sit on the HubSpot company, so reps see account health before they call.
Orders tagged by channel join HubSpot attribution, so leaders see which campaigns drive webstore, marketplace and wholesale revenue.
For trade accounts, HubSpot runs the selling motion and Brightpearl runs pricing, fulfilment and payment. The integration hands each record across at the moment ownership changes.
All custom properties use the bp_ prefix in a Brightpearl property group. Rollups are calculated in the integration layer so every report agrees.
| Internal name | Label | Object | Type | Source / logic |
|---|---|---|---|---|
| bp_contact_id | Brightpearl Contact ID | Contact | Single-line text | contactId; unique |
| bp_price_list | Price List | Company | Dropdown | financialDetails.priceListId |
| bp_credit_limit | Credit Limit | Company | Number (currency) | financialDetails.creditLimit |
| bp_credit_term_days | Credit Term Days | Company | Number | financialDetails.creditTermDays |
| bp_balance_owed | Balance Owed | Company | Number (currency) | Accounting service contact balance |
| bp_lifetime_value | Lifetime Value | Contact | Number (currency) | Sales orders less credits, base currency |
| bp_order_count | Order Count | Contact | Number | Count of sales orders |
| bp_last_order_date | Last Order Date | Contact | Date picker | lastOrderedOn |
| bp_rfm_segment | RFM Segment | Contact | Dropdown | Recency, frequency and value rules |
| bp_order_status | Brightpearl Order Status | Order | Dropdown | orderStatus.name |
| bp_channel | Sales Channel | Order | Dropdown | assignment.channelId |
| bp_tracking_reference | Tracking Reference | Order | Single-line text | goods-out note shipping.reference |
Choose the records and fields for this engagement and the direction each one syncs. Required fields are the keys the integration cannot run without. Copy the summary into the SOW or a reply to the client.
Based on public documentation from Brightpearl. Request limits, webhook events and account-specific setup are confirmed with the client's Brightpearl admin and Brightpearl during discovery.
Yes, through a custom integration on the Brightpearl REST API. Campaign Creators builds on its contact, order, product, warehouse and accounting services, and uses Brightpearl webhooks to pick up changes.
Brightpearl customers, products, sales orders, shipments, returns and payments sync to HubSpot contacts, companies, products and orders, with buying history rolled up on the customer record. Won B2B deals are sent back to Brightpearl as sales orders on the right price list.
Yes. Retail customers and trade accounts both live as Brightpearl contacts, so an agreed rule (company, contact group or price list) decides which records become HubSpot companies. Marketplace customers sync for reporting but stay out of marketing lists unless consent is clear.
Seven phases, each closed by a client sign-off: discovery and inventory, access and request budget, ownership and mapping rules, the HubSpot data model, building the sync module, backfill, and a parallel run before launch.
Timeline and cost depend on the sales channels, warehouses, price lists, custom fields and order history in scope, and on how much of the API request budget other apps already use. Campaign Creators confirms these in discovery and provides a fixed scope before the build starts.