Invoices

Permissions

Permission to view, create, edit and delete invoice information is governed by the group a staff member is a part of.


cb_createInvoice

Create a new invoice and return the ID of the newly created invoice.

Request

string $auth_string Your authentication token returned from cb_setAuthCredentials()
int $client_id The client_id of the client the invoice is being created for
array $invoice_info An array of additional information to use when creating the invoice. The valid fields for this array are:
string client - Client name to appear on the invoice
string pobox - A purchase order to be assigned to the invoice
string address - Client address to appear on the invoice
string terms - Terms of the invoice
string notes - Additional notes
string date - The invoiced date for the invoice
string payment_due_date - Date the invoice is due
array $items An array of items to add to the invoice being created. The format of this array is:
int item_id - The ID of the item to add
string description - A description of the item
float cost - The cost of a single unit of this item
int quantity - The number of this item to be added
float price - The cost of the item mutplied by the quantity
int tax_item - The tax_id to attach to this item
float tax - The tax percentage. This value cannot exceed 1.
float tax_amount - The total amount of taxes to be added to this item
int $status optional; The default status of the invoice. The two valid values for this paramater are:
0: Draft, 1: Sent
If a status of 1 is set, an invoice email will be sent upon successful creation.
int $creator_id optional; The ID of the staff member who created the invoice. If left blank, the creator will be set as 'Clientbill'

Response

int invoice_id

cb_editInvoice

Edit an invoice using a given invoice_id.

Request

string $auth_string Your authentication token returned from cb_setAuthCredentials()
int $invoice_id The invoice_id of the invoice to be updated
int $client_id The client_id of the client the invoice is being created for
array $invoice_info An array of additional information to use when creating the invoice. The valid fields for this array are:
string client - Client name to appear on the invoice
string pobox - A purchase order to be assigned to the invoice
string address - Client address to appear on the invoice
string terms - Terms of the invoice
string notes - Additional notes
string date - The invoiced date for the invoice
string payment_due_date - Date the invoice is due
array $items An array of items to add to the invoice being created. The format of this array is:
int item_id - The ID of the item to add
string description - A description of the item
float cost - The cost of a single unit of this item
int quantity - The number of this item to be added
float price - The cost of the item mutplied by the quantity
int tax_item - The tax_id to attach to this item
float tax - The tax percentage. This value cannot exceed 1.
float tax_amount - The total amount of taxes to be added to this item
int $status optional; The default status of the invoice. The two valid values for this paramater are:
0: Draft, 1: Sent
If a status of 1 is set, an invoice email will be sent upon successful creation.

Response

boolean update_success

cb_deleteInvoice

Delete an invoice using the given invoice_id

Request

string $auth_string Your authentication token returned from cb_setAuthCredentials()
int $invoice_id The invoice_id of the invoice to be deleted

Response

No response is generated by this function call

cb_getInvoice

Retrieve information for a single invoice using a given invoice_id

Request

string $auth_string Your authentication token returned from cb_setAuthCredentials()
int $invoice_id The invoice_id of the invoice to retrieve

Response

Array
(
    [invoice_id] => 6
    [client_id] => 1
    [client] => John Doe
    [address] => 100 Doe Avenue Apartment #2
    [po] => 1001
    [status] => Draft
    [last_access] => 7/1/2008 12:00PM
    [invoice_date] => 6/28/2008 3:30PM
    [payment_due_date] => 7/14/2008 12:00AM
    [payment_remaining] => 86.40
    [subtotal] => 80.00
    [tax_total] => 6.40
    [total] => 86.40
    [special_terms] => terms
    [notes] => Additional invoice notes
    [creator_id] => 1
)

cb_getInvoices

Retrieve an array of all invoices ordered by a given column.

Request

string $auth_string Your authentication token returned from cb_setAuthCredentials()
int $sort_column optional; The column to sort invoices on. The valid columns that can be used in this function are those returned by the cb_getInvoice() function.

Response

Array
(
    [0] => Array
    (
        [invoice_id] => 6
        [client_id] => 1
        [client] => John Doe
        [address] => 100 Doe Avenue Apartment #2
        [po] => 1001
        [status] => Draft
        [last_access] => 7/1/2008 12:00PM
        [invoice_date] => 6/28/2008 3:30PM
        [payment_due_date] => 7/14/2008 12:00AM
        [payment_remaining] => 86.40
        [subtotal] => 80.00
        [tax_total] => 6.40
        [total] => 86.40
        [special_terms] => Invoice terms
        [notes] => Additional invoice notes
        [creator_id] => 1
    ),
    [1] => Array
    (
        [invoice_id] => 7
        [client_id] => 2
        [client] => Jane Doe
        [address] => 101 Doe Avenue Suite #4
        [po] => 1002
        [status] => Sent
        [last_access] => 6/29/2008 4:00PM
        [invoice_date] => 6/21/2008 1:00PM
        [payment_due_date] => 7/17/2008 12:00AM
        [payment_remaining] => 86.40
        [subtotal] => 10.00
        [tax_total] => 0.00
        [total] => 10.00
        [special_terms] => Invoice terms
        [notes] => Additional invoice notes
        [creator_id] => 5
    )
)

