PHPackages                             laraditz/tiktok - PHPackages - PHPackages  [Skip to content](#main-content)[PHPackages](/)[Directory](/)[Categories](/categories)[Trending](/trending)[Leaderboard](/leaderboard)[Changelog](/changelog)[Analyze](/analyze)[Collections](/collections)[Log in](/login)[Sign up](/register)

1. [Directory](/)
2. /
3. [API Development](/categories/api)
4. /
5. laraditz/tiktok

ActiveLibrary[API Development](/categories/api)

laraditz/tiktok
===============

Laravel package for interacting with TikTok API.

1.1.3(1mo ago)14173MITPHPPHP ^8.2

Since Sep 20Pushed 7mo ago1 watchersCompare

[ Source](https://github.com/laraditz/tiktok)[ Packagist](https://packagist.org/packages/laraditz/tiktok)[ Docs](https://github.com/laraditz/tiktok)[ Fund](https://www.buymeacoffee.com/raditzfarhan)[ GitHub Sponsors](https://github.com/raditzfarhan)[ RSS](/packages/laraditz-tiktok/feed)WikiDiscussions main Synced 1mo ago

READMEChangelogDependencies (6)Versions (11)Used By (0)

Laravel TikTok
==============

[](#laravel-tiktok)

[![Latest Version on Packagist](https://camo.githubusercontent.com/cb2e3532e9e94b7b804666c46a336634717b45cfc7cfa20dc23aadcc78c62460/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f762f6c6172616469747a2f74696b746f6b2e7376673f7374796c653d666c61742d737175617265)](https://packagist.org/packages/laraditz/tiktok)[![Total Downloads](https://camo.githubusercontent.com/bee16a89edea35249a97a91e568d20e6d9262e255556a43a64f3534dc0035883/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f64742f6c6172616469747a2f74696b746f6b2e7376673f7374796c653d666c61742d737175617265)](https://packagist.org/packages/laraditz/tiktok)[![License](https://camo.githubusercontent.com/7051e31f5144cbae48b37d20536b4c05a5325ac8dbd9c3e69e83fcbb3e1b3083/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f6c2f6c6172616469747a2f74696b746f6b3f7374796c653d666c61742d737175617265)](./LICENSE.md)[![GitHub Actions](https://github.com/laraditz/tiktok/actions/workflows/main.yml/badge.svg)](https://github.com/laraditz/tiktok/actions/workflows/main.yml/badge.svg)

A comprehensive Laravel package for seamless integration with the TikTok Shop API. This package provides a clean, intuitive interface for managing TikTok shops, handling authentication, processing orders, managing products, and receiving webhooks.

[![Buy Me A Coffee](https://camo.githubusercontent.com/0cf29a542375e1a46e84d8bf5805a4e5c0a6ee98b6547ccdc0c55eed49d99c69/68747470733a2f2f63646e2e6275796d6561636f666665652e636f6d2f627574746f6e732f76322f64656661756c742d79656c6c6f772e706e67)](https://www.buymeacoffee.com/raditzfarhan)

⚠️ Breaking Changes in v1.1.0
-----------------------------

[](#️-breaking-changes-in-v110)

**IMPORTANT:** If you're upgrading from v1.0.4 or below, please note the following breaking changes:

- **Database Schema Changes**: The `tiktok_shops` table structure has been updated:
    - The `id` column now serves as the TikTok shop ID (unique identifier)
    - The `identifier` column has been removed as it's no longer used
- **Re-authorization Required**: Due to these database changes, **you will need to re-authorize all your TikTok shops** after upgrading to v1.1.0
- **Migration Impact**: Run the new migrations and ensure your existing shop data is properly migrated before re-authorizing

Please backup your database before upgrading and plan for shop re-authorization in your deployment process.

Features
--------

[](#features)

- 🔐 **Complete Authentication Flow** - Automatic token management with refresh capabilities
- 🏪 **Multi-Shop Support** - Manage multiple TikTok shops within a single application
- 📦 **Product Management** - Full CRUD operations for TikTok Shop products
- 🛒 **Order Processing** - Comprehensive order management and tracking
- 🔄 **Return Handling** - Complete return and refund management
- 📡 **Webhook Integration** - Real-time event handling with built-in webhook endpoints
- 🗄️ **Database Logging** - Automatic request logging for debugging and monitoring
- 🔄 **Auto Token Refresh** - Background token refresh to maintain API connectivity

Requirements
------------

[](#requirements)

- PHP 8.2 and above.
- Laravel 10 and above.

Installation
------------

[](#installation)

You can install the package via composer:

```
composer require laraditz/tiktok
```

Quick Start
-----------

[](#quick-start)

### 1. TikTok Shop App Setup

[](#1-tiktok-shop-app-setup)

Before using this package, you need to create a TikTok Shop app:

1. Visit [TikTok Shop Partner Center](https://partner.tiktokshop.com/)
2. Create a new app or use an existing one
3. Note your `App Key` and `App Secret`
4. Configure the redirect URL: `https://your-app-url.com/tiktok/seller/authorized`

### 2. Environment Configuration

[](#2-environment-configuration)

Add your TikTok Shop credentials to your `.env` file:

```
TIKTOK_APP_KEY=your_app_key_here
TIKTOK_APP_SECRET=your_app_secret_here
TIKTOK_SHOP_ID=your_shop_id_here          # Optional: Default shop ID
TIKTOK_SHOP_CODE=your_shop_code_here      # Optional: Default shop code
TIKTOK_SHOP_NAME=your_shop_name_here      # Optional: Default shop name
```

### 3. Publish Migration

[](#3-publish-migration)

You can publish the migration file via this command:

```
php artisan vendor:publish --provider="Laraditz\TikTok\TikTokServiceProvider" --tag="migrations"
```

### 4. Run Migration

[](#4-run-migration)

Run the migration command to create the necessary database tables:

```
php artisan migrate
```

This creates tables for shops, access tokens, requests, webhooks, orders, and returns.

### 5. Configuration (Optional)

[](#5-configuration-optional)

Publish the configuration file if you need to customize settings:

```
php artisan vendor:publish --provider="Laraditz\TikTok\TikTokServiceProvider" --tag="config"
```

### 6. Authorization Flow

[](#6-authorization-flow)

To authorize a TikTok shop with your app:

1. **In Partner Center**, go to `App & Service` and select your app. On the right side, you can find `Authorization` section with `Copy authorization link` button. Copy the URL and paste it into your browser address. The URL look like this:

```
 https://services.tiktokshop.com/open/authorize?service_id=720850956892765XXXXX

```

2. **Login using the seller account** that you want to authorized to be use for the app.
3. **TikTok redirects back** to `https://your-app-url.com/tiktok/seller/authorized`
4. **Package automatically handles** the authorization code exchange and token storage
5. **Shop is now ready** for API calls

Available Methods
-----------------

[](#available-methods)

Here’s the full list of methods available in this package. Each method uses the same parameters defined in the [TikTok Shop API Documentation](https://partner.tiktokshop.com/docv2/page/6789f6f818828103147a8b05). You don’t need to worry about adding common parameters like `app_key`, `sign`, `timestamp`, or `shop_cipher` because they’ll be automatically included whenever required.

### Authentication Service `auth()`

[](#authentication-service-auth)

MethodDescriptionParameters`accessToken()`Generate access token from authorization codequery: `app_key`, `app_secret`, `auth_code`, `grant_type``refreshAccessToken()`Refresh access token before it expired.TiktokAccessToken `tiktokAccessToken`### Authorization Service `authorization()`

[](#authorization-service-authorization)

MethodDescription`shops()`Retrieves the list of shops that a seller has authorized for an app.### Event Service `event()`

[](#event-service-event)

MethodDescriptionParameters`webhookList()`Retrieves a shop's webhooks and the corresponding webhook URLs.`updateWebhook()`Updates the shop's webhook URL for a specific event topic.body: `event_type`, `address``deleteWebhook()`Deletes the shop's webhook URL for a specific event topic.body: `event_type`### Seller Service `seller()`

[](#seller-service-seller)

MethodDescription`shops()`Retrieves all active shops that belong to a seller.### Order Service `order()`

[](#order-service-order)

Full parameters refer to [API documentation](https://partner.tiktokshop.com/docv2/page/order-api-overview)

MethodDescriptionParameters`list()`Returns a list of orders created or updated during the timeframe indicated by the specified parameters.query: `page_size` and morebody: `order_status` and more`detail()`Get the detailed order information of an order.query: `ids``priceDetail()`Get the detailed pricing calculation information of an order or a line item, including vouchers, tax, etc.params: `order_id`### Product Service `product()`

[](#product-service-product)

Full parameters refer to [API documentation](https://partner.tiktokshop.com/docv2/page/products-api-overview)

MethodDescriptionParameters`list()`Retrieve a list of products that meet the specified conditions.query: `page_size`, `page_token`body: `status`, `update_time_ge` and more`get()`Retrieve all properties of a product that is in the DRAFT, PENDING, or ACTIVATE status.params: `product_id``updateInventory()`Retrieve all properties of a product that is in the DRAFT, PENDING, or ACTIVATE status.params: `product_id`body: `skus`### Return Service `return()`

[](#return-service-return)

Full parameters refer to [API documentation](https://partner.tiktokshop.com/docv2/page/return-refund-and-cancel-api-overview)

MethodDescriptionParameters`list()`Use this API to retrieve one or more returns.query: `page_size`, `page_token` and more`get()`Use this API to get a list of return records.params: `return_id`Usage Examples
--------------

[](#usage-examples)

### Basic Usage

[](#basic-usage)

```
use Laraditz\TikTok\Facades\TikTok;

// Using facade (recommended)
$shops = TikTok::seller()->shops();

// Using service container
$seller = app('tiktok')->seller()->shops();
```

### Working with Products

[](#working-with-products)

```
// Get all products
$products = TikTok::product()->list(
    query: [
        'page_size' => 20
    ],
    body: [
        'status' => 'ALL',
        'update_time_ge' => 1758211200  // Unix timestamp
    ]
);

// Get specific product
$product = TikTok::product()->get(
    params: [
        'product_id' => 'your_product_id'
    ]
);

// Update SKU quantity of a product
$updateInventory = TikTok::product()->updateInventory(
    params: [
        'product_id' => 'your_product_id'
    ],
    body: [
        'skus' => [
            [
                'id' => 'your_product_sku_id',
                'inventory' => [
                    [
                        'warehouse_id' => 'your_warehouse_id',
                        'quantity' => 17,
                    ]
                ]
            ]
        ]
    ],
);
```

### Order Management

[](#order-management)

```
// Search orders
$orders = TikTok::order()->list(
    query: [
        'page_size' => 50
    ],
    body: [
        'order_status' => 'UNPAID',
        'create_time_ge' => 1758211200,
        'create_time_lt' => 1758297600
    ]
);

// Get order details
$orderDetails = TikTok::order()->detail(
    query: [
        'ids' => 'order_id_1,order_id_2'
    ]
);

// Get order pricing details
$pricing = TikTok::order()->priceDetail(
    params: [
        'order_id' => 'your_order_id'
    ]
);
```

### Return Order

[](#return-order)

```
// Get returns
$returns = TikTok::return()->list(
    query: [
        'page_size' => 20
    ],
    body: [
        'create_time_ge' => 1758211200
    ]
);

// Get specific return records
$returnRecords = TikTok::return()->get(
    params: [
        'return_id' => '168129934203XXXX' // A unique identifier for a TikTok Shop return request.
    ]
);
```

### Multi-Shop Support

[](#multi-shop-support)

By default, the package uses `TIKTOK_SHOP_ID` from your `.env` file. For multi-shop applications, specify the shop ID per request:

```
// Method 1: Using make() with shop_id
$products = TikTok::make(shop_id: '7010123456556XXXXXX')
    ->product()
    ->list(
        query: ['page_size' => 10],
        body: ['status' => 'ACTIVATE']
    );

// Method 2: Using shopId() method
$orders = TikTok::shopId('7010123456556XXXXXX')
    ->order()
    ->list(
        query: ['page_size' => 50],
        body: ['order_status' => 'UNPAID', 'create_time_ge' => 1758211200]
    );

// You also can set shop context and reuse
$tiktok = TikTok::make(shop_id: '7010123456556XXXXXX');
$products = $tiktok->product()->list(/* ... */);
$orders = $tiktok->order()->list(/* ... */);
```

### Error Handling

[](#error-handling)

```
use Laraditz\TikTok\Exceptions\TikTokAPIError;

try {
    $products = TikTok::product()->list(
        query: ['page_size' => 10],
        body: ['status' => 'ALL']
    );

    // Handle successful response
    $data = $products['data'];

} catch (TikTokAPIError $e) {
    // Handle API errors
    $errorCode = $e->getCode();
    $errorMessage = $e->getMessage();
    $errorData = $e->getData();

    logger()->error('TikTok API Error', [
        'code' => $errorCode,
        'message' => $errorMessage,
        'data' => $errorData
    ]);
}
```

Events & Webhooks
---------------------

[](#events--webhooks)

### Available Events

[](#available-events)

This package provides events that you can listen to in your application:

EventDescription`Laraditz\TikTok\Events\WebhookReceived`Triggered when TikTok sends webhook data`Laraditz\TikTok\Events\TikTokRequestFailed`Triggered when API request fails### Creating Event Listeners

[](#creating-event-listeners)

Create listeners for these events in your application:

```
// app/Listeners/TikTokWebhookListener.php