Commerce

The commerce routes hold a product catalog per agent and let the caller build a basket, place it as an order, and move that order through its statuses. They are the REST twin of the Products, Baskets, and Orders runtime objects. Baskets and orders belong to the end user the credential identifies. Verified against lua-cli 3.33.0.

Base URL and authentication

Reads need commerce:read and writes commerce:write on the agent; the host, the bearer header, and the error envelope are on the REST API overview.

Response envelope

Basket and order routes, and product search and read by id, answer { "success", "message", "data" }. A record that does not exist answers with the route’s normal status, 200 or 201 on a POST, and success: false with a message such as Basket with ID '<id>' not found for agent '<id>'; a failed precondition, such as ordering an empty basket, does the same. Check success before reading data. Product create, update, and delete answer their own small objects, listed with each route. A basket is { id, userId, agentId, data: { currency, items, createdAt, metadata }, common: { status, totalAmount, itemCount } }; its status is one of active, checked_out, abandoned, expired. An order is { id, userId, agentId, data: { basketId, ... }, common: { status, ... } } with a status of pending, confirmed, fullfilled (spelled with two l’s), or cancelled.

Endpoints

GET /developer/agents/:agentId/products

Lists products, one page at a time.

string

required

The agent.

integer

default:"1"

Page number from 1.

integer

default:"10"

From 1 to 100; larger values are clamped.

string

default:"createdAt"

createdAt or productId; anything else answers 400.

string

default:"desc"

asc or desc.

string

A JSON Lua Query over the product fields: dot notation, $eq, $ne, $gt, $gte, $lt, $lte, $in, $nin, $exists, and $and or $or at the root.

Response 200 with

{ "success": true, "data": [...products], "pagination": { currentPage, totalPages, totalCount, limit, hasNextPage, hasPrevPage, nextPage, prevPage } }

. Errors

Status	Code or message	Meaning	Fix
`400`	A filter validation message	`filter` is not valid JSON or uses an operator outside the grammar	Fix the filter
`400`	`sortBy must be one of createdAt or productId`	Unknown sort field	Use one of the two
`400`	`Pagination offset may not exceed 100000`	`(page - 1) × limit` is over 100,000	Narrow the filter

Equivalent: Products.get(1, 10).

const params = new URLSearchParams({ filter: JSON.stringify({ category: 'coffee', price: { $lte: 10 } }), limit: '20' });
const response = await fetch(`https://api.heylua.ai/developer/agents/<<YOUR_AGENT_ID>>/products?${params}`, {
  headers: { Authorization: 'Bearer <<YOUR_API_KEY>>' },
});
const page: { success: boolean; data: Array<{ id: string }>; pagination: { totalCount: number } } = await response.json();
console.log(page.pagination.totalCount);

curl -G "https://api.heylua.ai/developer/agents/<<YOUR_AGENT_ID>>/products" \
  -H "Authorization: Bearer <<YOUR_API_KEY>>" \
  --data-urlencode 'filter={"category":"coffee","price":{"$lte":10}}' --data-urlencode 'limit=20'

GET /developer/agents/:agentId/products/search

Searches the catalog by text.

string

required

The agent.

string

required

The search text.

integer

default:"5"

Maximum number of products.

Response 200 with { "success": true, "message": "Successfully found <n> products for \"<query>\"", "data": [...products] }. Equivalent: Products.search('coffee').

const params = new URLSearchParams({ searchQuery: 'oat flat white', limit: '5' });
const response = await fetch(`https://api.heylua.ai/developer/agents/<<YOUR_AGENT_ID>>/products/search?${params}`, {
  headers: { Authorization: 'Bearer <<YOUR_API_KEY>>' },
});
const found: { success: boolean; data: Array<{ id: string; name?: string }> } = await response.json();
for (const product of found.data) console.log(product.id, product.name);

curl -G "https://api.heylua.ai/developer/agents/<<YOUR_AGENT_ID>>/products/search" \
  -H "Authorization: Bearer <<YOUR_API_KEY>>" \
  --data-urlencode 'searchQuery=oat flat white' --data-urlencode 'limit=5'

POST /developer/agents/:agentId/products

