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

Type / Transaction Type Description Effect on Subscriber Balance Due Effect on “Revenue” (money collected)
charge A positive amount assessed to a subscription for an item (i.e. a Product or Component) sale. Usually assessed at signup or renewal time. Increases balance due No effect on revenue
credit A negative amount assessed to a subscription that indicates a “return” or “credit” for an item (i.e. a Product or Component). Usually offsets an earlier charge, i.e. in the case of a prorated downgrade. Decreases balance due No effect on revenue
adjustment A postive or negative amount that adjusts the subscription balance but cannot usually be directly attributed to a single item (Product or Component) Increases or decreases balance due No effect on revenue
payment A postive amount that denotes amount paid to you by the subscriber, usually on their credit card or bank account via your payment gateway. Payments may also be recorded “manually” in the case of checks received, or money received outside of Chargify. Decreases balance due Increases revenue
refund A positive amount that denotes “cash” given back to a subscriber (i.e. put back on their card) via a refund or credit at the gateway. No effect on balance due Decreases revenue
InfoTransaction / info An informational transaction whose description provides context for transactions nearby in time, or serves as a placeholder for another transaction that could not be attempted (i.e. when payment cannot be attempted because no card is on file) N/A N/A
payment_authorization Deprecated. No longer appears in transactions listing N/A N/A

Transaction Kinds (Subtypes)

Kinds for the charge transaction type

Type / Transaction Type Kind Description
charge trial A charge for a subscription’s trial period. Usually applied at the time of signup, but sometimes after a migration where a trial is allowed.
charge initial A charge for the initial/setup fee assessed according to the product setup settings. Usually applied at the time of signup, but sometimes after a migration where the setup fee is included.
charge baseline A charge for the normal, recurring fee.
charge one_time A one-time fee applied to a subscription, usually between normal renewals. Can be added in the Chargify UI or the API, and is captured (via credit card payment) immediately.
charge delay_capture Like a one_time charge, but not captured (i.e. not paid) until the next normal renewal. Sometimes called an “accrued charge”.
charge quantity_based_component A charge for the currently allocated quantity of a quantity-based component (i.e. seat licenses). Applied at renewal based on the quantity allocated at that time.
charge on_off_component A charge for the current status (on or off) of an on/off component. Applied at renewal.
charge metered_component A charge for the usage of a metered component (i.e. minutes). Applied at renewal based on the usage during the last period.
charge metered Deprecated. May exist for very old transasctions. Can be considered an alias for “metered_component”.
charge tax A charge for the taxes computed on taxable line items for the billing event (signup or renewal).
charge A generic charge that is not otherwise classified by any of the above values for `kind`.

Kinds for the credit transaction type

Type / Transaction Type Kind Description
credit quantity_based_component A credit against a quantity-based component charge. Usually generated during a prorated downgrade for an amount previously charged.
credit on_off_component A credit against an on/off component charge. Usually generated during a prorated downgrade for an amount previously charged.
credit tax A credit against tax charges. Usually generated during a prorated downgrade to offset a tax amount already assessed.
credit A generic credit that is not otherwise classified by any of the above values for `kind`.

Kinds for the adjustment transaction type

Type / Transaction Type Kind Description
adjustment @coupon An adjustment that reflects the discount provided by a coupon. Is almost always a negative amount.
adjustment prorated An adjustment applied during a migration proration that offsets overpayments resulting from the shortened period on the old product. Followed by the assessment of new charges for the new product.
adjustment quantity_based_component Deprecated. Like a quantity_based_component credit in function but no longer used (since credits can be taxable but adjustments cannot).
adjustment on_off_component Deprecated. Like an on_off_component credit in function but no longer used (since credits can be taxable but adjustments cannot).
adjustment tax Deprecated. Like a tax credit in function but no longer used.
adjustment referral An adjustment that acts like a coupon but is the discount applied to the referring subscriber in a Refer-A-Friend scenario.
adjustment A generic adjustment that is not otherwise classified by any of the above values for `kind`. This is the kind of ad-hoc adjustment that can be created via the API.

Kinds for the payment transaction type

Type / Transaction Type Kind Description
payment one_time A payment received for a mid-period one-time charge (i.e. for a charge with kind one_time).
payment component_proration A payment received for a mid-period component proration (allocation change).
payment manual A payment recorded “manually” via the Admin UI or API. This kind of payment was not one automatically processed by Chargify, but instead entered manually.
payment A generic payment received in any sitation not described above. Usually an automatically captured payment for a normal signup or renewal.

Kinds for the refund transaction type

