Whatnot Store Management

This is the installation and configuration guide for Whatnot Store Management (whatnot_store_management). The facts below were read out of the module source of the current build, 2.5.2 (17.0, 18.0, 19.0; the 20.0 build is 2.5.1).

Technical name	whatnot_store_management
Odoo versions	17.0, 18.0, 19.0, 20.0 (Community or Enterprise)
Current version	17.0 → 17.0.2.5.2, 18.0 → 18.0.2.5.2, 19.0 → 19.0.2.5.2, 20.0 → 20.0.2.5.1
Price	$499 USD — one-time, per Odoo version
Odoo module licence	OPL-1
Category	Connector

Requirements

Requirement	Detail
Odoo	17.0, 18.0, 19.0 or 20.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
Python packages	requests
Platform account	A Whatnot seller account with Seller API access: your own seller API key (wn_access_tk_…), or a Whatnot partner app (Client ID and Client Secret)

The module has no ECOSIRE licence client and needs no activation key.

Install the Python package into the same interpreter that runs Odoo:

sudo -u odoo pip install requests

Installation

1. Download the module for your Odoo version from the Odoo Apps Store (or your ecosire.com account if you bought it there).

2. Extract it into your addons path so that whatnot_store_management/__manifest__.py sits directly inside an addons directory:

   unzip whatnot_store_management*.zip -d /opt/odoo/addons/
   ls /opt/odoo/addons/whatnot_store_management/__manifest__.py   # sanity check

3. Restart Odoo, then in Apps click Update Apps List (developer mode on), search for Whatnot Store Management and click Install.

When the install finishes, a Whatnot menu appears in the main Odoo app switcher.

Configuration

Connect to Whatnot

Create a connection under Whatnot → Configuration → Instances. The main fields are:

Field	Technical name	Notes
Instance Name	name	Required
Company	company_id	Required
Environment	environment	Production (api.whatnot.com) or Staging (api.stage.whatnot.com); a wn_access_tk_test_ key is routed to staging
Authentication	auth_mode	Seller API key (your own account) or OAuth app (a partner app with Client ID and Client Secret, or portal-issued credentials)
API Key / Client ID	api_key	Partner-app Client ID; leave empty for portal-issued credentials
Client Secret	shared_secret	Needed for every automatic token refresh
Access Token / Refresh Token	access_token, refresh_token	Filled by the OAuth flow, or pasted from the Whatnot developer portal
Webhook Secret Key	webhook_secret	Used to verify every incoming webhook (HMAC-SHA256)
Whatnot Shop URL	shop_url	Informational only

Credentials are stored in password fields readable by system administrators only. OAuth access tokens are refreshed automatically before they expire (scheduled action Refresh OAuth Tokens).

The connection form has three buttons for the connection itself:

• Connect to Whatnot — partner apps: sends you to Whatnot's consent screen. Whatnot then returns you to Odoo through the OAuth callback (see Public endpoints below).
• Test Connection — checks the stored token against Whatnot. A refused token marks the connection Error and the failure stays on the record. A rate limit, a Whatnot server error or a network failure is reported and leaves the connection as it was.
• Paste New Access Token — the recovery action when a token has expired or been revoked. The pasted token is tested before it is stored, so a token Whatnot refuses changes nothing and your working tokens are kept.

While the connection cannot reach Whatnot, jobs that need the Seller API are held, not failed: they stay Pending and are counted on the Waiting for Connection button on the connection form. Webhook deliveries and other jobs that need no token keep running. Held jobs resume by themselves once the connection reads Connected again.

Tax and stock settings (Warehouse & Stock tab)

Two settings change how data is written into Odoo. Both are off by default, on a new install and on every upgraded database, so upgrading never changes how your orders post or how your stock behaves.

Setting	Technical name	When on
Whatnot Collects the Tax	whatnot_collects_tax	Imported orders carry no Odoo tax. Instead they get a shipping line, a Whatnot tax line and, if needed, a reconciliation line, so the sale order equals the total the buyer paid on Whatnot. Turn it on once your accountant confirms Whatnot's tax is your tax of record (Whatnot collects the tax from the buyer as marketplace facilitator, so leaving Odoo's product taxes on as well would count it twice). It applies to orders imported after you turn it on; orders already in Odoo are never rewritten.
Overwrite Odoo Stock from Whatnot	whatnot_overwrite_odoo_stock	Every stock import (the 10-minute inventory sync and the Import Stock From Whatnot button on a location) sets the on-hand quantity of each linked storable product in the import warehouse to Whatnot's quantity. When off, Odoo stock is never changed; Whatnot's quantity is only recorded on the product link. Turn it on only if Whatnot, not Odoo, is your stock of record.

While Whatnot Collects the Tax is off, orders import with the product's Odoo taxes and no shipping, tax or reconciliation line, exactly as before 2.5.0.

The instance also carries the order-workflow checkboxes auto_confirm_order, auto_create_invoice and auto_validate_invoice, the default warehouse, and the medium / high / critical risk thresholds. Leave anything you are not ready for switched off.

The module contacts api.whatnot.com (and api.stage.whatnot.com for staging), www.whatnot.com, and raw.githubusercontent.com for Whatnot's public product taxonomy. Your firewall must allow outbound HTTPS to them.

What Whatnot's API does not provide

Whatnot's Seller API has no query for payouts, customers, refunds or bid history. The module therefore:

• files buyers from imported orders (matched to Odoo contacts by Whatnot username, e-mail, phone, then exact name);
• keeps payouts and refunds as records you enter from the Whatnot Seller Hub, then reconciles them against orders and turns refunds into credit notes;
• does not show a bid history.

Stock: Odoo free quantity is pushed to each listing (listingAdjustQuantity), and quantities are read back from Whatnot's product variants onto each product link. Odoo on-hand is only overwritten when Overwrite Odoo Stock from Whatnot is on (above).

Public endpoints

The module exposes these URLs on your Odoo server. Both are auth='public' because Whatnot calls them without an Odoo session, so your Odoo must be reachable over HTTPS from the internet, and web.base.url must be your public address (both URLs are built from it).

Endpoint	Method	What it is for
/whatnot/callback	GET	OAuth callback. Whatnot redirects the seller here after the consent screen started by Connect to Whatnot. The request must carry the one-time state value the connection generated; a missing or unknown state is refused and nothing is stored. The authorization code is then exchanged for tokens with your Client Secret. Register https://<your-odoo-host>/whatnot/callback as the redirect URI of your Whatnot partner app. Not used with a Seller API key or portal-issued credentials.
/whatnot/webhook/<instance id>	POST	Webhook receiver. Register the delivery URL shown on each webhook record (it already contains the instance id). Every delivery's X-Whatnot-Webhook-Signature (HMAC-SHA256 of the raw body with the Webhook Secret Key) is verified before anything is stored; an unsigned or wrongly signed delivery is refused with HTTP 401 and logged. A verified delivery is acknowledged at once and processed through the queue, and a redelivery of an event already received does not create a second record.

/whatnot/webhook (without an id) and the older /whatnot/webhook/product, /order, /customer and /refund paths still answer with the same signature check, and work out the connection from the X-Whatnot-Seller-Id header. With more than one connection, use the URL with the instance id.

Scheduled actions

The module installs 15 scheduled actions (Settings → Technical → Scheduled Actions), all enabled on install:

Scheduled action	Runs every
Whatnot: Sync Products	30 minutes
Whatnot: Sync Orders	15 minutes
Whatnot: Reconcile Buyers from Orders	60 minutes
Whatnot: Sync Inventory	10 minutes
Whatnot: Process Queue Jobs	5 minutes
Whatnot: Auto Risk Detection	30 minutes
Whatnot: Generate Analytics	4 hours
Whatnot: Webhook Health Check	60 minutes
Whatnot: Cleanup Old Logs	24 hours
Whatnot: Process Workflows	10 minutes
Whatnot: Daily Summary Report	1 day
Whatnot: Refresh OAuth Tokens	1 hour
Whatnot: Sync Listings	30 minutes
Whatnot: Sync Livestreams	30 minutes
Whatnot: Sync Shipments	30 minutes

Whatnot asks for no more than 10 API requests per second; the module throttles itself under that, but shortening intervals is still the usual cause of throttling errors in the logs.

Using the module

The menu is laid out as:

• Whatnot → Dashboard
• Whatnot → Orders — Import Orders from File, Refunds & Returns, Shipments (preview)
• Whatnot → Products
• Whatnot → Customers
• Whatnot → Analytics — Payouts
• Whatnot → Livestream — Shows, Listings, Bids, Breaks, Authentications, Seller Level
• Whatnot → Operations — Run Operations, Bulk Operations, Inspect Whatnot Object, Queue Jobs, API Call Log, Webhook Deliveries, Logs
• Whatnot → Configuration — Instances, Locations, Payment Gateways, Scheduled Actions, Taxonomy & Categories, Shipping Profiles, Webhooks

A normal first run is:

1. Save the connection record and run Test Connection before importing anything.
2. Run a small import first from Operations → Run Operations — restrict it by date — and check the results before letting the scheduled actions take over.
3. Register the webhook delivery URL shown on each webhook record in the Webhooks tab of the Whatnot developer portal (or ask sellerapi@whatnot.com). The module processes the eleven topics Whatnot documents; other topics are stored and acknowledged.
4. Watch Queue Jobs and the API Call Log during the first full sync. Failed jobs can be retried from the list.

Importing orders from a Whatnot export

Orders → Import Orders from File imports the Whatnot order export (CSV). Use it when the Seller API cannot be reached. It is limited to Whatnot managers. Orders are keyed on the Whatnot order id, so importing the same file again updates orders instead of duplicating them, and an order imported from a file is not imported a second time when the API sync reaches it. The file import uses the same buyer and product matching as the API import and never contacts Whatnot. It reports created, updated, skipped and failed rows, with a reason for every skipped row.

Whatnot publishes no format for this export, so column headers are matched against a list of known names. A file whose headers are not recognised is refused, and the message lists the headers found next to the fields needed: send that message to info@ecosire.com and we add the mapping.

What's new in 2.5.2

Dashboard and list fixes (17.0, 18.0 and 19.0):

• Dark mode themes the whole dashboard. Cards, charts, placeholders and banners follow Odoo's dark colour scheme instead of staying light under a dark menu bar.
• The Order Status chart draws. It could stay blank behind its legend. The charts are now built from the loaded figures, and a chart with nothing to show says No orders in this period or No sales in this period.
• Loading, empty and error states are clear. The first load shows placeholders instead of zeros and Not Configured. A company with no Whatnot store sees one No Whatnot store connected yet panel with Connect a Whatnot store and Setup guide. A failed load shows the error at the top with Try again and a link to the sync logs. Sync Now appears once a store is connected.
• Phone layout. The store name in the dashboard header stays on one line and is shortened with an ellipsis instead of running off the screen.
• Lists. The hidden Active column no longer leaves an empty column on the Instances, Orders and Locations lists. On 18.0 the Customers list shows Last Sync and Active as optional columns (hidden by default) so it fits a phone screen. The Orders, Customers and Products cards on the dashboard open with the keyboard (Enter or Space).

What's new in 2.5.1

• Buyers are matched to the right contact. An underscore or percent sign in a buyer's Whatnot username, e-mail or name was treated as a wildcard, so a buyer such as j_smith could be matched to an existing contact jasmith. These values are now compared literally. A match that differs only in upper or lower case still matches.

What's new in 2.5.0

• Orders can carry Whatnot's own shipping and tax. With Whatnot Collects the Tax on, orders get Whatnot's shipping and tax lines and a reconciliation line, so they equal what the buyer paid. Off by default.
• An expired token no longer stops everything. Webhook deliveries and jobs that need no token keep running; jobs that need the API are held, counted under Waiting for Connection, and resume when the connection is fixed.
• Paste New Access Token tests the new token before storing it, and Test Connection keeps a refusal on the record and treats temporary Whatnot problems as temporary.
• Import Orders from File for when the API cannot be reached.
• Stock import never changes Odoo stock unless you ask (Overwrite Odoo Stock from Whatnot, off by default).

Troubleshooting

Symptom	Cause and fix
The connection will not validate	Re-check the credentials and the Environment. Most failures are a mistyped secret, or a staging key used against production (or vice-versa).
Connection shows expired	Whatnot refused the token refresh. Use Paste New Access Token, or supply the Client ID and Client Secret so the connection can renew itself. Jobs that need the API wait under Waiting for Connection and resume once it reads Connected.
OAuth state mismatch after the consent screen	The callback did not match a connection that started the flow. Click Connect to Whatnot again from the connection, and check that web.base.url is your public address.
Orders total more or less than you expect	Check Whatnot Collects the Tax: off, the product's Odoo taxes apply; on, Whatnot's shipping and tax lines are used.
Nothing syncs even though the connection is fine	The scheduled actions are disabled, 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 queue job and API call log for that run. Rate limiting and rejected field values are the two common causes; both are logged with Whatnot's own error text.
Webhooks arrive but are rejected	The Webhook Secret Key on the instance does not match the key Whatnot issued for your app.
The requests library is required	Install requests into the interpreter that runs Odoo.

Version history

Odoo version	Current version
17.0	17.0.2.5.2
18.0	18.0.2.5.2
19.0	19.0.2.5.2
20.0	20.0.2.5.1

ECOSIRE module versions are <odoo major>.<module major>.<minor>.<patch>. Your installed version is shown in Apps.

Support

• General troubleshooting
• Email: info@ecosire.com
• Support portal