TikTok Shop Store Management

ECOSIRE TikTok Shop Store Management connects an approved TikTok Shop seller account to Odoo. Its supported API boundary is explicit: it does not claim the complete TikTok Shop Open API or provider LIVE viewer and engagement metrics.

Compatibility: Odoo 17, 18, and 19, Community or Enterprise

Current release: 19.0.2.15.0 (Odoo 17/18: 17.0.2.12.6 / 18.0.2.12.6). Fulfilment priority/SLA tracking, the Packages screen, shipment push, Arrange Shipment, the shipping-document window, the auto-cancel date, the dashboard shop selector, the faster background order synchronization, the per-synchronization intervals and the incremental package synchronization described below ship on Odoo 19 only. The per-shop cadence and the bounded affiliate recovery are on all three.

Licensing: all three builds ship under OPL-1. No key is entered anywhere and there is no unlock step — install the ZIP and the connector works. Builds older than 2.11.0 bundled a separate ECOSIRE licensing add-on; that dependency and every execution-blocking check have been removed. See the installation guide.

Implemented scope

• Seller connection and shop-scoped configuration
• Product and inventory synchronization for the supported seller boundary
• Order import with buyer records derived from order detail
• Rolling order synchronization plus a one-off historical backfill range
• Incremental order synchronization that skips orders TikTok reports as unchanged, with a daily full re-read as a safety net (Odoo 19)
• Background Sync Orders that returns immediately and notifies on completion (Odoo 19)
• Original TikTok order-date preservation and safe reprocessing
• Read-only return and refund mirror
• Settlement statements and order-level transaction detail
• Shop, product, and video analytics snapshots where TikTok returns them
• Read-only promotion activity import
• Affiliate Seller order import when the Partner Center app has the required Affiliate API permission
• Fulfilled by TikTok inventory, inbound planning, and Odoo picking linkage
• Shipment push to TikTok Shop over the official Ship Package flow, with tracking write-back (Odoo 19)
• Package synchronization from TikTok's package search (Odoo 19)
• Fulfilment priority and SLA deadline tracking on orders and packages, with overdue alerts (Odoo 19)
• TikTok's auto-cancel date tracked on orders, with filters and group-by (Odoo 19)
• Per-shop synchronization cadence that governs the scheduled order and affiliate runs
• Scheduled/manual synchronization and replay-safe webhook intake for events configured in TikTok Partner Center
• Multi-company record isolation, role-based access, sync logs, retry states, and masked credential fields

Provider webhook-subscription CRUD (creating, editing, or deleting webhook subscriptions in Partner Center) is not included in this release. Buyer records are derived from orders; there is no separate TikTok customer-directory endpoint in the supported contract.

Prerequisites

• Your ECOSIRE purchase for this module and your Odoo version
• A TikTok Shop seller account
• A TikTok Shop Partner Center application approved for the operations you intend to use
• App key, app secret, access token, refresh token, and shop identity for that application

The permissions available to a connected shop are controlled by TikTok. For example, Affiliate Seller synchronization requires TikTok's approved Affiliate API read scope; a normal seller connection does not grant it automatically.

Installation

1. Download the matching Odoo version from your ECOSIRE Dashboard.
2. Extract the module into an Odoo addons directory.
3. Restart Odoo and update the Apps list.
4. Search for TikTok Shop Store Management and install it.

There is no second ECOSIRE archive to install first, and nothing to unlock afterwards.

After updating an existing installation, run an Apps upgrade for the module so the database schema, views, data, and migrations match the installed source.

Connect a shop

1. In TikTok Shop Partner Center, create or select the application used by the seller.
2. Request the read/write scopes required for the workflows you will enable.
3. Complete TikTok's OAuth authorization for the seller shop.
4. In Odoo, open TikTok Shop → Configuration and create or edit the shop.
5. Enter the shop identity and credentials, assign the Odoo company and currency context, then use Test Connection.
6. Enable only the synchronization areas approved for that TikTok application.

Credentials are sensitive. Store them only in the protected configuration fields and do not paste them into support tickets or screenshots.

Synchronization behavior

How often a shop synchronizes

Each shop's Sync Frequency (Every 15 minutes … Daily) decides how often its scheduled order and affiliate synchronization runs. The two schedules tick every 15 minutes and measure each shop against its own cadence and its own last successful run, so shops on different cadences share one schedule and a failed run is retried on the next tick rather than waiting out a whole interval.