Type / Transaction Type Kind Description
refund manual A refund recorded “manually” via the Admin UI or API to reflect a refund already given outside of Chargify. Chargify does not actually submit this kind of refund to the payment gateway.
refund A generic refund resulting from any sitation not described above. This kind of refund is submitted by Chargify to the payment gateway to return money to the subscriber.

Transaction Attributes

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

  • transaction_type / 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
  • starting_balance_in_cents The initial balance on the subscription before the Transaction has been processed
  • 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
  • gateway_order_id A gateway-specific identifier for the transaction, separate from the gateway_transaction_id:
Gateway Value in gateway_order_id
BPoint “ReceiptNumber” from the transaction response
All other gateways Undefined at this time

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 timestamp at or after midnight (12:00:00 AM) in your site’s time zone on the date specified
  • until_date (format YYYY-MM-DD) Returns transactions with a created_at timestamp up to and including 11:59:59PM in your site’s time zone on the date specified
  • page and per_page The page number and number of results used for pagination. By default results are paginated 20 per page. Please see the pagination notes below.
  • direction can be either asc for ascending or desc for descending order. (defaults to desc) The sort order is based on the created_at timestamp then id for transactions within the same second.
  • order_by Either id or created_at. Using an ID filter (since_id/max_id) will force id order, while using a Date filter (since_date/until_date) will force created_at order. Otherwise, your requested value will be used.

Response: An array of Transactions

XML example
JSON example

Notes about ID/Date Filters

  • Using since_id and/or max_id is known as creating an “ID Filter”.
  • Using since_date and/or until_date is known as creating a “Date Filter”.
  • You may ONLY make use of either an ID Filter or a Date Filter in any one request.
  • If you specify both an ID Filter and a Date Filter, the Date Filter will be ignored.

Pagination Notes

Stepping through pages of results by incrementing the page number is typically
less performant than using an ID Filter with since_id, especially at high
values of page.

For example, instead of these successive requests to traverse pagination…

GET /transactions.json?page=1&per_page=200
GET /transactions.json?page=2&per_page=200

… it is usually faster to use since_id to continue fetching from the last ID
you observed:

GET /transactions.json?since_id=0&per_page=200&direction=asc
GET /transactions.json?since_id=1567&per_page=200&direction=asc

In the above example, 1567 is derived by adding 1 to the “last” ID you
received from the first request.

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 timestamp at or after midnight (12:00:00 AM) in your site’s time zone on the date specified
  • until_date (format YYYY-MM-DD) Returns transactions with a created_at timestamp up to and including 11:59:59 PM in your site’s time zone on the date specified.
  • page and per_page The page number and number of results used for pagination. By default results are paginated 20 per page.
  • direction can be either asc for ascending or desc for descending order. (defaults to desc). The sort order is based on the created_at timestamp and cannot be changed.

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>
          <starting_balance_in_cents type="integer">[@charge.starting_balance_in_cents]</starting_balance_in_cents>
          <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>
          <starting_balance_in_cents type="integer">[@credit.starting_balance_in_cents]</starting_balance_in_cents>
          <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>
          <starting_balance_in_cents type="integer">[@payment.starting_balance_in_cents]</starting_balance_in_cents>
          <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>
          <starting_balance_in_cents type="integer">[@payment_authorization.starting_balance_in_cents]</starting_balance_in_cents>
          <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>
          <starting_balance_in_cents type="integer">[@refund.starting_balance_in_cents]</starting_balance_in_cents>
          <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>
          <starting_balance_in_cents type="integer">[@adjustment.starting_balance_in_cents]</starting_balance_in_cents>
          <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>
          <starting_balance_in_cents type="integer">[@info_transaction.starting_balance_in_cents]</starting_balance_in_cents>
          <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>
        <starting_balance_in_cents type="integer">[@charge.starting_balance_in_cents]</starting_balance_in_cents>
        <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>
        <starting_balance_in_cents type="integer">[@credit.starting_balance_in_cents]</starting_balance_in_cents>
        <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>
        <starting_balance_in_cents type="integer">[@payment.starting_balance_in_cents]</starting_balance_in_cents>
        <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>
        <starting_balance_in_cents type="integer">[@payment_authorization.starting_balance_in_cents]</starting_balance_in_cents>
        <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>
        <starting_balance_in_cents type="integer">[@refund.starting_balance_in_cents]</starting_balance_in_cents>
        <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>
        <refunded_amount_in_cents type="integer">`auto generated`</refunded_amount_in_cents>
        <starting_balance_in_cents type="integer">`auto generated`</starting_balance_in_cents>
        <ending_balance_in_cents type="integer">`auto generated`</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],
          "refunded_amount_in_cents": `auto generated`,
          "starting_balance_in_cents": `auto generated`,
          "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"