TikTok Shop uses OAuth 2.0 Authorization Code flow combined with a per-request HMAC-SHA256 signature. Every API call requires both an access token header and a signed query parameter. The TikTok grant type is authorized_code (non-standard spelling).
Ensure your TikTok Shop seller account is active on the target region. TikTok Shop operates per-shop — each shop connects as a separate credential row with its own shop_cipher and warehouse_id.
Note that Sugibana's TikTok integration uses a shared marketplace app (App Key + App Secret). No developer account is required from your side.
TikTok refresh tokens have a 30-day hard expiry. After expiry, token refresh is impossible — you must re-authorize via OAuth. An AUTH_EXPIRY_WARNING incident fires at 7 days remaining; the connector card shows a red badge when expired. Re-authorize promptly to avoid a service gap.
On the Sales Channels page, click Connect TikTok Shop. You will be redirected to auth.tiktok-shops.com to authorize access.
Log in with your TikTok Shop seller account and approve the authorization request. After approval, you are redirected back to Sugibana.
Click Validate Connection. This step fetches your shop's warehouse_idfrom TikTok's Logistics API and stores it in the credential row. Without this step, stock push will failwith a "warehouse not found" error.
Enable Order sync and Stock push toggles. Orders will start importing in the next 5-minute cycle.
TikTok access tokens use the non-standard field name access_token_expire_in (not the RFC expires_in). Sugibana handles this correctly; do not modify the auth configuration.
Orders are polled every 5 minutes via /order/202309/orders/search using update_time_ge / update_time_lt filters.
TikTok status mapping: AWAITING_SHIPMENT / AWAITING_COLLECTION → Unshipped; IN_TRANSIT / DELIVERED / COMPLETED → Shipped; CANCELLED → Cancelled; UNPAID / ON_HOLD → Pending.
TikTok create_time is in Unix seconds (not milliseconds). Convert using new Date(ts * 1000).toISOString().
TikTok inventory updates use PUT /product/202309/products/inventory. The payload requires TikTok's internal SKU UUID (stored as tiktok_sku_id in tiktok_offer_mapping) — not the seller-facing seller_sku.
Run the SKU Alignment Wizard on the TikTok connector card to populate tiktok_offer_mapping with both tiktok_sku_id (internal UUID) and seller_sku for each SKU.
Enable the Stock push toggle. The inventory update uses the warehouse_id stored during the Validate Connection step — re-validate if the warehouse changes.
Every signed TikTok API call requires a shop_cipher query parameter. This cipher is stored at OAuth time from the seller_base_cipherfield. A missing cipher causes error 40000012 "Shop cipher is empty". Sugibana handles this automatically for all API calls.