TikTok Shop API Client

API Client

npm i tiktokshops-api-client

tiktokshops-api-client is a TypeScript library for TikTok Shop Open API, covering all 14 domains of the reference tiktok-shop-sdk (155 endpoints): orders, products, fulfillment, logistics, finance, promotions, returns and refunds, affiliate, analytics and more. It implements TikTok's HMAC-SHA256 request signing, including the shop_cipher parameter and the separate signing rule for multipart uploads. The domains live under typed namespaces (tiktok.finance, tiktok.order, …) next to the original flat methods, so existing code keeps working. Failures throw a TiktokApiError, and every call has a 30-second timeout.

Key Features

◆155 endpoints across 14 domains: order, product, fulfillment, logistics, finance, promotion, return/refund, affiliate, analytics, seller, shop and more
◆Namespaced domains (tiktok.finance.*, tiktok.order.*) sit next to the original flat methods without breaking them
◆HMAC-SHA256 request signing, with shop_cipher and the multipart signing rule handled for you
◆Errors: failures throw a TiktokApiError with code, request ID and HTTP status; 30s timeout on every call
◆Product image and file uploads over multipart/form-data
◆OAuth: generateAuthLink (US Partner Center supported), fetchTokenWithAuthCode, refreshToken, getAuthorizedShop
◆No any in the public API; every endpoint checked against the reference SDK, 17 unit tests

Code Examples

Creating the client

import { TiktokModule } from "tiktokshops-api-client";

const tiktok = new TiktokModule({
  appKey: process.env.TIKTOK_APP_KEY!,
  appSecret: process.env.TIKTOK_APP_SECRET!,
  serviceId: process.env.TIKTOK_SERVICE_ID!,
  shopId: process.env.TIKTOK_SHOP_ID!,
  shopCipher: process.env.TIKTOK_SHOP_CIPHER!,
  accessToken: process.env.TIKTOK_ACCESS_TOKEN!,
  refreshToken: process.env.TIKTOK_REFRESH_TOKEN!,
});

Fetching orders

// Orders from the last 24 hours
const orders = await tiktok.getOrderList({
  beforeHours: 24,
  pageSize: 20,
  sortField: "create_time",
  sortOrder: "ASC",
});

console.log(orders);

// Detail for a single order
const detail = await tiktok.getOrderDetail("ORDER_NUMBER");
console.log(detail);

Creating a product

import { TiktokModule } from "tiktokshops-api-client";

const tiktok = new TiktokModule({ /* config */ });

// Look up the category and its attributes
const categories = await tiktok.getCategories();
const attributes = await tiktok.getAttributes(categoryId);

// Create the product
const newProduct = await tiktok.createProduct({
  product_name: "Product name",
  category_id: "CATEGORY_ID",
  description: "Product description...",
  // ... remaining fields
});

Namespaced domains

import { TiktokApiError } from "tiktokshops-api-client";

try {
  // Finance: settlements and withdrawals from the last 7 days
  const withdrawals = await tiktok.finance.getWithdrawals({
    types: ["WITHDRAW", "SETTLE"],
    create_time_ge: Math.floor(Date.now() / 1000) - 7 * 24 * 3600,
    page_size: 50,
  });
  console.log(withdrawals.data);
} catch (err) {
  if (err instanceof TiktokApiError) {
    console.error(err.code, err.requestId, err.status);
  }
  throw err;
}

Resources

GitHub Repository npm Registry Full Documentation

Handling Shopee and TikTok Shop webhook pushes safely

HMAC signature verification fails for a reason that has nothing to do with the key or the algorithm: one JSON parse-and-reserialize step, done before signature check, is enough to change every byte.

TikTok Shop API Client — API ClientBack to Home