API: Statements

Chargify Statements give you and your customers a breakdown of Subscription charges, payments, credits, and activity on a period-by-period basis. A Statement is similar to an “Invoice” because it is marked as currently paid or unpaid. Statements display all account activity for a specific usage period.

All of the statement attribute fields are returned from GET (read) operations. Note, all of these attributes are read only.

  • id The unique identifier for this statement within Chargify
  • subscription_id The unique identifier of the subscription associated with the statement
  • opened_at The date that the statement was opened
  • closed_at The date that the statement was closed
  • settled_at The date that the statement was settled
  • text_view A text representation of the statement
  • basic_html_view A simple HTML representation of the statement
  • html_view A more robust HTML representation of the statement
  • future_payments A collection of payments from future statements that pay charges on this statement
  • starting_balance_in_cents The subscription’s balance at the time the statement was opened
  • ending_balance_in_cents The subscription’s balance at the time the statement was closed
  • customer_first_name The customer’s first name
  • customer_last_name The customer’s last name
  • customer_organization The customer’s organization
  • customer_shipping_address The customer’s shipping address
  • customer_shipping_address_2 The customer’s shipping address, line 2
  • customer_shipping_city The customer’s shipping city
  • customer_shipping_state The customer’s shipping state
  • customer_shipping_country The customer’s shipping country
  • customer_shipping_zip The customer’s shipping zip
  • customer_billing_address The customer’s billing address
  • customer_billing_address_2 The customer’s billing address, line 2
  • customer_billing_city The customer’s billing city
  • customer_billing_state The customer’s billing state
  • customer_billing_country The customer’s billing country
  • customer_billing_zip The customer’s billing zip
  • transactions A collection of the transaction objects associated with the statement
  • events A collection of the event objects associated with the statement
  • created_at The creation date for this statement
  • updated_at The date of last update for this statement

Methods

List Statement IDs for a Subscription

URL: https://<subdomain>.chargify.com/subscriptions/<subscription_id>/statements/ids.<format>
Method: GET
Optional Parameters: page, sort, direction
Response: An array of Statement IDs for a subscription

Note that the per_page parameter is preset to 10,000.

sort

The optional sort prameter can be created_at, opened_at, or closed_at. This allows you to choose what you would like to sort on. (defaults to created_at)

direction

The optional direction parameter can be either asc for ascending or desc for descending order. (defaults to asc)

Sorting examples

Say you would like to get the 10 most recently created statements. You would specify the following optional parameters sort as created_at, direction as desc and limit your per_page to 10.

If you on the other hand wish to find the oldest closed statements you could do: sort as closed_at and direction as asc.

List Statement IDs for a Site

URL: https://<subdomain>.chargify.com/statements/ids.<format>
Method: GET
Optional Parameters: page
Response: An array of Statement IDs for a site

Note that the per_page parameter is preset to 10,000.

JSON Output

{
  "statement_ids":[1,2,3,4 ... 9999,10000]
}

XML Output

<statement_ids>
  <id>1</id>
  <id>2</id> 
  ... 
  <id>9999</id>
  <id>10000</id>
</statement_ids>

List Statements for a Subscription

URL: https://<subdomain>.chargify.com/subscriptions/<subscription_id>/statements.<format>
Method: GET
Optional Parameters: page
Response: An array of Statements

Read/Show (via Chargify ID)

URL: https://<subdomain>.chargify.com/statements/<id>.<format>
Method: GET
Required Parameters: id
Response: An single Statement

Individual PDF Statements can be retrieved by using the Accept/Content-Type header application/pdf or appending .pdf as the <format> portion of the URL:


  curl -u <api_key>:x -H Accept:application/pdf -H Content-Type:application/pdf https://acme.chargify.com/statements/1.pdf > output_file.pdf

JSON Response

{
  "statement": {
    "basic_html_view": `auto generated`,
    "closed_at": null,
    "created_at": `auto generated`,
    "customer_billing_address": `your value`,
    "customer_billing_address_2": `your value`,
    "customer_billing_city": `your value`,
    "customer_billing_country": `your value`,
    "customer_billing_state": `your value`,
    "customer_billing_zip": `your value`,
    "customer_first_name": `your value`,
    "customer_last_name": `your value`,
    "customer_organization": `your value`,
    "customer_shipping_address": `your value`,
    "customer_shipping_address_2": `your value`,
    "customer_shipping_city": `your value`,
    "customer_shipping_country": `your value`,
    "customer_shipping_state": `your value`,
    "customer_shipping_zip": `your value`,
    "ending_balance_in_cents": 0,
    "events": [
      {
        "event": {
          "id":  `auto generated`,
          "key": "payment_success",
          "message": `auto generated`,
          "created_at": `auto generated`,
          "subscription_id": `auto generated`,
          "event_specific_data": {
            "product_id": `auto generated`,
            "account_transaction_id": `auto generated`
          }
        }
      },
      {
        "event": {
          "id": `auto generated`,
          "key": "signup_success",
          "message": `auto generated`,
          "created_at": `auto generated`,
          "subscription_id": `auto generated`,
          "event_specific_data": {
            "product_id": `auto generated`,
            "account_transaction_id": `auto generated`
          }
        }
      }
    ],
    "future_payments": [],
    "html_view": `auto generated`,
    "id": `auto generated`,
    "memo": "",
    "opened_at": null,
    "settled_at": null,
    "starting_balance_in_cents": 0,
    "subscription_id": `auto generated`,
    "text_view": `auto generated`,
    "transactions": [
      {
        "transaction_type":"charge",
        "created_at":`auto generated`,
        "product_id":`auto generated`,
        "starting_balance_in_cents":0,
        "ending_balance_in_cents":1000,
        "memo":`auto generated`,
        "id":`auto generated`,
        "type":"Charge",
        "amount_in_cents":1000,
        "success":true,
        "subscription_id":`auto generated`,
        "payment_id":`auto generated`,
        "kind":"baseline",
        "gateway_transaction_id":null
      },
      {
        "transaction_type":"payment",
        "created_at":`auto generated`,
        "product_id":`auto generated`,
        "starting_balance_in_cents":1000,
        "ending_balance_in_cents":0,
        "memo":`auto generated`,
        "id":`auto generated`,
        "type":"Payment",
        "amount_in_cents":1000,
        "success":true,
        "subscription_id":`auto generated`,
        "payment_id":`auto generated`,
        "kind":null,
        "gateway_transaction_id":`auto generated`
      }
    ],
    "updated_at": `auto generated`
  }
}

