10
reason codes in the public vocabulary for agent order disputes
Available now/ ON THE RECORDEvidence for AI agent orders
Agent commerce, on the record.
Sooner or later, someone on your team will have to explain an order an AI agent placed. KYA keeps the record: what the agent was allowed to do, what your store checked, and what happened next. Where a fact is missing, the record says so instead of filling it in.
/ Case reviewExplain the order, gaps included.
/ 01The job
Four questions every agent order has to answer.
A shopper who checks out can be asked what they meant. An agent order arrives with no one to ask. When the buyer, a payment dispute, or your own finance team questions it, the record has to answer these four questions.
- 01
What was the agent allowed to do?
The authorization evidence your store had when it decided: the signed trace the operator issued, its scope and spending cap, and the verification result.
- 02
What did your store actually check?
Each limit your checkout compared against the order, with the result. A limit nobody could check is marked not evaluated, never passed.
- 03
What happened afterward?
Outcomes reported after the order, such as a refund, a dispute, or a reported fraud case, with the source channel each one came from.
- 04
What is still missing?
Absent events, authority nobody verified, and decisions not yet reviewed stay visible. You see the gap before someone else finds it.
/ 02Our approach
Five steps that put an order on the record.
Each step is a separate call or screen, not one magic check. The status column shows what you can use today and what the founding merchant pilot adds.
01
Verify the agent
POST /api/v1/verify identifies the agent and its operator and returns a recommendation to accept, review, or decline, with reasons and a verification ID.
Available now
02
Check the signed limits
The operator issues an X-KYA-Trace-ID, signed by KYA, that names the merchant, the scope, and a spending cap. POST /api/v1/checkout/sessions checks the order against it before authorization. On Shopify, these checks are advisory today.
Available now
03
Review in one place
Orders your policy flags land in the review queue of the Trust Operations Console. Each decision is saved with the context the reviewer saw.
Available now
04
Resolve before a chargeback
Open a pre-dispute alert against the order’s trace. The operator answers on the record: accept, counter-offer, decline, or ask for more information.
Available now
05
Export the case
Download one order as a signed evidence packet: JSON plus a readable HTML copy. Anyone holding KYA’s public key can check that the JSON hasn’t changed. The packet lists its own gaps.
Founding pilot
/ 03By the record
We lead with what a record holds, not with volume.
Large platforms publish how much they block. KYA is early, so this section counts what a record contains. Customer and volume numbers will appear here once the pilot produces them, each with its denominator.
5
response types for a pre-dispute alert, including resolution by a merchant rule
Available nowEd25519
signature on each exported packet, checked against a public key you receive separately
Founding pilotNot evaluated
what the record says about a limit nobody could check. Never “passed.”
Founding pilot/ 04How agent orders go wrong
Six ways an agent order goes wrong.
Each case maps to a reason code you can raise against the order, with what the record shows and where it stops. Alerts and checkout checks are available now; evidence records are part of the founding pilot.
CaseWhat the record showsReason code
Over the limit
The signed trace caps the order at $149. The cart comes to $188.
What the record shows
The cap, the cart total, and the check that compared them. Through the checkout API, the session is declined with TRACE_AMOUNT_EXCEEDED.
AMOUNT_EXCEEDED
“My agent did that, not me”
The buyer says they never authorized the purchase their agent made.
What the record shows
The authorization evidence your store had when it decided. The trace comes from the agent’s operator, so the record states plainly that it does not prove the buyer agreed.
PRINCIPAL_DENIAL
Stuck in a loop
The agent places the same order again and again.
What the record shows
One checkout session spends a trace. A repeat that reuses it is marked unverified with TRACE_REPLAYED. A stop-loss alert asks the operator to halt the agent.
HALLUCINATION_LOOPDUPLICATE_ACTION
Permission pulled mid-order
Permission is withdrawn while an order is in progress.
What the record shows
If the operator revokes the trace before checkout, the checkout API marks the session unverified with TRACE_REVOKED. Otherwise, raise the alert; the operator’s response is recorded against its deadline.
REVOKED_DURING
Outside its scope
An agent cleared for one merchant or task acts beyond it.
What the record shows
The trace’s merchant and scope beside the order. When the trace names a different merchant, the checkout API marks the session unverified with AUDIENCE_MISMATCH.
SCOPE_EXCEEDED
Wrong item
The agent buys something other than what the buyer asked for.
What the record shows
Today’s trace carries no item-level limit, so KYA cannot check the item, and the record says not evaluated. You can still raise the alert and get the operator’s answer on the record.
WRONG_ITEM
/ 05The evidence packet
What one order looks like on the record.
One order, exported as signed JSON with a readable HTML copy, for the person who has to explain the order to someone else. Packets are part of the founding merchant pilot.
Founding pilot
- Decision
- The recommendation, the policy version, and the facts evaluated, as recorded at the time. Missing facts are not rebuilt from today’s settings.
- Authorization
- The trace’s merchant, scope, and spending cap, and the class of authority behind them. Context from the operator’s trace is labeled as operator context, not as buyer consent.
- Checks
- Each constraint compared and its result. Checks that could not run are listed as not evaluated, with the reason.
- Sources
- The source channel, environment, and source event ID behind each outcome. Source authentication is not recorded yet, and the packet says so.
- Outcomes
- Results reported after the order. A fraud report stays a report from its source. The packet does not confirm it.
- Review
- Decisions your team recorded. Corrections are not tracked yet, and the packet states that gap.
- Integrity
- Canonical JSON, a SHA-256 hash, and an Ed25519 signature. A separate verifier, given KYA’s public key, detects any change to the signed JSON.
Left out on purpose: raw trace tokens, payment credentials, carts, review notes, and principal references.
/ 06Limits
What the record does not claim.
Evidence is only useful if it is honest about its limits. These are ours.
No certification, no guarantee. KYA records evidence. Your store makes the call, and KYA does not certify agents or guarantee orders.
Agent credentials are not buyer consent. A trace the operator issued does not independently verify the buyer. The record says so instead of implying it.
Records are not immutable. Stored records are timestamped and tied to stable IDs, and some can be updated. Exported packets are signed, so a changed packet fails verification.
Shopify checks are advisory. Blocking a Shopify checkout requires a Shopify cart and checkout validation Function. Until one is in place, KYA advises and your store decides.
No promised chargeback outcomes. Pre-dispute alerts run alongside the chargeback process. They do not replace it, and KYA does not predict how a dispute will end.
No volume numbers yet. We will publish pilot results when we have them, each with its denominator, cohort, and dates.
/ 07KYA Founding Merchant Network
The network is the merchants, not a data pool.
Up to five merchants with real agent orders work with KYA to put those orders on the record and shape the record format. Seats are limited because each one gets hands-on work from our team.
Who it is for
- Agent orders reach your checkout now or soon, on Shopify, WooCommerce, or a custom checkout.
- One named person owns agent order review.
- You can share checkout and order events and the final outcome of each order.
What members get
- Setup on your checkout, working directly with the KYA team.
- A record-only start: KYA records, your checkout keeps deciding.
- Evidence packets for your own orders, exportable when you need them.
- A say in the record format and the reason codes.
What is not promised yet
- Cross-merchant evidence. If it proves useful, founding members get it first. Until then, we call it unproven.
- Published results. Pilot numbers appear only after the pilot produces them.
/ 08Terms
The words on this page, defined.
- Agent order
- An order an AI agent places on behalf of a person or business.
- Operator
- The business that runs the AI agent and issues its traces.
- Principal
- The person or business the agent acts for, usually the buyer.
- Signed trace (X-KYA-Trace-ID)
- A token the operator issues before checkout and KYA signs. It names the agent, the merchant it may buy from, what it may do, and a spending cap.
- Evidence record
- KYA’s view of one agent order attempt: the verification, the checks, reported outcomes, review decisions, and the gaps.
- Evidence packet
- One evidence record exported as signed JSON with a readable HTML copy.
- Not evaluated
- The status of a limit nobody could check, such as an item limit the trace does not carry. It is never shown as passed.
- Principal denial
- A buyer saying they did not authorize their agent’s order. The agent-commerce version of “I didn’t order this.”
- Pre-dispute alert
- A case a merchant or operator opens against an order’s trace to resolve a problem before it becomes a chargeback.
/ 09FAQ
Questions merchants ask.
How do I prove an AI agent was allowed to place an order?
Show the authorization evidence your store had when it decided: the signed trace the operator issued, with its merchant, scope, and spending cap; the verification result; and the checks your checkout ran. KYA keeps those together. The trace shows what the operator authorized. It does not independently prove the buyer agreed, and the record says so.
What should a merchant do when a buyer says their AI agent made a purchase they did not authorize?
Open a pre-dispute alert with the PRINCIPAL_DENIAL reason code against the order’s trace. The operator can accept, counter-offer, decline, or ask for more information. If the case does not resolve, you can still use the normal chargeback process with the trace and the response history.
Does KYA block agent orders on Shopify?
Not today. Shopify checkout checks are advisory. Blocking a Shopify checkout requires a Shopify cart and checkout validation Function. With a custom integration, the KYA checkout API can decline a session that exceeds the signed limits.
Can KYA guarantee that I win a chargeback?
No. KYA gives your team a source-labeled record to work from, with its gaps marked. It does not promise dispute outcomes, and we do not cite card-network precedents we do not have.
Are KYA records immutable?
No, and we do not describe them that way. Records are timestamped and tied to stable IDs. An exported evidence packet is signed, so anyone holding KYA’s public key can detect a change to its JSON.
What is the KYA Founding Merchant Network?
A small group of up to five merchants with real agent orders who work with KYA during the pilot. Members get setup on their checkout, evidence packets for their own orders, and a say in the record format. If cross-merchant evidence proves useful, members get it first. Until then, it is unproven.
Next step
Put your next agent order on the record.
Tell us where agent orders reach your checkout and who reviews them. We will walk through one order with you from verification to outcome, gaps included.