API: Components

Components are defined and associated with a product family. They become a part of your product offering. These component definitions determine what components are named, how they are measured, and how much they cost.

Components can then be added and “allocated” for each subscription to a product in the product family. These component line-items affect how much a subscription will be charged, depending on the current allocations (i.e. 4 IP Addresses, or SSL “enabled”)

This documentation covers both component definitions and component line-items. Please understand the difference.

URI/Method

Resource/URI GET POST PUT DELETE
Component Definitions
/product_families/<x>/components 		List component definitions – – –
Component Definition
/product_families/<x>/components/<y> 		Read a component definition – – –
Component Definition
/product_families/<x>/[plural_kind] 		– Create a Component definition – –
Components Line-Items
/subscriptions/<x>/components 		List component line-items belonging to a Subscription – – –
Component Line-Item
/subscriptions/<x>/components/<y> 		Read a component line-item belonging to a Subscription – – –

Component Definition Input Attributes

These values should be nested beneath a key that defines the kind of component being created or updated. Valid values are on_off_component, quantity_based_component, and metered_component

  • name The name of the Component, suitable for display to customers on statements. i.e. “Text Messages”.
  • unit_name (Not required for On/Off Components) The name of the unit of measurement for the component. It should be singular since it will be automatically pluralized when necessary. i.e. “message”, which may then be shown as “5 messages” on a subscription’s component line-item
  • unit_price The amount the customer will be charged per unit when the pricing scheme is “per_unit”. For On/Off Components, this is the amount that the customer will be charged when they turn the component on for the subscription. The price can contain up to 4 decimal places. i.e. 1.00 or 0.0012
  • pricing_scheme (Not required for On/Off Components) The identifier for the pricing scheme. Available options: per_unit, volume, tiered, stairstep. See Product Components for an overview of pricing schemes.
  • prices (Not required for On/Off Components or ‘per_unit’ pricing schemes) One or more price brackets. See Product Components for an overview of how price brackets work for different pricing schemes.
    • starting_quantity
    • ending_quantity
    • unit_price

Component Definition Output Attributes

Component definitions refer to the components you create that become available to subscriptions. This differs from what we are calling “component line-items”, which detail the attachment of the component to a subscription (and are documented below).

  • id The unique ID assigned to the component by Chargify. This ID can be used to fetch the component from the API.
  • name The name of the Component, suitable for display on statements. i.e. Text Messages.
  • unit_name_ The name of the unit that the component’s usage is measured in. i.e. message
  • unit_price The amount the customer will be charged per unit. This field is only populated for ‘per_unit’ pricing schemes, otherwise it may be null.
  • pricing_scheme The handle for the pricing scheme. Available options: per_unit, volume, tiered, stairstep. See Product Components for an overview of pricing schemes.
  • prices An array of price brackets. If the component uses the ‘per_unit’ pricing scheme, this array will be empty.
    • starting_quantity
    • ending_quantity
    • unit_price
  • product_family_id The id of the Product Family to which the Component belongs
  • kind A handle for the component type: metered_component, quantity_based_component, on_off_component
  • price_per_unit_in_cents (This field is deprecated (see note below)) This represents the unit price prior to the Chargify upgrade to fractional cent component pricing. This field may no longer represent the correct unit price of the component. The unit_price field should be used instead.
  • archived Boolean flag describing whether a component is archived or not.

In May 2011, we added the ability to create components with fractional cent pricing (i.e. $0.0012 per unit). To accommodate this change we made some adjustments on our end that altered how prices are stored. Because of this, we have deprecated the price_in_cents field in favor of the unit_price field. The price_in_cents field is still returned for backwards compatibility, but may not accurately represent the current state of the component if it has been updated since the change. We recommend updating your API calls to use the unit_price field as soon as possible.

Component Line-Item Input Attributes

The attributes listed in the following sections should be nested under the component key, e.g. the following JSON could be used to update the allocated_quantity on a Component Line-Item:


{
  "component": {
    "allocated_quantity": 23
  }
}

Inputs for Quantity-Based Line-Items

  • allocated_quantity The current allocation for the component on the given subscription.

