Shopee PHP

https://github.com/ecomphp/shopee-php
Admin
An unofficial Shopee API client library for PHP that provides simple SDK implementation to interact...
Tokens:108,132
Snippets:950
Trust Score:6.7
License:Apache-2.0
Update:1 month ago
Show doc for...
Tokens:
Raw
### Example: Fetch shop sales performance detail

Source: https://github.com/ecomphp/shopee-php/blob/master/_autodocs/api-reference/Insights.md

Shows how to set a principal access token and call getShopSalesPerformanceDetail with start and end dates. The method returns shop sales performance detail for the specified period.

```php
$client->setPrincipalAccessToken($principalId, $token);
$sales = $client->BrandPortal->getShopSalesPerformanceDetail([
    'start_date' => '2024-01-01',
    'end_date' => '2024-01-31',
]);
```

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

### Ship order example

Source: https://github.com/ecomphp/shopee-php/blob/master/_autodocs/api-reference/Logistics.md

Example of getting shipping parameters and then shipping an order. The comment indicates choosing pickup/dropoff/non_integrated based on info_needed.

```php
$params = $client->Logistic->getShippingParameter($orderSn, $packageNo);
// addr = $params['info_needed'] ... choose pickup/dropoff/non_integrated
$client->Logistic->shipOrder($orderSn, $packageNo, $pickup, $dropoff, $nonIntegrated);
```

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

### Install via Composer

Source: https://github.com/ecomphp/shopee-php/blob/master/README.md

Install the ecomphp/shopee-php package using Composer.

```shell
composer require ecomphp/shopee-php
```

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

### Example: getShopInfo() usage

Source: https://github.com/ecomphp/shopee-php/blob/master/_autodocs/api-reference/Shop.md

Example usage of getShopInfo() to fetch and display the shop name.

```php
$info = $client->Shop->getShopInfo();
echo $info['shop_name'];
```

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

### Invoice upload and download example

Source: https://github.com/ecomphp/shopee-php/blob/master/_autodocs/api-reference/Order.md

Example showing upload of an invoice document and subsequent download.

```php
// upload an invoice, then download it back
$client->Order->uploadInvoiceDoc('250922ABC123', 'pdf', '/tmp/invoice.pdf');
$content = $client->Order->downloadInvoiceDoc('250922ABC123');
```

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

### Example usage of Ads methods

Source: https://github.com/ecomphp/shopee-php/blob/master/_autodocs/api-reference/Insights.md

Example showing how to call getTotalBalance() and getAllCpcAdsDailyPerformance() on the Ads client.

```php
$balance = $client->Ads->getTotalBalance();
$daily = $client->Ads->getAllCpcAdsDailyPerformance('2024-01-01', '2024-01-07');
```

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

### getToken usage example

Source: https://github.com/ecomphp/shopee-php/blob/master/_autodocs/api-reference/Auth.md

Example of calling getToken with $_GET parameters and setting the access token on the client.

```php
$auth = $client->auth();
$token = $auth->getToken($_GET['code'], $_GET['shop_id']);
// $token['access_token'], $token['refresh_token']
$client->setAccessToken($_GET['shop_id'], $token['access_token']);
```

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

### handleBuyerCancellation example

Source: https://github.com/ecomphp/shopee-php/blob/master/_autodocs/api-reference/Order.md

Example call to accept a buyer cancellation request.

```php
// handle a buyer cancellation request (accept)
$client->Order->handleBuyerCancellation('250922ABC123', 'ACCEPT');
```

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

### Example MCP configuration (mcp.json)

Source: https://github.com/ecomphp/shopee-php/blob/master/_autodocs/configuration.md

Example configuration written by bin/shopee-mcp-install into .ai/mcp/mcp.json. Sets environment variables for the shopee MCP server, including partner ID, key, region, redirect URI, shop ID, and access token. Use this as a template for configuring the MCP server.

```json
{
  "mcpServers": {
    "shopee": {
      "command": "php",
      "args": ["/path/to/shopee-php/bin/shopee-mcp-server"],
      "env": {
        "SHOPEE_PARTNER_ID": "10001",
        "SHOPEE_PARTNER_KEY": "your_key",
        "SHOPEE_REGION": "cn",
        "SHOPEE_REDIRECT_URI": "https://myapp.example/oauth/callback",
        "SHOPEE_SHOP_ID": "123456",
        "SHOPEE_ACCESS_TOKEN": "token"
      }
    }
  }
}
```

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

### getOrderList example

Source: https://github.com/ecomphp/shopee-php/blob/master/_autodocs/api-reference/Order.md

Example call to getOrderList with order_status, time_from, and page_size overrides.

```php
$orders = $client->Order->getOrderList([
    'order_status' => 'READY_TO_SHIP',
    'time_from' => strtotime('-30 days'),
    'page_size' => 50,
]);
```

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

### createCancelAuthRequest usage example

Source: https://github.com/ecomphp/shopee-php/blob/master/_autodocs/api-reference/Auth.md

Example of creating a cancellation authorization URL and echoing it.

```php
$url = $auth->createCancelAuthRequest('https://myapp.example/unlink', true);
echo $url; // e.g. https://open.shopee.com/cancel_auth?partner_id=...&redirect_uri=...&auth_type=seller&response_type=code
```

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

### Upload an image example

Source: https://github.com/ecomphp/shopee-php/blob/master/_autodocs/api-reference/Communication.md

Example of uploading an image using an SplFileInfo object with scene and ratio parameters.

```php
$upload = $client->MediaSpace->uploadImage(new \SplFileInfo('/tmp/banner.jpg'), 'product', '1:1');
```

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

### call method usage example

Source: https://github.com/ecomphp/shopee-php/blob/master/_autodocs/api-reference/Client.md

Example of calling the product/get_item_list endpoint with query parameters. The response is the array under the 'response' key.

```php
$response = $client->call('GET', 'product/get_item_list', [
    \GuzzleHttp\RequestOptions::QUERY => ['offset' => 0, 'page_size' => 20],
]);
// $response is the array under {"response": ...}
```

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

### createAuthRequest usage example

Source: https://github.com/ecomphp/shopee-php/blob/master/_autodocs/api-reference/Auth.md

