Raises an invoice or credit note. VAT is calculated automatically. The customer's account balance will be decreased (for invoices) or increased (for credit notes).
Invoices will automatically be emailed to the customer (email address derived from the supplied args).
| arg | required? | syntax | info |
|---|---|---|---|
custID | Y | posint | custID of account being invoiced |
items | Y | array | array of invoice/creditnote items |
invoicerID | N | posint | custID of account raising the invoice (default is your own account) |
invoicer_companyID | grp1 | posint | billing company ID of billing company raising the invoice |
invoicer_company | grp1 | string | name of billing company; alternative to using invoicer_companyID |
inv_or_credit | N | enum:invoice|creditnote | Set to 'invoice' to raise an invoice, 'creditnote' to raise a credit note. Default = 'invoice' |
expected_payment | N | enum:card|manual|automated|direct debit|standing order|bacs|cheque|cash|postal order | Type of payment expected (leave blank if you are unsure) |
payment_due | N | isodate | if specified, overrides the default due date |
enforce_date | N | isodate | defaults to the current raise date |
notify_when_paid | N | boolean | should evaluate to true if needed; staff will be notified when an invoice has been paid. |
ignore_credit_limit | N | boolean | if evaluates to true, allows the invoice generation to exceed the account credit limit. default: 1 (true) |
address | N | array | address of invoicee (ie the address of customer custID) |
attr | N | array | extended attributes for the invoice |
dry_run | N | boolean | If specified and true, will not actually raise the invoice but will fully parse the arguments, and return the VAT calculation |
Within a parent account (identified by invoicerID) there may be several billing companies, eg one for ISP services, one for telecoms services, etc (see [billing_companies] element of login object on the invoicer account to see which companies exist, and see [custof] element of client login object to see which billing companies can raise invoices for this client).
You must supply this argument, or the invoicer_company argument. You cannot supply both.
When raising an invoice, you can define the expected payment type. This can effect certain automated processes such as a direct debit run, etc. Specify one of the following values:
If you don't supply the invoicee address, the default account address of the customer being invoice will be used.
This will be a key/value pair of attributes. In most cases you won't need these.
The attributes available for use may vary, depending on which other arguments are supplied. Contact us for a list of attributes and their use.
Perl example request:
POST https://live.apicontrol.co.uk/1/json
my $api = new CCclient($u, $p, $live); # this must be logging in to the parent account of the one being invoiced
my $items =
[
{
'price' =>'3.23',
'text' => 'Some bits',
},
{
'price'=>'9.95',
'domain'=>'mystuff.com',
'datefrom'=>'2009-01-01',
'dateto'=>'2009-12-31'
},
];
my %invargs =
(
'invoicerID' => $api->custID,
'custID' => 16526,
'invoicer_company' => 'skycom',
'ignore_credit_limit' => 1,
'items' => $items,
'address' =>
{
'contactname' => 'Mr Test',
'companyname' => 'Tinkly Ltd',
'addr1' => '81 Fothering Street',
'addr2' => 'Tinkleton',
'postcode' => 'N1 8QT',
'email'=>'mrtest@mailme.tickles.org',
},
);
my $res = $api->invoice_create(%invargs);XML example request:
POST https://live.apicontrol.co.uk/1/json
The response includes the following information:
Perl example response:
{
'success' => '1',
'vat' => '1.97',
'payment_due' => '2009-07-20',
'subtotal' => '13.18',
'total' => '15.15',
'errordiags' => '',
'textID' => '201046',
'invnum' => '127762',
'error' => undef,
'invoiceID' => '108239',
'errornum' => '',
'seq' => '34',
'oldbalancepence' => '-2006',
'results' => []
};XML example response: