Laravel TikTok Ads

https://github.com/jeffersongoncalves/laravel-tiktok-ads
Admin
Laravel TikTok Ads provides a Laravel integration for the TikTok Ads (TikTok Business) API to manage...
Tokens:20,265
Snippets:148
Trust Score:9.8
License:MIT
Update:3 days ago
Show doc for...
Tokens:
Raw
### Basic report with defaults

Source: https://github.com/jeffersongoncalves/laravel-tiktok-ads

Example of calling report() with only start and end dates, using all default parameters. Checks the response code for success and retrieves rows from data.list.

```php
use JeffersonGoncalves\TiktokAds\Facades\TiktokAds;

$response = TiktokAds::report('2026-01-01', '2026-01-31');

if ($response->json('code') === 0) {
    $rows = $response->json('data.list');
}
```

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

### Run tests

Source: https://github.com/jeffersongoncalves/laravel-tiktok-ads/blob/main/README.md

Execute the package test suite using Composer.

```bash
composer test
```

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

### get() protected method

Source: https://github.com/jeffersongoncalves/laravel-tiktok-ads

Protected method that performs a GET request on the given path with optional query parameters. The query array is documented as a string-keyed map of mixed values.

```php
/**
 * @param  array<string, mixed>  $query
 */
protected function get(string $path, array $query = []): Response
{
    return $this->client()->get($path, $query);
}
```

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

### Accessing the underlying instance

Source: https://github.com/jeffersongoncalves/laravel-tiktok-ads

Shows how to get the container singleton instance behind the facade using getFacadeRoot(), a method inherited from Illuminate\Support\Facades\Facade.

```php
$instance = TiktokAds::getFacadeRoot(); // the container singleton TiktokAds
```

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

### Install package via Composer

Source: https://github.com/jeffersongoncalves/laravel-tiktok-ads/blob/main/README.md

Install the Laravel TikTok Ads package using Composer.

```bash
composer require jeffersongoncalves/laravel-tiktok-ads
```

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

### Custom dimensions and metrics

Source: https://github.com/jeffersongoncalves/laravel-tiktok-ads

Example of calling report() with custom dimensions, metrics, data level, and report type using named arguments.

```php
$response = TiktokAds::report(
    startDate: '2026-01-01',
    endDate: '2026-01-31',
    dimensions: ['campaign_id', 'stat_time_day'],
    metrics: ['spend', 'impressions', 'clicks', 'conversion'],
    dataLevel: 'AUCTION_CAMPAIGN',
    reportType: 'BASIC',
);
```

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

### audiences() usage example

Source: https://github.com/jeffersongoncalves/laravel-tiktok-ads

Example of calling the audiences() method via the TiktokAds facade and retrieving the audience list from the response's data.list key, defaulting to an empty array if not present.

```php
use JeffersonGoncalves\TiktokAds\Facades\TiktokAds;

$audiences = TiktokAds::audiences()->json('data.list', []);
```

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

### Basic usage with facade

Source: https://github.com/jeffersongoncalves/laravel-tiktok-ads/blob/main/README.md

Use the TiktokAds facade to interact with the TikTok Ads API. Methods include advertiserInfo, campaigns, createCampaign, updateCampaignStatus, adGroups, report, and audiences. Each method returns an Illuminate\Http\Client\Response.

```php
use JeffersonGoncalves\TiktokAds\Facades\TiktokAds;

TiktokAds::advertiserInfo(); // uses TIKTOK_ADVERTISER_ID by default
TiktokAds::advertiserInfo('7000000000000000000'); // or pass an advertiser id explicitly

TiktokAds::campaigns();
TiktokAds::campaigns(page: 2, pageSize: 50);

TiktokAds::createCampaign(name: 'My Campaign', objective: 'TRAFFIC', budgetMode: 'BUDGET_MODE_DAY', budget: 50.0);

TiktokAds::updateCampaignStatus(campaignIds: ['1790000000000000000'], status: 'DISABLE');

TiktokAds::adGroups();
TiktokAds::adGroups(campaignId: '1790000000000000000');

TiktokAds::report(
    startDate: '2026-01-01',
    endDate: '2026-01-31',
    dimensions: ['campaign_id'],
    metrics: ['spend', 'impressions', 'clicks', 'conversion'],
    dataLevel: 'AUCTION_CAMPAIGN',
);

TiktokAds::audiences();
```

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

### Set credentials in .env

Source: https://github.com/jeffersongoncalves/laravel-tiktok-ads/blob/main/README.md

Define the required environment variables for the TikTok Ads API: access token, advertiser ID, and API version.

```env
TIKTOK_ACCESS_TOKEN=
TIKTOK_ADVERTISER_ID=
TIKTOK_ADS_API_VERSION=v1.3
```

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

### GET /campaign/get/

Source: https://github.com/jeffersongoncalves/laravel-tiktok-ads

Retrieves a paginated list of campaigns for the specified advertiser. Supports pagination via page and page_size parameters.

```APIDOC
## GET /campaign/get/

### Description
Retrieves a paginated list of campaigns for the specified advertiser.

### Method
GET

### Endpoint
/campaign/get/

### Parameters
#### Query Parameters
- **advertiser_id** (string) - Required - Resolved advertiser ID.
- **page** (int) - Required - Page number, default `1`.
- **page_size** (int) - Required - Page size, default `20`.

### Response
#### Success Response (200)
- **data.list** (array) - Array of campaign records (e.g. `campaign_id`, `campaign_name`).

```

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

### updateCampaignStatus() usage example

Source: https://github.com/jeffersongoncalves/laravel-tiktok-ads