Example of creating an authorization URL and redirecting the user.

```php
$authUrl = $auth->createAuthRequest('https://myapp.example/oauth/callback', true);
header('Location: ' . $authUrl);
```

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

### getOrderDetail example

Source: https://github.com/ecomphp/shopee-php/blob/master/_autodocs/api-reference/Order.md

Example call to getOrderDetail with an array of order SNs.

```php
$detail = $client->Order->getOrderDetail(['250922ABC123', '250922ABC124']);
```

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

### Example usage of AccountHealth methods

Source: https://github.com/ecomphp/shopee-php/blob/master/_autodocs/api-reference/Insights.md

Example demonstrating how to use getShopPerformance, getPenaltyPointHistory, and getMetricSourceDetail together to fetch and process account health data.

```php
$perf = $client->AccountHealth->getShopPerformance();
$penalties = $client->AccountHealth->getPenaltyPointHistory('SELLER_PENALTY_POINT', 1, 50);
foreach ($perf['metrics'] as $metric) {
    $detail = $client->AccountHealth->getMetricSourceDetail($metric['metric_id']);
}
```

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

### AddOnDeal create example

Source: https://github.com/ecomphp/shopee-php/blob/master/_autodocs/api-reference/Promotions.md

Example of creating an add-on deal and then adding main and sub items. Uses the client's AddOnDeal resource to call addAddOnDeal, addAddOnDealMainItem, and addAddOnDealSubItem.

```php
$added = $client->AddOnDeal->addAddOnDeal([
    'name' => 'Winter Gift Combo',
    'start_time' => 1700000000,
    'end_time' => 1705000000,
]);
$client->AddOnDeal->addAddOnDealMainItem($added['add_on_deal_id'], [
    ['item_id' => 111],
]);
$client->AddOnDeal->addAddOnDealSubItem($added['add_on_deal_id'], [
    ['item_id' => 222, 'promotion_price' => 5000, 'purchase_limit' => 1],
]);
```

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

### Voucher usage example

Source: https://github.com/ecomphp/shopee-php/blob/master/_autodocs/api-reference/Promotions-Campaigns.md

Demonstrates adding a voucher and retrieving a list of ongoing vouchers.

```php
$client->Voucher->addVoucher([
    'name' => 'Loyal 10%',
    'voucher_type' => 1,
    'start_time' => 1700000000,
    'end_time' => 1705000000,
]);
$vouchers = $client->Voucher->getVoucherList(['status' => 'ONGOING']);
```

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

### addItem usage example

Source: https://github.com/ecomphp/shopee-php/blob/master/_autodocs/api-reference/Product.md

Example usage of addItem with required fields. Note 'original_price' is in Shopee price units.

```php
$item = $client->Product->addItem([
    'name' => 'Widget',
    'original_price' => 100000,   // in Shopee price units
    'category_id' => 100001,
    'description' => '...',
    'images' => ['https://cdn.example/img.jpg'],
]);
```

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

### Example: merchant warehouse list with principal token

Source: https://github.com/ecomphp/shopee-php/blob/master/_autodocs/api-reference/Shop.md

Example usage of merchant-level authorization and retrieving warehouse list with custom page size.

```php
$client->setPrincipalAccessToken($principalId, $token);
$warehouses = $client->Merchant->getMerchantWarehouseList('custom', ['page_size' => 20]);
```

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

### Discount Usage Example

Source: https://github.com/ecomphp/shopee-php/blob/master/_autodocs/api-reference/Promotions.md

Shows how to add a discount and retrieve a list of ongoing discounts using the client.

```php
$client->Discount->addDiscount([
    'name' => 'Year End Sale',
    'start_time' => 1700000000,
    'end_time' => 1705000000,
]);
$discounts = $client->Discount->getDiscountList(['discount_status' => 'ongoing']);
```

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

### Manual dispatch example

Source: https://github.com/ecomphp/shopee-php/blob/master/_autodocs/api-reference/Resource.md

Example of manually dispatching a request using the call() method. It creates a Shop resource, binds a client, and calls the 'shop/get_shop_info' endpoint.

```php
$resource = new EcomPHP\Shopee\Resources\Shop();
$resource->useApiClient($client);
$info = $resource->call('GET', 'shop/get_shop_info'); // == $client->Shop->getShopInfo()
```

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

### Download shipping document example

Source: https://github.com/ecomphp/shopee-php/blob/master/_autodocs/api-reference/Logistics.md

Example of downloading a shipping document to a local file using the save_path parameter. Without save_path, the raw body string is returned instead.

```php
$client->Logistic->downloadShippingDocument(
    [['order_sn' => $orderSn, 'package_number' => $packageNo, 'tracking_number' => $trackingNo]],
    'label',
    '/tmp/label.pdf',           // SINK: writes the file locally
);
// without $save_path the raw body string is returned instead
$bytes = $client->Logistic->downloadShippingDocument([...], 'label');
```

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

### setAppPushConfig usage example

Source: https://github.com/ecomphp/shopee-php/blob/master/_autodocs/api-reference/Communication.md

Example call to setAppPushConfig with a callback URL and enabling the ORDER_STATUS topic. The method returns a response from the Shopee API.

```php
$client->Push->setAppPushConfig('https://myapp.example/webhook', ['ORDER_STATUS'], [], []);
```

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

### TopPicks usage example

Source: https://github.com/ecomphp/shopee-php/blob/master/_autodocs/api-reference/Promotions-Campaigns.md

Shows how to add and update a TopPicks collection via the client.

```php
$client->TopPicks->addTopPicks('Best Sellers', [111, 222, 333], true);
$client->TopPicks->updateTopPicks($topPicksId, null, [111, 222], null);
```

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

### refreshNewToken usage example

Source: https://github.com/ecomphp/shopee-php/blob/master/_autodocs/api-reference/Auth.md

Example of refreshing the access token and persisting the new refresh token.

```php
$new = $auth->refreshNewToken($stored_refresh_token, $shop_id);
$client->setAccessToken($shop_id, $new['access_token']);
// persist $new['refresh_token'] for the next refresh
```

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

### Example: refreshNewToken usage

