Worlds / Commerce

Shopify API

A local Shopify store with products, variants, orders, fulfillments, refunds and inventory per location. Test the agent that refunds line items, cancels orders and restocks the right location.

Base path: /admin/api/2024-10
Auth: X-Shopify-Access-Token header, the world key
Endpoints: 15
Status: Active today

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

js · @shopify/admin-api-client

import { createAdminApiClient } from "@shopify/admin-api-client";

const client = createAdminApiClient({
  storeDomain: process.env.WORLDS_SHOPIFY_URL,
  apiVersion: "2024-10",
  accessToken: process.env.WORLDS_API_KEY,
});

const { data } = await client.request("{ orders(first: 5) { nodes { id name } } }");

API reference

15 of 15

Orders

Customer purchases and their payment and fulfillment state.

POST/admin/api/2024-10/graphql.json · ordersList orders
POST/admin/api/2024-10/graphql.json · orderGet an order
POST/admin/api/2024-10/graphql.json · orderUpdateUpdate an order
POST/admin/api/2024-10/graphql.json · orderCancelCancel an order
POST/admin/api/2024-10/graphql.json · refundCreateRefund an order

Fields · 6

`id`	ID	Order global id
`name`	String	Order number like #1001
`displayFinancialStatus`	enum	PAID, REFUNDED, PENDING and so on
`displayFulfillmentStatus`	enum	FULFILLED, UNFULFILLED and so on
`totalPriceSet`	MoneyBag	Order total
`customer`	Customer	Buyer

Products

Items for sale with variants.

POST/admin/api/2024-10/graphql.json · productsList products
POST/admin/api/2024-10/graphql.json · productCreateCreate a product
POST/admin/api/2024-10/graphql.json · productUpdateUpdate a product

Fields · 5

`id`	ID	Product global id
`title`	String	Title
`status`	enum	ACTIVE, DRAFT or ARCHIVED
`variants`	connection	Variants with price and sku
`totalInventory`	Int	Units in stock

Customers

People who buy from the store.

POST/admin/api/2024-10/graphql.json · customersList customers
POST/admin/api/2024-10/graphql.json · customerCreateCreate a customer
POST/admin/api/2024-10/graphql.json · customerUpdateUpdate a customer

Fields · 5

`id`	ID	Customer global id
`email`	String	Email address
`firstName`	String	First name
`numberOfOrders`	UnsignedInt64	Order count
`amountSpent`	MoneyV2	Lifetime spend

Fulfillments

Shipments sent for an order.

POST/admin/api/2024-10/graphql.json · fulfillmentCreateV2Create a fulfillment
POST/admin/api/2024-10/graphql.json · fulfillmentCancelCancel a fulfillment

Fields · 4

`id`	ID	Fulfillment global id
`status`	enum	SUCCESS, CANCELLED and so on
`trackingInfo`	array	Carrier and tracking number
`fulfillmentLineItems`	connection	Items shipped

Inventory

Stock levels per location.

POST/admin/api/2024-10/graphql.json · inventoryItemsList inventory items
POST/admin/api/2024-10/graphql.json · inventoryAdjustQuantitiesAdjust stock

Fields · 4

`id`	ID	Inventory item id
`sku`	String	Stock keeping unit
`inventoryLevels`	connection	Quantities by location
`tracked`	Boolean	Whether stock is tracked

Test workflow

Prepare. Select the Shopify 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

#1042 partially refunded for one line item
#1044 untouched
Restocked quantity added at Warehouse East
#1045 voided, no refund created
#1046 from the second Dana Lee untouched

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 · Shopify
version: 2
connector: shopify
seed: shopify-starter
mode: isolated
policy: >
  Handle today's return requests. Refund damaged items only, not the whole
  order, and restock to the location they shipped from. Void the unpaid order
  from Ortiz Labs.