Shows how to call updateCampaignStatus using the TiktokAds facade, disabling two campaigns. The response is a Laravel HTTP client Response; calling throw() will throw on an HTTP error status.

```php
use JeffersonGoncalves\TiktokAds\Facades\TiktokAds;

$response = TiktokAds::updateCampaignStatus(
    campaignIds: ['1790000000000000000', '1790000000000000001'],
    status: 'DISABLE',
);

$response->throw(); // Laravel HTTP client: throws on HTTP error status

```

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

### Resolve client from container

Source: https://github.com/jeffersongoncalves/laravel-tiktok-ads/blob/main/README.md

Instead of using the facade, you can resolve the TiktokAds class from the Laravel service container and call methods directly.

```php
app(JeffersonGoncalves\TiktokAds\TiktokAds::class)->campaigns();
```

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

### adGroups() usage example

Source: https://github.com/jeffersongoncalves/laravel-tiktok-ads

Shows two calls to adGroups: one without a campaign filter and one with a specific campaign ID. The second call sends campaign_ids as a JSON-encoded array in the query string.

```php
use JeffersonGoncalves\TiktokAds\Facades\TiktokAds;

$all = TiktokAds::adGroups();                       // no campaign filter
$byCampaign = TiktokAds::adGroups('1790000000000000000'); // ?campaign_ids=["1790000000000000000"]

```

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

### GET /advertiser/info/

Source: https://github.com/jeffersongoncalves/laravel-tiktok-ads

Retrieves advertiser information for the specified advertiser IDs. The advertiser_ids parameter must be a JSON-encoded single-element array.

```APIDOC
## GET /advertiser/info/

### Description
Retrieves advertiser information for the specified advertiser IDs.

### Method
GET

### Endpoint
/advertiser/info/

### Parameters
#### Query Parameters
- **advertiser_ids** (string) - Required - A JSON-encoded single-element array, e.g. `["123"]`.

### Response
#### Success Response (200)
- **data.list** (array) - Array of advertiser records, each with `advertiser_id`.

```

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

### GET /adgroup/get/

Source: https://github.com/jeffersongoncalves/laravel-tiktok-ads

Retrieves a list of ad groups for a given advertiser. The client method is TiktokAds::adGroups().

```APIDOC
## [GET] /adgroup/get/

### Description
Retrieves a list of ad groups for a given advertiser. The client method is `TiktokAds::adGroups()`.

### Method
GET

### Endpoint
/adgroup/get/

### Parameters
#### Query Parameters
- **advertiser_id** (string) - Required - Resolved advertiser ID.
- **campaign_ids** (string) - Optional - Omitted when `$campaignId` is `null`; otherwise `json_encode([$campaignId])`, e.g. `["789"]`.

### Response
#### Success Response (200)
- **data.list** (array) - Array of ad group records.
```

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

### Handle API errors

Source: https://github.com/jeffersongoncalves/laravel-tiktok-ads/blob/main/README.md

Check the 'code' field in the response payload because the TikTok Business API returns HTTP 200 even on failure. Use the response's json method to inspect the code and message.

```php
$response = TiktokAds::campaigns();

if ($response->json('code') !== 0) {
    report(new RuntimeException($response->json('message')));
}
```

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

### GET /dmp/custom_audience/list/

Source: https://github.com/jeffersongoncalves/laravel-tiktok-ads

Retrieves a list of custom audiences for a given advertiser. The advertiser ID is resolved automatically by the client, but can be overridden via the query parameter.

```APIDOC
## [GET] /dmp/custom_audience/list/

### Description
Retrieves a list of custom audiences for the resolved advertiser ID.

### Method
GET

### Endpoint
/dmp/custom_audience/list/

### Parameters
#### Query Parameters
- **advertiser_id** (string) - Required - Resolved advertiser ID.

### Response
#### Success Response (200)
- **data.list** (array) - Array of custom audience records.
```

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

### Named arguments with createCampaign

Source: https://github.com/jeffersongoncalves/laravel-tiktok-ads

Shows how to pass named arguments to the facade method, which work exactly as on the underlying class.

```php
$response = TiktokAds::createCampaign(name: 'My Campaign', objective: 'TRAFFIC');
```

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

### Resolution paths for the singleton

Source: https://github.com/jeffersongoncalves/laravel-tiktok-ads

Three equivalent ways to resolve the same singleton instance from the Laravel container: via the class name, the string alias, or the facade root.

```php
app(JeffersonGoncalves\TiktokAds\TiktokAds::class);
app('laravel-tiktok-ads');
\JeffersonGoncalves\TiktokAds\Facades\TiktokAds::getFacadeRoot();
```

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

### configurePackage() method

Source: https://github.com/jeffersongoncalves/laravel-tiktok-ads

The configurePackage method sets the package name to 'laravel-tiktok-ads' and declares a config file with the same name, published via vendor:publish with tag 'laravel-tiktok-ads-config'.

```php
public function configurePackage(Package $package): void
{
    $package
        ->name('laravel-tiktok-ads')
        ->hasConfigFile('laravel-tiktok-ads');
}
```

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

### Basic createCampaign call with explicit budget

Source: https://github.com/jeffersongoncalves/laravel-tiktok-ads

Creates a campaign with an explicit budget of 50.0 and checks the response code to retrieve the campaign ID from data.campaign_id.

```php
use JeffersonGoncalves\TiktokAds\Facades\TiktokAds;

$response = TiktokAds::createCampaign('My Campaign', 'TRAFFIC', 'BUDGET_MODE_DAY', 50.0);

if ($response->json('code') === 0) {
    $campaignId = $response->json('data.campaign_id');
}
```

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

