{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://artifacts.apis.io/bettermenu/json-schema/bettermenu-usage-response-schema.json",
  "title": "UsageResponse",
  "description": "One organization's usage for one billing cycle, and what it comes to.",
  "x-generated": "2026-11-04",
  "x-method": "derived",
  "x-generator": "derive-json-schema.py",
  "x-source": "openapi/bettermenu-entitlements-api-openapi.yml#/components/schemas/UsageResponse",
  "properties": {
    "period_key": {
      "type": "string",
      "title": "Period Key"
    },
    "credits_used": {
      "type": "integer",
      "title": "Credits Used"
    },
    "allowance": {
      "$ref": "#/$defs/AllowanceView",
      "description": "What the plan allows this cycle, as a tagged object rather than a nullable number. A null limit had to mean both 'no ceiling' and 'no entitlement', which is exactly how a cancelled organization came to be reported as unlimited. Read the kind, then the fields that kind carries."
    },
    "credits_overage": {
      "type": "integer",
      "title": "Credits Overage",
      "description": "Credits beyond the included allowance: credits_used minus credits_included, floored at zero, and zero when the allowance is unlimited. Named for the rate card's own term, which is also what reaches the meter event and the invoice line, so a disputed bill and this payload use one word for one thing."
    },
    "charges_apply": {
      "type": "boolean",
      "title": "Charges Apply",
      "description": "Whether an overage in this cycle is actually charged. False while the AI quota is in its preview period, when usage is recorded and billed to nobody, and for an organization with no paid subscription, whose allowance is a hard stop. Separate from credits_overage because the two are different facts: one is the regime, the other is this cycle."
    },
    "unattributed_credits": {
      "type": "integer",
      "title": "Unattributed Credits",
      "description": "Credits in credits_used that by_capability does not account for, floored at zero. Normally zero. It is positive for a cycle that was already in flight when per-capability counting began: the cycle total covers the whole period while the breakdown covers only the part after it, so the parts do not sum to the whole. Reported rather than hidden, because a breakdown that silently fails to add up is the one thing a screen built to be checkable must not do. Self-clearing: no cycle started after counting began can have it."
    },
    "resets_at": {
      "anyOf": [
        {
          "type": "string",
          "format": "date-time"
        },
        {
          "type": "null"
        }
      ],
      "title": "Resets At",
      "description": "When this period ends and the allowance renews: the 1st of next month (UTC) for an allowance counted per calendar month, otherwise the next billing-cycle boundary. Not derivable from period_key, which is the cycle's clamped start day and says nothing about the next boundary in a month too short to hold the anchor. Null when a billing-cycle allowance has no plan row to take an anchor from. The same instant getEntitlementStatus reports, from one helper."
    },
    "by_capability": {
      "items": {
        "$ref": "#/$defs/CapabilityUsage"
      },
      "type": "array",
      "title": "By Capability",
      "description": "Largest consumer first. Empty when the cycle recorded none."
    }
  },
  "type": "object",
  "required": [
    "period_key",
    "credits_used",
    "allowance",
    "credits_overage",
    "charges_apply",
    "unattributed_credits",
    "resets_at",
    "by_capability"
  ],
  "$defs": {
    "AllowanceView": {
      "properties": {
        "kind": {
          "type": "string",
          "title": "Kind",
          "description": "One of \"capped\" (a ceiling, in credits), \"uncapped\" (the plan meters this without limiting it), or \"not_entitled\" (billing has lapsed, so there is no allowance at all)."
        },
        "credits": {
          "anyOf": [
            {
              "type": "integer"
            },
            {
              "type": "null"
            }
          ],
          "title": "Credits",
          "description": "The ceiling, present only when kind is \"capped\". Absent for the other two, because neither has one — and 0 would be a ceiling of zero, which makes every credit an overage."
        }
      },
      "type": "object",
      "required": [
        "kind"
      ],
      "title": "AllowanceView",
      "description": "What a plan allows for a cycle, tagged so the three cases stay distinct.\n\nMirrors ``entitlements.allowance.QuotaGrant`` deliberately: the wire shape\nand the internal type have the same three cases, so they cannot drift into\nthe collapse this replaces.\n\n``kind`` is a plain string rather than an enum in the schema, so a fourth\ncase later does not break a strict client parsing today's closed set. The\nserver's own type is exhaustive; the wire stays open."
    },
    "CapabilityUsage": {
      "properties": {
        "capability": {
          "type": "string",
          "title": "Capability",
          "description": "Stable key, e.g. \"paste_and_go\"."
        },
        "credits": {
          "type": "integer",
          "title": "Credits"
        },
        "requests": {
          "anyOf": [
            {
              "type": "integer"
            },
            {
              "type": "null"
            }
          ],
          "title": "Requests",
          "description": "Requests that earned credits under this capability. Null when the count is not recorded for this cycle, which is every cycle already in flight when the counter was introduced. Null rather than zero on purpose: zero says a capability earned credits across no requests, which is not a state any request can produce, so a reader shown 0 would be shown a contradiction rather than a gap."
        }
      },
      "type": "object",
      "required": [
        "capability",
        "credits"
      ],
      "title": "CapabilityUsage",
      "description": "One capability's share of the cycle."
    }
  }
}