Source: https://github.com/ecomphp/shopee-php/blob/master/_autodocs/api-reference/Shop.md

Example usage of refreshNewToken to obtain new tokens and set the access token for a shop.

```php
$tokens = $client->Authorization->refreshNewToken($refreshToken, $shopId, $partnerId);
$client->setAccessToken($shopId, $tokens['access_token']);
```

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

### FollowPrize usage example

Source: https://github.com/ecomphp/shopee-php/blob/master/_autodocs/api-reference/Promotions-Campaigns.md

Demonstrates adding a new follow-prize campaign.

```php
$client->FollowPrize->addFollowPrize([
    'name' => 'Follow Us!',
    'start_time' => 1700000000,
    'end_time' => 1705000000,
    'prize' => ['type' => 1, 'amount' => 10000],
]);
```

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

### Generate and bind first-mile tracking number example

Source: https://github.com/ecomphp/shopee-php/blob/master/_autodocs/api-reference/Logistics.md

Example usage: generates a tracking number for today's date with quantity 1, then binds it to an order using the returned tracking number.

```php
$fn = $client->FirstMile->generateFirstMileTrackingNumber(date('Y-m-d'), 1);
$client->FirstMile->bindFirstMileTrackingNumber([
    'first_mile_tracking_number_list' => [$fn['first_mile_tracking_number']],
    'order_sn_list' => [$orderSn],
]);
```

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

### getItemList usage example

Source: https://github.com/ecomphp/shopee-php/blob/master/_autodocs/api-reference/Product.md

Example usage of getItemList showing array and string parameter forms. The string form allows repeating 'item_status' for multi-status queries.

```php
$items = $client->Product->getItemList(['offset' => 0, 'page_size' => 50]);
// multi-status: pass a raw query string to repeat item_status
$items = $client->Product->getItemList('offset=0&page_size=20&item_status=NORMAL&item_status=BANNED');
```

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

### ShopCategory usage example

Source: https://github.com/ecomphp/shopee-php/blob/master/_autodocs/api-reference/Product.md

Example usage of ShopCategory methods: add a category, add items to it, and retrieve the item list.

```php
$cat = $client->ShopCategory->addShopCategory('New Collection', 5);
$client->ShopCategory->addItemList($cat['shop_category_id'], [111, 222]);
$list = $client->ShopCategory->getItemList($cat['shop_category_id'], ['page_size' => 50]);
```

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

### getShopInstallmentStatus()

Source: https://github.com/ecomphp/shopee-php/blob/master/_autodocs/api-reference/Payment.md

Retrieves the current shop installment status.

```APIDOC
## getShopInstallmentStatus()

### Description
Retrieves the current shop installment status.

### Method
GET

### Endpoint
Not specified
```

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

### ShopFlashSale - getItemCriteria method signature (:49)

Source: https://github.com/ecomphp/shopee-php/blob/master/_autodocs/api-reference/Promotions-Campaigns.md

Gets eligibility criteria for flash-sale items via GET.

```php
public function getItemCriteria()
```

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

### getEscrowDetail usage example

Source: https://github.com/ecomphp/shopee-php/blob/master/_autodocs/api-reference/Payment.md

Example of calling getEscrowDetail with an order SN and accessing the escrow amount from the response.

```php
$escrow = $client->Payment->getEscrowDetail('250922ABC123');
echo $escrow['escrow_amount'];   // amount released to you
```

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

### AddOnDeal reading method signatures

Source: https://github.com/ecomphp/shopee-php/blob/master/_autodocs/api-reference/Promotions.md

Method signatures for reading add-on deals and their items. getAddOnDealList uses GET with default parameters; the others use GET query parameters.

```php
public function getAddOnDealList($params = [])     // GET; defaults ['page_no' => 1, 'page_size' => 100, 'promotion_status' => 'all']
public function getAddOnDeal($add_on_deal_id)      // GET query {add_on_deal_id}
public function getAddOnDealMainItem($add_on_deal_id)  // GET query {add_on_deal_id}
public function getAddOnDealSubItem($add_on_deal_id)   // GET query {add_on_deal_id}
```

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

### Payout reconciliation example

Source: https://github.com/ecomphp/shopee-php/blob/master/_autodocs/api-reference/Payment.md

Example of using getPayoutDetail and getBillingTransactionInfo together for payout reconciliation. Retrieves payouts from the last 7 days and then fetches billing transactions for the first payout.

```php
$payouts = $client->Payment->getPayoutDetail(50, 1, strtotime('-7 days'), time());
$transactions = $client->Payment->getBillingTransactionInfo([
    'payout_id' => $payouts['payout_id'],
]);
```

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

### getAllCpcAdsDailyPerformance($start_date, $end_date) method signature

Source: https://github.com/ecomphp/shopee-php/blob/master/_autodocs/api-reference/Insights.md

Public method to get shop-level CPC multi-day daily performance. GET query: {start_date, end_date}.

```php
public function getAllCpcAdsDailyPerformance($start_date, $end_date)
```

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

### getReturnList usage example

Source: https://github.com/ecomphp/shopee-php/blob/master/_autodocs/api-reference/Order.md

Shows how to call getReturnList with a filter for return_status 'REQUESTED' and page_size 100.

```php
$returns = $client->Returns->getReturnList(['return_status' => 'REQUESTED', 'page_size' => 100]);
```

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

### ShopFlashSale usage example

Source: https://github.com/ecomphp/shopee-php/blob/master/_autodocs/api-reference/Promotions-Campaigns.md

Creates a flash-sale campaign by resolving a time slot and adding items with pricing and stock.

```php
$slot = $client->ShopFlashSale->getTimeSlotId(1700000000, 1700064000);
$fs = $client->ShopFlashSale->createShopFlashSale($slot['timeslot_id']);
$client->ShopFlashSale->addShopFlashSaleItems($fs['flash_sale_id'], [
    ['item_id' => 111, 'flash_sale_price' => 90000, 'flash_sale_stock' => 50],
]);
```

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

### getShopInstallmentStatus method signature

Source: https://github.com/ecomphp/shopee-php/blob/master/_autodocs/api-reference/Payment.md

Method signature for retrieving the shop's installment status.

```php
public function getShopInstallmentStatus()
```

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

