shopcall/docs/woocommerce-api.md

WooCommerce REST API v3 Documentation

Table of Contents

1. Introduction
2. Authentication
3. Products API
4. Orders API
5. Customers API
6. Pagination
7. Error Handling
8. Common Parameters

---

Introduction

The WooCommerce REST API v3 provides programmatic access to WooCommerce store data. This documentation focuses on the three main resources used in ShopCall.ai integration: Products, Orders, and Customers.

Base URL

All API requests use the following base URL pattern:

https://your-store.com/wp-json/wc/v3/

Requirements

• WooCommerce: Version 3.5 or higher
• WordPress: Version 4.4 or higher
• Pretty Permalinks: Must be enabled in WordPress settings
• HTTPS: Recommended (HTTP requires OAuth 1.0a)

API Version

This documentation covers WooCommerce REST API v3, which is the latest stable version.

Important: This is NOT the legacy WooCommerce API (v1, v2, v3 at /wc-api/v*). The modern REST API uses /wp-json/wc/v3/.

---

Authentication

WooCommerce REST API supports two authentication methods depending on your connection type.

HTTP Basic Authentication (HTTPS - Recommended)

For secure HTTPS connections, use HTTP Basic Auth with your API credentials:

Headers:

Authorization: Basic <base64_encoded_credentials>

Where <base64_encoded_credentials> is the Base64 encoding of consumer_key:consumer_secret.

Example:

curl https://example.com/wp-json/wc/v3/products \
  -u consumer_key:consumer_secret

OAuth 1.0a (HTTP)

For non-HTTPS connections, WooCommerce uses OAuth 1.0a "one-legged" authentication to prevent credential interception.

Required Parameters:

• oauth_consumer_key - Your API consumer key
• oauth_timestamp - Unix timestamp (must be within 15 minutes)
• oauth_nonce - 32-character random string, unique per consumer key
• oauth_signature - HMAC-SHA1 or HMAC-SHA256 signature
• oauth_signature_method - Either HMAC-SHA1 or HMAC-SHA256

Signature Generation:

1. Create signature base string from HTTP method, URL, and sorted parameters
2. Generate HMAC hash using consumer secret as key
3. Base64 encode the hash

Example OAuth 1.0a Request:

GET /wp-json/wc/v3/products?oauth_consumer_key=ck_xxx&oauth_timestamp=1234567890&oauth_nonce=abc123...&oauth_signature=xyz789...&oauth_signature_method=HMAC-SHA256

Generating API Keys

1. Go to WooCommerce > Settings > Advanced > REST API
2. Click Add Key
3. Select user and permissions (Read/Write/Read-Write)
4. Generate and save your Consumer Key and Consumer Secret

---

Products API

The Products API allows you to create, view, update, and delete products.

Endpoints

Method	Endpoint	Description
GET	/wp-json/wc/v3/products	List all products
GET	/wp-json/wc/v3/products/{id}	Retrieve a single product
POST	/wp-json/wc/v3/products	Create a product
PUT/PATCH	/wp-json/wc/v3/products/{id}	Update a product
DELETE	/wp-json/wc/v3/products/{id}	Delete a product
POST	/wp-json/wc/v3/products/batch	Batch update products

Product Properties

Core Fields

Property	Type	Description
id	integer	Unique product identifier (read-only)
name	string	Product name/title
slug	string	URL-friendly product name
permalink	string	Product URL (read-only)
date_created	string	ISO8601 date when created (read-only)
date_modified	string	ISO8601 date when last modified (read-only)
type	string	Product type: simple, grouped, external, variable
status	string	Status: draft, pending, private, publish
featured	boolean	Featured product flag
catalog_visibility	string	Visibility: visible, catalog, search, hidden
description	string	Full product description (HTML)
short_description	string	Short product description (HTML)
sku	string	Stock Keeping Unit
price	string	Current price (read-only)
regular_price	string	Regular price
sale_price	string	Sale price
on_sale	boolean	Sale status (read-only)
purchasable	boolean	Can be purchased (read-only)
total_sales	integer	Total units sold (read-only)
virtual	boolean	Is virtual product
downloadable	boolean	Is downloadable product
external_url	string	External product URL (for external products)
button_text	string	External product button text

