Stop an agent over-refunding

A refund agent rarely fails by refunding one enormous amount. It fails by refunding

90 against a

40 order, quietly, on an order it misread, because the ceiling it was given was a number and the order total is a different number on every request.

Before you start

The agent and budget below come from the quickstart. Export the two ids it printed, and scope the agent for refund.create so its key may ask about refunds at all:

Identifiers

export KORDIO_AGENT_ID="7d2a6c15-3f89-4b02-9e64-8a15d7c0b3f2"
export KORDIO_BUDGET_ID="3f1c8a92-5d41-4c8e-9f2b-7a6e1d0c4b83"

Why a cap cannot express this

per_transaction_cap_cents and cost_cap compare cost_cents to a number you wrote when you saved the policy. That number cannot be “whatever this order was worth”, so the tightest cap you can write is the largest order you ever expect, which is far too loose for the smallest one. A condition predicate can compare a field to another field on the same request instead of to a literal, using value_field:

{ "field": "cost_cents", "operator": "gt", "value_field": "metadata.order_total_cents" }

Both sides resolve the same way, so value_field accepts exactly the names the left side accepts: action_type, resource, cost_cents, currency, agent_id, agent_mode, budget_id, or any metadata.* dot path. The condition language covers the rest of the grammar.

1. Write the ceiling

POLICY=$(curl -s -X POST https://api.kordio.io/control/v1/workspaces/$KORDIO_WORKSPACE/policies \
  -H "Authorization: Bearer $KORDIO_DASHBOARD_TOKEN" \
  -H "Content-Type: application/json" \
  -d "{
    \"agent_id\": \"$KORDIO_AGENT_ID\",
    \"rules\": [
      {
        \"kind\": \"condition\",
        \"effect\": \"deny\",
        \"rule_name\": \"refund_exceeds_order\",
        \"action_types\": [\"refund.create\"],
        \"when\": {
          \"field\": \"cost_cents\",
          \"operator\": \"gt\",
          \"value_field\": \"metadata.order_total_cents\"
        }
      }
    ]
  }")

export KORDIO_POLICY_ID=$(echo "$POLICY" | jq -r '.data.id')

201 Created

{
  "data": {
    "id": "c41d7b28-9e05-4a63-b7f1-6d2c8e30a915",
    "agent_id": "7d2a6c15-3f89-4b02-9e64-8a15d7c0b3f2",
    "status": "active",
    "mode": "blocklist",
    "imports": [],
    "rules": [
      {
        "kind": "condition",
        "effect": "deny",
        "rule_name": "refund_exceeds_order",
        "action_types": ["refund.create"],
        "when": {
          "field": "cost_cents",
          "operator": "gt",
          "value_field": "metadata.order_total_cents"
        },
        "id": "b8e4f072-3c19-4d5a-8e26-0f7a91c4b3d8"
      }
    ],
    "per_transaction_cap_cents": null,
    "counterparty_allowlist": [],
    "created_at": "2026-08-22T10:04:18Z",
    "updated_at": "2026-08-22T10:04:18Z"
  }
}

action_types is an exact list, not a prefix. To cover a family of refund types, drop it and match action_type with starts_with inside the expression instead.

2. Refuse a refund that arrives without an order total

A field that is not on the request resolves to nil, and nil does not compare. It does not fall back to zero. So a refund that omits metadata.order_total_cents makes the predicate false, the rule does not fire, and the refund goes through.

A value_field rule is silent when the fact is missing, which is the direction that costs you money. Pair it with an exists test whenever the fact is mandatory.

Add the guard by sending the full rules array back. An update replaces the array rather than merging into it, and each rule keeps its id only if you send the id back with it:

curl -X PATCH https://api.kordio.io/control/v1/workspaces/$KORDIO_WORKSPACE/policies/$KORDIO_POLICY_ID \
  -H "Authorization: Bearer $KORDIO_DASHBOARD_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "rules": [
      {
        "id": "b8e4f072-3c19-4d5a-8e26-0f7a91c4b3d8",
        "kind": "condition",
        "effect": "deny",
        "rule_name": "refund_exceeds_order",
        "action_types": ["refund.create"],
        "when": {
          "field": "cost_cents",
          "operator": "gt",
          "value_field": "metadata.order_total_cents"
        }
      },
      {
        "kind": "condition",
        "effect": "deny",
        "rule_name": "refund_missing_order_total",
        "action_types": ["refund.create"],
        "when": {
          "field": "metadata.order_total_cents",
          "operator": "exists",
          "value": false
        }
      }
    ]
  }'

200 OK

{
  "data": {
    "id": "c41d7b28-9e05-4a63-b7f1-6d2c8e30a915",
    "status": "active",
    "rules": [
      { "rule_name": "refund_exceeds_order", "id": "b8e4f072-3c19-4d5a-8e26-0f7a91c4b3d8" },
      { "rule_name": "refund_missing_order_total", "id": "1a7c5d93-8b04-4e21-9f6d-3c0b8a52e7f1" }
    ],
    "updated_at": "2026-08-22T10:06:41Z"
  }
}

