Lists invoices and credit notes on an account. Only returns basic info; use invoice.getdetails to get
more detail on an individual invoice or credit note. Supply the invoiceID value returned by this function in the invoiceID
argument to invoice.getdetails.
This function treats invoices and credit notes alike; any reference to an invoice or some invoices should also be taken to include credit notes.
You can use this function to get a list of invoices which you have raised to your customers (if applicable) or a list of invoices which have been raised on your account for you to pay. To get a list of invoices that you have raised to your customers, you should put your own custID value into the invoicerID argument (the person raising the invoice is the invoicer, whereas the person being invoiced is the invoicee). To get a list of invoices raised to you, you should put your custID value into the invoiceeID field. In fact, you can put any custID into the invoiceeID field to see a list of invoices that have been raised to them so long as that account is a child account of the one you are logged in with, or a grandchild account, etc.
| arg | required? | syntax | info |
|---|---|---|---|
invoiceeID | conditional | posint | custID of invoicee; you must provide this or invoicerID |
invoicerID | conditional | posint | custID of invoicer; you must provide this or invoiceeID |
invoicer_company | N | string | optional filter; billcomp owning the invoices being listed (exclusive with invoicer_companyID) |
invoicer_companyID | N | string | optional filter; ID of billcomp owning the invoices being listed (exclusive with invoicer_company) |
invoiceID | N | list:posint | optional filter; array or comma separated list of invoiceIDs - restricts results to just invoices with these invoiceIDs |
invnum | N | list:posint | optional filter; array or comma separated list of invoice numbers - restricts results to just invoices with these invoice numbers |
minwhenpaidID | N | posint | optional filter; limit results to invoices having whenpaidID greater or equal to this |
maxwhenpaidID | N | posint | optional filter; limit results to invoices having whenpaidID less or equal to this |
minupdateID | N | posint | optional filter; limit results to invoices having updateID greater or equal to this |
maxupdateID | N | posint | optional filter; limit results to invoices having updateID less or equal to this |
age.min | N | (see longdesc) | optional filter; limit results to invoices raised at least this long ago |
age.max | N | (see age.min) | optional filter; limit results to invoices raised at most this long ago |
date.min | N | isodate | optional filter; limit results to invoices raised on or after this date |
date.max | N | isodate | optional filter; limit results to invoices raised on or before this date |
payment_due.min | N | isodate | optional filter; limit results to invoices having a payment_due on or after this date |
payment_due.max | N | isodate | optional filter; limit results to invoices having a payment_due on or before this date |
enforce_date.min | N | isodate | optional filter; limit results to invoices having an enforce_date on or after this date |
enforce_date.max | N | isodate | optional filter; limit results to invoices having an enforce_date on or before this date |
expected_payment | N | (see longdesc) | optional filter; limit results to invoices having specific expected_payment values |
status | N | (see longdesc) | optional filter; limit results to invoices having specific status values |
has_dd_instruction | N | boolean | optional filter; limit results to invoices where a direct debit has been submitted to the bank for payment |
alsoget | N | list:enum | option to return additional fields |
startfrom | N | unsint | first matching invoice to return, counting from zero |
numtoreturn | N | posint | number of records to return (subject to a built in hard limit) |
The invoicee is the account which the invoice is being raised to, ie the customer who will be paying the bill. If you want to list invoices raised on a particular account (ie for that customer to pay), then put their custID into this field.
If you want to see all invoices raised to you (ie for you to pay), put your own custID into this field.
The invoicer is the account that is raising the invoice. Putting your account number in here will result in the invoices that you have raised to your customers being returned. Unless you are are a reseller and are using this system to raise your invoices, this is probably not what you want.
Within a supplier's account, there may be several separate companies. Supplying this argument limits results to just returning invoices raised by that specific company.
For a list of companies that a reseller account contains (and therefore can be the invoicer for), look for the [billing_companies] element returned by the API login process. This is keyed by company keyword.
For a list of companies that you are a client of (and could therefore raise invoices to you), see the [custof] element returned by the API login process. This is keyed by company keyword.
Alternative and slightly more efficient way of specifying invoicer_company. Takes the companyID value from the invoicer company data. See the invoicer_company description for more info.
Specify this argument as a minimum age filter, so that you only list invoices raised more than a certain amount of time ago. Specify as an integer, a space and then one of second,minute,hour,day,month,year. For example, if you want to only list invoices that were raised at least half an hour ago, specify "30 MINUTE"
When raising an invoice, you can define the expected payment type. This can effect certain automated processes such as a
direct debit run, etc. See invoice.create for more details.
Use this field to only return records with specific statuses (stati?). Supply an array or a string containing a comma separeted list. Supply one or more values from the following:
For example, if you supply 'unused,partused' then this function will only list credit notes that have some unused money that can be assigned to things (eg invoices or refunds).
This field takes a list (comma separated string, or array) of values from the following list:
List all invoices on account 16526 raised on or after 10 August 2009, sort by invoice number and skip the first 6 results:
Perl example request:
POST https://live.apicontrol.co.uk/1/json
my $api = new CCclient($u, $p, $is_live);
my %args =
(
'invoiceeID' => 16526,
'date.min' => '2009-08-10',
'sort' => 'invnum'
'startfrom' => 6
);
my $res = $api->invoice_list(%args);PHP example request:
POST https://live.apicontrol.co.uk/1/json
$api = new_CCclient($u, $p, $is_live);
$args = array
(
'invoiceeID' => 16526,
'date.min' => '2009-08-10',
'sort'=>'invnum',
'startfrom'=>614
);
$res = $api->invoice_list($args);XML example request:
POST https://live.apicontrol.co.uk/1/json
In this example, the response returned 5 results (4 invoices and a credit note). Invoice 179176 is unpaid and still has the full amount oweing on it.
The credit note (credit note 179177) is unused, so it could be used to pay off the invoice (see payment.assign).
invoice.create for detailsPerl example response:
{
'success' => '1',
'error' => '',
'errornum' => '',
'errordiags' => '',
'results' => {
'totmatches' => '11',
'invlist' => [
{
'payment_due' => '2009-08-17',
'vat' => '1.50',
'inv_or_credit' => 'invoice',
'status' => 'paid',
'date' => '2009-08-10 10:13:25',
'subtotal' => '10.00',
'expected_payment' => 'manual',
'invoiceID' => '112324',
'invoicer_company' => 'skymarket',
'invoicer_companyID' => '1',
'total' => '11.50',
'enforce_date' => '2009-08-18',
'invnum' => '179153',
'invoicerID' => '13810',
'invoiceeID' => '16526',
'amount_outstanding' => '0.00',
'updateID' => '6137067',
'notifywhenpaid' => '1'
},
{
'payment_due' => '2009-08-17',
'vat' => '1.50',
'inv_or_credit' => 'invoice',
'status' => 'paid',
'date' => '2009-08-10 10:15:16',
'subtotal' => '10.00',
'expected_payment' => 'manual',
'invoiceID' => '112325',
'invoicer_company' => 'skymarket',
'invoicer_companyID' => '1',
'total' => '11.50',
'enforce_date' => '2009-08-18',
'invnum' => '179154',
'invoicerID' => '13810',
'invoiceeID' => '16526',
'amount_outstanding' => '0.00',
'updateID' => '6137070',
'notifywhenpaid' => '1'
},
{
'payment_due' => '2009-08-17',
'vat' => '1.50',
'inv_or_credit' => 'invoice',
'status' => 'paid',
'date' => '2009-08-10 11:41:43',
'subtotal' => '10.00',
'expected_payment' => 'manual',
'invoiceID' => '112328',
'invoicer_company' => 'skymarket',
'invoicer_companyID' => '1',
'total' => '11.50',
'enforce_date' => '2009-08-18',
'invnum' => '179156',
'invoicerID' => '13810',
'invoiceeID' => '16526',
'amount_outstanding' => '0.00',
'updateID' => '6137080',
'notifywhenpaid' => '1'
},
{
'payment_due' => '2009-08-25',
'vat' => '3.30',
'inv_or_credit' => 'invoice',
'status' => 'unpaid',
'date' => '2009-08-18 17:35:27',
'subtotal' => '22.00',
'expected_payment' => 'manual',
'invoiceID' => '112362',
'invoicer_company' => 'skymarket',
'invoicer_companyID' => '1',
'total' => '25.30',
'enforce_date' => '2009-08-26',
'invnum' => '179176',
'invoicerID' => '13810',
'invoiceeID' => '16526',
'amount_outstanding' => '25.30',
'updateID' => '6137207',
'notifywhenpaid' => '1'
},
{
'payment_due' => '0000-00-00',
'vat' => '-7.50',
'inv_or_credit' => 'creditnote',
'status' => 'unused',
'date' => '2009-08-21 16:56:37',
'subtotal' => '-50.00',
'expected_payment' => 'manual',
'invoiceID' => '112364',
'invoicer_company' => 'skymarket',
'invoicer_companyID' => '1',
'total' => '-57.50',
'enforce_date' => '2009-08-22',
'invnum' => '179177',
'invoicerID' => '13810',
'invoiceeID' => '16526',
'amount_outstanding' => '-57.50',
'updateID' => '6138499',
'notifywhenpaid' => '1'
}
]
}
};PHP example response:
Array
(
[success] => 1
[error] =>
[errornum] =>
[errordiags] =>
[results] => Array
(
[invlist] => Array
(
[0] => Array
(
[invoiceID] => 112324
[invnum] => 179153
[date] => 2009-08-10 10:13:25
[invoiceeID] => 16526
[invoicerID] => 13810
[invoicer_companyID] => 1
[inv_or_credit] => invoice
[subtotal] => 10.00
[vat] => 1.50
[total] => 11.50
[amount_outstanding] => 0.00
[updateID] => 6137067
[payment_due] => 2009-08-17
[enforce_date] => 2009-08-18
[status] => paid
[expected_payment] => manual
[notifywhenpaid] => 1
[invoicer_company] => skymarket
)
[1] => Array
(
[invoiceID] => 112325
[invnum] => 179154
[date] => 2009-08-10 10:15:16
[invoiceeID] => 16526
[invoicerID] => 13810
[invoicer_companyID] => 1
[inv_or_credit] => invoice
[subtotal] => 10.00
[vat] => 1.50
[total] => 11.50
[amount_outstanding] => 0.00
[updateID] => 6137070
[payment_due] => 2009-08-17
[enforce_date] => 2009-08-18
[status] => paid
[expected_payment] => manual
[notifywhenpaid] => 1
[invoicer_company] => skymarket
)
[2] => Array
(
[invoiceID] => 112328
[invnum] => 179156
[date] => 2009-08-10 11:41:43
[invoiceeID] => 16526
[invoicerID] => 13810
[invoicer_companyID] => 1
[inv_or_credit] => invoice
[subtotal] => 10.00
[vat] => 1.50
[total] => 11.50
[amount_outstanding] => 0.00
[updateID] => 6137080
[payment_due] => 2009-08-17
[enforce_date] => 2009-08-18
[status] => paid
[expected_payment] => manual
[notifywhenpaid] => 1
[invoicer_company] => skymarket
)
[3] => Array
(
[invoiceID] => 112362
[invnum] => 179176
[date] => 2009-08-18 17:35:27
[invoiceeID] => 16526
[invoicerID] => 13810
[invoicer_companyID] => 1
[inv_or_credit] => invoice
[subtotal] => 22.00
[vat] => 3.30
[total] => 25.30
[amount_outstanding] => 25.30
[updateID] => 6137207
[payment_due] => 2009-08-25
[enforce_date] => 2009-08-26
[status] => unpaid
[expected_payment] => manual
[notifywhenpaid] => 1
[invoicer_company] => skymarket
)
[4] => Array
(
[invoiceID] => 112364
[invnum] => 179177
[date] => 2009-08-21 16:56:37
[invoiceeID] => 16526
[invoicerID] => 13810
[invoicer_companyID] => 1
[inv_or_credit] => creditnote
[subtotal] => -50.00
[vat] => -7.50
[total] => -57.50
[amount_outstanding] => -57.50
[updateID] => 6138499
[payment_due] => 0000-00-00
[enforce_date] => 2009-08-22
[status] => unused
[expected_payment] => manual
[notifywhenpaid] => 1
[invoicer_company] => skymarket
)
)
[totmatches] => 11
)
)XML example response: