Chargify Documentation » API v1 Resources

API: Products

Product Attributes

All of the product 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
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
return_url The URL a buyer is returned to after successful purchase. See the section on “Return URLs and Parameters” [here](/product-options#return-url-and-parameters)
return_params The parameters string we will use in constructing your return URL. See the section on “Return URLs and Parameters” here
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

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
return_url The URL a buyer is returned to after successful purchase. See the section on “Return URLs and Parameters” [here](/product-options#return-url-and-parameters)
return_params The parameters string we will use in constructing your return URL. See the section on “Return URLs and Parameters” here
require_credit_card Boolean
request_credit_card Boolean
require_billing_address Boolean
request_billing_address Boolean
taxable Boolean

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

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

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>
      </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"

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>
      </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>
      <return_url nil="true"></return_url>
      <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>
    </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"
      }}
      ""
    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,
         "return_url":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`
         }
       }
     }
     ""

  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."]
    }
    ""

Next page: API: Quantity Component Allocations
Previous page: API: Migrations (Prorated Upgrades/Downgrades)

API: Products

Product Attributes

Input Attributes (Create)

Methods

List

List products for a Product Family

Read/Show (via Chargify ID)

Read/Show (via API handle)

Create

Usage Examples

XML List Usage Example

JSON List Usage Example

XML Read/Show Usage Example

JSON Read/Show Usage Example

XML List Products for Product Family Example

JSON List Products for Product Family Example

XML Create Product Example

JSON Create Product Example

Features

Resources

Community

Chargify