Features
Pricing
Support
Accountants
MTD Software
Contact
More

API examples

PHP using SoapClient

Browse the repo on GitHub

Initialisation

<?php 
$clearbooksUrl 
'https://secure.clearbooks.co.uk/';
 
$client = new SoapClient($clearbooksUrl.'api/accounting/wsdl/');
 
$client->__setSoapHeaders(array(
    new 
SoapHeader($clearbooksUrl 'api/accounting/soap/',
        
'authenticate', array('apiKey' => 'yourApiKey')),
));

CreateEntity

<?php
require_once __DIR__ '/includes.php';

// create the entity
$entity = new \Clearbooks_Soap_1_0_Entity();
$entity->address1     '107 Hammersmith Road';
$entity->address2     'West Kensington';
$entity->building     'Master\'s House';
$entity->company_name 'Clear Books';
$entity->email        'support@clearbooks.co.uk';
$entity->postcode     'W14 0QH';
$entity->town         'London';
$entity->website      'http://www.clearbooks.co.uk';

// indicate that the entity is a supplier - an entity must be a customer, supplier or both
$entity->supplier     = new \Clearbooks_Soap_1_0_EntityExtra();

$entityId $client->createEntity$entity );
print_r$entityId );

/*
32
*/

View on GitHub

CreateInvoice

<?php
require_once __DIR__ '/includes.php';

// create the invoice
$invoice = new \Clearbooks_Soap_1_0_Invoice();
$invoice->creditTerms 30;
$invoice->dateCreated date'Y-m-d' );
$invoice->dateDue     date'Y-m-d'strtotime'+28 days' ) );
$invoice->description 'API Test Invoice';
$invoice->entityId    16;
$invoice->status      'approved';
$invoice->type        'sales';
// $invoice->multicurrency = 2; // Optionally create my invoice in Euros
// $invoice->fxrate = 2.00; // Optionally force the exchange rate for the invoice.

// add an item to the invoice
$item = new \Clearbooks_Soap_1_0_Item();
$item->description 'Line Item #1';
$item->quantity    1;
$item->type        1001001;
$item->unitPrice   number_format29.99 1.2);
$item->vatRate     '0.2';
$invoice->items[]  = $item;

$invoiceReturn $client->createInvoice$invoice );
print_r$invoiceReturn );

/*
Clearbooks_Soap_1_0_InvoiceReturn Object
(
    [due] => 29.99
    [invoice_id] => 211
    [invoice_prefix] => INV
    [invoice_number] => 201
)
*/

View on GitHub

CreatePayment

<?php
require_once __DIR__ '/includes.php';

$invoice = new \Clearbooks_Soap_1_0_PaymentInvoice();
$invoice->id 212;
$invoice->amount 15.5;
$allocatedToInvoices = [ $invoice ];


// create the payment
$payment = new \Clearbooks_Soap_1_0_Payment();
$payment->amount         29.99;
$payment->accountingDate date'Y-m-d' );
$payment->bankAccount    7502001;
$payment->description    'Invoice Payment';
$payment->entityId       22;
$payment->invoices       $allocatedToInvoices;
$payment->paymentMethod  1;
$payment->type           'sales';

$paymentReturn $client->createPayment$payment );
print_r$paymentReturn );

/*
Clearbooks_Soap_1_0_PaymentReturn Object
(
    [payment_id] => 618
)
*/

View on GitHub

CreatePaymentPayPal

<?php
require_once __DIR__ '/includes.php';

// the paypal bank account
$paypalBankAccount 7502004;

// the paypal entity id
$paypalEntityId 12;

// the amount received by paypal
$received 1150;

// the sales invoice id to apply the payment to
$salesInvoiceId 189;

// fetch the original invoice
$invoiceQuery = new \Clearbooks_Soap_1_0_InvoiceQuery();
$invoiceQuery->id[]   = $salesInvoiceId;
$invoiceQuery->ledger 'sales';
$invoiceQuery->status 'approved';
$invoices $client->listInvoices$invoiceQuery );
if ( !
$invoices ) {
    throw new \
Exception'Invoice not found' );
}
$invoice  $invoices[0];

