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.4, 18.0 → 18.0.1.1.4, 19.0 → 19.0.1.2.1 |
| Price | $499 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.
The 19.0 build (19.0.1.2.1) speaks Bonanza's own Bonapitit API protocol and connects with the Fetch User Token handshake described in this guide. The 17.0 and 18.0 builds are at 1.1.4 and have not yet received that rewrite, so the handshake below is specific to the 19.0 build. Everything else on this page — installation, menus, imports, webhooks, scheduled actions — applies to all three.
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. Bonanza issues API developer credentials after partner approval — request them by emailing api-support@bonanza.com from your seller account. |
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 — has no OAuth 2.0 login page. It authenticates with a developer account name, a certification token and a user token, and the user token is obtained through a handshake rather than a password:
fetchToken— the module asks Bonanza for a token, sending the URL Bonanza should return the seller to.- Bonanza answers with a token, an authentication URL and an expiry.
- The module sends the seller to that authentication URL. The seller signs in to Bonanza there and approves that this developer may act for the booth.
- Bonanza emails the booth account to verify the token. Until the seller confirms that email, the token does not work — so the module records it and says so plainly instead of claiming the store is connected.
In Odoo the whole handshake is one button:
- Open Bonanza → Configuration → Instances and create a connection record for your store.
- Enter your developer account name in Developer Account Name and the certification token from Bonanza in Certification Token. Both come from the credentials email Bonanza sends after approving your API access.
- Save, then click Fetch User Token. Odoo asks Bonanza for a token and opens Bonanza's authorisation page for you to approve.
- Confirm the verification email Bonanza sends to your booth account. The record stays in Draft until the token is usable — that is expected, not an error.
- Click Test Connection. It makes a live call with your credentials, and the record's status moves to Connected when the handshake succeeds. A successful test also creates the booth mapping under Locations for you.
The connection fields the module defines are:
| Field on screen | Technical name | Notes |
|---|---|---|
| Instance Name | name | Required |
| Bonanza Booth URL | shop_url | Required — the public address of the seller's booth, e.g. bonanza.com/booths/yourbooth |
| Company | company_id | Required |
| Developer Account Name | api_key | Required for the handshake; masked on screen |
| Certification Token | shared_secret | Required for the handshake; masked on screen. Also the secret Bonanza signs webhooks with |
| User Access Token | access_token | Filled in by Fetch User Token; masked on screen |
| Token Fetched On / Token Expires On | token_fetched_at, token_expires_at | Read-only. Bonanza's reply includes an expiry, documented as one year out |
A successful Test Connection is the only thing that marks the record connected. There is no activation key and no licence step — the status field reflects whether Bonanza answered, nothing else.
The connection record also carries three 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 contacts one host only: api.bonanza.com, over HTTPS. Your firewall must allow outbound HTTPS to it.
Endpoints this module exposes
The connector serves six endpoints, relative to your Odoo base URL (web.base.url). Two are the return points of the token handshake just described; four receive Bonanza webhooks.
| Endpoint | Method | Auth | Purpose |
|---|---|---|---|
/bonanza/authorize | GET | Signed-in Odoo user | Starts the token handshake for one connection record. This is what the Fetch User Token button opens; it takes an instance_id and redirects the browser on to Bonanza's authorisation page. |
/bonanza/authorize/complete | GET | Signed-in Odoo user | Where Bonanza returns the seller after they approve the request. It confirms the authorisation was recorded and tells the seller to confirm Bonanza's verification email before testing the connection. |
/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 two handshake endpoints are not public. They require a signed-in Odoo user, and the record rules on the connection model decide which connection a given user may reach — so you start the handshake from the Fetch User Token button on your own instance record rather than by typing a URL.
Both handshake endpoints are built from web.base.url. Set it to your real HTTPS address before you connect — Settings → Technical → System Parameters — or Bonanza is handed a return URL that points nowhere.
None of these endpoints lets an anonymous caller inject data:
/bonanza/authorizerefuses an instance the caller's company cannot see, and refuses to start when the developer name or certification token is missing — it tells you which field to set instead./bonanza/authorize/completeonly ever reads the connection through the same record rules; it exposes nothing but a confirmation page.- 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 Certification Token). 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.
The dashboard period filter
Bonanza → Dashboard opens with a period bar — Today, 7D, 30D, 90D, Year and Custom. Changing it re-reads every KPI, chart and breakdown on the page for that window, and the numbers always match the period shown.
Your period choice applies to your view only. It is remembered in your own browser, and opening the dashboard no longer changes the period saved on the shared connection record — so two people watching the same booth on different periods no longer overwrite each other's selection, and reading the dashboard no longer writes to the database at all.
Locations is where your booth is mapped onto an Odoo warehouse: the booth's name, ID, public URL, subscription level and vacation flag, with the warehouse to assign imported orders to and the warehouses to sum stock from when exporting inventory.
Troubleshooting
Connecting
| Symptom | Cause and fix |
|---|---|
| Fetch User Token asks for the developer name and certification token | Both must be saved on the instance first — they are what the fetchToken call is made with. Fill them from Bonanza's credentials email and try again. |
| Bonanza says the token is not valid yet | Expected until you confirm Bonanza's verification email. The token is recorded on the instance but is not usable before that confirmation. |
| The connection will not validate | Re-check both credentials in the connection table above. Most failures are a mistyped token, or credentials issued for Bonanza's sandbox while the module points at production (or vice-versa). |
| The handshake page cannot be reached | Odoo could not reach api.bonanza.com — check outbound HTTPS from the server. The record is set to Error and the platform's own message is shown. |
Syncing
| Symptom | Cause and fix |
|---|---|
| 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 Certification Token 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 customers | Check the existing contacts before re-running an import that half-finished rather than importing on top. Orders and customers resolve to the same contact record, so one buyer stays one contact. |
Version history
| Odoo version | Version you download today |
|---|---|
| 17.0 | 17.0.1.1.4 |
| 18.0 | 18.0.1.1.4 |
| 19.0 | 19.0.1.2.1 |
ECOSIRE module versions are <odoo major>.<module major>.<minor>.<patch>, so 19.0.1.2.1 is the Odoo 19 build of module version 1.2.1. Your installed version is shown in Apps.
What changed in recent versions, in terms of what you do differently:
- 1.1.4 (17.0 and 18.0 builds) — brings the two older builds up to the same behaviour as 1.2.1 on the points that cost you data, and closes two defects that were specific to them. Webhook signature verification could never succeed on these builds: the library used for the HMAC comparison was imported only inside the signature generator, not where the comparison runs, so every well-formed webhook was rejected with an internal error. A failed connection test also used to lose its own result — the "Error" status and the reason were rolled back with the failure — so the connection silently kept its previous status; the status now sticks and the reason is written to the log. Alongside those, the 17.0/18.0 builds receive the same fixes as 1.2.1: the dashboard read no longer writes to the connection record, order dates are parsed properly instead of being reduced to a year by a bad fallback, orders and customers resolve to one shared contact record, and the dashboard's currency symbol comes from your connection rather than a hardcoded dollar sign.
- 1.2.1 — the dashboard period filter no longer writes to the connection record while it reads. Picking a period is now per-view and remembered in your own browser, so two users on different periods no longer overwrite each other, and the KPI figures always match the period shown.
- 1.2.0 — the connection and the API client were rebuilt against Bonanza's own documentation. The connector now speaks the Bonapitit API protocol (previously it used an endpoint style the platform does not serve, so no call could complete), and the Fetch User Token handshake replaces the earlier login flow — including the step where Bonanza emails your booth account to verify the token. Order and customer addresses, category imports and order timestamps are read from the field names Bonanza actually sends, so imported orders arrive with a full delivery address and January-to-September order dates are no longer misread. Locations now show the real booth data and map to a warehouse, Logs and Queue Jobs show their creation dates, and the dashboard uses your booth's own currency symbol.
- 1.1.3 — the customer/address helper functions ship inside this module again, so a clean single-module install can import its first address without an error.
- 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 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.