Create Quantity Based Component
Creates a Quantity Based component definition under the specified product family. A Quantity Based component can then be added and “allocated” for a subscription.
When defining a Quantity Based component, you can choose one of two types:
Recurring
Recurring quantity-based components are used to bill for the number of some unit (think monthly software user licenses or the number of pairs of socks in a box-a-month club). This is most commonly associated with billing for user licenses, number of users, number of employees, etc.
One-time
One-time quantity-based components are used to create ad hoc usage charges that do not recur. For example, at the time of signup, you might want to charge your customer a one-time fee for onboarding or other services.
The allocated quantity for one-time quantity-based components immediately gets reset back to zero after the allocation is made.
For more information, see Components Overview.
Hybrid Pricing
A volume, tiered, or stairstep component can combine its primary pricing with a secondary pricing model (the overage_pricing parameter) so both bill as a single invoice line item instead of two. See Hybrid Pricing for requirements and configuration details.
For more information on components, see our documentation here.
If you have the new Catalog experience enabled, taxable components must include a non-blank tax_code. Sending "tax_code": "" returns 422.
Authorization
BasicAuth The username is a Maxio Chargify API key. The password is x.
In: header
Path Parameters
Either the product family's id or its handle prefixed with handle:
Request Body
application/json
Response Body
application/json
application/json
curl -X POST "https://example.com/product_families/string/quantity_based_components.json" \ -H "Content-Type: application/json" \ -d '{ "quantity_based_component": { "name": "Quantity Based Component", "unit_name": "Component", "description": "Example of JSON per-unit component example", "pricing_scheme": "per_unit", "unit_price": "10", "taxable": true, "display_on_hosted_page": true, "allow_fractional_quantities": true, "public_signup_page_ids": [ 323397 ] } }'{ "component": { "id": 292609, "name": "Text messages", "handle": "text-messages", "pricing_scheme": "per_unit", "unit_name": "unit", "unit_price": "10.0", "product_family_id": 528484, "product_family_name": "Cloud Compute Servers", "price_per_unit_in_cents": null, "kind": "quantity_based_component", "archived": false, "taxable": false, "description": null, "default_price_point_id": 2944263, "prices": [ { "id": 55423, "component_id": 30002, "starting_quantity": 1, "ending_quantity": null, "unit_price": "10.0", "price_point_id": 2944263, "formatted_unit_price": "$10.00", "segment_id": null } ], "price_point_count": 1, "price_points_url": "https://demo-3238403362.chargify.com/components/30002/price_points", "default_price_point_name": "Original", "tax_code": null, "recurring": false, "upgrade_charge": null, "downgrade_credit": null, "created_at": "2024-01-23T06:08:05-05:00", "updated_at": "2024-01-23T06:08:05-05:00", "archived_at": null, "hide_date_range_on_invoice": false, "allow_fractional_quantities": false, "use_site_exchange_rate": true, "item_category": null, "accounting_code": null }}Create Metered Component POST
Creates a metered component definition under the specified product family. A metered component can then be added and “allocated” for a subscription. Metered components are used to bill for any type of unit that resets to 0 at the end of the billing period (think daily Google Ads clicks or monthly cell phone minutes). This is most commonly associated with usage-based billing and many other pricing schemes. Note that this is different from recurring quantity-based components, which DO NOT reset to zero at the start of every billing period. If you want to bill for a quantity of something that does not change unless you change it, then you want quantity components, instead. #### Hybrid Pricing A `volume`, `tiered`, or `stairstep` metered component can combine its primary pricing with a secondary pricing model (the `overage_pricing` parameter) so both bill as a single invoice line item instead of two. This does not apply to metered components configured for event-based billing (metric, meter, or formula). See [Hybrid Pricing](https://maxio-test-wp.pages.dev/getting-started/basic-concepts/hybrid-pricing) for requirements and configuration details. For more information on components, see our documentation [here](https://maxio.zendesk.com/hc/en-us/articles/24261141522189-Components-Overview). If you have the new [Catalog experience](https://maxio-test-wp.pages.dev/support/announcements/2026-announcements#new-catalog-experience-and-terminology) enabled, taxable components must include a non-blank `tax_code`. Sending `"tax_code": ""` returns `422`.
Create On/Off Component POST
Creates an On/Off component definition under the specified product family. An On/Off component can then be added and “allocated” for a subscription. On/off components are used for any flat fee, recurring add on (think $99/month for tech support or a flat add on shipping fee). For more information on components, see our documentation [here](https://maxio.zendesk.com/hc/en-us/articles/24261141522189-Components-Overview). If you have the new [Catalog experience](https://maxio-test-wp.pages.dev/support/announcements/2026-announcements#new-catalog-experience-and-terminology) enabled, taxable components must include a non-blank `tax_code`. Sending `"tax_code": ""` returns `422`.