Agent API Reference

// Request body
{
  "items": [
    {
      "name": "Wireless Headphones",   // required, max 200 chars
      "unit_amount": 4999,              // required, cents (positive int, max 99999999)
      "quantity": 1,                    // required, positive int, max 10000
      "sku": "WH-100",                 // optional, max 100 chars
      "category": "electronics"         // optional, max 100 chars
    }
  ],
  "currency": "USD",                    // optional, default "USD", ISO 4217
  "merchant_name": "TechShop",          // optional, max 200 chars
  "merchant_domain": "techshop.com",    // optional, max 200 chars
  "category": "electronics",            // optional, max 100 chars
  "metadata": { "ref": "order-123" }    // optional, under 10KB JSON
}

GET /api/v1/agent/checkout?checkout_id=chk_abc123

// Returns full CheckoutResponse (same shape as all checkout endpoints)

// Request body
{
  "checkout_id": "chk_abc123",          // required
  "items": [                            // optional — replaces all items
    {
      "name": "Wireless Headphones",
      "unit_amount": 3999,
      "quantity": 2,
      "sku": "WH-100",
      "category": "electronics"
    }
  ],
  "merchant_name": "TechShop",          // optional
  "merchant_domain": "techshop.com",    // optional
  "category": "electronics",            // optional
  "metadata": { "ref": "updated-456" }  // optional
}

// Request body
{
  "checkout_id": "chk_abc123"           // required
}

// Response on approval:
{
  "id": "chk_abc123",
  "status": "approved",
  "approval_required": null,
  ...
}

// Response when escalated (requires human approval):
{
  "id": "chk_abc123",
  "status": "ready_for_payment",
  "approval_required": {
    "approval_id": "apr_xyz",
    "tier": 2,
    "method": "notification",
    "timeout": 300,
    "status": "pending"
  },
  ...
}

// Request body
{
  "checkout_id": "chk_abc123",  // required
  "reason": "User changed mind"  // optional, max 500 chars
}

GET /api/v1/agent/approval/apr_xyz

// Response:
{
  "approval_id": "apr_xyz",
  "status": "pending" | "approved" | "denied" | "expired",
  "checkout_id": "chk_abc123",
  "tier": 2,
  "method": "notification",
  "reason": null,                       // populated on deny
  "decided_at": null,                   // populated when resolved
  "expires_at": "2026-02-22T12:05:00.000Z"
}

// Request body
{
  "checkout_id": "chk_abc123",          // required
  "receipt": {
    "external_id": "pi_xxxxxxxx",       // required — payment provider's transaction ID
    "provider": "stripe",               // required — payment provider name
    "amount_charged": 4999,             // required — actual amount charged in cents
    "currency": "USD",                  // optional, default matches checkout currency
    "paid_at": "2026-02-22T12:02:00Z", // optional, defaults to now
    "metadata": {                       // optional
      "card_last4": "4242",
      "confirmation_url": "https://..."
    }
  }
}

// Response:
{
  "id": "chk_abc123",
  "status": "completed",
  "order": {
    "id": "ord_abc123",
    "checkout_session_id": "chk_abc123",
    "external_payment_id": "pi_xxxxxxxx",
    "provider": "stripe",
    "amount_charged": 4999,
    "completed_at": "2026-02-22T12:02:00.000Z"
  },
  ...
}

// Request body
{
  "confirm": true,                      // required — must be true
  "reason": "Suspicious activity"       // required — why the kill switch was triggered
}

// Response:
{
  "success": true,
  "agent_status": "suspended",
  "active_checkouts_canceled": 3,
  "timestamp": "2026-02-22T12:00:00.000Z"
}

{
  "id": "chk_abc123",
  "status": "approved",                 // see status machine above
  "currency": "usd",
  "line_items": [
    {
      "id": "li_item1",
      "item": { "name": "Wireless Headphones", "quantity": 1, "sku": "WH-100" },
      "base_amount": 4999,
      "subtotal": 4999,
      "tax": 0,
      "total": 4999
    }
  ],
  "merchant_name": "TechShop",
  "merchant_domain": "techshop.com",
  "category": "electronics",
  "totals": [
    { "type": "subtotal", "display_text": "Subtotal", "amount": 4999 },
    { "type": "tax", "display_text": "Tax", "amount": 0 },
    { "type": "total", "display_text": "Total", "amount": 4999 }
  ],
  "messages": [],
  "rule_result": "allow",
  "rule_name": "Per-Transaction Spending Cap",
  "reason": "Transaction amount $49.99 is within limit of $500",
  "approval_required": null,            // null when approved, object when escalated
  "order": null,                        // populated after receipt is reported
  "expires_at": "2026-02-22T13:00:00.000Z",
  "created_at": "2026-02-22T12:00:00.000Z"
}