### Run Examples CLI App

Source: https://github.com/hsib19/tiktok-shop-sdk/blob/main/CLAUDE.md

Starts the interactive CLI examples application, useful for testing SDK modules.

```bash
pnpm dev:examples
```

--------------------------------

### SDK Initialization and Usage Examples

Source: https://github.com/hsib19/tiktok-shop-sdk/blob/main/packages/sdk/README.md

Demonstrates how to initialize the TikTokShopSDK and provides examples for obtaining an access token and updating shop webhooks.

```APIDOC
## Initialize SDK

```ts
import { TikTokShopSDK } from 'tiktok-shop-sdk';

const sdk = new TikTokShopSDK({
  appKey: '', // Your TikTok Shop App Key
  appSecret: '', // Your TikTok Shop App Secret
});
```

## Example 1: Request Access Token

This example shows how to request an access token using the authorization code grant type.

### Method

`sdk.auth.getAccessToken(params: { auth_code: string; grant_type: 'authorized_code' })`

### Parameters

- **auth_code** (string) - Required - The authorization code obtained from TikTok.
- **grant_type** (string) - Required - Must be set to `"authorized_code"`.

### Request Example

```ts
const response = await sdk.auth.getAccessToken({
  auth_code: '', // Authorization code obtained from TikTok (must be provided)
  grant_type: 'authorized_code', // Grant type, typically fixed as "authorized_code"
});

console.log('Access Token Response:', response);
```

## Example 2: Update Shop Webhook

This example demonstrates how to set the access token and shop cipher, then update a shop's webhook configuration.

### Method

`sdk.event.updateShopWebhook(params: { address: string; event_type: string })`

### Parameters

- **address** (string) - Required - The URL for the webhook.
- **event_type** (string) - Required - The type of event to subscribe to (e.g., `"NEW_CONVERSATION"`).

### Request Example

```ts
// Set Access Token - typically stored in environment variables
sdk.setAccessToken(process.env.TIKTOK_APP_ACCESS_KEY!); 

// Set Shop Cipher - also typically stored in environment variables
sdk.setShopCipher(process.env.TIKTOK_SHOP_CIPHER!);

// Update shop webhook configuration
const updateResponse = await sdk.event.updateShopWebhook({
  address: 'https://urlhere.com/notify',
  event_type: 'NEW_CONVERSATION',
});

console.log(updateResponse);
```
```

--------------------------------

### Get Authorized Shops with SDK

Source: https://github.com/hsib19/tiktok-shop-sdk/blob/main/apps/docs/core-api/authorization/get-authorized-shop.md

Use this TypeScript example to initialize the SDK, set an access token, and retrieve a list of authorized shops. It includes basic error handling for API-specific errors.

```typescript
import { TikTokShopSDK, TikTokAPIError } from 'tiktok-shop-sdk';

const sdk = new TikTokShopSDK({
  appKey: process.env.TIKTOK_APP_KEY!,
  appSecret: process.env.TIKTOK_APP_SECRET!,
});

async function main() {
  try {
    // Set Access Token (seller-level)
    sdk.setAccessToken(process.env.TIKTOK_APP_ACCESS_KEY!);

    // Get authorized shops
    const response = await sdk.shop.getAuthorizedShops();

    console.log('Authorized Shops:', response.data);
  } catch (error) {
    if (error instanceof TikTokAPIError) {
      console.error('TikTok API Error:', error.message);
      console.error('Status Code:', error.code);
      console.error('Request ID:', error.request_id);
    } else {
      console.error('Unexpected Error:', error);
    }
  }
}

main();

```

--------------------------------

### JSON: Package Handover Time Slots Response Example

Source: https://github.com/hsib19/tiktok-shop-sdk/blob/main/apps/docs/core-api/fulfilment/get-package-handover-time-slots.md

This is an example of a successful response when retrieving package handover time slots. It includes the start time, end time, and cutoff time for each available slot.

```json
{
  "code": 0,
  "data": {
    "time_slots": [
      {
        "start_time": "2024-07-02T09:00:00Z",
        "end_time": "2024-07-02T11:00:00Z",
        "cutoff_time": "2024-07-01T23:59:00Z"
      }
    ]
  },
  "message": "Success",
  "request_id": "20240702143000010123456789ABCDEFFF"
}
```

--------------------------------

### Install TikTok Shop SDK

Source: https://github.com/hsib19/tiktok-shop-sdk/blob/main/packages/sdk/README.md

Install the SDK using npm or Yarn. Ensure you have Node.js and npm/Yarn installed.

```bash
npm install tiktok-shop-sdk
```

