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
- Settings.
POST /v1/storefront/secret(keep it on your server), thenPOST /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}}. - 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 callPOST /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 thecontinue_urlyou 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 withform-action, add https://dev.usewilby.com to it: browsers check the redirect tocontinue_urlagainst it and silently stop there otherwise. The same sign-in sent twice (a double click) gets a freshcontinue_url(withrepeated: true), not an error. - The Storefront API at
api_url: seven POST endpoints Wilby calls. Check theWilby-Signatureheader (also sent asOpenhold-Signatureduring 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.
| Answer | For | Endpoints |
|---|---|---|
catalog | Agents search what you sell (products, menu items, services) | /products/search, /product |
delivery | You ship or deliver to the customer | /delivery-options, /addresses |
locations | Customers choose one of your locations (a branch, a store) | /stores, /store |
times | Customers book a time (a pickup, delivery slot, appointment or reservation) | /open-times or /pickup-times |
addresses | You 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.
| POST | Gets | Answers |
|---|---|---|
/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"}}. |
/quote | store_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. |
/orders | quote_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-status | order_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. |
/cancel | order_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.
- Lines. Answer
/quotewithlinesthat add up toamount_cents, each with akind:item,fee,discount(negative),tip,credit(negative: rewards, store credit),tax,minimum(raised to the store minimum),delivery. The lines go into the signed quote. - Extras you accept.
POST /v1/settings {"storefront": {"extras": ["tip", "promo_code", "rewards"]}}(or per store:"accepts"in/store). The agent can then pass the customer's tip, promo code or "use my rewards", and you get them inextrason/quote. Price them on your side and send them back as lines; a tip as atipline (ortip_cents). A code that doesn't work: refuse withpromo_invalid. - Price extras exactly as your checkout does, in the same order. For example: the goods (raised to your store minimum if needed), minus the promo (never more than the goods), plus the tip, plus delivery. If your checkout takes a percent tip from the price before discounts, so does your quote.
- Check promo codes for the signed-in customer. A code can be once per customer, for new customers only, or capped. Check it the way your checkout does, for the customer in
customer_ref, or the agent will quote a discount your checkout then refuses. Wilby passes the code exactly as typed (spaces trimmed only). - Tip rules. Tell agents how your checkout asks for a tip:
"tips": {"suggested_cents": [500, 1000, 1500], "suggested_percent": [15, 18, 20], "allow_custom": true, "allow_percent": true, "percent_of": "before_discounts"}in/store(percent_of:before_discounts,after_discountsortotal). Agents see them whenever you send them, and ask the same way. - Tips and limits. When the customer sets the agent's limits, they choose whether tips count toward them (on by default; shown as
tips_count_toward_limitson the customer's mandate). A tip is fixed: "up to without asking" applies to the order, not the tip. Charge the tip as you charge tips today. - Tiered prices.
"tiers": [{"up_to": 10, "price_cents": 1000}, {"up_to": 20, "price_cents": 2000}, {"per_unit_cents": 150}]reads as "$10.00 up to 10 lb, $20.00 up to 20 lb, then $1.50 per lb", one price list, instead of one confusingprice_cents. - Estimated prices.
"estimated": trueon a service or line (priced by weight, final price set later). Agents say it's an estimate; any increase goes through incremental charges and the customer's limits. - Options and long lists. List each item once with
"options": [{"id", "label", "add_cents"}](turnarounds, sizes) instead of one service per combination; the agent sendsoption_idwithservice_id(and to your open-times call, when times depend on the option). Addcategoryto each service: agents see 40 at a time and can open one category (up to 300 per store). - A quote is priced for its time. Your quote is for the time in it (same-day, peak hours, rush fees, slots). A different time needs a new quote; agents tell the customer the price may change. Refuse an order for another time with
time_unavailable, and name the open time in your message if you have one; the agent offers it. - Same answers as your checkout page. Checkout pages often decide things in the browser (defaults, which times show, minimum lead times, prices by time). An agent path built from server code alone can quietly give agents different answers than customers get. List what your checkout page decides by itself and make the agent path follow it. A good check: run your page's own functions next to your agent quote for every time and option at a few stores, and compare.
- Say what happened to the money. Add
"payment": {"held_cents": 4600, "charged_cents": 0, "refunded_cents": 0, "released": true}to your/canceland/order-statusanswers. Agents see it as facts from your payment records ("Payment: $46.00 held, $0.00 charged, the hold was released"), not as the store's words. Anything else for the customer goes in"message". - Cancel policy.
"cancel_policy": "Free to cancel until the store picks it up"in/store; agents tell customers before ordering. - Standard refusal codes. Refuse with
{"message": "…", "code": "…"}. With one of these codes, the agent also gets what to do next:split_required(one kind of service per order),time_required(its original namepickup_time_requiredstill works),time_unavailable,outside_area,store_closed,item_unavailable,out_of_stock,minimum_not_met,promo_invalid,rewards_unavailable,address_needed,quantity_invalid. - The customer isn't there when you take the hold. On Stripe, take it with
off_session: true(a card that asks for 3-D Secure declines, and the agent tells the customer). Other processors: use their merchant-initiated setting. - Your storefront secret stays on your server (fetch it once, keep it in your database). Never paste it into a config file, a chat or a ticket.
- Test it: Dashboard → Agent Readiness checks what an agent sees, runs two price checks per store (one that must be refused) and lists what to fix. Nothing is ordered.
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.
- Above the per-order or monthly limit the customer gave the agent, the order isn't placed: the agent gets a link for the customer, who approves that one order with Face ID or a texted code; then it is placed.
- Extra charges follow the customer's own rule, exactly as in your app.
- Repeating orders (a subscription, "every week") always go to the customer to approve, even inside the limits: your quote says
"repeats": true, or the order's wording asks for it. - Signed quotes. Every price from your
/quoteis signed by Wilby (estimate, "up to without asking", the order's times, expiry). The agent getssigned_quote.verify_urlto share with the customer; when the order is placed, the signed quote goes onto the order's record (order.signed_quote) and into chargeback evidence. Charging more than "up to" still needs the customer's approval. - Browse first (ChatGPT's way). Your storefront has two addresses.
https://dev.usewilby.com/s/<slug>/mcpasks the customer to connect first (Claude and most agents).https://dev.usewilby.com/s/<slug>/mcp/openlets an agent find stores, see prices and open times and run a price check before the customer connects; anything that orders or shows the customer's orders still needs them to connect (the tool answers with a sign-in request). Use the open address for ChatGPT. Browsing follows your Agent Access Policy and is limited per visitor. - Checkout names. The same steps also answer as
create_checkout,get_checkout,update_checkoutandcomplete_checkout, the names in ChatGPT's commerce guide. A checkout is a signed quote; changing it gives a new one. - Your rules for agent orders.
POST /v1/settings {"agent_rules": {"max_order_cents": 20000, "always_approval_required_above_cents": 10000, "hours": {"days": [1,2,3,4,5,6], "start": "07:00", "end": "21:00", "tz": "America/New_York"}}}: the most an agent may order (above it, refused; the customer orders directly), "the customer approves any order over" (orders and incremental charges, whatever the customer's own rule says), and hours for agent orders (browsing works any time). Per store:POST /v1/merchants/{id}/agent-rules, stricter only, plusblocked_agents. Also in Dashboard under AI Agents. Every change is signed. - ChatGPT Wallet payments. When your checkout takes a ChatGPT Wallet payment, report it with
"paid_with": "chatgpt_wallet"and pass on ChatGPT's signed request to your checkout page asagent_request(signature_input,signature,signature_agent,authority,path). Wilby checks it against ChatGPT's published keys and signs it into the order ("Paid with ChatGPT Wallet, approved in ChatGPT, verified"); it shows on the receipt, the order block (paid_with_wallet) and in chargeback evidence. Optionalpayment_account_referenceis kept as a checkpoint only. - Agent on every payment. For an order an AI agent placed, every payment (hold, capture, charge, incremental charge, refund) carries an
agentblock, in the order'spayments, thepayment.*webhooks and the signed record:name,identified_by(strongest first:verified_signature,platform_signed,customer_permission,reported_by_business),mandate_idwith thelimitsin force, andpaid_with(saved_card,agent_one_time_token,google_pay,chatgpt_wallet,paypal_wallet,bank_debit, …). A Stripe shared payment token is read from Stripe before it is charged: the agent's business profile, the token's limits and Stripe's risk details go inagent.token. The order'ssummary.paid_by_agenthas a ready line for screens. If you run your own processor, report how an agent paid with"agent_payment": {"paid_with": "link_agent_wallet" | "mastercard_agent_pay" | "visa_intelligent_commerce" | "agent_one_time_token" | …, "agent": "chatgpt", "reference": "…"}; it is recorded as reported by you, never as checked. - Listing in AI app directories.
GET /v1/storefront/listing(or Dashboard → Get Listed) puts together what each directory asks for and checks it: name, one-line summary, description, square icon, privacy policy (opened to check it works and mentions AI agents), support contact, help page (Wilby hosts one at/s/<slug>/help), example prompts, a reviewer test account and steps, and whether you've connected in each agent. Set them withPOST /v1/settings {"listing": {…}}. The reviewer's login and password go only in the directory's form. - Limits on agent sign-ups. 20 per visitor address and 500 per storefront per hour (an agent registering again with the same details within 24 hours gets the same registration back). Repeated failed sign-in steps are slowed too. Sign-ups that never reached a customer are removed after 30 days.
- Agent Readiness Check.
GET /v1/storefront/readiness(or Dashboard → Agent Readiness) asks your Storefront API what an agent would see and scores each store out of 100: listed, name and address, services with prices and units, ready or delivery times, notes and policies, open times, and no links or instructions in store text. Each check says what to fix. Nothing is ordered or quoted. For any business's public website (no account needed), there's the free Agent Readiness Check at/ready. - Customers coming back on their own. Link to
https://dev.usewilby.com/my-agents/<your slug>from your app, website, texts and emails. Wilby sends the customer to yourlogin_urlwithopenhold_request=csi_…andpurpose=manage_agents; sign them in as usual and finish it with the samePOST /v1/storefront/sign-inscall, then send them tocontinue_url(their Your AI Agents page: what each agent did, its track record, Turn Off, Get Proof). Receipts and extra-charge pages also show Manage Your AI Agents to customers who allowed one. From your own system:POST /v1/customers/mandate-link {"manage_only": true}. - "Approve Every Order": a customer can choose this on the limits page. The agent can still find stores, get prices and prepare orders, but every order and every incremental charge waits for the customer.
- Your text is cleaned before an agent reads it. Store names, notes, service names, slot labels and extra-charge reasons have hidden characters, links and markup removed, anything that reads like an instruction to an agent replaced with "[removed]", and long text cut short. It is handed over labelled as the store's own words, so a tampered store note can't steer the agent.
- The customer can turn the agent off at any time; its access stops at once.
- Statements only the customer can make. Add
"customer_must_confirm": ["I'm 21 or older."](1 to 5, your own words, plain text) to a/quoteanswer. The agent can't confirm these: the order always goes to the customer, who ticks each statement and approves with Face ID. The exact words are signed into the order (order.customer_statements). For any order outside agents,POST /v1/orders/{id}/confirmationsgives you a link to send. - Odd orders are checked first. Even inside the limits, an order goes to the customer to confirm when it may be a repeat (same agent, same store, within 24 hours), is more than 3 times what this customer usually spends at that store, or your quote asks for it: add
"confirm_with_customer": "Delivery address is new for this customer"to the/quoteanswer. - "Report an Agent Mistake". On "Your AI Agents" the customer can report an order their agent got wrong, and pause that agent. You get the
agent_order.reported_wrongwebhook, and the order'sorderblock showsreported_wrong(their words, marked as authorized) withnext_step: "review_reported_mistake". Cancel or refund it if they're right, before it becomes a bank dispute. If it still reaches the bank, the evidence says the order was authorized under the customer's own permission and the agent got it wrong. Dispute Evidence Package:reported_wrong.claim_packet_urlis one printable page with what the customer allowed, what the agent did, the report and what you did about it, each signed; the customer gets it on Your AI Agents and it's linked in chargeback evidence. - Agent Access Policy: choose which agents may order from you.
POST /v1/settings {"agent_access": {"mode": "all", "blocked": ["perplexity"]}}, or{"mode": "only", "allowed": ["claude", "chatgpt"]}; add"verified_only": trueto take orders only from agents that prove who they are with a signed identity (Visa's agent protocol, Web Bot Auth). Agents are told plainly that you don't take their orders, at sign-in and on every call.GET /v1/agent-access/reportshows who ordered and who was turned away in the last 30 days. Everyone is allowed until you change it. - "Your AI Agents" button (recommended): when tapped, call
POST /v1/customers/mandate-link {"customer_external_ref", "manage_only": true}and open theurl. The customer sees every agent they allowed, what each ordered and spent, Turn Off, Turn Off All, and Get Proof: a signed page they can send to their bank showing what they allowed, when they turned it off, every order, and that nothing happened after. Orders an agent asks the customer to approve link there too.
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://dev.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.
- Checkout sessions: create, read, update, complete and cancel, over REST or MCP (one endpoint,
/ucp/<slug>/mcp, the five checkout tools plusget_order; listed after REST in your profile, or first with"prefer_mcp": true). Items are your product ids ("lamp::slate"picks an option). Prices, shipping options and the total come live from your/product,/delivery-optionsand/quote, which get the shipping address the buyer chose asship_to. Right before payment the checkout is priced again; if anything changed, the buyer sees the new total first. - Payment: Google Pay, with the buyer's one-time token from your gateway, charged at once on your Stripe, Braintree or Adyen account (Braintree: add
"client_key", your tokenization key; Adyen:gateway_merchant_idis your merchant account). If you charge yourself, the token goes to your/ordersaspayment. Raw card numbers are never accepted. In the sandbox, the test handler takessuccess_token(paid) andfail_token(declined). - Your rules apply. Agent Access Policy and your rules for agent orders (the most per order, hours, "the customer approves anything over $X"), repeating orders and statements only the customer can make: past any of these, a guest's checkout answers
requires_escalationwith yourwebsite_url, and the buyer finishes on your own site. - Account linking (optional for Google; guests always work). Register Google once:
POST /v1/ucp/link-clients {"name": "Google", "redirect_uris": ["https://oauth-redirect.googleusercontent.com/r/<project>"]}gives aclient_idandclient_secret(shown once) for Google's setup. Your OAuth details are at/ucp/<slug>/.well-known/oauth-authorization-server(scopesdev.ucp.shopping.checkout:manageanddev.ucp.shopping.order:read; client_secret_basic or private_key_jwt; PKCE S256). The customer signs in on your own login page (as for the AI storefront), then sets what Google may spend and confirms with Face ID or a code. Google becomes one of their AI agents: they can see it and turn it off at any time. - Linked customers order as themselves, under their own limits. Their saved addresses (your
/addresseswith"full": true: sendfull_name,street_address,address_locality,address_region,postal_code,address_country) are offered only on a linked, signed Google request; turn this off with"share_saved_addresses": false. Above the customer's limits, the checkout answersrequires_escalationwith the customer's own approval page; they approve with Face ID, then Google completes it. - If your final price can change (
variable_amounton): only linked customers check out on Google. The checkout shows the estimate and says the final price comes later; Google Pay pays the estimate; an incremental charge after the work follows the customer's own rule (charged to their saved card with you) or they approve it. Guests finish on your site. - Shipping updates: report
POST /v1/orders/{id}/fulfillmentwithshipped(tracking number and link) and thendelivered. Google requires both. Save your Google key once (POST /v1/settings/google-orders {"google_partner_id", "api_key"}, from Google's onboarding) and Wilby sends Google every update for orders Google placed: placed, shipped, delivered, cancellations, refunds and disputes, with the same Idempotency-Key on every retry. Google refusing one is flagged for you (GET /v1/ucp/order-updates?needs_attention=true), never retried unchanged. - Signed both ways. When a platform signs its requests (HTTP Message Signatures, RFC 9421, with a key it publishes in its UCP profile), Wilby checks the signature, and a session opened signed must stay signed. Add
"require_signatures": trueto accept only signed requests. Updates Wilby sends to a platform's own address are signed with Wilby's key, published in your profile. - AP2 mandates (when the platform supports them): every checkout carries
ap2.merchant_authorization, Wilby's signature for you over the exact checkout, and completing needs the buyer'sap2.checkout_mandatecontaining that checkout. Its fingerprint goes on the order's signed record; the mandate itself is kept 180 days for disputes. - Your own domain (Google expects it). Forward
https://yourshop.example/.well-known/ucp,/.well-known/oauth-authorization-serverandhttps://yourshop.example/ucp/*tohttps://dev.usewilby.com/ucp/<slug>/…(keep the rest of the path; sendX-Forwarded-Host), and set"public_base_url": "https://yourshop.example/ucp". Your profile, OAuth issuer and order links then use your domain, and signatures are checked against your address. - The record. Each completed checkout is an order in Wilby: the signed quote, the platform, whether its signature checked out, the linked customer (if any) and how the buyer paid go onto its signed record. The shipping address goes to you for the order, and is removed from Wilby 30 days after the checkout ends; it never goes into the record.
- Same Idempotency-Key, same answer: a repeated request with the same key (within 24 hours) gets the first answer, and never a second payment; the same key with a different request is refused (409).
- Versions: UCP 2026-04-08 (what Google uses today, the default) and 2026-08-25. Set
"version": "2026-08-25"to make 2026-08-25 your current version; 2026-04-08 stays available to platforms that use it (your profile links it undersupported_versions). Each checkout keeps the version it was opened in. - Goods sold by weight (2026-08-25): answer
"unit": "lb"(orkg,oz,g) and an optional"increment"(like0.25) from/product, withprice_centsper unit. Checkout lines then count in steps of 0.01 lb, as the standard says, and your/quoteand/ordersget the quantity in pounds. When the final price is set, send what was weighed:POST /v1/orders/{id}/capture {"capture_cents": 4200, "measure": {"unit": "lb", "value": 24}}. The order shows a price adjustment with the weight, and the platform and Google hear about it. In 2026-04-08, quantities are whole pounds. - Location search (2026-08-25, if your storefront answers
locations):/ucp/<slug>/locations/searchand/locations/lookup, from your/storesand/store, with store text cleaned as for AI agents. - Return policies (2026-08-25): the
returnstext from your/productis shown on the checkout and kept on the order. - Google Pay on Braintree: turn Google Pay on in your Braintree account (Settings → Processing), or Braintree refuses the payment (error 91567).
- To go live on Google: in Merchant Center, request the UCP integration hub, mark products with
native_commerce(checkout eligibility), and pass Google's review. Not yet: discounts, Google's "Streamlined Linking", and payment terms.
Try it on the sample online shop: https://dev.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.
- Your own address. Directories expect a connector's address to match the business it lists. Choose one under your domain with
POST /v1/storefront/domain {"host": "agents.yourbusiness.com"}. The answer lists two DNS records to add where you manage your domain: aCNAMEto Wilby and aTXTrecord that shows the address is yours. ThenPOST /v1/storefront/domain/check. Wilby then gets the security certificate for your address by itself (usually within minutes;certificateshows where it is), and the status turnsactiveand your connector answers athttps://agents.yourbusiness.com/mcp(also/mcp/open, the sign-in at/oauth/…, and the help page at/and/help). Your website stays where it is. Customer pages (limits, approvals, Face ID) stay on Wilby's address, so a customer's passkey works for every business.GETshows the status;DELETEremoves it. Your connector keeps working on Wilby's address too. - Reviewer test account. Set
listing.reviewer_customer_refto a test customer in your system. Every call Wilby makes for that customer carries"reviewer": true(on/quote,/orders,/canceland the rest), and its orders showreviewer: trueon the order and in webhooks. In your system, use test payments for these calls, and send no store texts or alerts. Wilby cancels reviewer orders 30 minutes after they're placed (asking your/cancelfirst, as when an agent cancels). The reviewer sets up Face ID without a code (they can't get your texts) and still confirms with their device's lock. - Ready-made answers: the description, example prompts, reviewer steps, "does it move money?" (the financial transactions question), data handling, one answer for each policy question, and a privacy policy section for your lawyer to finish.
- Directory Rules Check: tool titles, read-only or changes-something labels, name lengths and descriptions that only describe, checked against each directory's published rules.
- Use by AI app: calls, order attempts and errors over the last 30 days, per AI app. Errors count only when something broke (your system didn't answer, or Wilby failed); refusals such as "that time is taken" are normal answers.
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:
- A price written into a name reads as a second, conflicting price. Use
price_centsortiers. - Services priced by weight need
estimated: true, or agents quote the estimate as final. - The same item listed once per turnaround or size reads as different items. Use
options. - Suggested tips belong in
tips, or agents can't offer them. - Open times must follow the
option_idchosen, or agents offer times the quote then refuses. - Summaries over 300 characters are cut. Put times in
timeswith your own names. - An open time whose id and label name different days (one in UTC, one in local time) confuses agents. Build both from the store's local date.
- A price is called an estimate only when you mark it
estimated; otherwise agents say "total". - Labels that say today or tomorrow are wrong once the day changes. Name the day and date.
- The quote
summarysays what's ordered ("Wash & Fold, about 15 lb"). A summary that repeats the price, tip or times makes agents see each one twice: Wilby already shows them from their own fields.
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.
| Tool | What it does | Kind |
|---|---|---|
my_limits | What the customer allows you to spend at Your Business: per order, per month, what's left, and until when. | Read-only |
find_stores | Find Your Business stores near an address or zip code, or by name. | Read-only |
get_store | A 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_times | Open times at a store for an order (a pickup, delivery, appointment or reservation time, depending on the business). | Read-only |
search_products | Search what Your Business sells, by words, with an optional category and highest price. | Read-only |
get_product | A 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_options | Shipping 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_addresses | The 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_order | Get 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_order | Places 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_orders | Orders placed through you for this customer, newest first. | Read-only |
order_status | Where an order is, and any extra charge waiting for an answer. | Read-only |
approve_extra_charge | Approves 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_charge | Decline a store's extra charge when the customer says no. Nothing more is charged; the store is told. | Changes something (asks first) |
cancel_order | Cancels an order the customer wants cancelled, before the store has started on it. | Changes something (asks first) |
create_checkout | Start 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_checkout | Where a checkout stands: open (and until when), waiting for the customer to approve, expired, or ordered. | Read-only |
update_checkout | Change 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_checkout | Places 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) |