Invoices

Raise, amend, send and cancel invoices. Invoices move through the statuses `DRAFT`, `SCHEDULED`, `UNPAID`, `OVERDUE`, `PARTIALLY_PAID`, `PAID` and `CANCELLED`.

List invoices

GET/invoices

Returns invoices newest first, using cursor pagination. Keep following next_cursor until has_more is false.

Authorization

accountKey

AuthorizationBearer <token>

An account API key, in the form ct_live_ followed by 32 characters. Generate one in the Chargetree dashboard under Settings → API. The plaintext key is shown only once.

Send it as Authorization: Bearer ct_live_....

In: header

Query Parameters

status?string

Filter by status. Accepts a single status or a comma-separated list, for example UNPAID,OVERDUE.

contact_id?string

Only invoices belonging to this contact.

Formatuuid

invoice_number?string

Exact match on the invoice number.

date_from?string

Only invoices dated on or after this day.

Formatdate

date_to?string

Only invoices dated on or before this day.

Formatdate

limit?integer

How many invoices to return. Values above 100 are capped at 100.

Range1 <= value <= 100

Default25

cursor?string

The next_cursor value from the previous page.

Response Body

`application/json`

curl -X GET "https://example.com/invoices?status=UNPAID%2COVERDUE"

{  "data": [    {      "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",      "invoice_number": "string",      "status": "DRAFT",      "is_draft": true,      "contact": null,      "invoice_date": "2019-08-24",      "due_date": "2019-08-24",      "currency": "string",      "line_amount_types": "string",      "sub_total": 0,      "tax_total": 0,      "total": 0,      "amount_paid": 0,      "amount_due": 0,      "line_items": [        {          "id": "string",          "description": "string",          "quantity": 0,          "unit_amount": 0,          "tax_rate": 0,          "tax_amount": 0,          "line_amount": 0        }      ],      "payments": [        {          "id": "string",          "amount": 0,          "currency": "string",          "received_at": "2019-08-24T14:15:22Z",          "method": "string",          "reference": "string",          "recorded_by": "user"        }      ],      "reference": "string",      "notes": "string",      "staff": "string",      "is_editable": true,      "sent_to_contact": true,      "last_sent_at": "2019-08-24T14:15:22Z",      "send_count": 0,      "pay_url": "string",      "xero_invoice_id": "string",      "created_at": "2019-08-24T14:15:22Z",      "updated_at": "2019-08-24T14:15:22Z"    }  ],  "next_cursor": "string",  "has_more": true}

Create an invoice

POST/invoices

Creates an invoice and, optionally, emails it to the contact straight away.

This endpoint honours the Idempotency-Key header, so a retried call after a dropped connection will not raise a second invoice.

Authorization

accountKey

AuthorizationBearer <token>

An account API key, in the form ct_live_ followed by 32 characters. Generate one in the Chargetree dashboard under Settings → API. The plaintext key is shown only once.

Send it as Authorization: Bearer ct_live_....

In: header

Header Parameters

Idempotency-Key?string

A unique value of your choosing, typically a UUID, that lets you retry this request safely. Replaying the same key with the same body returns the original response instead of acting twice.

Request Body

application/json

TypeScript Definitions

Use the request body type in TypeScript.

contact*

Identifies a contact, either by pointing at an existing one or by describing a new one.

invoice_number?string

Your own invoice number. Generated for you when omitted, and must be unique within your account.

invoice_date?string

The date the invoice is raised. Defaults to today.

Formatdate

due_date?string

The date payment is due.

Formatdate

reference?string

notes?string

staff?string

Free text naming whoever raised the invoice.

currency_code?string

Defaults to your account's currency.

line_amount_types?string

Whether line amounts include tax. Defaults to Exclusive.

Default"Exclusive"

Value in

"Exclusive"
"Inclusive"
"NoTax"

line_items*array<>

Items1 <= items

send_invoice?boolean

Email the invoice to the contact immediately. Cannot be combined with is_draft: true.

Defaultfalse

is_draft?boolean

Save as a draft rather than raising it live. Omitted or false, the invoice is raised as UNPAID, or OVERDUE if the due date has already passed.

Defaultfalse

Response Body

`application/json`