```bash
yarn add tiktok-shop-sdk
```

--------------------------------

### Run Development Examples

Source: https://github.com/hsib19/tiktok-shop-sdk/blob/main/README.md

Execute the CLI in the examples package from the monorepo root. This allows you to test and interact with different modules of the SDK.

```bash
pnpm run dev:examples
```

--------------------------------

### Response Example (JSON)

Source: https://github.com/hsib19/tiktok-shop-sdk/blob/main/apps/docs/core-api/analytics/get-shop-product-performance.md

This is an example of a successful response from the getShopProductPerformance API, detailing product metrics.

```json
{
  "code": 0,
  "data": {
    "product_id": "230947230423423",
    "metrics": {
      "gmv": "15000000",
      "sales_volume": 1200,
      "views": 54000,
      "conversion_rate": 0.032
    }
  },
  "message": "Success",
  "request_id": "202407021200000122334455AAFFEE"
}
```

--------------------------------

### Get Affiliate Partner Campaign Product List Example

Source: https://github.com/hsib19/tiktok-shop-sdk/blob/main/apps/docs/core-api/affiliate-partner/get-affiliate-partner-campaign-product-list.md

Demonstrates how to initialize the SDK, set access tokens and ciphers, and call the `getAffiliatePartnerCampaignProductList` method. Includes error handling for TikTok API specific errors and general exceptions.

```typescript
import { TikTokAPIError, TikTokShopSDK } from 'tiktok-shop-sdk';

const sdk = new TikTokShopSDK({
  appKey: process.env.TIKTOK_APP_KEY!,
  appSecret: process.env.TIKTOK_APP_SECRET!,
});

async function main() {
  try {
    // Set Access Token
    sdk.setAccessToken(process.env.TIKTOK_APP_ACCESS_KEY!);
    // Set Category Assets Cipher
    sdk.setCategoryAssetsCipher(process.env.TIKTOK_SHOP_CIPHER!);

    const response =
      await sdk.affiliatePartner.getAffiliatePartnerCampaignProductList({
        path: {
          campaign_id: '3498573945345',
        },
        query: {
          page_size: 20,
        },
      });

    console.log('Response:', response);
  } catch (error) {
    if (error instanceof TikTokAPIError) {
      console.error('TikTok API Error:', error.message);
      console.error('Status Code:', error.code);
      console.log('Request Id: ', error.request_id);
    } else {
      console.error('Unexpected error:', error);
    }
  }
}

main();

```

--------------------------------

### Install Dependencies and Run Tests

Source: https://github.com/hsib19/tiktok-shop-sdk/blob/main/CONTRIBUTING.md

Install project dependencies and run tests to ensure code quality and functionality before committing changes. Linting is also performed.

```bash
pnpm install
pnpm run test
pnpm run lint
```

--------------------------------

### Install Project Dependencies

Source: https://github.com/hsib19/tiktok-shop-sdk/blob/main/README.md

Install all project dependencies using pnpm after cloning the repository. This command ensures all necessary packages are available for development.

```bash
pnpm install
```

--------------------------------

### Create Return Response Example - JSON

Source: https://github.com/hsib19/tiktok-shop-sdk/blob/main/apps/docs/core-api/return-and-refund/create-return.md

This is an example of a successful response when creating a return request. It includes the return ID and its initial status.

```json
{
  "code": 0,
  "data": {
    "return_id": "1234567890123456789",
    "status": "PENDING"
  },
  "message": "Success",
  "request_id": "202407031245009988776655AABBCC"
}
```

--------------------------------

### Order List Response Example (JSON)

Source: https://github.com/hsib19/tiktok-shop-sdk/blob/main/apps/docs/core-api/orders/get-order-list.md

This is an example of a successful response when retrieving an order list. It includes order details and line items.

```json
{
  "code": 0,
  "message": "Success",
  "data": {
    "orders": [
      {
        "order_id": "1234567890123456789",
        "order_status": "COMPLETED",
        "line_items": [
          {
            "product_id": "9876543210987654321",
            "sku_id": "9876543210123",
            "quantity": 1
          }
        ]
      }
    ]
  },
  "request_id": "20240301094500123456789ABCDE"
}
```

--------------------------------

### Install TikTok Shop SDK

Source: https://github.com/hsib19/tiktok-shop-sdk/blob/main/README.md

Install the SDK using npm or yarn. This is the first step to integrating the TikTok Shop API into your Node.js application.

```bash
npm install tiktok-shop-sdk
# or
yarn add tiktok-shop-sdk
```

--------------------------------

### Promotion Activities Response Example

