woocommerce
# WooCommerce
Access the WooCommerce REST API with managed OAuth authentication. Manage products, orders, customers, coupons, shipping, taxes, and more for e-commerce operations.
## Quick Start
```bash
# List products
python <<'EOF'
import urllib.request, os, json
req = urllib.request.Request('https://gateway.maton.ai/woocommerce/wp-json/wc/v3/products')
req.add_header('Authorization', f'Bearer {os.environ["MATON_API_KEY"]}')
print(json.dumps(json.load(urllib.request.urlopen(req)), indent=2))
EOF
```
## Base URL
```
https://gateway.maton.ai/woocommerce/{native-api-path}
```
Replace `{native-api-path}` with the actual WooCommerce API endpoint path. The gateway proxies requests to your WooCommerce store and automatically handles authentication.
## Authentication
All requests require the Maton API key in the Authorization header:
```
Authorization: Bearer $MATON_API_KEY
```
**Environment Variable:** Set your API key as `MATON_API_KEY`:
```bash
export MATON_API_KEY="YOUR_API_KEY"
```
### Getting Your API Key
1. Sign in or create an account at [maton.ai](https://maton.ai)
2. Go to [maton.ai/settings](https://maton.ai/settings)
3. Copy your API key
## Connection Management
Manage your WooCommerce OAuth connections at `https://ctrl.maton.ai`.
### List Connections
```bash
python <<'EOF'
import urllib.request, os, json
req = urllib.request.Request('https://ctrl.maton.ai/connections?app=woocommerce&status=ACTIVE')
req.add_header('Authorization', f'Bearer {os.environ["MATON_API_KEY"]}')
print(json.dumps(json.load(urllib.request.urlopen(req)), indent=2))
EOF
```
### Create Connection
```bash
python <<'EOF'
import urllib.request, os, json
data = json.dumps({'app': 'woocommerce'}).encode()
req = urllib.request.Request('https://ctrl.maton.ai/connections', data=data, method='POST')
req.add_header('Authorization', f'Bearer {os.environ["MATON_API_KEY"]}')
req.add_header('Content-Type', 'application/json')
print(json.dumps(json.load(urllib.request.urlopen(req)), indent=2))
EOF
```
### Get Connection
```bash
python <<'EOF'
import urllib.request, os, json
req = urllib.request.Request('https://ctrl.maton.ai/connections/{connection_id}')
req.add_header('Authorization', f'Bearer {os.environ["MATON_API_KEY"]}')
print(json.dumps(json.load(urllib.request.urlopen(req)), indent=2))
EOF
```
**Response:**
```json
{
"connection": {
"connection_id": "21fd90f9-5935-43cd-b6c8-bde9d915ca80",
"status": "ACTIVE",
"creation_time": "2025-12-08T07:20:53.488460Z",
"last_updated_time": "2026-01-31T20:03:32.593153Z",
"url": "https://connect.maton.ai/?session_token=...",
"app": "woocommerce",
"metadata": {}
}
}
```
Open the returned `url` in a browser to complete OAuth authorization.
### Delete Connection
```bash
python <<'EOF'
import urllib.request, os, json
req = urllib.request.Request('https://ctrl.maton.ai/connections/{connection_id}', method='DELETE')
req.add_header('Authorization', f'Bearer {os.environ["MATON_API_KEY"]}')
print(json.dumps(json.load(urllib.request.urlopen(req)), indent=2))
EOF
```
### Specifying Connection
If you have multiple WooCommerce connections, specify which one to use with the `Maton-Connection` header:
```bash
python <<'EOF'
import urllib.request, os, json
req = urllib.request.Request('https://gateway.maton.ai/woocommerce/wp-json/wc/v3/products')
req.add_header('Authorization', f'Bearer {os.environ["MATON_API_KEY"]}')
req.add_header('Maton-Connection', '21fd90f9-5935-43cd-b6c8-bde9d915ca80')
print(json.dumps(json.load(urllib.request.urlopen(req)), indent=2))
EOF
```
If omitted, the gateway uses the default (oldest) active connection.
## API Reference
### Products
#### List All Products
```bash
GET /woocommerce/wp-json/wc/v3/products
```
Query parameters:
- `page` - Current page (default: 1)
- `per_page` - Items per page (default: 10, max: 100)
- `search` - Search by product name
- `status` - Filter by status: `draft`, `pending`, `private`, `publish`
- `type` - Filter by type: `simple`, `grouped`, `external`, `variable`
- `sku` - Filter by SKU
- `category` - Filter by category ID
- `tag` - Filter by tag ID
- `featured` - Filter featured products
- `on_sale` - Filter on-sale products
- `min_price` / `max_price` - Filter by price range
- `stock_status` - Filter by stock status: `instock`, `outofstock`, `onbackorder`
- `orderby` - Sort by: `date`, `id`, `include`, `title`, `slug`, `price`, `popularity`, `rating`
- `order` - Sort order: `asc`, `desc`
**Example:**
```bash
curl -s -X GET "https://gateway.maton.ai/woocommerce/wp-json/wc/v3/products?per_page=20&status=publish" -H "Authorization: Bearer $MATON_API_KEY"
```
**Response:**
```json
[
{
"id": 123,
"name": "Premium T-Shirt",
"slug": "premium-t-shirt",
"type": "simple",
"status": "publish",
"sku": "TSH-001",
"price": "29.99",
"regular_price": "34.99",
"sale_price": "29.99",
"stock_quantity": 50,
"stock_status": "instock",
"categories": [{"id": 15, "name": "Apparel"}],
"images": [{"id": 456, "src": "https://..."}]
}
]
```
#### Get a Product
```bash
GET /woocommerce/wp-json/wc/v3/products/{id}
```
**Example:**
```bash
curl -s -X GET "https://gateway.maton.ai/woocommerce/wp-json/wc/v3/products/123" -H "Authorization: Bearer $MATON_API_KEY"
```
#### Create a Product
```bash
POST /woocommerce/wp-json/wc/v3/products
Content-Type: application/json
{
"name": "New Product",
"type": "simple",
"regular_price": "49.99",
"description": "Full product description",
"short_description": "Brief description",
"sku": "PROD-001",
"manage_stock": true,
"stock_quantity": 100,
"categories": [{"id": 15}],
"images": [{"src": "https://example.com/image.jpg"}]
}
```
**Example:**
```bash
curl -s -X POST "https://gateway.maton.ai/woocommerce/wp-json/wc/v3/products" -H "Content-Type: application/json" -H "Authorization: Bearer $MATON_API_KEY" -d '{"name": "Premium Widget", "type": "simple", "regular_price": "19.99", "sku": "WDG-001"}'
```
#### Update a Product
```bash
PUT /woocommerce/wp-json/wc/v3/products/{id}
```
**Example:**
```bash
curl -s -X PUT "https://gateway.maton.ai/woocommerce/wp-json/wc/v3/products/123" -H "Content-Type: application/json" -H "Authorization: Bearer $MATON_API_KEY" -d '{"regular_price": "24.99", "sale_price": "19.99"}'
```
#### Delete a Product
```bash
DELETE /woocommerce/wp-json/wc/v3/products/{id}
```
Query parameters:
- `force` - Set to `true` to permanently delete (default: `false` moves to trash)
#### Duplicate a Product
```bash
POST /woocommerce/wp-json/wc/v3/products/{id}/duplicate
```
### Product Variations
For variable products, manage individual variations:
#### List Variations
```bash
GET /woocommerce/wp-json/wc/v3/products/{product_id}/variations
```
#### Create Variation
```bash
POST /woocommerce/wp-json/wc/v3/products/{product_id}/variations
Content-Type: application/json
{
"regular_price": "29.99",
"sku": "TSH-001-RED-M",
"attributes": [
{"id": 1, "option": "Red"},
{"id": 2, "option": "Medium"}
]
}
```
#### Update Variation
```bash
PUT /woocommerce/wp-json/wc/v3/products/{product_id}/variations/{id}
```
#### Delete Variation
```bash
DELETE /woocommerce/wp-json/wc/v3/products/{product_id}/variations/{id}
```
#### Batch Update Variations
```bash
POST /woocommerce/wp-json/wc/v3/products/{product_id}/variations/batch
```
### Product Attributes
#### List Attributes
```bash
GET /woocommerce/wp-json/wc/v3/products/attributes
```
#### Create Attribute
```bash
POST /woocommerce/wp-json/wc/v3/products/attributes
Content-Type: application/json
{
"name": "Color",
"slug": "color",
"type": "select",
"order_by": "menu_order"
}
```
#### Get/Update/Delete Attribute
```bash
GET /woocommerce/wp-json/wc/v3/products/attributes/{id}
PUT /woocommerce/wp-json/wc/v3/products/attributes/{id}
DELETE /woocommerce/wp-json/wc/v3/products/attributes/{id}
```
### Attribute Terms
```bash
GET /woocommerce/wp-json/wc/v3/products/attributes/{attribute_id}/terms
POST /woocommerce/wp-json/wc/v3/products/attributes/{attribute_id}/terms
GET /woocommerce/wp-json/wc/v3/products/attributes/{attribute_id}/terms/{id}
PUT /woocommerce/wp-json/wc/v3/products/attributes/{attribute_id}/terms/{id}
DELETE /woocommerce/wp-json/wc/v3/products/attributes/{attribute_id}/terms/{id}
```
### Product Categories
#### List Categories
```bash
GET /woocommerce/wp-json/wc/v3/products/categories
```
#### Create Category
```bash
POST /woocommerce/wp-json/wc/v3/products/categories
Content-Type: application/json
{
"name": "Electronics",
"parent": 0,
"description": "Electronic products"
}
```
#### Get/Update/Delete Category
```bash
GET /woocommerce/wp-json/wc/v3/products/categories/{id}
PUT /woocommerce/wp-json/wc/v3/products/categories/{id}
DELETE /woocommerce/wp-json/wc/v3/products/categories/{id}
```
### Product Tags
```bash
GET /woocommerce/wp-json/wc/v3/products/tags
POST /woocommerce/wp-json/wc/v3/products/tags
GET /woocommerce/wp-json/wc/v3/products/tags/{id}
PUT /woocommerce/wp-json/wc/v3/products/tags/{id}
DELETE /woocommerce/wp-json/wc/v3/products/tags/{id}
```
### Product Shipping Classes
```bash
GET /woocommerce/wp-json/wc/v3/products/shipping_classes
POST /woocommerce/wp-json/wc/v3/products/shipping_classes
GET /woocommerce/wp-json/wc/v3/products/shipping_classes/{id}
PUT /woocommerce/wp-json/wc/v3/products/shipping_classes/{id}
DELETE /woocommerce/wp-json/wc/v3/products/shipping_classes/{id}
```
### Product Reviews
#### List Reviews
```bash
GET /woocommerce/wp-json/wc/v3/products/reviews
```
Query parameters:
- `product` - Filter by product ID
- `status` - Filter by status: `approved`, `hold`, `spam`, `trash`
#### Create Review
```bash
POST /woocommerce/wp-json/wc/v3/products/reviews
Content-Type: application/json
{
"product_id": 123,
"review": "Great product!",
"reviewer": "John Doe",
"reviewer_email": "john@example.com",
"rating": 5
}
```
#### Get/Update/Delete Review
```bash
GET /woocommerce/wp-json/wc/v3/products/reviews/{id}
PUT /woocommerce/wp-json/wc/v3/products/reviews/{id}
DELETE /woocommerce/wp-json/wc/v3/products/reviews/{id}
```
---
### Orders
#### List All Orders
```bash
GET /woocommerce/wp-json/wc/v3/orders
```
Query parameters:
- `page` - Current page (default: 1)
- `per_page` - Items per page (default: 10)
- `search` - Search orders
- `after` / `before` - Filter by date (ISO8601)
- `status` - Order status (see below)
- `customer` - Filter by customer ID
- `product` - Filter by product ID
- `orderby` - Sort by: `date`, `id`, `include`, `title`, `slug`
- `order` - Sort order: `asc`, `desc`
**Order Statuses:**
- `pending` - Payment pending
- `processing` - Payment received, awaiting fulfillment
- `on-hold` - Awaiting payment confirmation
- `completed` - Order fulfilled
- `cancelled` - Cancelled by admin or customer
- `refunded` - Fully refunded
- `failed` - Payment failed
**Example:**
```bash
curl -s -X GET "https://gateway.maton.ai/woocommerce/wp-json/wc/v3/orders?status=processing&per_page=50" -H "Authorization: Bearer $MATON_API_KEY"
```
**Response:**
```json
[
{
"id": 456,
"status": "processing",
"currency": "USD",
"total": "129.99",
"customer_id": 12,
"billing": {
"first_name": "John",
"last_name": "Doe",
"email": "john@example.com"
},
"line_items": [
{
"id": 789,
"product_id": 123,
"name": "Premium T-Shirt",
"quantity": 2,
"total": "59.98"
}
]
}
]
```
#### Get an Order
```bash
GET /woocommerce/wp-json/wc/v3/orders/{id}
```
#### Create an Order
```bash
POST /woocommerce/wp-json/wc/v3/orders
Content-Type: application/json
{
"payment_method": "stripe",
"payment_method_title": "Credit Card",
"set_paid": true,
"billing": {
"first_name": "John",
"last_name": "Doe",
"address_1": "123 Main St",
"city": "Anytown",
"state": "CA",
"postcode": "12345",
"country": "US",
"email": "john@example.com",
"phone": "555-1234"
},
"shipping": {
"first_name": "John",
"last_name": "Doe",
"address_1": "123 Main St",
"city": "Anytown",
"state": "CA",
"postcode": "12345",
"country": "US"
},
"line_items": [
{
"product_id": 123,
"quantity": 2
}
]
}
```
#### Update an Order
```bash
PUT /woocommerce/wp-json/wc/v3/orders/{id}
```
**Example - Update order status:**
```bash
curl -s -X PUT "https://gateway.maton.ai/woocommerce/wp-json/wc/v3/orders/456" -H "Content-Type: application/json" -H "Authorization: Bearer $MATON_API_KEY" -d '{"status": "completed"}'
```
#### Delete an Order
```bash
DELETE /woocommerce/wp-json/wc/v3/orders/{id}
```
### Order Notes
#### List Order Notes
```bash
GET /woocommerce/wp-json/wc/v3/orders/{order_id}/notes
```
#### Create Order Note
```bash
POST /woocommerce/wp-json/wc/v3/orders/{order_id}/notes
Content-Type: application/json
{
"note": "Order shipped via FedEx, tracking #12345",
"customer_note": true
}
```
- `customer_note`: Set to `true` to make the note visible to the customer
#### Get/Delete Order Note
```bash
GET /woocommerce/wp-json/wc/v3/orders/{order_id}/notes/{id}
DELETE /woocommerce/wp-json/wc/v3/orders/{order_id}/notes/{id}
```
### Order Refunds
#### List Refunds
```bash
GET /woocommerce/wp-json/wc/v3/orders/{order_id}/refunds
```
#### Create Refund
```bash
POST /woocommerce/wp-json/wc/v3/orders/{order_id}/refunds
Content-Type: application/json
{
"amount": "25.00",
"reason": "Product damaged during shipping",
"api_refund": true
}
```
- `api_refund`: Set to `true` to process refund through payment gateway
#### Get/Delete Refund
```bash
GET /woocommerce/wp-json/wc/v3/orders/{order_id}/refunds/{id}
DELETE /woocommerce/wp-json/wc/v3/orders/{order_id}/refunds/{id}
```
---
### Customers
#### List All Customers
```bash
GET /woocommerce/wp-json/wc/v3/customers
```
Query parameters:
- `page` - Current page (default: 1)
- `per_page` - Items per page (default: 10)
- `search` - Search by name or email
- `email` - Filter by exact email
- `role` - Filter by role: `all`, `administrator`, `customer`, `shop_manager`
- `orderby` - Sort by: `id`, `include`, `name`, `registered_date`
- `order` - Sort order: `asc`, `desc`
**Example:**
```bash
curl -s -X GET "https://gateway.maton.ai/woocommerce/wp-json/wc/v3/customers?per_page=25" -H "Authorization: Bearer $MATON_API_KEY"
```
**Response:**
```json
[
{
"id": 12,
"email": "john@example.com",
"first_name": "John",
"last_name": "Doe",
"username": "johndoe",
"billing": {
"first_name": "John",
"last_name": "Doe",
"address_1": "123 Main St",
"city": "Anytown",
"state": "CA",
"postcode": "12345",
"country": "US",
"email": "john@example.com",
"phone": "555-1234"
},
"shipping": {
"first_name": "John",
"last_name": "Doe",
"address_1": "123 Main St",
"city": "Anytown",
"state": "CA",
"postcode": "12345",
"country": "US"
}
}
]
```
#### Get a Customer
```bash
GET /woocommerce/wp-json/wc/v3/customers/{id}
```
#### Create a Customer
```bash
POST /woocommerce/wp-json/wc/v3/customers
Content-Type: application/json
{
"email": "jane@example.com",
"first_name": "Jane",
"last_name": "Smith",
"username": "janesmith",
"password": "secure_password",
"billing": {
"first_name": "Jane",
"last_name": "Smith",
"address_1": "456 Oak Ave",
"city": "Springfield",
"state": "IL",
"postcode": "62701",
"country": "US",
"email": "jane@example.com",
"phone": "555-5678"
}
}
```
#### Update a Customer
```bash
PUT /woocommerce/wp-json/wc/v3/customers/{id}
```
#### Delete a Customer
```bash
DELETE /woocommerce/wp-json/wc/v3/customers/{id}
```
### Customer Downloads
```bash
GET /woocommerce/wp-json/wc/v3/customers/{customer_id}/downloads
```
Returns downloadable products the customer has access to.
---
### Coupons
#### List All Coupons
```bash
GET /woocommerce/wp-json/wc/v3/coupons
```
Query parameters:
- `page` - Current page (default: 1)
- `per_page` - Items per page (default: 10)
- `search` - Search coupons
- `code` - Filter by coupon code
#### Get a Coupon
```bash
GET /woocommerce/wp-json/wc/v3/coupons/{id}
```
#### Create a Coupon
```bash
POST /woocommerce/wp-json/wc/v3/coupons
Content-Type: application/json
{
"code": "SUMMER2024",
"discount_type": "percent",
"amount": "15",
"description": "Summer promotion - 15% off",
"date_expires": "2024-08-31T23:59:59",
"individual_use": true,
"usage_limit": 100,
"usage_limit_per_user": 1,
"minimum_amount": "50.00",
"maximum_amount": "500.00",
"free_shipping": false,
"exclude_sale_items": true
}
```
**Discount Types:**
- `percent` - Percentage discount
- `fixed_cart` - Fixed amount off entire cart
- `fixed_product` - Fixed amount off per product
**Coupon Properties:**
- `code` - Coupon code (required)
- `amount` - Discount amount
- `discount_type` - Type of discount
- `description` - Coupon description
- `date_expires` - Expiration date (ISO8601)
- `individual_use` - Cannot be combined with other coupons
- `product_ids` - Array of product IDs the coupon applies to
- `excluded_product_ids` - Array of product IDs excluded
- `usage_limit` - Total number of times coupon can be used
- `usage_limit_per_user` - Usage limit per customer
- `limit_usage_to_x_items` - Max items the discount applies to
- `free_shipping` - Enables free shipping
- `product_categories` - Array of category IDs
- `excluded_product_categories` - Array of excluded category IDs
- `exclude_sale_items` - Exclude sale items from discount
- `minimum_amount` - Minimum cart total required
- `maximum_amount` - Maximum cart total allowed
- `email_restrictions` - Array of allowed email addresses
#### Update a Coupon
```bash
PUT /woocommerce/wp-json/wc/v3/coupons/{id}
```
#### Delete a Coupon
```bash
DELETE /woocommerce/wp-json/wc/v3/coupons/{id}
```
---
### Taxes
#### Tax Rates
```bash
GET /woocommerce/wp-json/wc/v3/taxes
POST /woocommerce/wp-json/wc/v3/taxes
GET /woocommerce/wp-json/wc/v3/taxes/{id}
PUT /woocommerce/wp-json/wc/v3/taxes/{id}
DELETE /woocommerce/wp-json/wc/v3/taxes/{id}
POST /woocommerce/wp-json/wc/v3/taxes/batch
```
**Create Tax Rate Example:**
```bash
curl -s -X POST "https://gateway.maton.ai/woocommerce/wp-json/wc/v3/taxes" -H "Content-Type: application/json" -H "Authorization: Bearer $MATON_API_KEY" -d '{"country": "US", "state": "CA", "rate": "7.25", "name": "CA State Tax", "shipping": true}'
```
#### Tax Classes
```bash
GET /woocommerce/wp-json/wc/v3/taxes/classes
POST /woocommerce/wp-json/wc/v3/taxes/classes
DELETE /woocommerce/wp-json/wc/v3/taxes/classes/{slug}
```
---
### Shipping
#### Shipping Zones
```bash
GET /woocommerce/wp-json/wc/v3/shipping/zones
POST /woocommerce/wp-json/wc/v3/shipping/zones
GET /woocommerce/wp-json/wc/v3/shipping/zones/{id}
PUT /woocommerce/wp-json/wc/v3/shipping/zones/{id}
DELETE /woocommerce/wp-json/wc/v3/shipping/zones/{id}
```
**Create Shipping Zone Example:**
```bash
curl -s -X POST "https://gateway.maton.ai/woocommerce/wp-json/wc/v3/shipping/zones" -H "Content-Type: application/json" -H "Authorization: Bearer $MATON_API_KEY" -d '{"name": "US West Coast", "order": 1}'
```
#### Shipping Zone Locations
```bash
GET /woocommerce/wp-json/wc/v3/shipping/zones/{zone_id}/locations
PUT /woocommerce/wp-json/wc/v3/shipping/zones/{zone_id}/locations
```
**Update Zone Locations Example:**
```bash
curl -s -X PUT "https://gateway.maton.ai/woocommerce/wp-json/wc/v3/shipping/zones/1/locations" -H "Content-Type: application/json" -H "Authorization: Bearer $MATON_API_KEY" -d '[{"code": "US:CA", "type": "state"}, {"code": "US:OR", "type": "state"}, {"code": "US:WA", "type": "state"}]'
```
#### Shipping Zone Methods
```bash
GET /woocommerce/wp-json/wc/v3/shipping/zones/{zone_id}/methods
POST /woocommerce/wp-json/wc/v3/shipping/zones/{zone_id}/methods
GET /woocommerce/wp-json/wc/v3/shipping/zones/{zone_id}/methods/{id}
PUT /woocommerce/wp-json/wc/v3/shipping/zones/{zone_id}/methods/{id}
DELETE /woocommerce/wp-json/wc/v3/shipping/zones/{zone_id}/methods/{id}
```
#### Shipping Methods (Global)
```bash
GET /woocommerce/wp-json/wc/v3/shipping_methods
GET /woocommerce/wp-json/wc/v3/shipping_methods/{id}
```
---
### Payment Gateways
```bash
GET /woocommerce/wp-json/wc/v3/payment_gateways
GET /woocommerce/wp-json/wc/v3/payment_gateways/{id}
PUT /woocommerce/wp-json/wc/v3/payment_gateways/{id}
```
**Example - Enable a Payment Gateway:**
```bash
curl -s -X PUT "https://gateway.maton.ai/woocommerce/wp-json/wc/v3/payment_gateways/stripe" -H "Content-Type: application/json" -H "Authorization: Bearer $MATON_API_KEY" -d '{"enabled": true}'
```
---
### Settings
#### List Settings Groups
```bash
GET /woocommerce/wp-json/wc/v3/settings
```
#### List Settings in a Group
```bash
GET /woocommerce/wp-json/wc/v3/settings/{group}
```
Common groups: `general`, `products`, `tax`, `shipping`, `checkout`, `account`, `email`
#### Get/Update a Setting
```bash
GET /woocommerce/wp-json/wc/v3/settings/{group}/{id}
PUT /woocommerce/wp-json/wc/v3/settings/{group}/{id}
```
**Example - Update Store Address:**
```bash
curl -s -X PUT "https://gateway.maton.ai/woocommerce/wp-json/wc/v3/settings/general/woocommerce_store_address" -H "Content-Type: application/json" -H "Authorization: Bearer $MATON_API_KEY" -d '{"value": "123 Commerce St"}'
```
#### Batch Update Settings
```bash
POST /woocommerce/wp-json/wc/v3/settings/{group}/batch
```
---
### Webhooks
#### List All Webhooks
```bash
GET /woocommerce/wp-json/wc/v3/webhooks
```
#### Create a Webhook
```bash
POST /woocommerce/wp-json/wc/v3/webhooks
Content-Type: application/json
{
"name": "Order Created",
"topic": "order.created",
"delivery_url": "https://example.com/webhooks/woocommerce",
"status": "active"
}
```
**Webhook Topics:**
- `order.created`, `order.updated`, `order.deleted`, `order.restored`
- `product.created`, `product.updated`, `product.deleted`, `product.restored`
- `customer.created`, `customer.updated`, `customer.deleted`
- `coupon.created`, `coupon.updated`, `coupon.deleted`, `coupon.restored`
#### Get/Update/Delete Webhook
```bash
GET /woocommerce/wp-json/wc/v3/webhooks/{id}
PUT /woocommerce/wp-json/wc/v3/webhooks/{id}
DELETE /woocommerce/wp-json/wc/v3/webhooks/{id}
```
---
### Reports
#### List Available Reports
```bash
GET /woocommerce/wp-json/wc/v3/reports
```
#### Sales Report
```bash
GET /woocommerce/wp-json/wc/v3/reports/sales
```
Query parameters:
- `period` - Report period: `week`, `month`, `last_month`, `year`
- `date_min` / `date_max` - Custom date range
#### Top Sellers Report
```bash
GET /woocommerce/wp-json/wc/v3/reports/top_sellers
```
#### Coupons Totals
```bash
GET /woocommerce/wp-json/wc/v3/reports/coupons/totals
```
#### Customers Totals
```bash
GET /woocommerce/wp-json/wc/v3/reports/customers/totals
```
#### Orders Totals
```bash
GET /woocommerce/wp-json/wc/v3/reports/orders/totals
```
#### Products Totals
```bash
GET /woocommerce/wp-json/wc/v3/reports/products/totals
```
#### Reviews Totals
```bash
GET /woocommerce/wp-json/wc/v3/reports/reviews/totals
```
---
### Data
#### List All Data Endpoints
```bash
GET /woocommerce/wp-json/wc/v3/data
```
#### Continents
```bash
GET /woocommerce/wp-json/wc/v3/data/continents
GET /woocommerce/wp-json/wc/v3/data/continents/{code}
```
#### Countries
```bash
GET /woocommerce/wp-json/wc/v3/data/countries
GET /woocommerce/wp-json/wc/v3/data/countries/{code}
```
#### Currencies
```bash
GET /woocommerce/wp-json/wc/v3/data/currencies
GET /woocommerce/wp-json/wc/v3/data/currencies/{code}
GET /woocommerce/wp-json/wc/v3/data/currencies/current
```
---
### System Status
```bash
GET /woocommerce/wp-json/wc/v3/system_status
GET /woocommerce/wp-json/wc/v3/system_status/tools
POST /woocommerce/wp-json/wc/v3/system_status/tools/{id}
```
---
## Batch Operations
Most resources support batch operations for creating, updating, and deleting multiple items:
```bash
POST /woocommerce/wp-json/wc/v3/{resource}/batch
Content-Type: application/json
{
"create": [
{"name": "New Product 1", "regular_price": "19.99"},
{"name": "New Product 2", "regular_price": "29.99"}
],
"update": [
{"id": 123, "regular_price": "24.99"}
],
"delete": [456, 789]
}
```
**Response:**
```json
{
"create": [...],
"update": [...],
"delete": [...]
}
```
## Pagination
WooCommerce uses page-based pagination with response headers:
**Query Parameters:**
- `page` - Page number (default: 1)
- `per_page` - Items per page (default: 10, max: 100)
- `offset` - Offset to start from
**Response Headers:**
- `X-WP-Total` - Total number of items
- `X-WP-TotalPages` - Total number of pages
- `Link` - Contains `next`, `prev`, `first`, `last` pagination links
**Example:**
```bash
curl -s -I -X GET "https://gateway.maton.ai/woocommerce/wp-json/wc/v3/products?page=2&per_page=25" -H "Authorization: Bearer $MATON_API_KEY"
```
## Code Examples
### JavaScript
```javascript
const response = await fetch(
'https://gateway.maton.ai/woocommerce/wp-json/wc/v3/orders?status=processing',
{
headers: {
'Authorization': `Bearer ${process.env.MATON_API_KEY}`
}
}
);
const orders = await response.json();
```
### Python
```python
import os
import requests
response = requests.get(
'https://gateway.maton.ai/woocommerce/wp-json/wc/v3/products',
headers={'Authorization': f'Bearer {os.environ["MATON_API_KEY"]}'},
params={'per_page': 50, 'status': 'publish'}
)
products = response.json()
```
### Creating an Order with Line Items
```python
import os
import requests
order_data = {
"payment_method": "stripe",
"set_paid": True,
"billing": {
"first_name": "John",
"last_name": "Doe",
"email": "john@example.com",
"address_1": "123 Main St",
"city": "Anytown",
"state": "CA",
"postcode": "12345",
"country": "US"
},
"line_items": [
{"product_id": 123, "quantity": 2},
{"product_id": 456, "quantity": 1}
]
}
response = requests.post(
'https://gateway.maton.ai/woocommerce/wp-json/wc/v3/orders',
headers={
'Authorization': f'Bearer {os.environ["MATON_API_KEY"]}',
'Content-Type': 'application/json'
},
json=order_data
)
order = response.json()
```
## Notes
- All monetary amounts are returned as strings with two decimal places
- Dates are in ISO8601 format: `YYYY-MM-DDTHH:MM:SS`
- Resource IDs are integers
- The API requires "pretty permalinks" enabled in WordPress
- Use `context=edit` parameter for additional writable fields
- IMPORTANT: When using curl commands, use `curl -g` when URLs contain brackets (`fields[]`, `sort[]`, `records[]`) to disable glob parsing
- IMPORTANT: When piping curl output to `jq` or other commands, environment variables like `$MATON_API_KEY` may not expand correctly in some shell environments. You may get "Invalid API key" errors when piping.
## Error Handling
| Status | Meaning |
|--------|---------|
| 400 | Bad request or invalid data |
| 401 | Invalid or missing authentication |
| 403 | Forbidden - insufficient permissions |
| 404 | Resource not found |
| 500 | Internal server error |
**Error Response Format:**
```json
{
"code": "woocommerce_rest_invalid_id",
"message": "Invalid ID.",
"data": {
"status": 404
}
}
```
### Troubleshooting: API Key Issues
1. Check that the `MATON_API_KEY` environment variable is set:
```bash
echo $MATON_API_KEY
```
2. Verify the API key is valid by listing connections:
```bash
python <<'EOF'
import urllib.request, os, json
req = urllib.request.Request('https://ctrl.maton.ai/connections')
req.add_header('Authorization', f'Bearer {os.environ["MATON_API_KEY"]}')
print(json.dumps(json.load(urllib.request.urlopen(req)), indent=2))
EOF
```
### Troubleshooting: Invalid App Name
1. Ensure your URL path starts with `woocommerce`. For example:
- Correct: `https://gateway.maton.ai/woocommerce/wp-json/wc/v3/products`
- Incorrect: `https://gateway.maton.ai/wp-json/wc/v3/products`
## Resources
### General
- [WooCommerce REST API Documentation](https://woocommerce.github.io/woocommerce-rest-api-docs/)
- [API Authentication Guide](https://woocommerce.github.io/woocommerce-rest-api-docs/#authentication)
- [WooCommerce Developer Resources](https://developer.woocommerce.com/)
### Products
- [Products](https://woocommerce.github.io/woocommerce-rest-api-docs/#products)
- [Product Variations](https://woocommerce.github.io/woocommerce-rest-api-docs/#product-variations)
- [Product Attributes](https://woocommerce.github.io/woocommerce-rest-api-docs/#product-attributes)
- [Product Attribute Terms](https://woocommerce.github.io/woocommerce-rest-api-docs/#product-attribute-terms)
- [Product Categories](https://woocommerce.github.io/woocommerce-rest-api-docs/#product-categories)
- [Product Tags](https://woocommerce.github.io/woocommerce-rest-api-docs/#product-tags)
- [Product Shipping Classes](https://woocommerce.github.io/woocommerce-rest-api-docs/#product-shipping-classes)
- [Product Reviews](https://woocommerce.github.io/woocommerce-rest-api-docs/#product-reviews)
### Orders
- [Orders](https://woocommerce.github.io/woocommerce-rest-api-docs/#orders)
- [Order Notes](https://woocommerce.github.io/woocommerce-rest-api-docs/#order-notes)
- [Refunds](https://woocommerce.github.io/woocommerce-rest-api-docs/#refunds)
### Customers
- [Customers](https://woocommerce.github.io/woocommerce-rest-api-docs/#customers)
### Coupons
- [Coupons](https://woocommerce.github.io/woocommerce-rest-api-docs/#coupons)
### Taxes
- [Tax Rates](https://woocommerce.github.io/woocommerce-rest-api-docs/#tax-rates)
- [Tax Classes](https://woocommerce.github.io/woocommerce-rest-api-docs/#tax-classes)
### Shipping
- [Shipping Zones](https://woocommerce.github.io/woocommerce-rest-api-docs/#shipping-zones)
- [Shipping Zone Locations](https://woocommerce.github.io/woocommerce-rest-api-docs/#shipping-zone-locations)
- [Shipping Zone Methods](https://woocommerce.github.io/woocommerce-rest-api-docs/#shipping-zone-methods)
- [Shipping Methods](https://woocommerce.github.io/woocommerce-rest-api-docs/#shipping-methods)
### Payments & Settings
- [Payment Gateways](https://woocommerce.github.io/woocommerce-rest-api-docs/#payment-gateways)
- [Settings](https://woocommerce.github.io/woocommerce-rest-api-docs/#settings)
- [Setting Options](https://woocommerce.github.io/woocommerce-rest-api-docs/#setting-options)
### Webhooks
- [Webhooks](https://woocommerce.github.io/woocommerce-rest-api-docs/#webhooks)
### Reports
- [Reports](https://woocommerce.github.io/woocommerce-rest-api-docs/#reports)
- [Sales Reports](https://woocommerce.github.io/woocommerce-rest-api-docs/#sales-reports)
- [Top Sellers Report](https://woocommerce.github.io/woocommerce-rest-api-docs/#top-sellers-report)
- [Coupons Totals](https://woocommerce.github.io/woocommerce-rest-api-docs/#coupons-totals)
- [Customers Totals](https://woocommerce.github.io/woocommerce-rest-api-docs/#customers-totals)
- [Orders Totals](https://woocommerce.github.io/woocommerce-rest-api-docs/#orders-totals)
- [Products Totals](https://woocommerce.github.io/woocommerce-rest-api-docs/#products-totals)
- [Reviews Totals](https://woocommerce.github.io/woocommerce-rest-api-docs/#reviews-totals)
### Data
- [Data](https://woocommerce.github.io/woocommerce-rest-api-docs/#data)
- [Continents](https://woocommerce.github.io/woocommerce-rest-api-docs/#continents)
- [Countries](https://woocommerce.github.io/woocommerce-rest-api-docs/#countries)
- [Currencies](https://woocommerce.github.io/woocommerce-rest-api-docs/#currencies)
### System
- [System Status](https://woocommerce.github.io/woocommerce-rest-api-docs/#system-status)
- [System Status Tools](https://woocommerce.github.io/woocommerce-rest-api-docs/#system-status-tools)
- [Maton Community](https://discord.com/invite/dBfFAcefs2)
- [Maton Support](mailto:support@maton.ai)
标签
skill
ai