curl -X POST "https://example.com/invoices" \  -H "Idempotency-Key: 0f2a5f1e-9f1a-4e0c-9a4e-2a9b7d1f6c33" \  -H "Content-Type: application/json" \  -d '{    "contact": {      "email": "ap@acme.example"    },    "invoice_date": "2026-07-01",    "due_date": "2026-07-31",    "line_items": [      {        "description": "Onsite EV charger installation",        "quantity": 1,        "unit_amount": 1850,        "tax_rate": 10,        "tax_type": "OUTPUT"      }    ],    "send_invoice": true  }'

{  "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",  "invoice_number": "string",  "status": "DRAFT",  "is_draft": true,  "contact": null,  "invoice_date": "2019-08-24",  "due_date": "2019-08-24",  "currency": "string",  "line_amount_types": "string",  "sub_total": 0,  "tax_total": 0,  "total": 0,  "amount_paid": 0,  "amount_due": 0,  "line_items": [    {      "id": "string",      "description": "string",      "quantity": 0,      "unit_amount": 0,      "tax_rate": 0,      "tax_amount": 0,      "line_amount": 0    }  ],  "payments": [    {      "id": "string",      "amount": 0,      "currency": "string",      "received_at": "2019-08-24T14:15:22Z",      "method": "string",      "reference": "string",      "recorded_by": "user"    }  ],  "reference": "string",  "notes": "string",  "staff": "string",  "is_editable": true,  "sent_to_contact": true,  "last_sent_at": "2019-08-24T14:15:22Z",  "send_count": 0,  "pay_url": "string",  "xero_invoice_id": "string",  "created_at": "2019-08-24T14:15:22Z",  "updated_at": "2019-08-24T14:15:22Z"}

Retrieve an invoice

GET/invoices/{id}

Returns a single invoice, including its line items and any payments recorded against it.

Authorization

accountKey

AuthorizationBearer <token>

An account API key, in the form ct_live_ followed by 32 characters. Generate one in the Chargetree dashboard under Settings → API. The plaintext key is shown only once.

Send it as Authorization: Bearer ct_live_....

In: header

Path Parameters

id*string

The invoice's Chargetree identifier.

Formatuuid

Response Body

`application/json`

curl -X GET "https://example.com/invoices/497f6eca-6276-4993-bfeb-53cbbbba6f08"

{  "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",  "invoice_number": "string",  "status": "DRAFT",  "is_draft": true,  "contact": null,  "invoice_date": "2019-08-24",  "due_date": "2019-08-24",  "currency": "string",  "line_amount_types": "string",  "sub_total": 0,  "tax_total": 0,  "total": 0,  "amount_paid": 0,  "amount_due": 0,  "line_items": [    {      "id": "string",      "description": "string",      "quantity": 0,      "unit_amount": 0,      "tax_rate": 0,      "tax_amount": 0,      "line_amount": 0    }  ],  "payments": [    {      "id": "string",      "amount": 0,      "currency": "string",      "received_at": "2019-08-24T14:15:22Z",      "method": "string",      "reference": "string",      "recorded_by": "user"    }  ],  "reference": "string",  "notes": "string",  "staff": "string",  "is_editable": true,  "sent_to_contact": true,  "last_sent_at": "2019-08-24T14:15:22Z",  "send_count": 0,  "pay_url": "string",  "xero_invoice_id": "string",  "created_at": "2019-08-24T14:15:22Z",  "updated_at": "2019-08-24T14:15:22Z"}

Update an invoice

PUT/invoices/{id}

Amends an invoice. Only the fields you send are changed.

Sending line_items replaces every existing line, so include the full set, not just the ones that changed.

Invoices that have been paid or cancelled are locked and return INVOICE_LOCKED.

Authorization

accountKey

AuthorizationBearer <token>

An account API key, in the form ct_live_ followed by 32 characters. Generate one in the Chargetree dashboard under Settings → API. The plaintext key is shown only once.

Send it as Authorization: Bearer ct_live_....

In: header

Path Parameters

id*string

The invoice's Chargetree identifier.

Formatuuid

Request Body

application/json

TypeScript Definitions

Use the request body type in TypeScript.

Only the fields you send are changed.

contact?

Identifies a contact, either by pointing at an existing one or by describing a new one.

invoice_number?string

invoice_date?string

Formatdate

due_date?string

