WooCommerce ExecModule

Overview

WooCommerceModule connects ValkyrAI workflows to the WooCommerce REST API v3 through the native map I/O ExecModule ABI. It covers the same customer, order, and product action families emphasized by n8n while enforcing ValkyrAI's IntegrationAccount, validation, retry, redaction, and observability contracts.

The module provides 15 operations: create, get, list, update, and guarded permanent delete for customers, orders, and products. Collection reads support bounded filters and page traversal. GET requests retry transient failures conservatively; creates, updates, and deletes are single-attempt because a transport failure can leave their provider outcome ambiguous.

Usage

1. Enable WordPress permalinks and the WooCommerce REST API on the target store.
2. Create a dedicated WooCommerce REST API key with only the read or read/write permissions the workflow needs.
3. Store the consumer key in encrypted IntegrationAccount.apiKey, the consumer secret in encrypted IntegrationAccount.password, and the HTTPS store origin in IntegrationAccount.accountId.
4. Set the account status to READY and bind it through ExecModuleConfig.authConfig.integrationAccount.
5. Choose one documented operation and supply only its typed resource ID, record, filters, and pagination controls.
6. Require a human or policy approval before setting confirmDelete: true.

Credentials, authorization headers, arbitrary HTTP methods, and alternate API paths cannot come from workflow input.

Inputs

Name	Type	Requirement	Default	Description and constraints
operation	string	Required	None	One of the 15 documented operations.
storeUrl	string	Required unless account supplies it	IntegrationAccount.accountId	HTTPS public-DNS store origin, optionally with a bounded WordPress subdirectory path. Credentials, custom ports, query strings, fragments, localhost, and IP literals are rejected.
resourceId	integer	Get/update/delete	None	Positive customer, order, or product ID.
record	object or JSON string	Create/update	None	Non-empty, resource-specific allowlisted fields; at most 80 properties and 256 KiB. Credential-like fields are rejected.
query	object or JSON string	Optional list filter	{}	Up to 20 resource-specific filters with bounded scalar or scalar-array values.
page	integer	Optional list start	1	First provider page, 1–100,000.
perPage	integer	Optional	100	WooCommerce page size, 1–100.
returnAll	boolean	Optional	false	Follow pages until exhaustion or the 10,000-item safety cap.
confirmDelete	boolean	Delete only	false	Must be true; the module sends WooCommerce force=true.
timeoutMs	integer	Optional	30000	Total/connect/read/write timeout, 100–300,000 ms.

Create requirements include a bounded email for customers, a bounded name for products, and either line_items or customer_id for orders. Customer password creation is intentionally deferred so workflow payloads cannot carry credential-like fields.

Outputs

Name	Type	When present	Description
status	string	Always	success or error.
operation	string	Always	Normalized operation name.
resource	string	Valid operation	customers, orders, or products.
data / id	object / integer	Single-resource success	Provider resource and verified positive ID.
items / count	array / integer	List success	Bounded collection resources and emitted count.
hasMore / nextPage	boolean / integer	List success	Provider pagination state.
httpStatus	integer	Single-resource provider response	WooCommerce HTTP status.
attempts	integer	Always	Total provider attempts, including page reads.
error	object	Failure	Safe {code, message, retryable} details.

Consumer keys, consumer secrets, Basic authorization values, and credential-bearing provider text are redacted from errors and outputs.

IntegrationAccount Requirements

Setting	Requirement
Provider	WooCommerce REST API v3 store
accountName	Human-readable automation identity
accountId	HTTPS store origin, for example https://store.example.com
apiKey	Encrypted WooCommerce consumer key, normally ck_...
password	Encrypted WooCommerce consumer secret, normally cs_...
status	READY; every other status fails closed
Permission	read for get/list-only workflows or read/write for approved mutations

WooCommerce REST API keys inherit the WordPress user's capabilities. Use a dedicated minimum-access user, rotate the key through the IntegrationAccount lifecycle, and never place either credential in workflow JSON.

Configuration

{
  "version": "1.0.0",
  "authConfig": {
    "authStrategy": 1,
    "integrationAccount": "integration-account:woocommerce-production-store"
  },
  "retryPolicy": {
    "maxAttempts": 3,
    "backoffStrategy": "EXPONENTIAL",
    "initialDelayMs": 1000,
    "maxDelayMs": 5000,
    "jitter": false
  },
  "executionConfig": {"timeoutMs": 30000},
  "payloadConfig": {
    "parameters": "{\"operation\":\"list_orders\",\"perPage\":50,\"query\":{\"status\":\"processing\"}}"
  }
}

The integration-account value is symbolic. Persisted workflows use the generated relationship, not embedded credentials.

Operations

