Worlds / Commerce

Amazon Seller Central API

A local Seller Central account with listings, FBA inventory, orders, returns and account health metrics. Test the agent that confirms shipments, updates listings and handles returns without hurting account health.

Base path: /
Auth: LWA access token in x-amz-access-token, the world key
Endpoints: 13
Status: Active today

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

js · fetch

const base = process.env.WORLDS_AMAZON_SELLER_CENTRAL_URL;
const headers = { "x-amz-access-token": process.env.WORLDS_API_KEY };

const res = await fetch(
  base + "/orders/v0/orders?MarketplaceIds=ATVPDKIKX0DER&CreatedAfter=2025-01-01T00:00:00Z",
  { headers }
);
const { payload } = await res.json();

API reference

13 of 13

Orders

Customer orders on the marketplace.

GET/orders/v0/ordersGet orders
GET/orders/v0/orders/{orderId}Get an order
GET/orders/v0/orders/{orderId}/orderItemsGet order items

Fields · 5

`AmazonOrderId`	string	Order id
`OrderStatus`	string	Pending, Unshipped, Shipped, Canceled
`PurchaseDate`	string	ISO 8601 timestamp
`OrderTotal`	object	Currency and amount
`FulfillmentChannel`	string	AFN or MFN

Listings

Seller offers for a product.

GET/listings/2021-08-01/items/{sellerId}/{sku}Get a listing
PUT/listings/2021-08-01/items/{sellerId}/{sku}Create or replace a listing
PATCH/listings/2021-08-01/items/{sellerId}/{sku}Update a listing
DELETE/listings/2021-08-01/items/{sellerId}/{sku}Delete a listing

Fields · 5

`sku`	string	Seller SKU
`productType`	string	Product type
`summaries`	array	Status and ASIN
`attributes`	object	Listing attributes
`issues`	array	Validation issues

FBA inventory

Stock held in fulfillment centers.

GET/fba/inventory/v1/summariesGet inventory summaries

Fields · 4

`sellerSku`	string	Seller SKU
`asin`	string	ASIN
`totalQuantity`	integer	Units on hand
`fulfillableQuantity`	integer	Units available to ship

Feeds

Bulk uploads for listings, prices and shipments.

POST/feeds/2021-06-30/feedsCreate a feed
GET/feeds/2021-06-30/feeds/{feedId}Get a feed
POST/feeds/2021-06-30/documentsCreate a feed document

Fields · 4

`feedId`	string	Feed id
`feedType`	string	Feed type
`processingStatus`	string	IN_QUEUE, DONE, FATAL and so on
`resultFeedDocumentId`	string	Result document

Catalog

Product details by ASIN.

GET/catalog/2022-04-01/itemsSearch catalog items
GET/catalog/2022-04-01/items/{asin}Get a catalog item

Fields · 4

`asin`	string	ASIN
`summaries`	array	Brand, name and classification
`images`	array	Product images
`salesRanks`	array	Sales ranks

Test workflow

Prepare. Select the Amazon Seller Central setup for your workflow and review its starting records, including orders, listings, fba 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

112-0041-771 Shipped with UPS tracking
112-0041-773 has a valid tracking number or is still Unshipped
112-0041-775 canceled with reason Buyer canceled
112-0041-774 still Pending
Valid tracking rate 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 · Amazon Seller Central
version: 2
connector: amazon-seller-central
seed: amazon-seller-central-starter
mode: isolated
policy: >
  Ship today's merchant fulfilled orders. Confirm every shipment with carrier
  and tracking. Cancel only what the buyer asked to cancel, with reason Buyer
  canceled. Do not touch Pending orders.
tasks:
  - id: confirm-shipment-with-carrier-and-tracking
    prompt: Confirm shipment with carrier and tracking
  - id: update-price-and-quantity-on-a-listing
    prompt: Update price and quantity on a listing
  - id: approve-or-close-a-return-request
    prompt: Approve or close a return request
expected:
  - 112-0041-771 Shipped with UPS tracking
  - 112-0041-773 has a valid tracking number or is still Unshipped
  - 112-0041-775 canceled with reason Buyer canceled
  - 112-0041-774 still Pending
  - Valid tracking rate unchanged
scenarios:
  - quota-exceeded
  - token-expired
  - invalid-input

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
`quota-exceeded`	429 QuotaExceeded on the orders operation
`token-expired`	The LWA access token expires after an hour and returns 403
`invalid-input`	400 InvalidInput on a malformed tracking number
`feed-error`	The listings feed finishes with errors on 2 SKUs
`listing-suppressed`	A price change trips the pricing check and suppresses the listing

Starting data

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

Records	Starting setup
listings	40 SKUs mapped to ASINs, Active, Inactive and Suppressed
FBA inventory	Fulfillable, inbound and reserved units
orders	60 merchant fulfilled and FBA, Pending, Unshipped and Shipped
returns	8 authorized and pending
account health	Order defect rate, late shipment rate, valid tracking rate

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 on the marketplace.

Field	Type	Meaning / relationship
`AmazonOrderId`	string	Order id
`OrderStatus`	string	Pending, Unshipped, Shipped, Canceled
`PurchaseDate`	string	ISO 8601 timestamp
`OrderTotal`	object	Currency and amount
`FulfillmentChannel`	string	AFN or MFN

json · illustrative record shape

{
  "AmazonOrderId": "<Order id>",
  "OrderStatus": "<Pending, Unshipped, Shipped, Canceled>",
  "PurchaseDate": "<ISO 8601 timestamp>",
  "OrderTotal": {},
  "FulfillmentChannel": "<AFN or MFN>"
}

See orders operations

Listings records

Listings

Seller offers for a product.

Field	Type	Meaning / relationship
`sku`	string	Seller SKU
`productType`	string	Product type
`summaries`	array	Status and ASIN
`attributes`	object	Listing attributes
`issues`	array	Validation issues

json · illustrative record shape

{
  "sku": "<Seller SKU>",
  "productType": "<Product type>",
  "summaries": [],
  "attributes": {},
  "issues": []
}

See listings operations

FBA inventory records

FBA inventory

Stock held in fulfillment centers.

Field	Type	Meaning / relationship
`sellerSku`	string	Seller SKU
`asin`	string	ASIN
`totalQuantity`	integer	Units on hand
`fulfillableQuantity`	integer	Units available to ship

json · illustrative record shape

{
  "sellerSku": "<Seller SKU>",
  "asin": "<ASIN>",
  "totalQuantity": 1,
  "fulfillableQuantity": 1
}

See fba inventory operations

Feeds records

Feeds

Bulk uploads for listings, prices and shipments.

Field	Type	Meaning / relationship
`feedId`	string	Feed id
`feedType`	string	Feed type
`processingStatus`	string	IN_QUEUE, DONE, FATAL and so on
`resultFeedDocumentId`	string	Result document

json · illustrative record shape

{
  "feedId": "<Feed id>",
  "feedType": "<Feed type>",
  "processingStatus": "<IN_QUEUE, DONE, FATAL and so on>",
  "resultFeedDocumentId": "<Result document>"
}

See feeds operations

Catalog records

Catalog

Product details by ASIN.

Field	Type	Meaning / relationship
`asin`	string	ASIN
`summaries`	array	Brand, name and classification
`images`	array	Product images
`salesRanks`	array	Sales ranks

json · illustrative record shape

{
  "asin": "<ASIN>",
  "summaries": [],
  "images": [],
  "salesRanks": []
}

See catalog operations

See the Amazon Seller Central world in the catalog