WooCommerce API Client

A TypeScript-friendly WooCommerce REST API client wrapper with comprehensive type definitions for the WooCommerce REST API.

Features

• 🔒 Type-Safe: Full TypeScript support with comprehensive type definitions
• 🚀 Modern: Built with modern JavaScript and TypeScript
• 🧩 Modular: Organized API endpoints for easy access
• 📚 Well-Documented: Detailed documentation and examples
• 🔄 Complete API Coverage: Support for all major WooCommerce REST API endpoints

Installation

npm install @dotyigit/woocommerce-api-client

or with yarn:

yarn add @dotyigit/woocommerce-api-client

Quick Start

import { WooCommerce } from '@dotyigit/woocommerce-api-client';

// Initialize the client
const api = new WooCommerce({
  url: 'https://example.com',
  consumerKey: 'ck_your_consumer_key',
  consumerSecret: 'cs_your_consumer_secret',
});

// Example: Get all products
async function getProducts() {
  try {
    const products = await api.products.list();
    console.log(products);
  } catch (error) {
    console.error('Error fetching products:', error);
  }
}

getProducts();

Pagination and Resource Counts

All list methods now return both the data and pagination information, including the total number of resources and total pages. This information is extracted from the WordPress API response headers (X-WP-Total and X-WP-TotalPages).

// Getting products with pagination info
async function getProductsWithPagination() {
  try {
    const result = await api.products.list({ page: 1, per_page: 10 });

    // Access the products
    console.log(`Fetched ${result.data.length} products`);

    // Access pagination info
    console.log(`Total products: ${result.pagination.total}`);
    console.log(`Total pages: ${result.pagination.totalPages}`);

    // Use the pagination info for UI components
    if (result.pagination.totalPages > 1) {
      console.log('There are more pages to fetch');
    }
  } catch (error) {
    console.error('Error fetching products:', error);
  }
}

Efficiently Getting Resource Counts

To efficiently retrieve just the resource counts without fetching unnecessary data, use the getTotals method:

// Get only the total counts for any resource type
async function getProductCounts() {
  try {
    // Only retrieves the count information with minimal data transfer
    const counts = await api.getTotals('products', { category: 123 });

    console.log(`Total products: ${counts.total}`);
    console.log(`Total pages: ${counts.totalPages}`);
  } catch (error) {
    console.error('Error fetching product counts:', error);
  }
}

This method is optimized for retrieving just the count information by:

• Setting per_page to 1 to minimize data transfer
• Requesting only the id field to further reduce response size
• Extracting the total counts from the headers

It's perfect for scenarios where you only need count information, such as for pagination UI components or statistics.

Data Syncing Support

All list methods now support date-based filtering for efficient data synchronization between systems. You can use the modified_after and modified_before parameters with any list method to retrieve only resources that have been modified within a specific time range.

// Get only products modified after a specific date
async function getRecentlyModifiedProducts() {
  try {
    const yesterday = new Date();
    yesterday.setDate(yesterday.getDate() - 1);

    const result = await api.products.list({
      modified_after: yesterday.toISOString(),
    });

    console.log(`Fetched ${result.data.length} recently modified products`);
  } catch (error) {
    console.error('Error fetching modified products:', error);
  }
}

// Sync products between a specific date range
async function syncProductsInDateRange() {
  try {
    const startDate = new Date('2023-01-01T00:00:00Z');
    const endDate = new Date('2023-01-31T23:59:59Z');

    const result = await api.products.list({
      modified_after: startDate.toISOString(),
      modified_before: endDate.toISOString(),
    });

    console.log(
      `Syncing ${result.data.length} products modified in January 2023`
    );
  } catch (error) {
    console.error('Error syncing products:', error);
  }
}

These parameters work with all resource types that support list operations, including:

• Products
• Product Variations
• Product Categories
• Product Attributes
• Orders
• Customers
• Coupons
• Webhooks
• Payment Gateways

Date Format

For the modified_after and modified_before parameters, provide dates in ISO8601 format (e.g., 2023-01-01T00:00:00Z). JavaScript's Date.toISOString() method provides the correct format.

Configuration

The WooCommerce constructor accepts the following configuration options:

interface WooCommerceConfig {
  url: string; // Your WooCommerce store URL (required)
  consumerKey: string; // Your consumer key (required)
  consumerSecret: string; // Your consumer secret (required)
  version?: string; // API version (default: 'wc/v3')
  queryStringAuth?: boolean; // Use query string for authentication (default: true)
  timeout?: number; // Request timeout in milliseconds (default: 10000)
}

