{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://artifacts.apis.io/agentanalytics-sh/json-schema/agentanalytics-sh-payment-handoff-schema.json",
  "title": "PaymentHandoff",
  "description": "Versioned, read-only commercial guidance for the authenticated account.\nThis is an Agent Analytics contract, not a Personal Agent Protocol compliance claim.\nA handoff URL does not authorize billing or prove payment. Hosted Pro entitlement\nand ready account setup are the completion evidence. Checkout pending does not\ndistinguish an abandoned checkout from payment still processing.\n",
  "x-generated": "2026-11-01",
  "x-method": "derived",
  "x-generator": "derive-json-schema.py",
  "x-source": "openapi/_original/agentanalytics-sh-api-openapi.yml#/components/schemas/PaymentHandoff",
  "type": "object",
  "required": [
    "version",
    "account_id",
    "state",
    "entitlement_source",
    "billing_status",
    "provider",
    "human_approval_required",
    "agent_can_charge",
    "pricing",
    "next_action",
    "status"
  ],
  "properties": {
    "version": {
      "type": "integer",
      "const": 1
    },
    "account_id": {
      "type": "string"
    },
    "state": {
      "type": "string",
      "enum": [
        "upgrade_available",
        "checkout_pending",
        "active",
        "payment_attention",
        "setup_required",
        "unavailable"
      ]
    },
    "entitlement_source": {
      "type": "string",
      "enum": [
        "free",
        "subscription",
        "complimentary"
      ]
    },
    "billing_status": {
      "type": "string"
    },
    "provider": {
      "type": "string",
      "const": "lemonsqueezy"
    },
    "human_approval_required": {
      "type": "boolean",
      "const": true
    },
    "agent_can_charge": {
      "type": "boolean",
      "const": false
    },
    "pricing": {
      "type": "object",
      "required": [
        "plan",
        "currency",
        "model",
        "billing_period",
        "unit",
        "events_per_unit",
        "unit_price_cents",
        "rounding",
        "applies_to",
        "excludes"
      ],
      "properties": {
        "plan": {
          "type": "string",
          "const": "pro"
        },
        "currency": {
          "type": "string",
          "const": "USD"
        },
        "model": {
          "type": "string",
          "const": "usage_based"
        },
        "billing_period": {
          "type": "string",
          "const": "monthly"
        },
        "unit": {
          "type": "string",
          "const": "accepted_event"
        },
        "events_per_unit": {
          "type": "integer"
        },
        "unit_price_cents": {
          "type": "integer"
        },
        "rounding": {
          "type": "string",
          "const": "started_units",
          "description": "Zero events costs zero; each started 10,000-event block costs $1."
        },
        "applies_to": {
          "type": "string",
          "const": "subscription",
          "description": "Complimentary Pro access is not a paid subscription."
        },
        "excludes": {
          "type": "array",
          "items": {
            "type": "string"
          }
        }
      }
    },
    "next_action": {
      "type": [
        "object",
        "null"
      ],
      "properties": {
        "type": {
          "type": "string",
          "const": "human_browser"
        },
        "url": {
          "type": "string",
          "format": "uri",
          "description": "Agent Analytics account confirmation or billing page, never a payment credential."
        },
        "reason": {
          "type": "string"
        }
      }
    },
    "status": {
      "type": "object",
      "required": [
        "method",
        "path",
        "required_scope",
        "poll_interval_seconds",
        "max_wait_seconds",
        "can_retry_pro_task",
        "completion_evidence"
      ],
      "properties": {
        "method": {
          "type": "string",
          "const": "GET"
        },
        "path": {
          "type": "string",
          "const": "/account/usage"
        },
        "required_scope": {
          "type": "string",
          "const": "account:read"
        },
        "poll_interval_seconds": {
          "type": "integer",
          "const": 5
        },
        "max_wait_seconds": {
          "type": "integer",
          "const": 900,
          "description": "Suggested bounded polling window; timeout does not mean cancellation."
        },
        "can_retry_pro_task": {
          "type": "boolean",
          "description": "Pro entitlement and account setup are ready. The retried route still enforces scopes and request limits."
        },
        "completion_evidence": {
          "type": "string",
          "const": "hosted_entitlement"
        }
      }
    }
  }
}