Creates a product, or updates it when the id exists.

string

required

The agent.

string

required

Your product id.

any

Any other fields: name, price, description, images, categories. The catalog does not enforce a schema.

Response 201 with { "updated", "isNew", "product" }: isNew: true on a create, updated: true on an update. Equivalent: Products.create({ id: 'flat-white', name: 'Flat white', price: 3.5 }).

const response = await fetch('https://api.heylua.ai/developer/agents/<<YOUR_AGENT_ID>>/products', {
  method: 'POST',
  headers: { Authorization: 'Bearer <<YOUR_API_KEY>>', 'Content-Type': 'application/json' },
  body: JSON.stringify({ id: 'flat-white', name: 'Flat white', price: 3.5, category: 'coffee' }),
});
const saved: { updated: boolean; isNew: boolean; product?: { id: string } } = await response.json();
console.log(saved.isNew ? 'created' : 'updated');

curl -X POST "https://api.heylua.ai/developer/agents/<<YOUR_AGENT_ID>>/products" \
  -H "Authorization: Bearer <<YOUR_API_KEY>>" \
  -H "Content-Type: application/json" \
  -d '{ "id": "flat-white", "name": "Flat white", "price": 3.5, "category": "coffee" }'

PUT /developer/agents/:agentId/products

Updates a product by its id; the body and answer are the same as POST, with status 200. Unlike POST, it does not create: a missing product answers { "updated": false, "isNew": false }.

GET /developer/agents/:agentId/products/:productId

Returns one product as { "success", "message", "data" }; a missing product answers 200 with success: false. Equivalent: Products.getById('flat-white').

DELETE /developer/agents/:agentId/products/:productId

Deletes a product and answers { "deleted": true }. Equivalent: Products.delete('flat-white').

POST /developer/agents/:agentId/basket

Creates an empty, active basket for the caller.

string

required

The agent.

string

required

ISO currency code, for example USD.

object

Anything you want stored on the basket.

Response 201 with { "success": true, "message": "Basket created successfully", "data": <basket> }; totalAmount and itemCount start at 0. Equivalent: Baskets.create({ currency: 'USD' }).

const response = await fetch('https://api.heylua.ai/developer/agents/<<YOUR_AGENT_ID>>/basket', {
  method: 'POST',
  headers: { Authorization: 'Bearer <<YOUR_API_KEY>>', 'Content-Type': 'application/json' },
  body: JSON.stringify({ currency: 'USD', metadata: { source: 'web' } }),
});
const created: { success: boolean; data: { id: string; common: { status: string } } } = await response.json();
console.log(created.data.id);

curl -X POST "https://api.heylua.ai/developer/agents/<<YOUR_AGENT_ID>>/basket" \
  -H "Authorization: Bearer <<YOUR_API_KEY>>" \
  -H "Content-Type: application/json" \
  -d '{ "currency": "USD", "metadata": { "source": "web" } }'

GET /developer/agents/:agentId/basket/user

Lists the caller’s baskets.

string

Only baskets in this status: active, checked_out, abandoned, expired.

Response 200 with { "success": true, "message": "Found <n> baskets for user", "data": [...baskets] }. Equivalent: Baskets.get('active').

GET /developer/agents/:agentId/basket/:basketId

Returns one basket as { "success", "message", "data" }. Equivalent: Baskets.getById('<basketId>').

POST /developer/agents/:agentId/basket/:basketId/item

Adds an item, or raises its quantity when an item with the same id is already in the basket, and recomputes the totals.

string

required

The basket.

string

required

Product id.

number

required

Unit price in the basket’s currency.

number

required

Units to add; defaults to 1 when omitted.

any

Any other fields are stored on the item.

Response 201 with { "success": true, "message": "Item added to basket successfully", "data": <basket> }, where common.totalAmount is the sum of price times quantity over the items and common.itemCount the sum of quantities. A missing basket answers 201 with success: false. Equivalent: Baskets.addItem('<basketId>', { id: 'flat-white', price: 3.5, quantity: 2 }).