### __get usage example with exception handling

Source: https://github.com/ecomphp/shopee-php/blob/master/_autodocs/api-reference/Client.md

Shows magic instantiation of Product resource and catching ShopeeException for invalid resource names. The exception message is 'Invalid resource DoesNotExist'.

```php
$client->Product->getItemList(['offset' => 0]);        // magic instantiation
try {
    $client->DoesNotExist;                              // ShopeeException
} catch (\EcomPHP\Shopee\Errors\ShopeeException $e) {
    echo $e->getMessage();                              // "Invalid resource DoesNotExist"
}
```

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

### getRecommendedKeywordList($item_id, $input_keyword = null) method signature

Source: https://github.com/ecomphp/shopee-php/blob/master/_autodocs/api-reference/Insights.md

Public method to get recommended keywords for an item. Accepts an optional seed keyword sent in the query. GET query: {item_id, input_keyword}.

```php
public function getRecommendedKeywordList($item_id, $input_keyword = null)
```

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

### Product::getItemList

Source: https://github.com/ecomphp/shopee-php/blob/master/_autodocs/api-reference/Product.md

Retrieves the list of items. This is a GET request to the product/get_item_list endpoint.

```APIDOC
## GET product/get_item_list

### Description
Retrieves the list of items.

### Method
GET

### Endpoint
product/get_item_list

### Response
Returns the decoded response array.
```

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

### Bundle Deal Usage Example

Source: https://github.com/ecomphp/shopee-php/blob/master/_autodocs/api-reference/Promotions.md

Shows how to add a bundle deal item and retrieve an ongoing bundle deal list using the client.

```php
$client->BundleDeal->addBundleDealItem($dealId, [
    ['item_id' => 111, 'item_price' => 90000, 'purchase_limit' => 3],
]);
$ongoing = $client->BundleDeal->getBundleDealList(['time_status' => 3]);
```

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

### Product::getItemBaseInfo

Source: https://github.com/ecomphp/shopee-php/blob/master/_autodocs/api-reference/Product.md

Retrieves base information for items. This is a GET request to the product/get_item_base_info endpoint.

```APIDOC
## GET product/get_item_base_info

### Description
Retrieves base information for items.

### Method
GET

### Endpoint
product/get_item_base_info

### Response
Returns the decoded response array.
```

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

### GET shop_flash_sale/get_shop_flash_sale_items

Source: https://github.com/ecomphp/shopee-php/blob/master/_autodocs/api-reference/Promotions-Campaigns.md

Retrieves items of a shop flash sale campaign with pagination.

```APIDOC
## GET shop_flash_sale/get_shop_flash_sale_items

### Description
Retrieves items of a shop flash sale campaign with pagination.

### Method
GET

### Endpoint
shop_flash_sale/get_shop_flash_sale_items

### Parameters
#### Query Parameters
- **flash_sale_id** (int) - Required - ID of the flash sale campaign (normalized with intval)
- **offset** (int) - Optional - Offset for pagination (default: 0)
- **limit** (int) - Optional - Limit for pagination (default: 10)

### Response
Returns a list of items in the flash sale campaign.
```

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

### Initialize Shopee Client

Source: https://github.com/ecomphp/shopee-php/blob/master/README.md

Create a new Shopee client instance using your partner ID and partner key from the Shopee Open Platform Console.

```php
use EcomPHP\Shopee\Client;

$partner_id = 'your_partner_id_here';
$partner_key = 'your_partner_key_here';

$client = new Client($partner_id, $partner_key);
```

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

### useDebugMode() example

Source: https://github.com/ecomphp/shopee-php/blob/master/_autodocs/api-reference/Client.md

Creates a client and enables debug mode, then sets the China region. The comment notes sandbox base URL and sandbox CN if combined.

```php
$client = new Client($partner_id, $partner_key);
$client->useDebugMode();            // sandbox base URL
$client->useChinaRegion();          // sandbox CN if combined (see baseUrl())
```

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

### TopPicks - getTopPicksList method signature (:22)

Source: https://github.com/ecomphp/shopee-php/blob/master/_autodocs/api-reference/Promotions-Campaigns.md

Returns TopPicks list via GET top_picks/get_top_picks_list with no parameters.

```php
public function getTopPicksList()
```

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

### Manual resource instantiation and binding

Source: https://github.com/ecomphp/shopee-php/blob/master/_autodocs/api-reference/Resource.md

Example of manually creating a resource and binding a client. This is unusual because resources are normally accessed via $client-><Resource> magic access.

```php
$resource = new EcomPHP\Shopee\Resources\Order(); // manual, unusual
$resource->useApiClient($client);
```

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

### setAccessToken() example

Source: https://github.com/ecomphp/shopee-php/blob/master/_autodocs/api-reference/Client.md

Sets the access token for a shop using the provided shop ID and token string.

```php
$client->setAccessToken(123456, 'shop_access_token_here');
```

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

### Client instantiation with Guzzle options

Source: https://github.com/ecomphp/shopee-php/blob/master/_autodocs/configuration.md

Example of creating a Client with custom timeout, connect_timeout, and proxy options. These override SDK defaults.

```php
$client = new Client('10001', 'secret_key', [
    'timeout' => 30,
    'connect_timeout' => 5,
    'proxy' => 'http://proxy.example:8080',
]);
```

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

### queryProof($return_sn)

Source: https://github.com/ecomphp/shopee-php/blob/master/_autodocs/api-reference/Order.md

Queries the proof associated with a return. Sends a GET request to retrieve proof details.

```APIDOC
## GET returns/query_proof

### Description
Queries the proof associated with a return.

### Method
GET

### Endpoint
returns/query_proof

### Parameters
#### Query Parameters
- **return_sn** (string) - Required - The return serial number.

### Request Example
GET returns/query_proof?return_sn=123456

### Response
#### Success Response (200)
- **proof** (object) - Proof details.

#### Response Example
{
  "proof": {}
}
```

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

### Chat::getUnreadConversationCount

Source: https://github.com/ecomphp/shopee-php/blob/master/_autodocs/api-reference/Communication.md

Gets the count of unread seller chat conversations. This method corresponds to the GET sellerchat/get_unread_conversation_count endpoint.

