Bonanza Store Management
This is the installation and configuration guide for Bonanza Store Management, the module you downloaded from your ECOSIRE dashboard. Everything on this page describes the bonanza_store_management module exactly as it ships today — the facts below were read out of the released build, not from a roadmap.
| Technical name | bonanza_store_management |
| Odoo versions | 17.0, 18.0, 19.0 (Community or Enterprise) |
| Current shipped version | 17.0 → 17.0.1.1.0, 18.0 → 18.0.1.1.0, 19.0 → 19.0.1.1.0 |
| Price | $349 USD — one-time; each Odoo major version is a separate product |
| Odoo module licence | OPL-1 |
| Category | Connector |
Since version 1.1.0 the module installs and runs standalone. There is no ecosire_license_client dependency, no activation step and no key to paste — buy the module, install it, configure your Bonanza connection and it works. Licensing is contractual (OPL-1); the software does not phone home to unlock itself.
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 Bonanza seller 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. Pick the file matching the Odoo version you run.
2. Extract into your addons path
unzip bonanza_store_management_v19_*.zip -d /opt/odoo/addons/
ls /opt/odoo/addons/bonanza_store_management/__manifest__.py # sanity check
The module must end up as a single top-level bonanza_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 Bonanza Store Management and click Install.
- Odoo pulls in the Odoo apps listed above automatically.
When the install finishes, a Bonanza menu appears in the main Odoo app switcher. Nothing else is required — the module is fully usable the moment it installs.
Configuration
Connect to Bonanza
Bonanza's API (the "Bonapitit" API) does not use a standard OAuth login — it authenticates with a developer name, a certificate and a user token triplet. The connector therefore connects by credential entry, not by a login button:
- Email api-support@bonanza.com from your seller account and request API developer credentials (Bonanza issues them after partner approval).
- In Odoo, open Bonanza → Configuration → Instances and create a connection record for your store — the fields are listed below.
- Enter your developer name in API Key / Client ID and your certificate in Client Secret.
- Obtain a user token through the API's
fetchTokencall (the credentials email from Bonanza explains how; the API documentation lives at api.bonanza.com/docs) and enter it in Access Token. - Click Test Connection — it makes a live call with your credentials, and the record's status moves to Connected when the handshake succeeds.
The Authorize button on the record does not start a login flow — Bonanza has none to start. It opens the same checklist above, so you can ignore it once the fields are filled in.
The fields the module defines for the connection are:
| Field | Technical name | Type | Required |
|---|---|---|---|
| Instance Name | name | Char | Yes |
| Bonanza 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. The password field is legacy — Bonanza deprecated private app passwords in 2022; use the developer credentials and user token described above instead.
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. Leave anything you are not ready for switched off, and turn them on one at a time.
The module's own source contacts this host: api.bonanza.com. Your firewall must allow outbound HTTPS to them.
Public endpoints this module exposes
The connector serves six externally reachable endpoints, relative to your Odoo base URL (web.base.url). Two serve an app-style connect handshake kept for installations that arrive from a Bonanza administration page; four receive Bonanza webhooks. Your day-to-day connection uses the credential entry above — these endpoints are what Bonanza's servers call, not something you drive by hand.
| Endpoint | Method | Auth | Purpose |
|---|---|---|---|
/bonanza/install | GET | Public (unauthenticated) | Entry point for the install / connect request coming from Bonanza. It resolves the shop to a saved connection record and redirects the browser on to the Bonanza authorization screen. |
/bonanza/callback | GET | Public (unauthenticated) | Redirect target for the app-style handshake — receives an authorization code and exchanges it for an access token, stored on the matching connection record. |
/bonanza/webhook/product | POST | Public, HMAC-verified | Receives product webhooks from Bonanza and queues a product import job. |
/bonanza/webhook/order | POST | Public, HMAC-verified | Receives order webhooks from Bonanza and queues an order import job. |
/bonanza/webhook/customer | POST | Public, HMAC-verified | Receives customer webhooks from Bonanza and queues a customer import job. |
/bonanza/webhook/refund | POST | Public, HMAC-verified | Receives refund webhooks from Bonanza and queues a refund import job. |
The module builds the OAuth redirect URI itself, as web.base.url + /bonanza/callback. Set web.base.url to the real HTTPS address before you connect — Settings → Technical → System Parameters — or the platform is handed a redirect URI that points nowhere.
None of these endpoints let an anonymous caller inject data:
/bonanza/installrefuses a shop domain it cannot match to a savedbonanza.instancerecord, verifies the HMAC when Bonanza sends one, and issues a single-usestatenonce./bonanza/callbackre-verifies the HMAC, rejects astatethat does not match the nonce just issued, and refuses a request that carries no authorization code.- The four webhook endpoints require two HTTP headers:
X-Bonanza-Shop-Domain(to resolve which saved connection the event belongs to) andX-Bonanza-Hmac-SHA256(a base64 HMAC-SHA256 of the raw request body, computed with the connection's Client Secret). A request that fails either check is rejected before any data is queued.
A verified webhook does not import inline — it creates a pending queue job (Bonanza → Operations → Queue Jobs), which the Bonanza: Process Queue Jobs scheduled action then picks up and runs. A delivery failure on Bonanza's side is therefore never lost work; it is a pending job you can inspect and replay.
Scheduled actions
The module installs 11 scheduled actions (Settings → Technical → Scheduled Actions), all enabled on install:
| Scheduled action | Runs every |
|---|---|
| Bonanza: Sync Inventory | 10 minutes |
| Bonanza: Process Queue Jobs | 5 minutes |
| Bonanza: Process Workflows | 10 minutes |
| Bonanza: Sync Customers | 60 minutes |
| Bonanza: Import Payout Reports | 6 hours |
| Bonanza: Import Refunds | 30 minutes |
| Bonanza: Auto Risk Detection | 30 minutes |
| Bonanza: Generate Analytics | 4 hours |
| Bonanza: Webhook Health Check | 60 minutes |
| Bonanza: Cleanup Old Logs | 24 hours |
| Bonanza: Daily Summary Report | 1 day |
Product and order imports are not on fixed timers — they run when you trigger them from Run Operations or when a webhook queues them. 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.
Using the module
The module's menu is laid out as:
- Bonanza → Dashboard
- Bonanza → Orders
- Bonanza → Refunds
- Bonanza → Products
- Bonanza → Customers
- Bonanza → Payouts
- Bonanza → Analytics
- Bonanza → Operations — Run Operations, Queue Jobs, Logs
- Bonanza → Configuration — Instances, Locations, Payment Gateways, Scheduled Actions, Webhooks
A normal first run is:
- Save the connection record and confirm the module reports a successful connection before importing anything.
- Run a small import first — Bonanza → Operations → Run Operations — and check the results before letting webhooks and the scheduled actions take over. The wizard offers: import products, orders, unshipped orders, customers, stock levels, locations and payment gateways; export products, customers and stock levels; update order status / export fulfilment; import payout report; import refunds.
- Watch the log records during the first full sync. Failures are recorded there rather than raised at the user.
Each record in a sync run is processed inside its own database savepoint: if one platform record is malformed or rejected, that single record is rolled back and logged, and the rest of the run completes. You will see the failed record in the logs with the platform's own error text instead of a half-finished import.
Troubleshooting
Syncing
| 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. The failing record itself is skipped, not the whole run. |
| Webhooks are not arriving | Check that Bonanza is sending both required headers and that the Client Secret on the connection matches the one Bonanza signs with. The Bonanza: Webhook Health Check scheduled action and the log records show rejected deliveries. |
| 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 |
|---|---|
| 17.0 | 17.0.1.1.0 |
| 18.0 | 18.0.1.1.0 |
| 19.0 | 19.0.1.1.0 |
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.
What changed in recent versions, in terms of what you do differently:
- 1.1.0 — the licence-client dependency was removed. There is no activation step any more; installing the module is the whole setup.
- 1.0.12 — sync hardening: every record in a sync or import run is now isolated in its own savepoint, so one bad platform record can no longer abort the whole run or silently roll back the good records imported before it. No configuration change is needed to benefit.