Shopee API Client
API Client • v1.0.8npm i shopee-api-clientshopee-api-client is a TypeScript library for Shopee Open API v2. It handles the whole OAuth flow: building the authorization link, exchanging the code for an access token, and refreshing the token before it expires. It covers order APIs (getOrders, getOrderDetail, cancelOrder), products (getCategory, getAttributes, getBrandList, updatePrice, updateStock), logistics (shipOrder, getTrackingNumber, createShippingDocument, massShipOrder), payment (getEscrowDetail), and signature checking for Shopee push notification webhooks.
Key Features
- ◆OAuth 2.0: generateAuthLink, fetchTokenWithAuthCode, fetchTokenWithRefreshToken
- ◆Orders: getOrders (auto-pagination), getOrderList, getOrderDetail, cancelOrder, searchPackageList
- ◆Products: getCategory, getAttributes, getBrandList, addItem, updatePrice, updateStock, unListItem
- ◆Logistics: shipOrder, getChannelList, getTrackingNumber, createShippingDocument, massShipOrder
- ◆Payment: getEscrowDetail (payment reconciliation)
- ◆Webhook Push: verifyShopeePushSignature, parseShopeePushPayload, createShopeePushSignature
- ◆Typed end to end, with request/response DTOs for every call
Code Examples
Setup & configuration
import { ShopeeModule } from "shopee-api-client";
const shopee = new ShopeeModule({
partnerId: Number(process.env.SHOPEE_PARTNER_ID),
partnerKey: process.env.SHOPEE_PARTNER_KEY!,
shopId: process.env.SHOPEE_SHOP_ID,
accessToken: process.env.SHOPEE_ACCESS_TOKEN,
refreshToken: process.env.SHOPEE_REFRESH_TOKEN,
});Fetching orders
// Orders from the last 60 minutes (auto-pagination)
const recentOrders = await shopee.getOrders(60);
// Or with a narrower filter:
const pendingOrders = await shopee.getOrders({
beforeMinutes: 120,
orderStatus: "READY_TO_SHIP",
timeRangeField: "update_time",
pageSize: 50,
});
console.log(`${pendingOrders.length} orders waiting to ship`);Verifying a push webhook
import { verifyShopeePushSignature } from "shopee-api-client";
// Check the signature on a Shopee push notification
const isValid = verifyShopeePushSignature(
process.env.SHOPEE_PARTNER_KEY!,
"raw-push-body",
"x-shopee-signature-value"
);
if (isValid) {
// Process the order carried by the push notification
console.log("Signature checks out, processing...");
} else {
console.warn("Signature mismatch, dropping the request");
}Resources
Related Article
Three calls get you a Shopee token. Keeping it alive is the hard part.
The quick start is three functions long and works first try against your own test shop. What it leaves out: the auth endpoints sign differently from every other call, the refresh token is single-use so two workers will quietly kill each other's copy, and the thing that actually expires is the seller's authorization — which you cannot read from the token in your hand.