Invoices

Apply a customer's credit to an invoice

POST
/v1/invoices/{id}/apply-credit

Draws on the customer's unallocated payment credit, oldest payment first, to pay down this invoice as far as the credit in the invoice's own currency goes. Refused when the invoice is not open, or there is no credit in that currency.

Authorization

apiKey
headerAuthorizationBearer <token>

An API key from the Developers page. rhq_test_ keys reach the sandbox, rhq_live_ keys the live side.

Path Parameters

id*string

Response Body

Success

application/json
  1. response

Success

id*string
number*string

Counts up from INV-0001 across your account, with no gaps

customerId*string
currency*string

The currency of every amount on the invoice

Value in"USD""EUR""GBP""CAD""AUD""NZD""CHF""SEK""NOK""DKK""PLN""INR""SGD""HKD""AED""ZAR""BRL""MXN"
lines*array<>
subtotal*integer

The lines added up, before tax

Range0 <= value
taxBps*|

The tax rate in basis points. Null when there is no tax

tax*integer

subtotal times the tax rate, rounded

Range0 <= value
taxLines*array<>

How tax is made up, line by line: one entry per matched tax rule component. Empty on an invoice priced with the flat taxBps or with no tax at all

reverseCharge*|

Set when the matched tax rule reverse-charges this invoice: tax is 0 and this is the legal note and both parties' tax numbers as they stood at issue

total*integer

What the customer owes: subtotal plus tax

Range0 <= value
status*string

credited was corrected in full by credit notes and asks for nothing

Value in"open""paid""void""credited"
overdue*boolean

True for an open invoice whose due date has passed: from a day after dueAt, so an invoice due today is not overdue today

shared*boolean

True once POST /invoices/{id}/share has made a public link for this invoice, false again once revoked. The token itself is never in this response or the list

issuedAt*string
Formatdate-time
dueAt*string
Formatdate-time
paidAt*|null
voidedAt*|null
note*string|null
credited*integer

What credit notes against this invoice come to. 0 when there are none

Range0 <= value
paidAmount*integer

Collected so far via payments applied to this invoice. 0 until the first one

Range0 <= value
amountDue*integer

What is still owed: total less credited and paidAmount, and 0 on one that is paid, void or credited in full

Range0 <= value
creditedAt*|null
issuer*|

Your account as it billed this invoice, copied at the time it was issued. Null on invoices made before you set any billing details

actor*|

Who raised this invoice

voidedBy*|

Who voided this invoice. Null unless status is void

paidBy*|

Who recorded this invoice as paid. Null unless status is paid through that path

sharedBy*|

Who last shared this invoice. Null until it has ever been shared

curl -X POST "https://example.com/v1/invoices/inv_01K6XJ4Q8ZT3M9R5V2B7WDHNCA/apply-credit"
{  "id": "inv_01K6XJ4Q8ZT3M9R5V2B7WDHNCA",  "number": "INV-0001",  "customerId": "cus_01K6XJ4Q8ZT3M9R5V2B7WDHNCA",  "currency": "USD",  "lines": [    {      "saleId": "sal_01K6XJ4Q8ZT3M9R5V2B7WDHNCA",      "description": "northwind-telecom.com, 2 years",      "quantity": 2,      "unitPrice": 1439,      "total": 2878    }  ],  "subtotal": 2878,  "taxBps": 2000,  "tax": 576,  "taxLines": [    {      "name": "string",      "rateBps": 2000,      "amount": 2878    }  ],  "reverseCharge": {    "note": "string",    "sellerTaxId": "string",    "customerTaxId": "string"  },  "total": 3454,  "status": "open",  "overdue": true,  "shared": true,  "issuedAt": "2026-10-07T11:04:31.000Z",  "dueAt": "2026-10-21T11:04:31.000Z",  "paidAt": null,  "voidedAt": null,  "note": "Thank you for your business",  "credited": 2878,  "paidAmount": 2878,  "amountDue": 2878,  "creditedAt": null,  "issuer": {    "name": "Northwind Telecom",    "legalName": null,    "addressLines": [],    "taxId": null,    "billingEmail": null  },  "actor": {    "kind": "user",    "label": "string"  },  "voidedBy": {    "kind": "user",    "label": "string"  },  "paidBy": {    "kind": "user",    "label": "string"  },  "sharedBy": {    "kind": "user",    "label": "string"  }}