API: Transactions

The Transactions API allows you to view a list of all transactions both for a site and for an individual subscription.

URIs

Resource/URI	GET	POST	PUT	DELETE
Transactions /transactions	List transactions	–	–	–
Transaction /transactions/<id>	Read transaction	–	–	–
Subscription Transactions /subscriptions/<id>/transactions	List transactions belonging to a Subscription	–	–	–

Transaction Types

The following is a list of available transaction types

• charge
• refund
• payment
• credit
• payment_authorization
• info
• adjustment

Charge Kinds (Subtypes)

• one_time: A one-time charge, captured immediately from payment source (credit card)
• delay_capture: A one-time charge accrued to the subscription to be captured at next normal billing/renewal
• initial: A initial/upfront/startup charge added according to the product setup settings
• metered or metered_component: A charge from usage of a metered component
• quantity_based_component: A charge from a quantity-based component allocation
• on_off_component: A charge from an on/off component allocation
• tax: A calculated tax charge

Transaction Attributes

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

• transaction_type The type of the transaction, see above
• id The unique identifier for the Transaction
• amount_in_cents The amount in cents of the Transaction
• created_at Timestamp indicating when the Transaction was created
• ending_balance_in_cents The remaining balance on the subscription after the Transaction has been processed
• memo A note about the Transaction
• subscription_id The unique identifier for the associated Subscription
• product_id The unique identifier for the product associated with the Subscription
• success Whether or not the Transaction was successful
• payment_id The unique identifier for the payment being explicitly refunded (in whole or in part) by this transaction. Will be null for all transaction types except for “Refund”. May be null even for Refunds. For partial refunds, more than one Refund transaction may reference the same payment_id.
• kind The specific “subtype” for the transaction_type
• gateway_transaction_id The transaction ID from the remote gateway (i.e. Authorize.Net), if one exists

Methods

List transactions for a Site

URL: https://<subdomain>.chargify.com/transactions.<format>
Method: GET
Optional Parameters (via query string):

• kinds[] An array of transaction types (see above). Multiple values can be passed in the url, for example: http://example.com?kinds[]=charge&kinds[]=payment&kinds[]=credit
• since_id Returns transactions with an id greater than or equal to the one specified
• max_id Returns transactions with an id less than or equal to the one specified
• since_date (format YYYY-MM-DD) Returns transactions with a created_at date greater than or equal to the one specified
• until_date (format YYYY-MM-DD) Returns transactions with a created_at date less than or equal to the one specified
• page and per_page The page number and number of results used for pagination. By default results are paginated 20 per page.

Response: An array of Transactions

XML example
JSON example

Show transaction

URL: https://<subdomain>.chargify.com/transactions/<id>.<format>
Method: GET
Required Parameters: id

Response: A single Transaction

XML example
JSON example

List transactions for a Subscription

URL: https://<subdomain>.chargify.com/subscriptions/<subscription_id>/transactions.<format>
Method: GET
Optional Parameters:

• kinds[] An array of transaction types, see above
• since_id Returns transactions with an id greater than or equal to the one specified
• max_id Returns transactions with an id less than or equal to the one specified
• since_date (format YYYY-MM-DD) Returns transactions with a created_at date greater than or equal to the one specified
• until_date (format YYYY-MM-DD) Returns transactions with a created_at date less than or equal to the one specified
• page and per_page The page number and number of results used for pagination. By default results are paginated 20 per page.

Response: An array of Transactions

XML example
JSON example

Usage Examples

