Wilby DocsGet Sandbox Keys

Agent Storefront

Your stores inside Claude and ChatGPT, under your own name. Customers add your connector once, sign in with your normal account, set what the agent may spend, then just ask: "order the blue lamp from the closest store", "reorder my usual dinner for 7pm" or "book a plumber for tomorrow morning". Wilby runs the connection, the sign-in handshake, the limits, approvals, the signed record and dispute evidence. Your system stays the source of every store, product, price and time.

What You Build

  1. Settings. POST /v1/storefront/secret (keep it on your server), then POST /v1/settings {"storefront": {"slug": "yourbrand", "name": "Your Brand", "description": "…", "login_url": "https://yourbrand.com/openhold-login", "api_url": "https://api.yourbrand.com/openhold", "enabled": true}}.
  2. A sign-in page at login_url. Wilby sends the customer there with ?openhold_request=oar_…. Sign them in as usual, then from your server call POST /v1/storefront/sign-ins {"request_id", "customer_external_ref"} (if Wilby takes the payment for you, add "payment_method_ref", the customer's saved card; Wilby then charges agent orders itself and cancels the order at your store if the card is declined) and redirect the customer to the continue_url you get back. They set the agent's limits there (your look, Face ID or a texted code) and return to the agent. If your sign-in page sets a Content-Security-Policy with form-action, add https://app.usewilby.com to it: browsers check the redirect to continue_url against it and silently stop there otherwise. The same sign-in sent twice (a double click) gets a fresh continue_url (with repeated: true), not an error.
  3. The Storefront API at api_url: seven POST endpoints Wilby calls. Check the Wilby-Signature header (also sent as Openhold-Signature during the move) (same scheme as webhooks, with your storefront secret) and answer JSON. Refuse with a 4xx and {"message": "…"} in plain words; the agent repeats it.

Answer What Applies to Your Business

One storefront for any business. You answer only the parts that fit, and tell Wilby which with POST /v1/settings {"storefront": {"answers": [...]}}. Agents only see the tools for what you answer.

AnswerForEndpoints
catalogAgents search what you sell (products, menu items, services)/products/search, /product
deliveryYou ship or deliver to the customer/delivery-options, /addresses
locationsCustomers choose one of your locations (a branch, a store)/stores, /store
timesCustomers book a time (a pickup, delivery slot, appointment or reservation)/open-times or /pickup-times
addressesYou pick up or work at the customer's saved address, without shipping choices (home services, pickup and drop-off services)/addresses

An online shop answers ["catalog", "delivery"]; a restaurant with branches ["catalog", "locations", "times"]; a laundry or repair service ["locations", "times"] (the default for storefronts set up before this choice existed). Everyone answers /quote, /orders, /order-status and /cancel. The Harbor Home Goods sample is an online shop; Little Fern Flowers uses locations and times.

Who is paid: store_id and seller_id are the external_ref of the store you added to Wilby, meaning whoever is paid for the order (a seller or merchant account), not necessarily a place. If you charge the customer once for a whole cart (most marketplaces), answer with your own store as seller_id and list every item, with its seller, in lines: it's one order. If each seller charges separately, each seller's items are their own order.

Addresses: agents never see or send a full address. /addresses answers your customer's saved addresses; Wilby passes only each label ("Home", "Office") to the agent, and sends the chosen address_label back to you with /delivery-options, /quote and /orders. Before the customer connects, /delivery-options gets a zip instead.

The Storefront API

Every request has customer_ref (your customer id) and agent (its name; the same name is also sent as assistant for storefronts built earlier: read either). Prices in cents. Times are ISO 8601 with a time zone offset (expires_at and anything you send back); slot labels are in the store's local time, in words.

POSTGetsAnswers
/products/search (catalog)query, category, max_price_cents{"products": [{"id", "name", "price_cents", "in_stock", "seller_id", "seller"}]}. An empty search returns your best sellers.
/product (catalog)product_id{"id", "name", "description", "price_cents", "in_stock", "options": [{"id", "label", "price_cents", "in_stock"}], "specs", "returns", "seller_id"}. specs: name–value pairs agents match against what the customer needs, for example {"Size system": "US men's", "Fit": "Runs small", "Works with": "HDMI 2.1"}. Sold by weight: add "unit": "lb" (price per lb) and optional "increment".
/delivery-options (delivery)items, address_label or zip{"options": [{"id", "label", "price_cents", "arrives"}]}
/addresses (delivery)(nothing){"addresses": [{"label"}]}. Only labels reach the agent.
/stores (locations)near (address or zip), query{"stores": [{"id", "name", "address", "distance"}]}. id is the store's external_ref in Wilby.
/store (locations)store_id{"id", "name", "address", "notes", "cancel_policy", "accepts", "services": [{"id", "name", "category", "price_cents", "unit", "minimum_cents", "turnaround", "repeats", "tiers", "estimated", "options"}]}. Set "repeats": true on a subscription or standing service. See Prices, Extras and Long Lists for tiers, estimated, options, category, accepts and cancel_policy.
/open-times or /pickup-times (times)store_id, service_id, option_id (the option chosen, such as Express or a longer appointment: answer only times that fit it), date{"slots": [{"id", "label"}]}. Wilby calls /pickup-times (the original name) unless you choose /open-times: POST /v1/settings {"storefront": {"times_path": "/open-times"}}.
/quotestore_id (if a location was chosen), items [{product_id, option_id, quantity}] or [{service_id, quantity}], time_id (also sent as pickup_time_id, its original name), delivery_option_id, address_label, notes, extras (what the customer asked for among what you accept: tip_percent or tip_cents, promo_code, use_rewards), price_check_only (a price check: keep nothing){"quote_id", "amount_cents", "summary", "expires_at", "lines": [{"name", "amount_cents", "kind"}], "tip_cents", "estimated", "delivery", "seller_id", "repeats"}. amount_cents is the total with delivery and tax (the price itself for a fixed price). Send seller_id when no store_id came in. Orders are placed only from your quotes, so the price is always yours. Send "repeats": true when the order would repeat on its own (a subscription, a weekly delivery or visit). Add "times": [{"name": "Pickup", "when": "Thu, Nov 19, 8–10 AM"}, {"name": "Return", "when": "Fri, Nov 20"}] with your own names for the order's times (Delivery, Appointment, Ships, Reservation…); agents and the signed quote show them. The older "pickup" string still works.
/ordersquote_id, store_id, wilby_order_id, amount_cents, max_amount_cents, and the delivery_option_id and address_label chosen{"order_id", "display_ref", "status"} (order_id is your own order). Create the order with your own checkout code (one checkout function used by your app, your website and this call; never a copy). If you can't, answer a 4xx: nothing is kept. Answer first, then take payment: Wilby saves its order together with your answer, so wilby_order_id doesn't exist yet while you are answering. After you answer (or when the order.created webhook arrives), take the hold in one call: POST /v1/orders/{wilby_order_id}/hold {"amount_cents", "processor", "processor_ref", "status"} (it confirms the order, asks Wilby and records the hold). If the hold fails or isn't allowed, release it, cancel your order and cancel Wilby's order with the reason. Send the store's "new order" texts and emails only after the hold is recorded.
/order-statusorder_id (yours), wilby_order_id{"status", "status_label", "times", "payment"}. times (optional): the order's times with your own names, shown while the order is active and hidden once it ends. payment (optional): {"held_cents", "charged_cents", "refunded_cents", "released"} from your payment records.
/cancelorder_id (yours), wilby_order_id, reason{"status": "cancelled", "message", "payment"}. Cancel your own order and release your hold; don't cancel Wilby's order yourself during this call: Wilby cancels it after you answer. Refuse with a 4xx in plain words when your cancel policy doesn't allow it (for example "the store already picked it up").

Prices, Extras and Long Lists

One shape for any marketplace. You price everything; Wilby shows it to the agent and never does your math. Nothing here needs a new field when you add a new kind of charge: it's a new line.

What the Agent Can Do

Depending on what you answer: search your products and see their options, see delivery choices for a saved address, find locations, see services and prices, see open times; then get a price, place an order (after the customer says yes), list orders, see an order's status, approve or decline an incremental charge, cancel. Every tool is marked read-only or changes-something, as the agent directories require.

Google's Agent Checkout (UCP)

Wilby also answers the Universal Commerce Protocol (UCP, version 2026-04-08), the checkout standard Google's AI Mode and Gemini use to buy from a business. It runs on the same Storefront API you already answer (catalog, plus delivery for saved addresses), so there is nothing new to build for checkout. Your business's UCP address is https://app.usewilby.com/ucp/<slug>; its profile is at /ucp/<slug>/.well-known/ucp.

Turn it on: POST /v1/settings {"ucp": {"enabled": true, "website_url": "https://yourshop.example/checkout", "terms_url": "https://yourshop.example/terms", "google_pay": {"gateway": "stripe", "gateway_merchant_id": "pk_live_…"}}}. It needs the storefront on with the catalog answer.

Try it on the sample online shop: https://app.usewilby.com/ucp/harbor-home-sample/.well-known/ucp.

Get Listed

Dashboard → Get Listed (or GET /v1/storefront/listing) has everything each AI app's directory asks for (Claude, ChatGPT, Gemini, Grok), with a checklist and text ready to copy into each form. You submit under your own name, from your own account in each directory.

Test Your Storefront

Dashboard → Agent Readiness → choose a store (and, if you like, a ZIP) → Test My Storefront, or GET /v1/storefront/full-test?store_ref=…&near=…. If your store search needs a location first, that's fine (agents ask the customer): the test searches again near the ZIP you give, or near the store's own ZIP from its address. Items whose versions each have their own price tiers (for example a Next Day and a Same Day service) aren't flagged as options, since an option only adds a flat amount. Free, on Wilby's server, in seconds; every quote is sent with price_check_only: true, so nothing is ordered. It plays what an AI agent does: find the store, read it, open times (also for an option), a quote, a quote with a tip, a bad promo code, no time, a taken time, an unknown item, a mixed basket, then status and cancel for an order that doesn't exist.

It also checks what real AI apps misread during testing, and grows each time one misreads something new:

Product sellers (a catalog, no stores or times) get the same test in their own shape, plus a check that products have specs (size system, fit, material, compatibility): in tests of AI shoppers, the most common failure was missing what the customer needed. The test: search, a product and its options, stock, delivery choices, a quote, an out-of-stock option, an unknown product, a wrong quantity, then status and cancel for an order that doesn't exist.

And it checks your connector against the AI app directories' rules: every tool has a title and is labeled read-only or changes-something, names fit, and descriptions describe what tools do without telling the AI how to behave.

Tools Agents See

Which tools show depends on your answers and extras. Read-only tools run without asking the customer; the others change something and the AI app asks first.

ToolWhat it doesKind
my_limitsWhat the customer allows you to spend at Your Business: per order, per month, what's left, and until when.Read-only
find_storesFind Your Business stores near an address or zip code, or by name.Read-only
get_storeA store's services, prices, minimums, turnaround times, cancel policy and what it accepts (tips, promo codes, rewards). A long list comes in pages: pass category or page to see more.Read-only
get_open_timesOpen times at a store for an order (a pickup, delivery, appointment or reservation time, depending on the business).Read-only
search_productsSearch what Your Business sells, by words, with an optional category and highest price.Read-only
get_productA product's description, specs (size system, fit, material, compatibility…), options (size, color…) each with its price and stock, and the return policy.Read-only
get_delivery_optionsShipping or delivery choices for these items: price and when it arrives. Before the customer connects, give a zip code; after, a saved address label from my_addresses.Read-only
my_addressesThe labels of the customer's saved addresses at Your Business ("Home", "Office"). Addresses are chosen by label; full addresses are not shared.Read-only
quote_orderGet the business's price for an order before placing it: the total, whether it fits your limits, and a signed quote. If the business's final price can change, it also shows how much more can be charged without asking the customer.Read-only
place_orderPlaces an order from a quote, after the customer confirms it in the AI app. Above the customer's limits, the answer is a link where the customer approves the order themselves. Orders at the same store within 30 minutes count together toward the limits.Changes something (asks first)
list_my_ordersOrders placed through you for this customer, newest first.Read-only
order_statusWhere an order is, and any extra charge waiting for an answer.Read-only
approve_extra_chargeApproves a store's extra charge on an order, after the customer confirms the amount and the store's reason in the AI app. Works within the customer's limits; above them, the customer approves it themselves.Changes something (asks first)
decline_extra_chargeDecline a store's extra charge when the customer says no. Nothing more is charged; the store is told.Changes something (asks first)
cancel_orderCancels an order the customer wants cancelled, before the store has started on it.Changes something (asks first)
create_checkoutStart a checkout: the store's price for an order (same as quote_order). Returns checkout_id, the estimate, how much more can be charged without asking, and whether it fits your limits. Before the customer connects, this is a price check only.Read-only
get_checkoutWhere a checkout stands: open (and until when), waiting for the customer to approve, expired, or ordered.Read-only
update_checkoutChange the items, time or notes of an open checkout. Gives a new signed price and a new checkout_id; the old one closes.Read-only
complete_checkoutPlaces the order from a checkout (same as place_order), after the customer confirms it in the AI app. Above the customer's limits, the answer is a link where the customer approves the order themselves.Changes something (asks first)