Example:

const api = new WooCommerce({
  url: 'https://example.com',
  consumerKey: 'ck_your_consumer_key',
  consumerSecret: 'cs_your_consumer_secret',
  version: 'wc/v3',
  queryStringAuth: true,
  timeout: 15000,
});

API Reference

Customers

Methods for managing customers.

customers.list(params?: CustomerListParams): Promise<Customer[]>

Get a list of customers with optional filtering.

const customers = await api.customers.list({
  page: 1,
  per_page: 20,
  search: 'john',
  // Other filter parameters available
});

customers.get(id: number): Promise<Customer>

Get a specific customer by ID.

const customer = await api.customers.get(123);

customers.create(data: CustomerCreateParams): Promise<Customer>

Create a new customer.

const newCustomer = await api.customers.create({
  email: '[email protected]',
  first_name: 'John',
  last_name: 'Doe',
  username: 'john.doe',
  // Optional fields
  password: 'secure_password',
  billing: {
    first_name: 'John',
    last_name: 'Doe',
    company: 'Acme Inc',
    address_1: '123 Main St',
    city: 'San Francisco',
    state: 'CA',
    postcode: '94103',
    country: 'US',
    email: '[email protected]',
    phone: '(555) 555-5555',
  },
  shipping: {
    first_name: 'John',
    last_name: 'Doe',
    company: 'Acme Inc',
    address_1: '123 Main St',
    city: 'San Francisco',
    state: 'CA',
    postcode: '94103',
    country: 'US',
  },
});

customers.update(id: number, data: Partial<CustomerCreateParams>): Promise<Customer>

Update an existing customer.

const updatedCustomer = await api.customers.update(123, {
  first_name: 'Johnny',
  billing: {
    first_name: 'Johnny',
  },
});

customers.delete(id: number, force: boolean = false): Promise<Customer>

Delete a customer.

// Delete a customer (move to trash)
const deletedCustomer = await api.customers.delete(123);

// Force delete a customer
const forceDeletedCustomer = await api.customers.delete(123, true);

customers.batch(data: { create?: CustomerCreateParams[]; update?: Array<Partial<Customer> & { id: number }>; delete?: number[] }): Promise<{ create?: Customer[]; update?: Customer[]; delete?: Customer[] }>

Batch update customers.

const batchResult = await api.customers.batch({
  create: [
    {
      email: '[email protected]',
      first_name: 'Jane',
      last_name: 'Doe',
    },
  ],
  update: [
    {
      id: 123,
      first_name: 'Johnny',
    },
  ],
  delete: [456],
});

Products

Methods for managing products.

products.list(params?: ProductListParams): Promise<Product[]>

Get a list of products with optional filtering.

const products = await api.products.list({
  page: 1,
  per_page: 20,
  search: 't-shirt',
  category: 15,
  status: 'publish',
  // Other filter parameters available
});

products.get(id: number): Promise<Product>

Get a specific product by ID.

const product = await api.products.get(123);

products.create(data: ProductCreateParams): Promise<Product>

Create a new product.

const newProduct = await api.products.create({
  name: 'Premium T-Shirt',
  type: 'simple',
  regular_price: '29.99',
  description: 'Soft premium cotton t-shirt',
  short_description: 'Premium cotton t-shirt',
  categories: [
    {
      id: 15,
    },
  ],
  images: [
    {
      src: 'http://example.com/wp-content/uploads/2023/06/t-shirt.jpg',
    },
  ],
});

products.update(id: number, data: Partial<ProductCreateParams>): Promise<Product>

Update an existing product.

const updatedProduct = await api.products.update(123, {
  regular_price: '34.99',
  sale_price: '29.99',
});

products.delete(id: number, force: boolean = false): Promise<Product>

Delete a product.

// Delete a product (move to trash)
const deletedProduct = await api.products.delete(123);

// Force delete a product
const forceDeletedProduct = await api.products.delete(123, true);

products.batch(data: { create?: ProductCreateParams[]; update?: Array<Partial<Product> & { id: number }>; delete?: number[] }): Promise<{ create?: Product[]; update?: Product[]; delete?: Product[] }>

Batch update products.

const batchResult = await api.products.batch({
  create: [
    {
      name: 'Premium T-Shirt',
      type: 'simple',
      regular_price: '29.99',
    },
  ],
  update: [
    {
      id: 123,
      sale_price: '24.99',
    },
  ],
  delete: [456],
});

