TikTok Shop Store Management - Installation

This page covers installation and connection. For the exact supported API boundary, synchronization behavior, historical order backfill, Affiliate API permission requirement, and troubleshooting, use the TikTok Shop workflow guide.

Item	Current release
Technical name	tiktok_store_management
Odoo 17	17.0.2.12.6 — $599 USD, OPL-1
Odoo 18	18.0.2.12.6 — $599 USD, OPL-1
Odoo 19	19.0.2.15.0 — $599 USD, OPL-1
Editions	Community and Enterprise
Python dependency	requests

Each Odoo major version is a separate product with its own price and its own build. Buy the version you actually run.

Nothing to unlock

No key is entered anywhere and there is no unlock step, on any of the three Odoo versions. You install the ZIP and the connector works. Your rights are governed by the OPL-1 terms the ZIP ships under, and support and updates still follow your purchase.

Builds older than 2.11.0 bundled a separate ECOSIRE licensing add-on and blocked features until a key was entered. That dependency and every execution-blocking check have been removed. If Odoo asks you for a key, you are on one of those older builds — download the current build from your dashboard.

New on Odoo 19 since 19.0.2.12.6: shipping and packages have had the most attention. A package you have shipped no longer falls back to "Created on TikTok"; shipping labels are requested only in the sizes TikTok actually issues; stock updates now reach TikTok and identify each item the way TikTok does; products can be exported with their images and category attributes; every scheduled synchronization has its own interval; and package synchronization no longer re-reads your whole fulfilment history. Earlier in the same run of releases, Sync Packages started working again after being refused on every attempt, order synchronization stopped taking around half an hour, and Sync Orders moved into the background instead of holding your browser. Each is described under What changed on Odoo 19 below.

The connector implements a verified subset of TikTok Shop seller operations. It does not claim the complete Open API, provider LIVE viewer or engagement metrics, or provider webhook-subscription CRUD.

Install

1. Download the archive matching your Odoo major version from the ECOSIRE Dashboard.
2. Extract the top-level module folder into an Odoo addons directory.
3. Install requests into the same Python environment that runs Odoo.
4. Restart Odoo, update the Apps list, and install TikTok Shop Store Management.

unzip tiktok_store_management_v19_*.zip -d /opt/odoo/addons/
sudo -u odoo pip install requests
sudo systemctl restart odoo

The module directory must contain __manifest__.py directly under tiktok_store_management/; avoid an extra nested folder. The connector depends only on standard Odoo apps — sale_management, stock, account, delivery, mail, web, product and contacts — so there is no second ECOSIRE archive to download first.

Upgrade an existing database

Copy the new module source into the addons path, restart Odoo, and run an Apps upgrade for TikTok Shop Store Management. Copying files without upgrading does not load new fields, views, data, or migrations.

For a production database, take a restorable backup before the upgrade and verify afterward that Apps shows the expected version and the Odoo update log contains no module-load errors.

Upgrading an Odoo 19 database to 19.0.2.15.0 runs migrations that retarget the two synchronization schedules so the shop's Sync Frequency is honoured, and — on databases that passed through 19.0.2.11.0 — replay the freebie de-duplication step that build skipped. Both run automatically as part of the Apps upgrade.

The first order synchronization after upgrading to 19.0.2.15.0 behaves like the old one, because there is nothing recorded yet to compare against. From the second run onwards it is much faster; see Faster order synchronization.

Connect TikTok Shop

1. Create or select the seller application in TikTok Shop Partner Center.
2. Obtain approval for the scopes required by the workflows you will enable.
3. In Odoo, open TikTok Shop → Configuration.
4. Enter the protected application credentials and shop identity, assign the Odoo company, and select the region matching the shop.
5. Complete authorization and use Test Connection.
6. Enable only the synchronization areas approved for that application.

Affiliate Seller synchronization needs TikTok's Affiliate API read permission; a normal seller authorization does not include it automatically. TikTok error 105005 indicates that provider-app permission is missing.

Choose when the shop synchronizes (Odoo 19)

On Odoo 19, a shop that is authorized but has every scheduled-sync switch off will never fetch anything until somebody presses Sync, and the configuration now says so on its Synchronization tab until you either sync once or turn a schedule on. Nothing is switched on for you.

The Automation panel carries the four scheduled lanes — products, orders, customers and affiliate. Sync Frequency on the same configuration decides how often the scheduled order and affiliate runs happen for that shop; see Scheduled synchronization below.