```APIDOC
## GET sellerchat/get_unread_conversation_count

### Description
Gets the count of unread seller chat conversations.

### Method
GET

### Endpoint
sellerchat/get_unread_conversation_count

```

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

### __construct($partner_id, $partner_key, $options = [])

Source: https://github.com/ecomphp/shopee-php/blob/master/_autodocs/api-reference/Client.md

Creates a new Shopee client instance with partner credentials and optional Guzzle options. Stores options for later merging with SDK defaults.

```APIDOC
## __construct($partner_id, $partner_key, $options = [])

### Description
Creates a new Shopee client instance with partner credentials and optional Guzzle options. Stores options for later merging with SDK defaults.

### Method
Constructor

### Parameters
#### Parameters
- **$partner_id** (mixed) - Required - Partner ID assigned in the Shopee Open Platform Console
- **$partner_key** (mixed) - Required - Partner key (secret) used to HMAC-sign every request
- **$options** (array) - Optional - Extra options merged into the Guzzle client constructor (default: `[]`)

### Request Example
```php
$client = new Client($partner_id, $partner_key, $options);
```

### Response
#### Success Response
- Returns a new `Client` instance.

#### Response Example
```php
$client = new Client(123, 'secret');
```
```

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

### Dispute workflow example

Source: https://github.com/ecomphp/shopee-php/blob/master/_autodocs/api-reference/Order.md

Shows a try-catch block that converts an image, disputes a return, and uploads proof, catching ShopeeException for error logging.

```php
try {
    $client->Returns->convertImage($returnSn, '/tmp/evidence.jpg');   // -> returns image URL
    $client->Returns->dispute($returnSn, 'me@example.com', [
        'reason' => 'Item not as described',
    ]);
    $client->Returns->uploadProof($returnSn, 'https://.../evidence.jpg', 'Photo of defect');
} catch (\EcomPHP\Shopee\Errors\ShopeeException $e) {
    error_log($e->getMessage());
}
```

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

### getShopToggleInfo() method signature

Source: https://github.com/ecomphp/shopee-php/blob/master/_autodocs/api-reference/Insights.md

Public method to get shop-level ads toggle status (on/off) via GET request.

```php
public function getShopToggleInfo()
```

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

### getAllCpcAdsHourlyPerformance($performance_date) method signature

Source: https://github.com/ecomphp/shopee-php/blob/master/_autodocs/api-reference/Insights.md

Public method to get shop-level CPC single-date hourly performance. GET query: {performance_date}.

```php
public function getAllCpcAdsHourlyPerformance($performance_date)
```

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

### Canonical usage of Client class

Source: https://github.com/ecomphp/shopee-php/blob/master/_autodocs/README.md

Shows the standard way to instantiate the Shopee client, set the access token for a shop, and fetch orders. Note that useDebugMode() and useChinaRegion() return void, so they cannot be chained with other setters.

```php
use EcomPHP\Shopee\Client;

$client = new Client($partner_id, $partner_key);
$client->setAccessToken($shop_id, $access_token);   // authorized shop scope
$orders = $client->Order->getOrderList(['order_status' => 'READY_TO_SHIP']);

// global sandbox + regional modes
$client->useDebugMode()->useChinaRegion();          // note: returns void, chain on other setters
```

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

### getRecommendedItemList() method signature

Source: https://github.com/ecomphp/shopee-php/blob/master/_autodocs/api-reference/Insights.md

Public method to get recommended SKUs with tags (top search / best selling / best ROI) via GET request.

```php
public function getRecommendedItemList()
```

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

### getTotalBalance() method signature

Source: https://github.com/ecomphp/shopee-php/blob/master/_autodocs/api-reference/Insights.md

Public method to get the seller's real-time total ads credit (paid + free credits) via GET request.

```php
public function getTotalBalance()
```

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

### validatePushMechanismRequest usage example

Source: https://github.com/ecomphp/shopee-php/blob/master/_autodocs/api-reference/Client.md

Example of calling validatePushMechanismRequest in a callback endpoint. When validation fails, the endpoint returns HTTP 401 and exits; the webhook_receive_url is derived from $_SERVER by default.

```php
// in the callback endpoint that receives Shopee push notifications
if (!$client->validatePushMechanismRequest()) {
    http_response_code(401);   // receives webhook_receive_url from $_SERVER by default
    exit;
}
```

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

### initVideoUpload

Source: https://github.com/ecomphp/shopee-php/blob/master/_autodocs/api-reference/Communication.md

Initializes a video upload session by providing the file's MD5 hash and size. This is the first step in the video upload pipeline.

```APIDOC
## POST JSON {file_md5, file_size}

### Description
Initializes a video upload session by providing the file's MD5 hash and size. This is the first step in the video upload pipeline.

### Method
POST

### Endpoint
(Not specified in source)

### Parameters
#### Request Body
- **file_md5** (string) - Required - MD5 hash of the video file.
- **file_size** (integer) - Required - Size of the video file in bytes.

### Request Example
{
  "file_md5": "string",
  "file_size": 0
}

### Response
#### Success Response (200)
- **video_upload_id** (string) - The ID of the video upload session.

#### Response Example
{
  "video_upload_id": "string"
}
```

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

### Clone the repository locally

Source: https://github.com/ecomphp/shopee-php/blob/master/CONTRIBUTING.md

Clones the forked repository and navigates into the project directory.

```bash
git clone https://github.com/your-username/shopee-php.git
cd shopee-php
```

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

### offer($return_sn, $proposed_solution, $proposed_adjusted_refund_amount = null)

Source: https://github.com/ecomphp/shopee-php/blob/master/_autodocs/api-reference/Order.md

Submits a proposed solution for a return, optionally including an adjusted refund amount. Sends a POST request with return_sn and proposed_solution, and appends proposed_adjusted_refund_amount if provided.

