About shopee-sdk

A lightweight, fully-featured TypeScript SDK for the Shopee Open API v2. Features automatic request signing, pluggable token storage, robust error handling, and 100% endpoint coverage.

c

Published by

congminh1254

Visit View Profile

README.md

View on GitHub

Shopee SDK

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

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.

📚 Documentation

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.

Quick Links

Getting Started:

Setup Guide - Installation and configuration
Authentication - OAuth flow and token management
Token Storage - Managing access tokens
Proxy Configuration - Using HTTP/HTTPS proxies

API Managers:

AuthManager - Authentication operations
ProductManager - Product catalog management
OrderManager - Order processing
LogisticsManager - Shipping operations
PaymentManager - Payment information
VoucherManager - Discount management
PushManager - Webhooks and notifications
PublicManager - Public API endpoints
AdsManager - Advertising campaigns
AmsManager - Affiliate Marketing Solutions (AMS)
AccountHealthManager - Performance metrics
ShopManager - Shop information and settings
MediaManager - Image and video upload
MediaSpaceManager - Media uploads (images and videos)
MerchantManager - Merchant information and warehouses
GlobalProductManager - Global product management
FirstMileManager - First mile logistics
DiscountManager - Discount campaigns
BundleDealManager - Bundle deal promotions
AddOnDealManager - Add-on deal promotions
ShopFlashSaleManager - Flash sale campaigns
FollowPrizeManager - Follow prize activities
TopPicksManager - Top picks collections
ShopCategoryManager - Shop category management
ReturnsManager - Return and refund management
SbsManager - Shopee Business Services (SBS) warehouse inventory
FbsManager - Fulfillment by Shopee operations
LivestreamManager - Live streaming features
VideoManager - Shopee Video features and analytics

Installation

npm install @congminh1254/shopee-sdk

Requirements: Node.js >= 20.0.0

What You Get

✅ 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

Quick Start

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.

Why Choose This SDK?

🚀 Production-Ready & Battle-Tested

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

💪 Complete API Coverage - All 29 Managers Implemented

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

✨ Developer Experience First

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

Real-World Use Cases

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

Migrating from Other SDKs?

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.

🧪 Testing & Quality Assurance

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.

1. Unit Tests

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
```

2. Live Sandbox Integration Tests

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
```

Contributing

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

Release Process

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

The release process follows these steps:

Commits to the main branch are automatically analyzed
When conventional commit messages are detected, Release Please creates or updates a release PR
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

License

MIT

shopee-sdk