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.20.6 — $599 USD, OPL-1 (tagged for release; last build confirmed on the Apps Store: 17.0.2.14.0)
Odoo 18	18.0.2.20.5 — $599 USD, OPL-1 (tagged for release; last build confirmed on the Apps Store: 18.0.2.14.0)
Odoo 19	19.0.2.21.9 — $599 USD, OPL-1 (tagged for release; last build confirmed on the Apps Store: 19.0.2.17.1)
Odoo 20	20.0.2.21.9 — $599 USD, OPL-1 (tagged for release)
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 scheduled synchronizations onto the shop's own intervals, 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

This section was rewritten on 17 September 2026 from a fresh installation and from TikTok Shop's own Partner Center documentation as it read on that date, and checked against the current App Store build (19.0.2.17.1) on 18 September 2026. It has two halves: what you do in TikTok Shop Partner Center, then what you do in Odoo. Do the halves in that order — Odoo needs the App Key, App Secret and Service ID that Partner Center issues.

You need 19.0.2.17.1 or later for the authorization buttons

The connector has carried the complete TikTok Shop authorization flow for a long time — but until 19.0.2.17.1 no screen showed a button to start it, so a shop could not be connected from Odoo without help. 19.0.2.17.1 and later add Authorize with TikTok, Refresh Shop Info and Refresh Token to the configuration form.

19.0.2.17.1 is the build on the Odoo App Store and the ECOSIRE dashboard, so the buttons are in the download you get today. If your Configuration form has no Authorize with TikTok button, you are running an older build: download the current one and upgrade the app (see Upgrade an existing database). If the button is still missing after the upgrade, write to info@ecosire.com and support connects the shop for you at no charge.

Half A — TikTok Shop Partner Center

TikTok Shop's developer console is Partner Center: https://partner.tiktokshop.com for every market except the United States, https://partner.us.tiktokshop.com for US shops. Everything below was checked against Partner Center's Get started overview, Create your App, Authorization overview and Seller authorization guide pages on 17 September 2026.

A1. Register as a seller developer. Sign in to Partner Center with the account that owns the shop and complete developer onboarding. A seller integrating its own shop is a TikTok Shop seller developer and builds a Custom app — it is distributed privately by an authorization link, sees only your own shop's data, and normally needs no public-app review.

A2. Create the app. In Partner Center open App & Service in the navigation panel and click Create app & service, then:

1. App type — choose Custom.

2. Service category — the connector belongs in the Connector category (it syncs products, orders, inventory and fulfilment with an external system). TikTok may ask for an app review for Connector-category apps even when they are private; allow for that in your timeline.

3. Default name and, optionally, a logo.

4. Market and Seller type — set these carefully: Partner Center treats them as creation-time choices that may not be editable afterwards. Pick the market your shop sells in (for example Thailand) and Local unless you are a cross-border seller.

5. Turn on Enable API.

6. Redirect URL — enter your Odoo instance's callback, exactly:

   https://<your-odoo-host>/tiktok/callback

   <your-odoo-host> is the public address your users open Odoo at (the value of web.base.url). TikTok sends the one-time authorization code to this address, and the connector will not accept it anywhere else.

7. Webhook URL (optional, recommended) — https://<your-odoo-host>/tiktok/webhook.

8. Click Create.

A3. Enable the API scopes. On the app's detail page enable the scopes the connector uses — at least the seller shop, product, order, fulfillment, logistics, finance and return/refund scopes. Enable the affiliate scopes only if you will use Affiliate Orders and Commissions (TikTok error 105005 later means that scope was never approved). If you add a scope after the shop has authorized the app, the shop must authorize again before the new data is reachable.

A4. Read the credentials. Partner Center → App & Service → your app → App credentials / Basic information shows three values the Odoo form asks for:

Partner Center label	Odoo field	Notes
App Key	App Key	Public identifier of the app
App Secret	App Secret	Keep it on the server; never paste it into a support thread
Service ID	Service ID	The identifier of the registered service — this is what the authorization link is built from

A5. Approval wait. A custom app for your own shop can usually be published and authorized straight away. Connector-category apps and apps reaching 25 or more seller authorizations go through TikTok's app review; Partner Center shows a review banner or a Submission materials for review entry when that applies. US and UK apps may additionally need a compliance and legal review, which TikTok says can take three or more weeks.