Source: https://github.com/hsib19/tiktok-shop-sdk/blob/main/apps/docs/core-api/promotion/search-activities.md

This is an example of a successful response when searching for promotion activities. It includes activity details, pagination information, and a request ID for tracking.

```json
{
  "code": 0,
  "data": {
    "activities": [
      {
        "activity_id": "7523240167205979921",
        "status": "DEACTIVATED",
        "update_time": 1709270400
      }
    ],
    "page_no": 1,
    "page_size": 20,
    "total": 1
  },
  "message": "Success",
  "request_id": "202402291200000101890810281AEC88FF"
}
```

--------------------------------

### Promotion Activity Response Example (JSON)

Source: https://github.com/hsib19/tiktok-shop-sdk/blob/main/apps/docs/core-api/promotion/get-activity.md

This is an example of a successful response when retrieving promotion activity details. It includes status codes, messages, request IDs, and detailed data about the activity.

```json
{
  "code": 0,
  "data": {
    "activity_id": "7523240167205979921",
    "title": "FlashSaleJanuary",
    "status": "ONGOING",
    "create_time": 1709200000,
    "update_time": 1709270400,
    "duration_type": "FIXED",
    "begin_time": 1709200000,
    "end_time": 1709270400
  },
  "message": "Success",
  "request_id": "202402291200000101890810281AEC88FF"
}
```

--------------------------------

### Combinable Packages Response Example

Source: https://github.com/hsib19/tiktok-shop-sdk/blob/main/apps/docs/core-api/fulfilment/search-combinable-packages.md

This is an example of a successful response when searching for combinable packages. It includes package details, weight, dimensions, and a token for fetching the next page of results.

```json
{
  "code": 0,
  "message": "Success",
  "request_id": "20240701143000010123456789ABCDEFFF",
  "data": {
    "packages": [
      {
        "package_id": "PKG123456",
        "order_id": "1162200639229365029",
        "package_status": "READY_TO_COMBINE",
        "weight": {
          "value": "0.5",
          "unit": "KG"
        },
        "dimension": {
          "length": "20",
          "width": "10",
          "height": "5",
          "unit": "CM"
        }
      }
    ],
    "next_page_token": "abcdef123456"
  }
}
```

--------------------------------

### Response Example (JSON)

Source: https://github.com/hsib19/tiktok-shop-sdk/blob/main/apps/docs/core-api/logistic/get-global-seller-warehouse.md

This is an example of a successful response when retrieving global seller warehouse information. It includes status codes, messages, request IDs, and detailed warehouse data.

```json
{
  "code": 0,
  "data": {
    "warehouses": [
      {
        "warehouse_id": "99887766",
        "warehouse_name": "Global Seller Warehouse",
        "country": "CN",
        "address": "Guangdong, China"
      }
    ]
  },
  "message": "Success",
  "request_id": "20240701153000012233445566AABBCC"
}
```

--------------------------------

### Initialize SDK Client

Source: https://github.com/hsib19/tiktok-shop-sdk/blob/main/apps/docs/authentication.md

Create a client instance using your app credentials and the obtained auth code.

```APIDOC
## Initialize SDK Client

### Description
Create a client instance using your credentials and auth code.

### Code Example
```ts
import { TikTokShopClient } from 'tiktok-shop-sdk';

const client = new TikTokShopClient({
  appKey: process.env.TTS_APP_KEY!,
  appSecret: process.env.TTS_APP_SECRET!,
  authCode: process.env.TIKTOK_AUTH_CODE!,
});
```
```

--------------------------------

### Get Shop SKU Performance

Source: https://github.com/hsib19/tiktok-shop-sdk/blob/main/apps/docs/core-api/analytics/get-shop-sku-performance.md

Retrieves performance metrics for a specific SKU. Requires SKU ID, start date, and end date. Optional parameters include currency, granularity, and comparison data.

```APIDOC
## Get Shop SKU Performance

### Description
Retrieves performance metrics for a specific SKU in your TikTok Shop.

### Method
`analytics.getShopSKUPerformance()`

### Parameters
#### Path / Main Parameters
- **`sku_id`** (string) - Required - SKU ID to retrieve performance for.

#### Query Parameters
- **`start_date_ge`** (string) - Required - Start date (inclusive), format: `YYYY-MM-DD`.
- **`end_date_lt`** (string) - Required - End date (exclusive), format: `YYYY-MM-DD`.
- **`currency`** (string) - Optional - Currency of metrics returned.
- **`granularity`** (string) - Optional - Data granularity (`DAILY`, `WEEKLY`, etc.).
- **`with_comparison`** (boolean) - Optional - Whether to return comparison data.

### Request Example (TypeScript)
```ts
import { TikTokShopSDK, TikTokAPIError } from 'tiktok-shop-sdk';

