API: Products

Product Attributes

All of the product attribute fields are returned from GET (read) operations.

  • 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
  • initial_charge_in_cents The up front charge you have specified.
  • trial_price_in_cents The price of the trial period for a subscription to this product, in integer cents.
  • trial_interval A numerical interval for the length of the trial period of a subscription to this product. See the description of interval for a description of how this value is coupled with an interval unit to calculate the full interval
  • trial_interval_unit A string representing the trial interval unit for this product, either month or day
  • expiration_interval A numerical interval for the length a subscription to this product will run before it expires. See the description of interval for a description of how this value is coupled with an interval unit to calculate the full interval
  • expiration_interval_unit A string representing the trial interval unit for this product, either month or day
  • version_number The version of the product
  • update_return_url The url to which a customer will be returned after a successful account update
  • update_return_params The parameters will append to the url after a successful account update. See Return URLs and Parameters
  • require_credit_card Boolean
  • request_credit_card Boolean
  • created_at Timestamp indicating when this product was created
  • updated_at Timestamp indicating when this product was last updated
  • archived_at Timestamp indicating when this product was archived
  • public_signup_pages An array of signup pages containing the following attributes:
    • id The id of the signup page
    • url The url where the signup page can be viewed
    • return_url The url to which a customer will be returned after a successful signup
    • return_params The params to be appended to the return_url

Input Attributes (Create)

  • price_in_cents The product price, in integer cents
  • name The product name
  • handle The product API handle
  • description The product description
  • product_family_id The ID of the product family to which the product belongs.
  • 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
  • initial_charge_in_cents The up front charge you have specified.
  • trial_price_in_cents The price of the trial period for a subscription to this product, in integer cents.
  • trial_interval A numerical interval for the length of the trial period of a subscription to this product. See the description of interval for a description of how this value is coupled with an interval unit to calculate the full interval
  • trial_interval_unit A string representing the trial interval unit for this product, either month or day
  • expiration_interval A numerical interval for the length a subscription to this product will run before it expires. See the description of interval for a description of how this value is coupled with an interval unit to calculate the full interval
  • expiration_interval_unit A string representing the trial interval unit for this product, either month or day
  • require_credit_card Boolean
  • request_credit_card Boolean
  • require_billing_address Boolean
  • request_billing_address Boolean
  • taxable Boolean
  • trial_type The type of trial for this product, either no_obligation or payment_expected.
  • auto_create_signup_page A true or false value (default true) indicating whether or not you want a Public Page" to be automatically created for this product
  • update_return_url The url to which a customer will be returned after a successful account update.
  • return_url If auto_create_signup_page is true, this will set the url to which a customer will be returned after a successful signup for the auto-created signup page.
  • return_params The parameters to be appended to both update_return_url and, (if auto_create_signup_page is true,) return_url for the auto-created signup page. See Return URLs and Parameters.

Input Attributes (Update)

Methods

List

URL: https://<subdomain>.chargify.com/products.<format>
Method: GET

Response: An array of Products

XML example
JSON example

List products for a Product Family

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

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: A 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

Create

URL: https://<subdomain>.chargify.com/product_families/<product_family_id>/products.<format>
Method: POST
Required Parameters: XML or JSON data, as specified by the required attributes
Response: The created product, if successful. Errors otherwise.

XML example
JSON example

Update

URL: https://<subdomain>.chargify.com/products/<productid>.<format>
Method: PUT
Required Parameters: XML or JSON data
Response: The updated product, if successful. Errors otherwise.

JSON example

Usage Examples

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>
        <public_signup_pages type="array"/>
        <version_number>1</version_number>
      </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>
       <public_signup_pages type="array"/>
       <version_number>1</version_number>
     </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,
          "public_signup_pages":[],
          "version_number": 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,
          "public_signup_pages":[],
          "version_number": 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"

XML List Products for Product Family Example


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

JSON List Products for Product Family Example


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

