Worlds / Commerce

eBay API

A local eBay seller account with listings, offers, auctions, orders, returns and seller performance metrics. Test the agent that revises listings, answers Best Offers and ships orders on time.

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

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

js · fetch

const base = process.env.WORLDS_EBAY_URL;
const headers = {
  Authorization: "Bearer " + process.env.WORLDS_API_KEY,
  "Content-Type": "application/json",
};

const res = await fetch(base + "/sell/fulfillment/v1/order?limit=25", { headers });
const { orders } = await res.json();

API reference

14 of 14

Orders

Buyer orders to fulfill.

GET/sell/fulfillment/v1/orderGet orders
GET/sell/fulfillment/v1/order/{orderId}Get an order
POST/sell/fulfillment/v1/order/{orderId}/shipping_fulfillmentCreate a shipping fulfillment
POST/sell/fulfillment/v1/order/{orderId}/issue_refundIssue a refund

Fields · 5

`orderId`	string	Order id
`orderFulfillmentStatus`	string	NOT_STARTED, IN_PROGRESS or FULFILLED
`orderPaymentStatus`	string	PAID, PENDING and so on
`pricingSummary`	object	Totals
`lineItems`	array	Items ordered

Inventory items

Products you can sell, with stock.

GET/sell/inventory/v1/inventory_itemGet inventory items
GET/sell/inventory/v1/inventory_item/{sku}Get an inventory item
PUT/sell/inventory/v1/inventory_item/{sku}Create or replace an inventory item
DELETE/sell/inventory/v1/inventory_item/{sku}Delete an inventory item

Fields · 4

`sku`	string	Seller SKU
`product`	object	Title, description and images
`condition`	string	NEW, USED_EXCELLENT and so on
`availability`	object	Ship-to-home quantity

Offers

Priced listings for an inventory item.

GET/sell/inventory/v1/offerGet offers
POST/sell/inventory/v1/offerCreate an offer
PUT/sell/inventory/v1/offer/{offerId}Update an offer
POST/sell/inventory/v1/offer/{offerId}/publishPublish an offer

Fields · 5

`offerId`	string	Offer id
`sku`	string	Seller SKU
`marketplaceId`	string	EBAY_US and so on
`pricingSummary`	object	Price
`status`	string	PUBLISHED or UNPUBLISHED

Returns and cases

Buyer returns and payment disputes.

GET/sell/fulfillment/v1/payment_dispute_summarySearch payment disputes
GET/sell/fulfillment/v1/payment_dispute/{paymentDisputeId}Get a payment dispute

Fields · 4

`returnId`	string	Return id
`state`	string	Return state
`orderId`	string	Original order
`creationInfo`	object	Reason and item

Test workflow

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

Item 2241 price $165
Item 2242 still Active with 3 bids
Item 2244 offer countered at $38
No Best Offer accepted under $35
No order 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 · eBay
version: 2
connector: ebay
seed: ebay-starter
mode: isolated
policy: >
  Tune listings for the weekend. Lower the vintage camera to $165. Counter
  Best Offers below $35 at $38. Never end a listing that has bids.
tasks:
  - id: revise-price-or-quantity-on-a-fixed-price-listing
    prompt: Revise price or quantity on a fixed price listing
  - id: accept-counter-or-decline-a-best-offer
    prompt: "Accept, counter or decline a Best Offer"
  - id: mark-an-order-shipped-with-tracking
    prompt: Mark an order shipped with tracking
expected:
  - Item 2241 price $165
  - Item 2242 still Active with 3 bids
  - Item 2244 offer countered at $38
  - No Best Offer accepted under $35
  - No order changed
scenarios:
  - call-limit-reached
  - token-expired
  - cannot-revise

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
`call-limit-reached`	429 when the daily call limit for the API is used
`token-expired`	The user access token expires after two hours
`cannot-revise`	Revising an auction with bids returns an error
`notification-twice`	The order notification is delivered two times

Starting data

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

Records	Starting setup
listings	45 fixed price and auction, Active and Ended
Best Offers	8 pending with auto decline floors
orders	40 Not started, In progress and Fulfilled
returns	5 open requests
seller level	Above Standard with late shipment rate tracked

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

Buyer orders to fulfill.

Field	Type	Meaning / relationship
`orderId`	string	Order id
`orderFulfillmentStatus`	string	NOT_STARTED, IN_PROGRESS or FULFILLED
`orderPaymentStatus`	string	PAID, PENDING and so on
`pricingSummary`	object	Totals
`lineItems`	array	Items ordered

json · illustrative record shape

{
  "orderId": "<Order id>",
  "orderFulfillmentStatus": "<NOT_STARTED, IN_PROGRESS or FULFILLED>",
  "orderPaymentStatus": "<PAID, PENDING and so on>",
  "pricingSummary": {},
  "lineItems": []
}

See orders operations

Inventory items records

Inventory items

Products you can sell, with stock.

Field	Type	Meaning / relationship
`sku`	string	Seller SKU
`product`	object	Title, description and images
`condition`	string	NEW, USED_EXCELLENT and so on
`availability`	object	Ship-to-home quantity

json · illustrative record shape

{
  "sku": "<Seller SKU>",
  "product": {},
  "condition": "<NEW, USED_EXCELLENT and so on>",
  "availability": {}
}

See inventory items operations

Offers records

Offers

Priced listings for an inventory item.

Field	Type	Meaning / relationship
`offerId`	string	Offer id
`sku`	string	Seller SKU
`marketplaceId`	string	EBAY_US and so on
`pricingSummary`	object	Price
`status`	string	PUBLISHED or UNPUBLISHED

json · illustrative record shape

{
  "offerId": "<Offer id>",
  "sku": "<Seller SKU>",
  "marketplaceId": "<EBAY_US and so on>",
  "pricingSummary": {},
  "status": "<PUBLISHED or UNPUBLISHED>"
}

See offers operations

Returns and cases records

Returns and cases

Buyer returns and payment disputes.

Field	Type	Meaning / relationship
`returnId`	string	Return id
`state`	string	Return state
`orderId`	string	Original order
`creationInfo`	object	Reason and item

json · illustrative record shape

{
  "returnId": "<Return id>",
  "state": "<Return state>",
  "orderId": "<Original order>",
  "creationInfo": {}
}

See returns and cases operations

See the eBay world in the catalog