Sync Frequency governs those two lanes only. Every other lane keeps its own fixed cycle and does 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 the order and affiliate jobs 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. That is why the numbers on the Scheduled Actions screen do not match the shop's setting.

Whether a shop syncs on a schedule at all is decided by the Auto Sync switches in the Automation panel — orders, products, customers and affiliate each have their own. A shop that is authorized with every switch off will not fetch anything until somebody presses Sync, and its Synchronization tab says so until you sync once or enable a schedule.

Upgrading a live Odoo 19 shop

Before 19.0.2.12.0 Sync Frequency was displayed but governed nothing: orders ran every 30 minutes and affiliate every 6 hours regardless of the setting. After the upgrade the shop follows what its setting says — Every hour for a shop that never changed it. The upgrade does not rewrite stored values, so a shop that wants 30-minute orders should select Every 30 minutes, which now works. Which shops sync at all is unchanged.

What each sync toggle controls

Products, Orders, and Customers each have their own toggle on the shop configuration. Sync All and the dashboard's Sync button run only the types enabled for that shop; a disabled type is skipped, not run with defaults.

Order import is the one exception: importing or updating a TikTok order always creates or matches the specific customer and the specific products that order references, whether or not the Products or Customers toggles are enabled. Odoo cannot save a sale order without a real customer and real order lines, so the order sync resolves both on the spot — the Products and Customers toggles control the dedicated catalog and buyer-directory synchronizations, not whether an order can import.

If you disable Products or Customers sync to avoid catalog drift and later find records you no longer want kept in sync, archive them rather than deleting them — Odoo blocks deleting a product or contact that a confirmed sales order still references, and archiving keeps the order history intact while removing the record from active lists and future matching.

Products and inventory

Use the configuration actions or scheduled jobs to import the supported product catalog and synchronize inventory within the configured shop boundary. Review the sync log for created, updated, skipped, and failed counts.

Orders and historical backfill

Normal order synchronization uses a rolling seven-day window. For older data, set Backfill From and, if needed, Backfill To on the configuration and run Sync Orders. The module requests the range in TikTok-compatible slices, upserts existing orders, and preserves the provider's original order date.

Backfill settings are one-off operator controls. Clear them after the historical run so normal scheduled synchronization returns to the rolling window.

Shipping documents and package status (Odoo 19, 19.0.2.15.0)

A package you have shipped stays shipped. TikTok keeps reporting a package as "processing" for a while after accepting your shipment. That status used to be copied straight onto the package, putting it back into the not-yet-shipped state and offering the Ship button again on a package already on its way. A package now only moves forward — created, then shipped, then delivered, with cancellation available until delivery — and both places that can ship a package refuse to send a second handover for one that is already shipped or already carries a tracking number.

Shipping documents match what TikTok issues. TikTok produces a label or packing slip only after it has accepted the shipment, so asking earlier is now refused with the actual next step instead of an unexplained provider error. The paper sizes offered are A6 and A5, which are the only two TikTok issues; A4 and 4x6 were offered before and were always rejected. The window now also offers the PNG picture label, the hazmat label, the Brazilian invoice label and ZPL output for the Brazil and Mexico markets, and hides the size or format where TikTok fixes or ignores it. Printing a label also records the tracking number TikTok returns with it.

Package synchronization is incremental. After the first run it asks TikTok only for packages changed since the last one, and re-reads the full history once a day. Packages can also keep themselves current on a schedule now — switch on Auto Sync Packages on the shop; it is off by default.

An interval for every synchronization (Odoo 19, 19.0.2.14.0)

Products, orders, customers, inventory, finance, affiliate orders, official LIVE sessions and packages each have their own numeric interval and minutes-or-hours unit on the shop. The shortest accepted is five minutes.

The scheduler 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. Upgrading migrates your existing order and affiliate frequencies to their exact equivalents and preserves every other lane's schedule, so no shop starts synchronizing more often.

Stock updates and product export (Odoo 19, 19.0.2.13.0, 19.0.2.13.1)

Inventory updates were being sent to an address TikTok does not serve, so no stock change ever arrived and shops kept selling from stale quantities. They now reach TikTok and identify each item by the code TikTok issues, not the Odoo internal reference. A product TikTok has not yet given a code for is reported as skipped by name with the step to fix it, and the log records why a product failed.

