### Initialize and Use Shopee PHP SDK

Source: https://github.com/ecomphp/shopee-php/blob/master/_autodocs/00-START-HERE.md

Quick start example demonstrating client initialization, OAuth2 authentication flow, and basic API calls for retrieving product and order lists. Ensure you have your partner ID and key, and handle the OAuth callback with code and shop ID.

```php
use EcomPHP\Shopee\Client;

// 1. Initialize
$client = new Client('partner_id', 'partner_key');

// 2. Authenticate (OAuth2)
$auth = $client->auth();
$auth_url = $auth->createAuthRequest('https://myapp.com/callback', true);
// ... user visits $auth_url ...
// ... receives callback with code & shop_id ...
$tokens = $auth->getToken($_GET['code'], $_GET['shop_id']);

// 3. Use APIs
$client->setAccessToken($_GET['shop_id'], $tokens['access_token']);
$items = $client->Product->getItemList(['page_size' => 50]);
$orders = $client->Order->getOrderList();
```

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

### Complete Shipping Flow Example

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

Demonstrates a full shipping process: getting parameters, initiating shipment with pickup, retrieving tracking numbers, and creating shipping documents.

```php
// 1. Get shipping parameters
$ship_params = $client->Logistic->getShippingParameter('2024061234567890');

// 2. Initiate shipment with pickup
$ship_result = $client->Logistic->shipOrder(
    '2024061234567890',
    '',
    ['address_id' => 123456, 'pickup_time_id' => 1]
);

// 3. Get tracking number
$tracking = $client->Logistic->getTrackingNumber('2024061234567890');

// 4. Create shipping document
$doc = $client->Logistic->createShippingDocument([
    [
        'order_sn' => '2024061234567890',
        'package_number' => '',
        'tracking_number' => $tracking['tracking_number'],
        'shipping_document_type' => 'LABEL',
    ]
]);
```

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

### Install Shopee PHP Client with Composer

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

Use Composer to install the Shopee PHP client library. This is the initial step before configuring and using the client.

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

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

### Make an API Call to Get Product List

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

Execute an API call to retrieve a list of products using the Shopee PHP SDK. This example demonstrates fetching items with a 'page_size' filter and includes basic error handling for Shopee exceptions.

```php
try {
    $result = $client->Product->getItemList(['page_size' => 50]);
} catch (ShopeeException $e) {
    // Handle error
}
```

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

### Get Product Details by IDs

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

Retrieve detailed information for specific products using their item IDs. This example shows how to fetch and iterate through the list of product details.

```php
$item_ids = [123456789, 987654321];
$details = $client->Product->getItemBaseInfo($item_ids, true, true);

foreach ($details['item_list'] as $item) {
    echo "Name: {$item['item_name']}\n";
    echo "Price: {$item['price']}\n";
    echo "Stock: {$item['stock']}\n";
}
```

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

### Escrow Detail Response Example

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

Example structure of the response when retrieving escrow details.

```json
[
    'order_sn' => '2024061234567890',
    'order_total' => 199.99,
    'commission' => 10.00,
    'seller_received_amount' => 189.99,
    'escrow_status' => 'RELEASED',
    'release_time' => 1234567890,
    'breakdown' => [
        'sale_amount' => 199.99,
        'platform_fee' => -5.00,
        'seller_subsidy' => 5.00,
    ]
]
```

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

### Payout Detail Response Example

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

Example structure of the response when retrieving payout details.

```json
[
    'payout_list' => [
        [
            'payout_id' => 'PAY123456',
            'payout_time' => 1234567890,
            'amount' => 5000.00,
            'currency' => 'SGD',
            'fx_rate' => 1.25,
            'order_income' => 5100.00,
            'order_deduction' => -50.00,
            'adjustment' => -50.00,
        ]
    ],
    'total_amount' => 5000.00,
    'pagination' => [
        'page_no' => 1,
        'page_size' => 50,
    ]
]
```

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

### Wallet Transaction List Response Example

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

Example structure of the response when retrieving a list of wallet transactions.

```json
[
    'transaction_list' => [
        [
            'transaction_id' => 'TXN123456',
            'create_time' => 1234567890,
            'amount' => 500.00,
            'wallet_type' => 'MAIN',
            'transaction_type' => 'ORDER_INCOME',
            'money_flow' => 'IN',
            'description' => 'Order payment received',
        ]
    ],
    'pagination' => [
        'page_no' => 1,
        'page_size' => 50,
        'total' => 150,
    ]
]
```

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

### getShopInstallmentStatus

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

Retrieves the current installment payment status for the shop.

```APIDOC
## getShopInstallmentStatus

### Description
Get current installment status for the shop.

### Method
GET

### Endpoint
/payment/shop/installment/get

### Response
#### Success Response (200)
- **installment_status** (int) - The current installment status (1 for enabled, 0 for disabled).

#### Response Example
```json
{
  "installment_status": 1
}
```
```

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

