Log in
 

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>
ICB accreditation

Clear Books, accredited by The Institute of Certified Bookkeepers and registered with the Financial Conduct Authority (reg. no. 843585), delivers valued, comprehensive online accounting software for small businesses in the UK.