Shopee SDK API Reference - v1.11.0
    Preparing search index...

    Shopee SDK API Reference - v1.11.0

    Shopee SDK

    CI Coverage Status npm version Node.js Version License: MIT

    🎉 The most complete, production-ready TypeScript SDK for Shopee Open API 🎉

    Buy Me a Coffee

    Build powerful Shopee integrations with confidence using our fully-featured SDK that covers 100% of Shopee's API endpoints. Trusted by developers, built by the community.

    • Complete Documentation - Comprehensive guides and API references
    • AI Onboarding & LLM Guide - A high-context onboarding guide specifically written for AI Agents and LLMs to quickly understand the codebase architecture and start coding.

    Getting Started:

    API Managers:

    npm install @congminh1254/shopee-sdk

    Requirements: Node.js >= 20.0.0

    ✅ Complete TypeScript definitions for all 29 API managers
    ✅ Automatic token refresh and management
    ✅ Built-in error handling and retry logic
    ✅ Zero dependencies (except node-fetch)
    ✅ Full documentation and examples

    Get up and running in minutes! Here's how easy it is to integrate with Shopee:

    import { ShopeeSDK, ShopeeRegion } from "@congminh1254/shopee-sdk";

    // 1. Initialize the SDK with your credentials
    const sdk = new ShopeeSDK({
      partner_id: 123456,
      partner_key: "your-partner-key",
      region: ShopeeRegion.GLOBAL,
      shop_id: 789012, // Optional for shop-specific operations
    });

    // 2. Authenticate your shop (OAuth flow)
    const authUrl = sdk.getAuthorizationUrl("https://your-app.com/callback");
    console.log("Visit:", authUrl);

    // After user authorizes, exchange code for token (automatic token storage!)
    await sdk.authenticateWithCode("auth-code-from-callback");

    // 3. Start using the API - it's that simple!

    // Manage your products
    const products = await sdk.product.getItemList({
      offset: 0,
      page_size: 20,
    });

    // Process orders
    const orders = await sdk.order.getOrderList({
      time_range_field: "create_time",
      time_from: Math.floor(Date.now() / 1000) - 86400,
      time_to: Math.floor(Date.now() / 1000),
      page_size: 50,
    });

    // Track shipments
    const shipping = await sdk.logistics.getShippingParameter({
      order_sn: "220615ABCDEF",
    });

    // Handle returns
    const returns = await sdk.returns.getReturnList({
      page_size: 20,
    });

    // And much more - all with full TypeScript support! 🎉

    That's it! The SDK handles token refresh, request signing, error handling, and more automatically.

    See the Setup Guide and Authentication Guide for detailed instructions.

    • 100% core test coverage with 700+ robust unit & live sandbox integration tests - ensuring ultimate production reliability
    • Zero compromises - Every Shopee API endpoint is implemented and documented
    • Type-safe - Full TypeScript definitions prevent errors before they happen
    • Actively maintained - Regular updates to stay in sync with Shopee API changes

    Unlike other SDKs with partial coverage, we provide complete access to every Shopee API:

    Core Commerce:

    • 📦 ProductManager - Full product catalog management with 55+ endpoints
    • 🛒 OrderManager - Complete order processing and fulfillment workflow
    • 🚚 LogisticsManager - Comprehensive shipping and tracking operations
    • 💳 PaymentManager - Payment and escrow information management

    Marketing & Promotions:

    • 🎟️ VoucherManager - Discount voucher campaigns
    • 💥 DiscountManager - Discount promotion campaigns
    • 🎁 BundleDealManager - Bundle deal promotions
    • ➕ AddOnDealManager - Add-on deal promotions
    • ⚡ ShopFlashSaleManager - Flash sale campaigns
    • 🎯 FollowPrizeManager - Follow prize activities
    • ⭐ TopPicksManager - Top picks product collections
    • 📣 AmsManager - Affiliate marketing solutions (AMS)

    Store Management:

    • 🏪 ShopManager - Shop information and profile management
    • 🏢 MerchantManager - Merchant information, warehouses, and multi-shop management
    • 📂 ShopCategoryManager - Shop category organization
    • 🖼️ MediaManager & MediaSpaceManager - Image and video upload operations

    Advanced Features:

    • 🔐 AuthManager - OAuth flow and token lifecycle management
    • 📢 PushManager - Webhooks and real-time notifications
    • 🌍 GlobalProductManager - Cross-border product management
    • 🔄 ReturnsManager - Return and refund request handling
    • 📊 AdsManager - Advertising campaign management
    • 📈 AccountHealthManager - Performance metrics and analytics
    • 🌐 PublicManager - Public API endpoints (no auth required)
    • 📍 FirstMileManager - First mile logistics operations
    • 🏭 SbsManager - Shopee Business Services warehouse inventory
    • 📦 FbsManager - Fulfillment by Shopee operations
    • 📹 LivestreamManager - Live streaming features
    • 🎬 VideoManager - Shopee Video features and analytics
    • Intuitive API design - Clean, consistent interfaces across all managers
    • Automatic token refresh - Built-in token management, never worry about expiration
    • Flexible storage - File-based storage included, easy to implement custom solutions
    • Multi-region support - Works seamlessly across all 12 Shopee regions
    • Proxy support - Enterprise-ready HTTP/HTTPS proxy configuration
    • Comprehensive docs - Detailed guides and real-world examples for every feature
    • Full type safety - Complete TypeScript definitions for autocomplete and error prevention

    This SDK is perfect for building:

    • 🏪 Multi-channel E-commerce Platforms - Sync inventory, orders, and products across multiple sales channels
    • 📊 Analytics Dashboards - Track sales performance, customer behavior, and business metrics
    • 🤖 Automation Tools - Automate order processing, inventory updates, and customer communications
    • 🔄 ERP Integrations - Connect Shopee with your existing business systems
    • 📱 Mobile Apps - Build native mobile experiences for shop management
    • 🎯 Marketing Automation - Manage promotions, vouchers, and advertising campaigns programmatically
    • 📦 Inventory Management Systems - Real-time stock tracking across warehouses
    • 🚀 Custom Storefronts - Create unique shopping experiences powered by Shopee's infrastructure

    Switching is easy! Our SDK offers:

    • More complete coverage - Every endpoint is implemented, not just the basics
    • Better TypeScript support - Full type safety from end to end
    • Simpler API - Intuitive, well-organized manager classes
    • Active maintenance - Regular updates and community support
    • Production-ready - Battle-tested with comprehensive test coverage

    Check our Migration Guide to get started.

    This SDK is built with reliability and correctness as first-class citizens, boasting extensive test coverage across both simulated unit environments and live external sandbox systems.

    • Mock Manager Coverage: Over 690+ unit tests validating standard parameters, response layouts, request sign-generation, and error boundaries for all 29 API managers.
    • 100% Code Coverage: All core and manager logic files maintain a strict 100% statement, branch, and line code coverage.
    • Run unit tests:
      npm run test

    Our integration test suite executes real HTTP requests against the live Shopee Sandbox environment (using dynamic OAuth credentials) to verify end-to-end integration safety:

    • Vouchers: Tests the full CRUD lifecycle (creating, fetching, updating limits, and automatically cleaning up/deleting test vouchers).
    • Media & Videos: Verifies safe transparent PNG uploads, video session initialization, and a complete chunked video upload workflow utilizing a built-in, highly-optimized 10-second Base64 MP4 H.264 video fixture.
    • Logistics & Documents: Validates thermal shipping label document generation and download jobs.
    • Payments & Settings: Checks public payment methods, shop installment profiles, active orders, local products, and dynamic Shopee server IP ranges.
    • Run sandbox integration tests:
      npm run test:sandbox

    We use Conventional Commits for commit messages to automate versioning and release notes.

    Examples of commit messages:

    • feat: add support for logistics API - Minor version bump
    • fix: correct error handling in order API - Patch version bump
    • docs: update API documentation - No version bump
    • feat!: rename parameters in product API or feat: rename parameters in product API BREAKING CHANGE: ... - Major version bump

    This project uses Release Please to automate version management and releases.

    The release process follows these steps:

    1. Commits to the main branch are automatically analyzed
    2. When conventional commit messages are detected, Release Please creates or updates a release PR
    3. When the release PR is merged:
      • A new GitHub tag and release is created
      • The package is automatically published to npm
      • The CHANGELOG.md is updated with the release notes

    MIT

    Settings

    Member Visibility

    On This Page

    Shopee SDK