WooCommerce Integration

Connect a Wiro agent directly to a WooCommerce store with a REST API consumer key and secret.

Overview

The int-woocommerce-manage skill uses WooCommerce's official, current recommended WP REST API namespace, wc/v3, to work with products, variations, taxonomy, inventory, orders, refunds, coupons, customers, reports, and supported store settings.

Prerequisites

• A deployed Wiro agent with the int-woocommerce-manage skill enabled.
• A public HTTPS WooCommerce store with REST API routing enabled.
• A WordPress user with the minimum permissions needed for the requested operations.

Setup

1. Create a WooCommerce REST API key

In WordPress Admin:

1. Open WooCommerce → Settings → Advanced → REST API.
2. Select Add key.
3. Choose the WordPress user the agent should act as.
4. Choose Read/Write only if the agent must modify the store; otherwise use Read.
5. Generate the key and copy both the consumer key and consumer secret.

2. Save credentials

Use the store's public base URL. Keep an existing WordPress subdirectory, but omit /wp-json/wc/v3, query strings, fragments, and the trailing slash.

curl -X POST "https://api.wiro.ai/v1/UserAgent/CredentialUpsert" \
  -H "Content-Type: application/json" \
  -H "x-api-key: YOUR_API_KEY" \
  -d '{
    "useragentguid": "your-useragent-guid",
    "fields": [
      { "credentialkey": "woocommerce", "fieldname": "storeurl", "fieldvalue": "https://store.example.com" },
      { "credentialkey": "woocommerce", "fieldname": "consumerkey", "fieldvalue": "ck_..." },
      { "credentialkey": "woocommerce", "fieldname": "consumersecret", "fieldvalue": "cs_..." }
    ]
  }'

3. Start or restart the agent

curl -X POST "https://api.wiro.ai/v1/UserAgent/Start" \
  -H "Content-Type: application/json" \
  -H "x-api-key: YOUR_API_KEY" \
  -d '{ "guid": "your-useragent-guid" }'

Credential fields

Runtime behavior

• Base endpoint: {storeurl}/wp-json/wc/v3
• Authentication: HTTPS Basic Auth with the consumer key and secret.
• Credentials are never added to URL query parameters.
• Collection endpoints use page-number pagination and inspect X-WP-TotalPages.
• The agent reads the current resource before a write and verifies the resource after a successful mutation.
• Ambiguous create/update outcomes are reconciled by reading remote state before any retry. WooCommerce has no universal idempotency header.
• Refund amount, currency, line items, restock behavior, and gateway behavior must be explicit; the agent does not infer them.

Products, inventory, and batch requests

• Product and variation writes use documented fields such as manage_stock, stock_quantity, stock_status, and backorders. Wiro does not treat low_stock_amount as a supported product/variation mutation field.
• POST /products/batch accepts create, update, and delete arrays. It is a convenience batch, not one atomic transaction: inspect every returned array item, and reconcile each item independently.
• A top-level 2xx response does not mean every batch item succeeded. Do not retry the whole batch after a partial or ambiguous result; retrying confirmed successes can duplicate creates.
• WooCommerce has no universal idempotency-key header. Wiro uses natural keys such as SKU/slug, records one ledger entry per item, and reads remote state before retrying an uncertain write.

Settings

• Read groups with GET /settings, group options with GET /settings/{group_id}, and one option with GET /settings/{group_id}/{option_id}.
• Update one writable option with PUT /settings/{group_id}/{option_id}.
• Batch-update writable options in one group with POST /settings/{group_id}/batch and an update array. This endpoint does not create or delete arbitrary settings.
• Payment gateways and shipping zones are separate resources, not generic setting options.

Errors and rate limits

WooCommerce/WordPress errors use the HTTP status plus a JSON object shaped like { code, message, data }; data.status commonly repeats the status. For batch calls, also inspect each returned item.

Core wc/v3 does not publish one built-in global request quota or standardized rate-limit header contract. A store, host, WAF, reverse proxy, or plugin can still return 429. When it does, honor Retry-After or another explicit reset header if present; otherwise stop and retry later with conservative backoff. Do not copy the optional WooCommerce Store API RateLimit-* contract onto wc/v3.

Troubleshooting

• 400: The payload, field, or state transition is invalid. Read the response's code, message, and data; do not infer success from a partially populated object.
• 401: The key/secret is invalid, revoked, or belongs to a different store.
• 403: The key's WordPress user or permission level cannot access the resource.
• 404 under /wp-json/wc/v3: The store URL or WordPress subdirectory is wrong, WooCommerce REST routing is unavailable, or permalinks need configuration.
• 409: The resource changed or conflicts with current state. Re-read it before deciding whether a new write is appropriate.
• 429: A store-specific limiter blocked the request. Follow the headers that store actually returned; wc/v3 itself does not guarantee Retry-After.
• 5xx or transport timeout after a write: The outcome is unknown. Reconcile by resource ID or natural key before any retry.
• WAF or reverse proxy failures: Allow authenticated requests to the WooCommerce REST route without redirecting to another hostname.

Related

• Agent Credentials & OAuth
• Agent Skills
• WooCommerce REST API documentation