tasks:
  - id: refund-one-line-item-and-restock-it
    prompt: Refund one line item and restock it
  - id: cancel-an-unfulfilled-order-with-the-right-reason
    prompt: Cancel an unfulfilled order with the right reason
  - id: adjust-inventory-at-a-single-location
    prompt: Adjust inventory at a single location
expected:
  - "#1042 partially refunded for one line item"
  - "#1044 untouched"
  - Restocked quantity added at Warehouse East
  - "#1045 voided, no refund created"
  - "#1046 from the second Dana Lee untouched"
scenarios:
  - throttled
  - user-error
  - already-fulfilled

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`	GraphQL returns THROTTLED when the cost bucket is empty
`user-error`	userErrors on refundCreate when the amount exceeds what was paid
`already-fulfilled`	The order shipped before the agent acted
`gateway-timeout`	The refund call times out once and the retry must not double refund
`webhook-twice`	orders/updated arrives two times

Starting data

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

Records	Starting setup
products	30 with 90 variants
orders	50 paid, partially refunded, refunded and pending
fulfillments	35 fulfilled, 10 unfulfilled
locations	Warehouse East and Retail Store
customers	40, two named Dana Lee

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 purchases and their payment and fulfillment state.

Field	Type	Meaning / relationship
`id`	ID	Order global id
`name`	String	Order number like #1001
`displayFinancialStatus`	enum	PAID, REFUNDED, PENDING and so on
`displayFulfillmentStatus`	enum	FULFILLED, UNFULFILLED and so on
`totalPriceSet`	MoneyBag	Order total
`customer`	Customer	Buyer

json · illustrative record shape

{
  "id": "<Order global id>",
  "name": "<Order number like #1001>",
  "displayFinancialStatus": "<PAID, REFUNDED, PENDING and so on>",
  "displayFulfillmentStatus": "<FULFILLED, UNFULFILLED and so on>",
  "totalPriceSet": "<Order total>",
  "customer": "<Buyer>"
}

See orders operations

Products records

Products

Items for sale with variants.

Field	Type	Meaning / relationship
`id`	ID	Product global id
`title`	String	Title
`status`	enum	ACTIVE, DRAFT or ARCHIVED
`variants`	connection	Variants with price and sku
`totalInventory`	Int	Units in stock

json · illustrative record shape

{
  "id": "<Product global id>",
  "title": "<Title>",
  "status": "<ACTIVE, DRAFT or ARCHIVED>",
  "variants": "<Variants with price and sku>",
  "totalInventory": 1
}

See products operations

Customers records

Customers

People who buy from the store.

Field	Type	Meaning / relationship
`id`	ID	Customer global id
`email`	String	Email address
`firstName`	String	First name
`numberOfOrders`	UnsignedInt64	Order count
`amountSpent`	MoneyV2	Lifetime spend

json · illustrative record shape

{
  "id": "<Customer global id>",
  "email": "person@example.test",
  "firstName": "<First name>",
  "numberOfOrders": "<Order count>",
  "amountSpent": "<Lifetime spend>"
}

See customers operations

Fulfillments records

Fulfillments

Shipments sent for an order.

Field	Type	Meaning / relationship
`id`	ID	Fulfillment global id
`status`	enum	SUCCESS, CANCELLED and so on
`trackingInfo`	array	Carrier and tracking number
`fulfillmentLineItems`	connection	Items shipped

json · illustrative record shape

{
  "id": "<Fulfillment global id>",
  "status": "<SUCCESS, CANCELLED and so on>",
  "trackingInfo": [],
  "fulfillmentLineItems": "<Items shipped>"
}

See fulfillments operations

Inventory records

Inventory

Stock levels per location.

Field	Type	Meaning / relationship
`id`	ID	Inventory item id
`sku`	String	Stock keeping unit
`inventoryLevels`	connection	Quantities by location
`tracked`	Boolean	Whether stock is tracked

json · illustrative record shape

{
  "id": "<Inventory item id>",
  "sku": "<Stock keeping unit>",
  "inventoryLevels": "<Quantities by location>",
  "tracked": false
}

See inventory operations

See the Shopify world in the catalog