Maxio Advanced Billing
HomeSDKsAPI ReferenceContext Plugin
Invoices

List Invoices

GET
/invoices.json

Lists invoices for a site. By default, invoices returned on the index will only include totals, not detailed breakdowns for line_items, discounts, taxes, credits, payments, custom_fields, or refunds. To include breakdowns, pass the specific field as a key in the query with a value set to true.

Authorization

BasicAuth
AuthorizationBasic <token>

The username is a Maxio Chargify API key. The password is x.

In: header

Query Parameters

start_date?string

The start date (format YYYY-MM-DD) with which to filter the date_field. Returns invoices with a timestamp at or after midnight (12:00:00 AM) in your site’s time zone on the date specified.

end_date?string

The end date (format YYYY-MM-DD) with which to filter the date_field. Returns invoices with a timestamp up to and including 11:59:59PM in your site’s time zone on the date specified.

status?Invoice Status

The current status of the invoice. Allowed Values: draft, open, paid, pending, voided

Value in

  • "draft"
  • "open"
  • "paid"
  • "pending"
  • "voided"
  • "canceled"
  • "processing"
subscription_id?integer

The subscription's ID.

subscription_group_uid?string

The UID of the subscription group you want to fetch consolidated invoices for. This will return a paginated list of consolidated invoices for the specified group.

consolidation_level?string

The consolidation level of the invoice. Allowed Values: none, parent, child or comma-separated lists of thereof, e.g. none,parent.

page?integer

Result records are organized in pages. By default, the first page of results is displayed. The page parameter specifies a page number of results to fetch. You can start navigating through the pages to consume the results. You do this by passing in a page parameter. Retrieve the next page by adding ?page=2 to the query string. If there are no results to return, then an empty result set will be returned. Use in query page=1.

Range1 <= value
Default1
per_page?integer

This parameter indicates how many records to fetch in each request. Default value is 20. The maximum allowed values is 200; any per_page value over 200 will be changed to 200. Use in query per_page=200.

Rangevalue <= 200
Default20
direction?string

The sort direction of the returned invoices.

Default"desc"

Value in

  • "asc"
  • "desc"
line_items?boolean

Include line items data.

Defaultfalse
discounts?boolean

Include discounts data.

Defaultfalse
taxes?boolean

Include taxes data.

Defaultfalse
credits?boolean

Include credits data.

Defaultfalse
payments?boolean

Include payments data.

Defaultfalse
custom_fields?boolean

Include custom fields data.

Defaultfalse
refunds?boolean

Include refunds data.

Defaultfalse
date_field?Invoice Date Field

The type of filter you would like to apply to your search. Use in query date_field=issue_date.

Default"due_date"

Value in

  • "created_at"
  • "due_date"
  • "issue_date"
  • "updated_at"
  • "paid_date"
start_datetime?string

The start date and time (format YYYY-MM-DD HH:MM:SS) with which to filter the date_field. Returns invoices with a timestamp at or after exact time provided in query. You can specify timezone in query - otherwise your site's time zone will be used. If provided, this parameter will be used instead of start_date. Allowed to be used only along with date_field set to created_at or updated_at.

end_datetime?string

The end date and time (format YYYY-MM-DD HH:MM:SS) with which to filter the date_field. Returns invoices with a timestamp at or before exact time provided in query. You can specify timezone in query - otherwise your site's time zone will be used. If provided, this parameter will be used instead of end_date. Allowed to be used only along with date_field set to created_at or updated_at.

customer_ids?array<integer>

Allows fetching invoices with matching customer id based on provided values. Use in query customer_ids=1,2,3.

number?array<string>

Allows fetching invoices with matching invoice number based on provided values. Use in query number=1234,1235.

product_ids?array<integer>

Allows fetching invoices with matching line items product ids based on provided values. Use in query product_ids=23,34.

sort?Invoice Sort Field

Allows specification of the order of the returned list. Use in query sort=total_amount.

Default"number"

Value in

  • "status"
  • "total_amount"
  • "due_amount"
  • "created_at"
  • "updated_at"
  • "issue_date"
  • "due_date"
  • "number"

Response Body

application/json