### TiktokAds::createCampaign()

Source: https://github.com/jeffersongoncalves/laravel-tiktok-ads

Creates a new campaign with the specified name, objective, and budget settings. The budget mode and budget amount can be customized.

```APIDOC
## TiktokAds::createCampaign()

### Description
Creates a new campaign with the specified name, objective, and budget settings. The budget mode and budget amount can be customized.

### Method
Static call on the TiktokAds facade

### Endpoint
`TiktokAds::createCampaign(string $name, string $objective, string $budgetMode = 'BUDGET_MODE_DAY', ?float $budget = null, ?string $advertiserId = null): Response`

### Parameters
#### Parameters
- **name** (string) - Required - The name of the campaign.
- **objective** (string) - Required - The campaign objective.
- **budgetMode** (string) - Optional - Budget mode. Defaults to 'BUDGET_MODE_DAY'.
- **budget** (?float) - Optional - Budget amount. If null, no budget is set.
- **advertiserId** (?string) - Optional - The advertiser ID. If null, it will be resolved automatically.

### Response
Returns `Illuminate\Http\Client\Response`.

### Exceptions
Throws `InvalidArgumentException` when no advertiser ID can be resolved.
```

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

### report()

Source: https://github.com/jeffersongoncalves/laravel-tiktok-ads

Runs an integrated report. POSTed as JSON with fields: advertiser_id, report_type, dimensions, metrics, data_level, start_date, end_date.

```APIDOC
## report()

### Description
Runs an integrated report. POSTed as JSON with fields: `advertiser_id`, `report_type`, `dimensions`, `metrics`, `data_level`, `start_date`, `end_date`.

### Method
POST

### Endpoint
Not specified in source.

### Parameters
#### Path Parameters
None.

#### Query Parameters
None.

#### Request Body
- **advertiser_id** (string) - Optional - Explicit advertiser ID; falls back to the configured `advertiser_id`.
- **report_type** (string) - Optional - Report type (default: `'BASIC'`).
- **dimensions** (array<int, string>) - Optional - Report dimensions (default: `['campaign_id']`).
- **metrics** (array<int, string>) - Optional - Report metrics (default: `['spend', 'impressions', 'clicks', 'conversion']`).
- **data_level** (string) - Optional - Data level (default: `'AUCTION_CAMPAIGN'`).
- **start_date** (string) - Required - Report start date, e.g. `'2026-01-01'`.
- **end_date** (string) - Required - Report end date, e.g. `'2026-01-31'`.

### Response
#### Success Response (200)
- **data.list** (array) - Report rows on success.

### Request Example
```php
use JeffersonGoncalves\TiktokAds\Facades\TiktokAds;

$response = TiktokAds::report('2026-01-01', '2026-01-31');

if ($response->json('code') === 0) {
    $rows = $response->json('data.list');
}
```

### Response Example
Not provided in source.

### Throws
- **InvalidArgumentException** - No advertiser ID available (per `resolveAdvertiserId()`).
```

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

### createCampaign() method signature

Source: https://github.com/jeffersongoncalves/laravel-tiktok-ads

Defines the createCampaign method with parameters for campaign name, objective, budget mode, budget, and advertiser ID. The budget is omitted from the payload when null.

```php
public function createCampaign(
    string $name,
    string $objective,
    string $budgetMode = 'BUDGET_MODE_DAY',
    ?float $budget = null,
    ?string $advertiserId = null,
): Response
```

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

### createCampaign with budget omitted

Source: https://github.com/jeffersongoncalves/laravel-tiktok-ads

Creates a campaign using only the required name and objective parameters. The null budget is filtered out, so the payload contains no 'budget' key.

```php
$response = TiktokAds::createCampaign(
    name: 'My Campaign',
    objective: 'TRAFFIC',
);
// payload contains campaign_name, objective_type, budget_mode = 'BUDGET_MODE_DAY'
// but NO 'budget' key — the null budget was filtered out
```

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

### Constructor

Source: https://github.com/jeffersongoncalves/laravel-tiktok-ads

Creates a new TiktokAds HTTP client instance. The constructor is normally invoked by the service provider singleton with values from the configuration, but can be called directly with an access token, advertiser ID, and API version.

```APIDOC
## Constructor

### Description
Creates a new TiktokAds HTTP client instance.

### Method
Constructor

### Signature
```php
public function __construct(
    protected ?string $accessToken,
    protected ?string $advertiserId,
    protected string $apiVersion,
) {}
```

### Parameters
- **$accessToken** (?string) - Required - TikTok Business API access token. Sent as the `Access-Token` header on every request.
- **$advertiserId** (?string) - Required - Default advertiser ID used by every method when no explicit ID is passed.
- **$apiVersion** (string) - Required - API version segment inserted into the base URL: `https://business-api.tiktok.com/open_api/{$apiVersion}`. Configured default is `v1.3`.

### Return type
None (constructor). The three promoted properties are `protected`, so they are not accessible from consuming code.

### Example
```php
new TiktokAds(
    config('laravel-tiktok-ads.access_token'),
    config('laravel-tiktok-ads.advertiser_id'),
    config('laravel-tiktok-ads.api_version'),
);
```
```

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

### POST /campaign/create/

Source: https://github.com/jeffersongoncalves/laravel-tiktok-ads

Creates a new campaign for the specified advertiser. The budget field is optional and only sent when non-null.

```APIDOC
## POST /campaign/create/

### Description
Creates a new campaign for the specified advertiser.

### Method
POST

### Endpoint
/campaign/create/