const sdk = new TikTokShopSDK({
  appKey: process.env.TIKTOK_APP_KEY!,
  appSecret: process.env.TIKTOK_APP_SECRET!,
});

try {
  sdk.setAccessToken(process.env.TIKTOK_APP_ACCESS_KEY!);
  sdk.setShopCipher(process.env.TIKTOK_SHOP_CIPHER!); 

  const response = await sdk.analytics.getShopSKUPerformance({
    sku_id: '9830453450345345',
    query: {
      end_date_lt: '2024-09-08',
      start_date_ge: '2024-09-09',
    },
  });

  console.log(response);
} catch (error) {
  if (error instanceof TikTokAPIError) {
    console.error('TikTok API Error:', error.message);
  } else {
    console.error('Unexpected error:', error);
  }
}
```

### Response Example (JSON)
```json
{
  "code": 0,
  "data": {
    "sku_id": "9830453450345345",
    "performance": {
      "gmv": "1500000",
      "units_sold": 120,
      "views": 4500,
      "conversion_rate": 0.026
    }
  },
  "message": "Success",
  "request_id": "202407041210998877665544"
}
```

### Response Descriptions
#### Top-Level Fields
- **`code`** (int) - API status code (0 = success).
- **`message`** (string) - Response message.
- **`request_id`** (string) - Unique request ID for debugging.
- **`data`** (object) - Contains SKU performance results.

#### `data.performance` Object
- **`gmv`** (string) - Gross Merchandise Value of the SKU.
- **`units_sold`** (number) - SKU units sold.
- **`views`** (number) - Number of product detail views.
- **`conversion_rate`** (number) - Conversion rate (0–1).
```

--------------------------------

### Response Example for Get Reject Reasons

Source: https://github.com/hsib19/tiktok-shop-sdk/blob/main/apps/docs/core-api/return-and-refund/get-reject-reasons.md

Illustrates the structure of a successful response when retrieving reject reasons, including the API status code, message, request ID, and the list of reject reasons with their codes and descriptions.

```json
{
  "code": 0,
  "data": {
    "reject_reasons": [
      {
        "reason_code": "R001",
        "reason_description": "Item not eligible for return"
      },
      {
        "reason_code": "R002",
        "reason_description": "Evidence provided is insufficient"
      }
    ]
  },
  "message": "Success",
  "request_id": "202407021210000112233445566AABB"
}
```

--------------------------------

### Create Promotion Activity

Source: https://github.com/hsib19/tiktok-shop-sdk/blob/main/apps/docs/core-api/promotion/update-activity.md

This example demonstrates how to create a promotion activity with various discount options like fixed price, shipping discounts, and Buy More Save More (BMSM) discounts. It also shows how to set participation limits and activity durations.