### AuthorizationException Example

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

The AuthorizationException is thrown for authentication and authorization errors. This example demonstrates how to catch this exception and handle specific error codes.

```APIDOC
## AuthorizationException

### Description
Exception thrown for authentication and authorization errors.

**Extends**: `ShopeeException`

Thrown when:
- Authorization code is invalid or expired (`invalid_code`)
- Access token is invalid (`invalid_acceess_token`)
- Refresh token has expired (`refresh_token_expired`)
- Shop ID is invalid
- Partner credentials are invalid

### Example
```php
use EcomPHP\Shopee\Errors\AuthorizationException;

try {
    $tokens = $auth->getToken($code, $shop_id);
} catch (AuthorizationException $e) {
    $error_code = $e->getCode();
    
    if ($error_code === 'invalid_code') {
        // Authorization code invalid or expired
        // Redirect user to authorize again
    } elseif ($error_code === 'refresh_token_expired') {
        // Need full re-authorization
        // Clear stored tokens and restart OAuth flow
    } else {
        // Other authorization error
    }
}
```
```

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

### setShopInstallmentStatus

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

Enables or disables the installment payment option for the entire shop.

```APIDOC
## setShopInstallmentStatus

### Description
Enable or disable installment payment option for the shop.

### Method
POST

### Endpoint
/payment/shop/installment/set

### Parameters
#### Request Body
- **installment_status** (int) - Yes - 0 to disable, 1 to enable

### Request Example
```json
{
  "installment_status": 1
}
```

### Response
#### Success Response (200)
- **status** (string) - Operation result message.

#### Response Example
```json
{
  "status": "success"
}
```
```

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

### Get Shop Info

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

Retrieves basic information about the seller's shop.

```APIDOC
## GET /shop/get_shop_info

### Description
Retrieves basic information about the seller's shop.

### Method
GET

### Endpoint
/shop/get_shop_info
```

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

### Get List of Boosted Products

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

Retrieve a list of all products currently being promoted. Iterate through the 'data' key to access individual item details.

```php
$boosted = $client->Product->getBoostedList();
foreach ($boosted['data'] as $item) {
    echo "Item {$item['item_id']} is boosted\n";
}
```

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

### getShipmentList

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

Get orders ready to ship (READY_TO_SHIP status). This method is used to retrieve a list of orders that are prepared for shipment.

```APIDOC
## getShipmentList

### Description
Get orders ready to ship (READY_TO_SHIP status).

### Method
GET

### Endpoint
/api/v1/shipments.get

### Parameters
#### Query Parameters
- **page_size** (int) - Required by API - always 20
- Additional filters per Shopee API

### Request Example
```php
$shipments = $client->Order->getShipmentList();
```

### Response
#### Success Response (200)
- **array** - List of orders ready to ship
```

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

### Get Shop Installment Status

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

Retrieves the current installment status for the shop. This indicates whether installment payments are enabled.

```APIDOC
## GET /payment/get_shop_installment_status

### Description
Retrieves the current installment status for the shop.

### Method
GET

### Endpoint
/payment/get_shop_installment_status

### Response
#### Success Response (200)
- **installment_status** (integer) - The current installment status (e.g., 1 for enabled, 0 for disabled).
```

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

### Get Item Installment Status

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

Retrieves the installment status for a specific item. This indicates whether installment payments are enabled for that item.

```APIDOC
## POST /payment/get_item_installment_status

### Description
Retrieves the installment status for a specific item.

### Method
POST

### Endpoint
/payment/get_item_installment_status

### Parameters
#### Request Body
- **item_id** (string) - Required - The ID of the item.

### Request Example
{
  "item_id": "123456789"
}

### Response
#### Success Response (200)
- **installment_status** (integer) - The current installment status for the item (e.g., 1 for enabled, 0 for disabled).
```

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

### Quick Start: Initialize Shopee PHP Client

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

Demonstrates how to initialize the Shopee PHP client with partner credentials and set an access token for authenticated API requests. It also shows how to access different API resources like Product and Order.

```php
use EcomPHP\Shopee\Client;

// Initialize client
$client = new Client($partner_id, $partner_key);

// Set access token for authenticated requests
$client->setAccessToken($shop_id, $access_token);

// Access resources via magic properties
$products = $client->Product->getItemList(['offset' => 0, 'page_size' => 20]);
$orders = $client->Order->getOrderList(['time_from' => time() - 86400]);
```

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

### Environment Variables for Shopee Configuration

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

Store sensitive Shopee API credentials and settings in environment variables for security. This example shows how to export variables and use them in PHP.