A6. The shop identity is read for you. You do not have to look up the Shop ID or Shop Cipher anywhere. When the shop authorizes the app (Half B, step 5), TikTok redirects back to Odoo with the authorization code; the connector exchanges it for the access and refresh tokens at TikTok's token endpoint and then calls Get Authorized Shops to fill Shop ID, Shop Cipher and Shop Name itself. Tokens last seven days and the connector renews them every six hours; the authorization itself lasts as long as the period the seller grants on TikTok's consent screen.

Half B — Odoo (19.0.2.14.0 and later)

Sign in as a user who is a TikTok Shop Manager (Settings → Users → the user → TikTok Shop access field). Managers see the Configuration and Operations menus; plain users do not.

B1. Open the configuration list. From the Odoo apps menu open TikTok Shop, then Configuration → Settings. Click New. One record is one TikTok shop; create one per shop.

B2. Fill the Connection group. The form has a title field and a Connection group on the left. Fill:

Field	Value
Configuration Name	Any name, e.g. the shop's trading name
App Key	From Partner Center (A4)
App Secret	From Partner Center (A4) — shown only to Odoo administrators
Service ID	From Partner Center (A4)
Region	The market the shop sells in — Thailand, Malaysia, Singapore, Vietnam, Philippines, Indonesia, United States, United Kingdom, Mexico, Brazil, MENA (KSA/UAE) or Global. This selects the API host; leave it on Global only if your market is not listed
Company (in the Status group on the right)	The Odoo company that owns this shop's orders and stock
Timeout (seconds)	Leave at 30

Leave Access Token, Refresh Token, Shop ID, Shop Cipher, Shop Name and Is Authorized empty — they are filled by the authorization step. Authorization URL is a read-only field that shows the one-time link only while an authorization is in progress. Category Tree Version, Default Category ID, Enable Live Shopping, Enable Affiliate and Default Commission Rate can stay at their defaults for now.

B3. Save. Click the cloud icon (or press Ctrl+S).

B4. Authorize the shop. Click Authorize with TikTok in the form header (19.0.2.17.1 and later — see the note at the top of this section). A new browser tab opens on TikTok's authorization page (services.tiktokshop.com/open/authorize?service_id=…). Sign in with the seller account that owns the shop, choose the region, review the requested scopes, pick the authorization period and click Approve. TikTok then redirects to https://<your-odoo-host>/tiktok/callback and Odoo shows Authorization complete — your shop is connected. Close that tab and reload the configuration: Is Authorized is on, Shop ID, Shop Cipher and Shop Name are filled, and the header now shows Re-authorize, Refresh Shop Info and Refresh Token instead of Authorize with TikTok.

If the callback page says Invalid, expired, or already-used authorization state, more than ten minutes passed between clicking the button and approving, or the button was clicked twice — click Authorize with TikTok again and complete the approval within ten minutes.

B5. Test Connection. Click Test Connection in the form header. The connector calls TikTok's Get Authorized Shops with the stored token; on success Connection Status in the Status group turns to Connected and Last Connection Test is stamped. On failure the status turns to Error and Connection Error Message shows TikTok's reply. (The same test is also available as a stand-alone wizard under Operations → Test Connection, where you can try a set of credentials without saving them on a record.)

B6. Choose what synchronizes — the Synchronization tab.

• Data Types — Sync Products, Sync Orders, Sync Customers, Sync Inventory, Sync Fulfillment, Sync Finance. These decide which areas the connector is allowed to touch at all; all are on by default.
• Automation — Auto Sync Products, Auto Sync Orders, Auto Sync Customers, Auto Sync Affiliate (and Auto Sync Inventory in the Connection group). These are off by default: nothing runs on a schedule until you switch a lane on, and the tab says so until you either sync once or enable a schedule.
• Numeric Sync Intervals — one interval per lane (Products, Orders, Customers, Inventory, Finance, Affiliate, Official LIVE), each with its unit.
• Order Sync Window — Order Sync Window (days) (default 7) is how far back each order run looks; an explicit Date From / Date To replaces the window for a one-off backfill.
• Seller Shipping Push — the handover method and carrier TikTok is told when Odoo pushes a shipment (Drop off by default).

B7. First synchronization. Press Fetch Categories first, so imported products land in TikTok's category tree, then Sync Products and Sync Orders in the header. Sync Orders runs in the background: the button is replaced by a status while the run is in flight. Imported products appear under Catalog → Products, orders under Orders → Orders; each imported order is an Odoo sale order tagged with its TikTok order id and is never duplicated on re-runs.