```APIDOC
## POST /promotion/createActivity

### Description
Creates a new promotion activity for the shop.

### Method
POST

### Endpoint
/promotion/createActivity

### Request Body
- **title** (string) - Required - The title of the promotion activity.
- **activity_type** (string) - Required - The type of activity (e.g., 'FIXED_PRICE').
- **product_level** (string) - Required - The level at which the promotion applies (e.g., 'PRODUCT').
- **duration_type** (string) - Required - The duration type of the activity (e.g., 'INDEFINITE').
- **begin_time** (integer) - Required - Unix timestamp for the start of the activity.
- **end_time** (integer) - Required - Unix timestamp for the end of the activity.
- **participation_limit** (array) - Required - Limits on participation.
  - **type** (string) - Required - The type of limit (e.g., 'BUYER_NO_LIMIT').
- **discount** (object) - Required - Discount details.
  - **shipping_discount** (object) - Optional - Details for shipping discounts.
    - **threshold_type** (string) - Required - Type of threshold (e.g., 'MINIMAL_ITEM_QUANTITY').
    - **threshold_value** (string) - Required - Value of the threshold.
    - **type** (string) - Required - Type of shipping discount (e.g., 'DISCOUNT_SHIPPING_FEE').
    - **value** (string) - Required - The discount value.
    - **shipping_method** (string) - Required - The shipping method.
    - **inventory_type** (string) - Required - Inventory type (e.g., 'SELF_FULFILLED').
    - **area_scope** (object) - Required - Scope of the discount area.
      - **type** (string) - Required - Type of area scope (e.g., 'WHOLE').
      - **specific_areas** (array) - Optional - List of specific areas.
  - **bmsm_discount** (object) - Optional - Details for Buy More Save More discounts.
    - **details** (array) - Required - List of BMSM discount tiers.
      - **tier** (integer) - Required - The tier number.
      - **threshold_type** (string) - Required - Type of threshold.
      - **threshold_value** (string) - Required - Value of the threshold.
      - **type** (string) - Required - Type of discount (e.g., 'PERCENTAGE_OFF').
      - **value** (string) - Required - The discount value.

### Request Example
```json
{
  "title": "DiscountEvent07041",
  "activity_type": "FIXED_PRICE",
  "product_level": "PRODUCT",
  "duration_type": "INDEFINITE",
  "begin_time": 1751644800,
  "end_time": 1751731200,
  "participation_limit": [
    {
      "type": "BUYER_NO_LIMIT"
    }
  ],
  "discount": {
    "shipping_discount": {
      "threshold_type": "MINIMAL_ITEM_QUANTITY",
      "threshold_value": "3",
      "type": "DISCOUNT_SHIPPING_FEE",
      "value": "10500",
      "shipping_method": "STANDARD_SHIPPING",
      "inventory_type": "SELF_FULFILLED",
      "area_scope": {
        "type": "WHOLE",
        "specific_areas": ["DKI Jakarta", "Jawa Barat"]
      }
    },
    "bmsm_discount": {
      "details": [
        {
          "tier": 1,
          "threshold_type": "MINIMAL_ITEM_QUANTITY",
          "threshold_value": "5",
          "type": "PERCENTAGE_OFF",
          "value": "10"
        }
      ]
    }
  }
}
```

### Response
#### Success Response (200)
- **code** (int) - Status code indicating success or failure.
- **message** (string) - Message describing the result.
- **request_id** (string) - Unique identifier for tracking the request.
- **data** (object) - Contains specific return information.
  - **activity_id** (string) - Unique ID identifying the promotion activity.
  - **create_time** (int) - Unix timestamp of when the activity was created.
  - **update_time** (int) - Unix timestamp of the last update to the activity.
  - **status** (string) - Current status of the promotion activity (e.g., 'DRAFT', 'ONGOING', 'EXPIRED').

#### Response Example
```json
{
  "code": 0,
  "data": {
    "activity_id": "7136104329798256386",
    "title": "BlackFridayDiscount",
    "update_time": 1661756811
  },
  "message": "Success",
  "request_id": "202203070749000101890810281E8C70B7"
}
```

### Error Handling
All API errors throw `TikTokAPIError`, which contains:
- **message**
- **code**
- **request_id**
```

--------------------------------

### TypeScript: Get Shop SKU Performance List

Source: https://github.com/hsib19/tiktok-shop-sdk/blob/main/apps/docs/core-api/analytics/get-shop-sku-performance-list.md

Demonstrates how to initialize the SDK, set authentication credentials, and call the getShopSKUPerformanceList method with various parameters. Includes error handling for API-specific errors.

```typescript
import { TikTokShopSDK, TikTokAPIError } from 'tiktok-shop-sdk';

const sdk = new TikTokShopSDK({
  appKey: process.env.TIKTOK_APP_KEY!,
  appSecret: process.env.TIKTOK_APP_SECRET!,
});

export async function main() {
  try {
    // Set Access Token
    sdk.setAccessToken(process.env.TIKTOK_APP_ACCESS_KEY!);
    sdk.setShopCipher(process.env.TIKTOK_SHOP_CIPHER!);

    const response = await sdk.analytics.getShopSKUPerformanceList({
      end_date_lt: '2024-09-08',
      start_date_ge: '2024-09-09',
      // currency: "",
      page_size: 20,
      // page_token: "",
      sort_field: 'gmv',
      sort_order: 'ASC',
      product_id: '2034792492342343',
    });

    console.log(response);
  } catch (error) {
    if (error instanceof TikTokAPIError) {
      console.error('TikTok API Error:', error.message);
      console.error('Status Code:', error.code);
      console.log('Request Id: ', error.request_id);
    } else {
      console.error('Unexpected error:', error);
    }
  }
}
```

--------------------------------

### Run Development Server

Source: https://github.com/hsib19/tiktok-shop-sdk/blob/main/apps/landing/README.md

Use these commands to start the development server for your Next.js project. Open http://localhost:3000 in your browser to view the application.

```bash
npm run dev
# or
yarn dev
# or
pnpm dev
# or
bun dev
```

--------------------------------

### Install pnpm

Source: https://github.com/hsib19/tiktok-shop-sdk/blob/main/README.md