### Parameters
#### Request Body
- **advertiser_id** (string) - Required - Resolved advertiser ID.
- **campaign_name** (string) - Required - The campaign name.
- **objective_type** (string) - Required - The campaign objective (e.g. `TRAFFIC`).
- **budget_mode** (string) - Required - Default `BUDGET_MODE_DAY`.
- **budget** (float) - Optional - Only sent when non-null.

### Response
#### Success Response (200)
- **data.campaign_id** (string) - The created campaign's ID.

```

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

### Basic advertiserInfo() call using configured advertiser ID

Source: https://github.com/jeffersongoncalves/laravel-tiktok-ads

Calls advertiserInfo() without arguments to use the configured advertiser_id. Checks response code 0 and accesses advertiser records via data.list, otherwise reports the error message.

```php
use JeffersonGoncalves\TiktokAds\Facades\TiktokAds;

$response = TiktokAds::advertiserInfo();

if ($response->json('code') === 0) {
    $advertisers = $response->json('data.list'); // e.g. [['advertiser_id' => '123']]
} else {
    report(new RuntimeException($response->json('message')));
}
```

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

### createCampaign()

Source: https://github.com/jeffersongoncalves/laravel-tiktok-ads

Creates a TikTok Ads campaign by POSTing campaign details as JSON. Returns an Illuminate HTTP Client Response containing the created campaign ID on success.

```APIDOC
## createCampaign()

### Description
Creates a TikTok Ads campaign by POSTing campaign details as JSON. Returns an Illuminate HTTP Client Response containing the created campaign ID on success.

### Method
POST

### Endpoint
Not specified in source

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
- **advertiser_id** (string) - Required - Advertiser ID (falls back to configured value when not provided)
- **campaign_name** (string) - Required - Campaign name
- **objective_type** (string) - Required - Campaign objective (e.g., TRAFFIC)
- **budget_mode** (string) - Optional - Budget mode (default: BUDGET_MODE_DAY)
- **budget** (float) - Optional - Campaign budget (omitted when null)

### Response
#### Success Response (200)
- **data.campaign_id** (string) - Created campaign ID

### Request Example
```php
use JeffersonGoncalves\TiktokAds\Facades\TiktokAds;

$response = TiktokAds::createCampaign('My Campaign', 'TRAFFIC', 'BUDGET_MODE_DAY', 50.0);

if ($response->json('code') === 0) {
    $campaignId = $response->json('data.campaign_id');
}
```

### Request Example (budget omitted)
```php
$response = TiktokAds::createCampaign(
    name: 'My Campaign',
    objective: 'TRAFFIC',
);
// payload contains campaign_name, objective_type, budget_mode = 'BUDGET_MODE_DAY'
// but NO 'budget' key — the null budget was filtered out
```
```

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

### Import paths for TiktokAds class and facade

Source: https://github.com/jeffersongoncalves/laravel-tiktok-ads

Shows the two import paths for the TiktokAds class and its facade, which share the same short name. Use the facade for convenient access in Laravel applications.

```php
use JeffersonGoncalves\TiktokAds\TiktokAds;          // the class
use JeffersonGoncalves\TiktokAds\Facades\TiktokAds;  // the facade (same short name)
```

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

### post() protected method

Source: https://github.com/jeffersongoncalves/laravel-tiktok-ads

Protected method that performs a POST request with the given data as the JSON body. The data array is documented as a string-keyed map of mixed values.

```php
/**
 * @param  array<string, mixed>  $data
 */
protected function post(string $path, array $data = []): Response
{
    return $this->client()->post($path, $data);
}
```

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

### Basic usage with facade and container

Source: https://github.com/jeffersongoncalves/laravel-tiktok-ads

Shows how to call the TikTok Ads API using the TiktokAds facade with the default advertiser ID from configuration, and the equivalent container-based usage.

```php
use JeffersonGoncalves\TiktokAds\Facades\TiktokAds;

$response = TiktokAds::campaigns();
$data = $response->json();

// Equivalent container-based usage (no facade):
app(JeffersonGoncalves\TiktokAds\TiktokAds::class)->campaigns();
```

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

### Set config values in tests before first resolution

Source: https://github.com/jeffersongoncalves/laravel-tiktok-ads

Used in tests/Feature/TiktokAdsTest.php to set config in beforeEach() before the singleton is first resolved, controlling the client values. Changing config at runtime after resolution does not rebuild the existing singleton.

```php
config(['laravel-tiktok-ads.access_token' => 'test-token']);
config(['laravel-tiktok-ads.advertiser_id' => '123']);
```

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

### Instantiate TiktokAds with configuration values

Source: https://github.com/jeffersongoncalves/laravel-tiktok-ads

Shows how to create a new TiktokAds instance using values from the Laravel configuration. The access token is sent as the Access-Token header on every request, and the advertiser ID is used as default when no explicit ID is passed.

```php
new TiktokAds(
    config('laravel-tiktok-ads.access_token'),
    config('laravel-tiktok-ads.advertiser_id'),
    config('laravel-tiktok-ads.api_version'),
);
```

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

### List campaigns with pagination using TiktokAds::campaigns()

Source: https://github.com/jeffersongoncalves/laravel-tiktok-ads

Calls the campaigns() method to fetch campaign lists with pagination. The first call uses defaults (page 1, page_size 20), the second specifies page 2 and page_size 50. The response is an Illuminate HTTP Client Response; campaign data is available under data.list.

```php
use JeffersonGoncalves\TiktokAds\Facades\TiktokAds;

$pageOne = TiktokAds::campaigns();              // page 1, page_size 20
$pageTwo = TiktokAds::campaigns(page: 2, pageSize: 50);

