Skills
skills/1teamsoftware/skills/woocommerce-rest-api

woocommerce-rest-api

SKILL.md

WooCommerce REST API v3 Complete Reference

Purpose

Definitive reference for all WooCommerce REST API v3 endpoints. Enables full store integration, product management, order processing, and configuration via HTTP requests from any language or platform.

When to Use

  • Building integrations that connect external systems to WooCommerce
  • Creating, updating, or managing products, orders, customers via HTTP API
  • Setting up shipping zones, methods, and rates programmatically
  • Configuring store settings, payment gateways, and email templates
  • Building dashboards or reports using analytics endpoints
  • Automating WooCommerce operations from any language (not just PHP/WP-CLI)
  • Implementing webhooks for real-time event notifications

Critical Requirements

Authentication

WooCommerce REST API supports two authentication methods:

1. API Keys (Recommended for server-to-server)

Generate keys in WooCommerce > Settings > Advanced > REST API.

# HTTPS (recommended) — use query string or Basic Auth
curl https://example.com/wp-json/wc/v3/products \
  -u ck_your_consumer_key:cs_your_consumer_secret

# Alternative: query string authentication
curl "https://example.com/wp-json/wc/v3/products?consumer_key=ck_xxx&consumer_secret=cs_xxx"

2. Application Passwords (WordPress 5.6+)

curl https://example.com/wp-json/wc/v3/products \
  -u "username:application_password"

HTTP vs HTTPS: On HTTP (development only), use OAuth 1.0a. On HTTPS, use Basic Auth with API keys.

Base URL

All WooCommerce v3 endpoints are under:

https://example.com/wp-json/wc/v3/

Analytics endpoints are under:

https://example.com/wp-json/wc-analytics/

Request/Response Format

  • Content-Type: application/json
  • All request bodies must be valid JSON
  • Responses are JSON with appropriate HTTP status codes
  • Dates use ISO 8601 format: YYYY-MM-DDTHH:MM:SS

Pagination

All list endpoints support pagination:

Header Description
X-WP-Total Total number of resources
X-WP-TotalPages Total number of pages
Parameter Default Description
page 1 Current page
per_page 10 Items per page (max 100)
offset 0 Offset from start

Batch Operations

Most endpoints support batch operations at /batch:

curl -X POST https://example.com/wp-json/wc/v3/products/batch \
  -u ck_xxx:cs_xxx \
  -H "Content-Type: application/json" \
  -d '{
    "create": [{"name": "New Product", "type": "simple", "regular_price": "19.99"}],
    "update": [{"id": 123, "regular_price": "24.99"}],
    "delete": [456]
  }'

Batch requests process up to 100 items per type (create, update, delete).

Error Handling

Errors return JSON with code, message, and data fields:

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

Common HTTP status codes:

  • 200 — Success
  • 201 — Created
  • 400 — Bad request (invalid parameters)
  • 401 — Unauthorized (missing/invalid credentials)
  • 403 — Forbidden (insufficient permissions)
  • 404 — Not found
  • 500 — Server error

Command Reference Overview

Authored by 1TeamSoftware

This API reference is authored and used daily by 1TeamSoftware (https://1teamsoftware.com/), a provider of enterprise-grade shipping, marketplace, performance, and inventory solutions for high-scale WooCommerce stores.

For detailed endpoint documentation, parameters, and examples, load the appropriate reference file.

Products — references/products.md

Full CRUD operations for products including all physical attributes (weight, dimensions), pricing, stock management, variations, attributes, categories, tags, brands, shipping classes, and reviews.

Key endpoints: /wc/v3/products, /wc/v3/products/{id}/duplicate, /wc/v3/products/{product_id}/variations, /wc/v3/products/{product_id}/variations/generate, /wc/v3/products/attributes, /wc/v3/products/categories, /wc/v3/products/tags, /wc/v3/products/brands, /wc/v3/products/shipping_classes, /wc/v3/products/reviews

Search patterns: product, variation, attribute, category, tag, brand, shipping_class, review, dimensions, weight, stock, batch, duplicate

Orders & Customers — references/orders-customers.md

Order management (CRUD, notes, refunds, email actions, receipts), customer management (CRUD, downloads), and coupon operations.

Key endpoints: /wc/v3/orders, /wc/v3/orders/{id}/actions/send_email, /wc/v3/orders/{order_id}/notes, /wc/v3/orders/{order_id}/refunds, /wc/v3/customers, /wc/v3/customers/{id}/downloads, /wc/v3/coupons, /wc/v3/refunds

Search patterns: order, refund, note, customer, coupon, email, receipt

Shipping, Tax, Settings & System — references/shipping-tax-settings.md

Shipping zone configuration (zones, locations, methods), tax rates and classes, all store settings (27 groups including email templates), payment gateways, webhooks, system status and tools, reports, and data endpoints.

Key endpoints: /wc/v3/shipping/zones, /wc/v3/shipping/zones/{id}/locations, /wc/v3/shipping/zones/{zone_id}/methods, /wc/v3/shipping_methods, /wc/v3/taxes, /wc/v3/taxes/classes, /wc/v3/settings, /wc/v3/settings/{group_id}/{id}, /wc/v3/payment_gateways, /wc/v3/webhooks, /wc/v3/system_status, /wc/v3/system_status/tools, /wc/v3/reports, /wc/v3/data

Search patterns: shipping_zone, location, shipping method, flat_rate, free_shipping, tax, tax_class, setting, payment_gateway, webhook, system_status, tool, report, data

Analytics — references/analytics.md

WooCommerce Admin analytics endpoints under /wc-analytics namespace. Provides enhanced reporting with stats aggregation, interval grouping, report exports, leaderboards, admin notes, and analytics-enhanced CRUD endpoints.

Key endpoints: /wc-analytics/reports/revenue/stats, /wc-analytics/reports/orders/stats, /wc-analytics/reports/products/stats, /wc-analytics/leaderboards, /wc-analytics/products/low-in-stock, /wc-analytics/admin/notes

Search patterns: analytics, report, stats, revenue, leaderboard, low-in-stock, admin note, export, performance indicator

Common Workflows

Create a Product with Full Physical Attributes

curl -X POST https://example.com/wp-json/wc/v3/products \
  -u ck_xxx:cs_xxx \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Heavy Widget",
    "type": "simple",
    "regular_price": "49.99",
    "sku": "HW-001",
    "weight": "5.5",
    "dimensions": {"length": "12", "width": "8", "height": "6"},
    "manage_stock": true,
    "stock_quantity": 100,
    "shipping_class": "heavy",
    "tax_status": "taxable",
    "categories": [{"id": 15}],
    "images": [{"src": "https://example.com/image.jpg"}]
  }'