XML List Transactions for Site Example

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

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

  Scenario: Retrieve a list of all the account transactions for my site
    Given I have transactions
    When I send a GET request to https://[@subdomain].chargify.com/transactions.xml
    Then the response status should be "200 OK"
    And the response should be a "transactions" array with 7 "transaction" elements
    And the response should be the xml:
      """
      <?xml version="1.0" encoding="UTF-8"?>
      <transactions type="array">
        <transaction>
          <id type="integer">[@charge.id]</id>
          <amount_in_cents type="integer">0</amount_in_cents>
          <created_at type="datetime">[@charge.created_at]</created_at>
          <ending_balance_in_cents type="integer" nil="true"></ending_balance_in_cents>
          <memo>memo</memo>
          <subscription_id type="integer">[@subscription.id]</subscription_id>
          <product_id type="integer">[@subscription.product_id]</product_id>
          <success type="boolean">true</success>
          <type>Charge</type>
          <payment_id type="integer" nil="true"></payment_id>
        </transaction>
        <transaction>
          <id type="integer">[@credit.id]</id>
          <amount_in_cents type="integer">0</amount_in_cents>
          <created_at type="datetime">[@credit.created_at]</created_at>
          <ending_balance_in_cents type="integer" nil="true"></ending_balance_in_cents>
          <memo></memo>
          <subscription_id type="integer">[@subscription.id]</subscription_id>
          <product_id type="integer">[@subscription.product_id]</product_id>
          <success type="boolean">true</success>
          <type>Credit</type>
          <payment_id type="integer" nil="true"></payment_id>
        </transaction>
        <transaction>
          <id type="integer">[@payment.id]</id>
          <amount_in_cents type="integer">1000</amount_in_cents>
          <created_at type="datetime">[@payment.created_at]</created_at>
          <ending_balance_in_cents type="integer" nil="true"></ending_balance_in_cents>
          <memo></memo>
          <subscription_id type="integer">[@subscription.id]</subscription_id>
          <product_id type="integer">[@subscription.product_id]</product_id>
          <success type="boolean">true</success>
          <type>Payment</type>
          <payment_id type="integer" nil="true"></payment_id>
        </transaction>
        <transaction>
          <id type="integer">[@payment_authorization.id]</id>
          <amount_in_cents type="integer">0</amount_in_cents>
          <created_at type="datetime">[@payment_authorization.created_at]</created_at>
          <ending_balance_in_cents type="integer" nil="true"></ending_balance_in_cents>
          <memo></memo>
          <subscription_id type="integer">[@subscription.id]</subscription_id>
          <product_id type="integer">[@subscription.product_id]</product_id>
          <success type="boolean">true</success>
          <type>PaymentAuthorization</type>
          <payment_id type="integer" nil="true"></payment_id>
        </transaction>
        <transaction>
          <id type="integer">[@refund.id]</id>
          <amount_in_cents type="integer">2000</amount_in_cents>
          <created_at type="datetime">[@refund.created_at]</created_at>
          <ending_balance_in_cents type="integer" nil="true"></ending_balance_in_cents>
          <memo></memo>
          <subscription_id type="integer">[@subscription.id]</subscription_id>
          <product_id type="integer">[@subscription.product_id]</product_id>
          <success type="boolean">true</success>
          <type>Refund</type>
          <payment_id type="integer">[@refund.payment_id]</payment_id>
        </transaction>
        <transaction>
          <id type="integer">[@adjustment.id]</id>
          <amount_in_cents type="integer">0</amount_in_cents>
          <created_at type="datetime">[@adjustment.created_at]</created_at>
          <ending_balance_in_cents type="integer" nil="true"></ending_balance_in_cents>
          <memo></memo>
          <subscription_id type="integer">[@subscription_2.id]</subscription_id>
          <product_id type="integer">[@subscription.product_id]</product_id>
          <success type="boolean">true</success>
          <type>Adjustment</type>
          <payment_id type="integer" nil="true"></payment_id>
        </transaction>
        <transaction>
          <id type="integer">[@info_transaction.id]</id>
          <amount_in_cents type="integer">0</amount_in_cents>
          <created_at type="datetime">[@info_transaction.created_at]</created_at>
          <ending_balance_in_cents type="integer" nil="true"></ending_balance_in_cents>
          <memo></memo>
          <subscription_id type="integer">[@subscription_2.id]</subscription_id>
          <product_id type="integer">[@subscription.product_id]</product_id>
          <success type="boolean">true</success>
          <type>InfoTransaction</type>
          <payment_id type="integer" nil="true"></payment_id>
        </transaction>
      </transactions>
      """

JSON List Transactions for Site Example

Scenario: Retrieve a list of all the account transactions for my site
  Given I have transactions
  When I send a GET request to https://[@subdomain].chargify.com/transactions.json
  Then the response status should be "200 OK"
  And the response should be a json array with 7 "transaction" objects

XML List Transactions for Site Example