XML Response

<?xml version="1.0" encoding="UTF-8"?>
<statement>
  <basic_html_view>`auto generated`</basic_html_view>
  <closed_at type="datetime" nil="true"></closed_at>
  <created_at type="datetime">`auto generated`</created_at>
  <html_view>`auto generated`</html_view>
  <id type="integer">`auto generated`</id>
  <opened_at type="datetime" nil="true"></opened_at>
  <settled_at type="datetime" nil="true"></settled_at>
  <subscription_id type="integer">`auto generated`</subscription_id>
  <text_view>`auto generated`</text_view>
  <updated_at type="datetime">`auto generated`</updated_at>
  <future_payments type="array"></future_payments>
  <starting_balance_in_cents type="integer">0</starting_balance_in_cents>
  <ending_balance_in_cents type="integer">0</ending_balance_in_cents>
  <customer_first_name>`auto generated`</customer_first_name>
  <customer_last_name>`auto generated`</customer_last_name>
  <customer_organization nil="true">`auto generated`</customer_organization>
  <customer_shipping_address nil="true">`auto generated`</customer_shipping_address>
  <customer_shipping_address_2 nil="true">`auto generated`</customer_shipping_address_2>
  <customer_shipping_city nil="true">`auto generated`</customer_shipping_city>
  <customer_shipping_state nil="true">`auto generated`</customer_shipping_state>
  <customer_shipping_country nil="true">`auto generated`</customer_shipping_country>
  <customer_shipping_zip nil="true">`auto generated`</customer_shipping_zip>
  <customer_billing_address>`auto generated`</customer_billing_address>
  <customer_billing_address_2 nil="true">`auto generated`</customer_billing_address_2>
  <customer_billing_city>`auto generated`</customer_billing_city>
  <customer_billing_state>`auto generated`</customer_billing_state>
  <customer_billing_country>`auto generated`</customer_billing_country>
  <customer_billing_zip>`auto generated`</customer_billing_zip>
  <memo></memo>
  <transactions type="array">
    <transaction>
      <transaction_type>charge</transaction_type>
      <created_at type="datetime">`auto generated`</created_at>
      <product_id type="integer">`auto generated`</product_id>
      <starting_balance_in_cents type="integer">0</starting_balance_in_cents>
      <ending_balance_in_cents type="integer">1000</ending_balance_in_cents>
      <memo>`auto generated`</memo>
      <id type="integer">`auto generated`</id>
      <type>Charge</type>
      <amount_in_cents type="integer">1000</amount_in_cents>
      <success type="boolean">true</success>
      <subscription_id type="integer">`auto generated`</subscription_id>
      <payment_id type="integer">`auto generated`</payment_id>
      <kind>baseline</kind>
      <gateway_transaction_id></gateway_transaction_id>
    </transaction>
    <transaction>
      <transaction_type>payment</transaction_type>
      <created_at type="datetime">`auto generated`</created_at>
      <product_id type="integer">`auto generated`</product_id>
      <starting_balance_in_cents type="integer">1000</starting_balance_in_cents>
      <ending_balance_in_cents type="integer">0</ending_balance_in_cents>
      <memo>`auto generated`</memo>
      <id type="integer">`auto generated`</id>
      <type>Payment</type>
      <amount_in_cents type="integer">1000</amount_in_cents>
      <success type="boolean">true</success>
      <subscription_id type="integer">`auto generated`</subscription_id>
      <payment_id type="integer">`auto generated`</payment_id>
      <kind></kind>
      <gateway_transaction_id>`auto generated`</gateway_transaction_id>
    </transaction>
  </transactions>
  <events type="array">
    <event>
      <id type="integer">`auto generated`</id>
      <key>payment_success</key>
      <message>`auto generated`</message>
      <created_at>`auto generated`</created_at>
      <subscription_id>`auto generated`</subscription_id>
      <event_specific_data>
        <product_id>`auto generated`</product_id>
        <account_transaction_id>`auto generated`</account_transaction_id>
      </event_specific_data>
    </event>
    <event>
      <id type="integer">`auto generated`</id>
      <key>signup_success</key>
      <message>`auto generated`</message>
      <created_at>`auto generated`</created_at>
      <subscription_id>`auto generated`</subscription_id>
      <event_specific_data>
        <product_id>`auto generated`</product_id>
        <account_transaction_id>`auto generated`</account_transaction_id>
      </event_specific_data>
    </event>
  </events>
</statement>

Rendering Statements on Your Site

The Statements API offers three ways to easily render a statement on your site. You can include a text representation of the statement or one of two HTML views that can be styled to your liking.

  • text_view A text representation of the statement
  • basic_html_view A simple HTML representation of the statement
  • html_view A more robust HTML representation of the statement

Rendering individual statements can also be done as PDF by using the Accept/Content-Type header application/pdf or appending .pdf as the <format> portion of the URL.