# TikTok Shop & Pinterest Catalog Sync: installation and setup

> Overview The module connects your PrestaShop 8 or 9 shop to two channels: TikTok Shop: listings created and updated through the Partner API, stock and prices sent, orders imported, tracking…

- Page: <https://www.datafirefly.com/en/documentation/dftiktokpinterest/>
- Language: en
- Last updated: 2026-09-24
- Other languages: [fr](https://www.datafirefly.com/documentation/dftiktokpinterest/index.md), [es](https://www.datafirefly.com/es/documentation/dftiktokpinterest/index.md), [de](https://www.datafirefly.com/de/documentation/dftiktokpinterest/index.md), [it](https://www.datafirefly.com/it/documentation/dftiktokpinterest/index.md), [pl](https://www.datafirefly.com/pl/documentation/dftiktokpinterest/index.md), [nl](https://www.datafirefly.com/nl/documentation/dftiktokpinterest/index.md), [pt](https://www.datafirefly.com/pt/documentation/dftiktokpinterest/index.md)
- Index: <https://www.datafirefly.com/en/documentation/llms.txt>

## Overview

The module connects your PrestaShop 8 or 9 shop to two channels:

- **TikTok Shop**: listings created and updated through the Partner API, stock and prices sent, orders imported, tracking numbers sent back.
- **Pinterest**: TSV catalog feed and, optionally, real-time updates through the Catalogs API.

A CSV feed for TikTok Ads catalogs is also provided. The module lives in **Catalog > TikTok & Pinterest**. The _Overview_ tab shows a getting-started checklist listing the remaining steps.

## Installation

1. In **Modules > Module Manager**, click _Upload a module_ and select the ZIP file.
2. Open **Catalog > TikTok & Pinterest**.
3. In the _Settings_ tab, check the language, currency and country used for prices (prices are sent tax included for that country), then the image size. TikTok Shop requires at least 600 x 600 pixels.

With multistore, select one shop in the context selector: channel settings are stored per shop.

## Pinterest

### Feed only, no app

1. _Pinterest_ tab: enable Pinterest and copy the feed URL.
2. In Pinterest Business Hub, open **Catalogs > Data sources**, add a source and paste the URL. Pinterest imports the feed every 24 hours.

### Real-time updates through the API

1. On [developers.pinterest.com](https://developers.pinterest.com/), create an app and add the redirect URI shown in the module's Pinterest tab.
2. Enter the App ID and App secret, keep _Real-time updates_ on Yes and click _Save and connect Pinterest_.
3. Once connected, click _Create the data source on Pinterest_: the module registers the feed with the currency and country from the settings.

Stock, price changes and removals are then sent within minutes. Two minutes after each push, the module reads Pinterest's result back. A rejected item is flagged as an error in the _Products_ tab with Pinterest's message, for example "image_link: Image could not be downloaded".

## TikTok Shop

### Create the TikTok Shop app

1. On [partner.tiktokshop.com](https://partner.tiktokshop.com/), create a custom seller app or a third-party service app.
2. Enable the **Product**, **Order**, **Fulfillment** and **Logistics** scopes.
3. Set the redirect URL to the one shown in the module's _TikTok Shop_ tab.
4. Copy the App key, the App secret and, if the app has one, the Service ID.

### Connect the shop

1. _TikTok Shop_ tab: enable TikTok, choose the region (Europe and rest of world, or United States), enter the credentials, then click _Save and connect TikTok Shop_.
2. Authorize the app on the TikTok page. The module fetches the shop and the default warehouse.
3. Choose the warehouse if you have several, then the EU manufacturer and responsible person. Create them in Seller Center first if the lists are empty, then click _Refresh lists_.
4. Click _Load categories_ to fetch the TikTok category tree.

### Listing settings

- **Price sent**: price after PrestaShop discounts, or regular price if you run promotions in TikTok.
- **Default parcel**: weight and dimensions used for products that have none.
- **Create new listings**: when off, the module only updates stock and price of listings already online.

## Listings already on TikTok Shop

If you already sell on TikTok Shop, run _Link existing listings_ in the TikTok Shop tab **before the first sync**. The module goes through your listings and links them to your products by seller SKU:

- combination reference;
- product reference, for a product without combinations;
- the PS12 or PS12-34 format used by the module.

A linked listing keeps its TikTok title, images and description: the module only manages its stock and price. To apply the PrestaShop content, open the product preview in the Products tab and click _Replace its content with PrestaShop data_. A listing whose SKUs point to several PrestaShop products is reported as a conflict and not linked.

## Category mapping

The _Categories_ tab maps each PrestaShop category to:

- a **Google category**, used by Pinterest and by the TikTok Ads feed: type a few words and pick from the built-in Google taxonomy;
- a **TikTok Shop category**: type to search, or click _Suggest_ so TikTok proposes the category based on your products.

A subcategory without its own mapping inherits its parent's, shown in grey. Products use their default category. Changes are saved together with _Save changes_.

The _Attributes_ button opens the TikTok category attributes. Those marked with an asterisk are required by TikTok and apply to every product of the category. The mapping can be exported and imported as CSV (semicolon separator).

## TikTok orders

The _TikTok orders_ tab prevents overselling: without import, a TikTok sale only lowers the stock on TikTok. Three modes are available:

- **Create PrestaShop orders**: each sale becomes an order at the price paid on TikTok (seller discount deducted) and with the TikTok shipping fee. VAT is computed by PrestaShop and stock goes down. The payment shows as "TikTok Shop", with the TikTok order number as transaction.
- **Only decrement stock**: for orders shipped from Seller Center or by TikTok.
- **Off**.

Orders are imported by the cron task. When the import is switched on, orders from the last 24 hours are picked up. Choose the status of new orders and the carrier. The shipping amount stays the one paid on TikTok, whatever the carrier.

- **Cancellations**: a TikTok cancellation moves the order to "Canceled", or puts the stock back in stock-only mode.
- **Errors**: an order in error (unlinked SKU, currency not enabled) is listed with the reason and retried every 15 minutes. The _Retry_ button tries it again at the next import.
- **Buyers**: they are created as guest customers with an @tiktokshop.invalid address. TikTok forbids contacting them outside the platform, so the module blocks any e-mail addressed to them.

The PrestaShop order page shows a TikTok Shop block with the TikTok number, status and tracking state.

## Tracking numbers

When a tracking number is added to an imported order, by hand or by a carrier module, it is sent to TikTok within 5 minutes and the TikTok order is marked as shipped. Orders fulfilled by TikTok are skipped.

TikTok requires a shipping provider. In the TikTok Shop tab, section _Carriers and TikTok shipping providers_, map each PrestaShop carrier to a TikTok provider. Without a mapping, the module looks for a provider with the same name. If none matches, the error lists the available providers.

## Products tab

Each row shows the thumbnail, price, stock, status on each channel and a quality score out of 100 with the main issue. Possible causes are:

- missing image, zero price or short description;
- invalid EAN;
- unmapped category;
- more than 3 attribute groups for TikTok.

Filters show products in error, excluded, without a Google or TikTok category, or linked from Seller Center. Tick products to export or exclude them in bulk, or to queue a full sync. The preview shows the variants as they will be sent and lets you set a title for each channel. _Sync now_ pushes the product immediately.

## Advanced settings

- **UTM parameters**: added to feed and Pinterest pin links for Google Analytics attribution. Leave empty to disable.
- **Custom labels**: custom_label_0 = category, custom_label_1 = price band, custom_label_2 = promo or regular.
- **Exclusion rules**: categories (subcategories included), brands, minimum tax-inclusive price, and out-of-stock variants removed from the feeds and Pinterest. An excluded product is removed from the feeds, deleted from Pinterest and deactivated on TikTok Shop. Changing a rule queues the whole catalog again.
- **Push timing**: right after each change (PHP-FPM or LiteSpeed hosting), or by cron only.

## Cron task

Copy the two lines from the _Overview_ tab into your hosting crontab:

- every 5 minutes, `task=sync`: push queue, retries, TikTok orders, tracking, Pinterest results;
- every hour, `task=feeds`: feed regeneration.

The overview shows whether the cron was seen in the last 20 minutes. An API error is retried after 2, 4, 8, 16 then 32 minutes. The _Retry failed jobs_ button puts abandoned jobs back in the queue.

The security token protects the feed and cron URLs. If you regenerate it, update the crontab and the feed URLs registered on Pinterest and TikTok.

## Logs and troubleshooting

The _Logs_ tab keeps 30 days of events, filterable by channel: Pinterest, TikTok, TikTok orders. API errors are stored with the full response.

- **A product is not sent to TikTok**: check its score in the Products tab. A missing TikTok category or a virtual product blocks the push.
- **A TikTok order stays in error**: the seller SKU must match a PrestaShop reference, or the listing must have been created by the module. Fix it, then click _Retry_.
- **Changes made by an employee are not sent**: PrestaShop skips a module's hooks for a profile without the "View" permission on that module. Grant it, or use _Sync now_ in the Products tab.