woo-api

name	woo-api
description	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.

WooCommerce REST API Development

Before writing code

Fetch live docs:

1. Fetch https://woocommerce.github.io/woocommerce-rest-api-docs/ for API reference
2. Fetch https://developer.wordpress.org/rest-api/ for WordPress REST API handbook
3. 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.