Worlds / Commerce

BigCommerce API

A local BigCommerce store with catalog products, variants, channels, carts, orders and shipments. Test the agent that updates catalog data, manages channel listings and moves orders to shipped.

Base path: /stores/{store_hash}
Auth: X-Auth-Token header, the world key
Endpoints: 14
Status: Active today

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

js · fetch

const base = process.env.WORLDS_BIGCOMMERCE_URL;
const headers = {
  "X-Auth-Token": process.env.WORLDS_API_KEY,
  Accept: "application/json",
};

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

API reference

14 of 14

Products

Catalog items.

GET/stores/{store_hash}/v3/catalog/productsGet all products
POST/stores/{store_hash}/v3/catalog/productsCreate a product
GET/stores/{store_hash}/v3/catalog/products/{product_id}Get a product
PUT/stores/{store_hash}/v3/catalog/products/{product_id}Update a product
DELETE/stores/{store_hash}/v3/catalog/products/{product_id}Delete a product

Fields · 6

`id`	integer	Product id
`name`	string	Name
`sku`	string	Stock keeping unit
`price`	number	Price
`inventory_level`	integer	Units in stock
`is_visible`	boolean	Shown on the storefront

Orders

Customer orders (v2 API).

GET/stores/{store_hash}/v2/ordersList orders
POST/stores/{store_hash}/v2/ordersCreate an order
GET/stores/{store_hash}/v2/orders/{order_id}Get an order
PUT/stores/{store_hash}/v2/orders/{order_id}Update an order

Fields · 5

`id`	integer	Order id
`status_id`	integer	Order status id
`total_inc_tax`	string	Total with tax
`customer_id`	integer	Customer
`date_created`	string	RFC 2822 date

Customers

Shoppers with accounts.

GET/stores/{store_hash}/v3/customersGet all customers
POST/stores/{store_hash}/v3/customersCreate customers
PUT/stores/{store_hash}/v3/customersUpdate customers

Fields · 5

`id`	integer	Customer id
`email`	string	Email address
`first_name`	string	First name
`last_name`	string	Last name
`customer_group_id`	integer	Group

Order shipments

Shipments sent for an order.

GET/stores/{store_hash}/v2/orders/{order_id}/shipmentsList shipments
POST/stores/{store_hash}/v2/orders/{order_id}/shipmentsCreate a shipment

Fields · 5

`id`	integer	Shipment id
`order_id`	integer	Order
`tracking_number`	string	Tracking number
`shipping_provider`	string	Carrier
`items`	array	Items shipped

Test workflow

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

#100231 Shipped with a tracking number
#100233 still Awaiting Payment
#100234 Partially Shipped for in stock items
No variant price changed
Channel listings unchanged

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 · BigCommerce
version: 2
connector: bigcommerce
seed: bigcommerce-starter
mode: isolated
policy: >
  Ship today's paid orders. Create shipments with tracking only for orders in
  Awaiting Fulfillment. Ortiz Labs gets a partial shipment for the items in
  stock.
tasks:
  - id: update-price-or-inventory-on-a-variant
    prompt: Update price or inventory on a variant
  - id: list-or-unlist-a-product-on-a-channel
    prompt: List or unlist a product on a channel
  - id: create-a-shipment-and-move-the-order-to-shipped
    prompt: Create a shipment and move the order to Shipped
expected:
  - "#100231 Shipped with a tracking number"
  - "#100233 still Awaiting Payment"
  - "#100234 Partially Shipped for in stock items"
  - No variant price changed
  - Channel listings unchanged
scenarios:
  - rate-limited
  - validation-error
  - token-revoked

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
`rate-limited`	429 with X-Rate-Limit-Time-Reset-Ms
`validation-error`	422 when the shipment quantity exceeds the order line
`token-revoked`	401 when the store API account is removed
`webhook-twice`	store/order/statusUpdated arrives two times

Starting data

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

Records	Starting setup
products	40 with 120 variants and categories
channels	Storefront, a marketplace channel and a POS channel
orders	50 across Awaiting Payment, Awaiting Fulfillment, Shipped and Refunded
carts	15 abandoned carts
price lists	Wholesale and Retail

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.

Products records

Products

Catalog items.

Field	Type	Meaning / relationship
`id`	integer	Product id
`name`	string	Name
`sku`	string	Stock keeping unit
`price`	number	Price
`inventory_level`	integer	Units in stock
`is_visible`	boolean	Shown on the storefront

json · illustrative record shape

{
  "id": 1,
  "name": "<Name>",
  "sku": "<Stock keeping unit>",
  "price": 1,
  "inventory_level": 1,
  "is_visible": false
}

See products operations

Orders records

Orders

Customer orders (v2 API).

Field	Type	Meaning / relationship
`id`	integer	Order id
`status_id`	integer	Order status id
`total_inc_tax`	string	Total with tax
`customer_id`	integer	Customer
`date_created`	string	RFC 2822 date

json · illustrative record shape

{
  "id": 1,
  "status_id": 1,
  "total_inc_tax": "<Total with tax>",
  "customer_id": 1,
  "date_created": "<RFC 2822 date>"
}

See orders operations

Customers records

Customers

Shoppers with accounts.

Field	Type	Meaning / relationship
`id`	integer	Customer id
`email`	string	Email address
`first_name`	string	First name
`last_name`	string	Last name
`customer_group_id`	integer	Group

json · illustrative record shape

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

See customers operations

Order shipments records

Order shipments

Shipments sent for an order.

Field	Type	Meaning / relationship
`id`	integer	Shipment id
`order_id`	integer	Order
`tracking_number`	string	Tracking number
`shipping_provider`	string	Carrier
`items`	array	Items shipped

json · illustrative record shape

{
  "id": 1,
  "order_id": 1,
  "tracking_number": "<Tracking number>",
  "shipping_provider": "<Carrier>",
  "items": []
}

See order shipments operations

See the BigCommerce world in the catalog