Exporting a product now uploads its images to TikTok first — TikTok requires at least one image and refuses any address it does not host itself — and sends real category attributes and rules.

Official LIVE sessions and freebies (Odoo 19, 19.0.2.12.11)

Official LIVE synchronization was importing affiliate creators' lives alongside your own account, which then fed the "Official Live Window" freebie condition. The filter now rides every page, and previously imported sessions TikTok does not confirm are re-tagged rather than deleted. Freebie re-evaluation now reconciles instead of only adding, so late attribution or a changed order total can no longer accumulate several freebies on one order; delivered or invoiced lines are kept and flagged, and manual lines are never touched.

Faster order synchronization (Odoo 19, 19.0.2.12.10)

A manual Sync Orders could take around thirty minutes on a busy shop, and the scheduled run repeated that work every time. Every order in the window was downloaded again and rewritten in full whether or not anything had changed, one request per order. Three corrections:

• Orders are downloaded fifty at a time rather than one at a time, so a week of orders costs a handful of requests instead of several hundred.
• The connector records when TikTok last changed each order and skips orders that have not moved since the previous run.
• 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 a late timestamp cannot hide an order. The run summary reports how many orders were unchanged, counted as a success rather than as skipped or failed work, so a fast run is legible.

The first run after upgrading behaves like the old one, because there is nothing recorded yet to compare against. From the second run onwards a typical synchronization finishes in a fraction of the time.

Sync Orders runs in the background (Odoo 19, 19.0.2.12.10)

Sync Orders used to hold the browser for the whole run, which on a large catch-up looked like a frozen page and, on hosted Odoo, could be cut off by the server's request time limit and lose the run.

The button 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 pressing the button again while a run is in flight does not start a second one. The queued run is picked up immediately; a scheduled runner re-checks every 30 minutes so a queued run cannot be stranded.

Packages

Sync Packages imports the shop's TikTok packages and keeps their status, handover type, provider/service and tracking number current.

From 19.0.2.12.9 package synchronization works again. Every attempt had been refused by TikTok with error 36009004 before it reached the shop — on all attempts, on every shop, and it continued after 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, page marker and sort order are now sent where TikTok documents them, and the message body carries only the date and status filters. Order and shipping synchronization were never affected, which is why only package synchronization failed.

Packages are read oldest-first by creation date while paging. Sorting by last-updated could move a package behind the point already read — and skip it — if it was packed or shipped during the run.

Returns

Sync Returns imports TikTok return/refund cases into a read-only Odoo mirror. It does not approve, reject, or mutate a return on TikTok Shop.

Finance

Sync Finance imports settlement statements and their order-level transactions, including revenue, fees, adjustments, shipping, refunds, discounts, rewards, and net settlement where supplied by TikTok. Provider statuses such as SETTLED are rendered as operator-friendly Odoo values.

Analytics

Sync Analytics stores dated provider snapshots for the supported shop, product, and video responses. These are not real-time telemetry. Unsupported or unavailable LIVE viewers, likes, comments, shares, followers, conversion, and LIVE GMV remain explicitly unavailable.

Promotions and Affiliate Seller

Promotion and Affiliate Seller synchronization are read-only imports. If Affiliate sync returns TikTok code 105005 or a permission error, request and approve the Affiliate API read scope in Partner Center, reconnect the shop, and retry. This is a permission issue on the TikTok application, not an Odoo problem.

Sync Affiliate is incremental. It resumes from the last successful run with a two-day overlap for late-arriving rows, instead of replaying the whole configured history every time it runs. For a deliberate full repair — a shop that was disconnected, or a window you know is incomplete — use Backfill Affiliate History, which walks the full configured range once.

Auto Sync Affiliate Orders sits in the Automation panel with the other three lanes. It is off by default while Enable Affiliate Program is on by default, so a shop can look affiliate-enabled everywhere and still never refresh creator attribution on its own; the shop now shows a note naming that switch until it is on, and a scheduled run that covered no shop records the affiliate shops it skipped in the log rather than finishing silently.