// calculate the invoice total
$total 0;
array_walk$invoice->items, function( $item ) use ( &$total ) {
    
/** @var $item \Clearbooks_Soap_1_0_item */
   
$total += $item->unitPrice $item->vat;
} );

// the paypal fee is the amount received minus the invoice total (1150 - 1200 = -50)
$fee $received $total;

// create an invoice for the paypal fee
$invoice = new \Clearbooks_Soap_1_0_Invoice();
$invoice->creditTerms 0;
$invoice->dateCreated date'Y-m-d' );
$invoice->dateDue     date'Y-m-d' );
$invoice->description 'PayPal Fee';
$invoice->entityId    $paypalEntityId;
$invoice->status      'approved';
$invoice->type        'sales';

// add the fee item to the invoice (should be a negative amount)
$item = new \Clearbooks_Soap_1_0_Item();
$item->description 'PayPal Fee';
$item->quantity    1;
$item->type        6001002;
$item->unitPrice   number_format$fee 1.2);
$item->vatRate     '0.2';
$invoice->items[]  = $item;

// create the invoice in the api and retrieve the invoice id
$invoiceReturn $client->createInvoice$invoice );
$feeInvoiceId  $invoiceReturn->invoice_id;

// create the payment
$payment = new \Clearbooks_Soap_1_0_Payment();
$payment->amount         $received;
$payment->accountingDate date'Y-m-d' );
$payment->bankAccount    $paypalBankAccount;
$payment->description    'PayPal Payment';
$payment->entityId       $invoice->entityId;
$payment->invoices[]     = array( 'id' => $feeInvoiceId );
$payment->invoices[]     = array( 'id' => $salesInvoiceId );
$payment->paymentMethod  21;
$payment->type           'sales';

$paymentReturn $client->createPayment$payment );
print_r$paymentReturn );

/*
Clearbooks_Soap_1_0_PaymentReturn Object
(
    [payment_id] => 620
)
*/

View on GitHub

CreateProject

<?php
require_once __DIR__ '/includes.php';

// create the project
$project = new \Clearbooks_Soap_1_0_Project();
$project->description 'Costs related to Search Engine Optimization';
$project->projectName 'SEO';
$project->status      'open';

$projectReturn $client->createProject$project );
print_r$projectReturn );

/*
Clearbooks_Soap_1_0_ProjectReturn Object
(
    [project_id] => 6
)
*/

View on GitHub

EntityOutstandingBalance

<?php
require_once __DIR__ '/includes.php';
$entityOutstandingBalance $client->getEntityOutstandingBalance16'sales' );
print_r$entityOutstandingBalance );

/*
Clearbooks_Soap_1_0_EntityOutstandingBalance Object
(
    [outstanding] => 6578.67
    [overdue] => 6548.68
)
*/

View on GitHub

GetExchangeRate

<?php
require_once __DIR__ '/includes.php';

// construct the request
$request = new \Clearbooks_Soap_1_0_ExchangeRateRequest();
$request->baseCurrency   'GBP'// default
$request->targetCurrency 'USD';
$request->date           '2012-10-05';

$rate $client->getExchangeRate$request );
print_r$rate );

/*
1.6184948525068
*/

View on GitHub

ListAccountCodes

<?php
require_once __DIR__ '/includes.php';

// execute the command
$accountCodes $client->listAccountCodes();
print_r$accountCodes );

/*
Array
(
    [0] => Clearbooks_Soap_1_0_AccountCode Object
        (
            [id] => 1001001
            [account_name] => Revenue
            [group_name] => Revenue
            [default_vat_rate] =>
            [show_sales] => 1
            [show_purchases] =>
        )

...

)
*/

View on GitHub

ListBankAccounts

<?php
require_once __DIR__ '/includes.php';
$bankAccounts $client->listBankAccounts();
print_r$bankAccounts );

