WooCommerce REST API Development
Before writing code
Fetch live docs:
- Fetch
https://woocommerce.github.io/woocommerce-rest-api-docs/ for API reference
- Fetch
https://developer.wordpress.org/rest-api/ for WordPress REST API handbook
- Web-search
site:developer.woocommerce.com rest api extending for extension patterns
REST API Architecture
Foundation
WooCommerce REST API v3 extends the WordPress REST API:
- Base:
/wp-json/wc/v3/
- Built on
WP_REST_Controller pattern
- Supports JSON request/response
- Versioned — v3 is current; v1/v2 are legacy
Built-In Endpoints
| Resource |
Endpoint |
Methods |
| Products |
/wc/v3/products |
GET, POST, PUT, DELETE |
| Product Variations |
/wc/v3/products/{id}/variations |
GET, POST, PUT, DELETE |
| Orders |
/wc/v3/orders |
GET, POST, PUT, DELETE |
| Customers |
/wc/v3/customers |
GET, POST, PUT, DELETE |
| Coupons |
/wc/v3/coupons |
GET, POST, PUT, DELETE |
| Reports |
/wc/v3/reports |
GET |
| Settings |
/wc/v3/settings |
GET, PUT |
| Shipping Zones |
/wc/v3/shipping/zones |
GET, POST, PUT, DELETE |
| Tax Rates |
/wc/v3/taxes |
GET, POST, PUT, DELETE |
| Webhooks |
/wc/v3/webhooks |
GET, POST, PUT, DELETE |
| System Status |
/wc/v3/system_status |
GET |
Authentication
API Keys
WooCommerce generates consumer key/secret pairs:
- Over HTTPS: Pass as query params
consumer_key & consumer_secret, or HTTP Basic Auth
- Over HTTP: OAuth 1.0a signature required
- Keys have permissions:
read, write, read_write
- Generate at WooCommerce > Settings > Advanced > REST API
Application Passwords (WordPress 5.6+)
WordPress-native auth — username + application password via HTTP Basic Auth. Works for all WP REST API endpoints including WooCommerce.
Cookie/Nonce Authentication
For internal (same-site) JavaScript:
- Use
wp_create_nonce( 'wp_rest' ) — set as X-WP-Nonce header
- Automatically handled by
wp.apiFetch in WordPress scripts
Custom Endpoints
Registering Routes
Use rest_api_init action to register routes:
register_rest_route( 'my-extension/v1', '/items', $args )
- Define
methods, callback, permission_callback, args (with validate_callback and sanitize_callback)
Controller Pattern
Extend WP_REST_Controller for structured endpoints:
register_routes() — define route patterns
get_items() — handle collection GET
get_item() — handle single GET
create_item() — handle POST
update_item() — handle PUT/PATCH
delete_item() — handle DELETE
get_item_schema() — JSON Schema for the resource
get_item_permissions_check() — authorization
Extending WooCommerce Endpoints
Add fields to existing WooCommerce resources:
register_rest_field( 'product', 'my_field', $args ) — add fields to product responses
$args includes get_callback, update_callback, schema
Filtering Responses
woocommerce_rest_prepare_{post_type} — filter response before sending (e.g., woocommerce_rest_prepare_product_object)
woocommerce_rest_pre_insert_{post_type} — filter object before saving
woocommerce_rest_{post_type}_query — filter query args
Webhooks
Built-In Webhooks
WooCommerce webhooks fire on resource events:
- Topics:
order.created, order.updated, product.created, customer.created, etc.
- Configured in WooCommerce > Settings > Advanced > Webhooks
- Delivered via HTTP POST with JSON payload and signature header
Custom Webhook Topics
Filter woocommerce_valid_webhook_events and woocommerce_webhook_topic_hooks to add custom topics.
Batch Operations
POST to /wc/v3/products/batch with create, update, delete arrays to perform bulk operations in a single request.
Best Practices
- Always use
permission_callback — never leave it empty or return true for non-public endpoints
- Validate and sanitize all input parameters
- Return proper HTTP status codes (200, 201, 400, 401, 403, 404)
- Use JSON Schema for endpoint argument validation
- Use
WP_REST_Response for responses with proper status codes
- Paginate list endpoints with
per_page, page, offset
- Include
_links for HATEOAS-style discoverability
- Use webhooks for real-time integrations instead of polling
Fetch the WooCommerce REST API docs and WordPress REST API handbook for exact endpoint paths, parameters, and authentication details before implementing.
1---2name: woo-api3description: Build and consume WooCommerce REST API v3 endpoints — authentication, custom endpoints, extending existing resources, webhooks, and batch operations. Use when creating custom API endpoints or integrating external systems with WooCommerce.4allowed-tools: Read, Write, Edit, Bash, Grep, Glob, WebSearch, WebFetch5metadata:6 source: https://skillmd.com/skills/orcaqubits/woo-api7---89# WooCommerce REST API Development1011## Before writing code1213**Fetch live docs**:141. Fetch `https://woocommerce.github.io/woocommerce-rest-api-docs/` for API reference152. Fetch `https://developer.wordpress.org/rest-api/` for WordPress REST API handbook163. Web-search `site:developer.woocommerce.com rest api extending` for extension patterns1718## REST API Architecture1920### Foundation2122WooCommerce REST API v3 extends the WordPress REST API:23- Base: `/wp-json/wc/v3/`24- Built on `WP_REST_Controller` pattern25- Supports JSON request/response26- Versioned — v3 is current; v1/v2 are legacy2728### Built-In Endpoints2930| Resource | Endpoint | Methods |31|----------|----------|---------|32| Products | `/wc/v3/products` | GET, POST, PUT, DELETE |33| Product Variations | `/wc/v3/products/{id}/variations` | GET, POST, PUT, DELETE |34| Orders | `/wc/v3/orders` | GET, POST, PUT, DELETE |35| Customers | `/wc/v3/customers` | GET, POST, PUT, DELETE |36| Coupons | `/wc/v3/coupons` | GET, POST, PUT, DELETE |37| Reports | `/wc/v3/reports` | GET |38| Settings | `/wc/v3/settings` | GET, PUT |39| Shipping Zones | `/wc/v3/shipping/zones` | GET, POST, PUT, DELETE |40| Tax Rates | `/wc/v3/taxes` | GET, POST, PUT, DELETE |41| Webhooks | `/wc/v3/webhooks` | GET, POST, PUT, DELETE |42| System Status | `/wc/v3/system_status` | GET |4344## Authentication4546### API Keys4748WooCommerce generates consumer key/secret pairs:49- **Over HTTPS**: Pass as query params `consumer_key` & `consumer_secret`, or HTTP Basic Auth50- **Over HTTP**: OAuth 1.0a signature required51- Keys have permissions: `read`, `write`, `read_write`52- Generate at WooCommerce > Settings > Advanced > REST API5354### Application Passwords (WordPress 5.6+)5556WordPress-native auth — username + application password via HTTP Basic Auth. Works for all WP REST API endpoints including WooCommerce.5758### Cookie/Nonce Authentication5960For internal (same-site) JavaScript:61- Use `wp_create_nonce( 'wp_rest' )` — set as `X-WP-Nonce` header62- Automatically handled by `wp.apiFetch` in WordPress scripts6364## Custom Endpoints6566### Registering Routes6768Use `rest_api_init` action to register routes:69- `register_rest_route( 'my-extension/v1', '/items', $args )`70- Define `methods`, `callback`, `permission_callback`, `args` (with `validate_callback` and `sanitize_callback`)7172### Controller Pattern7374Extend `WP_REST_Controller` for structured endpoints:75- `register_routes()` — define route patterns76- `get_items()` — handle collection GET77- `get_item()` — handle single GET78- `create_item()` — handle POST79- `update_item()` — handle PUT/PATCH80- `delete_item()` — handle DELETE81- `get_item_schema()` — JSON Schema for the resource82- `get_item_permissions_check()` — authorization8384### Extending WooCommerce Endpoints8586Add fields to existing WooCommerce resources:87- `register_rest_field( 'product', 'my_field', $args )` — add fields to product responses88- `$args` includes `get_callback`, `update_callback`, `schema`8990### Filtering Responses9192- `woocommerce_rest_prepare_{post_type}` — filter response before sending (e.g., `woocommerce_rest_prepare_product_object`)93- `woocommerce_rest_pre_insert_{post_type}` — filter object before saving94- `woocommerce_rest_{post_type}_query` — filter query args9596## Webhooks9798### Built-In Webhooks99100WooCommerce webhooks fire on resource events:101- Topics: `order.created`, `order.updated`, `product.created`, `customer.created`, etc.102- Configured in WooCommerce > Settings > Advanced > Webhooks103- Delivered via HTTP POST with JSON payload and signature header104105### Custom Webhook Topics106107Filter `woocommerce_valid_webhook_events` and `woocommerce_webhook_topic_hooks` to add custom topics.108109## Batch Operations110111POST to `/wc/v3/products/batch` with `create`, `update`, `delete` arrays to perform bulk operations in a single request.112113## Best Practices114115- Always use `permission_callback` — never leave it empty or return `true` for non-public endpoints116- Validate and sanitize all input parameters117- Return proper HTTP status codes (200, 201, 400, 401, 403, 404)118- Use JSON Schema for endpoint argument validation119- Use `WP_REST_Response` for responses with proper status codes120- Paginate list endpoints with `per_page`, `page`, `offset`121- Include `_links` for HATEOAS-style discoverability122- Use webhooks for real-time integrations instead of polling123124Fetch the WooCommerce REST API docs and WordPress REST API handbook for exact endpoint paths, parameters, and authentication details before implementing.