Worlds / Commerce

WooCommerce API

A local WooCommerce store with products, stock, orders, coupons and refunds. Test the agent that moves orders through statuses, issues refunds and keeps stock counts right.

Base path: /wp-json/wc/v3
Auth: Consumer key and secret as Basic auth, the world key
Endpoints: 17
Status: Active today

This reference previews the surface the WooCommerce world serves in the closed beta. Paths mirror the public WooCommerce API; the exact subset is confirmed when your workflow is scoped.

Connect

The run gives your agent these bindings. Keep your SDK; change only where it sends requests.

binding	meaning
`WORLDS_WOOCOMMERCE_URL`	This world's origin followed by `/wp-json/wc/v3`
`WORLDS_API_KEY`	The world key, accepted wherever WooCommerce expects a credential
`WORLDS_WORLD_ID`	The isolated world's identity

js · @woocommerce/woocommerce-rest-api

import WooCommerceRestApi from "@woocommerce/woocommerce-rest-api";

const woo = new WooCommerceRestApi({
  url: process.env.WORLDS_WOOCOMMERCE_URL,
  consumerKey: process.env.WORLDS_API_KEY,
  consumerSecret: "world-secret",
  version: "wc/v3",
});

const { data } = await woo.get("orders", { per_page: 10 });

API reference

17 of 17

Orders

Customer orders.

GET/wp-json/wc/v3/ordersList orders
POST/wp-json/wc/v3/ordersCreate an order
GET/wp-json/wc/v3/orders/{id}Retrieve an order
PUT/wp-json/wc/v3/orders/{id}Update an order
DELETE/wp-json/wc/v3/orders/{id}Delete an order

Fields · 6

`id`	integer	Order id
`status`	string	pending, processing, completed, cancelled, refunded
`total`	string	Order total
`customer_id`	integer	Customer
`line_items`	array	Items ordered
`billing`	object	Billing address

Products

Items for sale.

GET/wp-json/wc/v3/productsList products
POST/wp-json/wc/v3/productsCreate a product
GET/wp-json/wc/v3/products/{id}Retrieve a product
PUT/wp-json/wc/v3/products/{id}Update a product

Fields · 6

`id`	integer	Product id
`name`	string	Name
`sku`	string	Stock keeping unit
`regular_price`	string	Regular price
`stock_quantity`	integer	Units in stock
`status`	string	draft, pending, private or publish

Customers

Registered shoppers.

GET/wp-json/wc/v3/customersList customers
POST/wp-json/wc/v3/customersCreate a customer
GET/wp-json/wc/v3/customers/{id}Retrieve a customer

Fields · 5

`id`	integer	Customer id
`email`	string	Email address
`first_name`	string	First name
`last_name`	string	Last name
`orders_count`	integer	Number of orders

Refunds

Refunds issued against an order.

GET/wp-json/wc/v3/orders/{order_id}/refundsList refunds
POST/wp-json/wc/v3/orders/{order_id}/refundsCreate a refund
GET/wp-json/wc/v3/orders/{order_id}/refunds/{id}Retrieve a refund

Fields · 4

`id`	integer	Refund id
`amount`	string	Refund amount
`reason`	string	Reason
`line_items`	array	Items refunded

Order notes

Private and customer-facing notes on an order.

GET/wp-json/wc/v3/orders/{order_id}/notesList notes
POST/wp-json/wc/v3/orders/{order_id}/notesCreate a note

Fields · 4

`id`	integer	Note id
`note`	string	Note text
`customer_note`	boolean	Visible to the customer
`date_created`	string	ISO 8601 timestamp

Test workflow

Prepare. Select the WooCommerce setup for your workflow and review its starting records, including orders, products, customers.
Connect. Configure your agent with this world's URL and key using the SDK example. Check that it reaches the intended API before running a test.
Define. Describe the task, expected final changes and records that must stay untouched. Keep expected outcomes separate from the agent's instructions.
Run and inspect. Use the dashboard or your workflow's generated CLI setup. Review final records and changes, then rerun from the same starting setup with the relevant failure conditions. Use Deployment and CI to automate the same workflow.

What to verify

#2301 Completed
#2303 Cancelled and stock restored for each line
#2304 has one $20 refund
#2302 still On hold
No coupon created

Test file

A task file names the jobs, the policy your agent is given and what the grader reads back from the world's final state. The agent never sees the expected outcomes.

