Widget SDK user guide

This guide covers the TikTok Shop Widget SDK packages:

The latest versions above were checked against the npm registry on 2026-07-06. New integrations should install the latest dist-tag unless your TikTok Shop integration contact asks you to pin a specific version.

npm install @tiktokshop/widget-kit-react@latest
npm install @tiktokshop/widget-kit@latest

Use the React package if your app is built with React. It wraps SDK initialization, config updates, preloading, and rendering in components. Use the native JavaScript package if your app is not built with React or if you need to mount the widget manually into a DOM node.

Before integrating the Widget SDK:

1. Build a backend endpoint in your system that returns a short-lived widget token to your frontend. Your backend should call Get Widget Token, which maps to the OpenAPI path GET /authorization/202401/widget_token.
2. Configure your widget domain allowlist with TikTok Shop Open Platform. Widget pages have cross-origin restrictions, so the browser domain that hosts your frontend must be allowlisted.
3. Confirm the widget names enabled for your app. The SDK does not discover widget names automatically. The widget name list is provided in your widget integration documentation or by TikTok Shop Open Platform during widget enablement.
4. Keep TikTok Shop OpenAPI credentials and seller access tokens on your backend. Do not expose app secrets, seller access tokens, or signing logic in the browser.

Use explicit values from Partner Center, your seller authorization data, and your widget enablement materials. Do not leave placeholder strings such as xxx in production code.

The frontend must not call TikTok Shop OpenAPI directly. Use this flow:

1. The frontend calls your backend endpoint, for example GET /api/widget-token?shopId=7493990753256900486.
2. Your backend verifies the seller session and retrieves the seller's TikTok Shop access_token.
3. Your backend calls TikTok Shop OpenAPI GET /authorization/202401/widget_token with the required x-tts-access-token header.
4. TikTok Shop returns data.widget_token.token and data.widget_token.expire_at.
5. Your backend returns { "token": "...", "expire_at": 1703100448 } to the frontend.
6. The SDK calls getToken whenever it needs a valid widget token.

The internal request path /api/v1/seller/widget/get may appear in browser errors or screenshots because the hosted widget page calls an internal widget service. Developers should not call that internal interface directly. Implement your own getToken callback and backend endpoint, and have the backend call the public Get Widget Token OpenAPI.

The following example shows the shape of a backend endpoint. Replace getSellerAccessToken and callTikTokShopOpenAPI with your existing OpenAPI signing and token handling logic.

import express from "express";

const app = express();

async function getSellerAccessToken(shopId: string): Promise<string> {
  // Read the seller access token from your authorization storage.
  // Do not expose this token to the browser.
  return "";
}

async function callTikTokShopOpenAPI(path: string, accessToken: string) {
  // Use the same OpenAPI base URL, signing, timestamp, and app credentials
  // that your backend uses for other TikTok Shop OpenAPI calls.
  const response = await fetch(`${process.env.TTS_OPEN_API_BASE_URL}${path}`, {
    method: "GET",
    headers: {
      "Content-Type": "application/json",
      "x-tts-access-token": accessToken,
    },
  });

  return response.json();
}

app.get("/api/widget-token", async (req, res) => {
  const shopId = String(req.query.shopId ?? "");

  if (!shopId) {
    res.status(400).json({ message: "shopId is required" });
    return;
  }

  const accessToken = await getSellerAccessToken(shopId);
  const body = await callTikTokShopOpenAPI(
    `/authorization/202401/widget_token?shop_id=${encodeURIComponent(shopId)}`,
    accessToken,
  );

  const widgetToken = body?.data?.widget_token;
  if (body?.code !== 0 || !widgetToken?.token || !widgetToken?.expire_at) {
    res.status(502).json({
      message: "Failed to get widget token",
      request_id: body?.request_id,
      code: body?.code,
    });
    return;
  }

  res.json({
    token: widgetToken.token,
    expire_at: widgetToken.expire_at,
  });
});

Use WidgetConfigProvider once near the top of your React app. Use RemoteWidget where the widget should render.

import { WidgetConfigProvider, RemoteWidget } from "@tiktokshop/widget-kit-react";

const widgetName = "@tiktokshop-widget/product:optimizer";

const widgetConfig = {
  shopId: "7493990753256900486",
  oecRegion: "US",
  appKey: import.meta.env.VITE_TTS_APP_KEY,
  isvInfo: {
    name: "OPEN_PLATFORM",
  },
};

async function getWidgetToken() {
  const response = await fetch(`/api/widget-token?shopId=${widgetConfig.shopId}`);
  if (!response.ok) {
    throw new Error("Failed to request widget token");
  }

  const data = await response.json();
  return {
    token: data.token,
    expire_at: data.expire_at,
  };
}

export function App() {
  return (
    <WidgetConfigProvider
      config={widgetConfig}
      getToken={getWidgetToken}
      remotes={[{ name: widgetName }]}
      preloadWidgetNames={[widgetName]}
    >
      <RemoteWidget
        name={widgetName}
        className="widget-preview-container"
        options={{}}
      />
    </WidgetConfigProvider>
  );
}

Call init once before calling preloadWidget, loadWidget, or update.

