WooCommerce: Скилл интеграции REST API

--- name: woocommerce description: "WooCommerce REST API integration with managed OAuth. Access products, orders, customers, coupons, shipping, taxes, reports, and webhooks. Use this skill when users want to manage e-commerce operations, process orders, or integrate with WooCommerce stores. For other third party apps, use the api-gateway skill (https://clawhub.ai/byungkyu/api-gateway)." --- # 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)