cb_getClientInvoices

Return an array of invoice IDs for a given client_id. If no invoices exist for the given client, a blank array will be returned.

Request

string $auth_string Your authentication token returned from cb_setAuthCredentials()
int $client_id The client_id of the account information to be updated

Response

Array(
      [0] => 13,
      [1] => 17,
      [2] => 26,
      [3] => 109,
)

cb_sendInvoice

Send out an invoice email from a given invoice_id.

Request

string $auth_string Your authentication token returned from cb_setAuthCredentials()
int $invoice_id The ID of the invoice to send

Response

boolean email_success

cb_exportInvoicesCSV

Returns invoices data for all invoices in a comma separated format. Entries in the returned string are separated by a newline character.

Request

string $auth_string Your authentication token returned from cb_setAuthCredentials()
int $detailed optional; Set what information is to be returned. By default all invoice data, including items, is returned. The valid options for this parameter are:
600 - Show all information, including items
601 - Show only basic information, items are not included
int $limit optional; Limit the number of results that are returned.
int $offset optional; By default Clientbill will start with invoice_id = 1. This paramater allows a different starting invoice_id to be used.

Response

Detailed results example:
6,1,John Doe,100 Doe Avenue Apartment #2,1001,Draft,7/1/2008 12:00PM,6/28/2008 3:30PM,80.00,6.40,86.40,7/14/2008 12:00AM,Invoice terms,1,Additional invoice notes,2   25,6,1,Item #1,10.00,7,70.00,1,0.08,5.60   26,6,2,Item #2,5.00,2,10.00,1,0.08,0.80

Basic results example:
7,1,Jane Doe,101 Doe Avenue Suite #4,1002,Draft,6/29/2008 4:00PM,6/21/2008 1:00PM,10.00,0.00,10.00,7/17/2008 12:00AM,Invoice terms,1,Additional invoice notes,0

cb_exportInvoicesXML

Returns invoices data for all invoices in XML format.

Request

string $auth_string Your authentication token returned from cb_setAuthCredentials()
int $detailed optional; Set what information is to be returned. By default all invoice data, including items, is returned. The valid options for this parameter are:
600 - Show all information, including items
601 - Show only basic information, items are not included
int $limit optional; Limit the number of results that are returned.
int $offset optional; By default Clientbill will start with invoice_id = 1. This paramater allows a different starting invoice_id to be used.

Response

<?xml version="1.0" standalone="yes"?>
<cbExportData>
   <invoice>
      <invoice_id>6</invoice_id>
      <client_id>1</client_id>
      <client>John Doe</client>
      <address>100 Doe Avenue Apartment #2</address>
      <po>1001</po>
      <status>Draft</status>
      <last_access>7/1/2008 12:00PM</last_access>
      <invoice_date>6/28/2008 3:30PM</invoice_date>
      <subtotal>80.00</subtotal>
      <tax_total>6.40</tax_total>
      <total>86.40</total>
      <payment_due_date>7/14/2008 12:00AM</payment_due_date>
      <payment_remainging>86.40</payment_remaining>
      <special_terms>Invoice terms</special_terms>
      <creator_id>1</creator_id>
      <notes>Additional invoice notes</notes>
      <items>
         <item>
            <invoice_item_id>25</invoice_item_id>
            <invoice_id>6</invoice_id>
            <item_id>1</item_id>
            <description_en>Item #1</description_en>
            <cost>10.00</cost>
            <quantity>7</quantity>
            <price>70.00</price>
            <tax_item>1</tax_item>
            <tax>0.08</tax>
            <tax_amount>5.60</tax_amount>
         </item>
         <item>
            <invoice_item_id>26</invoice_item_id>
            <invoice_id>6</invoice_id>
            <item_id>2</item_id>
            <description_en>Item #2</description_en>
            <cost>5.00</cost>
            <quantity>2</quantity>
            <price>10.00</price>
            <tax_item>1</tax_item>
            <tax>0.08</tax>
            <tax_amount>0.80</tax_amount>
         </item>
      </items>
   </invoice>
</cbExportData>