Inventory Management

Property	Type	Description
manage_stock	boolean	Enable stock management
stock_quantity	integer	Current stock quantity
stock_status	string	Stock status: instock, outofstock, onbackorder
backorders	string	Backorder policy: no, notify, yes
backorders_allowed	boolean	Backorders allowed (read-only)
backordered	boolean	Is on backorder (read-only)
low_stock_amount	integer	Low stock threshold
sold_individually	boolean	Limit purchases to 1 per order

Pricing & Tax

Property	Type	Description
tax_status	string	Tax status: taxable, shipping, none
tax_class	string	Tax class
price_html	string	Formatted price HTML (read-only)

Shipping

Property	Type	Description
shipping_required	boolean	Requires shipping
shipping_taxable	boolean	Is shipping taxable
shipping_class	string	Shipping class slug
shipping_class_id	integer	Shipping class ID
weight	string	Product weight
dimensions	object	Product dimensions: length, width, height

Organization

Property	Type	Description
categories	array	List of category objects with id and name
tags	array	List of tag objects with id and name
images	array	List of product images (see Images section)
attributes	array	List of product attributes (see Attributes section)

Images Structure

{
  "id": 123,
  "src": "https://example.com/image.jpg",
  "name": "Product image",
  "alt": "Alt text"
}

Attributes Structure

{
  "id": 1,
  "name": "Color",
  "position": 0,
  "visible": true,
  "variation": false,
  "options": ["Red", "Blue", "Green"]
}

List All Products

Request:

GET /wp-json/wc/v3/products

Query Parameters:

Parameter	Type	Description
context	string	Scope: view or edit. Default: view
page	integer	Current page. Default: 1
per_page	integer	Results per page. Default: 10, Max: 100
search	string	Search by product name or SKU
after	string	ISO8601 date - products created after
before	string	ISO8601 date - products created before
exclude	array	Product IDs to exclude
include	array	Product IDs to include
offset	integer	Offset results
order	string	Sort order: asc or desc. Default: desc
orderby	string	Sort by: date, id, include, title, slug. Default: date
parent	array	Parent product IDs
parent_exclude	array	Parent product IDs to exclude
slug	string	Product slug
status	string	Product status: any, draft, pending, private, publish
type	string	Product type: simple, grouped, external, variable
sku	string	Filter by SKU
featured	boolean	Featured products only
category	string	Category slug
tag	string	Tag slug
on_sale	boolean	On sale products only
min_price	string	Minimum price
max_price	string	Maximum price
stock_status	string	Stock status: instock, outofstock, onbackorder

Example Request:

curl https://example.com/wp-json/wc/v3/products?per_page=20&status=publish \
  -u consumer_key:consumer_secret

Response:

[
  {
    "id": 123,
    "name": "Premium T-Shirt",
    "slug": "premium-t-shirt",
    "permalink": "https://example.com/product/premium-t-shirt/",
    "date_created": "2025-01-15T10:30:00",
    "date_modified": "2025-01-20T14:25:00",
    "type": "simple",
    "status": "publish",
    "featured": false,
    "catalog_visibility": "visible",
    "description": "<p>High quality cotton t-shirt</p>",
    "short_description": "<p>Comfortable premium tee</p>",
    "sku": "TSHIRT-001",
    "price": "29.99",
    "regular_price": "29.99",
    "sale_price": "",
    "on_sale": false,
    "purchasable": true,
    "total_sales": 45,
    "virtual": false,
    "downloadable": false,
    "manage_stock": true,
    "stock_quantity": 100,
    "stock_status": "instock",
    "backorders": "no",
    "backorders_allowed": false,
    "backordered": false,
    "sold_individually": false,
    "weight": "0.2",
    "dimensions": {
      "length": "",
      "width": "",
      "height": ""
    },
    "shipping_required": true,
    "shipping_taxable": true,
    "shipping_class": "",
    "shipping_class_id": 0,
    "tax_status": "taxable",
    "tax_class": "",
    "categories": [
      {
        "id": 9,
        "name": "Clothing",
        "slug": "clothing"
      }
    ],
    "tags": [
      {
        "id": 15,
        "name": "Cotton",
        "slug": "cotton"
      }
    ],
    "images": [
      {
        "id": 456,
        "src": "https://example.com/wp-content/uploads/tshirt.jpg",
        "name": "tshirt.jpg",
        "alt": "Premium T-Shirt"
      }
    ],
    "attributes": [],
    "_links": {
      "self": [{"href": "https://example.com/wp-json/wc/v3/products/123"}]
    }
  }
]