```APIDOC
## POST returns/offer

### Description
Submits a proposed solution for a return, optionally including an adjusted refund amount.

### Method
POST

### Endpoint
returns/offer

### Parameters
#### Request Body
- **return_sn** (string) - Required - The return serial number.
- **proposed_solution** (string) - Required - The proposed solution.
- **proposed_adjusted_refund_amount** (number) - Optional - Adjusted refund amount.

### Request Example
POST returns/offer
{
  "return_sn": "123456",
  "proposed_solution": "Refund 50%",
  "proposed_adjusted_refund_amount": 5.00
}

### Response
#### Success Response (200)
- **success** (boolean) - Indicates if the offer was submitted.

#### Response Example
{
  "success": true
}
```

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

### Create a feature branch

Source: https://github.com/ecomphp/shopee-php/blob/master/CONTRIBUTING.md

Creates a new feature branch with a descriptive name, showing two example branch names.

```bash
git checkout -b feature/add-logistics-endpoints
# or
git checkout -b fix/auth-token-refresh
```

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

### GET shop_flash_sale/get_item_criteria

Source: https://github.com/ecomphp/shopee-php/blob/master/_autodocs/api-reference/Promotions-Campaigns.md

Retrieves the eligibility criteria for flash-sale items.

```APIDOC
## GET shop_flash_sale/get_item_criteria

### Description
Retrieves the eligibility criteria for flash-sale items.

### Method
GET

### Endpoint
shop_flash_sale/get_item_criteria

### Parameters
None

### Response
Returns the eligibility criteria for flash-sale items.
```

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

### Client constructor signature

Source: https://github.com/ecomphp/shopee-php/blob/master/_autodocs/configuration.md

Constructor signature for the Shopee Client. Requires partner ID and partner key, with optional extra options array.

```php
public function __construct($partner_id, $partner_key, $options = [])
```

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

### GET shop_flash_sale/get_time_slot_id

Source: https://github.com/ecomphp/shopee-php/blob/master/_autodocs/api-reference/Promotions-Campaigns.md

Resolves the slot ID for a flash-sale campaign window.

```APIDOC
## GET shop_flash_sale/get_time_slot_id

### Description
Resolves the slot ID for a flash-sale campaign window.

### Method
GET

### Endpoint
shop_flash_sale/get_time_slot_id

### Parameters
#### Query Parameters
- **start_time** (int) - Required - Unix timestamp for the start of the campaign window
- **end_time** (int) - Required - Unix timestamp for the end of the campaign window

### Response
Returns the timeslot ID for the given window.
```

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

### Returns::queryProof

Source: https://github.com/ecomphp/shopee-php/blob/master/_autodocs/api-reference/Order.md

Queries proof for a return/refund.

```APIDOC
## GET returns/query_proof

### Description
Queries proof for a return/refund.

### Method
GET

### Endpoint
returns/query_proof

### Parameters
No parameters documented.

### Response
Returns the decoded response array.
```

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

### Logistic::getChannelList

Source: https://github.com/ecomphp/shopee-php/blob/master/_autodocs/api-reference/Logistics.md

Retrieves the channel list. This is a GET request to the logistics/get_channel_list endpoint.

```APIDOC
## GET logistics/get_channel_list

### Description
Retrieves the channel list.

### Method
GET

### Endpoint
logistics/get_channel_list

### Parameters
#### Query Parameters
- **region** (string) - Required - The region code.

### Response
#### Success Response (200)
- **response** (array) - The decoded response array.

#### Response Example
{
  "response": {}
}
```

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

### Chat::sendMessage() usage example

Source: https://github.com/ecomphp/shopee-php/blob/master/_autodocs/api-reference/Communication.md

Shows how to send a text message and an image message using the Chat client. Image messages require uploading the image first to obtain a URL.

```php
$client->Chat->sendMessage(100001, 1, 'Hello, how can I help?');
// image message: upload first, then send the URL
$client->Chat->sendMessage(100001, 2, ['image_url' => $imageUrl]);
```

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

### Logistic::getAddressList

Source: https://github.com/ecomphp/shopee-php/blob/master/_autodocs/api-reference/Logistics.md

Retrieves the address list. This is a GET request to the logistics/get_address_list endpoint.

```APIDOC
## GET logistics/get_address_list

### Description
Retrieves the address list.

### Method
GET

### Endpoint
logistics/get_address_list

### Parameters
#### Query Parameters
- **region** (string) - Required - The region code.

### Response
#### Success Response (200)
- **response** (array) - The decoded response array.

#### Response Example
{
  "response": {}
}
```

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

### __get($resourceName)

Source: https://github.com/ecomphp/shopee-php/blob/master/_autodocs/api-reference/Client.md

Magic resource accessor that lazily instantiates and returns a resource object (e.g., Product, Order) for the given name. Throws ShopeeException for unknown resources.

```APIDOC
## __get($resourceName)

### Description
Magic resource accessor that lazily instantiates and returns a resource object (e.g., Product, Order) for the given name. Throws ShopeeException for unknown resources.

### Method
__get

### Parameters
#### Parameters
- **$resourceName** (mixed) - Required - Property name accessed, e.g. `Product`, `Order`, `Logistic`

### Request Example
```php
$client->Product->getItemList(['offset' => 0]); // magic instantiation
try {
    $client->DoesNotExist; // ShopeeException
} catch (\EcomPHP\Shopee\Errors\ShopeeException $e) {
    echo $e->getMessage(); // "Invalid resource DoesNotExist"
}
```

### Response
#### Success Response
- **mixed** - Returns a new instance of the resource class.

#### Error Response
- **EcomPHP\Shopee\Errors\ShopeeException** - Thrown when resource name is unknown or object is not a Resource.
```

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

### Product::getComment

Source: https://github.com/ecomphp/shopee-php/blob/master/_autodocs/api-reference/Product.md

Retrieves comments for items. This is a GET request to the product/get_comment endpoint.

```APIDOC
## GET product/get_comment

### Description
Retrieves comments for items.

### Method
GET

### Endpoint
product/get_comment

### Response
Returns the decoded response array.
```

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

### auth()

Source: https://github.com/ecomphp/shopee-php/blob/master/_autodocs/api-reference/Client.md

Returns a new EcomPHP\Shopee\Auth instance bound to this client.

```APIDOC
## auth()

### Description
Returns a new EcomPHP\Shopee\Auth instance bound to this client.

### Method
auth

### Parameters
None

### Request Example
```php
$auth = $client->auth();
```

### Response
#### Success Response
- Returns a new `EcomPHP\Shopee\Auth` instance.

#### Response Example
```php
$auth = $client->auth();
```
```

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