B8. Where errors show. Three places, from quick to detailed: the Connection Status / Connection Error Message fields on the configuration; Operations → Logs, one line per run with the record counts and the provider message; and the Statistics tab of the configuration (last sync time per lane, totals).

The scheduled actions and what they do

Settings → Technical → Scheduled Actions (developer mode) lists the jobs the build installs. A job only does work for configurations that are active, authorized and have the matching automation switch on.

Scheduled action	Runs every	On by default	What it does
tiktok: Sync Products	5 minutes	Yes	Imports listings for shops with Auto Sync Products, honouring each shop's product interval
tiktok: Sync Orders	5 minutes	Yes	Imports orders over the order window for shops with Auto Sync Orders
tiktok: Run Queued Order Syncs	30 minutes	Yes	Drains order runs that were queued from the button
tiktok: Sync Customers	5 minutes	Yes	Buyer records from order detail for shops with Auto Sync Customers
tiktok: Sync Inventory	5 minutes	Yes	Pushes Odoo stock to TikTok SKUs for shops with Auto Sync Inventory
tiktok: Refresh Access Tokens	6 hours	Yes	Renews every authorized shop's token before its seven-day expiry
tiktok: Test Connection	1 day	Yes	Re-checks every configuration and updates its status
tiktok: Cleanup Old Logs	1 day	Yes	Trims the module's own log records
tiktok: Sync Settlement Statements	5 minutes	Yes	Settlement statements and transactions for shops with Sync Finance on
tiktok: Sync Affiliate Orders	5 minutes	Yes	Affiliate orders and commissions for shops with Auto Sync Affiliate
tiktok: Sync Official LIVE Sessions	5 minutes	No	Official LIVE sessions; enable on the configuration's Official LIVE Sessions panel
tiktok: Apply Freebie Rules	5 minutes	Yes	Re-applies freebie rules to recently synced orders, honouring each shop's freebie re-check interval (1 hour by default)

The five-minute jobs are cheap when nothing is due: each shop's own interval decides whether a run actually calls TikTok.

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 (inventory and Official LIVE sessions have their own switches elsewhere on the form). The per-lane intervals on the same configuration decide how often each scheduled run happens 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.

Dispatch records the verified event in the webhook log (personal data redacted) and does not itself change an order, return or product in Odoo; those changes arrive with the next scheduled or manual synchronization.

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

The 2.21 fixes in every download (19.0.2.21.9, 20.0.2.21.9)

Odoo 19 and 20. The fixes released as 2.21.0 to 2.21.8 are now in the build every buyer downloads. Upgrade the module; nothing needs configuring.

• Official LIVE orders qualify the same day. An Official LIVE sync records how far it saw a running session, so gift rules for the shop's own LIVE window apply while the live is still running. Evidence is recorded only from a complete sync, and session totals are counted by distinct sessions.
• TikTok Total is what the buyer paid, read from TikTok's total_amount, with the payment-method Handling Fee shown in its own field.
• Order lines carry the seller's revenue: TikTok's original price with the seller-funded discount as the line discount.
• Settlements clear the order's invoice instead of booking the revenue a second time; seller fees are booked as an expense. A shop that does not invoice TikTok orders can choose TikTok settlements as its revenue basis.
• Sync warnings are kept apart from sync errors, with stable warning codes. A differently masked read of the same recipient is not an address change.
• Overlapping scheduled syncs of one shop take turns instead of failing each other with a write conflict.

Sync Inventory on the product form sends the shop's quantity (19.0.2.21.9, 20.0.2.21.9, 18.0.2.20.5, 17.0.2.20.6)

All four versions. The Sync Inventory button on a product sent the company-wide on-hand quantity. It now sends exactly what the scheduled stock push sends: the shop's warehouse, its Inventory Owner and its Stock Push Ratio apply. A malformed App Secret (with a space or line break, or still the placeholder from the documentation) is refused when you save the shop.

TikTok Total on Odoo 18 and 17 (18.0.2.20.5, 17.0.2.20.6)

TikTok Total is now read from the buyer-paid total_amount, so order-total gift rules use what the buyer paid. Existing orders correct on their next refresh; use Apply Freebie Rules on an order to re-apply its gifts.

The dashboard opens on Odoo 17 again (17.0.2.20.5)

