docs: add comprehensive WooCommerce REST API v3 documentation #78

- Created detailed markdown documentation for WooCommerce REST API v3
- Focused on Products, Orders, and Customers endpoints
- Includes authentication methods (OAuth 1.0a and HTTP Basic Auth)
- Comprehensive property descriptions and examples
- Pagination, error handling, and common parameters
- Request/response examples for all CRUD operations
- Best practices for security, performance, and data synchronization
- Based on official WooCommerce REST API documentation

🤖 Generated with Claude Code (https://claude.com/claude-code)

Co-Authored-By: Claude <noreply@anthropic.com>

docs/woocommerce-api.md

@@ -0,0 +1,1282 @@
+# WooCommerce REST API v3 Documentation
+
+## Table of Contents
+
+1. [Introduction](#introduction)
+2. [Authentication](#authentication)
+3. [Products API](#products-api)
+4. [Orders API](#orders-api)
+5. [Customers API](#customers-api)
+6. [Pagination](#pagination)
+7. [Error Handling](#error-handling)
+8. [Common Parameters](#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:**
+```bash
+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
+
+```json
+{
+  "id": 123,
+  "src": "https://example.com/image.jpg",
+  "name": "Product image",
+  "alt": "Alt text"
+}
+```
+
+#### Attributes Structure
+
+```json
+{
+  "id": 1,
+  "name": "Color",
+  "position": 0,
+  "visible": true,
+  "variation": false,
+  "options": ["Red", "Blue", "Green"]
+}
+```
+
+### List All Products
+
+**Request:**
+```http
+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:**
+```bash
+curl https://example.com/wp-json/wc/v3/products?per_page=20&status=publish \
+  -u consumer_key:consumer_secret
+```
+
+**Response:**
+```json
+[
+  {
+    "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:**
+```http
+GET /wp-json/wc/v3/products/{id}
+```
+
+**Example:**
+```bash
+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:**
+```http
+POST /wp-json/wc/v3/products
+```
+
+**Example:**
+```bash
+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:**
+```http
+PUT /wp-json/wc/v3/products/{id}
+PATCH /wp-json/wc/v3/products/{id}
+```
+
+**Example:**
+```bash
+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:**
+```http
+DELETE /wp-json/wc/v3/products/{id}
+```
+
+**Query Parameters:**
+- `force` (boolean): Set to `true` to permanently delete (default moves to trash)
+
+**Example:**
+```bash
+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
+
+```json
+{
+  "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
+
+```json
+{
+  "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:**
+```http
+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:**
+```bash
+curl https://example.com/wp-json/wc/v3/orders?status=processing&per_page=20 \
+  -u consumer_key:consumer_secret
+```
+
+**Response:**
+```json
+[
+  {
+    "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:**
+```http
+GET /wp-json/wc/v3/orders/{id}
+```
+
+**Example:**
+```bash
+curl https://example.com/wp-json/wc/v3/orders/456 \
+  -u consumer_key:consumer_secret
+```
+
+### Create an Order
+
+**Request:**
+```http
+POST /wp-json/wc/v3/orders
+```
+
+**Example:**
+```bash
+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:**
+```http
+PUT /wp-json/wc/v3/orders/{id}
+PATCH /wp-json/wc/v3/orders/{id}
+```
+
+**Example:**
+```bash
+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:**
+```http
+GET /wp-json/wc/v3/orders/{order_id}/notes
+```
+
+**Create Order Note:**
+```http
+POST /wp-json/wc/v3/orders/{order_id}/notes
+```
+
+**Example:**
+```bash
+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:**
+```http
+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:**
+```bash
+curl https://example.com/wp-json/wc/v3/customers?per_page=20&orderby=registered_date \
+  -u consumer_key:consumer_secret
+```
+
+**Response:**
+```json
+[
+  {
+    "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:**
+```http
+GET /wp-json/wc/v3/customers/{id}
+```
+
+**Example:**
+```bash
+curl https://example.com/wp-json/wc/v3/customers/789 \
+  -u consumer_key:consumer_secret
+```
+
+### Create a Customer
+
+**Request:**
+```http
+POST /wp-json/wc/v3/customers
+```
+
+**Example:**
+```bash
+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:**
+```http
+PUT /wp-json/wc/v3/customers/{id}
+PATCH /wp-json/wc/v3/customers/{id}
+```
+
+**Example:**
+```bash
+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:**
+```http
+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:**
+```bash
+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:**
+```http
+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
+
+```bash
+# 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:
+
+```json
+{
+  "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:**
+```json
+{
+  "code": "woocommerce_rest_authentication_error",
+  "message": "Invalid signature - provided signature does not match",
+  "data": {
+    "status": 401
+  }
+}
+```
+
+**Not Found Error:**
+```json
+{
+  "code": "woocommerce_rest_product_invalid_id",
+  "message": "Invalid ID",
+  "data": {
+    "status": 404
+  }
+}
+```
+
+**Invalid Parameter Error:**
+```json
+{
+  "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:**
+```typescript
+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:
+
+```bash
+# 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
+
+```bash
+# 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:**
+```typescript
+// 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