/*
Clearbooks_Soap_1_0_ListBankAccountsReturn Object
(
    [bankAccounts] => Array
        (
            [0] => Clearbooks_Soap_1_0_BankAccountListItem Object
                (
                    [account_type] => 0
                    [balance] => 38253.83
                    [bank_name] => HSBC
                    [currency] => 1
                    [gl_account_code] => 7502004
                    [id] => 2
                    [last_date] => 23 Jul 2010
                    [total_mc] =>
                )

            [1] => Clearbooks_Soap_1_0_BankAccountListItem Object
                (
                    [account_type] => 0
                    [balance] => 18768.89
                    [bank_name] => Barclays
                    [currency] => 1
                    [gl_account_code] => 7502001
                    [id] => 1
                    [last_date] => 24 Mar 2011
                    [total_mc] =>
                )

        )

    [total] => 57022.72
)
*/

View on GitHub

ListEntities

<?php
require_once __DIR__ '/includes.php';

// construct a query to filter returned invoices
$entityQuery = new \Clearbooks_Soap_1_0_EntityQuery();
$entityQuery->id[] = 8;
$entityQuery->type 'supplier';

// execute the command
$entities $client->listEntities$entityQuery );
print_r$entities );

/*
Array
(
    [0] => Clearbooks_Soap_1_0_Entity Object
        (
            [supplier] => Clearbooks_Soap_1_0_EntityExtra Object
                (
                    [default_account_code] => 0
                    [default_vat_rate] => 0.2
                    [default_credit_terms] => 0
                )

            [customer] => Clearbooks_Soap_1_0_EntityExtra Object
                (
                    [default_account_code] => 0
                    [default_vat_rate] => 0.00:Out
                    [default_credit_terms] => 30
                )

            [bankAccount] => Clearbooks_Soap_1_0_BankAccount Object
                (
                    [bankName] =>
                    [name] =>
                    [sortcode] =>
                    [accountNumber] =>
                )

            [id] => 8
            [company_name] => Fubra Limited
            [contact_name] =>
            [address1] => Church Hill
            [town] => Aldershot
            [county] => Hampshire
            [country] => GB
            [postcode] => GU12 4RQ
            [email] =>
            [phone1] =>
            [building] => Manor Coach House
            [address2] =>
            [phone2] =>
            [fax] =>
            [website] =>
            [date_modified] => 2010-09-16 16:34:42
            [external_id] => 0
            [vat_number] =>
            [company_number] =>
            [statement_url] => https://secure.clearbooks.co.uk/s/2:333e2ce22db288036ec67ca6056c5a7b
        )

)
*/

View on GitHub

ListInvoices

<?php
require_once __DIR__ '/includes.php';

// construct a query to filter returned invoices
$invoiceQuery = new \Clearbooks_Soap_1_0_InvoiceQuery();
$invoiceQuery->id[]   = 209;
$invoiceQuery->ledger 'sales';

// execute the command
$invoices $client->listInvoices$invoiceQuery );
print_r$invoices );

/*
Array
(
    [0] => Clearbooks_Soap_1_0_Invoice Object
        (
            [items] => Array
                (
                    [0] => Clearbooks_Soap_1_0_Item Object
                        (
                            [description] => Line Item #1
                            [unitPrice] => 24.99
                            [vat] => 5
                            [quantity] => 1
                            [type] => 1001001
                            [vatRate] => 0.2
                        )

                )

            [description] => API Test Invoice
            [entityId] => 16
            [invoice_id] => 209
            [invoice_prefix] => INV
            [invoiceNumber] => 204
            [reference] =>
            [dateCreated] => 2012-10-19 00:00:00
            [dateDue] => 2012-11-16 00:00:00
            [dateAccrual] => 2012-10-19 00:00:00
            [creditTerms] => 30
            [bankPaymentId] => 0
            [project] => 0
            [external_id] =>
            [status] => approved
            [statementPage] => https://secure.clearbooks.co.uk/accounting/sales/invoice_html/?source=statement&type=invoice&c=2&auth=-lHLOCMD8mOPS5qyEjiw2g
            [themeId] => 0
            [type] => S
            [vatTreatment] =>
            [multicurrency] => 0
            [gross] => 29.99
            [net] => 24.99
            [vat] => 5
            [paid] => 0
            [balance] => 29.99
            [foreignCurrencyBalance] => 0
        )

)
*/