### Product::getBrandList

Source: https://github.com/ecomphp/shopee-php/blob/master/_autodocs/api-reference/Product.md

Retrieves the list of brands. This is a GET request to the product/get_brand_list endpoint.

```APIDOC
## GET product/get_brand_list

### Description
Retrieves the list of brands.

### Method
GET

### Endpoint
product/get_brand_list

### Response
Returns the decoded response array.
```

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

### FollowPrize class lifecycle methods

Source: https://github.com/ecomphp/shopee-php/blob/master/_autodocs/api-reference/Promotions-Campaigns.md

Defines the signatures for creating, updating, deleting, and ending follow-prize campaigns.

```php
public function addFollowPrize($data)                     // :22 POST; $data verbatim JSON
public function updateFollowPrize($data)                  // :59 POST; $data verbatim JSON (includes campaign_id)
public function deleteFollowPrize($campaign_id)           // :33 POST JSON {campaign_id}
public function endFollowPrize($campaign_id)              // :46 POST JSON {campaign_id}
```

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

### GET shop_flash_sale/get_shop_flash_sale

Source: https://github.com/ecomphp/shopee-php/blob/master/_autodocs/api-reference/Promotions-Campaigns.md

Retrieves a specific shop flash sale campaign by ID.

```APIDOC
## GET shop_flash_sale/get_shop_flash_sale

### Description
Retrieves a specific shop flash sale campaign by ID.

### Method
GET

### Endpoint
shop_flash_sale/get_shop_flash_sale

### Parameters
#### Query Parameters
- **flash_sale_id** (int) - Required - ID of the flash sale campaign (normalized with intval)

### Response
Returns the flash sale campaign details.
```

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

### Get Product Item List

Source: https://github.com/ecomphp/shopee-php/blob/master/README.md

Fetch product details and stock information from your store. Requires a valid access_token and shop_id.

```php
$products = $client->Product->getItemList([
    'offset' => 0,
    'page_size' => 50,
    'item_status' => 'NORMAL',
]);
```

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

### GET top_picks/get_top_picks_list

Source: https://github.com/ecomphp/shopee-php/blob/master/_autodocs/api-reference/Promotions-Campaigns.md

Retrieves the list of top picks (curated collections) for the shopfront.

```APIDOC
## GET top_picks/get_top_picks_list

### Description
Retrieves the list of top picks (curated collections) for the shopfront.

### Method
GET

### Endpoint
top_picks/get_top_picks_list

### Parameters
None

### Response
Returns a list of top picks collections.
```

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

### Bundle Deal Reading Method Signatures

Source: https://github.com/ecomphp/shopee-php/blob/master/_autodocs/api-reference/Promotions.md

Declares methods for retrieving bundle deal lists and details, with GET queries and default parameters.

```php
public function getBundleDealList($params = [])  // :47 GET; defaults ['page_no' => 1, 'page_size' => 100, 'time_status' => 1]
public function getBundleDeal($bundle_deal_id)   // :62 GET query {bundle_deal_id}
public function getBundleDealItem($bundle_deal_id) // :75 GET query {bundle_deal_id}
```

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

### createAuthRequest($redirect_uri, $return_url = false)

Source: https://github.com/ecomphp/shopee-php/blob/master/_autodocs/api-reference/Auth.md

Builds the seller-login authorization URL. Can either return the URL or redirect the user to it directly.

```APIDOC
## createAuthRequest($redirect_uri, $return_url = false)

### Description
Builds the seller-login URL for OAuth authorization. If `$return_url` is true, the URL is returned; otherwise, the script redirects to the URL and exits.

### Method
GET

### Endpoint
`/api/v2/shop/auth_partner`

### Parameters
#### Path Parameters
- None

#### Query Parameters
- **redirect_uri** (string) - Required - Your OAuth callback URL
- **return_url** (bool) - Optional - If true, returns the URL; if false, redirects and exits. Default: `false`

### Request Example
```php
$authUrl = $auth->createAuthRequest('https://myapp.example/oauth/callback', true);
header('Location: ' . $authUrl);
```

### Response
#### Success Response (200)
- **url** (string) - The authorization URL (when `$return_url` is true)

#### Response Example
```php
// When $return_url = true, returns the URL string
$authUrl = $auth->createAuthRequest('https://myapp.example/oauth/callback', true);
```

### Error Handling
No explicit error handling documented.
```

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

### FirstMile::getUnbindOrderList

Source: https://github.com/ecomphp/shopee-php/blob/master/_autodocs/api-reference/Logistics.md

Retrieves the list of unbind orders. This is a GET request to the first_mile/get_unbind_order_list endpoint.

```APIDOC
## GET first_mile/get_unbind_order_list

### Description
Retrieves the list of unbind orders.

### Method
GET

### Endpoint
first_mile/get_unbind_order_list

### Parameters
#### Query Parameters
- **region** (string) - Required - The region code.

### Response
#### Success Response (200)
- **response** (array) - The decoded response array.

#### Response Example
{
  "response": {}
}
```

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

### useDebugMode()

Source: https://github.com/ecomphp/shopee-php/blob/master/_autodocs/api-reference/Client.md

Toggles debug mode to use the Shopee sandbox environment. Call region setters after this method.

```APIDOC
## useDebugMode()

### Description
Toggles debug mode to use the Shopee sandbox environment. Call region setters after this method.

### Method
useDebugMode

### Parameters
None

### Request Example
```php
$client->useDebugMode();
```

### Response
#### Success Response
- Returns `null` (void).

#### Response Example
```php
$client->useDebugMode();
```
```

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

### Logistic::getTrackingInfo

Source: https://github.com/ecomphp/shopee-php/blob/master/_autodocs/api-reference/Logistics.md

Retrieves tracking information for an order. This is a GET request to the logistics/get_tracking_info endpoint.

```APIDOC
## GET logistics/get_tracking_info

### Description
Retrieves tracking information for an order.

### Method
GET

### Endpoint
logistics/get_tracking_info

### Parameters
#### Query Parameters
- **order_sn** (string) - Required - The order serial number.
- **region** (string) - Required - The region code.

### Response
#### Success Response (200)
- **response** (array) - The decoded response array.

#### Response Example
{
  "response": {}
}
```

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