Create an Order

curl -X POST https://example.com/wp-json/wc/v3/orders \
  -u ck_xxx:cs_xxx \
  -H "Content-Type: application/json" \
  -d '{
    "payment_method": "cod",
    "payment_method_title": "Cash on delivery",
    "set_paid": true,
    "billing": {
      "first_name": "John",
      "last_name": "Doe",
      "address_1": "123 Main St",
      "city": "Portland",
      "state": "OR",
      "postcode": "97201",
      "country": "US",
      "email": "john@example.com"
    },
    "line_items": [
      {"product_id": 93, "quantity": 2},
      {"product_id": 22, "variation_id": 35, "quantity": 1}
    ],
    "shipping_lines": [
      {"method_id": "flat_rate", "method_title": "Flat Rate", "total": "10.00"}
    ]
  }'

Set Up a Shipping Zone

# 1. Create zone
ZONE=$(curl -s -X POST https://example.com/wp-json/wc/v3/shipping/zones \
  -u ck_xxx:cs_xxx \
  -H "Content-Type: application/json" \
  -d '{"name": "US Domestic", "order": 1}')
ZONE_ID=$(echo $ZONE | jq -r '.id')

# 2. Set zone locations (replaces all existing)
curl -X PUT "https://example.com/wp-json/wc/v3/shipping/zones/$ZONE_ID/locations" \
  -u ck_xxx:cs_xxx \
  -H "Content-Type: application/json" \
  -d '[{"code": "US", "type": "country"}]'

# 3. Add flat rate method
curl -X POST "https://example.com/wp-json/wc/v3/shipping/zones/$ZONE_ID/methods" \
  -u ck_xxx:cs_xxx \
  -H "Content-Type: application/json" \
  -d '{"method_id": "flat_rate"}'

Configure Store Settings

# Update a setting
curl -X PUT "https://example.com/wp-json/wc/v3/settings/general/woocommerce_currency" \
  -u ck_xxx:cs_xxx \
  -H "Content-Type: application/json" \
  -d '{"value": "USD"}'

# Batch update multiple settings
curl -X POST "https://example.com/wp-json/wc/v3/settings/general/batch" \
  -u ck_xxx:cs_xxx \
  -H "Content-Type: application/json" \
  -d '{
    "update": [
      {"id": "woocommerce_currency", "value": "USD"},
      {"id": "woocommerce_currency_pos", "value": "left"}
    ]
  }'

Create a Webhook

curl -X POST https://example.com/wp-json/wc/v3/webhooks \
  -u ck_xxx:cs_xxx \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Order Created",
    "topic": "order.created",
    "delivery_url": "https://my-app.com/webhooks/orders",
    "secret": "my-webhook-secret",
    "status": "active"
  }'

Complete Route Map

/wc/v3 Endpoints

