๐ 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.
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.
Unlike other SDKs with partial coverage, we provide complete access to every Shopee API:
Core Commerce:
Marketing & Promotions:
Store Management:
Advanced Features:
This SDK is perfect for building:
Switching is easy! Our SDK offers:
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.
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 bumpfix: correct error handling in order API - Patch version bumpdocs: update API documentation - No version bumpfeat!: rename parameters in product API or feat: rename parameters in product API BREAKING CHANGE: ... - Major version bumpThis project uses Release Please to automate version management and releases.
The release process follows these steps:
MIT