foreach ($pageTwo->json('data.list', []) as $campaign) {
    echo $campaign['campaign_id'] . ' ' . $campaign['campaign_name'];
}
```

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

### Full source of TiktokAdsServiceProvider

Source: https://github.com/jeffersongoncalves/laravel-tiktok-ads

The complete service provider class that registers the package with Laravel. It extends Spatie's PackageServiceProvider, configures the package name and config file, and binds the TiktokAds client as a singleton with an alias.

```php
<?php

namespace JeffersonGoncalves\TiktokAds;

use Spatie\LaravelPackageTools\Package;
use Spatie\LaravelPackageTools\PackageServiceProvider;

class TiktokAdsServiceProvider extends PackageServiceProvider
{
    public function configurePackage(Package $package): void
    {
        $package
            ->name('laravel-tiktok-ads')
            ->hasConfigFile('laravel-tiktok-ads');
    }

    public function packageRegistered(): void
    {
        $this->app->singleton(TiktokAds::class, fn () => new TiktokAds(
            config('laravel-tiktok-ads.access_token'),
            config('laravel-tiktok-ads.advertiser_id'),
            config('laravel-tiktok-ads.api_version'),
        ));

        $this->app->alias(TiktokAds::class, 'laravel-tiktok-ads');
    }
}
```

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

### client() protected method

Source: https://github.com/jeffersongoncalves/laravel-tiktok-ads

Protected method that builds the Laravel PendingRequest used by all calls. Sets the TikTok Business base URL with the API version, the Access-Token header, and JSON request semantics.

```php
protected function client(): PendingRequest
{
    return Http::baseUrl("https://business-api.tiktok.com/open_api/{$this->apiVersion}")
        ->withHeaders(['Access-Token' => $this->accessToken])
        ->asJson();
}
```

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

### TiktokAds::campaigns()

Source: https://github.com/jeffersongoncalves/laravel-tiktok-ads

Fetches a paginated list of campaigns for the specified advertiser. Supports pagination through page and pageSize parameters.

```APIDOC
## TiktokAds::campaigns()

### Description
Fetches a paginated list of campaigns for the specified advertiser. Supports pagination through page and pageSize parameters.

### Method
Static call on the TiktokAds facade

### Endpoint
`TiktokAds::campaigns(?string $advertiserId = null, int $page = 1, int $pageSize = 20): Response`

### Parameters
#### Parameters
- **advertiserId** (?string) - Optional - The advertiser ID. If null, it will be resolved automatically.
- **page** (int) - Optional - Page number for pagination. Defaults to 1.
- **pageSize** (int) - Optional - Number of items per page. Defaults to 20.

### Response
Returns `Illuminate\Http\Client\Response`.

### Exceptions
Throws `InvalidArgumentException` when no advertiser ID can be resolved.
```

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

### advertiserInfo() with explicit ID and error handling

Source: https://github.com/jeffersongoncalves/laravel-tiktok-ads

Passes an explicit advertiser ID to advertiserInfo() and catches InvalidArgumentException, which is thrown when neither the argument nor the configured advertiser_id is set.

```php
try {
    $response = TiktokAds::advertiserInfo('7000000000000000000');
    dd($response->json());
} catch (InvalidArgumentException $e) {
    // thrown when neither the argument nor config('laravel-tiktok-ads.advertiser_id') is set
}
```

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

### Default config file config/laravel-tiktok-ads.php

Source: https://github.com/jeffersongoncalves/laravel-tiktok-ads

The package's entire configuration is read from this single Laravel config file. It defines access_token, advertiser_id, and api_version keys, each sourced from environment variables with defaults (api_version defaults to 'v1.3').

```php
<?php

return [
    'access_token' => env('TIKTOK_ACCESS_TOKEN'),

    'advertiser_id' => env('TIKTOK_ADVERTISER_ID'),

    'api_version' => env('TIKTOK_ADS_API_VERSION', 'v1.3'),
];
```

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

### Singleton closure consuming config values

Source: https://github.com/jeffersongoncalves/laravel-tiktok-ads

The config is consumed only by the service-provider singleton closure, which passes the three config values to the TiktokAds constructor.

```php
$this->app->singleton(TiktokAds::class, fn () => new TiktokAds(
    config('laravel-tiktok-ads.access_token'),
    config('laravel-tiktok-ads.advertiser_id'),
    config('laravel-tiktok-ads.api_version'),
));
```

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

### getFacadeAccessor Method Implementation

Source: https://github.com/jeffersongoncalves/laravel-tiktok-ads

Returns the container binding key for the underlying TiktokAds instance. This method is called by the facade to resolve the singleton instance registered by the service provider.

```php
protected static function getFacadeAccessor(): string
{
    return \JeffersonGoncalves\TiktokAds\TiktokAds::class;
}
```

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

### packageRegistered() method

Source: https://github.com/jeffersongoncalves/laravel-tiktok-ads

The packageRegistered method binds TiktokAds as a singleton in the Laravel container, reading configuration values for access_token, advertiser_id, and api_version. It also registers the string alias 'laravel-tiktok-ads'.

```php
public function packageRegistered(): void
{
    $this->app->singleton(TiktokAds::class, fn () => new TiktokAds(
        config('laravel-tiktok-ads.access_token'),
        config('laravel-tiktok-ads.advertiser_id'),
        config('laravel-tiktok-ads.api_version'),
    ));

    $this->app->alias(TiktokAds::class, 'laravel-tiktok-ads');
}
```

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

### TiktokAds::report()

Source: https://github.com/jeffersongoncalves/laravel-tiktok-ads

Generates a performance report for the specified date range, dimensions, metrics, and data level. Allows customization of report type and advertiser.

```APIDOC
## TiktokAds::report()