```bash
export SHOPEE_PARTNER_ID="your_partner_id"
export SHOPEE_PARTNER_KEY="your_partner_key"
export SHOPEE_SHOP_ID="your_shop_id"
export SHOPEE_ACCESS_TOKEN="your_access_token"
export SHOPEE_REFRESH_TOKEN="your_refresh_token"
export SHOPEE_REGION="default"  # or "china", "brazil"
export SHOPEE_DEBUG="false"
```

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

### Typical Shopee SDK Initialization Flow

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

A step-by-step guide for initializing the Shopee SDK. Covers client creation, region setting, OAuth flow, token handling, and making API calls.

```php
// 1. Create client with credentials
$client = new Client(
    getenv('SHOPEE_PARTNER_ID'),
    getenv('SHOPEE_PARTNER_KEY'),
    ['timeout' => 30]
);

// 2. Set region if needed
if (getenv('SHOPEE_REGION') === 'china') {
    $client->useChinaRegion();
}

// 3. Perform OAuth flow (on first authorization)
$auth = $client->auth();
$auth_url = $auth->createAuthRequest('https://myapp.com/callback', true);
// ... redirect user to $auth_url

// 4. In callback handler, get tokens
$tokens = $auth->getToken($_GET['code'], $_GET['shop_id']);
// ... save tokens to database

// 5. For subsequent requests, set access token
$client->setAccessToken($shop_id, $access_token);

// 6. Make API calls
$items = $client->Product->getItemList();
```

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

### Get Current Shop Installment Status

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

Check if the installment payment option is currently enabled or disabled for your shop. This helps in verifying configuration.

```php
$status = $client->Payment->getShopInstallmentStatus();

if ($status['installment_status'] === 1) {
    echo "Installment is enabled\n";
}
```

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

### Get and Process New Orders

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

Fetches orders from the last 24 hours and processes each item within those orders. Requires the Shopee client to be initialized.

```php
// Get orders from last 24 hours
$orders = $client->Order->getOrderList([
    'time_from' => time() - 86400,
    'time_to' => time(),
    'page_size' => 100,
]);

foreach ($orders['order_list'] as $order) {
    $order_sn = $order['order_sn'];
    
    // Get full details
    $detail = $client->Order->getOrderDetail($order_sn);
    
    // Process each item
    foreach ($detail[0]['item_list'] as $item) {
        echo "Order: $order_sn\n";
        echo "Item: {$item['item_name']}\n";
        echo "Quantity: {$item['quantity']}\n";
    }
}
```

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

### Initialize Shopee Client with Constructor Options

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

Instantiate the Shopee Client with custom options like timeouts, SSL verification, headers, and proxy settings.

```php
new Client($partner_id, $partner_key, [
    'timeout' => 30,           // Request timeout
    'connect_timeout' => 5,    // Connection timeout
    'verify' => true,          // SSL verification
    'headers' => [...],        // Custom headers
    'proxy' => '...',          // Proxy server
])
```

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

### Get Installment Tenures Available for Items

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

Retrieve the list of available installment payment durations for specified items. This is applicable only in TH and TW regions.

```php
$status = $client->Payment->getItemInstallmentStatus([123456789, 987654321]);

foreach ($status['item_list'] as $item) {
    echo "Item {" . $item['item_id'] . "}: tenures = " . implode(',', $item['tenure_list']) . "\n";
}
```

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

### Get Payment Method List

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

Retrieves a list of available payment methods. This can be used to identify supported installment payment options.

```APIDOC
## GET /payment/get_payment_method_list

### Description
Retrieves a list of available payment methods.

### Method
GET

### Endpoint
/payment/get_payment_method_list

### Response
#### Success Response (200)
- **payment_method_list** (array) - A list of payment methods.
  - **payment_method_name** (string) - The name of the payment method.
```

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

### Get Billing Transaction Information

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

Retrieve billing transaction details. This method accepts an optional array of query parameters, such as start and end times.

```php
public function getBillingTransactionInfo($params = []): array
```

```php
$billing = $client->Payment->getBillingTransactionInfo([
    'start_time' => strtotime('-30 days'),
    'end_time' => time(),
]);

foreach ($billing['billing_list'] as $bill) {
    echo "Transaction ID: " . $bill['transaction_id'] . "\n";
    echo "Amount: " . $bill['amount'] . "\n";
}
```

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

### Usage of Configuration File in PHP Client

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

Load configuration from a PHP file and use it to instantiate the Shopee client. This example shows how to set partner credentials, debug mode, and region based on the loaded configuration.

```php
$config = require 'config/shopee.php';

$client = new Client(
    $config['partner_id'],
    $config['partner_key'],
    $config['guzzle']
);

if ($config['debug']) {
    $client->useDebugMode();
}

if ($config['region'] === 'china') {
    $client->useChinaRegion();
} elseif ($config['region'] === 'brazil') {
    $client->useBrazilRegion();
}
```

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

### Minimal Client Configuration

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

Basic initialization of the Shopee PHP SDK client using only partner ID and key.