Public endpoints

The module serves two routes without an Odoo session. Both are declared on the TikTok Shop side, so both must be reachable over HTTPS from the internet. web.base.url must already hold the real public URL of the database — the connector composes the redirect URI from it.

Endpoint	Method	Set in Partner Center as
/tiktok/callback	GET	The app's redirect / callback URI
/tiktok/webhook	POST	The app's webhook (push) URL

/tiktok/callback

The return leg of seller authorization. Authorize in the Odoo configuration mints a one-time state token valid for 10 minutes and opens TikTok's authorization page with redirect_uri set to <web.base.url>/tiktok/callback. Use that exact URI in Partner Center; a mismatch fails the authorization before Odoo is reached.

The state is consumed exactly once, atomically, so a replayed, expired, or already-used callback is refused rather than exchanged. A missing code or state, or a state that fails to consume, renders a failure page instructing a retry of the Authorize step from Odoo. The authorization code is exchanged for tokens server-side only after the state has been consumed.

/tiktok/webhook

The push receiver. It fails closed at four separate points and processes nothing until all four pass:

1. The body must be JSON carrying a shop_id.
2. That shop_id must resolve to exactly one active tiktok.configuration.
3. That configuration must have an active tiktok.webhook receiver record.
4. The Authorization header must equal HMAC-SHA256(app_secret, app_key + raw body) as a hex digest, computed from the app credentials on the matched configuration.

Any of those failing returns HTTP 401 and is logged. A verified delivery is claimed against a unique fingerprint before dispatch, so a redelivered event is acknowledged as {"status": "success", "duplicate": true} without being processed twice. Claim and dispatch run in one savepoint: if dispatch raises, the claim rolls back and the endpoint answers HTTP 503 with {"status": "retry"} so TikTok retries the same delivery rather than dropping it.

The module's other routes — /tiktok/api/status, /tiktok/api/sync and /tiktok/dashboard/data — are internal JSON-RPC endpoints for the module's own screens. They require a logged-in Odoo user and are not part of Partner Center setup.

What changed on Odoo 19

Everything in this section ships on Odoo 19, in the releases between 19.0.2.10.19 and 19.0.2.15.0. Odoo 17 and 18 are on 2.12.6 and carry a subset — see Where Odoo 17 and 18 stand. Full behaviour is documented in the TikTok Shop workflow guide.

Shipping and packages (19.0.2.15.0)

A package you have shipped stays shipped. TikTok's status feed keeps reporting a package as "processing" for a while after it has accepted your shipment. The connector was copying that status straight onto the package, which put it back into the not-yet-shipped state and offered the Ship button again on a package that was already on its way — with a real risk of handing the same package over twice. A package now only ever moves forward: created, then shipped, then delivered, with cancellation available until it is delivered. TikTok's own wording is still shown, unchanged, in the TikTok Status field, so you can always see what TikTok is reporting.

The same package cannot be handed over twice. Both places that can ship a package — the Ship button on the package, and the "ship the package TikTok already created" line in Arrange Shipment — now run the same check first and refuse if the package is already shipped or already carries a tracking number. TikTok only issues a tracking number once it has accepted a shipment, so one is proof the handover went through even if the status has not caught up.

Asking for a label before shipping now explains itself. TikTok produces a label or packing slip only once it has accepted the shipment; asking earlier came back as an unexplained provider error. The connector now says so before contacting TikTok and names the packages that still need to be shipped. If you select a mix of shipped and unshipped packages, the shipped ones still produce their documents and the rest are listed individually.

Only the paper sizes TikTok issues are offered. The document window offered A4 and 4x6; TikTok Shop issues these documents in A6 or A5 only and rejected anything else with an error code that gave no hint which choice was wrong. It also offered PNG as a format, which this service does not accept — a PNG label is a document type of its own.

More of the documents TikTok issues. The window now offers the shipping label, the packing slip, both together, the PNG picture label, the hazmat label, and the Brazilian invoice label, plus ZPL output for the Brazil and Mexico markets. Where TikTok fixes the paper size itself (hazmat, invoice label) or ignores it (PNG label), the size and format choices are hidden rather than offered and then quietly ignored.

Printing a label also records the tracking number TikTok returns with it, onto the order and the delivery, with no extra synchronization.