### Description
Generates a performance report for the specified date range, dimensions, metrics, and data level. Allows customization of report type and advertiser.

### Method
Static call on the TiktokAds facade

### Endpoint
`TiktokAds::report(string $startDate, string $endDate, array $dimensions = ['campaign_id'], array $metrics = ['spend', 'impressions', 'clicks', 'conversion'], string $dataLevel = 'AUCTION_CAMPAIGN', string $reportType = 'BASIC', ?string $advertiserId = null): Response`

### Parameters
#### Parameters
- **startDate** (string) - Required - Start date for the report.
- **endDate** (string) - Required - End date for the report.
- **dimensions** (array) - Optional - Dimensions to group by. Defaults to ['campaign_id'].
- **metrics** (array) - Optional - Metrics to include. Defaults to ['spend', 'impressions', 'clicks', 'conversion'].
- **dataLevel** (string) - Optional - Data level. Defaults to 'AUCTION_CAMPAIGN'.
- **reportType** (string) - Optional - Report type. Defaults to 'BASIC'.
- **advertiserId** (?string) - Optional - The advertiser ID. If null, it will be resolved automatically.

### Response
Returns `Illuminate\Http\Client\Response`.

### Exceptions
Throws `InvalidArgumentException` when no advertiser ID can be resolved.
```

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

### POST /report/integrated/get/

Source: https://github.com/jeffersongoncalves/laravel-tiktok-ads

Fetches an integrated performance report. The client method is TiktokAds::report().

```APIDOC
## [POST] /report/integrated/get/

### Description
Fetches an integrated performance report. The client method is `TiktokAds::report()`.

### Method
POST

### Endpoint
/report/integrated/get/

### Parameters
#### Request Body
- **advertiser_id** (string) - Required - Resolved advertiser ID.
- **report_type** (string) - Required - Default `BASIC`.
- **dimensions** (array<int, string>) - Required - Default `['campaign_id']`.
- **metrics** (array<int, string>) - Required - Default `['spend', 'impressions', 'clicks', 'conversion']`.
- **data_level** (string) - Required - Default `AUCTION_CAMPAIGN`.
- **start_date** (string) - Required - e.g. `2026-01-01`.
- **end_date** (string) - Required - e.g. `2026-01-31`.

### Response
#### Success Response (200)
- **data.list** (array) - Array of report rows.
```

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

### TiktokAds::advertiserInfo()

Source: https://github.com/jeffersongoncalves/laravel-tiktok-ads

Retrieves advertiser information for the given advertiser ID. If no advertiser ID is provided, it attempts to resolve one automatically.

```APIDOC
## TiktokAds::advertiserInfo()

### Description
Retrieves advertiser information for the given advertiser ID. If no advertiser ID is provided, it attempts to resolve one automatically.

### Method
Static call on the TiktokAds facade

### Endpoint
`TiktokAds::advertiserInfo(?string $advertiserId = null): Response`

### Parameters
#### Parameters
- **advertiserId** (?string) - Optional - The advertiser ID. If null, it will be resolved automatically.

### Response
Returns `Illuminate\Http\Client\Response`.

### Exceptions
Throws `InvalidArgumentException` when no advertiser ID can be resolved.
```

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

### adGroups() method signature

Source: https://github.com/jeffersongoncalves/laravel-tiktok-ads

Declares the adGroups method that lists ad groups, optionally filtered by a campaign ID. When a campaign ID is provided, it is sent as a JSON-encoded single-element array in the campaign_ids query parameter.

```php
public function adGroups(?string $campaignId = null, ?string $advertiserId = null): Response

```

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

### Publish config with artisan vendor:publish

Source: https://github.com/jeffersongoncalves/laravel-tiktok-ads

Publishes config/laravel-tiktok-ads.php into the consuming application's config/ directory for editing or overriding.

```bash
php artisan vendor:publish --tag="laravel-tiktok-ads-config"
```

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

### composer.json extra.laravel.providers registration

Source: https://github.com/jeffersongoncalves/laravel-tiktok-ads

JSON configuration in composer.json that enables Laravel auto-discovery of the service provider and registers the facade alias.

```json
"extra": {
    "laravel": {
        "providers": [
            "JeffersonGoncalves\\TiktokAds\\TiktokAdsServiceProvider"
        ],
        "aliases": {
            "TiktokAds": "JeffersonGoncalves\\TiktokAds\\Facades\\TiktokAds"
        }
    }
}
```

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

### TiktokAds constructor signature

Source: https://github.com/jeffersongoncalves/laravel-tiktok-ads

Exact constructor signature from src/TiktokAds.php lines 12–16. The constructor is normally invoked by the service provider singleton with configuration values.

```php
public function __construct(
    protected ?string $accessToken,
    protected ?string $advertiserId,
    protected string $apiVersion,
) {}
```

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

### updateCampaignStatus() method signature

Source: https://github.com/jeffersongoncalves/laravel-tiktok-ads

Declares the updateCampaignStatus method that updates the status (enable/disable/delete) of one or more campaigns. It accepts an array of campaign IDs, a status string, and an optional advertiser ID. The method throws InvalidArgumentException if no advertiser ID is available.

```php
/**
 * @param  array<int, string>  $campaignIds
 */
public function updateCampaignStatus(array $campaignIds, string $status, ?string $advertiserId = null): Response