Odoo 17 only. The TikTok Shop dashboard loaded a component that exists in Odoo 18 and 19 but not in Odoo 17, so on Odoo 17 the dashboard did not open. It now uses Odoo 17's own way of reading the current user, and the dashboard, its charts and its shop selector open as expected. Nothing changes on Odoo 18 or 19, and there is nothing to configure: upgrading is enough.

Delivery addresses compared correctly on every refresh (19.0.2.20.4)

Five corrections to how an order refresh decides whether its delivery address changed. None of them needs any configuration.

• An order is flagged "delivery address changed" only when the address really changed. A customer can hold two identical delivery addresses (created by releases before 2.20.0); the connector now compares the address itself and keeps the order on the contact it already uses.
• Addresses TikTok sends as a district list are read the same way when a delivery contact is created and when it is checked, so a refresh no longer creates another copy of the address or flags a confirmed order.
• When the buyer genuinely changes on an order that is not confirmed yet, the order stays on the shop's configured warehouse.
• When the recipient has the buyer's own name, a changed street is still noticed: an unconfirmed order follows the new address, and a confirmed order keeps its delivery contact and records a note to check the address before shipping.
• A short affiliate history import, or an Official LIVE import with a window shorter than the standard 30 days, no longer moves the time the scheduled synchronization starts from, so no days are skipped afterwards.

Clearer failure records for support (19.0.2.20.3)

When a scheduled synchronization fails for a shop, or two scheduled runs collide on the same shop, the server log now names the shop together with its record id. When the stock update for one product fails, the log names the shop, the Odoo product, its TikTok product id and its SKU. If you send us a log excerpt, we can find the exact record without re-running the synchronization. What you see in the synchronization log is unchanged, and no synchronization behaves differently.

The release also stops shipping four images the store page never displayed. Nothing visible changes. Upgrading is enough; there is nothing to configure.

Cancellation reasons, amount changes and the Inventory Owner (19.0.2.20.2)

• A cancellation needs a reason. TikTok requires a reason on every cancellation. Asking to cancel without one (or with a blank one) is now refused before anything is sent, with the reasons you can use: Out of stock, Pricing error and Seller unable to fulfil order.
• The two buyer-related reasons keep working until 31 October 2026. 19.0.2.20.1 refused Buyer requested cancellation and Unable to deliver to buyer address five weeks before TikTok retires them. From 19.0.2.20.2 they are sent to TikTok as before until 31 October 2026, with a log warning that names Seller unable to fulfil order as their replacement. From 31 October 2026 they are refused before the request, with the reasons that remain.
• Re-reading an order keeps small amount changes. When an order is refreshed, each amount is compared with the stored one using the field's own precision, and money amounts with the order currency's own number of decimals. A change in the third decimal of a three-decimal currency (for example BHD, KWD or OMR) is kept, and an unchanged amount is left alone.
• The Inventory Owner must belong to the shop's company. On a database with several companies, a contact of another company could be chosen as a shop's Inventory Owner, and every order from that shop then failed at confirmation. The field now offers only contacts of the shop's company (or contacts shared by all companies), and saving another company's contact is refused with a message naming the shop, the contact and both companies.

The delivery address survives a re-sync (19.0.2.20.0)

Re-reading an order from TikTok Shop — from the order form, the scheduled order synchronization, or a bulk import — used to re-state the buyer on the order even when the buyer had not changed. Odoo treats a field as changed because it was written, not because its value moved, so that re-statement made Odoo work the delivery address out again from scratch: it took the buyer's first delivery address rather than the one the order was placed with. The delivery note that already existed kept the original address, so the order and its delivery no longer agreed — and a free gift added afterwards could not be put on that delivery, so a second, gift-only delivery was raised for the same order. The invoice address, price list, fiscal position, payment terms, salesperson and warehouse were all being re-derived by the same write.

From 19.0.2.20.0 the connector writes only what has genuinely changed, so an order that has not changed is left exactly as it is.

When the buyer or the delivery address really does change:

• on an order that has not been confirmed, the delivery address is resolved from the payload and the order follows it;
• on an order whose delivery already exists, the delivery and invoice contacts are kept as they are and a plain-language note is written to the order's synchronization message, so nobody ships to a changed address without seeing it first. The existing delivery note is never rewritten.

A repeat buyer no longer collects a new delivery address per order either: an existing delivery address is reused when it matches, and a new one is created only when the address is genuinely different.

Orders that were already split