Affiliate paging is bounded and self-correcting. The connector treats TikTok's reported total as the terminal condition, rejects repeated cursors, and stops after a defensive page ceiling, so a malformed trailing cursor cannot hold an Odoo worker. When TikTok reports more rows than its cursor actually returns, the run retries bounded half-open sub-windows — down to one-second slices, and via TikTok's documented single-row cursor where a slice still closes early — then de-duplicates by affiliate id so counters are not inflated. From 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 still cannot be reconciled it fails closed and leaves the last-success cursor untouched, so the next run retries the same window rather than skipping it.

Fulfilment priority and SLA deadlines (Odoo 19, new in 19.0.2.10.19)

Order sync persists the fulfilment-urgency fields TikTok already returns in the order payload:

TikTok field	Shown in Odoo as	Meaning
fulfillment_priority_level	Fulfilment Priority	Platform-assigned urgency ranking, shown exactly as TikTok returns it. Served to Southeast Asia shops only — empty for other regions. TikTok defines the ranking; sort the column to group values rather than assuming a direction.
rts_sla_time	Ship By (TikTok SLA)	Latest time TikTok allows the order to ship.
tts_sla_time	Collect By (TikTok SLA)	Latest collection time TikTok specifies.
delivery_sla_time	Deliver By (TikTok SLA)	Time the order should arrive to count as on-time.

SLA Due is the earliest of the deadlines still recorded on the order — the next deadline to work to. SLA Overdue becomes true once that deadline has passed and the order has not yet reached a settled status (delivered, completed, or cancelled); a settled order is never flagged, even past its original deadline.

On the Orders list, Fulfilment Priority and SLA Due are sortable, optional columns, an order past its deadline is highlighted in the row, and SLA Overdue and SLA Due Today filters plus group-by (Fulfilment Priority, SLA Due) are available. The full deadline set — Ship By, Collect By, and Deliver By — is on the order's Financial & Shipping tab.

TikTok's package payloads carry neither field, so the Packages list mirrors each package's priority and SLA Due from its order, with the same overdue row highlighting, an SLA Overdue filter, and group-by on Fulfilment Priority and SLA Due.

TikTok omits the SLA stamps once no seller action is pending on an order, so these fields stay empty rather than showing a guessed value. Priority and SLA values are picked up on an order's next sync — running Sync Orders populates them for orders that were imported before this release.

FBT, fulfillment, and shipment push

The release supports FBT inventory and inbound planning with Odoo picking linkage, plus imported fulfillment status and local shipping-method mappings.

On Odoo 19, shipment push to TikTok is implemented: Sync Fulfillment (shop-level or per order) ships a synced order's package over TikTok's official Ship Package flow — the connector resolves the package, matches the Odoo carrier against the shipping providers TikTok publishes for the shop, and pushes the tracking number. Configure Handover Method and a Fallback Shipping Provider ID on the shop configuration; an order whose Odoo carrier maps to no TikTok-published provider is skipped rather than shipped under a guessed carrier. A Packages screen tracks each TikTok package's status, handover type, provider/service, and tracking number, with per-company access and the same fulfilment-priority/SLA columns described above.

The three Arrange Shipment flows (Odoo 19, 19.0.2.12.7)

Arrange Shipment works in every market from 19.0.2.12.7. TikTok only lets a seller buy a shipping label through the API in the United States and Japan; everywhere else TikTok Shop creates the package itself. The wizard used to open every order by asking for eligible shipping services — the label-buying flow — so outside those two markets it was rejected with TikTok error 21001001 and no shipment could be arranged from Odoo.

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

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

Each documented TikTok fulfillment failure (invalid parameters, already shipped, no service available, order no longer shippable, multiple packages, feature not offered in this country or region) carries 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 and without customer data, so support can diagnose it without quoting a request id back to TikTok.

On Odoo 17 and 18, package submission and Arrange Shipment are not implemented — Sync Fulfillment detects orders that are ready to ship but does not call TikTok.

Webhooks

The module can authenticate and process replay-safe webhook deliveries that TikTok is already configured to send. Creating, updating, or deleting webhook subscriptions in TikTok Partner Center is outside this release.

TikTok's auto-cancel date (Odoo 19)

Order sync stores the date TikTok will cancel the order by itself if the outstanding action is still missing — the same date Seller Center shows, taken as the earliest auto-cancel threshold the order payload carries. It is an optional sortable column on the Orders list 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 plus a group-by.

TikTok stops returning these stamps once no action is pending, so a settled order shows no auto-cancel date rather than a guessed one.

