Merchant Policy Schema (v1)
Overview
Merchant policy determines whether agent-submitted order intent is approved, reviewed, clarified, or rejected before anything reaches checkout. This is the control surface ChatBasket evaluates during the Agentic Commerce Flow.
What policy controls
- Whether an intent is allowed, requires human review, needs clarification, or is rejected
- Category restrictions and spend limits
- Agent allow/deny and per-agent thresholds
- SKU-level overrides for high-risk items
What policy does not control
- Pricing truth, tax calculation, inventory truth
- Order creation, fulfillment, returns, refunds
- Catalog distribution to agents (ChatBasket consumes catalog metadata to evaluate rules)
Technical details
This section defines the JSON structure and evaluation behavior used by ChatBasket when authorizing SKU-level order intent.
Decision actions
Every policy evaluation returns one of four actions:
- ALLOW - approve automatically
- REVIEW - require human approval
- DENY - reject (no forwarding)
- CLARIFY - request missing inputs (store, fulfillment mode, substitutions, etc.)
Rule precedence
When multiple rules could apply, ChatBasket resolves them in a predictable order:
Schema
The policy document is a single JSON object per merchant. It is designed to be human-editable and UI-friendly.
{
"merchant_id": "merchant_abc",
"version": "v1",
"global": {
"max_order_value": { "amount": 200, "currency": "USD", "action": "REVIEW" },
"default_action": "ALLOW",
"default_substitutions_allowed": false
},
"agents": {
"agent_xyz": {
"enabled": true,
"max_order_value": { "amount": 100, "currency": "USD", "action": "DENY" },
"category_overrides": {
"produce": { "action": "ALLOW" }
}
}
},
"categories": {
"alcohol": { "action": "DENY", "reason_code": "AGE_RESTRICTED" },
"tobacco": { "action": "DENY", "reason_code": "AGE_RESTRICTED" },
"gift_cards": { "action": "REVIEW", "reason_code": "HIGH_FRAUD_RISK" }
},
"skus": {
"SKU-12345": { "max_quantity": 5, "action_on_violation": "REVIEW", "reason_code": "QTY_REVIEW" }
}
}
Field notes
- global.max_order_value: total threshold for review/deny (merchant-wide default)
- agents[agent_id].enabled: allow/deny an agent at the gate
- categories: coarse controls that map to merchant risk/compliance (age-restricted, fraud-prone, regulated)
- skus: exact overrides for specific items (limits, review gates)
- reason_code: stable code used in audit logs and agent responses
Evaluation behavior
Inputs
ChatBasket evaluates policy using SKU-level order intent (from ACP) plus merchant context.
- agent_id, merchant_id
- items: sku, category, quantity, price context (if provided)
- estimated_total
- fulfillment: delivery vs pickup, store_id (if required)
- preferences: substitutions allowed (if required by merchant policy)
Outputs
Every evaluation produces an action and a small set of reason codes. ChatBasket stores a full evaluation trace for auditability.
{
"transaction_id": "cb-789",
"final_action": "REVIEW",
"reason_codes": ["ORDER_VALUE_REVIEW"],
"matched_rules": [
{ "level": "global", "rule": "max_order_value", "action": "REVIEW" }
]
}
Examples
1) Require approval over $150
{
"global": {
"max_order_value": { "amount": 150, "currency": "USD", "action": "REVIEW" }
}
}
2) Block restricted categories
{
"categories": {
"alcohol": { "action": "DENY", "reason_code": "AGE_RESTRICTED" },
"tobacco": { "action": "DENY", "reason_code": "AGE_RESTRICTED" }
}
}
3) Allowlist one agent and set a lower spend limit
{
"agents": {
"agent_xyz": {
"enabled": true,
"max_order_value": { "amount": 75, "currency": "USD", "action": "REVIEW" }
},
"agent_unknown": {
"enabled": false
}
}
}
Notes on v1 scope
v1 is intentionally small. The goal is to make policy predictable, auditable, and easy to operate. Over time, this schema can expand to cover additional constraints (store lists, hours, delivery zones, substitution policies by category), without changing the core actions or precedence.