Product Categories

Methods for managing product categories.

productCategories.list(params?: ProductCategoryListParams): Promise<ProductCategory[]>

Get a list of product categories with optional filtering.

const categories = await api.productCategories.list({
  page: 1,
  per_page: 20,
  parent: 0,
});

productCategories.get(id: number): Promise<ProductCategory>

Get a specific product category by ID.

const category = await api.productCategories.get(15);

productCategories.create(data: ProductCategoryCreateParams): Promise<ProductCategory>

Create a new product category.

const newCategory = await api.productCategories.create({
  name: 'Accessories',
  parent: 0,
  description: 'Accessories for all products',
});

productCategories.update(id: number, data: Partial<ProductCategoryCreateParams>): Promise<ProductCategory>

Update an existing product category.

const updatedCategory = await api.productCategories.update(15, {
  description: 'Updated description for accessories',
});

productCategories.delete(id: number, force: boolean = false): Promise<ProductCategory>

Delete a product category.

// Delete a category
const deletedCategory = await api.productCategories.delete(15);

// Force delete a category
const forceDeletedCategory = await api.productCategories.delete(15, true);

productCategories.batch(data: { create?: ProductCategoryCreateParams[]; update?: Array<Partial<ProductCategory> & { id: number }>; delete?: number[] }): Promise<{ create?: ProductCategory[]; update?: ProductCategory[]; delete?: ProductCategory[] }>

Batch update product categories.

const batchResult = await api.productCategories.batch({
  create: [
    {
      name: 'New Category',
      parent: 0,
    },
  ],
  update: [
    {
      id: 15,
      description: 'Updated description',
    },
  ],
  delete: [16],
});

Product Attributes

Methods for managing product attributes and terms.

productAttributes.list(params?: ProductAttributeListParams): Promise<ProductAttributeDetails[]>

Get a list of product attributes.

const attributes = await api.productAttributes.list();

productAttributes.get(id: number): Promise<ProductAttributeDetails>

Get a specific product attribute by ID.

const attribute = await api.productAttributes.get(1);

productAttributes.create(data: ProductAttributeCreateParams): Promise<ProductAttributeDetails>

Create a new product attribute.

const newAttribute = await api.productAttributes.create({
  name: 'Size',
  slug: 'size',
  type: 'select',
  order_by: 'menu_order',
  has_archives: true,
});

productAttributes.update(id: number, data: Partial<ProductAttributeCreateParams>): Promise<ProductAttributeDetails>

Update an existing product attribute.

const updatedAttribute = await api.productAttributes.update(1, {
  order_by: 'name',
});

productAttributes.delete(id: number, force: boolean = false): Promise<ProductAttributeDetails>

Delete a product attribute.

const deletedAttribute = await api.productAttributes.delete(1);

productAttributes.batch(data: { create?: ProductAttributeCreateParams[]; update?: Array<Partial<ProductAttributeDetails> & { id: number }>; delete?: number[] }): Promise<{ create?: ProductAttributeDetails[]; update?: ProductAttributeDetails[]; delete?: ProductAttributeDetails[] }>

Batch update product attributes.

const batchResult = await api.productAttributes.batch({
  create: [
    {
      name: 'Color',
      slug: 'color',
      type: 'select',
    },
  ],
  update: [
    {
      id: 1,
      has_archives: false,
    },
  ],
  delete: [2],
});

productAttributes.listTerms(attributeId: number, params?: ProductAttributeTermListParams): Promise<PaginatedResponse<ProductAttributeTerm>>

Get a list of terms for a specific attribute with pagination information.

const result = await api.productAttributes.listTerms(1);
console.log(`Terms: ${result.data.length}`);
console.log(`Total terms: ${result.pagination.total}`);

productAttributes.getTerm(attributeId: number, termId: number): Promise<ProductAttributeTerm>

Get a specific term by ID.

const term = await api.productAttributes.getTerm(1, 5);

productAttributes.createTerm(attributeId: number, data: ProductAttributeTermCreateParams): Promise<ProductAttributeTerm>

Create a new term for an attribute.

const newTerm = await api.productAttributes.createTerm(1, {
  name: 'Large',
  slug: 'large',
});

productAttributes.updateTerm(attributeId: number, termId: number, data: Partial<ProductAttributeTermCreateParams>): Promise<ProductAttributeTerm>

Update an existing term.

const updatedTerm = await api.productAttributes.updateTerm(1, 5, {
  description: 'Large size',
});

