Shopee API Client

API Client

npm i shopee-api-client

shopee-api-client is a TypeScript library for Shopee Open API v2, covering all 30 domains of the reference shopee-sdk (446 endpoints). It handles the whole OAuth flow, signs every request, and verifies push-notification webhooks. The six core domains (orders, products, logistics, payment, returns, push) are flat methods on ShopeeModule; the other domains live under typed namespaces such as shopee.ads and shopee.voucher, so no new method collides with an existing name. Every failure surfaces as a ShopeeApiError, every call has a 30-second timeout, and GET requests retry transient errors while POST never does. 147 unit tests.

Key Features

◆446 endpoints across 30 domains: orders, products, logistics, payment, returns, ads, vouchers, livestream, global products and more
◆Namespaced domains (shopee.ads.*, shopee.voucher.*, shopee.globalProduct.*) keep 20 new domains clear of existing method names
◆Errors: every failure throws a ShopeeApiError with code, request ID, HTTP status and the raw response
◆Reliability: 30s timeout on every call; GET retries 408/429/5xx with exponential backoff, jitter and Retry-After; POST is never retried, so an order is never shipped or cancelled twice
◆OAuth: generateAuthLink, fetchTokenWithAuthCode, fetchTokenWithRefreshToken
◆Webhooks: verifyShopeePushSignature, parseShopeePushPayload
◆File uploads sent as real multipart/form-data (5 upload endpoints fixed in v2.3.0)
◆No any in the public API; 147 unit tests

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");
}

Namespaced domains and typed errors

import { ShopeeApiError } from "shopee-api-client";

try {
  // Newer domains live under their own namespace
  const vouchers = await shopee.voucher.getVoucherList({
    status: "ongoing", // upcoming | ongoing | expired | all
    page_size: 50,
  });
  console.log(vouchers);
} catch (err) {
  if (err instanceof ShopeeApiError) {
    // Shopee's error code, request ID and HTTP status, ready for logs
    console.error(err.code, err.requestId, err.status);
  }
  throw err;
}

Resources

GitHub Repository npm Registry Full Documentation

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.

Shopee API Client — API ClientBack to Home