Formatdate

reference?string|null

notes?string|null

staff?string|null

currency_code?string

line_amount_types?string

Value in

"Exclusive"
"Inclusive"
"NoTax"

line_items?array<>

Replaces every existing line item. Send the complete set.

send_invoice?boolean

is_draft?boolean

Move the invoice into or out of draft. A draft can be finalised, and a live invoice can go back to draft only while it has never been sent and carries no payment.

Response Body

`application/json`

curl -X PUT "https://example.com/invoices/497f6eca-6276-4993-bfeb-53cbbbba6f08" \  -H "Content-Type: application/json" \  -d '{}'

{  "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",  "invoice_number": "string",  "status": "DRAFT",  "is_draft": true,  "contact": null,  "invoice_date": "2019-08-24",  "due_date": "2019-08-24",  "currency": "string",  "line_amount_types": "string",  "sub_total": 0,  "tax_total": 0,  "total": 0,  "amount_paid": 0,  "amount_due": 0,  "line_items": [    {      "id": "string",      "description": "string",      "quantity": 0,      "unit_amount": 0,      "tax_rate": 0,      "tax_amount": 0,      "line_amount": 0    }  ],  "payments": [    {      "id": "string",      "amount": 0,      "currency": "string",      "received_at": "2019-08-24T14:15:22Z",      "method": "string",      "reference": "string",      "recorded_by": "user"    }  ],  "reference": "string",  "notes": "string",  "staff": "string",  "is_editable": true,  "sent_to_contact": true,  "last_sent_at": "2019-08-24T14:15:22Z",  "send_count": 0,  "pay_url": "string",  "xero_invoice_id": "string",  "created_at": "2019-08-24T14:15:22Z",  "updated_at": "2019-08-24T14:15:22Z"}

Cancel an invoice

POST/invoices/{id}/cancel

Soft-cancels the invoice: the status becomes CANCELLED and the amount due is set to zero. Nothing is deleted, so the invoice stays readable.

If the invoice was synced to Xero, Chargetree also tries to void it there. The cancellation in Chargetree succeeds either way.

Invoices that are already paid cannot be cancelled.

Note this endpoint does not honour Idempotency-Key; the header is ignored. Cancelling twice is harmless, as the second call simply reports the invoice is no longer cancellable.

Authorization

accountKey

AuthorizationBearer <token>

An account API key, in the form ct_live_ followed by 32 characters. Generate one in the Chargetree dashboard under Settings → API. The plaintext key is shown only once.

Send it as Authorization: Bearer ct_live_....

In: header

Path Parameters

id*string

The invoice's Chargetree identifier.

Formatuuid

Response Body

`application/json`

curl -X POST "https://example.com/invoices/497f6eca-6276-4993-bfeb-53cbbbba6f08/cancel"

{  "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",  "invoice_number": "string",  "status": "DRAFT",  "is_draft": true,  "contact": null,  "invoice_date": "2019-08-24",  "due_date": "2019-08-24",  "currency": "string",  "line_amount_types": "string",  "sub_total": 0,  "tax_total": 0,  "total": 0,  "amount_paid": 0,  "amount_due": 0,  "line_items": [    {      "id": "string",      "description": "string",      "quantity": 0,      "unit_amount": 0,      "tax_rate": 0,      "tax_amount": 0,      "line_amount": 0    }  ],  "payments": [    {      "id": "string",      "amount": 0,      "currency": "string",      "received_at": "2019-08-24T14:15:22Z",      "method": "string",      "reference": "string",      "recorded_by": "user"    }  ],  "reference": "string",  "notes": "string",  "staff": "string",  "is_editable": true,  "sent_to_contact": true,  "last_sent_at": "2019-08-24T14:15:22Z",  "send_count": 0,  "pay_url": "string",  "xero_invoice_id": "string",  "created_at": "2019-08-24T14:15:22Z",  "updated_at": "2019-08-24T14:15:22Z"}

200application/json

400application/json

401application/json

403application/json

429application/json

201application/json

400application/json

401application/json

403application/json

409application/json

429application/json

500application/json

200application/json

401application/json

404application/json

429application/json

200application/json

400application/json

401application/json

404application/json

409application/json

429application/json

200application/json

400application/json

401application/json

404application/json

429application/json

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`