productAttributes.deleteTerm(attributeId: number, termId: number, force: boolean = false): Promise<ProductAttributeTerm>

Delete a term.

const deletedTerm = await api.productAttributes.deleteTerm(1, 5);

productAttributes.batchTerms(attributeId: number, data: { create?: ProductAttributeTermCreateParams[]; update?: Array<Partial<ProductAttributeTerm> & { id: number }>; delete?: number[] }): Promise<{ create?: ProductAttributeTerm[]; update?: ProductAttributeTerm[]; delete?: ProductAttributeTerm[] }>

Batch update terms for an attribute.

const batchResult = await api.productAttributes.batchTerms(1, {
  create: [
    {
      name: 'Medium',
      slug: 'medium',
    },
  ],
  update: [
    {
      id: 5,
      description: 'Updated description',
    },
  ],
  delete: [6],
});

Coupons

Methods for managing coupons.

coupons.list(params?: CouponListParams): Promise<Coupon[]>

Get a list of coupons with optional filtering.

const coupons = await api.coupons.list({
  page: 1,
  per_page: 20,
  code: 'SUMMER',
});

coupons.get(id: number): Promise<Coupon>

Get a specific coupon by ID.

const coupon = await api.coupons.get(123);

coupons.create(data: CouponCreateParams): Promise<Coupon>

Create a new coupon.

const newCoupon = await api.coupons.create({
  code: 'SUMMER20',
  discount_type: 'percent',
  amount: '20',
  individual_use: true,
  exclude_sale_items: true,
  minimum_amount: '100.00',
});

coupons.update(id: number, data: Partial<CouponCreateParams>): Promise<Coupon>

Update an existing coupon.

const updatedCoupon = await api.coupons.update(123, {
  amount: '25',
  minimum_amount: '75.00',
});

coupons.delete(id: number, force: boolean = false): Promise<Coupon>

Delete a coupon.

const deletedCoupon = await api.coupons.delete(123);

coupons.batch(data: { create?: CouponCreateParams[]; update?: Array<Partial<Coupon> & { id: number }>; delete?: number[] }): Promise<{ create?: Coupon[]; update?: Coupon[]; delete?: Coupon[] }>

Batch update coupons.

const batchResult = await api.coupons.batch({
  create: [
    {
      code: 'FALL20',
      discount_type: 'percent',
      amount: '20',
    },
  ],
  update: [
    {
      id: 123,
      amount: '25',
    },
  ],
  delete: [124],
});

Payment Gateways

Methods for managing payment gateways.

paymentGateways.list(): Promise<PaymentGateway[]>

Get a list of all payment gateways.

const gateways = await api.paymentGateways.list();

paymentGateways.get(id: string): Promise<PaymentGateway>

Get a specific payment gateway by ID.

const gateway = await api.paymentGateways.get('stripe');

paymentGateways.update(id: string, data: Partial<PaymentGateway>): Promise<PaymentGateway>

Update a payment gateway.

const updatedGateway = await api.paymentGateways.update('stripe', {
  enabled: true,
  title: 'Credit Card (Stripe)',
  description: 'Pay with your credit card via Stripe.',
});

Orders

Methods for managing orders.

orders.list(params?: OrderListParams): Promise<Order[]>

Get a list of orders with optional filtering.

const orders = await api.orders.list({
  page: 1,
  per_page: 20,
  status: 'processing',
  customer: 123,
});

orders.get(id: number): Promise<Order>

Get a specific order by ID.

const order = await api.orders.get(123);

orders.create(data: OrderCreateParams): Promise<Order>

Create a new order.

const newOrder = await api.orders.create({
  payment_method: 'stripe',
  payment_method_title: 'Credit Card',
  set_paid: true,
  customer_id: 123,
  billing: {
    first_name: 'John',
    last_name: 'Doe',
    address_1: '123 Main St',
    city: 'San Francisco',
    state: 'CA',
    postcode: '94103',
    country: 'US',
    email: '[email protected]',
    phone: '(555) 555-5555',
  },
  shipping: {
    first_name: 'John',
    last_name: 'Doe',
    address_1: '123 Main St',
    city: 'San Francisco',
    state: 'CA',
    postcode: '94103',
    country: 'US',
  },
  line_items: [
    {
      product_id: 93,
      quantity: 2,
    },
    {
      product_id: 22,
      variation_id: 23,
      quantity: 1,
    },
  ],
  shipping_lines: [
    {
      method_id: 'flat_rate',
      method_title: 'Flat Rate',
      total: '10.00',
    },
  ],
});

