Chargify Documentation » Chargify API Resources

API: Components

URI/Method

Resource/URI	GET	POST	PUT	DELETE
Components `/subscriptions/<x>/components`	List components belonging to a Subscription	–	–	–
Compoment `/subscriptions/<x>/components/<y>`	Read a component belonging to a Subscription	–	–	–
Components `/product_families/<x>/components`	List components belonging to a Product Family	–	–	–
Compoment `/product_families/<x>/components/<y>`	Read a component belonging to a Product Family	–	–	–
Compoment `/product_families/<x>/[component_type]`	–	Create Component	–	–

Component Input Attributes

name The name of the Component. i.e. Text Messages.
unit_name_ (Not required for On/Off Components) 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. The price can contain up to 4 decimal places. i.e. $1.00, $0.0012, etc.
pricing_scheme (Not required for On/Off Components) The handle 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 Output Attributes

In addition to the Input attributes, the following Output attributes are returned.

name The name of the Component. 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.
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 that the Component belongs to
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.

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_>/<component_type>.<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
compontent_type_: The endpoint for the type of component you want to create. Options: 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>address</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"

Next page: API: Coupons
Previous page: API: Charges