PlanChangePreview

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://artifacts.apis.io/agentaos-ai/json-schema/agentaos-ai-plan-change-preview-schema.json",
  "title": "PlanChangePreview",
  "description": "Read-only quote for moving a subscription to another plan. Money is integer minor units.",
  "x-generated": "2026-11-04",
  "x-method": "derived",
  "x-generator": "derive-json-schema.py",
  "x-source": "openapi/agentaos-ai-subscriptions-api-openapi.yml#/components/schemas/PlanChangePreview",
  "type": "object",
  "properties": {
    "direction": {
      "type": "string",
      "enum": [
        "upgrade",
        "downgrade",
        "revert"
      ],
      "description": "`upgrade` when the new plan costs more per cycle; `downgrade` otherwise; `revert` when the target is the current plan while a downgrade is pending (cancels it, nothing due)."
    },
    "currency": {
      "type": "string"
    },
    "dueTodayMinor": {
      "type": "integer",
      "description": "Charged now. Always 0 for a downgrade."
    },
    "dueTodayVatMinor": {
      "type": "integer"
    },
    "effectiveAt": {
      "type": "string",
      "format": "date-time",
      "description": "Upgrade: now. Downgrade: the current period end."
    },
    "nextInvoiceMinor": {
      "type": "integer",
      "description": "The next regular cycle invoice on the new plan."
    },
    "nextInvoiceVatMinor": {
      "type": "integer"
    },
    "nextInvoiceAt": {
      "type": "string",
      "format": "date-time"
    },
    "prorationDate": {
      "type": "integer",
      "description": "Unix seconds. Echo it in the apply request so the charge matches this quote."
    }
  },
  "required": [
    "direction",
    "currency",
    "dueTodayMinor",
    "dueTodayVatMinor",
    "effectiveAt",
    "nextInvoiceMinor",
    "nextInvoiceVatMinor",
    "nextInvoiceAt",
    "prorationDate"
  ]
}