```

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

### adGroups(?string $campaignId = null, ?string $advertiserId = null): Response

Source: https://github.com/jeffersongoncalves/laravel-tiktok-ads

Lists ad groups, optionally filtered by a campaign. When a campaign ID is provided, the query includes campaign_ids as a JSON-encoded single-element array string; otherwise, campaign_ids is omitted.

```APIDOC
## adGroups(?string $campaignId = null, ?string $advertiserId = null): Response

### Description
Lists ad groups, optionally filtered by a campaign. GET query: `advertiser_id`, and — only when `$campaignId` is non-null — `campaign_ids` as a JSON-encoded single-element array string (`json_encode([$campaignId])`).

### Method
GET

### Endpoint
Not specified (SDK method)

### Parameters
#### Path Parameters
None

#### Query Parameters
- **advertiser_id** (string) - Required - Explicit advertiser ID; falls back to the configured `advertiser_id`.
- **campaign_ids** (string) - Optional - JSON-encoded single-element array string, e.g. `["1790000000000000000"]`. Only present when `$campaignId` is non-null.

### Response
#### Success Response (200)
- **data.list** (array) - Ad group list on success.

### Request Example
```php
use JeffersonGoncalves\TiktokAds\Facades\TiktokAds;

$all = TiktokAds::adGroups();                       // no campaign filter
$byCampaign = TiktokAds::adGroups('1790000000000000000'); // ?campaign_ids=["1790000000000000000"]
```
```

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

### TiktokAds::adGroups()

Source: https://github.com/jeffersongoncalves/laravel-tiktok-ads

Retrieves ad groups, optionally filtered by campaign ID and advertiser ID.

```APIDOC
## TiktokAds::adGroups()

### Description
Retrieves ad groups, optionally filtered by campaign ID and advertiser ID.

### Method
Static call on the TiktokAds facade

### Endpoint
`TiktokAds::adGroups(?string $campaignId = null, ?string $advertiserId = null): Response`

### Parameters
#### Parameters
- **campaignId** (?string) - Optional - Filter by campaign ID.
- **advertiserId** (?string) - Optional - The advertiser ID. If null, it will be resolved automatically.

### Response
Returns `Illuminate\Http\Client\Response`.

### Exceptions
Throws `InvalidArgumentException` when no advertiser ID can be resolved.
```

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

### TiktokAds Facade Class Definition

Source: https://github.com/jeffersongoncalves/laravel-tiktok-ads

Defines the Laravel facade for the TiktokAds client, extending Illuminate\Support\Facades\Facade. The getFacadeAccessor method returns the fully qualified class name of the underlying client, enabling static calls to be forwarded to the singleton instance.

```php
<?php

namespace JeffersonGoncalves\TiktokAds\Facades;

use Illuminate\Support\Facades\Facade;

/**
 * @see \JeffersonGoncalves\TiktokAds\TiktokAds
 */
class TiktokAds extends Facade
{
    protected static function getFacadeAccessor(): string
    {
        return \JeffersonGoncalves\TiktokAds\TiktokAds::class;
    }
}
```

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

### report() method signature

Source: https://github.com/jeffersongoncalves/laravel-tiktok-ads

Signature of the report() method in src/TiktokAds.php (lines 74-84). It runs an integrated report, POSTed as JSON with fields: advertiser_id, report_type, dimensions, metrics, data_level, start_date, end_date. Returns Illuminate\Http\Client\Response with report rows under data.list on success. Throws InvalidArgumentException when no advertiser ID is available.

```php
/**
 * @param  array<int, string>  $dimensions
 * @param  array<int, string>  $metrics
 */
public function report(
    string $startDate,
    string $endDate,
    array $dimensions = ['campaign_id'],
    array $metrics = ['spend', 'impressions', 'clicks', 'conversion'],
    string $dataLevel = 'AUCTION_CAMPAIGN',
    string $reportType = 'BASIC',
    ?string $advertiserId = null,
): Response
```

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

### Handle missing advertiser ID with InvalidArgumentException

Source: https://github.com/jeffersongoncalves/laravel-tiktok-ads

Simulates an unconfigured advertiser_id and catches the InvalidArgumentException thrown when no advertiser ID is available. The error message indicates that advertiser_id is required and can be passed explicitly or set via TIKTOK_ADVERTISER_ID.

```php
config(['laravel-tiktok-ads.advertiser_id' => null]); // simulate unconfigured env

try {
    TiktokAds::campaigns();
} catch (InvalidArgumentException $e) {
    // "advertiser_id required (pass explicitly or set TIKTOK_ADVERTISER_ID)"
}
```

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

### updateCampaignStatus(array $campaignIds, string $status, ?string $advertiserId = null): Response

Source: https://github.com/jeffersongoncalves/laravel-tiktok-ads

Updates the status (enable/disable/delete) of one or more campaigns. The method POSTs JSON with advertiser_id, campaign_ids, and opt_status fields, and returns an Illuminate HTTP Client Response where success is indicated by payload code === 0.

```APIDOC
## updateCampaignStatus(array $campaignIds, string $status, ?string $advertiserId = null): Response

### Description
Updates the status (enable/disable/delete) of one or more campaigns. POSTed as JSON: `advertiser_id`, `campaign_ids`, `opt_status`.

### Method
POST

### Endpoint
Not specified (SDK method)

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
- **advertiser_id** (string) - Required - Explicit advertiser ID; falls back to the configured `advertiser_id`.
- **campaign_ids** (array<int, string>) - Required - List of campaign IDs.
- **opt_status** (string) - Required - Desired status, e.g. `ENABLE`, `DISABLE`, `DELETE`.

