Demo & reviewer guide

Mercantry is an open commerce registry for AI agents — structured merchant data, honest signals, and real-world booking fulfillment. This page is the standing demo: everything a reviewer or a new integrator needs to drive the whole booking loop, start to finish, in about two minutes.

1. Credentials: there are none to issue

Reads and sandbox bookings are open. An API key is optional — it attributes bookings and buys abuse-control headroom, and it never gates a read. There is no login, no dashboard and no paid tier, so a shared "reviewer account" would grant nothing this page doesn't.

If your process needs a credential on file, mint your own in one call (instant, free, no approval):

curl -sX POST https://agentic-commerce-registry.fly.dev/v1/keys -H 'content-type: application/json' \
  -d '{"developer_name":"Directory review","contact":"you@example.com"}'

Send it back as x-api-key: <key> or Authorization: Bearer <key>. Rate limit: 300 requests/minute, keyed or anonymous; 429s carry Retry-After. What a key stores is itemized on the privacy page.

2. Connect

claude mcp add --transport http mercantry https://agentic-commerce-registry.fly.dev/mcp

Or drive it directly: MCP Streamable HTTP at https://agentic-commerce-registry.fly.dev/mcp, REST mirror at https://agentic-commerce-registry.fly.dev/v1 (OpenAPI). Tools: search_merchants, get_merchant, get_availability, place_booking, get_booking_status, modify_booking, cancel_booking, submit_feedback, get_registry_meta.

3. Sample data: the sandbox merchants

Sandbox merchants are synthetic records kept for exactly this purpose — the test cards of this registry. They carry sandbox: true, they are excluded from every published coverage number, and the simulated call never dials a phone. They are the only merchants that complete a booking today.

merchant_id	Name	City	Max party
`005c876f-ea60-45ae-bdcb-b61087a2ef6b`	Jade House	San Francisco, CA	6
`02350de7-2a9e-462b-9940-ac1740d5aab7`	Il Forno Verde on Hayes	San Francisco, CA	6
`03100da1-e636-4da2-9fb7-9167b130c0dc`	The Grove on Clement	San Francisco, CA	8

Read from this deployment's database at render time — 500 sandbox merchants exist in total; these 3 are bookable right now. Search them yourself with GET /v1/merchants?city=San%20Francisco%2C%20CA&bookable_only=true.

4. The walkthrough — four calls

Search, book, watch it confirm, then cancel. Swap in any sandbox merchant_id above.

# a. find bookable sandbox merchants
curl -s "https://agentic-commerce-registry.fly.dev/v1/merchants?bookable_only=true&limit=3"

# b. book one, and force the outcome you want to see
curl -sX POST https://agentic-commerce-registry.fly.dev/v1/bookings -H 'content-type: application/json' -d '{
  "merchant_id": "005c876f-ea60-45ae-bdcb-b61087a2ef6b",
  "party_size": 2,
  "datetime": "2026-07-27T17:36",
  "reservation_name": "Directory review",
  "window_minutes": 60,
  "accept_within_window": true,
  "client_reference_id": "review-001",
  "sandbox_outcome": "confirmed"
}'

# c. poll until terminal (the simulated call takes ~30s)
curl -s https://agentic-commerce-registry.fly.dev/v1/bookings/<booking_id>

# d. cancel it (also the honest thing to do with any booking you abandon)
curl -sX POST https://agentic-commerce-registry.fly.dev/v1/bookings/<booking_id>/cancel \
  -H 'content-type: application/json' -d '{"reason":"demo complete"}'

The suggested datetime is the merchant's own wall clock about two hours out. Times further than 4h ahead politely wait out the merchant's meal rush before the call is placed (REQ-FUL-5), which is correct behavior but a dull demo. Retry safety: reusing a client_reference_id replays the same booking rather than double-booking — with different parameters it is rejected as client_reference_conflict.

5. Forced outcomes (sandbox only)

Pass sandbox_outcome on place_booking to walk a chosen branch of the state machine on demand, instead of taking the pseudo-random draw a real call would give you:

sandbox_outcome	What happens
`confirmed`	The call succeeds at the requested time: `queued → in_progress → confirmed`, with a confirmation code.
`no_answer`	Nobody picks up. The booking retries up to 3 times, then ends `failed` with `failure_reason: no_answer`.
`counter_offer`	The merchant offers two alternative times. With `accept_within_window` and a wide enough `window_minutes` the nearer one auto-confirms; otherwise the booking pauses in `needs_input` for you to resolve with `modify_booking`.
`fully_booked`	Terminal `failed` with `failure_reason: fully_booked`.
`merchant_declined`	Terminal `failed` with `failure_reason: merchant_declined`.
`bad_data`	Terminal `failed` with `failure_reason: bad_data` — the record the call was placed against was wrong.

Omit the field and the outcome is drawn deterministically from the booking id, so any single booking always replays the same way. The field is rejected with sandbox_outcome_requires_sandbox_merchant for real merchants — nobody gets to script a real restaurant's answer. Note that no_answer is deliberately slow: retries are 30 minute(s) apart in this deployment.

6. What is real, and what isn't

Real-merchant fulfillment is not live: place_booking against a real merchant returns fulfillment_not_live. Only sandbox merchants complete the loop today.
Search and read data is a real, QA-gated corpus of 168,524 merchants — verify anytime with GET /v1/meta.
Sandbox merchants are synthetic and are marked sandbox: true on every surface. No sandbox booking, transcript or confirmation involves a real business.
V1 holds no live table availability. get_availability says so outright: availability is checked on the call, at booking time.
Nothing in the calling specification operates until legal review completes (see the spec).

Home · Privacy · API index · OpenAPI · llms.txt · MCP manifest · MCP tool reference · GitHub · Status