Integrate Node.js SDK

Follow this guide to install the TikTok Shop Node.js SDK, retrieve a seller access token, get an authorized shop's shop_cipher, and make your first product API call with Search Products. The SDK signs TikTok Shop API requests for you. Use Sign your API request only when you call OpenAPI endpoints with your own HTTP client instead of the SDK. This guide uses:

Version note: API groups do not always share the same version. For example, this guide uses AuthorizationV202309Api for Get Authorized Shops because the current endpoint is /authorization/202309/shops, while the Search Products example uses ProductV202502Api.

Before integrating the SDK, you need:

1. A TikTok Shop app and a test seller account. See Create a test seller account.
2. A seller authorization code from the redirect URL configured for your test app. See Generate a test access token.
3. The latest Node.js SDK package downloaded from Partner Center. SDK packages are generated for your app's enabled scopes and API versions. See Update SDK.

Do not commit app_key, app_secret, access_token, refresh_token, authorization codes, or seller data to source control. Load secrets from environment variables or your secret manager.

Use a supported Node.js LTS release. As of July 2026, Node.js 22.x and 24.x are supported LTS lines; Node.js 16.x is end-of-life. Check the Node.js release schedule before publishing a new version of this guide. Recommended baseline:

After downloading and unzipping the SDK, place it in your project and import it by the relative path from your code file to the SDK entry point. Example layout:

my-project/
  package.json
  tsconfig.json
  src/
    index.ts
  tiktok-shop-node-sdk/
    index.ts
    api/
    model/
    ...

If your demo file is src/index.ts, import from the SDK folder with:

import {
  AccessTokenTool,
  ClientConfiguration,
  TikTokShopNodeApiClient,
} from "../tiktok-shop-node-sdk";

If you place the demo file directly inside the SDK root, from "." works because it points to that folder's index.ts. In an application project, prefer importing from the explicit SDK folder path.

Install the dependencies listed in the SDK package you downloaded. If the generated SDK includes its own package.json, use that file as the source of truth. For a new TypeScript project around the SDK, start with a maintained baseline similar to this:

{
  "type": "module",
  "scripts": {
    "start": "tsx src/index.ts"
  },
  "dependencies": {
    "tslib": "^2.8.1"
  },
  "devDependencies": {
    "@types/node": "^24",
    "tsx": "^4",
    "typescript": "^6"
  }
}

Do not add request or @types/request to new integrations. The request package is deprecated and should not be used for new custom HTTP code. If your downloaded SDK still depends on request, download the latest SDK from Partner Center and check whether the generated client has been updated; otherwise keep the dependency only as a compatibility requirement for that specific SDK package. Add the following to tsconfig.json:

{
  "compilerOptions": {
    "esModuleInterop": true,
    "moduleResolution": "node",
    "target": "ES2022",
    "module": "ESNext",
    "strict": true
  }
}

Install dependencies:

npm install

You can also use yarn install or pnpm install if your project standardizes on Yarn or pnpm.

Configure the SDK from environment variables:

const requiredEnv = (name: string): string => {
  const value = process.env[name];
  if (!value) {
    throw new Error(`Missing required environment variable: ${name}`);
  }
  return value;
};

ClientConfiguration.globalConfig.app_key = requiredEnv("TTS_APP_KEY");
ClientConfiguration.globalConfig.app_secret = requiredEnv("TTS_APP_SECRET");

const client = new TikTokShopNodeApiClient({
  config: {
    sandbox: process.env.TTS_SANDBOX === "true",
  },
});

sandbox: false sends requests to the production environment. Use sandbox: true only when you are testing against the sandbox or Development Shop environment supported by your SDK package.

Use the SDK helper to exchange the one-time seller authorization code for an access token.

const authCode = requiredEnv("TTS_AUTH_CODE");

const { body: tokenBody } = await AccessTokenTool.getAccessToken(authCode);
console.log("getAccessToken response:", JSON.stringify(tokenBody, null, 2));

const accessToken = tokenBody.data?.access_token;
if (!accessToken) {
  throw new Error("Failed to get access token");
}

In production, store the access token, refresh token, and their expiration timestamps in a secure server-side data store. Do not store tokens in frontend code.

shop_cipher identifies the authorized shop for shop-level APIs such as Search Products. Call Get Authorized Shops with the seller accessToken and use data.shops[].cipher from the response.

