woocommerce-rest-api

woocommerce-rest-api is a reusable Node.js SDK for WooCommerce stores. The package is structured into reusable transport, auth, and resource modules so application teams can use it directly in apps or extend it inside their own commerce tooling.

Why this package is useful

• Modular src/ layout instead of a single monolithic client file
• Config validation with zod
• axios transport with consistent response envelopes
• Automatic auth strategy selection for HTTPS and HTTP deployments
• Built-in pagination helper for list endpoints
• Separate resource helpers for catalog, orders, customers, and store operations

Installation

npm install woocommerce-rest-api

Quick start

const WooCommerceRestApi = require('woocommerce-rest-api');

async function main() {
  const api = new WooCommerceRestApi({
    url: 'https://store.example.com',
    consumerKey: process.env.WC_KEY,
    consumerSecret: process.env.WC_SECRET,
    version: 'wc/v3',
    timeout: 15000,
  });

  const products = await api.getProducts({
    per_page: 20,
    status: 'publish',
  });

  console.log(products.data);
  console.log(products.meta.pagination);
}

main().catch((error) => {
  console.error(error);
  process.exit(1);
});

Response format

All request helpers return a consistent envelope:

{
  data,
  statusCode,
  headers,
  meta: {
    pagination: {
      total,
      totalPages
    }
  }
}

That makes it easier to build SDK wrappers, dashboards, background jobs, and internal admin tools without special-casing list responses.

Authentication strategies

authStrategy supports:

• auto: uses basic for HTTPS and oauth1 for HTTP
• basic
• query-string
• oauth1

Example:

const api = new WooCommerceRestApi({
  url: 'https://store.example.com',
  consumerKey: process.env.WC_KEY,
  consumerSecret: process.env.WC_SECRET,
  authStrategy: 'query-string',
});

Core usage

Products

const created = await api.createProduct({
  name: 'Developer Hoodie',
  type: 'simple',
  regular_price: '59.99',
  manage_stock: true,
  stock_quantity: 25,
});

await api.updateProduct(created.data.id, {
  sale_price: '49.99',
});

await api.deleteProduct(created.data.id, {
  force: true,
});

Orders

const order = await api.createOrder({
  payment_method: 'bacs',
  payment_method_title: 'Direct Bank Transfer',
  set_paid: true,
  billing: {
    first_name: 'Jane',
    last_name: 'Doe',
    email: '[email protected]',
  },
  line_items: [
    { product_id: 42, quantity: 1 },
  ],
});

await api.updateOrder(order.data.id, {
  status: 'completed',
});

Customers and coupons

const customers = await api.getCustomers({ role: 'customer' });

const coupon = await api.createCoupon({
  code: 'WELCOME10',
  discount_type: 'percent',
  amount: '10',
});

await api.updateCoupon(coupon.data.id, {
  amount: '15',
});

Pagination helper

const allProducts = await api.paginate('products', { per_page: 50 }, { maxPages: 5 });

console.log(allProducts.data.length);
console.log(allProducts.pagesFetched);

Generic requests

If your store exposes custom endpoints, use the generic request methods:

const webhooks = await api.get('webhooks');

const extensionData = await api.request('POST', 'my-plugin/v1/sync', {
  data: {
    source: 'inventory-job',
  },
});

API

new WooCommerceRestApi(options)

| Option | Required | Default | Description | | --- | --- | --- | --- | | url | Yes | — | Store base URL | | consumerKey | Yes | — | WooCommerce consumer key | | consumerSecret | Yes | — | WooCommerce consumer secret | | version | No | 'wc/v3' | API version | | verifySsl | No | true | Whether TLS certificates must validate | | timeout | No | 10000 | Request timeout in milliseconds | | authStrategy | No | 'auto' | Auth mode | | userAgent | No | woocommerce-rest-api/1.1.0 | Custom user agent | | headers | No | {} | Default request headers |

Generic methods

• request(method, endpoint, options?)
• get(endpoint, options?)
• post(endpoint, data, options?)
• put(endpoint, data, options?)
• delete(endpoint, options?)
• paginate(endpoint, params?, options?)

Resource methods

• getProducts(params?)
• getProduct(id)
• createProduct(data)
• updateProduct(id, data)
• deleteProduct(id, params?)
• getOrders(params?)
• getOrder(id)
• createOrder(data)
• updateOrder(id, data)
• deleteOrder(id, params?)
• getCustomers(params?)
• getCustomer(id)
• createCustomer(data)
• updateCustomer(id, data)
• getCoupons(params?)
• getCoupon(id)
• createCoupon(data)
• updateCoupon(id, data)
• deleteCoupon(id, params?)
• getCategories(params?)
• getReports(type?)
• getSystemStatus()
• getShippingZones()

Error handling

const { WooCommerceRestApiError } = require('woocommerce-rest-api');

try {
  await api.getProduct(999999);
} catch (error) {
  if (error instanceof WooCommerceRestApiError) {
    console.error(error.statusCode);
    console.error(error.body);
    console.error(error.request);
  }
}

License

This package is licensed under the MIT License. See LICENSE.