Three discovery files AI shopping agents look for

1. Why three files, not one

A checkout description without a signup description is a half answer. An agent that lands on /.well-known/agent-checkout.json and sees a POST endpoint does not know if it has to sign in first, or whether guest purchases are allowed. A signup description without a checkout description is worse: the agent knows the account model but not the price, the fulfillment path, or the refund window.

The split is deliberate. Checkout is transactional. Signup is identity. They change on different clocks, they belong to different teams, and mixing them into a single JSON forces a schema that neither team wants to own.

The third file, llms-pay.md, is the human-and-machine narrative. Agents parse the JSON, but LLMs read the markdown when they are asked to explain what you sell in plain language. Both surfaces should agree on the facts.

2. File 1: /.well-known/agent-checkout.json

Lives at the site root under the .well-known prefix, served with Content-Type: application/json. This is where an agent looks first when the human user says "buy the pro plan for me".

What it declares:

• products[] - each product has an id, name, description, and a price object with amount, currency, and recurrence (one_time or monthly). For tiers that combine one-time and recurring, add a subscription block with starts_after.
• checkout_flow - the exact HTTP call the agent makes. Includes method, endpoint, and a body_schema with the field names the agent has to fill. If checkout requires a prior step (say, scanning a target domain before buying a scan-bound pack), that goes in prereq with its own schema.
• fulfillment - how the agent knows the order is done. Usually a poll_endpoint and a terminal_status. The delivery field describes what the buyer actually receives (signed URL, license key, dashboard access).
• payment_providers[] - list them with role (primary, fallback, planned), supported modes (live, sandbox), and card networks.
• test_mode - critical. Give the agent an explicit path to smoke-test the flow without moving real money. Sandbox host, seller-account requirement, or a documented dry-run branch.

A live example lives at agentfix.pro/.well-known/agent-checkout.json. Two products, three providers, one prereq step (scan before checkout), one poll endpoint.

3. File 2: /.well-known/agent-signup.json

Same directory, Content-Type: application/json. This file exists even if you do not have signup - in that case it declares signup_required: false and describes the guest model.

What it declares:

• signup_required - boolean. Default false is a strong signal to agents that they can proceed without account creation logic.
• signup_model - one of guest_first, pre_purchase_signup, post_purchase_activation, or hybrid. Tells the agent when identity is needed.
• authentication_methods[] - SSO providers, passkey, email-link, password. Empty array is a valid answer.
• post_purchase_activation - if the pack, license, or subscription needs a separate activation step after payment, describe the trigger, the delivery channel, and the endpoints. Agents that expect instant delivery will otherwise get confused when a payment webhook completes but no download appears immediately.
• identity_privacy - PII collected, retention days, password storage boolean, cross-site tracking boolean. Agents that answer to privacy-conscious users check these first.

A live example: agentfix.pro/.well-known/agent-signup.json. It declares guest-first, no accounts, post-purchase activation via license key.

4. File 3: /llms-pay.md

Markdown at the site root. This one is dual-purpose. Agents parse it as a fallback when they cannot ground a decision in the JSON files. Human developers and LLM-powered assistants read it when they need a conversational answer.

Structure that works:

1. One-line summary at the very top (> Discovery layer for AI shopping agents...).
2. Links back to the JSON files, so the agent knows both surfaces exist.
3. What we sell - bullet per product, with price in the sentence, not buried in a table.
4. How to purchase programmatically - numbered steps that mirror the checkout_flow in the JSON but in prose.
5. Test mode - repeat the sandbox path from the JSON but explain why it exists.
6. Payment providers, refunds, contact - human-readable versions of the JSON fields.

A live example: agentfix.pro/llms-pay.md.

The rule of thumb: the JSON is what agents execute, the markdown is what agents cite when asked to explain. Neither should ever contradict the other.

5. How agents actually use these

The realistic order of operations from an autonomous shopping agent:

1. Agent lands on the site root, reads robots.txt and llms.txt for the AI-facing manifest.
2. llms.txt should list the three commerce files under a Commerce section. If they are not linked, the agent may skip them entirely - a lot of agents refuse to guess .well-known/ paths that were not explicitly announced.
3. Agent parses agent-signup.json first. If signup_required: true and no authentication_methods the agent supports, it stops.
4. Agent parses agent-checkout.json, matches product by user intent, and locks the checkout_flow.
5. If sandbox mode is available and the agent is in dry-run, it uses the test_mode branch.
6. Agent executes the flow, polls fulfillment, hands the delivery artifact back to the user.

Step 2 is where most sites lose: perfectly good discovery files that the agent never finds because they are not announced in llms.txt.

6. What to write when data is missing

The safe pattern: emit the file with an explicit notes field explaining the gap. agent-signup.json with signup_required: false and notes: "no signup layer configured; guest checkout only" is a valid, useful answer. Empty products[] with notes: "product catalog pending; contact [email protected] for programmatic buying" is a valid, useful answer.

Silence is worse than a truthful gap.

7. Cross-linking so agents follow the trail

Every one of these files should reference the other two. agent-checkout.json includes a docs field pointing at llms-pay.md. agent-signup.json includes a checkout_reference field pointing at agent-checkout.json. llms-pay.md links out to both .well-known files at the top.

The llms.txt at the site root then has a Commerce section that lists all three. That is the trailhead. Without it, everything else is unreachable.

If you want to see what the trail looks like in practice, run a scan of a site that ships this layer, or run one of your own commerce properties and see how many of the nine commerce checks pass.

8. Key takeaways