Soap API documentation

Method: createInvoice

Create a new invoice.

Please note, that auto-payment features will not work on invoices created through the API.

Vat treatment
Possible values for the vat treatment field:

The vat treatment of the invoice, default is 'UK'.
'OUT' – 'Out of Scope – Not on VAT Return'
'UK' – 'Goods or services (UK VAT)'
'GE' – 'Goods Exported' (sales only)
'GI' – 'Goods Imported' (purchases only)
'GIPVA' – 'Goods Imported – Postponed VAT Accounting' (purchases only)
'SE' – 'Services Exported' (sales only)
'SIRC' – 'Services Imported – Reverse Charge' (purchases only)
'GNIEU' – 'Goods to NI from EU Entity' (Northern Ireland businesses only)
'DSEU' – 'Digital Services to EU Entity' (sales only)
'GEU' – 'Goods to EU Entity (Pre-Brexit)'
'SEU' – 'Services to EU Entity (Pre-Brexit)'

Please note for backwards compatibility, the result vatTreatment field may have a prefix of "S" for sales and "P" for purchases.

Request

Field	Type	Description
invoice dateCreated	string	The tax point of the invoice	required
invoice dateDue	string	The date the invoice is due (YYYY-MM-DD). Use either this field or creditTerms	required
invoice dateAccrual	string	The invoice accrual date	optional
invoice creditTerms	string	The number of days after the tax point that the invoice is due	required
invoice description	string		optional
invoice entityId	string	The customer or supplier id	required
invoice reference	string	A reference string for the invoice	optional
invoice project	string	The id of the project to assign the invoice to	optional
invoice type	string	A string identifying the type of the invoice Value one of: purchases sales cn-sales cn-purchases	required
invoice bankPaymentId	integer	The bank account code	optional
Invoice vatTreatment	string	Vat treatment of the invoice.	optional
invoice multicurrency	integer	Specifies the currency of the invoice. A list of valid currency IDs can be found here by downloading this CSV. Defaults to the home currency of the company. The values on the invoice are always considered to be in the provided currency.	optional
invoice fxrate	float	The exchange rate between the home currency of the company and the currency of the invoice. If it's not specified, the exchange rate will be automatically determined based on up-to-date data for the date specified in dateCreated.	optional
invoice invoiceNumber	integer	The invoice number. Must be unique, if not specified the next number in the sequence will be automatically used.	optional
items	array	A list of item elements identifying the line items	required
item description	string		required
item unitPrice	string	The unit price of an item in pounds	required
item quantity	integer		required
item type	string	The account code identifying the revenue stream	required
item vat	string	The total amount of VAT in pounds. Use either this field or vatRate.	required
item vatRate	string	The percentage VAT as a decimal number. Use either this field or vat.	optional
item project	integer	Project id of the line item	optional

Response

Field	Type	Description
due	float	The total amount due in pounds	optional
invoice_id	integer	The internal id of the invoice	optional
invoice_prefix	string	The prefix of the invoice	optional
invoice_number	string	The number of the invoice	optional

Examples

Request

<Envelope xmlns="http://schemas.xmlsoap.org/soap/envelope/">
    <Header>
        <authenticate xmlns="https://secure.clearbooks.local/api/accounting/soap/">
            <apiKey>yourApiKey</apiKey>
        </authenticate>
    </Header>
    <Body>
        <createInvoice xmlns="https://secure.clearbooks.local/api/accounting/soap/">
            <invoice project="3" dateDue="2008-10-17" reference="abcd">
                <type>purchases</type>
                <entityId>20</entityId>
                <dateCreated>2008-09-17</dateCreated>
                <description>My invoice</description>
                <items>
                    <item quantity="2" vatRate="0.175" project="2">
                        <unitPrice>1.44</unitPrice>
                        <type>1001001</type>
                        <description>Entry ticket</description>
                    </item>
                </items>
            </invoice>
        </createInvoice>
    </Body>
</Envelope>

Response

<?xml version="1.0" encoding="UTF-8"?>
<SOAP-ENV:Envelope xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/" xmlns:ns1="https://secure.clearbooks.local/api/accounting/soap/">
    <SOAP-ENV:Body>
        <ns1:createInvoiceResponse>
            <return>
                <due>3.38</due>
                <invoice_id>30</invoice_id>
                <invoice_prefix>PUR</invoice_prefix>
                <invoice_number>20</invoice_number>
            </return>
        </ns1:createInvoiceResponse>
    </SOAP-ENV:Body>
</SOAP-ENV:Envelope>