Package synchronization no longer re-reads your whole fulfilment history. After its first run it asks TikTok only for packages that have changed since the last one, which is what makes it fast on a shop with a long order history; once a day it still re-reads everything so nothing can hide behind a late timestamp. If a run stops at its internal page limit it now says so in the synchronization log instead of finishing quietly.

Packages can keep themselves up to date. Package synchronization used to be the only TikTok data that never moved on its own — statuses and tracking advanced only when somebody pressed Sync Packages. Switch on Auto Sync Packages on the shop and give packages their own interval alongside the other synchronizations. It is off by default, so nothing starts happening on its own because of this upgrade.

An interval for every synchronization (19.0.2.14.0)

Every scheduled synchronization now has its own numeric interval and a minutes-or-hours unit on the shop: products, orders, customers, inventory, finance, affiliate orders, official LIVE sessions — and, from 19.0.2.15.0, packages. The shortest interval accepted is five minutes, so a shop cannot be configured into TikTok's rate limits.

The scheduler itself wakes every five minutes and then runs only the shops that are due. A five-minute check is not a five-minute synchronization: a lane set to one hour is contacted once an hour. That is now stated on the shop's Synchronization tab.

Existing order and affiliate frequencies are migrated to their exact numeric equivalents, and the defaults for every other lane preserve the schedule it already had — upgrading does not make any shop synchronize more often.

Stock updates reach TikTok, and product export carries images (19.0.2.13.0, 19.0.2.13.1)

Stock levels now actually reach TikTok Shop. Every inventory update was being sent to an address TikTok does not serve, so no stock change ever arrived and the shop kept selling from stale quantities.

And they name the item the way TikTok does. Correcting the address was necessary but not enough: the update still identified each item by its Odoo internal reference, while TikTok only recognises the item code it issues itself. Updates are now built strictly from that code. A product TikTok has not yet given a code for is reported as skipped, by name, with the step needed to fix it ("run a product sync"), instead of being silently counted as updated — and the synchronization log now records why a product failed, not only which products were skipped.

Exporting a product to TikTok Shop now works. TikTok requires at least one image on every product and refuses any image address it does not host itself, so a listing can only be created after its pictures have been uploaded to TikTok. The connector now performs that upload, and sends real category attributes and rules rather than an empty set.

Official LIVE sessions and freebies (19.0.2.12.11)

Official LIVE session synchronization was importing affiliate creators' lives alongside your own shop's account, which then fed the "Official Live Window" freebie condition. The filter now rides every page of the request, and sessions imported earlier that TikTok does not confirm are re-tagged, never deleted.

Freebie re-evaluation used to only ever add lines, so late affiliate attribution or a change in the order total could accumulate several freebies on one order. It now reconciles the automatic lines with the rules that currently win: stale lines are removed, delivered or invoiced ones are kept and flagged, and lines you added by hand are never touched.

Faster order synchronization (19.0.2.12.10)

A manual Sync Orders could take around thirty minutes, and the scheduled run did the same amount of work every time. Every order inside the window was downloaded again and rewritten in full on every run — whether or not anything had changed — and each order was downloaded in a separate request. Three corrections:

• Orders are downloaded fifty at a time instead of one at a time, so a week of orders costs a handful of requests rather than several hundred.
• The connector remembers when TikTok last changed each order and skips orders that have not moved since the previous synchronization.
• Each run asks TikTok only for orders updated since the last successful run, with a safety overlap, instead of re-reading the whole window.

Nothing is skipped silently. An order TikTok reports as changed, one whose last synchronization ended in an error, and one the connector has never seen are all read in full; and once a day the whole window is re-read without the "changed since" filter, so nothing can hide behind a late timestamp. The synchronization summary now reports how many orders were unchanged, so a fast run is legible instead of looking like it did nothing — unchanged orders count as a success, never as skipped or failed work.

The first run after the upgrade behaves as before, because there is nothing recorded yet to compare against. From the second run onwards a typical synchronization completes in a fraction of the time.

Sync Orders runs in the background (19.0.2.12.10)

The button used to hold your browser for the entire synchronization, which on a large catch-up could look like the page had frozen — and on hosted Odoo could be cut off by the server's request time limit, losing the run.

It now confirms that synchronization has started, hands the work to a background job, and notifies the person who asked for it when the job finishes. The shop's form shows the run's state while it is in progress, and clicking again while one is running does not start a second one. The queued run is picked up immediately; a scheduled runner re-checks every 30 minutes as a safety net.

Sync Packages works again (19.0.2.12.9)

Every package synchronization was refused by TikTok with error 36009004 before it reached the shop — on all attempts, on every shop, and it kept happening after a re-authorization. The request was sending the page size in the wrong part of the call: TikTok requires it in the web address of the package search, and it was being sent in the message body instead, so a value TikTok treats as mandatory was missing. The page size, the page marker and the sort order are now sent where TikTok documents them, and the message body carries only the date and status filters. Orders and shipping were never affected, which is why only package synchronization failed.

Packages are now read in a stable order — oldest first, by creation date — while paging through them. Sorting by last-updated could move a package behind the point already read, and skip it, if it was packed or shipped during the synchronization. This is the same correction already applied to order synchronization.

The message for error 36009004 no longer blames your credentials. TikTok reuses this single code for a number of different request problems, so it cannot identify a cause on its own; the previous wording asked you to re-check the App Key and App Secret, which was wrong advice for this failure. The message now explains that TikTok rejected the format of the request, notes that your credentials are usually not the cause when other synchronizations are working, and points to the Odoo server log, where the connector records TikTok's own explanation next to the request reference.

Scheduled synchronization (Odoo 19)

Each shop's Sync Frequency (Every 15 minutes … Daily) decides how often that shop's scheduled order and affiliate synchronization runs. Before 19.0.2.12.0 the setting was displayed but governed nothing: orders ran on a fixed 30-minute cycle and affiliate on a fixed 6-hour cycle whatever you chose.

Both lanes follow the one setting, so creator attribution no longer lags the orders it belongs to. The two schedules tick every 15 minutes and measure each shop against its own cadence and its own last successful sync, so one schedule serves shops on different cadences and a failed run is retried on the next tick instead of waiting out a whole interval.

Sync Frequency governs those two lanes only. The others keep their own fixed cycles and do not read the setting:

Lane	Cadence
Orders	Per shop, from Sync Frequency
Affiliate orders	Per shop, from Sync Frequency
Products	Every hour, fixed
Inventory	Every 15 minutes, fixed
Customers	Every 6 hours, fixed
Settlement statements	Every 6 hours, fixed
Official LIVE sessions	Every 6 hours, fixed (ships switched off)
Freebie rules	Every hour, fixed

What Settings → Technical → Scheduled Actions shows for orders and affiliate is the 15-minute tick at which Odoo checks which shops are due — not the per-shop cadence. A shop set to Every hour is examined every 15 minutes and synchronized once an hour.

Read this before upgrading a live shop. A shop with scheduled sync on moves from the old fixed cycles to whatever its Sync Frequency says — for a shop that never changed the setting, that is Every hour. Stored values are not rewritten by the upgrade. A shop that wants 30-minute orders should now select Every 30 minutes, which works where it previously did not. Which shops sync at all is unchanged: the Auto Sync Orders and Auto Sync Affiliate Orders opt-ins still decide that, and a shop that opted out is still skipped.

The import wizard's own Sync Frequency field previously offered its own vocabulary and no code read it. It now borrows the configuration's list, is optional, and applies the chosen cadence to the shop when the import runs. Leaving it empty changes nothing.

Affiliate synchronization (Odoo 19)

Sync Affiliate is incremental: it resumes from the last successful run with a two-day late-arrival overlap instead of replaying the whole configured history on every click or cron tick. For a deliberate full repair, use the Backfill Affiliate History action.

Auto Sync Affiliate Orders sits in the Automation panel with the other three lanes rather than alone under Affiliate Sync Window, and an affiliate shop with no affiliate schedule shows a note naming the switch that fixes it. A scheduled run that covered no shop says so in the log and names the affiliate shops it skipped, instead of finishing silently.

Affiliate paging is also bounded and self-correcting: the connector treats TikTok's reported total as a terminal condition, rejects repeated cursors, and when TikTok reports more rows than its cursor returns it retries bounded sub-windows down to one-second slices. From 19.0.2.12.6 a closed cursor that reports at most the existing page ceiling is re-walked once as a single bounded cursor before the connector falls back to subdividing time. If a run cannot be reconciled it fails closed and leaves the last-success cursor unchanged, so nothing is silently skipped.

Arrange Shipment outside the United States (19.0.2.12.7)

Arrange Shipment previously opened every order by asking TikTok for its eligible shipping services — the flow TikTok publishes for buying a label in the US and Japan. In every other market TikTok Shop creates the package itself, so that request was rejected with error 21001001 and no shipment could be arranged from Odoo.

The wizard now takes one of three paths, in this order:

1. A package TikTok already created. It is handed over directly (pickup or drop-off), recorded against the order, and the tracking number is written back. A package that Sync Packages already imported is updated in place rather than failing as a duplicate. This is the path taken in markets where TikTok Shop creates the package — the Philippines, for example.
2. No package, and the market allows buying a label (US and Japan). The connector buys the label, sending the delivery's actual weight rather than an empty request. Box dimensions are still not sent: Odoo records a product volume, not box measurements, and a guessed size would misprice a label.
3. No package, and the market does not allow buying a label. The wizard names the next step — arrange the shipment in Seller Center, then run Sync Packages — instead of surfacing a provider error code.

The documented TikTok fulfillment failures — invalid parameters, already shipped, no service available, order no longer shippable, multiple packages, feature not offered in this country or region — each carry a plain-language next step instead of "Please retry.", which was wrong advice for a request that would be rejected again. TikTok's own reason is written to the Odoo server log (bounded, no customer data) so support can read it without quoting a request id back to TikTok. Messages shown to you never repeat provider text.

Dashboard, orders and record filters (Odoo 19)

• Dashboard shop selector. A database with more than one TikTok shop can choose which one the dashboard shows. The KPIs, deltas, both charts, the top-product list, the activity feed and the chart drill-downs all follow the selection, and Sync Now synchronizes the shop on screen. The selector lists only shops the user may read, and remembers the choice. A single-shop database is unchanged.
• TikTok's auto-cancel date on the order. Order sync stores the date TikTok will cancel the order itself if the outstanding action is still missing — the same date Seller Center shows. It is an optional sortable column next to SLA Due, sits with the other deadlines on the order's Financial & Shipping page, and comes with Auto-Cancels Today and Auto-Cancel Date Set filters and a group-by. TikTok stops returning the stamp once no action is pending, so a settled order shows none rather than a guessed date.
• Separating marketplace records from the rest of the business. Importing an order necessarily creates the buyer and the products it references. The standard Contacts and Products screens carry TikTok Customers / TikTok Products and Exclude TikTok Customers / Exclude TikTok Products filters, a searchable TikTok Shop field, and a group-by shop. Saving an exclude filter as a default favourite makes the split permanent for that user. Nothing is hidden by default and no record is modified.

Packaging (Odoo 19)

The build carries no ECOSIRE licensing dependency and no unlock check; entitlement is governed by the OPL-1 terms it ships under. The translation template (i18n/tiktok_store_management.pot, ~1,700 terms) is shipped again, so the module can be translated.

If you installed 19.0.2.11.0

That build was assembled from an incomplete source snapshot and shipped without work earlier releases had already delivered — affiliate groups, per-SKU affiliate lines, the Packages record and screens, the Arrange Shipment and Shipping Document wizards, the freebie de-duplication migration, and twelve regression suites. Upgrading to 19.0.2.15.0 is a normal Apps upgrade and restores all of it, replaying the skipped migration first so the upgrade completes even on a database that accumulated duplicate freebie lines.

Where Odoo 17 and 18 stand

The Odoo 17 and 18 builds are on 2.12.6. They carry the per-shop order and affiliate sync cadence and the bounded affiliate recovery described above, and the same OPL-1 packaging with no unlock step.

Package submission and Arrange Shipment are Odoo 19 only, and so are the three items introduced in 2.12.7 and later — the package-first shipment flow, the Sync Packages fix, and the faster background order synchronization. If you need those, run the Odoo 19 build.

First production verification

1. Run a small product or order synchronization and inspect the sync log.
2. Verify imported order dates and company currency.
3. If historical orders are required, set the one-off backfill range, run Sync Orders, confirm the oldest order date, then clear the range.
4. On Odoo 19, confirm the shop's Sync Frequency and the Automation switches match the cadence you intend, then check after one interval that a scheduled run has recorded a success.
5. Run only the Finance, Analytics, Returns, Promotions, Affiliate Seller, and FBT actions for which the Partner Center app has approved access.

Support

• TikTok Shop workflow guide
• General troubleshooting
• Support portal
• Email: [email protected]