OrgRelay
orgrelay.com

WooCommerce connector: a REST key pair, nine tools, and approval on every change

This page is for whoever runs the WordPress site behind a WooCommerce store, whether that is the owner, an agency or in-house IT. It explains which key to create, what the server must allow, what each tool returns, and which three actions wait for a person to approve them.

The connector depends on your WordPress hosting as much as on WooCommerce. It calls the WooCommerce REST API under /wp-json/wc/v3 and authenticates with a consumer key and consumer secret. There is no OAuth step and nothing to register with WooCommerce.com. For how a connector like this fits OrgRelay's model, see the connector spec.

What staff can ask

  • "Which orders are still processing from the weekend?" This calls orders.search with status: processing and date_from/date_to. The date range becomes WooCommerce's after and before filters, and the end date runs to 23:59:59.
  • "What's in order 4821 and is there a customer note?" This calls orders.get with the number as shown in the store, even when a sequential numbering plugin is installed. It returns line items, shipping city and country, and the note the customer left at checkout.
  • "Which products are out of stock or running low?" This calls inventory.list with low_only: true.
  • "Mark 4821 completed and note that it went by courier." This calls orders.update_status with status: completed and a note. It waits for approval.
  • "Put the blue mug on sale at 9.50, regular price 12." This calls products.update_price with price and sale_price. It also waits for approval.

The names match the domain vocabulary in standard tools, so the same question about orders works whether a team is granted this store or the Shopify connector. If checkout runs through Stripe, the Stripe connector answers the payment side of the same order.

Tools

Tool Access What it does Key parameters
orders.search read Lists orders status (pending, processing, on-hold, completed, cancelled, refunded, failed), customer (sent as search), date_from, date_to, limit, cursor
orders.get read One order by its displayed number, with line items, shipping city and country, and the customer note order_no
products.search read Products with price, status and stock keyword, sku, limit, cursor
inventory.list read Stock quantity, stock status and low-stock threshold per product sku, low_only (out of stock, on backorder, or at or below the product's own threshold), limit, cursor
customers.search read Registered customers with email, billing country and order count keyword, limit, cursor
reports.sales_summary read Orders, items and sales for a date range date_from, date_to (both required)
orders.update_status write · approval Moves an order to a new status, optionally adding a note order_no, status (processing, on-hold, completed, cancelled), note
products.update_price write · approval Sets the regular price and optionally the sale price of a SKU sku, price, sale_price
inventory.set_stock write · approval Sets an absolute stock quantity for a SKU sku, quantity

How the code behaves:

  • Paging is by page number for ordinary lists. cursor is the page, starting at 1. limit defaults to 20 and caps at 100. The connector offers a next page whenever the current page came back full, so the last page can be empty.
  • Order numbers are matched as displayed. orders.get and orders.update_status accept 4821 or #4821 and resolve it to the internal ID by comparing WooCommerce's number field, which numbering plugins change.
  • Variations are handled. When a SKU belongs to a variation, price and stock updates go to /products/<parent>/variations/<id>. Simple products are updated at /products/<id>.
  • low_only reads the whole catalogue. WooCommerce cannot filter by "at or below the low-stock amount", so the connector walks the product list 100 at a time, up to 5,000 products, and keeps those that are out of stock, on backorder, or managed and at or below their own low-stock amount. The cursor is then a position in that filtered list. A store with more than 5,000 products gets truncated: true and a note saying how many were checked.
  • reports.sales_summary uses the legacy report. It reads /reports/sales with date_min and date_max and returns total_orders, total_items and total_sales. These figures can differ from WooCommerce Analytics, which counts differently.
  • Prices come back without a currency on product lists. The store's currency is on orders only.

Credentials and server requirements

The connector has three fields:

  • Store URL, for example https://shop.example.com. The connector appends /wp-json/wc/v3.
  • Consumer key, starting with ck_.
  • Consumer secret, starting with cs_. OrgRelay encrypts it and shows only the last four characters afterwards.

The server has to meet a few conditions. WooCommerce documents version 3.5 or later and WordPress 4.4 or later. Pretty permalinks must be on, because the /wp-json/ routes do not resolve with plain permalinks. If they are off, WordPress answers with an HTML page instead of JSON, and the connector says so and points you to Settings → Permalinks. The site must use HTTPS. The connector first sends the key pair as an HTTP Basic Authorization header. Some Apache, CGI and FastCGI setups drop that header, and WooCommerce then answers 401. In that case the connector retries with consumer_key and consumer_secret as query parameters, which the WooCommerce docs describe as the fallback, and uses that method for the site from then on. It only does this over HTTPS. Query-string authentication requires OrgRelay 1.4.0 or later. Security plugins and web application firewalls sometimes block /wp-json/ for unknown clients. Allow the OrgRelay machine's address if that happens.

Permissions come from two places. The key has its own Read, Write or Read/Write setting. The key also acts as the WordPress user you chose when creating it, so that user needs WooCommerce management rights. The connection test reads /system_status, which needs a shop manager or administrator. Keys do not expire, so treat them like passwords and keep them off shared drives; the security model explains what OrgRelay does on its side. To rotate one, generate a new key, update it in OrgRelay, then revoke the old key in WordPress. The auth page covers how OrgRelay stores both values.

Which actions need approval

Three tools change the store. Each creates an approval request, and the call runs only after the owner or a designated approver accepts it. The approver sees the tool name and the arguments:

  • orders.update_status: the order and the target status. A status change runs WooCommerce's normal hooks. "Completed" can send the customer the completed-order email set up under WooCommerce → Settings → Emails, and "cancelled" can restore stock, so approvers should know how the store is configured. If a note is present, the connector posts it as a separate private order note after the status change.
  • products.update_price: the SKU, the new regular price and, if given, the sale price. Leaving sale_price out keeps the current sale price.
  • inventory.set_stock: the SKU and the absolute quantity. This is not a delta. The connector also turns on "manage stock" for that product, so a product that was not tracking stock starts tracking it.

Approved calls carry the idempotency key orgrelay-approval-<approval id>, and OrgRelay uses it to run each approval once. The WooCommerce endpoints used here have no idempotency header, so the key stays inside OrgRelay. The whole flow is described in approvals and writes, and the reasons for a person in the loop are on human in the loop. For the business view of approvals, see OrgRelay approvals.

Set it up

  1. In WordPress admin, open Settings → Permalinks and pick any structure except Plain.
  2. Open WooCommerce → Settings → Advanced → REST API and click Add key.
  3. Enter a description such as "OrgRelay". Choose a WordPress user with the shop manager role. Set permissions to Read for reports only, or Read/Write if you want the three write tools.
  4. Click Generate API key and copy the consumer key and secret. WooCommerce shows the secret only on this screen.
  5. Check that the store loads over HTTPS.
  6. In OrgRelay, open Admin → Business systems → App directory, pick WooCommerce, enter the store URL and both keys, and click Connect. OrgRelay reads one order to test the key and shows the store's host name.
  7. Grant the connector to the roles that need it, and switch off tools they should not use. A warehouse role might keep inventory.set_stock and lose products.update_price.

To try the write tools without touching live orders, install WooCommerce on a staging copy of the site and bind that first. Building your own connector for a different WordPress plugin? Start with the quickstart and run the connector check before binding it.

Limits and things it does not do

WooCommerce core does not rate-limit its REST API, so the real limit is your host. Shared hosting can slow down or return errors under bursts. OrgRelay keeps traffic modest anyway: at most 120 calls per minute per connection by default, and a 60-second pause after three failures in a row. If the host returns HTTP 429, OrgRelay waits for the Retry-After time, or 60 seconds if none is given.

The connector does not:

  • issue refunds or create orders, coupons or shipments;
  • change product titles, descriptions, images or categories;
  • read street addresses, phone numbers or payment details (orders give city and country only);
  • see guest customers in customers.search, because WooCommerce's customers endpoint lists registered accounts only;
  • read data added by other plugins, such as bookings or subscriptions, unless that data appears in the core order and product fields.

If a plugin exposes its own REST routes, you can add them as a separate connector through the OpenAPI import or REST compatible mode. For changes pushed from the store, such as new orders, see events. The AI sees about 12,000 characters of any result, so filtered questions work better than "list every product".

Official MCP server and OrgRelay

WooCommerce documents an MCP integration marked as a developer preview. WooCommerce registers abilities for products and orders through the WordPress Abilities API. You install the separate MCP Adapter plugin to expose them at /wp-json/mcp/mcp-adapter-default-server. Remote clients sign in with a WordPress username and an application password, not a REST API key. The abilities can query, create, update and delete products, and query orders, update order status and add order notes. WooCommerce's guidance is to use a dedicated user with only the capabilities the client needs.

OrgRelay can connect that HTTP endpoint as a third-party MCP connection if you prefer WooCommerce's own tools. The local STDIO route through WP-CLI cannot be connected directly, because OrgRelay does not bridge stdio servers. What OrgRelay adds is the same whichever route you pick: per-role grants, an approval before every write, one audit log across WooCommerce and the rest of your systems, and everything running on the company's own machine. For how vendor servers compare, see official MCP servers and enterprise patterns.

Common questions

Should the API key be Read or Read/Write?

Read is enough for the six read tools. The three write tools need Read/Write. OrgRelay still holds every write for approval, but a Read key adds a second lock inside WordPress itself.

We use a sequential order number plugin. Will orders.get find the right order?

Yes. The connector matches the order number the store displays, not the internal ID. For an all-digit number it first tries the order with that ID and keeps it only if its displayed number matches; otherwise it searches orders and picks the exact number match. A leading # is ignored.

Why does the connector return 401 on a store that works in the browser?

Usually the key is wrong, revoked, or belongs to a user without WooCommerce rights. A host that strips the Authorization header is handled: on HTTPS the connector retries with the keys as query parameters and remembers that for the site. On plain HTTP it cannot, so the store must use HTTPS.

Updated (Singapore time) · OrgRelay Team