# AgentPay Bookings — agent-callable appointment rail

Local businesses with a machine-readable booking endpoint. An agent reads
availability, reserves a slot for a human, and gets a confirmation code.
0.10 USDC per confirmed booking, charged to the agent. No key, no account.

MACHINE-CHECKABLE SPECS: POST /book/api/match with a must-have list and get
pass/fail/unknown per requirement plus recommendation book or skip. An unpublished
fact is unknown, never satisfied. Nothing fits? POST /book/api/skip records an
honest no-fit (free) instead of a wrong booking, and GET /book/api/skips/stats
publishes the skip rate.

## Businesses
### Desert Sage Hair Studio (demo) — Phoenix, AZ
profile: https://agentpaystore.com/book/api/b/desert-sage-demo
slots:   https://agentpaystore.com/book/api/b/desert-sage-demo/availability?service=SERVICE&date=YYYY-MM-DD
book:    POST https://agentpaystore.com/book/api/b/desert-sage-demo/book  {service,date,time,name,phone|email}
page:    https://agentpaystore.com/book/b/desert-sage-demo

## For a business's own agent (one-call signup)
register: POST https://agentpaystore.com/book/api/register  {name, category, city, phone|email, services, hours, mode, booking_url, business_absorbs}
guide:    https://agentpaystore.com/book/agent-signup.md
page:     https://agentpaystore.com/book/join
Registering is free and needs no account: the response carries the public profile, the availability and book endpoints, and an admin token for the business.
A hosted listing means we hold the calendar and answer availability ourselves; a link listing publishes the business's own booking system and costs the agent nothing.

## Shopping for a human (products)
search:  https://agentpaystore.com/book/api/products?q=&city=&in_stock=1
catalog: https://agentpaystore.com/book/api/b/<slug>/products
hold:    POST https://agentpaystore.com/book/api/b/<slug>/order  {sku,qty,name,email,reserve_only:true} -> HL- code, free, 45 min
confirm: POST https://agentpaystore.com/book/api/b/<slug>/order/confirm  {code}  (the fee is paid here)
return:  POST https://agentpaystore.com/book/api/b/<slug>/order/return  {code,reason}
Reserve first and show the human the preview image, the total and the return window. Nothing is charged until confirm. If the human rejects it, return it: the business refunds the merchandise under its own policy, and the reservation fee is not refunded.

## Trade desks (HVAC, appliance, refrigeration)
coverage: https://agentpaystore.com/book/api/hvac/coverage
book:     POST https://agentpaystore.com/book/api/hvac/book  {city,service,name,phone|email,urgency,window,address}
An agent books a real service call for a human; a vetted local contractor calls to confirm.

## Rules an agent should follow
- Re-read availability immediately before booking; another agent may take the slot.
- A booking is a request the shop confirms with the human, not a guarantee.
- Give the human name plus a phone or email; one of the two is enough.
- Reuse the confirmation code to cancel rather than booking a second slot.

OpenAPI: https://agentpaystore.com/book/openapi.json