View on GitHub

ListInvoicesAdvanced

<?php
require_once __DIR__ '/includes.php';

// construct a query to filter returned invoices
$invoiceQuery = new \Clearbooks_Soap_1_0_InvoiceQuery();
// find invoices that were created or had a payment applied within the last week
$invoiceQuery->modifiedSince date'Y-m-d'strtotime'-1 week' ) );
// look in the sales ledger
$invoiceQuery->ledger 'sales';
// exclude voided invoices
$invoiceQuery->status 'valid';

$invoices = array();

for ( 
$i 0true$i += 100 ) {
    
$invoiceQuery->offset $i;
    
// get the next batch of invoices
    
$batch $client->listInvoices$invoiceQuery );
    
// filter invoices by status
    
array_walk$batch, function( $invoice ) use ( &$invoices ) {
        
/** @var $invoice Clearbooks_Soap_1_0_Invoice */
        
$status $invoice->status;
        if ( 
$status == 'approved' && strtotime$invoice->dateDue ) <= mktime00) ) {
            
$status 'unpaid';
        }
        
$invoices[$status][] = $invoice;
    } );
    
// exit the loop if there are no more invoices to retrieve
    
if ( count$batch ) < 100 ) {
        break;
    }
}

// If you only wanted to retrieve paid invoices,
// $invoiceQuery->status = 'paid';

if ( isset( $invoices['paid'] ) ) {
    
array_walk$invoices['paid'], function( $invoice ) {
        
/** @var $invoice Clearbooks_Soap_1_0_Invoice */
        
$number = ( $invoice->invoice_prefix ?: 'INV' ) . str_pad$invoice->invoiceNumber6'0'STR_PAD_LEFT );
        
$gross number_format$invoice->gross);
        echo 
"Invoice {$number} has been paid £{$gross}\n";
    } );
}

/*
Invoice INV000196 has been paid £5,875.00
Invoice INV000197 has been paid £5,875.00
Invoice INV000198 has been paid £11,750.00
 */

if ( isset( $invoices['approved'] ) ) {
    
array_walk$invoices['approved'], function( $invoice ) {
        
/** @var $invoice Clearbooks_Soap_1_0_Invoice */
        
$number  = ( $invoice->invoice_prefix ?: 'INV' ) . str_pad$invoice->invoiceNumber6'0'STR_PAD_LEFT );
        
$balance number_format$invoice->balance);
        echo 
"Invoice {$number} has a balance of £{$balance}\n";
    } );
}

/*
Invoice INV000199 has a balance of £3,842.25
 */

if ( isset( $invoices['unpaid'] ) ) {
    
array_walk$invoices['unpaid'], function( $invoice ) {
        
/** @var $invoice Clearbooks_Soap_1_0_Invoice */
        
$number  = ( $invoice->invoice_prefix ?: 'INV' ) . str_pad$invoice->invoiceNumber6'0'STR_PAD_LEFT );
        
$balance number_format$invoice->balance);
        echo 
"Invoice {$number} has an outstanding balance of £{$balance}\n";
    } );
}

/*
Invoice INV000200 has an outstanding balance of £66.89
 */

View on GitHub

ListOutstandingBalances

<?php
require_once __DIR__ '/includes.php';
$outstandingBalances $client->listOutstandingBalances'sales' );
print_r$outstandingBalances );

/*
Array
(
    [0] => Clearbooks_Soap_1_0_ListOutstandingBalancesReturn Object
        (
            [entity] => 16
            [balance] => 6608.66
        )

    [1] => Clearbooks_Soap_1_0_ListOutstandingBalancesReturn Object
        (
            [entity] => 17
            [balance] => 3842.25
        )

    [2] => Clearbooks_Soap_1_0_ListOutstandingBalancesReturn Object
        (
            [entity] => 20
            [balance] => 2469.91
        )

    [3] => Clearbooks_Soap_1_0_ListOutstandingBalancesReturn Object
        (
            [entity] => 18
            [balance] => 1982.6
        )

    [4] => Clearbooks_Soap_1_0_ListOutstandingBalancesReturn Object
        (
            [entity] => 19
            [balance] => 1200
        )

    [5] => Clearbooks_Soap_1_0_ListOutstandingBalancesReturn Object
        (
            [entity] => 26
            [balance] => 360
        )

)
*/