orders.update(id: number, data: Partial<OrderCreateParams>): Promise<Order>

Update an existing order.

const updatedOrder = await api.orders.update(123, {
  status: 'completed',
});

orders.delete(id: number, force: boolean = false): Promise<Order>

Delete an order.

const deletedOrder = await api.orders.delete(123);

orders.batch(data: { create?: OrderCreateParams[]; update?: Array<Partial<Order> & { id: number }>; delete?: number[] }): Promise<{ create?: Order[]; update?: Order[]; delete?: Order[] }>

Batch update orders.

const batchResult = await api.orders.batch({
  create: [
    {
      payment_method: 'stripe',
      payment_method_title: 'Credit Card',
      set_paid: true,
      customer_id: 123,
      line_items: [
        {
          product_id: 93,
          quantity: 2,
        },
      ],
    },
  ],
  update: [
    {
      id: 123,
      status: 'completed',
    },
  ],
  delete: [124],
});

Webhooks

Methods for managing webhooks.

webhooks.list(params?: WebhookListParams): Promise<Webhook[]>

Get a list of webhooks with optional filtering.

const webhooks = await api.webhooks.list({
  page: 1,
  per_page: 20,
  status: 'active',
});

webhooks.get(id: number): Promise<Webhook>

Get a specific webhook by ID.

const webhook = await api.webhooks.get(123);

webhooks.create(data: WebhookCreateParams): Promise<Webhook>

Create a new webhook.

const newWebhook = await api.webhooks.create({
  name: 'Order created',
  topic: 'order.created',
  delivery_url: 'https://example.com/webhooks/order-created',
  secret: 'my-secret-key',
});

webhooks.update(id: number, data: Partial<WebhookCreateParams>): Promise<Webhook>

Update an existing webhook.

const updatedWebhook = await api.webhooks.update(123, {
  status: 'paused',
});

webhooks.delete(id: number, force: boolean = false): Promise<Webhook>

Delete a webhook.

const deletedWebhook = await api.webhooks.delete(123);

webhooks.batch(data: { create?: WebhookCreateParams[]; update?: Array<Partial<Webhook> & { id: number }>; delete?: number[] }): Promise<{ create?: Webhook[]; update?: Webhook[]; delete?: Webhook[] }>

Batch update webhooks.

const batchResult = await api.webhooks.batch({
  create: [
    {
      name: 'Product created',
      topic: 'product.created',
      delivery_url: 'https://example.com/webhooks/product-created',
    },
  ],
  update: [
    {
      id: 123,
      status: 'active',
    },
  ],
  delete: [124],
});

Error Handling

The library uses Axios for HTTP requests. Errors are thrown as Axios error objects, which include details about the request and response.

try {
  const products = await api.products.list();
  console.log(products);
} catch (error) {
  if (error.response) {
    // The request was made and the server responded with a status code
    // that falls out of the range of 2xx
    console.error('Error status:', error.response.status);
    console.error('Error data:', error.response.data);
  } else if (error.request) {
    // The request was made but no response was received
    console.error('No response received:', error.request);
  } else {
    // Something happened in setting up the request that triggered an Error
    console.error('Error message:', error.message);
  }
}

TypeScript Support

This library is built with TypeScript and provides comprehensive type definitions for all WooCommerce API endpoints and data structures. You can import these types for use in your own code:

import {
  Customer,
  Product,
  Order,
  Coupon,
  PaymentGateway,
  Webhook,
  // etc.
} from '@dotyigit/woocommerce-api-client';

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

License

This project is licensed under the MIT License - see the LICENSE file for details.

Development

Code Style and Linting

This project uses ESLint and Prettier for code formatting and linting, but keeps them as separate tools:

• ESLint - For code quality rules and TypeScript-specific linting
• Prettier - For code formatting and style consistency

ESLint

To run ESLint:

# Check for linting errors
npm run lint

# Fix automatically fixable errors
npm run lint:fix

Prettier

To run Prettier:

# Format code
npm run format

# Check if files are formatted correctly
npm run format:check

Running Both

To run both ESLint and Prettier together:

npm run style

Pre-commit Hooks

This project uses Husky and lint-staged to automatically format and lint your code before committing:

• All TypeScript files will be formatted with Prettier
• All TypeScript files will be linted with ESLint

This ensures the codebase maintains a consistent style and passes all linting rules.