BetterMenu · Schema

UsageResponse

One organization's usage for one billing cycle, and what it comes to.

Food TechRecipeFormulationFDA ComplianceSoftware-as-a-ServiceCloud

Properties

Name Type Description
period_key string
credits_used integer
allowance object 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 t
credits_overage integer 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 th
charges_apply boolean 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,
unattributed_credits integer 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 tot
resets_at object 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
by_capability array Largest consumer first. Empty when the cycle recorded none.
View JSON Schema on GitHub

JSON Schema

bettermenu-usage-response-schema.json Raw ↑
{
  "$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."
    }
  }
}

Work with this as data

Every JSON Schema here is available over the APIs.io API and to AI agents over MCP.

MCP server

One button, every client — Claude, Cursor, VS Code and the rest.

https://apis.io/mcp

Tools for schemas

4 MCP tools reach this
  • find_json_schemasBrowse and filter every JSON Schema in the catalog.
  • apis_io_searchSTART HERE — APIs, providers and tags for one query, each with its total.
  • resolveTurn a domain, URL or GitHub org into the provider it belongs to.
  • find_cohortsEvery scored population of providers in the catalog.
All 92 tools →

Call it yourself

curl for this page
This JSON Schema
curl "https://apis.io/api/v1/json-schemas/bettermenu-usage-response"
All schemas
curl "https://apis.io/api/v1/json-schemas?limit=25"

Calls without X-API-Key need no key. Calls with it need a paid plan — get a key.

Get an API key

Free tier, no form to fill in. Signing in shares your email address with us — we store it to create your key and to recognise you if you sign in with another provider. See our Privacy Policy and Terms.

A second provider on the same verified email joins the account you already have.