README

A comprehensive Laravel package for seamlessly integrating with the Shopee Open Platform API. This package provides an elegant, fluent interface for managing shops, products, orders, and payments on Shopee's marketplace.

Installation

You can install the package via composer:

composer require laraditz/shopee

Before Starting

Configure your Shopee API credentials in your .env file (recommended) or publish and modify the config file.

SHOPEE_SANDBOX_MODE=true # Set to false for production
SHOPEE_PARTNER_ID=<your_shopee_partner_id>
SHOPEE_PARTNER_KEY=<your_shopee_partner_key>
SHOPEE_SHOP_ID=<your_shopee_shop_id>
SHOPEE_REDIRECT_URL=<your_redirect_url> # Optional — see Authorization Flow

(Optional) You can publish the config file via this command:

php artisan vendor:publish --provider="Laraditz\Shopee\ShopeeServiceProvider" --tag="config"

Publish and run the migrations to create the necessary database tables for storing shop data, access tokens, and API request logs.

php artisan vendor:publish --provider="Laraditz\Shopee\ShopeeServiceProvider" --tag="migrations"
php artisan migrate

Authorization Flow

To authorize a Shopee shop with your app:

1. Visit Shopee Open Platform Console.
2. On your App List, click Authorize link next to the Test/Live Partner_id. Alternatively, you can generate the authorization URL using the generateAuthorizationURL() method.
3. Make sure the domain for authorized redirect URL already been whitelisted beforehand.
4. Enter https://your-app-url/shopee/shops/authorized as the Redirect URL and click Next.
5. Proceed to login using the seller account that you want to authorized to be use for the app.
6. Shopee redirects back to https://your-app-url/shopee/shops/authorized.
7. Package automatically handles the authorization code exchange and token storage.
8. Shop is now ready for API calls.

Custom Redirect After Authorization

By default, the package renders a built-in success page after authorization. To redirect to your own URL instead, set SHOPEE_REDIRECT_URL in your .env:

SHOPEE_REDIRECT_URL=https://your-app-url/shopee/callback

On success, the package redirects to your URL with the following query parameters:

On failure (e.g. token exchange error), the redirect includes:

Security: SHOPEE_REDIRECT_URL must be an exact absolute URL without query strings. Only requests carrying this exact value are honoured — any other value is silently discarded, preventing open redirect attacks. Use HTTPS in production as tokens are passed in the URL.

Available Services & Methods

Below is a list of all available methods in this SDK. For detailed usage, please refer to the Developer’s Guide and the API Reference. This package organizes Shopee API endpoints into logical services. Each method name corresponds to its respective API endpoint (converted from snake_case → camelCase), and all parameters follow the exact definitions provided in the API reference.

Note: All method parameters must be passed as named arguments, not positional arguments.

🔐 Authorization and Authentication Service auth()

Handles OAuth 2.0 authentication flow and token management.

🏪 Shop Service shop()

Manages shop information and authorization processes.

📦 Product Service product()

Comprehensive product and inventory management capabilities.

🛒 Order Service order()

Handles order management and retrieval with detailed tracking information.

💰 Payment Service payment()

Manages payment and financial transaction details.

Usage Examples

The package provides a fluent, chainable API interface. Access services by chaining the service name before calling the method.

Basic Usage

use Laraditz\Shopee\Facades\Shopee;

// Get order details
$orderDetails = Shopee::order()->getOrderDetail(
    order_sn_list: '211020BNFYMXXX,211020BNFYXXX2'
);

// Get shop information
$shopInfo = Shopee::shop()->getShopInfo();

// Search products
$products = Shopee::product()->searchItem(
    item_name: 'smartphone',
    page_size: 20,
    offset: 0
);

// Add a new product
$newProduct = Shopee::product()->addItem(
    item_name: 'My Product',
    description: 'Product description',
    original_price: 29.90,
    normal_stock: 100,
    weight: 0.5,
    item_sku: 'SKU-001',
    category_id: 100001,
    // ... refer to Shopee API Reference for full parameter list
);

// Update an existing product
Shopee::product()->updateItem(
    item_id: 123456789,
    item_name: 'Updated Product Name',
    original_price: 24.90,
);

// Delete a product
Shopee::product()->deleteItem(item_id: 123456789);

// Alternative: using service container
$orders = app('shopee')->order()->getOrderList(
    time_range_field: 'create_time',
    time_from: strtotime('-30 days'),
    time_to: time(),
    page_size: 50
);

Multi-Shop Support

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

use Laraditz\Shopee\Facades\Shopee;

// Method 1: Using make() with shop_id
$products = Shopee::make(shop_id: '2257XXXXX')
    ->product()
    ->getItemList(
        offset: 0,
        page_size: 10,
        item_status: 'NORMAL'
    );

// Method 2: Using shopId() method
$orders = Shopee::shopId('2257XXXXX')
    ->order()
    ->getOrderList(
        time_range_field: 'create_time',
        time_from: strtotime('-7 days'),
        time_to: time()
    );

Error Handling

use Laraditz\Shopee\Facades\Shopee;
use Illuminate\Http\Client\RequestException;

try {
    $result = Shopee::product()->updateStock(
        item_id: 123456789,
        stock_list: [
            [
                'model_id' => 123123123,
                'seller_stock' => [
                    [
                        'location_id' => 'MYZ',
                        'stock' => 100,
                    ]
                ],
            ]
        ]
    );
} catch (RequestException $e) {
    // Handle HTTP/network errors
    logger()->error('Request failed: ' . $e->getMessage());
}

Webhook Integration

This package provides comprehensive webhook support for real-time notifications from Shopee. Refer to Push Mecahnism documentation for more details.

Event Handling

Create listeners for webhook events to automatically process updates from Shopee:

Setting Up Webhooks

Configure Webhook URL: In your Shopee Open Platform dashboard, set the webhook URL to:

https://your-app-url/shopee/webhooks

Create Event Listeners to Handle Webhook Data: Create a listener to process incoming data:

<?php

namespace App\Listeners;

use Laraditz\Shopee\Events\WebhookReceived;

class YourWebhookListener
{
    public function handle(WebhookReceived $event)
    {
        $webhookData = $event->data;

        // Process order updates, product changes, etc.
        if ($webhookData['event'] === 'order_status_update') {
            // Handle order status changes
        }
    }
}

Register Event Listeners: Register listeners in your EventServiceProvider (Laravel 10 and below):

use Laraditz\Shopee\Events\WebhookReceived;

protected $listen = [
    WebhookReceived::class => [
        YourWebhookListener::class,
    ],
];

Artisan Commands

The package provides convenient Artisan commands for token management:

# Remove expired access tokens from database
php artisan shopee:flush-expired-token

# Refresh existing access tokens before expiration
php artisan shopee:refresh-token

Automated Token Refresh

Since Shopee access tokens expire every 4 hours, it's recommended to schedule the refresh command to run automatically. Add this to your app/Console/Kernel.php:

protected function schedule(Schedule $schedule)
{
    // Refresh tokens every 3 hours to prevent expiration
    $schedule->command('shopee:refresh-token')
             ->everyThreeHours()
             ->withoutOverlapping();

    // Clean up expired tokens daily
    $schedule->command('shopee:flush-expired-token')
             ->daily();
}

Important: Without automatic refresh, expired tokens will require shop reauthorization and manual token generation.

Changelog

Please see CHANGELOG for more information what has changed recently.

Contributing

Please see CONTRIBUTING for details.

Security

If you discover any security related issues, please email raditzfarhan@gmail.com instead of using the issue tracker.

Credits

• Raditz Farhan
• All Contributors

License

The MIT License (MIT). Please see License File for more information.