```php
$client = new Client('your_partner_id', 'your_partner_key');
```

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

### Handling AuthorizationException

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

Provides an example of catching an AuthorizationException and checking specific error codes to implement different recovery strategies, such as re-authorization or restarting the OAuth flow.

```php
use EcomPHP
\Shopee\Errors\AuthorizationException;

try {
    $tokens = $auth->getToken($code, $shop_id);
} catch (AuthorizationException $e) {
    $error_code = $e->getCode();
    
    if ($error_code === 'invalid_code') {
        // Authorization code invalid or expired
        // Redirect user to authorize again
    } elseif ($error_code === 'refresh_token_expired') {
        // Need full re-authorization
        // Clear stored tokens and restart OAuth flow
    } else {
        // Other authorization error
    }
}
```

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

### Get API Base URL

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

Retrieves the current API base URL, which is determined by the configured region and debug settings. Examples show potential URLs based on different configurations.

```php
public function baseUrl(): string
```

```php
$base = $client->baseUrl();
// Returns one of:
// https://partner.shopeemobile.com/api/v2/
// https://openplatform.shopee.cn/api/v2/
// https://openplatform.shopee.com.br/api/v2/
// https://openplatform.sandbox.test-stable.shopee.sg/api/v2/
// https://custom-host/api/v2/ (if custom hostname set)
```

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

### Client Initialization with Proxy Configuration

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

Configure the Shopee client to use a proxy server. Pass proxy details within the options array during client instantiation.

```php
$client = new Client(
    'partner_id',
    'partner_key',
    [
        'timeout' => 30,
        'proxy' => 'http://corp-proxy.internal:8080',
    ]
);
```

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

### Initialize Product Tier Variations

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

Set up variations (like size or color) for a product. This involves defining the tier names and options, and then providing stock and price data for each specific variant combination. Ensure 'tier_index' correctly maps to the defined 'tier_variation' options.

```php
$result = $client->Product->initTierVariation(
    123456789,
    [
        'name' => 'Size',  // First tier name
        'option' => ['S', 'M', 'L']  // Options for first tier
    ],
    [
        [
            'tier_index' => [0],  // First size option
            'normal_stock' => 100,
            'price' => 99.99,
        ],
        [
            'tier_index' => [1],  // Second size option
            'normal_stock' => 150,
            'price' => 99.99,
        ],
    ]
);
```

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

### Create a Simple Product

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

Use this to add a new product to your catalog. Provide essential details such as category ID, name, description, price, weight, and image URLs.

```php
$new_product = $client->Product->addItem([
    'category_id' => 100001,
    'name' => 'Wireless Headphones',
    'description' => 'High quality wireless headphones',
    'price' => 149.99,
    'weight' => 0.5,
    'images' => ['https://example.com/image1.jpg'],
]);

echo "Created product ID: " . $new_product['item_id'];
```

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

### Get Shopee Authentication URL and Redirect

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

Obtain the authentication URL and manually redirect the user. This is useful for server-side flows where header redirects are not immediately possible.

```php
$authUrl = $auth->createAuthRequest($redirect_uri, true);

// redirect user to auth url
header('Location: '.$authUrl);
```

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

### Initialize Shopee PHP Client

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

Instantiate the Shopee PHP SDK client with partner credentials and optional configurations. Set the access token for a specific shop ID to authenticate API requests.

```php
use EcomPHP\Shopee\Client;

$client = new Client('partner_id', 'partner_key', $options);
$client->setAccessToken($shop_id, $access_token);
```

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

### Set Item Installment Status

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

Sets the installment status for a specific item. This allows or disallows installment payments for that particular item.

```APIDOC
## POST /payment/set_item_installment_status

### Description
Sets the installment status for a specific item.

### Method
POST

### Endpoint
/payment/set_item_installment_status

### Parameters
#### Request Body
- **item_id** (string) - Required - The ID of the item.
- **installment_status** (integer) - Required - The status to set for item installments (e.g., 1 for enabled, 0 for disabled).

### Request Example
{
  "item_id": "123456789",
  "installment_status": 1
}

### Response
#### Success Response (200)
- **message** (string) - Confirmation message.
```

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

### Configure Shopee PHP Client

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

Instantiate the Shopee Client with your partner ID and partner key. Ensure these credentials are kept secure.

```php
use EcomPHP\Shopee\Client;

$partner_id = 'your partner id';
$partner_key = 'your partner key';

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

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

### Set Shop Installment Status

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

Sets the installment status for the shop. This allows or disallows installment payments for the shop's products.

```APIDOC
## POST /payment/set_shop_installment_status

### Description
Sets the installment status for the shop.

### Method
POST

### Endpoint
/payment/set_shop_installment_status

### Parameters
#### Request Body
- **installment_status** (integer) - Required - The status to set for shop installments (e.g., 1 for enabled, 0 for disabled).