Dashboard and audit trail

The dashboard and list views show Odoo-local operational KPIs, synchronized records, provider snapshot data, explicit unavailable states, and drill-downs to sync logs. Monetary values use the configured company/shop currency context.

On Odoo 19 the dashboard has a shop selector, so a database with more than one TikTok shop can look at either of them. The KPIs, the 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 the shops the user is allowed to read and remembers the choice for the next visit; a single-shop database is unchanged and simply shows the shop's name.

Keeping marketplace records separate (Odoo 19)

Importing an order necessarily creates the buyer and the products it references, so the standard Contacts and Products lists fill with marketplace records. Those screens carry TikTok Customers / TikTok Products and Exclude TikTok Customers / Exclude TikTok Products filters, a searchable TikTok Shop field, and a group-by shop, so the two populations can be split or the marketplace records hidden in the standard screens. 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 — these are the same records the orders are built from. The connector's own Imported Customers and Imported Products screens have the same group-by shop.

Troubleshooting

Issue	Resolution
Connection fails	Verify the Partner Center application, shop authorization, token validity, and network access.
Orders stop at recent history	Set a one-off backfill range, run Sync Orders, verify counts and oldest order dates, then clear the range.
Affiliate sync returns 105005	Obtain the required Affiliate API permission in Partner Center and reconnect the shop.
Creator attribution is stale until somebody presses Sync	Auto Sync Affiliate Orders is off. It is in the Automation panel on the shop configuration.
Sync Packages fails with 36009004	The database is on an Odoo 19 build older than 19.0.2.12.9, which sent the page size in the wrong part of the request. Upgrade. This code means TikTok rejected the shape of the request; when other synchronizations are working, your credentials are not the cause. The exact reason TikTok gave is in the Odoo server log.
A shipping-document request fails with 21042104	The package has not been shipped yet. TikTok issues a label or packing slip only after it has accepted the shipment. Ship the package first — from Arrange Shipment or the Ship button on the package — then fetch the documents. Odoo 19 19.0.2.15.0 and later say this before contacting TikTok.
A shipping-document request fails with 36009004	The requested paper size is not one TikTok issues. It accepts A6 and A5 only; A4 and 4x6 were offered by builds before Odoo 19 19.0.2.15.0 and were always rejected. For a PNG label choose the Shipping Label (PNG picture) document type rather than a PNG format. Note that TikTok reuses this code for unrelated conditions, so it does not always mean the paper size.
A package you shipped shows Created on TikTok again	Builds before Odoo 19 19.0.2.15.0 copied TikTok's lagging "processing" status straight onto the package, which re-armed the Ship button. Upgrade. Do not press Ship a second time — check the Tracking Number field first: if it is filled, TikTok accepted the shipment.
Arrange Shipment fails with 21001001	Odoo 19 19.0.2.12.7 and later handle markets where TikTok creates the package itself. Upgrade the module; if TikTok has created no package yet, arrange the shipment in Seller Center and then run Sync Packages.
Sync Orders takes around half an hour	Upgrade to Odoo 19 19.0.2.12.10, which downloads orders in batches and skips orders TikTok reports as unchanged. The first run after the upgrade is still slow because there is nothing recorded yet to compare against; the runs after it are not. Keep the order window at seven days — a wider window multiplies the work.
Sync Orders returns immediately without a result	That is the Odoo 19 19.0.2.12.10 behaviour: the run continues in the background and you are notified when it finishes. The shop's form shows the run's state meanwhile.
Scheduled sync runs on the old cycle, not the chosen Sync Frequency	The database is on an Odoo 19 build older than 19.0.2.12.0, where the setting governed nothing. Upgrade, then confirm the cadence on the shop.
Scheduled Actions shows 15 minutes but the shop is set to Every hour	Expected. 15 minutes is the tick at which Odoo checks which shops are due; each shop still syncs on its own Sync Frequency.
Finance or Analytics fails	Open the corresponding sync log and provide ECOSIRE Support with the safe TikTok error code, HTTP status, request ID, module version, and timestamp. Never include credentials.
Dashboard shows the wrong currency	Verify the configuration company and its currency, then refresh the synchronized data.
Code was updated but views or fields are missing	Upgrade the module from Apps so the client database loads the new schema and data.

Support

• General Troubleshooting
• Support Portal
• Email: [email protected]