Retrieve a Product

Request:

GET /wp-json/wc/v3/products/{id}

Example:

curl https://example.com/wp-json/wc/v3/products/123 \
  -u consumer_key:consumer_secret

Response: Single product object (same structure as list response)

Create a Product

Request:

POST /wp-json/wc/v3/products

Example:

curl -X POST https://example.com/wp-json/wc/v3/products \
  -u consumer_key:consumer_secret \
  -H "Content-Type: application/json" \
  -d '{
    "name": "New Product",
    "type": "simple",
    "regular_price": "19.99",
    "description": "Product description",
    "short_description": "Short description",
    "categories": [{"id": 9}],
    "images": [{"src": "https://example.com/image.jpg"}]
  }'

Update a Product

Request:

PUT /wp-json/wc/v3/products/{id}
PATCH /wp-json/wc/v3/products/{id}

Example:

curl -X PATCH https://example.com/wp-json/wc/v3/products/123 \
  -u consumer_key:consumer_secret \
  -H "Content-Type: application/json" \
  -d '{
    "regular_price": "24.99",
    "stock_quantity": 75
  }'

Delete a Product

Request:

DELETE /wp-json/wc/v3/products/{id}

Query Parameters:

• force (boolean): Set to true to permanently delete (default moves to trash)

Example:

curl -X DELETE https://example.com/wp-json/wc/v3/products/123?force=true \
  -u consumer_key:consumer_secret

---

Orders API

The Orders API allows you to create, view, update, and delete orders.

Endpoints

Method	Endpoint	Description
GET	/wp-json/wc/v3/orders	List all orders
GET	/wp-json/wc/v3/orders/{id}	Retrieve a single order
POST	/wp-json/wc/v3/orders	Create an order
PUT/PATCH	/wp-json/wc/v3/orders/{id}	Update an order
DELETE	/wp-json/wc/v3/orders/{id}	Delete an order
POST	/wp-json/wc/v3/orders/batch	Batch update orders
GET	/wp-json/wc/v3/orders/{id}/notes	List order notes
POST	/wp-json/wc/v3/orders/{id}/notes	Create an order note
GET	/wp-json/wc/v3/orders/{id}/refunds	List order refunds
POST	/wp-json/wc/v3/orders/{id}/refunds	Create a refund

Order Properties

Core Fields

Property	Type	Description
id	integer	Unique order identifier (read-only)
parent_id	integer	Parent order ID
number	string	Order number (read-only)
order_key	string	Order key (read-only)
created_via	string	Source of order creation (read-only)
version	string	WooCommerce version (read-only)
status	string	Order status (see Order Statuses)
currency	string	Currency code (ISO 4217)
date_created	string	ISO8601 date when created (read-only)
date_modified	string	ISO8601 date when modified (read-only)
discount_total	string	Total discount amount
discount_tax	string	Total discount tax
shipping_total	string	Total shipping amount
shipping_tax	string	Total shipping tax
cart_tax	string	Cart tax amount
total	string	Order total
total_tax	string	Total tax amount
prices_include_tax	boolean	Prices include tax
customer_id	integer	Customer/user ID
customer_ip_address	string	Customer IP address (read-only)
customer_user_agent	string	Customer user agent (read-only)
customer_note	string	Customer-provided note
payment_method	string	Payment method ID
payment_method_title	string	Payment method title
transaction_id	string	Transaction ID
date_paid	string	ISO8601 date when paid
date_completed	string	ISO8601 date when completed
cart_hash	string	Cart hash (read-only)