Install pnpm globally, which is recommended for managing the monorepo and dependencies within this project.

```bash
npm install -g pnpm
```

--------------------------------

### Run Docs Dev Server

Source: https://github.com/hsib19/tiktok-shop-sdk/blob/main/CLAUDE.md

Starts the VitePress development server for the project documentation.

```bash
pnpm docs:dev
```

--------------------------------

### Warehouse List Response Example

Source: https://github.com/hsib19/tiktok-shop-sdk/blob/main/apps/docs/core-api/logistic/get-warehouse-list.md

An example of the JSON response structure when successfully retrieving a list of warehouses.

```json
{
  "code": 0,
  "data": {
    "warehouses": [
      {
        "warehouse_id": "1234567890",
        "warehouse_name": "Main Warehouse",
        "region": "ID-JK",
        "address": "Jakarta, Indonesia"
      }
    ]
  },
  "message": "Success",
  "request_id": "20240701143000010123456789ABCDEF01"
}
```

--------------------------------

### Create Promotion Activity

Source: https://github.com/hsib19/tiktok-shop-sdk/blob/main/apps/docs/core-api/promotion/create-activity.md

This example demonstrates how to create a promotion activity with specific discount rules, such as fixed price, shipping discounts, and buy-more-save-more (BMSM) offers.

```APIDOC
## POST /promotion/createActivity

### Description
Creates a new promotion activity with specified details, including activity type, duration, and discount rules.

### Method
POST

### Endpoint
/promotion/createActivity

### Request Body
- **title** (string) - Required - The name of the promotion activity.
- **activity_type** (string) - Required - The type of activity (e.g., 'FIXED_PRICE').
- **product_level** (string) - Required - The level at which the promotion applies (e.g., 'PRODUCT').
- **duration_type** (string) - Required - How the duration is defined (e.g., 'INDEFINITE').
- **begin_time** (integer) - Required - Unix timestamp for the start of the activity.
- **end_time** (integer) - Required - Unix timestamp for the end of the activity.
- **participation_limit** (array) - Optional - Limits on participation.
  - **type** (string) - Required - The type of limit (e.g., 'BUYER_NO_LIMIT').
- **discount** (object) - Required - Discount details.
  - **shipping_discount** (object) - Optional - Details for shipping discounts.
    - **threshold_type** (string) - Required - Type of threshold (e.g., 'MINIMAL_ITEM_QUANTITY').
    - **threshold_value** (string) - Required - Value for the threshold.
    - **type** (string) - Required - Type of shipping discount (e.g., 'DISCOUNT_SHIPPING_FEE').
    - **value** (string) - Required - The discount value.
    - **shipping_method** (string) - Required - Applicable shipping method (e.g., 'STANDARD_SHIPPING').
    - **inventory_type** (string) - Required - Inventory type (e.g., 'SELF_FULFILLED').
    - **area_scope** (object) - Required - Geographic scope of the discount.
      - **type** (string) - Required - Scope type (e.g., 'WHOLE').
      - **specific_areas** (array) - Optional - List of specific areas.
  - **bmsm_discount** (object) - Optional - Details for Buy More Save More discounts.
    - **details** (array) - Required - List of discount tiers.
      - **tier** (integer) - Required - The tier number.
      - **threshold_type** (string) - Required - Type of threshold (e.g., 'MINIMAL_ITEM_QUANTITY').
      - **threshold_value** (string) - Required - Value for the threshold.
      - **type** (string) - Required - Type of discount (e.g., 'PERCENTAGE_OFF').
      - **value** (string) - Required - The discount value.

### Request Example
```json
{
  "title": "DiscountEvent07041",
  "activity_type": "FIXED_PRICE",
  "product_level": "PRODUCT",
  "duration_type": "INDEFINITE",
  "begin_time": 1751648400,
  "end_time": 1751734800,
  "participation_limit": [
    {
      "type": "BUYER_NO_LIMIT"
    }
  ],
  "discount": {
    "shipping_discount": {
      "threshold_type": "MINIMAL_ITEM_QUANTITY",
      "threshold_value": "3",
      "type": "DISCOUNT_SHIPPING_FEE",
      "value": "10500",
      "shipping_method": "STANDARD_SHIPPING",
      "inventory_type": "SELF_FULFILLED",
      "area_scope": {
        "type": "WHOLE",
        "specific_areas": ["DKI Jakarta", "Jawa Barat"]
      }
    },
    "bmsm_discount": {
      "details": [
        {
          "tier": 1,
          "threshold_type": "MINIMAL_ITEM_QUANTITY",
          "threshold_value": "5",
          "type": "PERCENTAGE_OFF",
          "value": "10"
        }
      ]
    }
  }
}
```

### Response
#### Success Response (200)
- **code** (int) - Status code indicating success or failure.
- **message** (string) - Message describing the result.
- **request_id** (string) - Unique identifier for tracking the request.
- **data** (object) - Contains specific return information.
  - **activity_id** (string) - Unique ID identifying the promotion activity.
  - **create_time** (int) - Unix timestamp of when the activity was created.
  - **update_time** (int) - Unix timestamp of the last update to the activity.
  - **status** (string) - Current status of the promotion activity (e.g., 'ONGOING', 'DRAFT').

#### Response Example
```json
{
  "code": 0,
  "data": {
    "activity_id": "7136104329798256386",
    "create_time": 1661756811,
    "update_time": 1661756811,
    "status": "ONGOING"
  },
  "message": "Success",
  "request_id": "202203070749000101890810281E8C70B7"
}
```

### Error Handling
All API errors throw `TikTokAPIError`, which contains:
- **message**
- **code**
- **request_id**
```