const response = await fetch('https://api.heylua.ai/developer/agents/<<YOUR_AGENT_ID>>/basket/<<BASKET_ID>>/item', {
  method: 'POST',
  headers: { Authorization: 'Bearer <<YOUR_API_KEY>>', 'Content-Type': 'application/json' },
  body: JSON.stringify({ id: 'flat-white', price: 3.5, quantity: 2 }),
});
const basket: { success: boolean; data?: { common: { totalAmount: number; itemCount: number } } } = await response.json();
console.log(basket.data?.common.totalAmount);

curl -X POST "https://api.heylua.ai/developer/agents/<<YOUR_AGENT_ID>>/basket/<<BASKET_ID>>/item" \
  -H "Authorization: Bearer <<YOUR_API_KEY>>" \
  -H "Content-Type: application/json" \
  -d '{ "id": "flat-white", "price": 3.5, "quantity": 2 }'

DELETE /developer/agents/:agentId/basket/:basketId/item/:itemId

Removes the item whose id is itemId and recomputes the totals; answers the basket. Equivalent: Baskets.removeItem('<basketId>', 'flat-white').

DELETE /developer/agents/:agentId/basket/:basketId/clear

Removes every item and keeps the basket; answers the basket. Equivalent: Baskets.clear('<basketId>').

PUT /developer/agents/:agentId/basket/:basketId/metadata

Replaces the basket’s metadata with the request body.

object

required

The new metadata object itself, not wrapped in a metadata key.

Response 200 with { "success": true, "message": "Basket metadata updated successfully" }. Equivalent: Baskets.updateMetadata('<basketId>', { source: 'web' }).

PUT /developer/agents/:agentId/basket/:basketId/:status

Sets the basket’s status.

string

required

active, checked_out, abandoned, or expired.

Response 200 with { "success": true, "message": "Basket status updated to <status>", "data": <basket> }. Equivalent: Baskets.updateStatus('<basketId>', 'abandoned').

POST /developer/agents/:agentId/order

Places an order from an active, non-empty basket.

string

required

The agent.

string

required

The basket to order.

object

Shipping, billing, payment, or any other order data, stored on the order.

Response 201 with { "success": true, "message": "Order created successfully", "data": <order> }; the order starts as pending and records the basket’s userId and basketId. A basket that is not active answers 201 with success: false and Cannot create order from basket with status '<status>'. Basket must be active.; an empty one Cannot create order from empty basket. Equivalent: Baskets.placeOrder({ shipping: { ... } }, '<basketId>') or Orders.create({ basketId }).

const response = await fetch('https://api.heylua.ai/developer/agents/<<YOUR_AGENT_ID>>/order', {
  method: 'POST',
  headers: { Authorization: 'Bearer <<YOUR_API_KEY>>', 'Content-Type': 'application/json' },
  body: JSON.stringify({ basketId: '<<BASKET_ID>>', data: { pickup: 'counter' } }),
});
const placed: { success: boolean; message: string; data?: { id: string; common: { status: string } } } = await response.json();
if (!placed.success) throw new Error(placed.message);
console.log(placed.data?.id);

curl -X POST "https://api.heylua.ai/developer/agents/<<YOUR_AGENT_ID>>/order" \
  -H "Authorization: Bearer <<YOUR_API_KEY>>" \
  -H "Content-Type: application/json" \
  -d '{ "basketId": "<<BASKET_ID>>", "data": { "pickup": "counter" } }'

GET /developer/agents/:agentId/order/user

Lists the caller’s orders.

string

Only orders in this status: pending, confirmed, fullfilled, cancelled.

Response 200 with { "success": true, "message": "Found <n> orders for user", "data": [...orders] }. Equivalent: Orders.get('pending').

GET /developer/agents/:agentId/order/:orderId

Returns one order as { "success", "message", "data" }. Equivalent: Orders.getById('<orderId>').

PUT /developer/agents/:agentId/order/:orderId/:status

Sets the order’s status.

string

required

pending, confirmed, fullfilled, or cancelled.

Response 200 with { "success": true, "message": "Order status updated to <status>", "data": <order> }. Equivalent: Orders.updateStatus('confirmed', '<orderId>').

