Component

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://artifacts.apis.io/maxio/json-schema/maxio-component-schema.json",
  "title": "Component",
  "x-generated": "2026-11-10",
  "x-method": "derived",
  "x-generator": "derive-json-schema.py",
  "x-source": "openapi/maxio-advanced-billing-openapi.yml#/components/schemas/Component",
  "type": "object",
  "properties": {
    "id": {
      "type": "integer",
      "description": "The unique ID assigned to the component by Chargify. This ID can be used to fetch the component from the API.",
      "contentEncoding": "int32"
    },
    "name": {
      "type": "string",
      "description": "The name of the Component, suitable for display on statements. e.g., Text Messages."
    },
    "handle": {
      "type": [
        "string",
        "null"
      ],
      "description": "The component API handle"
    },
    "pricing_scheme": {
      "allOf": [
        {
          "oneOf": [
            {},
            {
              "$ref": "#/$defs/PricingScheme"
            }
          ]
        },
        {}
      ]
    },
    "unit_name": {
      "type": "string",
      "description": "The name of the unit that the component’s usage is measured in. e.g., message"
    },
    "unit_price": {
      "type": [
        "string",
        "null"
      ],
      "description": "The amount the customer will be charged per unit. This field is only populated for ‘per_unit’ pricing schemes, otherwise it may be null."
    },
    "product_family_id": {
      "type": [
        "integer",
        "null"
      ],
      "description": "The id of the Product Family to which the Component belongs. `null` for a Wallet Product, which has no Product Family.",
      "contentEncoding": "int32"
    },
    "product_family_name": {
      "type": [
        "string",
        "null"
      ],
      "description": "The name of the Product Family to which the Component belongs. `null` for a Wallet Product, which has no Product Family."
    },
    "product_family_handle": {
      "type": [
        "string",
        "null"
      ],
      "description": "The handle of the Product Family to which the Component belongs. `null` for a Wallet Product, which has no Product Family."
    },
    "price_per_unit_in_cents": {
      "type": [
        "integer",
        "null"
      ],
      "description": "deprecated - use unit_price instead.",
      "contentEncoding": "int64"
    },
    "kind": {
      "allOf": [
        {
          "$ref": "#/$defs/ComponentKind"
        },
        {
          "description": "A handle for the component type"
        }
      ]
    },
    "archived": {
      "type": "boolean",
      "description": "Boolean flag describing whether a component is archived or not."
    },
    "description": {
      "type": [
        "string",
        "null"
      ],
      "description": "The description of the component."
    },
    "default_price_point_id": {
      "type": [
        "integer",
        "null"
      ],
      "contentEncoding": "int32"
    },
    "overage_prices": {
      "type": [
        "array",
        "null"
      ],
      "items": {
        "$ref": "#/$defs/ComponentPrice"
      },
      "description": "Applicable only to prepaid usage components. An array of overage price brackets."
    },
    "prices": {
      "type": [
        "array",
        "null"
      ],
      "items": {
        "$ref": "#/$defs/ComponentPrice"
      },
      "description": "An array of price brackets. If the component uses the ‘per_unit’ pricing scheme, this array will be empty."
    },
    "price_point_count": {
      "type": "integer",
      "description": "Count for the number of price points associated with the component",
      "contentEncoding": "int32"
    },
    "price_points_url": {
      "type": [
        "string",
        "null"
      ],
      "description": "URL that points to the location to read the existing price points via GET request"
    },
    "default_price_point_name": {
      "type": "string"
    },
    "taxable": {
      "type": "boolean",
      "description": "Boolean flag describing whether a component is taxable or not."
    },
    "tax_code": {
      "type": [
        "string",
        "null"
      ],
      "description": "A string representing the tax code related to the component type. This is especially important when using AvaTax to tax based on locale. This attribute has a max length of 25 characters."
    },
    "recurring": {
      "type": "boolean"
    },
    "upgrade_charge": {
      "allOf": [
        {
          "oneOf": [
            {},
            {
              "$ref": "#/$defs/CreditType"
            }
          ]
        },
        {
          "description": "The type of credit to be created when upgrading/downgrading. Defaults to the component and then site setting if one is not provided."
        }
      ]
    },
    "downgrade_credit": {
      "allOf": [
        {
          "oneOf": [
            {},
            {
              "$ref": "#/$defs/CreditType"
            }
          ]
        },
        {
          "description": "The type of credit to be created when upgrading/downgrading. Defaults to the component and then site setting if one is not provided."
        }
      ]
    },
    "created_at": {
      "type": "string",
      "description": "Timestamp indicating when this component was created",
      "contentEncoding": "date-time"
    },
    "updated_at": {
      "type": "string",
      "description": "Timestamp indicating when this component was updated",
      "contentEncoding": "date-time"
    },
    "archived_at": {
      "type": [
        "string",
        "null"
      ],
      "description": "Timestamp indicating when this component was archived",
      "contentEncoding": "date-time"
    },
    "hide_date_range_on_invoice": {
      "type": "boolean",
      "description": "(Only available on Relationship Invoicing sites) Boolean flag describing if the service date range should show for the component on generated invoices."
    },
    "allow_fractional_quantities": {
      "type": "boolean"
    },
    "item_category": {
      "allOf": [
        {
          "oneOf": [
            {},
            {
              "$ref": "#/$defs/ItemCategory"
            }
          ]
        },
        {
          "description": "One of the following: Business Software, Consumer Software, Digital Services, Physical Goods, Other"
        }
      ]
    },
    "use_site_exchange_rate": {
      "type": [
        "boolean",
        "null"
      ]
    },
    "accounting_code": {
      "type": [
        "string",
        "null"
      ],
      "description": "E.g. Internal ID or SKU Number"
    },
    "event_based_billing_metric_id": {
      "type": "integer",
      "description": "(Only for Event Based Components) This is an ID of a metric attached to the component. This metric is used to bill upon collected events.",
      "contentEncoding": "int32"
    },
    "interval": {
      "type": "integer",
      "description": "The numerical interval. e.g., an interval of ‘30’ coupled with an interval_unit of day would mean this component’s default price point would renew every 30 days. This property is only available for sites with Multifrequency enabled.",
      "contentEncoding": "int32"
    },
    "interval_unit": {
      "allOf": [
        {
          "oneOf": [
            {},
            {
              "$ref": "#/$defs/IntervalUnit"
            }
          ]
        },
        {
          "description": "A string representing the interval unit for this component's default price point, either month or day. This property is only available for sites with Multifrequency enabled."
        }
      ]
    },
    "unspsc_code": {
      "type": [
        "string",
        "null"
      ],
      "description": "(Optional) Custom UNSPSC commodity code for Level 3/CEDP payment data. When set, this value is sent as the commodity code on invoice line items for this component instead of the default derived from item_category."
    },
    "features": {
      "type": [
        "array",
        "null"
      ],
      "items": {
        "$ref": "#/$defs/FeatureCatalogItem"
      },
      "description": "The active feature catalog items attached to this component. Present only when the request includes `include_features=true`."
    }
  },
  "$defs": {
    "ComponentKind": {
      "title": "ComponentKind",
      "enum": [
        "metered_component",
        "quantity_based_component",
        "on_off_component",
        "prepaid_usage_component",
        "event_based_component",
        "wallet_product"
      ],
      "type": "string",
      "description": "A handle for the component type"
    },
    "ComponentPrice": {
      "title": "ComponentPrice",
      "type": "object",
      "properties": {
        "id": {
          "type": "integer",
          "contentEncoding": "int32"
        },
        "component_id": {
          "type": "integer",
          "contentEncoding": "int32"
        },
        "starting_quantity": {
          "type": "integer",
          "contentEncoding": "int32"
        },
        "ending_quantity": {
          "type": [
            "integer",
            "null"
          ],
          "contentEncoding": "int32"
        },
        "unit_price": {
          "type": "string"
        },
        "price_point_id": {
          "type": "integer",
          "contentEncoding": "int32"
        },
        "formatted_unit_price": {
          "type": "string"
        },
        "segment_id": {
          "type": [
            "integer",
            "null"
          ],
          "contentEncoding": "int32"
        }
      }
    },
    "CreditType": {
      "title": "CreditType",
      "enum": [
        "full",
        "prorated",
        "none"
      ],
      "type": "string",
      "description": "The type of credit to be created when upgrading/downgrading. Defaults to the component and then site setting if one is not provided."
    },
    "EntitlementPeriodicityUnit": {
      "title": "EntitlementPeriodicityUnit",
      "enum": [
        "hour",
        "day",
        "week",
        "month",
        "year"
      ],
      "type": "string",
      "description": "The recurring window over which a `usage_limit` feature's allowance resets."
    },
    "FeatureCatalogItem": {
      "title": "FeatureCatalogItem",
      "type": "object",
      "properties": {
        "id": {
          "type": "integer",
          "contentEncoding": "int32"
        },
        "feature_template_id": {
          "type": "integer",
          "description": "The id of the feature template this item was created from.",
          "contentEncoding": "int32"
        },
        "feature_key": {
          "type": "string",
          "description": "The `key` of the parent feature template."
        },
        "feature_name": {
          "type": "string",
          "description": "The `name` of the parent feature template."
        },
        "feature_kind": {
          "allOf": [
            {
              "$ref": "#/$defs/FeatureKind"
            },
            {
              "description": "The behavior of a feature:\n- `access_right`: a boolean entitlement. A subscriber either has access or does not.\n- `usage_limit`: a quantified allowance measured over a recurring period (for example, \"10,000 API calls per month\").\n- `service_right`: a free-form value (text, boolean, or number) that isn't a simple access flag or a metered limit."
            }
          ]
        },
        "value": {
          "type": "string",
          "description": "The value granted by this feature catalog item. Interpreted according to `feature_kind`: `\"true\"`/`\"false\"` for `access_right`, a numeric string for `usage_limit`, or any string for `service_right` (shaped by the feature template's `value_type`)."
        },
        "periodicity_interval": {
          "type": [
            "integer",
            "null"
          ],
          "description": "Set when `feature_kind` is `usage_limit`; `null` otherwise.",
          "contentEncoding": "int32"
        },
        "periodicity_unit": {
          "allOf": [
            {
              "oneOf": [
                {},
                {
                  "$ref": "#/$defs/EntitlementPeriodicityUnit"
                }
              ]
            },
            {
              "description": "Set when `feature_kind` is `usage_limit`; `null` otherwise."
            }
          ]
        },
        "price_point_type": {
          "allOf": [
            {
              "oneOf": [
                {},
                {
                  "$ref": "#/$defs/FeatureOwnerPricePointType"
                }
              ]
            },
            {
              "description": "`null` when this feature catalog item applies to every price point of its owning product/component. Set when the feature catalog item is an override for one specific price point."
            }
          ]
        },
        "price_point_id": {
          "type": [
            "integer",
            "null"
          ],
          "description": "Set together with `price_point_type` for price-point-specific overrides.",
          "contentEncoding": "int32"
        },
        "archived_at": {
          "type": [
            "string",
            "null"
          ],
          "contentEncoding": "date-time"
        },
        "created_at": {
          "type": "string",
          "contentEncoding": "date-time"
        },
        "updated_at": {
          "type": "string",
          "contentEncoding": "date-time"
        }
      },
      "description": "A feature template attached to a specific product or component (or one of their price points), with a concrete value. When a subscriber signs up for or is assigned this product/component, the feature catalog item is provisioned as an entitlement on their subscription."
    },
    "FeatureKind": {
      "title": "FeatureKind",
      "enum": [
        "access_right",
        "usage_limit",
        "service_right"
      ],
      "type": "string",
      "description": "The behavior of a feature:\n- `access_right`: a boolean entitlement. A subscriber either has access or does not.\n- `usage_limit`: a quantified allowance measured over a recurring period (for example, \"10,000 API calls per month\").\n- `service_right`: a free-form value (text, boolean, or number) that isn't a simple access flag or a metered limit."
    },
    "FeatureOwnerPricePointType": {
      "title": "FeatureOwnerPricePointType",
      "enum": [
        "ProductPricePoint",
        "PricePoint"
      ],
      "type": "string",
      "description": "Identifies which kind of price point a feature catalog item override applies to: `ProductPricePoint` for a product price point, `PricePoint` for a component price point. Only relevant when `price_point_id` is set."
    },
    "IntervalUnit": {
      "title": "IntervalUnit",
      "enum": [
        "day",
        "month"
      ],
      "type": "string"
    },
    "ItemCategory": {
      "title": "ItemCategory",
      "enum": [
        "Business Software",
        "Consumer Software",
        "Digital Services",
        "Physical Goods",
        "Other"
      ],
      "type": "string",
      "description": "One of the following: Business Software, Consumer Software, Digital Services, Physical Goods, Other"
    },
    "PricingScheme": {
      "title": "PricingScheme",
      "enum": [
        "stairstep",
        "volume",
        "per_unit",
        "tiered"
      ],
      "type": "string",
      "description": "The identifier for the pricing scheme. See [Product Components](https://help.chargify.com/products/product-components.html) for an overview of pricing schemes."
    }
  }
}