### Response
#### Success Response (200)
- **code** (int) - Success indicated by `code === 0`.

### Request Example
```php
use JeffersonGoncalves\TiktokAds\Facades\TiktokAds;

$response = TiktokAds::updateCampaignStatus(
    campaignIds: ['1790000000000000000', '1790000000000000001'],
    status: 'DISABLE',
);

$response->throw(); // Laravel HTTP client: throws on HTTP error status
```
```

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

### TiktokAds::audiences()

Source: https://github.com/jeffersongoncalves/laravel-tiktok-ads

Retrieves the list of audiences for the specified advertiser.

```APIDOC
## TiktokAds::audiences()

### Description
Retrieves the list of audiences for the specified advertiser.

### Method
Static call on the TiktokAds facade

### Endpoint
`TiktokAds::audiences(?string $advertiserId = null): Response`

### Parameters
#### Parameters
- **advertiserId** (?string) - Optional - The advertiser ID. If null, it will be resolved automatically.

### Response
Returns `Illuminate\Http\Client\Response`.

### Exceptions
Throws `InvalidArgumentException` when no advertiser ID can be resolved.
```

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

### audiences() method signature

Source: https://github.com/jeffersongoncalves/laravel-tiktok-ads

Public method to list custom audiences (TikTok DMP). Accepts an optional advertiser ID; falls back to the configured advertiser_id. Returns a Laravel HTTP client Response with the audience list under data.list on success.

```php
public function audiences(?string $advertiserId = null): Response
```

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

### Error handling with missing advertiser_id

Source: https://github.com/jeffersongoncalves/laravel-tiktok-ads

Demonstrates that when the advertiser_id is null, calling campaigns() throws an InvalidArgumentException with the message 'advertiser_id required (pass explicitly or set TIKTOK_ADVERTISER_ID)'.

```php
config(['laravel-tiktok-ads.advertiser_id' => null]);

try {
    TiktokAds::campaigns();
} catch (InvalidArgumentException $e) {
    // "advertiser_id required (pass explicitly or set TIKTOK_ADVERTISER_ID)"
}
```

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

### TiktokAds::updateCampaignStatus()

Source: https://github.com/jeffersongoncalves/laravel-tiktok-ads

Updates the status of one or more campaigns. Accepts an array of campaign IDs and the new status.

```APIDOC
## TiktokAds::updateCampaignStatus()

### Description
Updates the status of one or more campaigns. Accepts an array of campaign IDs and the new status.

### Method
Static call on the TiktokAds facade

### Endpoint
`TiktokAds::updateCampaignStatus(array $campaignIds, string $status, ?string $advertiserId = null): Response`

### Parameters
#### Parameters
- **campaignIds** (array) - Required - Array of campaign IDs to update.
- **status** (string) - Required - The new status to set.
- **advertiserId** (?string) - Optional - The advertiser ID. If null, it will be resolved automatically.

### Response
Returns `Illuminate\Http\Client\Response`.

### Exceptions
Throws `InvalidArgumentException` when no advertiser ID can be resolved.
```

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

### POST /campaign/status/update/

Source: https://github.com/jeffersongoncalves/laravel-tiktok-ads

Updates the status of one or more campaigns. The client method is TiktokAds::updateCampaignStatus().

```APIDOC
## [POST] /campaign/status/update/

### Description
Updates the status of one or more campaigns. The client method is `TiktokAds::updateCampaignStatus()`.

### Method
POST

### Endpoint
/campaign/status/update/

### Parameters
#### Request Body
- **advertiser_id** (string) - Required - Resolved advertiser ID.
- **campaign_ids** (array<int, string>) - Required - `$campaignIds` argument, sent as a JSON array (e.g. `["1","2"]`).
- **opt_status** (string) - Required - `$status` argument (e.g. `ENABLE`, `DISABLE`, `DELETE`).

### Response
#### Success Response (200)
None (`code === 0` indicates success).
```

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

### resolveAdvertiserId() protected method

Source: https://github.com/jeffersongoncalves/laravel-tiktok-ads

Protected method that resolves the advertiser ID, falling back to the configured value if null. Throws InvalidArgumentException with the message 'advertiser_id required (pass explicitly or set TIKTOK_ADVERTISER_ID)' if the resolved value is blank.

```php
protected function resolveAdvertiserId(?string $advertiserId): string
{
    $advertiserId ??= $this->advertiserId;

    throw_if(blank($advertiserId), new InvalidArgumentException('advertiser_id required (pass explicitly or set TIKTOK_ADVERTISER_ID)'));

    return $advertiserId;
}
```

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

### audiences(?string $advertiserId = null): Response

Source: https://github.com/jeffersongoncalves/laravel-tiktok-ads

Lists custom audiences (TikTok DMP) by calling the /dmp/custom_audience/list/ endpoint. Accepts an optional advertiser ID, falling back to the configured advertiser_id.

```APIDOC
## audiences(?string $advertiserId = null): Response

### Description
Lists custom audiences (TikTok DMP) by calling the /dmp/custom_audience/list/ endpoint. Accepts an optional advertiser ID, falling back to the configured advertiser_id.

### Method
GET

### Endpoint
/dmp/custom_audience/list/

### Parameters
#### Query Parameters
- **advertiser_id** (string) - Optional - Explicit advertiser ID; falls back to the configured `advertiser_id`.

### Response
#### Success Response (200)
- **data.list** (array) - Audience list on success.

### Request Example
```php
use JeffersonGoncalves\TiktokAds\Facades\TiktokAds;

$audiences = TiktokAds::audiences()->json('data.list', []);
```
```
Tokens:
Raw