Customer Details

Property	Type	Description
billing	object	Billing address (see Address Structure)
shipping	object	Shipping address (see Address Structure)

Order Items

Property	Type	Description
line_items	array	Line items data (see Line Items Structure)
tax_lines	array	Tax line items
shipping_lines	array	Shipping line items
fee_lines	array	Fee line items
coupon_lines	array	Coupon line items

Order Statuses

Status	Description
pending	Payment pending
processing	Payment received, processing order
on-hold	Awaiting payment or stock
completed	Order fulfilled and complete
cancelled	Cancelled by admin or customer
refunded	Fully refunded
failed	Payment failed or declined
trash	Moved to trash

Address Structure

{
  "first_name": "John",
  "last_name": "Doe",
  "company": "Acme Inc",
  "address_1": "123 Main St",
  "address_2": "Apt 4B",
  "city": "New York",
  "state": "NY",
  "postcode": "10001",
  "country": "US",
  "email": "john@example.com",
  "phone": "+1-555-1234"
}

Line Items Structure

{
  "id": 789,
  "name": "Premium T-Shirt",
  "product_id": 123,
  "variation_id": 0,
  "quantity": 2,
  "tax_class": "",
  "subtotal": "59.98",
  "subtotal_tax": "0.00",
  "total": "59.98",
  "total_tax": "0.00",
  "taxes": [],
  "meta_data": [],
  "sku": "TSHIRT-001",
  "price": 29.99
}

List All Orders

Request:

GET /wp-json/wc/v3/orders

Query Parameters:

Parameter	Type	Description
context	string	Scope: view or edit. Default: view
page	integer	Current page. Default: 1
per_page	integer	Results per page. Default: 10, Max: 100
search	string	Search orders
after	string	ISO8601 date - orders created after
before	string	ISO8601 date - orders created before
exclude	array	Order IDs to exclude
include	array	Order IDs to include
offset	integer	Offset results
order	string	Sort order: asc or desc. Default: desc
orderby	string	Sort by: date, id, include, title, slug. Default: date
parent	array	Parent order IDs
parent_exclude	array	Parent order IDs to exclude
status	array	Order statuses (see Order Statuses)
customer	integer	Customer user ID
product	integer	Product ID in order
dp	integer	Decimal points for amounts. Default: 2

Example Request:

curl https://example.com/wp-json/wc/v3/orders?status=processing&per_page=20 \
  -u consumer_key:consumer_secret

Response:

[
  {
    "id": 456,
    "parent_id": 0,
    "number": "456",
    "order_key": "wc_order_abc123",
    "created_via": "checkout",
    "version": "8.5.0",
    "status": "processing",
    "currency": "USD",
    "date_created": "2025-01-20T15:30:00",
    "date_modified": "2025-01-20T15:31:00",
    "discount_total": "0.00",
    "discount_tax": "0.00",
    "shipping_total": "10.00",
    "shipping_tax": "0.00",
    "cart_tax": "0.00",
    "total": "69.98",
    "total_tax": "0.00",
    "prices_include_tax": false,
    "customer_id": 789,
    "customer_ip_address": "192.168.1.1",
    "customer_user_agent": "Mozilla/5.0...",
    "customer_note": "",
    "billing": {
      "first_name": "John",
      "last_name": "Doe",
      "company": "",
      "address_1": "123 Main St",
      "address_2": "",
      "city": "New York",
      "state": "NY",
      "postcode": "10001",
      "country": "US",
      "email": "john@example.com",
      "phone": "+1-555-1234"
    },
    "shipping": {
      "first_name": "John",
      "last_name": "Doe",
      "company": "",
      "address_1": "123 Main St",
      "address_2": "",
      "city": "New York",
      "state": "NY",
      "postcode": "10001",
      "country": "US"
    },
    "payment_method": "stripe",
    "payment_method_title": "Credit Card",
    "transaction_id": "ch_abc123",
    "date_paid": "2025-01-20T15:30:15",
    "date_completed": null,
    "cart_hash": "abc123def456",
    "line_items": [
      {
        "id": 789,
        "name": "Premium T-Shirt",
        "product_id": 123,
        "variation_id": 0,
        "quantity": 2,
        "tax_class": "",
        "subtotal": "59.98",
        "subtotal_tax": "0.00",
        "total": "59.98",
        "total_tax": "0.00",
        "taxes": [],
        "meta_data": [],
        "sku": "TSHIRT-001",
        "price": 29.99
      }
    ],
    "tax_lines": [],
    "shipping_lines": [
      {
        "id": 790,
        "method_title": "Flat Rate",
        "method_id": "flat_rate",
        "total": "10.00",
        "total_tax": "0.00",
        "taxes": []
      }
    ],
    "fee_lines": [],
    "coupon_lines": [],
    "_links": {
      "self": [{"href": "https://example.com/wp-json/wc/v3/orders/456"}]
    }
  }
]

