Brightpearl Store Management
This is the installation and configuration guide for Brightpearl Store Management, the module you downloaded from your ECOSIRE dashboard or the Odoo App Store. Everything on this page describes the brightpearl_store_management module exactly as it ships today — the facts below were read out of the released build, not from a roadmap.
| Technical name | brightpearl_store_management |
| Odoo versions | 17.0, 18.0, 19.0 (Community or Enterprise) |
| Current shipped version | 19.0 → 19.0.1.1.0 |
| Price | $499 USD — one-time, per Odoo version |
| Odoo module licence | OPL-1 |
| Category | Connector |
The current build ships under the OPL-1 licence with no activation gate: install it and it runs. There is no licence key to paste, no ECOSIRE licence client to install, and no daily call-home. Every feature works the moment the module is installed. (The older 17.0 / 18.0 maintenance builds predate this change — see Version history.)
Requirements
| Requirement | Detail |
|---|---|
| Odoo | 17.0, 18.0 or 19.0, Community or Enterprise. Self-hosted or Odoo.sh — Odoo Online (SaaS) cannot install third-party modules |
| Odoo apps | base, sale_management, stock, account, delivery, mail, web, portal, product, contacts, digest — Odoo installs any that are missing automatically |
| Python packages | requests |
| Platform account | A Brightpearl account with API access |
Install the Python packages into the same interpreter that runs Odoo:
sudo -u odoo pip install requests
Installation
1. Download the ZIP for your Odoo version
Sign in at ecosire.com and open your dashboard downloads, or download the module from your Odoo App Store purchase.
2. Extract into your addons path
unzip brightpearl_store_management_v19_*.zip -d /opt/odoo/addons/
ls /opt/odoo/addons/brightpearl_store_management/__manifest__.py # sanity check
The module must end up as a single top-level brightpearl_store_management/ directory with __manifest__.py directly inside it. If your ls check fails, the folder landed one level too deep or too shallow — move it so the path above resolves.
3. Restart Odoo and install
sudo systemctl restart odoo
- Go to Apps and click Update Apps List (developer mode must be on).
- Search for Brightpearl Store Management and click Install.
- Odoo pulls in the Odoo apps listed above automatically.
When the install finishes, a Brightpearl menu appears in the main Odoo app switcher. Nothing further is required — the module is fully usable immediately, with no separate activation step.
Configuration
Connect to Brightpearl
Create a connection record on the brightpearl.instance model. The fields the module defines for the connection are:
| Field | Technical name | Type | Required |
|---|---|---|---|
| Instance Name | name | Char | Yes |
| Brightpearl Shop URL | shop_url | Char | Yes |
| Company | company_id | Many2one | Yes |
| API Key / Client ID | api_key | Char | No |
| API Password | password | Char | No |
| Client Secret | shared_secret | Char | No |
| Access Token | access_token | Char | No |
The fields marked Yes are enforced by the model — Odoo will not let you save the record without them. The technical name is the reliable identifier if your screen wording differs.
Credentials are easiest to obtain through the OAuth handshake (see the endpoints below): click the connect action on the instance, authorize in Brightpearl, and the module stores the access token for you. The API Password field is a legacy input, only needed when you supply a token manually instead of using OAuth — Brightpearl deprecated private app passwords in 2022.
The same record carries 3 behaviour checkboxes — auto_confirm_order, auto_create_invoice, auto_validate_invoice. They gate what the module is allowed to do automatically once it is connected: confirming imported orders, creating their invoices, and validating those invoices. Leave anything you are not ready for switched off, and turn them on one at a time.
Each instance is unique per company, and record rules keep every account's orders, stock and payouts isolated across legal entities — two Brightpearl accounts in the same Odoo never see each other's records.
The module's own source contacts Brightpearl's API endpoints for your account's datacenter. Your firewall must allow outbound HTTPS to Brightpearl.
Public endpoints this module exposes
The connector serves six externally reachable endpoints: the two OAuth handshake routes and four webhook receivers. All are relative to your Odoo base URL (web.base.url).
| Endpoint | Method | Auth | Purpose |
|---|---|---|---|
/brightpearl/install | GET | Public (unauthenticated) | Entry point for the install / connect request coming from Brightpearl. It resolves the shop to a saved connection record and redirects the browser on to the Brightpearl authorization screen. |
/brightpearl/callback | GET | Public (unauthenticated) | OAuth redirect target — this is where Brightpearl sends the authorization code, and the module exchanges it for an access token. Register https://erp.example.com/brightpearl/callback as the redirect URI in your Brightpearl app. |
/brightpearl/webhook/product | POST | Public, HMAC-verified | Receives Brightpearl product events (create / update / delete). |
/brightpearl/webhook/order | POST | Public, HMAC-verified | Receives Brightpearl order events. |
/brightpearl/webhook/customer | POST | Public, HMAC-verified | Receives Brightpearl customer events. |
/brightpearl/webhook/refund | POST | Public, HMAC-verified | Receives Brightpearl refund events. |
Set web.base.url to the real HTTPS address before you connect or register webhooks — the OAuth redirect URI is built from it, and a placeholder hands Brightpearl a URI that points nowhere.
Neither OAuth endpoint is usable by an anonymous caller. /brightpearl/install refuses a shop domain it cannot match to a saved brightpearl.instance record, verifies the HMAC when Brightpearl sends one, and issues a single-use state nonce. /brightpearl/callback re-verifies the HMAC, rejects a state that does not match the nonce just issued, and refuses a request that carries no authorization code. A failure at any of those checks ends the handshake on an error page, and no token is stored.
Every webhook receiver checks the X-Brightpearl-Hmac-SHA256 signature against the client secret on the instance before doing anything — a delivery that fails verification is rejected, so the webhook secret on the instance must match the one registered in Brightpearl.
Configuring a webhook
Each webhook record (Brightpearl → Configuration → Webhooks) is wired to one of the four receivers above and carries three independent toggles: Create Odoo Record, Update Odoo Record and Delete Odoo Record. They are honoured per event — switch deletions off and a Brightpearl deletion is simply logged, never turned into Odoo work. An Auto Process switch decides what happens to a delivery when it arrives:
- Auto Process on (the default): the delivery is processed immediately on receipt.
- Auto Process off: the delivery is parked as a HELD queue job that the scheduled queue run never touches, so you can review what came in before letting it run. The queue form exposes Process Now, Retry and Cancel buttons for exactly this — held or failed jobs are resumed or discarded by hand, never silently.
Scheduled actions
The module installs 13 scheduled actions (Settings → Technical → Scheduled Actions):
| Scheduled action | Runs every | Enabled on install |
|---|---|---|
| Brightpearl: Sync Products | 30 minutes | Yes |
| Brightpearl: Sync Orders | 15 minutes | Yes |
| Brightpearl: Sync Customers | 60 minutes | Yes |
| Brightpearl: Sync Inventory | 10 minutes | Yes |
| Brightpearl: Process Queue Jobs | 5 minutes | Yes |
| Brightpearl: Import Payout Reports | 6 hours | Yes |
| Brightpearl: Import Refunds | 30 minutes | Yes |
| Brightpearl: Auto Risk Detection | 30 minutes | Yes |
| Brightpearl: Generate Analytics | 4 hours | Yes |
| Brightpearl: Webhook Health Check | 60 minutes | Yes |
| Brightpearl: Cleanup Old Logs | 24 hours | Yes |
| Brightpearl: Process Workflows | 10 minutes | Yes |
| Brightpearl: Daily Summary Report | 1 day | Yes |
Intervals above are the shipped defaults. Adjust them to your volume — but be aware that the platform, not Odoo, sets the API rate limits, and shortening a sync interval is the usual cause of throttling errors in the logs. When Brightpearl asks the module to slow down (HTTP 429), the sync waits for the Retry-After interval Brightpearl sends instead of hammering the API.
Using the module
The module's menu is laid out as:
- Brightpearl → Dashboard
- Brightpearl → Orders
- Brightpearl → Refunds
- Brightpearl → Products
- Brightpearl → Customers
- Brightpearl → Payouts
- Brightpearl → Analytics
- Brightpearl → Operations — Run Operations, Queue Jobs, Logs
- Brightpearl → Configuration — Instances, Locations, Payment Gateways, Scheduled Actions, Webhooks
A normal first run is:
- Save the connection record and authorise via OAuth; confirm the module reports a successful connection before importing anything.
- Review the mapping records so imported data lands on the right Odoo records.
- Run a small import first — restrict it by date or by a handful of specific IDs — and check the results before letting the scheduled actions take over.
- Watch the log records during the first full sync. Failures are recorded there rather than raised at the user, and a single bad record no longer rolls back the rest of the run.
The operations wizard
Brightpearl → Operations → Run Operations covers targeted runs: choose an operation (import products / orders / unshipped orders / customers / stock levels / locations / payment gateways, export products / customers / stock levels, update order status, import payout, import refunds) and every option on the form reaches the sync:
- From / To Date — restricts order, payout and refund imports to the window.
- Specific IDs — comma-separated Brightpearl IDs, for importing exactly the records you name.
- Skip Existing Records — leaves records already in Odoo untouched instead of updating them.
- Import Product Images — downloads product images during product imports (on by default).
- Import Unshipped Orders — pulls only orders Brightpearl has not fulfilled, instead of everything in the window.
Dashboard
The dashboard reads KPI tiles with period-over-period deltas in your company currency — the symbol is taken from the Odoo currency, never painted on. Charts are clickable: a point on the revenue trend opens that day's or month's orders, and a slice of the order-status doughnut opens the orders in that state. The period selector (presets or a custom range) changes the numbers and charts for everyone viewing without writing anything back to the instance configuration, so two users on different periods no longer overwrite each other's window.
Payouts
Imported payout reports land on the payouts menu. Skip Import leaves a payout in draft with a note saying so, instead of importing it; Create Bank Statement (on by default at import time) posts the payout to your bank journal and reconciles it when the option is on. Both are visible on the payout form, and the statement a payout produced is linked from it. Payouts can also be created by hand — the currency defaults to the company currency, the date to today, and the reference is drawn from the module's payout sequence.
Orders, stock and shipping
- Orders are keyed by their Brightpearl order ID, so a re-sync updates the same sale order instead of duplicating it. Order views include kanban, pivot and graph alongside the list and form.
- Warehouses import from Brightpearl as Odoo locations; stock levels import per location, and exports go back to Brightpearl as stock corrections (Run Operations → Import Locations / Import Stock Levels / Export Stock Levels).
- Shipping labels are produced through the carrier you configure: the module calls the carrier's API, passes the Signature Required option when set, and refuses with a clear message if no carrier API is configured — it never invents a tracking number or a label URL. With Real-time Tracking off, it returns the carrier's public tracking link instead of calling the API.
- Order risk scoring runs on a schedule with thresholds you configure per instance, and flagged assessments are resolved by users with a Manager, Administrator, Operations, Finance or Developer role — workflow action buttons throughout the module (validate payouts, activate carriers, resolve risks) require one of those roles; a read-only Brightpearl User can see the data but cannot move it.
Troubleshooting
| Symptom | Cause and fix |
|---|---|
| The connection will not validate | Re-check every required field in the table above. Most failures are a mistyped secret, or credentials created for a sandbox while the module points at production (or vice-versa). |
| Nothing syncs even though the connection is fine | The scheduled actions are disabled at the Odoo level, or Odoo's cron worker is not running. Check Settings → Technical → Scheduled Actions and that --max-cron-threads is greater than zero. |
| Sync starts then stops part-way | Read the module's log records for that run. Rate limiting and rejected field values are the two common causes; both are logged with the platform's own error text. A single bad record rolls back alone and the rest of the run completes. |
| Webhook deliveries arrive but nothing happens | Check the delivery in the queue (Operations → Queue Jobs): if Auto Process is off it is HELD by design — use Process Now once you have reviewed it. If the delivery failed signature verification, the client secret on the instance does not match the one registered in Brightpearl. |
| Label generation refuses with "no carrier API configured" | Expected behaviour. Configure the carrier integration first; the module will not fabricate a label or tracking number. |
| Records import but map to the wrong Odoo values | Fix the mapping records under the module's configuration, then re-run the import. |
| Duplicated products or customers | Run the initial import once. If a first attempt half-finished, check the existing records before re-running rather than importing on top. |
Version history
| Odoo version | Version you download today | Price |
|---|---|---|
| 17.0 | 17.0.1.0.12 | $349 USD |
| 18.0 | 18.0.1.0.12 | $349 USD |
| 19.0 | 19.0.1.1.0 | $499 USD |
ECOSIRE module versions are <odoo major>.<module major>.<minor>.<patch>, so 19.0.1.1.0 is the Odoo 19 build of module version 1.1.0. Your installed version is shown in Apps.
The 19.0.1.1.0 release (27 August 2026) made the module licence-free (no activation, no key), fixed order dates that could truncate to 1 January, made the dashboard a pure read in the company currency with clickable charts, wired every operations-wizard option into the sync layer, implemented warehouse/location and stock-level sync against Brightpearl's warehouse service, routed shipping labels through the configured carrier API, and required elevated roles for workflow actions. The 17.0 and 18.0 rows are maintenance builds of the previous generation, which still use the ECOSIRE licence client — buyers on those versions follow the licence verification guide after purchase.