Operation	WooCommerce behavior	Side effect
create_customer	Creates a customer with a bounded email and allowlisted profile/address metadata.	Customer write; single attempt.
get_customer	Reads one customer by ID.	Read-only; safe retries.
list_customers	Lists customers with search, email, role, ordering, and ID filters.	Read-only; paginated safe retries.
update_customer	Updates allowlisted customer fields.	Customer write; single attempt.
delete_customer	Permanently deletes one customer with force=true.	Destructive; confirmation required.
create_order	Creates an order from typed customer, line-item, address, payment, shipping, fee, coupon, and metadata fields.	Order write; single attempt.
get_order	Reads one order by ID.	Read-only; safe retries.
list_orders	Lists orders by status, customer, product, time, parent, search, and ordering filters.	Read-only; paginated safe retries.
update_order	Updates allowlisted order fields.	Order write; single attempt.
delete_order	Permanently deletes one order with force=true.	Destructive; confirmation required.
create_product	Creates a product with bounded catalog, price, stock, shipping, media, category, attribute, and metadata fields.	Product write; single attempt.
get_product	Reads one product by ID.	Read-only; safe retries.
list_products	Lists products by catalog, stock, category, tag, price, SKU, time, and ordering filters.	Read-only; paginated safe retries.
update_product	Updates allowlisted product fields.	Product write; single attempt.
delete_product	Permanently deletes one product with force=true.	Destructive; confirmation required.

Errors and Failure Modes

Code	Typical cause	Retryable	Resolution
VALIDATION_ERROR	Invalid store origin, credential, ID, payload, filter, timestamp, pagination, or delete acknowledgement.	No	Correct the named field; no unsafe request was sent.
UNSUPPORTED_OPERATION	Unknown operation.	No	Select a documented operation.
INTEGRATION_ACCOUNT_REQUIRED	No bound account.	No	Bind a WooCommerce IntegrationAccount.
INTEGRATION_ACCOUNT_NOT_READY	Account is not READY.	No	Repair or reconnect the account.
WOOCOMMERCE_WOOCOMMERCE_REST_*	WooCommerce returned a structured API error.	Depends on HTTP status	Correct permissions, resource state, or payload.
WOOCOMMERCE_HTTP_401 / 403	Key is invalid, expired, or under-scoped.	No	Rotate the key or grant the minimum required capability.
WOOCOMMERCE_HTTP_404	Resource or REST route is absent.	No	Verify permalinks, WooCommerce activation, version, and resource ID.
WOOCOMMERCE_HTTP_429 / 5xx	Rate limit or transient store failure.	Yes for reads	Honor Retry-After; reconcile mutations before repeating them.
NETWORK_ERROR	DNS, TLS, timeout, or connectivity failure.	Yes for reads	Verify the store; never blindly retry an ambiguous mutation.
RESPONSE_TOO_LARGE	One response exceeded 5 MiB.	No	Narrow filters or lower perPage.

Example

List paid orders waiting for fulfillment:

{
  "operation": "list_orders",
  "storeUrl": "https://store.example.com",
  "perPage": 50,
  "returnAll": false,
  "query": {
    "status": "processing",
    "orderby": "date",
    "order": "asc"
  }
}

Expected result:

{
  "status": "success",
  "operation": "list_orders",
  "resource": "orders",
  "count": 2,
  "hasMore": false,
  "attempts": 1,
  "items": [
    {"id": 1042, "status": "processing"},
    {"id": 1048, "status": "processing"}
  ]
}

Notes

• Pagination: list operations set page and per_page, consume X-WP-TotalPages, stop after the requested page unless returnAll is enabled, and cap aggregate results at 10,000.
• Rate limits: GET operations retry HTTP 408, 429, 500, 502, 503, and 504 up to three attempts with bounded backoff and integer Retry-After. Mutations never retry automatically.
• API limits: every response is capped at 5 MiB, every record at 256 KiB and 80 fields, filters at 20 fields, page size at 100, and aggregate results at 10,000. Store origins, strings, arrays, IDs, and timestamps are validated before dispatch.
• Idempotency: get/list operations are safe reads. Create, update, and delete are not assumed idempotent; a timeout is ambiguous and requires provider reconciliation before a manual retry. Use stable SKU, email, transaction, and caller correlation data where the business process supports it.
• Destructive behavior: all exposed delete operations send force=true, are permanent, and require confirmDelete: true. This version does not expose batch deletion.
• Privacy: customer and order responses can contain personal and transactional data. Limit downstream propagation, logging, retention, and workflow audiences to the governing policy.
• Routing: production requests use the validated HTTPS store origin plus the fixed /wp-json/wc/v3 API root. HTTP downgrade, embedded credentials, custom ports, arbitrary paths, localhost, and IP literals are rejected.
• External verification: request construction, Basic authentication, pagination, validation, retry safety, response mapping, identity checks, redaction, and metadata discovery are deterministic local tests. Live WordPress capabilities, plugin configuration, proxies, extensions, rate limits, and store data require separately authorized WooCommerce credentials and are not exercised in repository tests.
• Deferred operations: coupons, product variations, categories, tags, attributes, shipping zones, tax classes, refunds, notes, reviews, reports, webhooks/triggers, batch endpoints, OAuth lifecycle, customer password setting, and arbitrary raw requests.
• Functional references: n8n WooCommerce integration and WooCommerce REST API documentation.