curl -X GET "https://example.com/invoices.json"
{  "invoices": [    {      "uid": "inv_8htcd29wcq3q6",      "site_id": 51288,      "customer_id": 20153415,      "subscription_id": 23277588,      "number": "125",      "sequence_number": 125,      "issue_date": "2018-09-20",      "due_date": "2018-09-20",      "paid_date": "2018-09-20",      "status": "paid",      "collection_method": "automatic",      "payment_instructions": "Make checks payable to Acme, Inc.",      "currency": "USD",      "consolidation_level": "parent",      "parent_invoice_uid": null,      "parent_invoice_number": null,      "group_primary_subscription_id": 23277588,      "product_name": "Trial and setup fee",      "product_family_name": "Billing Plans",      "seller": {        "name": "General Goods",        "address": {          "street": "123 General Goods Way",          "line2": "Apt. 10",          "city": "Boston",          "state": "MA",          "zip": "02120",          "country": "US"        },        "phone": "555-555-1212"      },      "customer": {        "chargify_id": 20153415,        "first_name": "Meg",        "last_name": "Example",        "organization": "",        "email": "meg@example.com"      },      "memo": "Payment due within 15 days of receipt.",      "billing_address": {        "street": "123 I Love Cats Way",        "line2": "",        "city": "Boston",        "state": "MA",        "zip": "90210",        "country": "US"      },      "shipping_address": {        "street": "123 I Love Cats Way",        "line2": "",        "city": "Boston",        "state": "MA",        "zip": "90210",        "country": "US"      },      "subtotal_amount": "100.0",      "discount_amount": "0.0",      "tax_amount": "0.0",      "total_amount": "100.0",      "credit_amount": "0.0",      "paid_amount": "100.0",      "refund_amount": "0.0",      "due_amount": "0.0",      "public_url": "https://www.chargifypay.com/invoice/inv_8htcd29wcq3q6?token=n9fr5fxff5v74c7h9srg3cwd"    },    {      "uid": "inv_8hr3546xp4h8n",      "site_id": 51288,      "customer_id": 21687686,      "subscription_id": 22007644,      "number": "124",      "sequence_number": 124,      "issue_date": "2018-09-18",      "due_date": "2018-09-18",      "paid_date": null,      "status": "open",      "collection_method": "remittance",      "payment_instructions": "Make checks payable to Acme, Inc.",      "currency": "USD",      "consolidation_level": "none",      "parent_invoice_uid": null,      "parent_invoice_number": null,      "group_primary_subscription_id": null,      "product_name": "Trial and setup fee",      "product_family_name": "Billing Plans",      "seller": {        "name": "General Goods",        "address": {          "street": "123 General Goods Way",          "line2": "Apt. 10",          "city": "Boston",          "state": "MA",          "zip": "02120",          "country": "US"        },        "phone": "555-555-1212"      },      "customer": {        "chargify_id": 21687686,        "first_name": "Charlene",        "last_name": "Tester",        "organization": "",        "email": "food@example.com"      },      "memo": "Payment due within 15 days of receipt.",      "billing_address": {        "street": "",        "line2": "",        "city": "",        "state": "",        "zip": "",        "country": ""      },      "shipping_address": {        "street": "",        "line2": "",        "city": "",        "state": "",        "zip": "",        "country": ""      },      "subtotal_amount": "100.0",      "discount_amount": "0.0",      "tax_amount": "0.0",      "total_amount": "100.0",      "credit_amount": "0.0",      "paid_amount": "0.0",      "refund_amount": "0.0",      "due_amount": "100.0",      "public_url": "https://www.chargifypay.com/invoice/inv_8hr3546xp4h8n?token=n9fr5fxff5v74c7h9srg3cwd"    },    {      "uid": "inv_8hr3546wdwxkr",      "site_id": 51288,      "customer_id": 21687670,      "subscription_id": 22007627,      "number": "123",      "sequence_number": 123,      "issue_date": "2018-09-18",      "due_date": "2018-09-18",      "paid_date": "2018-09-18",      "status": "paid",      "collection_method": "automatic",      "payment_instructions": "Make checks payable to Acme, Inc.",      "currency": "USD",      "consolidation_level": "none",      "parent_invoice_uid": null,      "parent_invoice_number": null,      "group_primary_subscription_id": null,      "product_name": "Trial End - Free",      "product_family_name": "Billing Plans",      "seller": {        "name": "General Goods",        "address": {          "street": "123 General Goods Way",          "line2": "Apt. 10",          "city": "Boston",          "state": "MA",          "zip": "02120",          "country": "US"        },        "phone": "555-555-1212"      },      "customer": {        "chargify_id": 21687670,        "first_name": "Hello",        "last_name": "World",        "organization": "123",        "email": "example@example.com"      },      "memo": "Payment due within 15 days of receipt.",      "billing_address": {        "street": "123 Anywhere Street",        "line2": "",        "city": "Boston",        "state": "MA",        "zip": "02120",        "country": "US"      },      "shipping_address": {        "street": "",        "line2": "",        "city": "Boston",        "state": "AL",        "zip": "02120",        "country": "US"      },      "subtotal_amount": "0.0",      "discount_amount": "0.0",      "tax_amount": "0.0",      "total_amount": "0.0",      "credit_amount": "0.0",      "paid_amount": "0.0",      "refund_amount": "0.0",      "due_amount": "0.0",      "public_url": "https://www.chargifypay.com/invoice/inv_8hr3546wdwxkr?token=n9fr5fxff5v74c7h9srg3cwd"    },    {      "uid": "inv_8hjtk8bz56bbp",      "site_id": 51288,      "customer_id": 20137757,      "subscription_id": 20541100,      "number": "122",      "sequence_number": 122,      "issue_date": "2018-09-10",      "due_date": "2018-09-10",      "paid_date": "2018-09-10",      "status": "paid",      "collection_method": "automatic",      "payment_instructions": "Make checks payable to Acme, Inc.",      "currency": "USD",      "consolidation_level": "none",      "parent_invoice_uid": null,      "parent_invoice_number": null,      "group_primary_subscription_id": null,      "product_name": "$0 Product",      "product_family_name": "Billing Plans",      "seller": {        "name": "General Goods",        "address": {          "street": "123 General Goods Way",          "line2": "Apt. 10",          "city": "Boston",          "state": "MA",          "zip": "02120",          "country": "US"        },        "phone": "555-555-1212"      },      "customer": {        "chargify_id": 20137757,        "first_name": "Sasha",        "last_name": "Example",        "organization": "",        "email": "example@example.com"      },      "memo": "Payment due within 15 days of receipt.",      "billing_address": {        "street": "123 I Love Cats Way",        "line2": "",        "city": "Catville",        "state": "MA",        "zip": "90210",        "country": "US"      },      "shipping_address": {        "street": "123 I Love Cats Way",        "line2": "",        "city": "Catville",        "state": "AL",        "zip": "90210",        "country": "US"      },      "subtotal_amount": "0.0",      "discount_amount": "0.0",      "tax_amount": "0.0",      "total_amount": "0.0",      "credit_amount": "0.0",      "paid_amount": "0.0",      "refund_amount": "0.0",      "due_amount": "0.0",      "public_url": "https://www.chargifypay.com/invoice/inv_8hjtk8bz56bbp?token=fb6kpjz5rcr2vttyjs4rcv6y"    }  ]}

Refund Invoice POST

Refunds an invoice, segment, or consolidated invoice. ## Partial Refund for Consolidated Invoice A refund less than the total of a consolidated invoice will be split across its segments. For a $50.00 refund on a $100.00 consolidated invoice with one $60.00 segment and one $40.00 segment, the refunded amount will be applied as 50% of each ($30.00 and $20.00, respectively).

Read Invoice GET

Returns the details for an invoice. ## PDF Invoice retrieval Individual PDF Invoices can be retrieved by using the "Accept" header application/pdf or appending .pdf as the format portion of the URL: ```curl -u <api_key>:x -H Accept:application/pdf -H https://acme.chargify.com/invoices/inv_8gd8tdhtd3hgr.pdf > output_file.pdf URL: `https://<subdomain>.chargify.com/invoices/<uid>.<format>` Method: GET Required parameters: `uid` Response: A single Invoice. ```