View on GitHub

UpdateEntity

<?php

require_once __DIR__ '/includes.php';

$entity = new \Clearbooks_Soap_1_0_Entity();
$entity->company_name "ClearBooks Api Example";
$entity->supplier     = new \Clearbooks_Soap_1_0_EntityExtra();
$entityId $client->createEntity$entity );

$entityQuery = new \Clearbooks_Soap_1_0_EntityQuery();
$entityQuery->id = [ $entityId ];
list( 
$storedEntity ) = $client->listEntities$entityQuery  );

$storedEntity->town "London";
$storedEntity->bankAccount->bankName "Bank";
$storedEntity->bankAccount null);
$storedEntity->supplier null;
$client->updateEntity$storedEntity->id$storedEntity );

list( 
$updatedEntity ) = $client->listEntities$entityQuery );

View on GitHub

VoidInvoice

<?php
require_once __DIR__ '/includes.php';

$invoice = new \Clearbooks_Soap_1_0_Invoice();
$invoice->creditTerms 30;
$invoice->dateCreated date'Y-m-d' );
$invoice->dateDue     date'Y-m-d'strtotime'+28 days' ) );
$invoice->description 'API Test Invoice';
$invoice->entityId    33;
$invoice->status      'approved';
$invoice->type        'sales';
$invoice->vatTreatment "DSEU";

// add an item to the invoice
$item = new \Clearbooks_Soap_1_0_Item();
$item->description 'Line Item #1';
$item->quantity    3.5;
$item->type        1001001;
$item->unitPrice   number_format29.99 1.2);
$item->vatRate     '0.2';
$invoice->items[]  = $item;

$invoiceReturn $client->createInvoice$invoice );
print_r$invoiceReturn );

/*
 Clearbooks_Soap_1_0_InvoiceReturn Object
(
    [due] => 104.96
    [invoice_id] => 45
    [invoice_prefix] => INV
    [invoice_number] => 29
)
 */

$voidRequest = new Clearbooks_Soap_1_0_InvoiceRef();
$voidRequest->id $invoiceReturn->invoice_id;
$voidRequest->type 'sales';
$voidResult $client->voidInvoice$voidRequest );

print_r$voidResult );

/*
Clearbooks_Soap_1_0_ResponseStatus Object
(
    [success] => 1
    [msg] =>  Voiding this invoice was successful
)
 */

View on GitHub

VoidPayment

<?php
require_once __DIR__ '/includes.php';

// create the payment
$payment = new \Clearbooks_Soap_1_0_RemovePayment();
$payment->id 620;
$payment->type "sales";

$paymentReturn $client->voidPayment$payment );
print_r$paymentReturn );

/*
Clearbooks_Soap_1_0_ResponseStatus Object
(
    [success] => 1
    [msg] => Voiding this payment was successful
)
*/

View on GitHub

WriteOff

<?php
require_once __DIR__ '/includes.php';

// create the credit query
$creditQuery = new \Clearbooks_Soap_1_0_CreditQuery();
$creditQuery->accountCode 7501001;
$creditQuery->dateCreated date'Y-m-d' );
$creditQuery->description 'Invoice Write Off';
$creditQuery->id          213;
$creditQuery->ledger      'sales';

$creditResponseStatus $client->writeOff$creditQuery );
print_r$creditResponseStatus );

/*
Clearbooks_Soap_1_0_CreditResponseStatus Object
(
    [id] => 213
    [msg] => Credit applied against invoice
)
*/

View on GitHub

includes

<?php
spl_autoload_register
( function( $class ) {
    if ( 
strpos$class'Clearbooks_' ) !== ) {
        return 
false;
    }
    require_once 
__DIR__ '/../src/' str_replace'_''/'$class ) . '.php';
    return 
true;
} );
$client = new \Clearbooks_Soap_1_0'demo' );

View on GitHub