const contentType = "application/json";

const { body: shopsGetBody } =
  await client.api.AuthorizationV202309Api.ShopsGet(accessToken, contentType);

console.log("ShopsGet response:", JSON.stringify(shopsGetBody, null, 2));

const shopList = shopsGetBody.data?.shops ?? [];
if (shopList.length === 0) {
  throw new Error("No authorized shops found.");
}

const selectedShop = shopList[0];
const shopId = selectedShop.id;
const shopCipher = selectedShop.cipher;

if (!shopCipher) {
  throw new Error(`No shop_cipher found for shop_id: ${shopId}`);
}

console.log(`Using shop_id: ${shopId}, shop_cipher: ${shopCipher}`);

Do not hard-code shop_cipher. Always use the cipher for the shop whose products you want to access.

Call Search Products after you have both accessToken and shopCipher. OpenAPI endpoint:

Node.js SDK method call used in this guide:

Different SDK languages may generate different positional argument orders. Do not copy the Java or Go method argument order into Node.js code. Check the generated Node.js SDK method signature in your downloaded SDK when you update the SDK.

const pageSize = 10;
const pageToken = undefined;
const searchProductsRequestBody = {};

const result = await client.api.ProductV202502Api.ProductsSearchPost(
  pageSize,
  accessToken,
  contentType,
  pageToken,
  searchProductsRequestBody,
  shopCipher
);

console.log("Search Products response:", JSON.stringify(result.body, null, 2));

import {
  AccessTokenTool,
  ClientConfiguration,
  TikTokShopNodeApiClient,
} from "../tiktok-shop-node-sdk";

const requiredEnv = (name: string): string => {
  const value = process.env[name];
  if (!value) {
    throw new Error(`Missing required environment variable: ${name}`);
  }
  return value;
};

ClientConfiguration.globalConfig.app_key = requiredEnv("TTS_APP_KEY");
ClientConfiguration.globalConfig.app_secret = requiredEnv("TTS_APP_SECRET");

const client = new TikTokShopNodeApiClient({
  config: {
    sandbox: process.env.TTS_SANDBOX === "true",
  },
});

const main = async () => {
  const contentType = "application/json";

  const authCode = requiredEnv("TTS_AUTH_CODE");
  const { body: tokenBody } = await AccessTokenTool.getAccessToken(authCode);
  console.log("getAccessToken response:", JSON.stringify(tokenBody, null, 2));

  const accessToken = tokenBody.data?.access_token;
  if (!accessToken) {
    throw new Error("Failed to get access token");
  }

  const { body: shopsGetBody } =
    await client.api.AuthorizationV202309Api.ShopsGet(accessToken, contentType);
  console.log("ShopsGet response:", JSON.stringify(shopsGetBody, null, 2));

  const shopList = shopsGetBody.data?.shops ?? [];
  if (shopList.length === 0) {
    throw new Error("No authorized shops found.");
  }

  const selectedShop = shopList[0];
  const shopId = selectedShop.id;
  const shopCipher = selectedShop.cipher;
  if (!shopCipher) {
    throw new Error(`No shop_cipher found for shop_id: ${shopId}`);
  }

  console.log(`Using shop_id: ${shopId}, shop_cipher: ${shopCipher}`);

  const pageSize = 10;
  const pageToken = undefined;
  const searchProductsRequestBody = {};

  const result = await client.api.ProductV202502Api.ProductsSearchPost(
    pageSize,
    accessToken,
    contentType,
    pageToken,
    searchProductsRequestBody,
    shopCipher
  );

  console.log("Search Products response:", JSON.stringify(result.body, null, 2));
};

main().catch((error) => {
  console.error(error);
  process.exitCode = 1;
});

Run the demo with environment variables:

TTS_APP_KEY="your_app_key" \
TTS_APP_SECRET="your_app_secret" \
TTS_AUTH_CODE="your_auth_code" \
TTS_SANDBOX="true" \
npm run start

Use TTS_SANDBOX="false" or omit TTS_SANDBOX for production.

SDK packages are app-specific and generated from the scopes and API versions available to your app. Record the SDK download date or package version in your project so you can reproduce generated method signatures. Update the SDK when:

For SDK update behavior, see Update SDK.