API: Metered Usage

URI/Methods

TODO

Input Attributes

The Chargify API allows you to record metered component usage by posting JSON or XML that includes:

  • quantity: The amount of units used
  • memo: An optional description of the usage

Methods

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

List Usage

URL: https://<subdomain>.chargify.com/subscriptions/<subscription_id>/components/<component_id>/usages.json
Method: GET
Required Parameters: subscription_id, component_id
Optional Parameters:

  • since_id Returns usages with an id greater than or equal to the one specified
  • max_id Returns usages with an id less than or equal to the one specified
  • created_at The creation date for this usage
  • page and per_page The page number and number of results used for pagination. By default results are paginated 20 per page.

Response: A collection of usages

Usage Examples:
XML example
JSON example

Create Usage

URL: https://<subdomain>.chargify.com/subscriptions/<subscription_id>/components/<component_id>/usages.json
Method: POST
Required Parameters: XML or JSON data, as specified by the required attributes

Response: The created usage log

Usage Examples:
XML example
JSON example

List Components for a Product Family

URL: https://<subdomain>.chargify.com/product_families/<product_family_id>/components.xml
Method: GET
Required Parameters: product_family_id

Response: A collection of components

Usage Examples:
XML example
JSON example

Usage Examples

XML List Usage Example


Feature: Chargify Metered Component Usage XML API
  In order integrate my app with Chargify
  As a developer
  I want to view a list the usages associated with a subscription

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

  Scenario: List metered component usages for a subscription
    Given I have 1 product
    And the product family has a metered component
    And I have an active subscription to the first product
    And the component is associated with the subscription
    And the component has 2 usages
    When I send a GET request to https://[@subdomain].chargify.com/subscriptions/[@subscription.id]/components/[@component.id]/usages.xml
    Then the response status should be "200 OK"
    And the response should be a "usages" array with 2 "usage" elements

JSON List Usage Example


Feature: Chargify Metered Component Usage JSON API
  In order integrate my app with Chargify
  As a developer
  I want to view a list the usages associated with a subscription

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

  Scenario: List metered component usages for a subscription
    Given I have 1 product
    And the product family has a metered component
    And I have an active subscription to the first product
    And the component is associated with the subscription
    And the component has 2 usages
    When I send a GET request to https://[@subdomain].chargify.com/subscriptions/[@subscription.id]/components/[@component.id]/usages.json
    Then the response status should be "200 OK"
    And the response should be a json array with 2 "usage" objects

XML Create Usage Example


Feature: Chargify Metered Component Usage XML API
  In order integrate my app with Chargify
  As a developer
  I want to record metered usage for a subscription

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

  Scenario: Record metered usage
    Given I have 1 product
    And the product family has a metered component
    And I have an active subscription to the first product
    And I have this xml usage data
      """
        <?xml version="1.0" encoding="UTF-8"?>
        <usage>
          <quantity>5</quantity>
          <memo>My Memo</memo>
        </usage>
      """
    When I send a POST request with the xml data to https://[@subdomain].chargify.com/subscriptions/[@subscription.id]/components/[@component.id]/usages.xml
    Then the response status should be "200 OK"
    And the response should be the xml:
      """
        <?xml version="1.0" encoding="UTF-8"?>
        <usage>
          <id>@auto generated@</id>
          <quantity type="integer">5</quantity>
          <memo>My Memo</memo>
        </usage>
      """    
    And a usage will have been recorded

JSON Create Usage Example


Feature: Chargify Metered Component Usage JSON API
  In order integrate my app with Chargify
  As a developer
  I want to record metered usage for a subscription

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

  Scenario: Record metered usage
    Given I have 1 product
    And the product family has a metered component
    And I have an active subscription to the first product
    And I have this json usage data
      """
      {
        "usage":{
          "quantity":5,
          "memo":"My memo"
        }
      }
      """
    When I send a POST request with the json data to https://[@subdomain].chargify.com/subscriptions/[@subscription.id]/components/[@component.id]/usages.json
    Then the response status should be "200 OK"
    And the response should be the json:
      """
      {
        "usage":{
          "id":@auto generated@,
          "quantity":5,
          "memo":"My memo"
        }
      }
      """
    And a usage will have been recorded

XML List Components for a Product Family


Scenario: List metered components in product family
  Given I have 1 product
  And the product family has a metered component
  When I send a GET request to https://[@subdomain].chargify.com/product_families/[@product_family.id]/components.xml
  Then the response status should be "200 OK"
  And the response should be a "components" array with 1 "component" element

JSON List Components for a Product Family


Scenario: List metered components in product family
  Given I have 1 product
  And the product family has a metered component
  When I send a GET request to https://[@subdomain].chargify.com/product_families/[@product_family.id]/components.json
  Then the response status should be "200 OK"
  And the response should be a json array with 1 "component" object