Implementation:Mage ai Mage ai Chargebee Item Model Events Schema

Knowledge Sources	Mage Integrations Chargebee API
Domains	Data_Integration, Chargebee, Schema
Last Updated	2026-02-09 00:00 GMT

Overview

JSON Schema definition for Chargebee event records under the item model, used by the Singer-based Chargebee source connector.

Description

This schema defines the structure and types for event data extracted from the Chargebee API when using the item-based billing model. It is loaded by the Chargebee source connector during stream discovery to validate and type-check extracted records. The schema follows the JSON Schema specification and includes top-level properties such as id, occurred_at, source, user, event_type, api_version, object, and webhook_status. It also contains a nested content object that references other item-model schemas via $ref, including coupon, credit_note, customer, gift, invoice, order, payment_source, item, item_price, item_family, promotional_credit, subscription, and transaction. The root type is a nullable object with additionalProperties set to false. At 653 lines, this is a comprehensive event envelope schema for the item pricing model.

Usage

This schema is automatically loaded by the Chargebee source connector during the discovery phase. It defines the available columns and their types for the events stream when configured for the item billing model.

Code Reference

Source Location

• Repository: mage-ai
• File: mage_integrations/mage_integrations/sources/chargebee/schemas/item_model/events.json
• Lines: 1-653

Signature

{
  "type": ["null", "object"],
  "additionalProperties": false,
  "properties": {
    "id": { "type": ["null", "string"] },
    "occurred_at": { "type": ["null", "string"], "format": "date-time" },
    "source": { "type": ["null", "string"] },
    "user": { "type": ["null", "string"] },
    "event_type": { "type": ["null", "string"] },
    "api_version": { "type": ["null", "string"] },
    "object": { "type": ["null", "string"] },
    "webhook_status": { "type": ["null", "string"] },
    "content": {
      "type": ["null", "object"],
      "properties": {
        "coupon": { "$ref": "coupons.json" },
        "credit_note": { "$ref": "credit_notes.json" },
        "customer": { "$ref": "customers.json" },
        "gift": { "$ref": "gifts.json" },
        "invoice": { "$ref": "invoices.json" },
        "order": { "$ref": "orders.json" },
        "payment_source": { "$ref": "payment_sources.json" },
        "item": { "$ref": "items.json" },
        "item_price": { "$ref": "item_prices.json" },
        "item_family": { "$ref": "item_families.json" },
        "subscription": { "$ref": "subscriptions.json" },
        "transaction": { "..." }
      }
    }
  }
}

Import

# Loaded automatically by Source.load_schemas_from_folder()
# Path: mage_integrations/mage_integrations/sources/chargebee/schemas/item_model/events.json

I/O Contract

Inputs

Name	Type	Required	Description
(none)	JSON file	Yes	Loaded from disk by schema loader

Outputs

Name	Type	Description
schema	dict	JSON Schema object with properties, types, format constraints, and $ref references to related item-model schemas

Usage Examples

import json
import os

# Schema is auto-loaded by the Chargebee source connector
# Manual loading example:
schema_path = os.path.join(
    "mage_integrations/mage_integrations/sources/chargebee/schemas/item_model",
    "events.json"
)
with open(schema_path) as f:
    schema = json.load(f)

# schema["properties"] contains field definitions
print(list(schema["properties"].keys()))
# The content property contains $ref references to other schemas
print(list(schema["properties"]["content"]["properties"].keys()))

Related Pages

Implements Principle

• Principle:Mage_ai_Mage_ai_JSON_Schema_Loading

Requires Environment

• Environment:Mage_ai_Mage_ai_Python_3_9_Runtime