Retrieve an Order

Request:

GET /wp-json/wc/v3/orders/{id}

Example:

curl https://example.com/wp-json/wc/v3/orders/456 \
  -u consumer_key:consumer_secret

Create an Order

Request:

POST /wp-json/wc/v3/orders

Example:

curl -X POST https://example.com/wp-json/wc/v3/orders \
  -u consumer_key:consumer_secret \
  -H "Content-Type: application/json" \
  -d '{
    "payment_method": "bacs",
    "payment_method_title": "Direct Bank Transfer",
    "set_paid": true,
    "billing": {
      "first_name": "John",
      "last_name": "Doe",
      "address_1": "123 Main St",
      "city": "New York",
      "state": "NY",
      "postcode": "10001",
      "country": "US",
      "email": "john@example.com",
      "phone": "+1-555-1234"
    },
    "shipping": {
      "first_name": "John",
      "last_name": "Doe",
      "address_1": "123 Main St",
      "city": "New York",
      "state": "NY",
      "postcode": "10001",
      "country": "US"
    },
    "line_items": [
      {
        "product_id": 123,
        "quantity": 2
      }
    ],
    "shipping_lines": [
      {
        "method_id": "flat_rate",
        "method_title": "Flat Rate",
        "total": "10.00"
      }
    ]
  }'

Update an Order

Request:

PUT /wp-json/wc/v3/orders/{id}
PATCH /wp-json/wc/v3/orders/{id}

Example:

curl -X PATCH https://example.com/wp-json/wc/v3/orders/456 \
  -u consumer_key:consumer_secret \
  -H "Content-Type: application/json" \
  -d '{
    "status": "completed"
  }'

Order Notes

Order notes are internal or customer-facing messages attached to orders.

List Order Notes:

GET /wp-json/wc/v3/orders/{order_id}/notes

Create Order Note:

POST /wp-json/wc/v3/orders/{order_id}/notes

Example:

curl -X POST https://example.com/wp-json/wc/v3/orders/456/notes \
  -u consumer_key:consumer_secret \
  -H "Content-Type: application/json" \
  -d '{
    "note": "Order packed and ready for shipment",
    "customer_note": true
  }'

---

Customers API

The Customers API allows you to create, view, update, and delete customers.

Endpoints

Method	Endpoint	Description
GET	/wp-json/wc/v3/customers	List all customers
GET	/wp-json/wc/v3/customers/{id}	Retrieve a single customer
POST	/wp-json/wc/v3/customers	Create a customer
PUT/PATCH	/wp-json/wc/v3/customers/{id}	Update a customer
DELETE	/wp-json/wc/v3/customers/{id}	Delete a customer
POST	/wp-json/wc/v3/customers/batch	Batch update customers
GET	/wp-json/wc/v3/customers/{id}/downloads	List customer downloads

Customer Properties

Property	Type	Description
id	integer	Unique customer identifier (read-only)
date_created	string	ISO8601 date when created (read-only)
date_modified	string	ISO8601 date when modified (read-only)
email	string	Customer email address (required)
first_name	string	Customer first name
last_name	string	Customer last name
role	string	User role (read-only)
username	string	Customer login username
password	string	Customer password (write-only)
billing	object	Billing address (see Address Structure)
shipping	object	Shipping address (see Address Structure)
is_paying_customer	boolean	Has purchased before (read-only)
avatar_url	string	Avatar/Gravatar URL (read-only)
meta_data	array	Customer metadata (custom fields)

