{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://artifacts.apis.io/benjipays-com/json-schema/benjipays-com-billing-response-schema.json",
  "title": "BillingResponse",
  "description": "Billing response with finalized billing data",
  "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/BillingResponse",
  "type": "object",
  "properties": {
    "data": {
      "type": "array",
      "items": {
        "$ref": "#/$defs/BillingItem"
      },
      "description": "Array of billing items grouped by organization and SKU"
    },
    "pagination": {
      "type": "object",
      "properties": {
        "nextOffset": {
          "anyOf": [
            {
              "type": "number"
            },
            {
              "type": "null"
            }
          ],
          "description": "Offset for next page (null if no more pages)"
        },
        "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": "Offset-based pagination metadata"
    }
  },
  "required": [
    "data",
    "pagination"
  ],
  "additionalProperties": false,
  "$defs": {
    "BillingItem": {
      "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 when type is partner)",
              "type": "string"
            },
            "partnerId": {
              "description": "Partner MongoDB ObjectId (present when type is partner)",
              "type": "string"
            }
          },
          "required": [
            "type",
            "distributorExternalId"
          ],
          "additionalProperties": false,
          "description": "API parent — distributor and optional partner"
        },
        "name": {
          "type": "string",
          "description": "Organization name"
        },
        "externalId": {
          "description": "External ID from distributor's system",
          "type": "string"
        },
        "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 for this SKU"
        },
        "unitPrice": {
          "type": "number",
          "description": "Price per unit"
        },
        "total": {
          "type": "number",
          "description": "Total price (quantity × unitPrice)"
        },
        "trial": {
          "type": "boolean",
          "description": "Whether organization is on trial"
        },
        "planName": {
          "description": "Plan name (e.g., pro, starter)",
          "type": "string"
        },
        "period": {
          "type": "string",
          "description": "Billing period (YYYY-MM)"
        }
      },
      "required": [
        "organizationId",
        "apiParent",
        "name",
        "sku",
        "quantity",
        "unitPrice",
        "total",
        "trial",
        "period"
      ],
      "additionalProperties": false,
      "description": "Billing line item for an organization + SKU combination"
    }
  }
}