Knowledge Base: API: Products

Products in Chargify are the things to which you are giving access through Subscriptions.

The Products API currently only allows listing and lookup operations.

Product Attributes

All of the customer attribute fields are returned from GET (read) operations, and all are read only at this time.

• price_in_cents The product price, in integer cents
• name The product name
• handle The product API handle
• description The product description
• product_family Nested attributes pertaining to the product family to which this product belongs
  • name The product family name
  • handle The product family API handle
  • accounting_code The product family accounting code (has no bearing in Chargify, may be used within your app)
  • description The product family description
• accounting_code The accounting code (has no bearing in Chargify, may be used within your app)
• interval_unit A string representing the interval unit for this product, either month or day
• interval The numerical interval. i.e. an interval of '30' coupled with an interval_unit of 'day' would mean this product would renew every 30 days

Methods

List

URL: https://<subdomain>.chargify.com/products.<format>
Method: GET
Response: An array of Products
XML example
JSON example

Read/Show (via Chargify ID)

URL: https://<subdomain>.chargify.com/products/<id>.<format>
Method: GET
Required Parameters: id
Response: An single Product
XML example
JSON example

Read/Show (via API handle)

URL: https://<subdomain>.chargify.com/products/handle/<handle>.<format>
Method: GET
Required Parameters: handle
Response: An single Product
XML example
JSON example

XML List Usage Example

Feature: Chargify API XML Products listing
  In order integrate an app with Chargify
  As a developer
  I want to be able to list my products via the Chargify XML API

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

  Scenario: Retrieve a list of my products
    Given I have 3 products
    When I send a GET request to https://[@subdomain].chargify.com/products.xml
    Then the response status should be "200 OK"
    And the response should be a "products" array with 3 "product" elements

JSON List Usage Example

Feature: Chargify API JSON Products listing
  In order integrate an app with Chargify
  As a developer
  I want to be able to list my products via the Chargify JSON API

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

  Scenario: Retrieve a list of my products
    Given I have 3 products
    When I send a GET request to https://[@subdomain].chargify.com/products.json
    Then the response status should be "200 OK"
    And the response should be a json array with 3 "product" objects

XML Read/Show Usage Example

Feature: Chargify API XML Product read
  In order integrate an app with Chargify
  As a developer
  I want to be able to fetch a product via the Chargify XML API

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


  Scenario: Retrieve a product via Chargify's id
    Given I have a product with these attributes
      | id            | name  | handle | interval | interval_unit | price_in_cents |
      | [@product.id] | Basic | basic  | 1        | month         | 4900           |
    When I send a GET request to https://[@subdomain].chargify.com/products/[@product.id].xml
    Then the response status should be "200 OK"
    And the response should be the xml:
    """
      <?xml version="1.0" encoding="UTF-8"?>
      <product>
        <name>Basic</name>
        <handle>basic</handle>
        <accounting_code>`your value`</accounting_code>
        <description>`your value`</description>
        <interval type="integer">1</interval>
        <interval_unit>month</interval_unit>
        <price_in_cents type="integer">4900</price_in_cents>
        <product_family>
          <accounting_code>`your value`</accounting_code>
          <description >`your value`</description>
          <handle>`your value`</handle>
          <name>`your value`</name>
        </product_family>
      </product>
      """


   Scenario: Attempt to retrieve a product that doesn't exist
     Given I have 0 products
     When I send a GET request to https://[@subdomain].chargify.com/products/999.xml
     Then the response status should be "404 Not Found"


   Scenario: Retrieve a product via the API Handle
     Given I have a product with these attributes
       | id            | name  | handle | interval | interval_unit | price_in_cents |
       | [@product.id] | Basic | basic  | 1        | month         | 4900           |
     When I send a GET request to https://[@subdomain].chargify.com/products/handle/basic.xml
     Then the response status should be "200 OK"
     And the response should be the xml:
     """
     <?xml version="1.0" encoding="UTF-8"?>
     <product>
       <name>Basic</name>
       <handle>basic</handle>
       <accounting_code>`your value`</accounting_code>
       <description>`your value`</description>
       <interval type="integer">1</interval>
       <interval_unit>month</interval_unit>
       <price_in_cents type="integer">4900</price_in_cents>
       <product_family>
         <accounting_code>`your value`</accounting_code>
       <description>`your value`</description>
         <handle>`your value`</handle>
         <name>`your value`</name>
       </product_family>
     </product>
     """


  Scenario: Attempt to retrieve a product, by handle, that doesn't exist
    Given I have 0 products
    When I send a GET request to https://[@subdomain].chargify.com/products/handle/dne.xml
    Then the response status should be "404 Not Found"

JSON Read/Show Usage Example

Feature: Chargify API JSON Product read
  In order integrate an app with Chargify
  As a developer
  I want to be able to fetch a product via the Chargify JSON API

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


  Scenario: Retrieve a product via Chargify's id
     Given I have a product with these attributes
       | id            | name  | handle | interval | interval_unit | price_in_cents |
       | [@product.id] | Basic | basic  | 1        | month         | 4900           |
     When I send a GET request to https://[@subdomain].chargify.com/products/[@product.id].json
     Then the response status should be "200 OK"
     And the response should be the json:
     """
      {
        "product":{
          "price_in_cents":4900,
          "name":"Basic",
          "handle":"basic",
          "product_family":{
            "name":`your value`,
            "handle":`your value`,
            "description":`your value`,
            "accounting_code":`your value`
          },
          "description":`your value`,
          "accounting_code":`your value`,
          "interval_unit":"month",
          "interval":1
        }
      }
      """


   Scenario: Attempt to retrieve a product that doesn't exist
     Given I have 0 products
     When I send a GET request to https://[@subdomain].chargify.com/products/999.json
     Then the response status should be "404 Not Found"


   Scenario: Retrieve a product via the API Handle
     Given I have a product with these attributes
       | id            | name  | handle | interval | interval_unit | price_in_cents |
       | [@product.id] | Basic | basic  | 1        | month         | 4900           |
     When I send a GET request to https://[@subdomain].chargify.com/products/handle/basic.json
     Then the response status should be "200 OK"
     And the response should be the json:
     """
      {
        "product":{
          "price_in_cents":4900,
          "name":"Basic",
          "handle":"basic",
          "product_family":{
            "name":`your value`,
            "handle":`your value`,
            "description":`your value`,
            "accounting_code":`your value`
          },
          "description":`your value`,
          "accounting_code":`your value`,
          "interval_unit":"month",
          "interval":1
        }
      }
      """


  Scenario: Attempt to retrieve a product, by handle, that doesn't exist
    Given I have 0 products
    When I send a GET request to https://[@subdomain].chargify.com/products/handle/dne.json
    Then the response status should be "404 Not Found"