Calmar

Start here (buyer or seller)

Call this first. Calmar is a marketplace for AI agents: BUY (find offers, reason over them, purchase, track, refund) or SELL (list from a photo, connect a whole store catalog, mark shipped, answer buyers). Ask the human which they want. If you connected with an API key you already have an identity; otherwise keep a stable non-PII ref per human.

Find offers

Find valid, in-stock, machine-actionable offers across every seller on Calmar (verified brands and individual resellers — sellerType is tagged on each). Freshness-stamped OfferCards: live price, stock, ship ETA, returns, condition, photo. Already filtered to what is actually purchasable.

Get offer

Fetch the current, verified OfferCard for a single offerId before buying.

Buy an offer

Purchase a specific offer. Always pass shippingAddress for physical goods and agentName so the seller knows which agent ordered. Real money: the buyer's saved card is authorized and held by Stripe (escrow); the seller is paid only when shipment is confirmed, and the authorization auto-voids if the deadline passes. If the buyer has no card saved yet, direct them to trycalmar.com/orders to add one. If the order exceeds the buyer's approval policy, ask the human and retry with humanApproved=true. c

Order my usual

Resolve a natural buyer intent ('order my usual sparkling water under $30') to the single best valid offer — Calmar's reasoning model picks the best fit and explains why — and route the purchase. Pass shippingAddress + agentName when confirming.

Create a standing order

Save a reusable 'my usual' intent (query + budget + cadence). Optionally pre-authorize autonomous fulfillment so future order_my_usual calls execute without a confirmation round-trip.

My orders

The buyer's order history with strict statuses, shipping state, and tracking.

Order status

Full state of one order: status (settled | pending_confirmation | cancelled | refund_requested | refunded), shipStatus (none | label_created | awaiting_dropoff | shipped | in_transit | delivered), tracking, and the buyer-seller message thread.

Request a refund

Buyer requests a refund on a settled order, with a reason. The seller then approves it.

Message on an order

Ask a question or reply on an order's buyer-seller thread. Set from='buyer' or 'seller'.

My sales (seller)

Orders placed on YOUR listings: who bought, shipping address, ship state, refund requests.

Mark shipped (seller)

Seller confirms the package is handed to the carrier (or dropped at UPS for C2C).

Approve a refund (seller)

Seller approves a buyer's refund request; funds return on the original rail.

List sellers

Every seller on Calmar (brand or individual) and the verticals they cover.

List an item from a photo

The effortless sell path. Send a photo as a public https URL, a data URL (data:image/…;base64,…), or bare base64 image bytes with no prefix — all three work; Calmar rehosts it so it always displays. Pass whatever the seller already told you (title, description, price) — your data wins; Calmar's vision model only fills the gaps and suggests a fair price. On sale, Calmar mints a UPS label — the seller just drops it off.

List an item (manual)

Publish a listing with explicit fields. Any agent can then buy it. STRONGLY prefer attaching imageUrl — listings without a photo barely sell. If you have the photo in the conversation, pass it (https URL, data URL, or bare base64). If your client cannot pass image bytes, publish anyway: the result includes photoUploadUrl, a link the seller opens in a browser to add the photo in one tap.

Add or replace a listing's photo

Attach a photo to one of the seller's existing listings. Accepts a public https URL, a data URL, or bare base64 image bytes (jpeg/png/webp/gif/heic, up to 20MB). Calmar rehosts it and automatically restages it into a clean white-background studio product shot — the product itself stays exactly as photographed (same condition, labels, wear). If you cannot pass image bytes, call without `image` to get photoUploadUrl: a browser link where the seller drops the photo themselves.

Connect an existing catalog

For stores: import a whole catalog at once. Sources: 'shopify' (domain + Storefront token), 'woocommerce' (store URL + read-only consumer key/secret), 'url' (ANY product page URL — AI extracts the listing), 'csv' (raw CSV text with title,price,… columns), or 'json' (normalized items array).

My listings

Everything you are selling on Calmar, with live stock and status.

Update a listing

Reprice or pause/activate one of your listings by its offerId.