Shopee SDK API Reference - v2.14.1
    Preparing search index...

    Shopee SDK API Reference - v2.14.1

    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.

    Getting Started:

    API Managers:

    npm install @congminh1254/shopee-sdk
    

    Requirements: Node.js >= 22.0.0

    โœ… Complete TypeScript definitions for all 30 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 1,160+ unit tests validating standard parameters, response layouts, request sign-generation, and error boundaries for all 30 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.

    • Sandbox tests are split into three suites, each with its own GitHub Actions job. Each logs in with Playwright, then runs its tests; missing configuration fails the suite (nothing is skipped):

      Suite Command Account Covers
      Shop npm run test:sandbox:shop SHOPEE_SANDBOX_ACCOUNT Shop APIs (src/__tests__/integration/shop/)
      User npm run test:sandbox:user SHOPEE_SANDBOX_MAIN_ACCOUNT Livestream user APIs (.../integration/user/)
      Merchant npm run test:sandbox:merchant SHOPEE_SANDBOX_MAIN_ACCOUNT Merchant and Global Product APIs (.../integration/merchant/)

      npm run test:sandbox runs all three. Copy .env.example to .env for local runs. These suites are excluded from npm test.

    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