### Request Example
{
  "installment_status": 1
}

### Response
#### Success Response (200)
- **message** (string) - Confirmation message.
```

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

### Initialize Shopee PHP SDK Client

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

Instantiate the Shopee PHP SDK client with partner credentials. The options array can be used for Guzzle HTTP client configuration.

```php
use EcomPHP\Shopee\Client;

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

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

### Check Shop Installment Support

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

Check if the shop's installment feature is enabled and retrieve available installment payment methods. This involves calling two separate API endpoints.

```php
$status = $client->Payment->getShopInstallmentStatus();

if ($status['installment_status'] === 1) {
    echo "Shop installment is enabled\n";
    
    // Get available payment methods
    $methods = $client->Payment->getPaymentMethodList();
    $installment_methods = array_filter(
        $methods['payment_method_list'],
        function($m) { return strpos($m['payment_method_name'], 'Installment') !== false; }
    );
}
```

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

### Using Environment Variables in PHP Client

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

Instantiate the Shopee client using values from environment variables. This example demonstrates setting partner credentials, debug mode, region, and access token.

```php
$client = new Client(
    getenv('SHOPEE_PARTNER_ID'),
    getenv('SHOPEE_PARTNER_KEY')
);

if (getenv('SHOPEE_DEBUG') === 'true') {
    $client->useDebugMode();
}

if (getenv('SHOPEE_REGION') === 'china') {
    $client->useChinaRegion();
}

$client->setAccessToken(
    getenv('SHOPEE_SHOP_ID'),
    getenv('SHOPEE_ACCESS_TOKEN')
);
```

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

### Initialize Shopee Client with Access Token

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

Re-initialize the client with partner credentials and set the access token and shop ID for making API calls.

```php
$client = new Client($partner_id, $partner_key);
$client->setAccessToken($shop_id, $access_token);
```

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

### Initialize Shopee Client

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

Instantiate the Shopee Client with your partner ID and key. You can also provide custom Guzzle HTTP client options.

```php
use EcomPHP\Shopee\Client;

$client = new Client('123456', 'your_partner_key_here');

// With custom Guzzle options
$client = new Client('123456', 'your_partner_key_here', [
    'timeout' => 30,
    'verify' => true,
]);
```

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

### Accessing SDK Resources

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

Demonstrates the standard pattern for accessing SDK resources and calling their methods. This pattern is common across all resource types.

```php
// Resource access
$resource = $client->ResourceName;

// Method calls
$result = $resource->methodName($params);
```

```php
// Chained (common pattern)
$result = $client->Product->getItemList(['page_size' => 50]);
```

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

### Get Shop Information

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

Retrieves basic information about the authorized shop. Use this to get the shop's name, ID, and status.

```php
$info = $client->Shop->getShopInfo();

echo "Shop Name: " . $info['shop_name'] . "\n";
echo "Shop ID: " . $info['shop_id'] . "\n";
echo "Status: " . $info['status'] . "\n";
```

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

### Configuration File for Shopee SDK

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

Store Shopee SDK configuration in a PHP file, separate from version control. This example shows a typical structure for storing partner credentials, region, debug settings, and Guzzle options.

```php
// config/shopee.php (add to .gitignore)
return [
    'partner_id' => getenv('SHOPEE_PARTNER_ID') ?: 'default_partner_id',
    'partner_key' => getenv('SHOPEE_PARTNER_KEY') ?: 'default_partner_key',
    'region' => getenv('SHOPEE_REGION') ?: 'default',
    'debug' => getenv('SHOPEE_DEBUG') === 'true',
    'guzzle' => [
        'timeout' => 30,
        'connect_timeout' => 5,
        'verify' => getenv('APP_ENV') !== 'development',
    ],
];
```

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

### Common Parameters for SDK Methods

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

Illustrates how to pass parameters to SDK methods using an array. This is a common practice for many resource methods, such as those in the Order resource.

```php
$client->Order->getOrderList([
    'time_from' => 1234567890,
    'time_to' => 1234567900,
    'page_size' => 100,
    'order_status' => 'READY_TO_SHIP',
]);
```

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

### Enable or Disable Shop Installment Payment Option

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

Control whether customers can use installment payment plans for your shop. Use '1' to enable and '0' to disable.

```php
// Enable installment
$result = $client->Payment->setShopInstallmentStatus(1);

// Disable installment
$result = $client->Payment->setShopInstallmentStatus(0);
```

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

### Client Constructor

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

Initializes a new Shopee API client instance. Requires your partner ID and partner key. Optional parameters can be passed for Guzzle HTTP client configuration.

```APIDOC
## Client Constructor

### Description
Initialize a new Shopee API client.

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

### Parameters
#### Path Parameters
(None)

#### Query Parameters
(None)

#### Request Body
(None)

### Parameters
- **partner_id** (string) - Required - Your partner ID from Shopee Partner Center
- **partner_key** (string) - Required - Your partner key from Shopee Partner Center
- **options** (array) - Optional - Additional options passed to Guzzle HTTP client

### Request Example
```php
use EcomPHP\Shopee\Client;

