WooCommerce REST API v3: Full CRUD for E-com Stores
Integrate WooCommerce stores via WP REST API v3 for JSON-based CRUD on products, orders, customers, shipping, reports, and more—requires WC 3.5+, pretty permalinks, and OAuth keys.
Comprehensive Endpoint Coverage for Store Management
WooCommerce REST API v3, integrated since WC 2.6 with WordPress REST API, exposes nearly every store entity for create, read, update, delete (CRUD) operations via standard HTTP methods and JSON payloads. This enables external apps to manage e-commerce data without direct WP admin access. Key entities include:
- Products and Catalog: Full CRUD on products, variations, attributes, terms, categories, tags, shipping classes, reviews, and custom fields. For example, duplicate products via POST /products/
with ?duplicate=true, or batch update multiple via POST /products/batch. - Customers and Orders: CRUD for customers (including downloads), orders, notes, refunds. Order actions like emailing details (?send=1) or notifications. Batch operations scale for bulk edits.
- Payments and Shipping: Manage payment gateways, tax rates/classes, shipping zones, locations, methods. Retrieve gateway settings or add methods to zones.
- Reports and Analytics: Fetch totals for sales, top sellers, coupons, customers, orders, products, reviews. List all reports at /reports.
- System and Webhooks: Access settings, webhooks (with topics like 'order.created'), system status/tools (e.g., run database updates), and static data (countries, currencies).
This structure prioritizes extensibility—every major WooCommerce object has dedicated endpoints with consistent properties (e.g., id, name, date_created in ISO8601). Tradeoff: Requires WC 3.5+ and WP 4.4+; legacy v1-v2 or separate legacy APIs for older versions. Pretty permalinks are mandatory; default ones fail custom endpoints.
Authentication: Keys Tied to WP User Permissions
REST API uses OAuth 1.0a consumer keys/secrets generated per WP user via WooCommerce > Settings > Advanced > REST API (pre-3.4: API > Keys/Apps). Permissions: Read, Write, or Read/Write, inheriting the user's roles/capabilities. Keys revoke if user deletes.
Alternative: Auto-generate via /wc-auth/v1/authorize?app_name=...&scope=read_write&user_id=...&return_url=...&callback_url=... (HTTPS required for callback). Redirects user to grant access, returns keys via POST—ideal for app integrations without manual key entry.
HTTP/HTTPS both supported, but HTTPS recommended. Plugins extend auth options.
"Pre-generated keys can be used to authenticate use of the REST API endpoints. New keys can be generated either through the WordPress admin interface or they can be auto-generated through an endpoint." (Explains dual generation paths for flexibility in app vs. direct use.)
Request Handling, Pagination, and Error Responses
Requests use JSON bodies; responses include ISO8601 dates, integer IDs, string decimals (e.g., prices as "10.00"), null/empty for blanks. Pagination defaults to 10 items/page (admin-adjustable via posts_per_page); override with ?per_page=15&page=2&offset=5. Headers provide X-WP-Total, X-WP-TotalPages; Link header offers rel=next/last/first/prev URLs.
Errors: 400 (bad request), 401 (auth), 404 (missing), 500 (server). Responses detail code/message/data.status, e.g., {"code":"rest_no_route","message":"No route was found...","data":{"status":404}} or Woo-specific like "woocommerce_rest_term_invalid".
JSONP via ?_jsonp=callback for GETs (application/javascript type).
"Requests that return multiple items will be paginated to 10 items by default... It's recommended that you follow these values instead of building your own URLs where possible." (Link header guidance prevents brittle pagination logic.)
Official Libraries and Testing Tools
Plug-and-play clients handle auth/versioning:
- JavaScript: npm i @woocommerce/woocommerce-rest-api; new WooCommerceRestApi({url, consumerKey, consumerSecret, version: 'wc/v3'}).
- PHP: composer require automattic/woocommerce; new Client(url, key, secret, 'wp_api'=>true, 'version'=>'wc/v3').
- Python: pip install woocommerce; API(url, key, secret, wp_api=True, version='wc/v3').
- Ruby: gem install woocommerce_api; WooCommerce::API.new(url, key, secret, {wp_api: true, version: 'wc/v3'}).
Third-party: Java, .NET, Android libs.
Test with Insomnia/Postman (REST clients), RequestBin/Hookbin (webhooks). ModSecurity may cause 501s—check GitHub issue #9838.
"The default response format is JSON. Requests with a message-body use plain JSON to set or update resource attributes. Successful requests will return a 200 OK HTTP status." (Sets expectation for stateless, idempotent HTTP usage.)
Key Takeaways
- Enable pretty permalinks and use WC 3.5+/WP 4.4+ for v3 endpoints at /wp-json/wc/v3/*.
- Generate read/write keys per user in admin or auto via /wc-auth/v1/authorize for app flows.
- Leverage batch endpoints (e.g., /products/batch) for efficient bulk ops; paginate with per_page/page/offset and parse Link headers.
- Use official libs to abstract auth/pagination; test webhooks with Hookbin.
- HTTPS everywhere for security; handle decimals as strings, dates as ISO8601.
- Group ops by entity: products/catalog first for inventory, then orders/customers for fulfillment.
- Monitor errors via code/data.status; extend with WP REST plugins.
"To use the latest version of the REST API you must be using: WooCommerce 3.5+. WordPress 4.4+. Pretty permalinks... Default permalinks will not work." (Critical setup gotcha for new integrators.)