### Logistic::getTrackingNumber

Source: https://github.com/ecomphp/shopee-php/blob/master/_autodocs/api-reference/Logistics.md

Retrieves the tracking number for an order. This is a GET request to the logistics/get_tracking_number endpoint.

```APIDOC
## GET logistics/get_tracking_number

### Description
Retrieves the tracking number for an order.

### Method
GET

### Endpoint
logistics/get_tracking_number

### Parameters
#### Query Parameters
- **order_sn** (string) - Required - The order serial number.
- **region** (string) - Required - The region code.

### Response
#### Success Response (200)
- **response** (array) - The decoded response array.

#### Response Example
{
  "response": {}
}
```

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

### Logistic::getShippingParameter

Source: https://github.com/ecomphp/shopee-php/blob/master/_autodocs/api-reference/Logistics.md

Retrieves shipping parameters for an order. This is a GET request to the logistics/get_shipping_parameter endpoint.

```APIDOC
## GET logistics/get_shipping_parameter

### Description
Retrieves shipping parameters for an order.

### Method
GET

### Endpoint
logistics/get_shipping_parameter

### Parameters
#### Query Parameters
- **order_sn** (string) - Required - The order serial number.
- **region** (string) - Required - The region code.

### Response
#### Success Response (200)
- **response** (array) - The decoded response array.

#### Response Example
{
  "response": {}
}
```

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

### Discount Methods

Source: https://github.com/ecomphp/shopee-php/blob/master/_autodocs/api-reference/Promotions.md

The Discount resource exposes 9 methods to manage discounts, each mapped to a specific HTTP endpoint.

```APIDOC
## Discount API

### addDiscount

- **Method:** POST
- **Endpoint:** `discount/add_discount`
- **Description:** Creates a new discount.

### addDiscountItem

- **Method:** POST
- **Endpoint:** `discount/add_discount_item`
- **Description:** Adds an item to a discount.

### deleteDiscount

- **Method:** POST
- **Endpoint:** `discount/delete_discount`
- **Description:** Deletes a discount.

### deleteDiscountItem

- **Method:** POST
- **Endpoint:** `discount/delete_discount_item`
- **Description:** Deletes an item from a discount.

### getDiscount

- **Method:** GET
- **Endpoint:** `discount/get_discount`
- **Description:** Retrieves a specific discount.

### getDiscountList

- **Method:** GET
- **Endpoint:** `discount/get_discount_list`
- **Description:** Retrieves a list of discounts.

### updateDiscount

- **Method:** POST
- **Endpoint:** `discount/update_discount`
- **Description:** Updates a discount.

### updateDiscountItem

- **Method:** POST
- **Endpoint:** `discount/update_discount_item`
- **Description:** Updates an item of a discount.

### endDiscount

- **Method:** POST
- **Endpoint:** `discount/end_discount`
- **Description:** Ends a discount.

```

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

### ShopCategory::getItemList

Source: https://github.com/ecomphp/shopee-php/blob/master/_autodocs/api-reference/Product.md

Retrieves items in a shop category. This is a GET request to the shop_category/get_item_list endpoint.

```APIDOC
## GET shop_category/get_item_list

### Description
Retrieves items in a shop category.

### Method
GET

### Endpoint
shop_category/get_item_list

### Response
Returns the decoded response array.
```

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

### Chat::uploadImage() and sendMessage() usage example

Source: https://github.com/ecomphp/shopee-php/blob/master/_autodocs/api-reference/Communication.md

Shows how to upload an image using SplFileInfo and then send it as an image message using the returned image URL.

```php
$upload = $client->Chat->uploadImage(new \SplFileInfo('/tmp/photo.jpg'));
$client->Chat->sendMessage($userId, 2, ['image_url' => $upload['image_url']]);
```

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

### ShopCategory::getShopCategoryList

Source: https://github.com/ecomphp/shopee-php/blob/master/_autodocs/api-reference/Product.md

Retrieves the list of shop categories. This is a GET request to the shop_category/get_shop_category_list endpoint.

```APIDOC
## GET shop_category/get_shop_category_list

### Description
Retrieves the list of shop categories.

### Method
GET

### Endpoint
shop_category/get_shop_category_list

### Response
Returns the decoded response array.
```

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

### POST shop_flash_sale/create_shop_flash_sale

Source: https://github.com/ecomphp/shopee-php/blob/master/_autodocs/api-reference/Promotions-Campaigns.md

Creates a new shop flash sale campaign for the given timeslot.

```APIDOC
## POST shop_flash_sale/create_shop_flash_sale

### Description
Creates a new shop flash sale campaign for the given timeslot.

### Method
POST

### Endpoint
shop_flash_sale/create_shop_flash_sale

### Parameters
#### Request Body
- **timeslot_id** (int) - Required - The timeslot ID (normalized with intval)

### Request Example
{
  "timeslot_id": 123
}

### Response
Returns the created flash sale campaign.
```

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

### Product::getBatchTaskResult

Source: https://github.com/ecomphp/shopee-php/blob/master/_autodocs/api-reference/Product.md

Retrieves the result of a batch task. This is a GET request to the product/get_batch_task_result endpoint.

```APIDOC
## GET product/get_batch_task_result

### Description
Retrieves the result of a batch task.

### Method
GET

### Endpoint
product/get_batch_task_result

### Response
Returns the decoded response array.
```

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

### Product::batchAddItem

Source: https://github.com/ecomphp/shopee-php/blob/master/_autodocs/api-reference/Product.md

Adds multiple items in a batch. This is a POST request to the product/batch_add_item endpoint.

```APIDOC
## POST product/batch_add_item

### Description
Adds multiple items in a batch.

### Method
POST

### Endpoint
product/batch_add_item

### Response
Returns the decoded response array.
```

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

### auth() signature

Source: https://github.com/ecomphp/shopee-php/blob/master/_autodocs/api-reference/Client.md

Returns a new EcomPHP\Shopee\Auth instance bound to the client.

```php
public function auth()
```
Tokens:
Raw