$client = new Client('123456', 'your_partner_key_here');

// With custom Guzzle options
$client = new Client('123456', 'your_partner_key_here', [
    'timeout' => 30,
    'verify' => true,
]);
```
```

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

### Safe Multi-Shop Pattern with Separate Clients

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

Demonstrates the recommended thread-safe pattern for handling multiple Shopee shops. Create separate Client instances for each shop to avoid race conditions.

```php
// Safe: Separate client per shop
$client_a = new Client('partner_id', 'partner_key');
$client_a->setAccessToken($shop_a_id, $shop_a_token);

$client_b = new Client('partner_id', 'partner_key');
$client_b->setAccessToken($shop_b_id, $shop_b_token);

// NOT safe: Switching tokens in concurrent context
// (Results in race condition)
```

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

### Set Installment Options for Specific Items

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

Configure available installment payment durations for individual items. This feature is region-specific (TH and TW) and can optionally include participation in the 'Ahora' plan.

```php
$result = $client->Payment->setItemInstallmentStatus(
    [123456789, 987654321],  // Item IDs
    [3, 6, 12],              // 3, 6, or 12 month plans
    false
);
```

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

### getItemInstallmentStatus

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

Retrieves the available installment tenures for specified items.

```APIDOC
## getItemInstallmentStatus

### Description
Get installment tenures available for items. Only for TH and TW.

### Method
POST

### Endpoint
/payment/item/installment/get

### Parameters
#### Request Body
- **item_id_list** (array) - Yes - Array of item IDs

### Request Example
```json
{
  "item_id_list": [123456789, 987654321]
}
```

### Response
#### Success Response (200)
- **item_list** (array) - Installment status for each item.
  - **item_id** (int) - The ID of the item.
  - **tenure_list** (array) - List of available tenure options (payment months).

#### Response Example
```json
{
  "item_list": [
    {
      "item_id": 123456789,
      "tenure_list": [3, 6, 12]
    }
  ]
}
```
```

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

### Add a New Product

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

Create a new product listing. The 'params' array must include required fields like 'category_id', 'name', 'description', 'price', and 'weight'. Refer to the Shopee API documentation for a complete list of required fields for specific categories.

```php
$new_item = $client->Product->addItem([
    'category_id' => 100001,
    'name' => 'Product Name',
    'description' => 'Product Description',
    'price' => 99.99,
    'weight' => 1.5,
    'images' => ['image_url_1', 'image_url_2'],
]);

$item_id = $new_item['item_id'];
```

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

### Client Initialization with Custom User-Agent

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

Set a custom User-Agent header for the Shopee client. This is useful for identifying your application in server logs.

```php
$client = new Client(
    'partner_id',
    'partner_key',
    [
        'headers' => [
            'User-Agent' => 'MyShop/2.0 (PHP/' . PHP_VERSION . ')',
        ],
    ]
);
```

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

### Get Token

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

Exchanges an authorization code for access and refresh tokens.

```APIDOC
## POST /auth/token/get

### Description
Exchanges an authorization code for access and refresh tokens.

### Method
POST

### Endpoint
/auth/token/get

### Parameters
#### Request Body
- **code** (string) - Required - The authorization code obtained from the user.
- **partner_id** (string) - Required - The partner ID.
- **shop_id** (string) - Required - The shop ID.

### Request Example
```json
{
  "code": "AUTHORIZATION_CODE",
  "partner_id": "PARTNER_ID",
  "shop_id": "SHOP_ID"
}
```

### Response
#### Success Response (200)
- **access_token** (string) - The access token for API requests.
- **refresh_token** (string) - The refresh token to obtain a new access token.
- **expires_in** (integer) - The validity period of the access token in seconds.
- **obtained_at** (timestamp) - The time when the token was obtained.

#### Response Example
```json
{
  "access_token": "ACCESS_TOKEN",
  "refresh_token": "REFRESH_TOKEN",
  "expires_in": 7200,
  "obtained_at": "2023-10-27T10:00:00Z"
}
```
```

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

### addItem

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

Creates a new product listing with specified details.

```APIDOC
## addItem

### Description
Create a new product/item.

### Method
POST (Assumed based on action, not explicitly stated)

### Endpoint
/product/add (Assumed based on action, not explicitly stated)

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
- **params** (array) - Required - Product data (see Shopee API for required fields)
  - `category_id` (int) - Required
  - `name` (string) - Required
  - `description` (string) - Required
  - `price` (float) - Required
  - `weight` (float) - Required
  - Additional fields per category

### Request Example
```php
$new_item = $client->Product->addItem([
    'category_id' => 100001,
    'name' => 'Product Name',
    'description' => 'Product Description',
    'price' => 99.99,
    'weight' => 1.5,
    'images' => ['image_url_1', 'image_url_2'],
]);