const response = await fetch('https://api.heylua.ai/developer/agents/<<YOUR_AGENT_ID>>/order/<<ORDER_ID>>/confirmed', {
  method: 'PUT',
  headers: { Authorization: 'Bearer <<YOUR_API_KEY>>' },
});
const updated: { success: boolean; message: string } = await response.json();
console.log(updated.message);

curl -X PUT "https://api.heylua.ai/developer/agents/<<YOUR_AGENT_ID>>/order/<<ORDER_ID>>/confirmed" \
  -H "Authorization: Bearer <<YOUR_API_KEY>>"

PUT /developer/agents/:agentId/order/:orderId

Merges the request body into the order’s data.

object

required

The fields to store on the order.

Response 200 with { "success": true, "message": "Order data updated successfully" }. Equivalent: Orders.updateData({ trackingNumber: '1Z999' }, '<orderId>').

SDK

CLI

REST API

Base URL and authentication

Response envelope

Endpoints

GET /developer/agents/:agentId/products

GET /developer/agents/:agentId/products/search

POST /developer/agents/:agentId/products

PUT /developer/agents/:agentId/products

GET /developer/agents/:agentId/products/:productId

DELETE /developer/agents/:agentId/products/:productId

POST /developer/agents/:agentId/basket

GET /developer/agents/:agentId/basket/user

GET /developer/agents/:agentId/basket/:basketId

POST /developer/agents/:agentId/basket/:basketId/item

DELETE /developer/agents/:agentId/basket/:basketId/item/:itemId

DELETE /developer/agents/:agentId/basket/:basketId/clear

PUT /developer/agents/:agentId/basket/:basketId/metadata

PUT /developer/agents/:agentId/basket/:basketId/:status

POST /developer/agents/:agentId/order

GET /developer/agents/:agentId/order/user

GET /developer/agents/:agentId/order/:orderId

PUT /developer/agents/:agentId/order/:orderId/:status

PUT /developer/agents/:agentId/order/:orderId

See also

​Base URL and authentication

​Response envelope

​Endpoints

​GET /developer/agents/:agentId/products

​GET /developer/agents/:agentId/products/search

​POST /developer/agents/:agentId/products

​PUT /developer/agents/:agentId/products

​GET /developer/agents/:agentId/products/:productId

​DELETE /developer/agents/:agentId/products/:productId

​POST /developer/agents/:agentId/basket

​GET /developer/agents/:agentId/basket/user

​GET /developer/agents/:agentId/basket/:basketId

​POST /developer/agents/:agentId/basket/:basketId/item

​DELETE /developer/agents/:agentId/basket/:basketId/item/:itemId

​DELETE /developer/agents/:agentId/basket/:basketId/clear

​PUT /developer/agents/:agentId/basket/:basketId/metadata

​PUT /developer/agents/:agentId/basket/:basketId/:status

​POST /developer/agents/:agentId/order

​GET /developer/agents/:agentId/order/user

​GET /developer/agents/:agentId/order/:orderId

​PUT /developer/agents/:agentId/order/:orderId/:status

​PUT /developer/agents/:agentId/order/:orderId

​See also

Base URL and authentication

Response envelope

Endpoints

GET /developer/agents/:agentId/products

GET /developer/agents/:agentId/products/search

POST /developer/agents/:agentId/products

PUT /developer/agents/:agentId/products

GET /developer/agents/:agentId/products/:productId

DELETE /developer/agents/:agentId/products/:productId

POST /developer/agents/:agentId/basket

GET /developer/agents/:agentId/basket/user

GET /developer/agents/:agentId/basket/:basketId

POST /developer/agents/:agentId/basket/:basketId/item

DELETE /developer/agents/:agentId/basket/:basketId/item/:itemId

DELETE /developer/agents/:agentId/basket/:basketId/clear

PUT /developer/agents/:agentId/basket/:basketId/metadata

PUT /developer/agents/:agentId/basket/:basketId/:status

POST /developer/agents/:agentId/order

GET /developer/agents/:agentId/order/user

GET /developer/agents/:agentId/order/:orderId

PUT /developer/agents/:agentId/order/:orderId/:status

PUT /developer/agents/:agentId/order/:orderId

See also