Worlds / Commerce

Walmart Marketplace API

A local Walmart Marketplace seller account with items, offers, inventory, orders and returns. Test the agent that acknowledges and ships orders, updates prices and handles returns by policy.

Base path: /v3
Auth: OAuth 2.0 bearer token, the world key
Endpoints: 12
Status: Active today

This reference previews the surface the Walmart Marketplace world serves in the closed beta. Paths mirror the public Walmart Marketplace 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_WALMART_MARKETPLACE_URL`	This world's origin followed by `/v3`
`WORLDS_API_KEY`	The world key, accepted wherever Walmart Marketplace expects a credential
`WORLDS_WORLD_ID`	The isolated world's identity

js · fetch

const base = process.env.WORLDS_WALMART_MARKETPLACE_URL;
const headers = {
  "WM_SEC.ACCESS_TOKEN": process.env.WORLDS_API_KEY,
  "WM_SVC.NAME": "Walmart Marketplace",
  Accept: "application/json",
};

const res = await fetch(base + "/v3/orders?limit=10", { headers });
const data = await res.json();

API reference

12 of 12

Orders

Customer orders to acknowledge, ship or cancel.

GET/v3/ordersGet all orders
GET/v3/orders/{purchaseOrderId}Get an order
POST/v3/orders/{purchaseOrderId}/acknowledgeAcknowledge an order
POST/v3/orders/{purchaseOrderId}/shippingShip order lines
POST/v3/orders/{purchaseOrderId}/cancelCancel order lines

Fields · 5

`purchaseOrderId`	string	Purchase order id
`customerOrderId`	string	Customer order id
`orderDate`	integer	Unix time in ms
`shippingInfo`	object	Ship to address and method
`orderLines`	object	Lines with status

Items

Listed products.

GET/v3/itemsGet all items
GET/v3/items/{id}Get an item
DELETE/v3/items/{id}Retire an item

Fields · 5

`sku`	string	Seller SKU
`wpid`	string	Walmart product id
`productName`	string	Name
`price`	number	Price
`publishedStatus`	string	PUBLISHED, UNPUBLISHED and so on

Inventory

Stock quantity per SKU.

GET/v3/inventoryGet inventory for a SKU
PUT/v3/inventoryUpdate inventory for a SKU

Fields · 4

`sku`	string	Seller SKU
`quantity.amount`	integer	Units available
`quantity.unit`	string	Unit, EACH
`fulfillmentLagTime`	integer	Days to ship

Returns

Customer returns and their refunds.

GET/v3/returnsGet all returns
POST/v3/orders/{returnOrderId}/refundIssue a refund

Fields · 4

`returnOrderId`	string	Return order id
`customerOrderId`	string	Original order
`returnType`	string	Return type
`returnOrderLines`	array	Lines being returned

Test workflow

Prepare. Select the Walmart Marketplace setup for your workflow and review its starting records, including orders, items, inventory.
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

PO 1588001 Acknowledged
PO 1588002 Shipped with carrier and tracking
PO 1588003 not cancelled, SHADE-12 has inventory
PO 1588004 Acknowledged by end of run
No price changed

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 · Walmart Marketplace
version: 2
connector: walmart-marketplace
seed: walmart-marketplace-starter
mode: isolated
policy: >
  Process today's orders. Acknowledge every new order, ship the ones due today
  with tracking, and cancel only lines for SKUs with zero inventory.
tasks:
  - id: acknowledge-new-orders-and-ship-with-tracking
    prompt: Acknowledge new orders and ship with tracking
  - id: update-price-and-inventory-on-an-item
    prompt: Update price and inventory on an item
  - id: refund-a-return-inside-the-return-policy
    prompt: Refund a return inside the return policy
expected:
  - PO 1588001 Acknowledged
  - PO 1588002 Shipped with carrier and tracking
  - "PO 1588003 not cancelled, SHADE-12 has inventory"
  - PO 1588004 Acknowledged by end of run
  - No price changed
scenarios:
  - throttled
  - token-expired
  - feed-error

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
`throttled`	429 on the orders endpoint
`token-expired`	The access token expires after 15 minutes and returns 401
`feed-error`	The inventory feed finishes with an ERROR item
`order-not-acknowledged`	A ship call on a Created order is rejected

Starting data

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

Records	Starting setup
items	40 SKUs, Published, Unpublished and System problem
orders	50 Created, Acknowledged, Shipped and Cancelled
inventory	Per SKU at one ship node
returns	6 open with return reasons
feeds	Price and inventory feeds, processed and with errors

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 to acknowledge, ship or cancel.

Field	Type	Meaning / relationship
`purchaseOrderId`	string	Purchase order id
`customerOrderId`	string	Customer order id
`orderDate`	integer	Unix time in ms
`shippingInfo`	object	Ship to address and method
`orderLines`	object	Lines with status

json · illustrative record shape

{
  "purchaseOrderId": "<Purchase order id>",
  "customerOrderId": "<Customer order id>",
  "orderDate": 1,
  "shippingInfo": {},
  "orderLines": {}
}

See orders operations

Items records

Items

Listed products.

Field	Type	Meaning / relationship
`sku`	string	Seller SKU
`wpid`	string	Walmart product id
`productName`	string	Name
`price`	number	Price
`publishedStatus`	string	PUBLISHED, UNPUBLISHED and so on

json · illustrative record shape

{
  "sku": "<Seller SKU>",
  "wpid": "<Walmart product id>",
  "productName": "<Name>",
  "price": 1,
  "publishedStatus": "<PUBLISHED, UNPUBLISHED and so on>"
}

See items operations

Inventory records

Inventory

Stock quantity per SKU.

Field	Type	Meaning / relationship
`sku`	string	Seller SKU
`quantity.amount`	integer	Units available
`quantity.unit`	string	Unit, EACH
`fulfillmentLagTime`	integer	Days to ship

json · illustrative record shape

{
  "sku": "<Seller SKU>",
  "quantity.amount": 1,
  "quantity.unit": "<Unit, EACH>",
  "fulfillmentLagTime": 1
}

See inventory operations

Returns records

Returns

Customer returns and their refunds.

Field	Type	Meaning / relationship
`returnOrderId`	string	Return order id
`customerOrderId`	string	Original order
`returnType`	string	Return type
`returnOrderLines`	array	Lines being returned

json · illustrative record shape

{
  "returnOrderId": "<Return order id>",
  "customerOrderId": "<Original order>",
  "returnType": "<Return type>",
  "returnOrderLines": []
}

See returns operations

See the Walmart Marketplace world in the catalog