--------------------------------

### Response Example JSON

Source: https://github.com/hsib19/tiktok-shop-sdk/blob/main/apps/docs/core-api/logistic/get-warehouse-delivery-options.md

This is an example of the JSON response structure when successfully retrieving delivery options for a warehouse.

```json
{
  "code": 0,
  "data": {
    "delivery_options": [
      {
        "delivery_option_id": "123456789",
        "delivery_option_name": "Standard Shipping",
        "carrier": "JNE",
        "estimated_delivery_time": "2-4 days"
      }
    ]
  },
  "message": "Success",
  "request_id": "20240701143000010123456789ABCDEF01"
}
```

--------------------------------

### Uncombine Packages API Response Example

Source: https://github.com/hsib19/tiktok-shop-sdk/blob/main/apps/docs/core-api/fulfilment/uncombine-packages.md

This is an example of a successful response when uncombining packages. It includes the status of each uncombined order.

```json
{
  "code": 0,
  "data": {
    "uncombined_orders": [
      {
        "order_id": "580205195696114469",
        "status": "SUCCESS"
      }
    ]
  },
  "message": "Success",
  "request_id": "20240701150000123456789ABCDEFFF"
}
```

--------------------------------

### Search Returns with TypeScript SDK

Source: https://github.com/hsib19/tiktok-shop-sdk/blob/main/apps/docs/core-api/return-and-refund/search-returns.md

Demonstrates how to initialize the SDK, set access tokens, and call the searchReturn method with query and body parameters. Includes error handling for API-specific errors.

```typescript
import { TikTokShopSDK, TikTokAPIError } from 'tiktok-shop-sdk';

const sdk = new TikTokShopSDK({
  appKey: process.env.TIKTOK_APP_KEY!,
  appSecret: process.env.TIKTOK_APP_SECRET!,
});

try {
  // Set Access Token
  sdk.setAccessToken(process.env.TIKTOK_APP_ACCESS_KEY!);
  sdk.setShopCipher(process.env.TIKTOK_SHOP_CIPHER!);

  const response = await sdk.return_refund.searchReturn({
    query: {
      page_size: 10,
    },
    body: {
      return_types: ['RETURN_AND_REFUND'],
    },
  });

  console.log(JSON.stringify(response));
} catch (error) {
  if (error instanceof TikTokAPIError) {
    console.error('TikTok API Error:', error.message);
    console.error('Status Code:', error.code);
    console.log('Request Id: ', error.request_id);
  } else {
    console.error('Unexpected error:', error);
  }
}
```

--------------------------------

### Shop Performance Response Example

Source: https://github.com/hsib19/tiktok-shop-sdk/blob/main/apps/docs/core-api/analytics/get-shop-performance.md

An example of the JSON response structure for the getShopPerformance API call, detailing the metrics returned.

```json
{
  "code": 0,
  "data": {
    "gmv": 12500.45,
    "orders": 320,
    "refund_rate": 0.012,
    "visitor_count": 15000,
    "conversion_rate": 0.021
  },
  "message": "Success",
  "request_id": "202407021200000122334455AAFFEE"
}
```

--------------------------------

### Split Order Example in TypeScript

Source: https://github.com/hsib19/tiktok-shop-sdk/blob/main/apps/docs/core-api/fulfilment/split-orders.md

Demonstrates how to initialize the SDK, set authentication credentials, and call the `splitOrders` method with order details and splittable groups. Includes error handling for API-specific errors.

