# 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