A rule you resend without its id is assigned a fresh one, and a decision recorded last week then names a rule id that no longer exists in the policy. Keep the ids.

3. Send the order total with the refund

The agent asks before it refunds, and carries the order total it is refunding against:

curl -s -X POST https://api.kordio.io/control/v1/agent/actions \
  -H "Authorization: Bearer $KORDIO_AGENT_KEY" \
  -H "Idempotency-Key: refund-4471-attempt-1" \
  -H "Content-Type: application/json" \
  -d "{
    \"budget_id\": \"$KORDIO_BUDGET_ID\",
    \"action_type\": \"refund.create\",
    \"resource\": \"order-4471\",
    \"cost_cents\": 2500,
    \"metadata\": { \"order_id\": \"4471\", \"order_total_cents\": 4000 }
  }"

201 Created

{
  "data": {
    "id": "9b2ef0c1-6a3d-4e75-8c19-2f4b7d5a0e63",
    "budget_id": "3f1c8a92-5d41-4c8e-9f2b-7a6e1d0c4b83",
    "action_type": "refund.create",
    "resource": "order-4471",
    "cost_cents": 2500,
    "currency": "USD",
    "state": "pending",
    "metadata": { "order_id": "4471", "order_total_cents": 4000 },
    "trace_id": "5e8c1a47-2b93-4d06-a7f1-9c3e05b8d24a"
  },
  "decision": {
    "outcome": "allowed",
    "rule": null,
    "detail": {},
    "headroom": { "session_remaining_cents": 38000 }
  },
  "cosignature": "eyJhbGciOiJFUzI1NiIsImtpZCI6ImtleV8xIn0..."
}

A refund is money leaving, so it reserves budget like any other spend. Report it with complete or fail once your rail has answered.

4. Watch it refuse

Same order, an amount above what the order was worth:

curl -s -X POST https://api.kordio.io/control/v1/agent/actions \
  -H "Authorization: Bearer $KORDIO_AGENT_KEY" \
  -H "Idempotency-Key: refund-4471-attempt-2" \
  -H "Content-Type: application/json" \
  -d "{
    \"budget_id\": \"$KORDIO_BUDGET_ID\",
    \"action_type\": \"refund.create\",
    \"resource\": \"order-4471\",
    \"cost_cents\": 9000,
    \"metadata\": { \"order_id\": \"4471\", \"order_total_cents\": 4000 }
  }"

403 Forbidden

{
  "data": {
    "id": "2c7f4b81-0d63-4a19-8e05-1b9c6f3a7d24",
    "action_type": "refund.create",
    "cost_cents": 9000,
    "state": "denied",
    "metadata": { "order_id": "4471", "order_total_cents": 4000 }
  },
  "decision": {
    "outcome": "denied",
    "rule": "refund_exceeds_order",
    "detail": {
      "rule_id": "b8e4f072-3c19-4d5a-8e26-0f7a91c4b3d8",
      "matched": {
        "field": "cost_cents",
        "operator": "gt",
        "value_field": "metadata.order_total_cents"
      }
    },
    "headroom": { "session_remaining_cents": 35500 }
  }
}

detail.matched is the predicate that fired, echoed back with the value_field intact, so the record of the denial says which two numbers were compared rather than just naming a rule.

What write time catches

Both mistakes are refused when you save the policy, not when an agent is waiting on an answer:

You wrote	You get
`"value_field": "order_total"`	`422`, `Unknown field "order_total"`
both `value` and `value_field`	`422`, `Expression compares to a value and a value_field, pick one`

422 Unprocessable Entity

{
  "error": {
    "message": "Validation failed: Rules Expression compares to a value and a value_field, pick one",
    "code": null
  }
}

Book refunds on /control/v1/agent/actions. The payment endpoint always evaluates as payment.create, whatever you send it, so it cannot carry a refund.create action type.

Next steps

Pass facts from your own service

Where metadata.order_total_cents comes from, and what else belongs there.

Roll a policy out safely

Preview this rule before it ever decides anything real.

Writing a policy

Every rule kind, operator, and combinator.

Errors

Every rule that can appear in decision.rule.

Get started

Core concepts

Guides

Guarantees

Reference

Endpoints

Stop an agent over-refunding

Before you start

Why a cap cannot express this

1. Write the ceiling

2. Refuse a refund that arrives without an order total

3. Send the order total with the refund

4. Watch it refuse

What write time catches

Next steps

Pass facts from your own service

Roll a policy out safely

Writing a policy

Errors

​Before you start

​Why a cap cannot express this

​1. Write the ceiling

​2. Refuse a refund that arrives without an order total

​3. Send the order total with the refund

​4. Watch it refuse

​What write time catches

​Next steps

Pass facts from your own service

Roll a policy out safely

Writing a policy

Errors

Before you start

Why a cap cannot express this

1. Write the ceiling

2. Refuse a refund that arrives without an order total

3. Send the order total with the refund

4. Watch it refuse

What write time catches

Next steps