List All Customers

Request:

GET /wp-json/wc/v3/customers

Query Parameters:

Parameter	Type	Description
context	string	Scope: view or edit. Default: view
page	integer	Current page. Default: 1
per_page	integer	Results per page. Default: 10, Max: 100
search	string	Search customers by name or email
exclude	array	Customer IDs to exclude
include	array	Customer IDs to include
offset	integer	Offset results
order	string	Sort order: asc or desc. Default: asc
orderby	string	Sort by: id, include, name, registered_date. Default: name
email	string	Filter by email address
role	string	Filter by user role: all, administrator, customer, etc.

Example Request:

curl https://example.com/wp-json/wc/v3/customers?per_page=20&orderby=registered_date \
  -u consumer_key:consumer_secret

Response:

[
  {
    "id": 789,
    "date_created": "2025-01-10T09:15:00",
    "date_modified": "2025-01-20T14:30:00",
    "email": "john@example.com",
    "first_name": "John",
    "last_name": "Doe",
    "role": "customer",
    "username": "johndoe",
    "billing": {
      "first_name": "John",
      "last_name": "Doe",
      "company": "",
      "address_1": "123 Main St",
      "address_2": "",
      "city": "New York",
      "state": "NY",
      "postcode": "10001",
      "country": "US",
      "email": "john@example.com",
      "phone": "+1-555-1234"
    },
    "shipping": {
      "first_name": "John",
      "last_name": "Doe",
      "company": "",
      "address_1": "123 Main St",
      "address_2": "",
      "city": "New York",
      "state": "NY",
      "postcode": "10001",
      "country": "US"
    },
    "is_paying_customer": true,
    "avatar_url": "https://secure.gravatar.com/avatar/...",
    "meta_data": [],
    "_links": {
      "self": [{"href": "https://example.com/wp-json/wc/v3/customers/789"}]
    }
  }
]

Retrieve a Customer

Request:

GET /wp-json/wc/v3/customers/{id}

Example:

curl https://example.com/wp-json/wc/v3/customers/789 \
  -u consumer_key:consumer_secret

Create a Customer

Request:

POST /wp-json/wc/v3/customers

Example:

curl -X POST https://example.com/wp-json/wc/v3/customers \
  -u consumer_key:consumer_secret \
  -H "Content-Type: application/json" \
  -d '{
    "email": "jane@example.com",
    "first_name": "Jane",
    "last_name": "Smith",
    "username": "janesmith",
    "password": "SecurePass123!",
    "billing": {
      "first_name": "Jane",
      "last_name": "Smith",
      "address_1": "456 Oak Ave",
      "city": "Los Angeles",
      "state": "CA",
      "postcode": "90001",
      "country": "US",
      "email": "jane@example.com",
      "phone": "+1-555-5678"
    }
  }'

Update a Customer

Request:

PUT /wp-json/wc/v3/customers/{id}
PATCH /wp-json/wc/v3/customers/{id}

Example:

curl -X PATCH https://example.com/wp-json/wc/v3/customers/789 \
  -u consumer_key:consumer_secret \
  -H "Content-Type: application/json" \
  -d '{
    "first_name": "Jonathan",
    "billing": {
      "phone": "+1-555-9999"
    }
  }'

Delete a Customer

Request:

DELETE /wp-json/wc/v3/customers/{id}

Query Parameters:

• force (boolean): Required and must be true to delete
• reassign (integer): User ID to reassign posts to

Example:

curl -X DELETE "https://example.com/wp-json/wc/v3/customers/789?force=true" \
  -u consumer_key:consumer_secret

---

Pagination

The WooCommerce REST API uses page-based pagination for list endpoints.

Default Behavior

• Default page size: 10 items
• Maximum page size: 100 items
• Configurable via WordPress posts_per_page option

Query Parameters

Parameter	Description	Example
per_page	Items per page (1-100)	?per_page=20
page	Page number (1-based)	?page=2
offset	Offset from first item	?offset=10