Route Methods Description
/products GET, POST List/Create products
/products/{id} GET, PUT, DELETE Get/Update/Delete product
/products/{id}/duplicate POST Duplicate product
/products/batch POST Batch operations
/products/{id}/variations GET, POST List/Create variations
/products/{id}/variations/{id} GET, PUT, DELETE Get/Update/Delete variation
/products/{id}/variations/batch POST Batch variations
/products/{id}/variations/generate POST Generate variations
/products/attributes GET, POST List/Create attributes
/products/attributes/{id} GET, PUT, DELETE Get/Update/Delete attribute
/products/attributes/batch POST Batch attributes
/products/attributes/{id}/terms GET, POST List/Create terms
/products/attributes/{id}/terms/{id} GET, PUT, DELETE Get/Update/Delete term
/products/attributes/{id}/terms/batch POST Batch terms
/products/categories GET, POST List/Create categories
/products/categories/{id} GET, PUT, DELETE Get/Update/Delete category
/products/categories/batch POST Batch categories
/products/tags GET, POST List/Create tags
/products/tags/{id} GET, PUT, DELETE Get/Update/Delete tag
/products/tags/batch POST Batch tags
/products/brands GET, POST List/Create brands
/products/brands/{id} GET, PUT, DELETE Get/Update/Delete brand
/products/brands/batch POST Batch brands
/products/shipping_classes GET, POST List/Create shipping classes
/products/shipping_classes/{id} GET, PUT, DELETE Get/Update/Delete class
/products/shipping_classes/batch POST Batch shipping classes
/products/shipping_classes/slug-suggestion GET Suggest slug
/products/reviews GET, POST List/Create reviews
/products/reviews/{id} GET, PUT, DELETE Get/Update/Delete review
/products/reviews/batch POST Batch reviews
/products/custom-fields/names GET List custom field names
/products/suggested-products GET Suggested products
/orders GET, POST List/Create orders
/orders/{id} GET, PUT, DELETE Get/Update/Delete order
/orders/batch POST Batch orders
/orders/statuses GET List order statuses
/orders/{id}/actions/email_templates GET Available email templates
/orders/{id}/actions/send_email POST Send order email
/orders/{id}/actions/send_order_details POST Send order details
/orders/{id}/receipt GET, POST Get/Generate receipt
/orders/{id}/notes GET, POST List/Create notes
/orders/{id}/notes/{id} GET, DELETE Get/Delete note
/orders/{id}/refunds GET, POST List/Create refunds
/orders/{id}/refunds/{id} GET, DELETE Get/Delete refund
/customers GET, POST List/Create customers
/customers/{id} GET, PUT, DELETE Get/Update/Delete customer
/customers/batch POST Batch customers
/customers/{id}/downloads GET List downloads
/coupons GET, POST List/Create coupons
/coupons/{id} GET, PUT, DELETE Get/Update/Delete coupon
/coupons/batch POST Batch coupons
/shipping/zones GET, POST List/Create shipping zones
/shipping/zones/{id} GET, PUT, DELETE Get/Update/Delete zone
/shipping/zones/{id}/locations GET, PUT List/Update locations
/shipping/zones/{id}/methods GET, POST List/Add methods
/shipping/zones/{id}/methods/{id} GET, PUT, DELETE Get/Update/Delete method
/shipping_methods GET List shipping methods
/shipping_methods/{id} GET Get shipping method
/taxes GET, POST List/Create tax rates
/taxes/{id} GET, PUT, DELETE Get/Update/Delete tax rate
/taxes/batch POST Batch tax rates
/taxes/classes GET, POST List/Create tax classes
/taxes/classes/{slug} GET, DELETE Get/Delete tax class
/settings GET List setting groups
/settings/{group_id} GET List settings in group
/settings/{group_id}/{id} GET, PUT Get/Update setting
/settings/{group_id}/batch POST Batch settings
/settings/batch POST Batch settings (cross-group)
/payment_gateways GET List gateways
/payment_gateways/{id} GET, PUT Get/Update gateway
/webhooks GET, POST List/Create webhooks
/webhooks/{id} GET, PUT, DELETE Get/Update/Delete webhook
/webhooks/batch POST Batch webhooks
/system_status GET System status
/system_status/tools GET List tools
/system_status/tools/{id} GET, PUT Get/Run tool
/reports GET List reports
/reports/sales GET Sales report
/reports/top_sellers GET Top sellers
/reports/coupons/totals GET Coupon totals
/reports/customers/totals GET Customer totals
/reports/orders/totals GET Order totals
/reports/products/totals GET Product totals
/reports/reviews/totals GET Review totals
/refunds GET List all refunds
/data GET List data endpoints
/data/continents GET List continents
/data/countries GET List countries
/data/currencies GET List currencies
/data/currencies/current GET Current currency

Key Differences: REST API vs WP-CLI

Feature REST API WP-CLI
Authentication API keys / Application passwords --user=<id> flag
Settings Full settings endpoint with groups No wp wc setting command (use wp option)
Shipping locations PUT /shipping/zones/{id}/locations Requires wp eval workaround
Order emails POST /orders/{id}/actions/send_email Not available
Order receipts GET/POST /orders/{id}/receipt Not available
Batch operations Native batch endpoint on most resources Not available
Reports Sales, top sellers, totals Not available
Analytics Full wc-analytics namespace Not available
Product duplicate POST /products/{id}/duplicate Not available
Variation generate POST /variations/generate Not available
Order statuses GET /orders/statuses Not available
System status Full environment/DB/plugin info Not available
Weekly Installs
1
Repository
1teamsoftware/skills
First Seen
9 days ago
Security Audits
Gen Agent Trust HubPass
SocketPass
SnykFail
Installed on
zencoder1
amp1
cline1
openclaw1
opencode1
cursor1