A reference guide for building AI agents: every method, how to authenticate, and the permissions each one needs.
The WooCommerce API is how an app or AI agent works with an online store: listing products, updating stock, reading and fulfilling orders, managing customers, and issuing refunds. Access is granted through an API key generated for a store user, and that key is set to read, write, or read and write when it is created, which bounds every call the key can make. WooCommerce can also push an event to a registered endpoint when a resource is created, updated, or deleted.
How an app or AI agent connects to WooCommerce determines what it can reach. There is a route for making calls against a store with an API key, a route for receiving events when something changes, and a first-party server that exposes WooCommerce as agent tools, and each is governed by the key behind it and the permission level that key carries.
The REST API runs inside WordPress under the store's domain at /wp-json/wc/v3, taking and returning JSON. A call authenticates with a consumer key and consumer secret, sent as HTTP Basic auth over HTTPS or signed with OAuth 1.0a over plain HTTP. Lists are page-based with a per_page cap of 100, and most resources offer a batch endpoint.
WooCommerce POSTs the changed resource as JSON to a registered URL when a coupon, customer, order, or product is created, updated, or deleted. Each delivery carries X-WC-Webhook-Topic, X-WC-Webhook-Resource, and X-WC-Webhook-Event headers, plus an X-WC-Webhook-Signature header (a base64 HMAC-SHA256 of the payload) so the receiver can verify it. Deliveries are sent in the background, by default through wp-cron.
WooCommerce ships a first-party Model Context Protocol server, built with Automattic on the WordPress Abilities system, that exposes store tools to AI agents and clients like Claude. An agent connects through the @automattic/mcp-wordpress-remote local proxy, which speaks MCP over stdio and translates calls into authenticated HTTP requests to the store. It authenticates with a WooCommerce REST API key and currently exposes product and order management plus REST-derived compatibility tools. It is in developer preview, so details may change.
A consumer key and consumer secret are generated for a WordPress user in the store's WooCommerce settings. Over HTTPS they are sent as HTTP Basic auth, the consumer key as the username and the consumer secret as the password. The key carries one permission level, read, write, or read and write, set when it is created, and inherits the capabilities of the user it belongs to.
When the store is served over plain HTTP, the same consumer key and secret are used to sign each request with OAuth 1.0a one-legged authentication, rather than sent directly, so they cannot be intercepted in transit. The signing uses the consumer key, a timestamp, a nonce, and an HMAC signature over the request.
The WooCommerce API is split into areas an agent can act on, like products, orders, customers, coupons, and refunds. Each area has its own methods, and writes in some areas change what shoppers see or move money back to a customer.
Methods for working with products in the catalog.
Methods for working with product categories.
Methods for working with orders and order notes.
Methods for working with refunds against orders.
Methods for working with customer accounts.
Methods for working with discount coupons.
Read-only sales and totals reports.
Methods for managing webhook subscriptions.
Filter by method, access, or permission, or search any path. Select a row for version detail, rate limits, the related webhook event, and the source.
| Method | Endpoint | What it does | Access | Permission | Version | |
|---|---|---|---|---|---|---|
ProductsMethods for working with products in the catalog.6 | ||||||
| GET | /wc/v3/products | List all products in the store (page-based). | read | read | Current | |
Any read or read/write key can call this. Acts onproduct Permission (capability) readVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| GET | /wc/v3/products/ | Retrieve a single product by ID. | read | read | Current | |
Any read or read/write key can call this. Acts onproduct Permission (capability) readVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| POST | /wc/v3/products | Create a new product in the catalog. | write | write | Current | |
Needs a write or read/write key. Acts onproduct Permission (capability) writeVersionAvailable since the API’s base version Webhook event product.createdRate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| PUT | /wc/v3/products/ | Update an existing product, like its price or stock. | write | write | Current | |
Needs a write or read/write key. Acts onproduct Permission (capability) writeVersionAvailable since the API’s base version Webhook event product.updatedRate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| DELETE | /wc/v3/products/ | Delete a product, or move it to the trash unless force is set. | write | write | Current | |
Needs a write or read/write key; pass force=true to permanently delete. Acts onproduct Permission (capability) writeVersionAvailable since the API’s base version Webhook event product.deletedRate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| POST | /wc/v3/products/batch | Create, update, and delete many products in one request. | write | write | Current | |
Needs a write or read/write key; up to 100 objects per call. Acts onproduct Permission (capability) writeVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
Product categoriesMethods for working with product categories.3 | ||||||
| GET | /wc/v3/products/categories | List all product categories. | read | read | Current | |
Any read or read/write key can call this. Acts onproduct_cat Permission (capability) readVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| POST | /wc/v3/products/categories | Create a new product category. | write | write | Current | |
Needs a write or read/write key. Acts onproduct_cat Permission (capability) writeVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| PUT | /wc/v3/products/categories/ | Update an existing product category. | write | write | Current | |
Needs a write or read/write key. Acts onproduct_cat Permission (capability) writeVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
OrdersMethods for working with orders and order notes.8 | ||||||
| GET | /wc/v3/orders | List all orders (page-based, filterable by status and date). | read | read | Current | |
Any read or read/write key can call this; returns customer and line-item data. Acts onorder Permission (capability) readVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| GET | /wc/v3/orders/ | Retrieve a single order by ID. | read | read | Current | |
Any read or read/write key can call this. Acts onorder Permission (capability) readVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| POST | /wc/v3/orders | Create a new order, setting line items, customer, and status. | write | write | Current | |
Needs a write or read/write key. Acts onorder Permission (capability) writeVersionAvailable since the API’s base version Webhook event order.createdRate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| PUT | /wc/v3/orders/ | Update an order, like changing its status or line items. | write | write | Current | |
Needs a write or read/write key; setting status drives fulfillment. Acts onorder Permission (capability) writeVersionAvailable since the API’s base version Webhook event order.updatedRate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| DELETE | /wc/v3/orders/ | Delete an order, or move it to the trash unless force is set. | write | write | Current | |
Needs a write or read/write key; pass force=true to permanently delete. Acts onorder Permission (capability) writeVersionAvailable since the API’s base version Webhook event order.deletedRate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| POST | /wc/v3/orders/batch | Create, update, and delete many orders in one request. | write | write | Current | |
Needs a write or read/write key; up to 100 objects per call. Acts onorder Permission (capability) writeVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| GET | /wc/v3/orders/ | List the notes attached to an order. | read | read | Current | |
Any read or read/write key can call this. Acts onorder_note Permission (capability) readVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| POST | /wc/v3/orders/ | Add a note to an order, optionally visible to the customer. | write | write | Current | |
Needs a write or read/write key; a customer-visible note can email the customer. Acts onorder_note Permission (capability) writeVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
RefundsMethods for working with refunds against orders.2 | ||||||
| GET | /wc/v3/orders/ | List the refunds recorded against an order. | read | read | Current | |
Any read or read/write key can call this. Acts onorder_refund Permission (capability) readVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| POST | /wc/v3/orders/ | Create a refund against an order, fully or partially. | write | write | Current | |
Needs a write or read/write key; with api_refund set, it sends money back through the payment gateway. Acts onorder_refund Permission (capability) writeVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
CustomersMethods for working with customer accounts.3 | ||||||
| GET | /wc/v3/customers | List all customers (page-based). | read | read | Current | |
Any read or read/write key can call this; returns names, emails, and addresses. Acts oncustomer Permission (capability) readVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| POST | /wc/v3/customers | Create a new customer account. | write | write | Current | |
Needs a write or read/write key. Acts oncustomer Permission (capability) writeVersionAvailable since the API’s base version Webhook event customer.createdRate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| PUT | /wc/v3/customers/ | Update an existing customer's details. | write | write | Current | |
Needs a write or read/write key. Acts oncustomer Permission (capability) writeVersionAvailable since the API’s base version Webhook event customer.updatedRate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
CouponsMethods for working with discount coupons.3 | ||||||
| GET | /wc/v3/coupons | List all discount coupons. | read | read | Current | |
Any read or read/write key can call this. Acts oncoupon Permission (capability) readVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| POST | /wc/v3/coupons | Create a new discount coupon. | write | write | Current | |
Needs a write or read/write key. Acts oncoupon Permission (capability) writeVersionAvailable since the API’s base version Webhook event coupon.createdRate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| PUT | /wc/v3/coupons/ | Update an existing coupon's terms. | write | write | Current | |
Needs a write or read/write key. Acts oncoupon Permission (capability) writeVersionAvailable since the API’s base version Webhook event coupon.updatedRate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
ReportsRead-only sales and totals reports.3 | ||||||
| GET | /wc/v3/reports/sales | Retrieve a sales report over a date range. | read | read | Current | |
Read-only; exposes store revenue and totals. Acts onreport Permission (capability) readVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| GET | /wc/v3/reports/top_sellers | Retrieve the top-selling products over a date range. | read | read | Current | |
Read-only. Acts onreport Permission (capability) readVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| GET | /wc/v3/reports/orders/totals | Retrieve order counts grouped by status. | read | read | Current | |
Read-only. Acts onreport Permission (capability) readVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
WebhooksMethods for managing webhook subscriptions.3 | ||||||
| GET | /wc/v3/webhooks | List all webhook subscriptions in the store. | read | read | Current | |
Any read or read/write key can call this. Acts onwebhook Permission (capability) readVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| POST | /wc/v3/webhooks | Create a webhook that POSTs to a URL when a topic fires. | write | write | Current | |
Needs a write or read/write key; sets the topic and delivery URL. Acts onwebhook Permission (capability) writeVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| DELETE | /wc/v3/webhooks/ | Delete a webhook subscription. | write | write | Current | |
Needs a write or read/write key; pass force=true to permanently delete. Acts onwebhook Permission (capability) writeVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
WooCommerce can notify an app when something happens in a store, like an order being created or a product being updated. It sends the changed resource as JSON with headers naming the topic, resource, and event, and signs each delivery so the receiver can confirm it came from the store.
| Event | What it signals | Triggered by |
|---|---|---|
order.created | A new order was created. The payload is the order resource, the same JSON returned by the orders API. | /wc/v3/orders |
order.updated | An order changed, like its status moving to processing or completed. | /wc/v3/orders/ |
order.deleted | An order was deleted or trashed. | /wc/v3/orders/ |
product.created | A new product was created in the catalog. | /wc/v3/products |
product.updated | A product changed, like its price, stock, or status. | /wc/v3/products/ |
product.deleted | A product was deleted or trashed. | /wc/v3/products/ |
customer.created | A new customer account was created. | /wc/v3/customers |
customer.updated | A customer's details changed. | /wc/v3/customers/ |
coupon.created | A new coupon was created. | /wc/v3/coupons |
coupon.updated | A coupon's terms changed. | /wc/v3/coupons/ |
WooCommerce core enforces no rate limit of its own, so how fast an app can call depends on the WordPress host that runs the store. Lists are capped at 100 items per page.
WooCommerce core does not enforce a rate limit of its own, so how fast an app or agent can call is set by the WordPress host that runs the store, like its PHP worker count, memory, and any rate limiting the host or a security plugin adds. There is no documented per-method cost or quota, and going too fast surfaces as host-level errors (such as a 429 or 503 from the host) rather than an API limit. WooCommerce's own newer Store API has separate, documented rate limiting, but the v3 REST API used here does not.
A list endpoint is page-based: page sets which page to return (1-based, default 1) and per_page sets the page size (default 10, maximum 100). An offset parameter can skip a number of records from the start. The response carries an X-WP-Total header with the total number of records and an X-WP-TotalPages header with the total number of pages, and a Link header gives next, prev, first, and last page URLs.
A list endpoint returns at most 100 records per page, the maximum value of per_page; fetching more means paging through with page or offset. A batch request processes many records in a single call, capped at 100 objects per request across its create, update, and delete arrays combined.
The status codes an agent should handle, and what to do about each.
| Status | Code | Meaning | What to do |
|---|---|---|---|
| 400 | woocommerce_rest_invalid_* | The request was bad: a parameter is missing or invalid. The JSON body carries code, message, and a data.status of 400. | Read the message, fix the parameters, and resend. The request is not retryable as-is. |
| 401 | woocommerce_rest_authentication_error / woocommerce_rest_cannot_* | Authentication failed, or the key lacks permission for the request, like a read key attempting a write. | Confirm the consumer key and secret are correct and that the key has the needed permission level, then resend. |
| 404 | woocommerce_rest_*_invalid_id | The requested resource does not exist or is not visible to this key. | Verify the resource ID and that it exists in this store, then resend. |
| 500 | internal_server_error | An error on the server side, often from the WordPress host running the store. | Retry with backoff, and check the host or store logs if it persists. |
WooCommerce versions its REST API by a path segment, where v3 is the current namespace and earlier v1 and v2 namespaces remain for older integrations.
The current REST API namespace, served under the store at /wp-json/wc/v3. It is versioned by the path segment rather than by a dated string, and tracks the WooCommerce plugin as it ships features through plugin releases. The older wc/v1 and wc/v2 namespaces remain available for existing integrations.
An earlier REST API namespace, served at /wp-json/wc/v2, still available for integrations built against it.
The first WooCommerce-namespaced REST API, served at /wp-json/wc/v1, kept for older integrations.
Target the v3 namespace for new integrations; v1 and v2 stay available for older code.
WooCommerce release posts ↗Bollard AI sits between a team's AI agents and WooCommerce. Grant each agent exactly the access it needs, read or write, resource by resource, and every call is checked and logged.