Response Headers

The API includes pagination information in response headers:

Header	Description
X-WP-Total	Total number of resources
X-WP-TotalPages	Total number of pages
Link	Navigation links (next, prev, first, last)

Example Response Headers:

X-WP-Total: 157
X-WP-TotalPages: 16
Link: <https://example.com/wp-json/wc/v3/products?page=1>; rel="first",
      <https://example.com/wp-json/wc/v3/products?page=2>; rel="next",
      <https://example.com/wp-json/wc/v3/products?page=16>; rel="last"

Example Pagination

# Get first page (20 items)
curl "https://example.com/wp-json/wc/v3/products?per_page=20&page=1" \
  -u consumer_key:consumer_secret

# Get second page
curl "https://example.com/wp-json/wc/v3/products?per_page=20&page=2" \
  -u consumer_key:consumer_secret

# Use offset instead
curl "https://example.com/wp-json/wc/v3/products?per_page=20&offset=20" \
  -u consumer_key:consumer_secret

---

Error Handling

The WooCommerce REST API uses standard HTTP status codes to indicate success or failure.

HTTP Status Codes

Code	Type	Description
200	Success	Request successful
201	Created	Resource created successfully
400	Bad Request	Invalid request parameters or data
401	Unauthorized	Invalid or missing authentication
403	Forbidden	Insufficient permissions
404	Not Found	Resource does not exist
500	Server Error	Internal server error

Error Response Format

All errors return JSON with the following structure:

{
  "code": "error_identifier",
  "message": "Human-readable error description",
  "data": {
    "status": 404
  }
}

Common Error Codes

Code	HTTP Status	Description
woocommerce_rest_authentication_error	401	Authentication failed
woocommerce_rest_cannot_view	403	Insufficient permissions to view
woocommerce_rest_cannot_create	403	Insufficient permissions to create
woocommerce_rest_cannot_edit	403	Insufficient permissions to edit
woocommerce_rest_cannot_delete	403	Insufficient permissions to delete
woocommerce_rest_invalid_id	404	Resource ID not found
woocommerce_rest_shop_order_invalid_id	404	Order not found
woocommerce_rest_product_invalid_id	404	Product not found
woocommerce_rest_customer_invalid_id	404	Customer not found
rest_invalid_param	400	Invalid parameter value
rest_missing_callback_param	400	Missing required parameter

Error Examples

Authentication Error:

{
  "code": "woocommerce_rest_authentication_error",
  "message": "Invalid signature - provided signature does not match",
  "data": {
    "status": 401
  }
}

Not Found Error:

{
  "code": "woocommerce_rest_product_invalid_id",
  "message": "Invalid ID",
  "data": {
    "status": 404
  }
}

Invalid Parameter Error:

{
  "code": "rest_invalid_param",
  "message": "Invalid parameter(s): status",
  "data": {
    "status": 400,
    "params": {
      "status": "status is not one of draft, pending, private, publish"
    }
  }
}

Handling Errors in Code

JavaScript/TypeScript Example:

try {
  const response = await fetch('https://example.com/wp-json/wc/v3/products/123', {
    headers: {
      'Authorization': 'Basic ' + btoa(consumerKey + ':' + consumerSecret)
    }
  });

  if (!response.ok) {
    const error = await response.json();
    console.error(`Error ${error.data.status}: ${error.message}`);
    throw new Error(error.message);
  }

  const product = await response.json();
  return product;
} catch (error) {
  console.error('API request failed:', error);
}

---

Common Parameters

These parameters are available across most list endpoints.

Universal Parameters

Parameter	Type	Default	Description
context	string	view	Scope of response: view (public) or edit (all fields)
page	integer	1	Current page number
per_page	integer	10	Results per page (max 100)
search	string	-	Search term for full-text search
after	string	-	ISO8601 date - resources created after
before	string	-	ISO8601 date - resources created before
exclude	array	-	Resource IDs to exclude
include	array	-	Resource IDs to include
offset	integer	-	Offset results by number
order	string	desc	Sort order: asc (ascending) or desc (descending)
orderby	string	date	Sort field (varies by resource)
parent	array	-	Parent resource IDs
parent_exclude	array	-	Parent resource IDs to exclude
slug	string	-	Filter by slug