XML Create Product Example


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

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


  Scenario: Create a product successfully
    Given I have this xml product data
      ""
      <?xml version="1.0" encoding="UTF-8"?>
      <product>
        <name>Basic Plan</name>
        <handle>basic</handle>
        <description>This is our basic plan.</description>
        <accounting_code>123</accounting_code>
        <request_credit_card type="boolean">true</request_credit_card>
        <price_in_cents>1000</price_in_cents>
        <interval>1</interval>
        <interval_unit>month</interval_unit>
        <auto_create_signup_page>true</auto_create_signup_page>
      </product>
      ""
    When I send a POST request with the xml data to https://[@subdomain].chargify.com/product_families/[@product_family.id]/products.xml
    Then the response status should be "201 Created"
    And the response should be the xml:
    ""
    <?xml version="1.0" encoding="UTF-8"?>
    <product>
      <id>`auto generated`</id>
      <name>Basic Plan</name>
      <handle>basic</handle>
      <accounting_code>123</accounting_code>
      <description>This is our basic plan.</description>
      <interval type="integer">1</interval>
      <interval_unit>month</interval_unit>
      <price_in_cents type="integer">1000</price_in_cents>
      <initial_charge_in_cents type="integer" nil="true"></initial_charge_in_cents>
      <trial_interval type="integer" nil="true"></trial_interval>
      <trial_interval_unit nil="true"></trial_interval_unit>
      <trial_price_in_cents type="integer" nil="true"></trial_price_in_cents>
      <expiration_interval type="integer">`your value`</expiration_interval>
      <expiration_interval_unit>`your value`</expiration_interval_unit>
      <archived_at type="datetime" nil="true"></archived_at>
      <created_at type="datetime">`auto generated`</created_at>
      <updated_at type="datetime">`auto generated`</updated_at>
      <request_credit_card type="boolean">true</request_credit_card>
      <require_credit_card type="boolean">true</require_credit_card>
      <update_return_url nil="true"></update_return_url>
      <return_params nil="true"></return_params>
      <product_family>
        <id>`auto generated`</id>
        <accounting_code>`your value`</accounting_code>
        <handle>`your value`</handle>
        <name>`your value`</name>
        <description>`your value`</description>
      </product_family>
      <public_signup_pages type="array">
        <public_signup_page>
          <id type="integer">`auto generated`</id>
          <return_url nil="true"></return_url>
          <url>`auto generated`</url>
        </public_signup_page>
      </public_signup_pages>
      <version_number>1</version_number>
    </product>
     """

JSON Create Product Example


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

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

  Scenario: Create a product successfully
    Given I have this json product data
      ""
      {"product":{
        "name":"Basic Plan",
        "handle":"basic",
        "description":"This is our basic plan.",
        "accounting_code":"123",
        "request_credit_card":true,
        "price_in_cents":1000,
        "interval":1,
        "interval_unit":"month",
        "auto_create_signup_page": true
      }}
      ""
    When I send a POST request with the json data to https://[@subdomain].chargify.com/product_families/[@product_family.id]/products.json
    Then the response status should be "201 Created"
    And the response should be the json:
    ""
     {
       "product":{
         "id":`auto generated`,
         "name":"Basic Plan",
         "handle":"basic",
         "accounting_code":"123",
         "description":"This is our basic plan.",
         "price_in_cents":1000,
         "interval_unit":"month",
         "interval":1,
         "initial_charge_in_cents":null,
         "trial_price_in_cents":null,
         "trial_interval":null,
         "trial_interval_unit":null,
         "expiration_interval_unit":null,
         "expiration_interval":null,
         "update_return_url":null,
         "return_params":null,
         "require_credit_card":true,
         "request_credit_card":true,
         "created_at":`auto generated`,
         "updated_at":`auto generated`,
         "archived_at":null,
         "product_family":{
           "id":`auto generated`,
           "name":`your value`,
           "handle":`your value`,
           "accounting_code":`your value`,
           "description":`your value`
         },
         "public_signup_pages": [
          {
            "id": `auto generated`,
            "return_url":null,
            "url": `auto generated`
          },
         "version_number": 1
        ]
       }
     }
     ""

  Scenario: Attempt to create a product with a trial validation error
    Given I have this json product data
      ""
      {"product":{
        "name":"Basic Plan",
        "handle":"basic",
        "description":"This is our basic plan.",
        "accounting_code":"123",
        "request_credit_card":true,
        "price_in_cents":1000,
        "interval":1,
        "interval_unit":"month",
        "trial_interval":1,
        "trial_interval_unit":"month"
      }}
      ""
    When I send a POST request with the json data to https://[@subdomain].chargify.com/product_families/[@product_family.id]/products.json
    Then the response status should be "422 Unprocessable Entity"
    And the response should be the json:
    ""
    {
      "errors":["Trial Price: must be given if a trial interval (duration) is provided."]
    }
    ""

JSON Update Product Example


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

  Background:
    Given I am a valid API user for site with subdomain "acme"
    And I send and accept JSON
    And I have a product family with ID "1700"
    And I have a product with ID "1900"

  Scenario: Update a product
    And I have this json product data
      """
      {"product":{
        "name":"Basic Plan",
        "handle":"basic",
        "accounting_code":"acme1",
        "require_credit_card":false,
        "request_credit_card":false,
        "description":"lorem ipsum",
        "price_in_cents":"2121"
      }}
      """
    When I send a PUT request with the json data to https://acme.chargify.com/products/1900.json
    Then the response status should be "200 OK"
    And the response should be the json:
     """
      {
        "product":{
          "id":1900,
          "name":"Basic Plan",
          "handle":"basic",
          "accounting_code":"acme1",
          "description":"lorem ipsum",
          "price_in_cents":`auto generated`,
          "interval_unit":"month",
          "interval":1,
          "initial_charge_in_cents":null,
          "trial_price_in_cents":null,
          "trial_interval":null,
          "trial_interval_unit":null,
          "expiration_interval_unit":null,
          "expiration_interval":null,
          "update_return_url":null,
          "return_params":null,
          "require_credit_card":false,
          "request_credit_card":false,
          "created_at":`auto generated`,
          "updated_at":`auto generated`,
          "archived_at":null,
          "taxable":false,
          "product_family":{
            "id":1700,
            "name":`your value`,
            "handle":`your value`,
            "accounting_code":`your value`,
            "description":`your value`
          },
          "public_signup_pages": [],
          "version_number": 2
        }
      }
      """

  Scenario: Update a product fails due to invalid attributes
    And I have this json product data
      """
        {"product":{
          "name":""
        }}
      """
    When I send a PUT request with the json data to https://acme.chargify.com/products/1900.json
    Then the response status should be "422 Unprocessable Entity"
    And the response should be the json:
      """
      {"errors":
        [
          "Name: cannot be blank."
        ]
      }
      """

  Scenario: Update a product fails due to "Product not found" (i.e. unknown ID of 0)
    Given I have 0 products
    And I have this json product data
      """
      {"product":{
        "name":"My Updated Product"
      }}
      """
    When I send a PUT request with the json data to https://acme.chargify.com/products/0.json
    Then the response status should be "404 Not Found"