Scenario: Retrieve a list of all the account transactions for a subscription
  Given I have transactions
  When I send a GET request to https://[@subdomain].chargify.com/subscriptions/[@subscription.id]/transactions.xml
  Then the response status should be "200 OK"
  And the response should be a "transactions" array with 5 "transaction" elements
  And the response should be the xml:
    """
    <?xml version="1.0" encoding="UTF-8"?>
    <transactions type="array">
      <transaction>
        <id type="integer">[@charge.id]</id>
        <amount_in_cents type="integer">0</amount_in_cents>
        <created_at type="datetime">[@charge.created_at]</created_at>
        <ending_balance_in_cents type="integer" nil="true"></ending_balance_in_cents>
        <memo>memo</memo>
        <subscription_id type="integer">[@subscription.id]</subscription_id>
        <product_id type="integer">[@subscription.product_id]</product_id>
        <success type="boolean">true</success>
        <type>Charge</type>
        <payment_id type="integer" nil="true"></payment_id>
      </transaction>
      <transaction>
        <id type="integer">[@credit.id]</id>
        <amount_in_cents type="integer">0</amount_in_cents>
        <created_at type="datetime">[@credit.created_at]</created_at>
        <ending_balance_in_cents type="integer" nil="true"></ending_balance_in_cents>
        <memo></memo>
        <subscription_id type="integer">[@subscription.id]</subscription_id>
        <product_id type="integer">[@subscription.product_id]</product_id>
        <success type="boolean">true</success>
        <type>Credit</type>
        <payment_id type="integer" nil="true"></payment_id>
      </transaction>
      <transaction>
        <id type="integer">[@payment.id]</id>
        <amount_in_cents type="integer">1000</amount_in_cents>
        <created_at type="datetime">[@payment.created_at]</created_at>
        <ending_balance_in_cents type="integer" nil="true"></ending_balance_in_cents>
        <memo></memo>
        <subscription_id type="integer">[@subscription.id]</subscription_id>
        <product_id type="integer">[@subscription.product_id]</product_id>
        <success type="boolean">true</success>
        <type>Payment</type>
        <payment_id type="integer" nil="true"></payment_id>
      </transaction>
      <transaction>
        <id type="integer">[@payment_authorization.id]</id>
        <amount_in_cents type="integer">0</amount_in_cents>
        <created_at type="datetime">[@payment_authorization.created_at]</created_at>
        <ending_balance_in_cents type="integer" nil="true"></ending_balance_in_cents>
        <memo></memo>
        <subscription_id type="integer">[@subscription.id]</subscription_id>
        <product_id type="integer">[@subscription.product_id]</product_id>
        <success type="boolean">true</success>
        <type>PaymentAuthorization</type>
        <payment_id type="integer" nil="true"></payment_id>
      </transaction>
      <transaction>
        <id type="integer">[@refund.id]</id>
        <amount_in_cents type="integer">2000</amount_in_cents>
        <created_at type="datetime">[@refund.created_at]</created_at>
        <ending_balance_in_cents type="integer" nil="true"></ending_balance_in_cents>
        <memo></memo>
        <subscription_id type="integer">[@subscription.id]</subscription_id>
        <product_id type="integer">[@subscription.product_id]</product_id>
        <success type="boolean">true</success>
        <type>Refund</type>
        <payment_id type="integer">[@refund.payment_id]</payment_id>
      </transaction>
    </transactions>
    """

JSON List Transactions for Site Example

Scenario: Retrieve a list of all the account transactions for a subscription
  Given I have transactions
  When I send a GET request to https://[@subdomain].chargify.com/subscriptions/[@subscription.id]/transactions.json
  Then the response status should be "200 OK"
  And the response should be a json array with 5 "transaction" objects

XML Show Transaction Example

Feature: Chargify Transactions Read/Show XML API
  In order to integrate my app with Chargify
  As a developer
  I want to read/show a transaction via the Chargify XML API

  Background:
    Given I am a valid API user
    And I accept xml responses
    And I have 1 product
    And I have 1 active subscriptions

  Scenario: Retrieve a transaction via ID
    Given I have a transaction
    When I send a GET request to https://[@subdomain].chargify.com/transactions/[@transaction.id].xml
    Then the response status should be "200 OK"
    And the response should be the xml:
      """
      <?xml version="1.0" encoding="UTF-8"?>
      <transaction>
        <transaction_type>payment</transaction_type>
        <created_at type="datetime">`auto generated`</created_at>
        <product_id type="integer">[@product.id]</product_id>
        <ending_balance_in_cents type="integer" nil="true"></ending_balance_in_cents>
        <memo></memo>
        <id type="integer">[@transaction.id]</id>
        <type>Payment</type>
        <amount_in_cents type="integer">1000</amount_in_cents>
        <success type="boolean">true</success>
        <subscription_id type="integer">[@subscription.id]</subscription_id>
        <payment_id type="integer" nil="true"></payment_id>
      </transaction>
      """

  @allow-rescue
  Scenario: Attempt to retrieve a transaction that doesn't exist
    Given no transactions exist
    When I send a GET request to https://[@subdomain].chargify.com/transactions/9999.xml
    Then the response status should be "404 Not Found"

JSON Show Transaction Example

Feature: Chargify Transactions Read/Show JSON API
  In order to integrate my app with Chargify
  As a developer
  I want to read/show a transaction via the Chargify JSON API

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

  Scenario: Retrieve a transaction via ID
    Given I have a transaction
    When I send a GET request to https://[@subdomain].chargify.com/transactions/[@transaction.id].json
    Then the response status should be "200 OK"
    And the response should be the json:
      """
      {
        "transaction":{
          "transaction_type":"payment",
          "created_at":`auto generated`,
          "product_id":[@product.id],
          "ending_balance_in_cents":null,
          "memo":null,
          "id":[@transaction.id],
          "type":"Payment",
          "amount_in_cents":1000,
          "success":true,
          "subscription_id":[@subscription.id],
          "payment_id":null
        }
      }
      """

  @allow-rescue
  Scenario: Attempt to retrieve a transaction that doesn't exist
    Given no transactions exist
    When I send a GET request to https://[@subdomain].chargify.com/transactions/9999.json
    Then the response status should be "404 Not Found"

• Next page: API: Webhooks
• Previous page: API: Subscriptions