For more, see also API: Quantity Component Allocations

Inputs for On/Off Line-Items

  • enabled A boolean that controls whether the component is “On” for a given subscription. Valid values are true/false, on/off, yes/no, t/f, y/n, 1/0

Inputs for Metered Line-Items

The Metered Component usages for a subscription are managed through the Metered Usage API

Component Line-Item Output Attributes

All component line-item kinds share the following attributes:

  • subscription_id
  • component_id
  • name
  • unit_name
  • kind

Then, each line-item has an indication of the current allocation on the given subscription, depending on the kind:

  • enabled Provided when kind is on_off_component
  • allocated_quantity Provided when kind is quantity_based_component
  • unit_balance Provided when kind is metered_component and gives the TOTAL of all reported usages for the period

Methods

format may be either ‘xml’ or ‘json’.

List Components for a Subscription

URL: https://<subdomain>.chargify.com/subscriptions/<subscription_id>/components.<format>
Method: GET
Required Parameters:
subscription_id: The id of the subscription from which you want to get a listing of applied components
Optional Parameters:
Response: An array of Components
Usage Examples:
XML example
JSON example

Read Component for a Subscription

URL: https://<subdomain>.chargify.com/subscriptions/<subscription_id>/components/<component_id>.<format>
Method: GET
Required Parameters:
subscription_id: The id of the applicable subscription
component_id: The id of the component you want to retrieve information about
Response: A component
Usage Examples:
XML example
JSON example

List Components for a Product Family

URL: https://<subdomain>.chargify.com/product_families/<product_family_id_>/components.<format>
Method: GET
Required Parameters:
product_family_id: The id of the product family from which you want to get a listing of available components
include_archived: Boolean, default 0. If 1 is sent then archived components will also be included.
Response: An array of Components

Read Component for a Product Family

URL: https://<subdomain>.chargify.com/product_families/<product_family_id_>/components/<component_id>.<format>
Method: GET
Required Parameters:
subscription_id: The id of the applicable product family
component_id: The id of the component you want to retrieve information about
Response: A component

Create Component

URL: https://<subdomain>.chargify.com/product_families/<product_family_id_>/<plural_kind_>.<format>
Method: POST
Required Parameters:
product_family_id: The id of the product family from which you want to get a listing of available components
plural_kind: The endpoint for the type of component you want to create. Valid values: metered_components, quantity_based_components, on_off_components
XML or JSON data: Specified by the required attributes
Response: A component
Usage Examples:
XML example
JSON example

Usage Examples

XML List Components Example


Feature: Chargify Components List for a Subscription XML API
  In order integrate my app with Chargify
  As a developer
  I want to interact with my components via the Chargify API

  Background:
    Given I am a valid API user
    And I accept xml responses

  Scenario: Retrieve a customer's subscriptions
    Given I have an active subscription
    And the subscription has 2 components
    When I send a GET request to https://[@subdomain].chargify.com/subscriptions/[@subscription.id]/components.xml
    Then the response status should be "200 OK"
    And the response should be a "components" array with 2 "component" elements

JSON List Components Example


Feature: Chargify Components List for a Subscription JSON API
  In order integrate my app with Chargify
  As a developer
  I want to interact with my components via the Chargify API

  Background:
    Given I am a valid API user
    And I accept json responses

  Scenario: Retrieve a customer's subscriptions
    Given I have an active subscription
    And the subscription has 2 components
    When I send a GET request to https://[@subdomain].chargify.com/subscriptions/[@subscription.id]/components.json
    Then the response status should be "200 OK"
    And the response should be a "components" array with 2 "component" elements

XML Read Component Example