$item_id = $new_item['item_id'];
```

### Response
#### Success Response (200)
- **array** — Created item data with item_id

#### Response Example
(Response structure not detailed in source, but example implies an 'item_id' field)
```

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

### Get Shop Notification

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

Retrieves notifications for the seller's shop.

```APIDOC
## GET /shop/get_shop_notification

### Description
Retrieves notifications for the seller's shop.

### Method
GET

### Endpoint
/shop/get_shop_notification
```

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

### Get Warehouse Detail

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

Retrieves details about the seller's warehouses.

```APIDOC
## GET /shop/get_warehouse_detail

### Description
Retrieves details about the seller's warehouses.

### Method
GET

### Endpoint
/shop/get_warehouse_detail
```

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

### Get Shop Profile

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

Retrieves the seller's shop profile information.

```APIDOC
## GET /shop/get_profile

### Description
Retrieves the seller's shop profile information.

### Method
GET

### Endpoint
/shop/get_profile
```

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

### Production Environment Configuration

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

Configure the client for a production environment, setting timeouts, enforcing SSL verification, and conditionally selecting the region based on environment variables.

```php
$client = new Client(
    getenv('SHOPEE_PARTNER_ID'),
    getenv('SHOPEE_PARTNER_KEY'),
    [
        'timeout' => 30,
        'connect_timeout' => 5,
        'verify' => true,  // Enforce SSL in production
        'headers' => [
            'User-Agent' => 'MyApp/1.0.0',
        ],
    ]
);

// Use production endpoints
if (getenv('SHOPEE_REGION') === 'china') {
    $client->useChinaRegion();
} elseif (getenv('SHOPEE_REGION') === 'brazil') {
    $client->useBrazilRegion();
}

// Set access token from database
$client->setAccessToken(
    $shop_id,
    $access_token
);
```

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

### Client Methods

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

Core client methods for SDK initialization and direct API calls.

```APIDOC
## Client Methods

### Description
Core client methods for SDK initialization and direct API calls.

### Methods
- `__construct($partner_id, $partner_key, $options = [])`
- `setAccessToken($shop_id, $access_token)`
- `setCustomHostname($hostname)`
- `useDebugMode()`
- `useChinaRegion()`
- `useBrazilRegion()`
- `auth()` → Auth instance
- `call($method, $api, $options = [])` — Direct API call
- `validatePushMechanismRequest($url, $throw)` — Validate webhook
```

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

### Get Partner ID

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

Retrieves the configured partner ID for Shopee API authentication.

```php
public function partnerId(): string
```

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

### setItemInstallmentStatus

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

Configures installment payment options for specific items, including participation in the Ahora plan.

```APIDOC
## setItemInstallmentStatus

### Description
Set installment options for specific items. Only for TH and TW regions.

### Method
POST

### Endpoint
/payment/item/installment/set

### Parameters
#### Request Body
- **item_id_list** (array) - Yes - Array of item IDs
- **tenure_list** (array) - Yes - Array of tenure options (payment months)
- **participate_plan_ahora** (bool) - No - Whether to participate in Ahora plan (defaults to false)

### Request Example
```json
{
  "item_id_list": [123456789, 987654321],
  "tenure_list": [3, 6, 12],
  "participate_plan_ahora": false
}
```

### Response
#### Success Response (200)
- **status** (string) - Operation result message.

#### Response Example
```json
{
  "status": "success"
}
```
```

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

### Client Configuration with Guzzle Options

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

Configure the Shopee PHP SDK client with partner credentials and specific Guzzle HTTP client options like timeout and SSL verification.

```php
$client = new Client(
    'your_partner_id',
    'your_partner_key',
    [
        'timeout' => 30,
        'verify' => true,
        'headers' => [
            'User-Agent' => 'MyApp/1.0',
        ],
    ]
);
```

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

### initTierVariation

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

Initializes product variations and tiers for products with multiple variants.

```APIDOC
## initTierVariation

### Description
Initialize product variations/tiers for multi-variant products.

### Method
POST (Assumed based on action, not explicitly stated)

### Endpoint
/product/tier_variation/init (Assumed based on action, not explicitly stated)

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None (Method signature suggests parameters are passed directly)

### Parameters (from method signature)
- **item_id** (int) - Required - Item ID
- **tier_variation** (array) - Required - Tier configuration (variant names)
  - `name` (string) - First tier name
  - `option` (array) - Options for first tier
- **model** (array) - Required - Model data for each variant
  - `tier_index` (array) - First size option
  - `normal_stock` (int)
  - `price` (float)

### Request Example
```php
$result = $client->Product->initTierVariation(
    123456789,
    [
        'name' => 'Size',  // First tier name
        'option' => ['S', 'M', 'L']  // Options for first tier
    ],
    [
        [
            'tier_index' => [0],  // First size option
            'normal_stock' => 100,
            'price' => 99.99,
        ],
        [
            'tier_index' => [1],  // Second size option
            'normal_stock' => 150,
            'price' => 99.99,
        ],
    ]
);
```

### Response
#### Success Response (200)
- **array** — Initialization result

#### Response Example
(Response structure not detailed in source)
```

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

