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.10.19 (Odoo 17/18: 17.0.2.10.5 /
18.0.2.10.5). Fulfilment priority/SLA tracking and the Packages screen
described below ship on Odoo 19 only.
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
- 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)
- Fulfilment priority and SLA deadline tracking on orders and packages, with overdue alerts (Odoo 19)
- 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
- An active ECOSIRE license for the module
- 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
- Download the matching Odoo version from your ECOSIRE Dashboard.
- Extract the module into an Odoo addons directory.
- Restart Odoo and update the Apps list.
- Search for TikTok Shop Store Management and install it.
- Activate the ECOSIRE license when prompted.
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
- In TikTok Shop Partner Center, create or select the application used by the seller.
- Request the read/write scopes required for the workflows you will enable.
- Complete TikTok's OAuth authorization for the seller shop.
- In Odoo, open TikTok Shop → Configuration and create or edit the shop.
- Enter the shop identity and credentials, assign the Odoo company and currency context, then use Test Connection.
- 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
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.
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 (see below) 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.
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 provider-app permission issue, not an Odoo license failure.
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.
On Odoo 17 and 18, pushing a completed Odoo shipment or tracking number back to TikTok is not yet 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.
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.
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. |
| 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. |