{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://artifacts.apis.io/benjipays-com/json-schema/benjipays-com-usage-response-schema.json",
  "title": "UsageResponse",
  "description": "Usage snapshot response",
  "x-generated": "2026-11-02",
  "x-method": "derived",
  "x-generator": "derive-json-schema.py",
  "x-source": "openapi/benjipays-com-benji-pays-partner-api-openapi.yml#/components/schemas/UsageResponse",
  "type": "object",
  "properties": {
    "data": {
      "type": "array",
      "items": {
        "$ref": "#/$defs/UsageItem"
      },
      "description": "Array of usage items grouped by organization + SKU"
    },
    "pagination": {
      "type": "object",
      "properties": {
        "nextOffset": {
          "anyOf": [
            {
              "type": "number"
            },
            {
              "type": "null"
            }
          ],
          "description": "Offset for next page (null if no more results)"
        },
        "prevOffset": {
          "anyOf": [
            {
              "type": "number"
            },
            {
              "type": "null"
            }
          ],
          "description": "Offset for previous page (null if first page)"
        },
        "limit": {
          "type": "number",
          "description": "Number of items per page"
        },
        "offset": {
          "type": "number",
          "description": "Current offset"
        },
        "hasMore": {
          "type": "boolean",
          "description": "Whether more results are available"
        }
      },
      "required": [
        "nextOffset",
        "prevOffset",
        "limit",
        "offset",
        "hasMore"
      ],
      "additionalProperties": false,
      "description": "Pagination metadata"
    }
  },
  "required": [
    "data",
    "pagination"
  ],
  "additionalProperties": false,
  "$defs": {
    "UsageItem": {
      "type": "object",
      "properties": {
        "organizationId": {
          "type": "string",
          "description": "MongoDB ObjectId of the organization"
        },
        "apiParent": {
          "type": "object",
          "properties": {
            "type": {
              "type": "string",
              "enum": [
                "distributor",
                "partner"
              ],
              "description": "Parent type — distributor or partner"
            },
            "distributorExternalId": {
              "type": "string",
              "description": "Distributor external ID"
            },
            "partnerExternalId": {
              "description": "Partner external ID (present for partner-type orgs)",
              "type": "string"
            },
            "partnerId": {
              "description": "Partner MongoDB ObjectId (present for partner-type orgs)",
              "type": "string"
            }
          },
          "required": [
            "type",
            "distributorExternalId"
          ],
          "additionalProperties": false,
          "description": "API parent — who created the organization"
        },
        "name": {
          "type": "string",
          "description": "Organization name"
        },
        "externalId": {
          "type": "string",
          "description": "External ID from distributor's system"
        },
        "sku": {
          "type": "string",
          "description": "SKU identifier — plan SKU (e.g., BENJI-PRO) for base plan, or BENJI-{PLAN}-OVERAGE-TIER{n} (e.g., BENJI-PRO-OVERAGE-TIER1) for each overage tier"
        },
        "quantity": {
          "type": "number",
          "description": "Quantity — 1 for base plan, per-tier overage count for BENJI-{PLAN}-OVERAGE-TIER{n} rows"
        },
        "trial": {
          "type": "boolean",
          "description": "Whether organization is in trial period"
        },
        "planName": {
          "description": "Plan name (included for base plan SKU, omitted for overage)",
          "type": "string"
        },
        "period": {
          "type": "string",
          "description": "Period in YYYY-MM format"
        }
      },
      "required": [
        "organizationId",
        "apiParent",
        "name",
        "externalId",
        "sku",
        "quantity",
        "trial",
        "period"
      ],
      "additionalProperties": false,
      "description": "Usage item for an organization"
    }
  }
}