```typescript
import { TikTokShopSDK, TikTokAPIError } from 'tiktok-shop-sdk';

const sdk = new TikTokShopSDK({
  appKey: process.env.TIKTOK_APP_KEY!,
  appSecret: process.env.TIKTOK_APP_SECRET!,
});

try {
  // Set Access Token & Shop Cipher
  sdk.setAccessToken(process.env.TIKTOK_APP_ACCESS_KEY!)
  sdk.setShopCipher(process.env.TIKTOK_SHOP_CIPHER!)

  const response = await sdk.fulfillment.splitOrders({
    order_id: '580196086824799013',
    body: {
      splittable_groups: [
        {
          id: '123',
          order_line_item_ids: ['580196086825061157'],
        },
      ],
    },
  });

  console.log(response);
} catch (error) {
  if (error instanceof TikTokAPIError) {
    console.error('TikTok API Error:', error.message);
    console.error('Status Code:', error.code);
    console.log('Request Id:', error.request_id);
  } else {
    console.error('Unexpected error:', error);
  }
}
```

--------------------------------

### Deactivate Activity Response Example

Source: https://github.com/hsib19/tiktok-shop-sdk/blob/main/apps/docs/core-api/promotion/deactivate-activity.md

This is an example of a successful response when deactivating an activity. It includes the activity ID and the timestamp of the last update.

```json
{
  "code": 0,
  "data": {
    "activity_id": "7523240167205979921",
    "update_time": 1709270400
  },
  "message": "Success",
  "request_id": "202402291200000101890810281AEC88FF"
}
```

--------------------------------

### Coupon API Response Example

Source: https://github.com/hsib19/tiktok-shop-sdk/blob/main/apps/docs/core-api/promotion/get-coupon.md

This is an example of a successful response when retrieving coupon details. It includes status, timestamps, and coupon-specific data.

```json
{
  "code": 0,
  "message": "Success",
  "request_id": "202402291200000101890810281AEC88FF",
  "data": {
    "coupon_id": "7136104329798256386",
    "title": "Holiday Special Coupon",
    "status": "ONGOING",
    "create_time": 1709270400,
    "update_time": 1709270500
  }
}
```

--------------------------------

### Get Shop Performance with TypeScript SDK

Source: https://github.com/hsib19/tiktok-shop-sdk/blob/main/apps/docs/core-api/analytics/get-shop-performance.md

Demonstrates how to initialize the SDK, set access tokens and shop cipher, and call the getShopPerformance method. Includes error handling for API-specific errors and unexpected issues.

```typescript
import { TikTokShopSDK, TikTokAPIError } from 'tiktok-shop-sdk';

const sdk = new TikTokShopSDK({
  appKey: process.env.TIKTOK_APP_KEY!,
  appSecret: process.env.TIKTOK_APP_SECRET!,
});

try {
  // Set Access Token
  sdk.setAccessToken(process.env.TIKTOK_APP_ACCESS_KEY!)
  sdk.setShopCipher(process.env.TIKTOK_SHOP_CIPHER!)

  const response = await sdk.analytics.getShopPerformance({
    end_date_lt: '2024-09-08',
    start_date_ge: '2024-09-09',
  });

  console.log(response);
} catch (error) {
  if (error instanceof TikTokAPIError) {
    console.error('TikTok API Error:', error.message);
    console.error('Status Code:', error.code);
    console.log('Request Id: ', error.request_id);
  } else {
    console.error('Unexpected error:', error);
  }
}
```

--------------------------------

### Get Warehouse List using TypeScript SDK

Source: https://github.com/hsib19/tiktok-shop-sdk/blob/main/apps/docs/core-api/logistic/get-warehouse-list.md

Demonstrates how to initialize the SDK, set authentication credentials, and call the `getWarehouseList` method. Includes error handling for API-specific errors.

```typescript
import { TikTokShopSDK, TikTokAPIError } from 'tiktok-shop-sdk';

const sdk = new TikTokShopSDK({
  appKey: process.env.TIKTOK_APP_KEY!,
  appSecret: process.env.TIKTOK_APP_SECRET!,
});

try {
  // Set Access Token & Shop Cipher
  sdk.setAccessToken(process.env.TIKTOK_APP_ACCESS_KEY!)
  sdk.setShopCipher(process.env.TIKTOK_SHOP_CIPHER!)

  const response = await sdk.logistic.getWarehouseList();

  console.log(response);
} catch (error) {
  if (error instanceof TikTokAPIError) {
    console.error('TikTok API Error:', error.message);
    console.error('Status Code:', error.code);
    console.log('Request Id:', error.request_id);
  } else {
    console.error('Unexpected error:', error);
  }
}
```