yaml · worlds/tasks.yaml

# worlds/tasks.yaml · WooCommerce
version: 2
connector: woocommerce
seed: woocommerce-starter
mode: isolated
policy: >
  Clear the order queue. Complete shipped orders. Cancel Moss & Co's order and
  put the stock back. Refund $20 on Ortiz Labs for the late item, not the
  whole order.
tasks:
  - id: complete-or-cancel-orders-and-restock
    prompt: Complete or cancel orders and restock
  - id: issue-a-partial-refund-on-an-order
    prompt: Issue a partial refund on an order
  - id: create-a-coupon-with-the-right-limits
    prompt: Create a coupon with the right limits
expected:
  - "#2301 Completed"
  - "#2303 Cancelled and stock restored for each line"
  - "#2304 has one $20 refund"
  - "#2302 still On hold"
  - No coupon created
scenarios:
  - order-not-found
  - auth-failed
  - gateway-refund-fails

See Tasks and outcomes for every field, and Deployment and CI to run the file on every pull request.

Failure conditions

Each one fires before the handler, at the same step on every run.

condition	what the agent sees
`order-not-found`	404 woocommerce_rest_shop_order_invalid_id
`auth-failed`	401 woocommerce_rest_authentication_error when the key is revoked
`gateway-refund-fails`	The payment gateway rejects the refund and only a manual refund is recorded
`webhook-disabled`	order.updated is disabled after repeated delivery failures

Starting data

Start each run from the same records and relationships. The overview below describes the WooCommerce starter; use the setup supplied for your workflow when preparing your own snapshot.

Records	Starting setup
products	35 simple and variable, managed stock
orders	50 pending, processing, on-hold, completed and refunded
coupons	6 percent and fixed cart, some with usage limits
customers	40 accounts and guest orders
webhooks	order.updated and product.updated

The record shapes below reuse this world's API field definitions. They show illustrative values and placeholders, not an importable seed. API responses and seed input can differ; include all required records and references in the accepted import format for your workflow.

Orders records

Orders

Customer orders.

Field	Type	Meaning / relationship
`id`	integer	Order id
`status`	string	pending, processing, completed, cancelled, refunded
`total`	string	Order total
`customer_id`	integer	Customer
`line_items`	array	Items ordered
`billing`	object	Billing address

json · illustrative record shape

{
  "id": 1,
  "status": "<pending, processing, completed, cancelled, refunded>",
  "total": "<Order total>",
  "customer_id": 1,
  "line_items": [],
  "billing": {}
}

See orders operations

Products records

Products

Items for sale.

Field	Type	Meaning / relationship
`id`	integer	Product id
`name`	string	Name
`sku`	string	Stock keeping unit
`regular_price`	string	Regular price
`stock_quantity`	integer	Units in stock
`status`	string	draft, pending, private or publish

json · illustrative record shape

{
  "id": 1,
  "name": "<Name>",
  "sku": "<Stock keeping unit>",
  "regular_price": "<Regular price>",
  "stock_quantity": 1,
  "status": "<draft, pending, private or publish>"
}

See products operations

Customers records

Customers

Registered shoppers.

Field	Type	Meaning / relationship
`id`	integer	Customer id
`email`	string	Email address
`first_name`	string	First name
`last_name`	string	Last name
`orders_count`	integer	Number of orders

json · illustrative record shape

{
  "id": 1,
  "email": "person@example.test",
  "first_name": "<First name>",
  "last_name": "<Last name>",
  "orders_count": 1
}

See customers operations

Refunds records

Refunds

Refunds issued against an order.

Field	Type	Meaning / relationship
`id`	integer	Refund id
`amount`	string	Refund amount
`reason`	string	Reason
`line_items`	array	Items refunded

json · illustrative record shape

{
  "id": 1,
  "amount": "<Refund amount>",
  "reason": "<Reason>",
  "line_items": []
}

See refunds operations

Order notes records

Order notes

Private and customer-facing notes on an order.

Field	Type	Meaning / relationship
`id`	integer	Note id
`note`	string	Note text
`customer_note`	boolean	Visible to the customer
`date_created`	string	ISO 8601 timestamp

json · illustrative record shape

{
  "id": 1,
  "note": "<Note text>",
  "customer_note": false,
  "date_created": "<ISO 8601 timestamp>"
}

See order notes operations

See the WooCommerce world in the catalog