Upgrading stops the cause; it does not merge deliveries that were already raised separately, because that is a decision about physical goods. Where nothing has shipped, cancel the gift-only delivery and add its line to the original one. Where something has shipped, leave both as they are.

Checking a Fulfilled by TikTok order, and two cancellation reasons (19.0.2.20.1)

Checking the status of a Fulfilled by TikTok (FBT) order sent the order identifier under a parameter name TikTok does not publish, so TikTok never received the identifier it requires and the check could not succeed. The published name is now used. No other TikTok operation was affected — every operation this connector calls was re-checked against TikTok's current documentation on 23 September 2026 and confirmed current.

TikTok also withdraws two order-cancellation reasons on 31 October 2026, on every market: Buyer requested cancellation and Unable to deliver to buyer address. 19.0.2.20.1 refused both straight away; from 19.0.2.20.2 they keep working until that date (see above) and are refused only from 31 October 2026, with a message naming the reasons that remain — Out of stock, Pricing error, and Seller unable to fulfil order. A cancellation is never re-filed under a different reason on your behalf.

Upgrading is enough; there is nothing to configure.

One package for every installation (19.0.2.20.0)

Until this release the connector was maintained on two branches that both released under 2.18.x numbers, so a fix made for one installation did not reach the other. Everything from both is in 19.0.2.20.0: per-shop stock ownership and the stock push ratio, the bind-only product mode, product images and the dashboard on Odoo 19 and saas~19.x, the API route check, Official LIVE session imports, and the retry when two scheduled synchronizations collide. Upgrade from any earlier build of either branch.

The upgrade explicitly keeps the settings an existing shop already had rather than letting them fall to a new default: a shop keeps sending its full stock quantity (a push ratio of 1.00, not the 0.80 a new shop starts at) and keeps letting TikTok update existing products. Shops created after the upgrade start at the new defaults.

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.14.0 and carry a subset — see Where Odoo 17 and 18 stand. Full behaviour is documented in the TikTok Shop workflow guide.

Which of these you already have

The build on the Odoo App Store and the ECOSIRE dashboard is 19.0.2.17.1, checked 18 September 2026. Everything in this section is in that build — including the items marked 19.0.2.15.0 below (the shipping and package changes) and the authorization buttons added in 19.0.2.17.1. If you are running an older build, upgrade to pick them up.

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

Every scheduled lane has its own interval on the shop's Synchronization tab — a number plus minutes or hours, five minutes at the shortest (from 19.0.2.14.0; on Odoo 18 and 17 from the 2.20.x builds). The scheduled actions wake every five minutes and run only the shops that are due, measured against each shop's own last successful sync, so a failed run is retried on the next wake-up instead of waiting out a whole interval.

Lane	Default interval for a new shop
Products	1 hour
Orders	1 hour
Customers	6 hours
Inventory	15 minutes
Settlement statements	6 hours
Affiliate orders	1 hour
Official LIVE sessions	6 hours (the job ships switched off)
Freebie re-check	1 hour

What Settings → Technical → Scheduled Actions shows is the five-minute wake-up at which Odoo checks which shops are due — not the shop's interval.

History. Before 19.0.2.12.0 the shop's Sync Frequency was displayed but governed nothing: orders ran on a fixed 30-minute cycle and affiliate on a fixed 6-hour cycle. 19.0.2.12.0 made Sync Frequency govern the order and affiliate lanes; 19.0.2.14.0 replaced it with the per-lane intervals above and converts an existing shop's order and affiliate frequency to the exact equivalent interval on upgrade. Which shops sync at all is still decided by the Auto Sync opt-ins; a shop that opted out is skipped.

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, about 2,100 terms) is shipped again, so the module can be translated. No translated language files ship today; the interface is in English.

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 2.20.x builds — 18.0.2.20.5 and 17.0.2.20.6 — merge the Odoo 19 work into the Odoo 18 and 17 packages: package submission and Arrange Shipment, the package-first shipment flow, the Sync Packages fix, the faster background order synchronization and the per-lane intervals are all in them, with the same OPL-1 packaging and no unlock step. The settlement accounting, Official LIVE and sync-warning changes of the 2.21 builds are Odoo 19 and 20 only.

The earlier 2.14.0 builds for Odoo 18 and 17 carry only the per-shop order and affiliate cadence and the bounded affiliate recovery; if you run one of those, upgrade to the 2.20.x build for your version.

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. Confirm the shop's per-lane intervals 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: info@ecosire.com