Feature: Chargify Component Read/Show/Lookup for a Subscription XML API
  In order integrate my app with Chargify
  As a developer
  I want to read/show/lookup a component as applied to a subscription via the Chargify XML API

  Background:
    Given I am a valid API user
    And I accept xml responses

  Scenario: Retrieve a component for a subscription via ID
    Given I have an active subscription
    When I send a GET request to https://[@subdomain].chargify.com/subscriptions/[@subscription.id]/components/[@component.id].xml
    Then the response status should be "200 OK"
    And print the response
    And the response should be the xml:
      """
      <?xml version="1.0" encoding="UTF-8"?>
	<components type="array">
	  <component>
             <component_id type="integer">[@component.id]</component_id>
             <subscription_id type="integer">[@subscription.id]</subscription_id>
             <unit_balance type="integer">`auto generated`</unit_balance>
             <name>`auto generated`</name>
             <unit_name>`auto generated`</unit_name>
             <kind>`auto generated`</kind>
	  </component>
	</component>
      """

  Scenario: Attempt to retrieve a component that hasn't been applied to a subscription
    Given I have no applicable
    When I send a GET request to https://[@subdomain].chargify.com/subscriptions/[@subscription.id]/components/9999.xml
    Then the response status should be "404 Not Found"

JSON Read Component Example


Feature: Chargify Subscriptions Read/Show/Lookup JSON API
  In order integrate my app with Chargify
  As a developer
  I want to read/show/lookup a subscription via the Chargify JSON API

  Background:
    Given I am a valid API user
    And I accept json responses

  Scenario: Retrieve a subscription via ID
    Given I have an active subscription
    When I send a GET request to https://[@subdomain].chargify.com/subscriptions/[@subscription.id].json
    Then the response status should be "200 OK"
    And the response should be the json:
      """
	{ "component": {
            "kind": "`auto generated`",
            "name": "`auto generated`",
            "unit_balance": `auto generated`,
            "subscription_id": [@subscription.id],
            "component_id": [@component.id],
            "unit_name": "`auto generated`"
          }
	}
      """

  Scenario: Attempt to retrieve a component that hasn't been applied to a subscription
    Given I have no applicable component
    When I send a GET request to https://[@subdomain].chargify.com/subscriptions/[@subscription.id]/components/9999.json
    Then the response status should be "404 Not Found"

JSON Create Component Example


  Feature: Create Metered Component
    In order integrate my app with Chargify
    As a developer
    I want to create a metered component via the Chargify JSON API

    Background:
      Given I am a valid API user
      And I send and accept json

    Scenario: Successfully create a metered component with per_unit pricing
      Given I have 1 product
      And I have this json metered_component data
        """
        {"metered_component":{
          "name":"Text messages",
          "unit_name": "text message",
          "pricing_scheme": "stairstep",
          "prices":[
            {"starting_quantity":1, "unit_price":1.0, "component":null}
          ]
        }}
        """
      When I send a POST request with the json data to https://[@subdomain].chargify.com/product_families/[@product_family.id]/metered_components.json
      Then the response status should be "201 Created"

XML Create Component Example


  Feature: Create Quanitity Component
    In order integrate my app with Chargify
    As a developer
    I want to create a quantity-based component via the Chargify XML API

    Background:
      Given I am a valid API user
      And I send and accept xml

    Scenario: Successfully create a quantity-based component with per_unit pricing
      Given I have 1 product
      And I have this xml quantity_based_component data
        """
        <?xml version="1.0" encoding="UTF-8"?>
        <quantity_based_component>
          <name>Swizzles</name>
          <unit_name>I.P Addresses</unit_name>
          <pricing_scheme>per_unit</pricing_scheme>
          <unit_price>1.00</unit_price>
        </quantity_based_component>
        """
      When I send a POST request with the xml data to https://[@subdomain].chargify.com/product_families/[@product_family.id]/quantity_based_components.xml
      Then the response status should be "201 Created"
	  
	Scenario: Successfully create a metered component with per_unit pricing
      Given I have 1 product
      And I have this xml metered_component data
        """
        <?xml version="1.0" encoding="UTF-8"?>
        <metered_component>
          <name>Swizzles</name>
          <unit_name>ip</unit_name>
          <pricing_scheme>per_unit</pricing_scheme>
          <unit_price>1.00</unit_price>
        </metered_component>
        """
      When I send a POST request with the xml data to https://[@subdomain].chargify.com/product_families/[@product_family.id]/metered_components.xml
      Then the response status should be "201 Created"