### Get Escrow List

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

Retrieves a list of escrow transactions. This provides an overview of escrow-related activities.

```APIDOC
## GET /payment/get_escrow_list

### Description
Retrieves a list of escrow transactions.

### Method
GET

### Endpoint
/payment/get_escrow_list

### Response
#### Success Response (200)
- **escrow_list** (array) - A list of escrow transaction details.
```

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

### addItem

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

Creates a new simple product listing. This method is used for initial product creation with basic details.

```APIDOC
## addItem

### Description
Creates a new simple product listing. This method is used for initial product creation with basic details.

### Method
POST (assumed, based on typical API patterns for creation)

### Endpoint
/api/v1/product

### Parameters
#### Request Body
- **category_id** (int) - Yes - The ID of the product's category
- **name** (string) - Yes - The name of the product
- **description** (string) - Yes - A detailed description of the product
- **price** (float) - Yes - The base price of the product
- **weight** (float) - Yes - The weight of the product
- **images** (array) - Yes - A list of URLs for product images

### Request Example
```json
{
  "category_id": 100001,
  "name": "Wireless Headphones",
  "description": "High quality wireless headphones",
  "price": 149.99,
  "weight": 0.5,
  "images": ["https://example.com/image1.jpg"]
}
```

### Response
#### Success Response (200)
- **item_id** (int) - The ID of the newly created product
```

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

### Get Partner Key

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

Retrieves the configured partner key, which should be kept secret, for API authentication.

```php
public function partnerKey(): string
```

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

### Client Configuration with Advanced Guzzle Options

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

Configure the Shopee PHP SDK client with partner credentials and advanced Guzzle options including timeouts, redirects, headers, and proxy settings.

```php
$client = new Client(
    'partner_id',
    'partner_key',
    [
        'timeout' => 30,
        'connect_timeout' => 5,
        'verify' => true,
        'allow_redirects' => true,
        'headers' => [
            'User-Agent' => 'MyShopeeApp/1.0',
            'X-Custom-Header' => 'value',
        ],
        'proxy' => 'http://proxy.company.com:8080',
    ]
);
```

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

### Get Authorized Reseller Brand

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

Retrieves a list of brands authorized by the reseller. Supports pagination.

```APIDOC
## GET /shop/get_authorised_reseller_brand

### Description
Retrieves a list of brands authorized by the reseller. Supports pagination.

### Method
GET

### Endpoint
/shop/get_authorised_reseller_brand

### Parameters
#### Query Parameters
- **page_no** (integer) - Required - The page number to retrieve.
- **page_size** (integer) - Optional - The number of items per page. Defaults to 100.
```

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

### Multi-Shop Configuration with ShopeeManager

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

Manage multiple Shopee shops by switching access tokens. Instantiate ShopeeManager with partner credentials and use switchToShop to set the active shop's access token before making API calls.

```php
class ShopeeManager {
    private $client;
    private $shops = [];
    
    public function __construct($partner_id, $partner_key) {
        $this->client = new Client($partner_id, $partner_key);
    }
    
    public function switchToShop($shop_id, $access_token) {
        // Load shop-specific token from database
        if (!isset($this->shops[$shop_id])) {
            $this->shops[$shop_id] = $access_token;
        }
        
        $this->client->setAccessToken($shop_id, $access_token);
    }
    
    public function getCurrentClient() {
        return $this->client;
    }
}

// Usage
$manager = new ShopeeManager('partner_id', 'partner_key');

// Work with shop A
$manager->switchToShop(123456, 'token_for_shop_a');
$items_a = $manager->getCurrentClient()->Product->getItemList();

// Switch to shop B
$manager->switchToShop(654321, 'token_for_shop_b');
$items_b = $manager->getCurrentClient()->Product->getItemList();
```

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

### Get Product Variants (Models)

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

Fetches all variants or models associated with a specific product item ID.

```php
$models = $client->Product->getModelList(123456789);
```

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

### Instantiate Auth Class

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

Create a new Auth instance using the Client. This is typically obtained via the client's auth() method.

```php
$auth = $client->auth();
// Equivalent to: $auth = new Auth($client);
```

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

### Get Product Categories

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

Retrieves a list of product categories. Supports optional query parameters for filtering.

```php
$categories = $client->Product->getCategory();

// With parameters
$categories = $client->Product->getCategory([
    'language' => 'en',
]);
```