import { init, preloadWidget, loadWidget, type WidgetComponent } from "@tiktokshop/widget-kit";

const widgetName = "@tiktokshop-widget/product:optimizer";

const widgetConfig = {
  shopId: "7493990753256900486",
  oecRegion: "US",
  appKey: import.meta.env.VITE_TTS_APP_KEY,
  isvInfo: {
    name: "OPEN_PLATFORM",
  },
};

async function getWidgetToken() {
  const response = await fetch(`/api/widget-token?shopId=${widgetConfig.shopId}`);
  if (!response.ok) {
    throw new Error("Failed to request widget token");
  }

  const data = await response.json();
  return {
    token: data.token,
    expire_at: data.expire_at,
  };
}

init({
  config: widgetConfig,
  getToken: getWidgetToken,
  remotes: [{ name: widgetName }],
});

await preloadWidget([widgetName]);

const component: WidgetComponent = await loadWidget(widgetName);
const view = component.create(document.getElementById("widget-preview-container")!);
await view.render({});

<div class="widget-preview-container" id="widget-preview-container"></div>

Preloading is optional. Use it when the widget is not displayed on the first screen and you want to load resources earlier. For React, pass preloadWidgetNames to WidgetConfigProvider.

<WidgetConfigProvider
  config={widgetConfig}
  getToken={getWidgetToken}
  remotes={[{ name: widgetName }]}
  preloadWidgetNames={[widgetName]}
>
  <RemoteWidget name={widgetName} options={{}} />
</WidgetConfigProvider>

For native JavaScript, call preloadWidget after init.

import { preloadWidget } from "@tiktokshop/widget-kit";

await preloadWidget(["@tiktokshop-widget/product:optimizer"]);

For React, use RemoteWidget.

import { RemoteWidget } from "@tiktokshop/widget-kit-react";

export function ProductOptimizerWidget() {
  return (
    <RemoteWidget
      name="@tiktokshop-widget/product:optimizer"
      className="widget-preview-container"
      options={{}}
    />
  );
}

For native JavaScript, call loadWidget after init.

import { loadWidget, type WidgetComponent } from "@tiktokshop/widget-kit";

const component: WidgetComponent = await loadWidget("@tiktokshop-widget/product:optimizer");
const view = component.create(document.getElementById("widget-preview-container")!);
await view.render({});

Use update when the current seller or shop context changes after initialization. For React, update the props passed to WidgetConfigProvider. For native JavaScript, call update. getToken is required during initialization. In update, pass getToken only if the token callback has changed.

import { update } from "@tiktokshop/widget-kit";

await update({
  config: {
    shopId: "7493990753256900486",
    oecRegion: "US",
    appKey: import.meta.env.VITE_TTS_APP_KEY,
    isvInfo: {
      name: "OPEN_PLATFORM",
    },
  },
  getToken: getWidgetToken,
});

init exists in @tiktokshop/widget-kit. Call it once before loading or preloading widgets.

getToken must resolve to the token object expected by the SDK.

loadWidget loads one widget by name.

const component = await loadWidget("@tiktokshop-widget/product:optimizer");
const view = component.create(document.getElementById("widget-preview-container")!);
await view.render({});

update exists in @tiktokshop/widget-kit. Use it to update widget configuration after initialization.

preloadWidget exists in @tiktokshop/widget-kit.

WidgetConfigProvider exists in @tiktokshop/widget-kit-react. Place it above the React components that render remote widgets.

RemoteWidget exists in @tiktokshop/widget-kit-react. Use it to render one enabled widget.

These interfaces apply to native JavaScript integration.

export interface WidgetComponent {
  create: (el: HTMLElement) => WidgetView;
}

export interface WidgetView {
  render: (props: Record<string, any>) => Promise<void>;
  unmount: () => Promise<void>;
  update: (props: Record<string, any>) => Promise<void>;
}

Symptom: the browser repeatedly requests a widget token and the widget page never finishes loading. Image Most common causes:

• getToken does not return { token, expire_at }.
• The backend returned the full OpenAPI response instead of data.widget_token.
• The token is expired.
• shopId, oecRegion, appKey, or the seller access token do not match.
• The frontend domain is not allowlisted for the widget.

The frontend getToken callback should return only the widget token object: Image

async function getWidgetToken() {
  const response = await fetch(`/api/widget-token?shopId=${widgetConfig.shopId}`);
  const data = await response.json();

  return {
    token: data.token,
    expire_at: data.expire_at,
  };
}

FAQ - Why do I see /api/v1/seller/widget/get in errors?

/api/v1/seller/widget/get is an internal widget service request made by the hosted widget page. It is not the public API that developers should call. Developers should call the public OpenAPI from the backend:

If the internal request fails, debug your public-token flow first: getToken output shape, token expiration, app key, shop ID, region, seller access token, and domain allowlist. Common internal widget error codes:

Symptom: the SDK reports Current name configuration not found or the widget page cannot be found. Image Check the widget name in the integration documentation shared for your app, then verify:

• The same widget name appears in remotes.
• RemoteWidget.name, preloadWidgetNames, and loadWidget(name) use the same exact string.
• The widget scenario is enabled for your app by TikTok Shop Open Platform.