Product-Specific Parameters

Parameter	Type	Description
status	string	Product status: any, draft, pending, private, publish
type	string	Product type: simple, grouped, external, variable
category	string	Category slug
tag	string	Tag slug
sku	string	Stock Keeping Unit
featured	boolean	Featured products only
on_sale	boolean	On sale products only
min_price	string	Minimum price filter
max_price	string	Maximum price filter
stock_status	string	Stock status: instock, outofstock, onbackorder

Order-Specific Parameters

Parameter	Type	Description
status	array	Order statuses (see Order Statuses section)
customer	integer	Customer user ID
product	integer	Product ID in order
dp	integer	Decimal places for amounts (default: 2)

Customer-Specific Parameters

Parameter	Type	Description
email	string	Filter by email address
role	string	Filter by user role

Date Filtering

Use ISO8601 format for date parameters:

# Products created after January 1, 2025
curl "https://example.com/wp-json/wc/v3/products?after=2025-01-01T00:00:00" \
  -u consumer_key:consumer_secret

# Orders created in January 2025
curl "https://example.com/wp-json/wc/v3/orders?after=2025-01-01T00:00:00&before=2025-02-01T00:00:00" \
  -u consumer_key:consumer_secret

Sorting Examples

# Products by price (ascending)
curl "https://example.com/wp-json/wc/v3/products?orderby=price&order=asc" \
  -u consumer_key:consumer_secret

# Orders by date (newest first)
curl "https://example.com/wp-json/wc/v3/orders?orderby=date&order=desc" \
  -u consumer_key:consumer_secret

# Customers by name (alphabetical)
curl "https://example.com/wp-json/wc/v3/customers?orderby=name&order=asc" \
  -u consumer_key:consumer_secret

---

Rate Limiting

WooCommerce itself does not implement rate limiting, but:

• WordPress hosting providers may implement rate limits
• It's recommended to implement client-side rate limiting (5 req/sec recommended)
• Use exponential backoff for retry logic
• Batch operations reduce API calls

Recommended Rate Limiting:

// ShopCall.ai implementation uses 5 requests per second
const RATE_LIMIT = 5; // requests per second
const delay = (ms: number) => new Promise(resolve => setTimeout(resolve, ms));

async function rateLimitedRequest(url: string, options: RequestInit) {
  await delay(1000 / RATE_LIMIT);
  return fetch(url, options);
}

---

Best Practices

Security

1. Always use HTTPS in production to protect API credentials
2. Generate API keys with minimum required permissions (read-only when possible)
3. Store credentials securely using environment variables or secure vaults
4. Rotate API keys regularly
5. Never commit API keys to version control

Performance

1. Use pagination for large datasets (default 10 items may be too small)
2. Request only needed fields using _fields parameter
3. Implement caching for frequently accessed data
4. Use batch operations when updating multiple resources
5. Implement exponential backoff for retries

Error Handling

1. Check HTTP status codes before parsing response
2. Log API errors for debugging
3. Handle authentication failures gracefully
4. Implement retry logic for transient failures
5. Display user-friendly error messages

Data Synchronization

1. Track last sync timestamp for incremental updates
2. Use modified_after parameter to fetch only updated resources
3. Implement conflict resolution for concurrent updates
4. Store platform-specific IDs for mapping
5. Handle deleted resources appropriately

---

Resources

• Official Documentation: https://woocommerce.github.io/woocommerce-rest-api-docs/
• WooCommerce GitHub: https://github.com/woocommerce/woocommerce
• Support Forum: https://wordpress.org/support/plugin/woocommerce/
• Developer Blog: https://developer.woocommerce.com/

---

Changelog

• v3 - Current stable version (WooCommerce 3.5+)
• Legacy API versions (v1, v2, v3 at /wc-api/v*) are deprecated

---

Document Version: 1.0 Last Updated: 2025-01-29 API Version: WooCommerce REST API v3 Created for: ShopCall.ai Integration