Getting started
This section shows you how to install the Easysoft ODBC-Zoho Books Driver and configure the ODBC data source that stores the connection details for your Zoho Books organization. You’re then ready to work with Zoho Books data in your application.
Installing the Easysoft ODBC-Zoho Books Driver
Install the Easysoft ODBC-Zoho Books Driver on the computer where the application you want to connect to Zoho Books is running.
Installing on Windows
The Windows installation can be done by anyone with local administrator privileges.
-
Follow the onscreen instructions to progress through the installation wizard.
Updating files that are in use
To avoid rebooting your computer, the Easysoft ODBC-Zoho Books Driver installer prompts you when files that it needs to update are in use by another application or service. This frees the locked files and allows the installation to complete without a system restart. The installer uses the Restart Manager to locate the applications that are using files that need updating. These applications are displayed in the Files in Use dialog box. To avoid a system restart, choose Automatically close applications and attempt to restart them after setup is complete. The Easysoft ODBC-Zoho Books Driver installer then uses Restart Manager to try to stop and restart each application or service in the list. If possible, Restart Manager restores applications to the same state that they were in before it shut them down.
Licensing
By default, the installer starts the Easysoft License Manager, because you can’t use the Easysoft ODBC-Zoho Books Driver until you have a license. If you choose not to run Easysoft License Manager as part of the installation process, run License Manager from the Easysoft group in the Windows Start menu when you’re ready to license the Easysoft ODBC-Zoho Books Driver. These types of license are available:
-
A free time-limited trial license which gives you free and unrestricted use of the product for a limited period (usually 14 days).
-
A full license if you have purchased the product. On purchasing the product you are given an authorization code, which you use to obtain a license.
To license the Easysoft ODBC-Zoho Books Driver:
-
In License Manager, enter your contact details.
You must complete the Name, E-Mail Address, and Company fields.
The e-mail address must be the same as the one used to register at the Easysoft web site. Otherwise, you won’t be able to obtain a trial license.
-
Choose Request License.
You’re prompted to choose a license type.
-
Do one of the following:
-
For a trial license, choose Time Limited Trial, and then choose Next.
-Or- -
For a purchased license, choose Non-expiring License, and then choose Next.
-
-
Choose your product from the drop-down list when prompted, and then choose Next.
-
For a purchased license, enter your authorization code when prompted, and then choose Next.
-
Choose how to get your license when prompted.
-
Do one of the following:
-
Choose On-line Request if your machine is connected to the internet and can make outgoing connections to port 8884.
With this method, License Manager automatically requests and then applies your license.
-Or- -
Choose View Request. Then open a web browser and go to https://www.easysoft.com/support/licensing/trial_license.html or https://www.easysoft.com/support/licensing/full_license.html, as appropriate. In the web page, enter your machine number (labelled Number in the license request). For purchased licenses, you also need to enter your authorization code (labelled Ref in the license request).
We’ll automatically email your license to the email address you supplied in License Manager.
-Or- -
Choose Email Request to email your license request to our licensing team.
Once we’ve processed you request, we’ll email your license to the email address you supplied in License Manager.
-
-
Close the License Manager windows and then choose Finish.
If you chose either View Request or Email Request, apply your license by double-clicking the email attachment when you get the license email from us. Alternatively, start License Manager from the Easysoft folder in the Windows Start menu. Then choose Enter License and paste the license in the space provided.
Once you’ve licensed the Easysoft ODBC-Zoho Books Driver, the installation is complete.
Repairing the installation
The installer can repair a broken Easysoft ODBC-Zoho Books Driver installation. For example, you can use the installer to restore missing Easysoft ODBC-Zoho Books Driver files or registry keys. To do this:
-
In the Windows taskbar, enter
Add or remove programs
in the Windows search box. -
Select Easysoft ODBC-Zoho Books Driver in the list, and then choose Repair.
Uninstalling on Windows
This section explains how to remove the Easysoft ODBC-Zoho Books Driver from your system.
Removing Easysoft ODBC-Zoho Books Driver data sources
Easysoft ODBC-Zoho Books Driver data sources are not removed when you uninstall the Easysoft ODBC-Zoho Books Driver. You don’t therefore need to recreate your Easysoft ODBC-Zoho Books Driver data sources if you reinstall or upgrade. If you don’t want to keep your Easysoft ODBC-Zoho Books Driver data sources, use Microsoft ODBC Data Source Administrator to remove them, before uninstalling the Easysoft ODBC-Zoho Books Driver:
-
In the Windows taskbar, enter
Run
in the Windows search box. -
In the Windows Run dialog box, enter:
odbcad32.exe
-
Locate your data source in either the User or System tab.
-
Select the data source from the list, and then choose Remove.
If the Remove button isn’t available, close ODBC Data Source Administrator, and then, in the Windows Run dialog box, enter:
%windir%\syswow64\odbcad32.exe
Repeat the previous two steps.
Removing the Easysoft ODBC-Zoho Books Driver
-
In the Windows taskbar, enter
Add or remove programs
in the Windows search box. -
Select Easysoft ODBC-Zoho Books Driver in the list, and then choose Uninstall.
Easysoft product licenses are stored in the Windows registry. When you uninstall, your licenses are not removed, so you do not need to relicense the product if you reinstall or upgrade. |
Connecting to Zoho Books
Applications that support ODBC interface with an ODBC Driver Manager, which is included with the operating system, and also the Easysoft ODBC driver distribution on some platforms. One of the jobs that the ODBC Driver Manager does is to manage ODBC data sources. A data source specifies which ODBC driver to load, which data store to connect to, and how to connect to it.
Before setting up a data source, you must have successfully installed the Easysoft ODBC-Zoho Books Driver.
Connecting from Windows
Creating an ODBC data source
-
In the Windows taskbar search box, enter “Run”.
-
Do one of the following:
-
If your application is 64-bit, in the Run dialog box, enter:
odbcad32.exe
-Or-
-
If your application is 32-bit, in the Run dialog box, enter:
%windir%\syswow64\odbcad32.exe
If your not sure whether your application is 32-bit or 64-bit, start your application, then in Windows Task Manager check whether your application’s process name contains (32-bit)
. For example, the process name for the 32-bit version of Excel isMicrosoft Excel (32-bit)
; the process name for the 64-bit version of Excel isMicrosoft Excel
. On older versions of Windows, 32-bit applications contain*32
in the process name rather than(32-bit)
.
For applications such as Oracle or SQL Server that run as a service, check the *Background processes* list rather than the Apps list in Task Manager.
If you’re running a programming language from within a Windows command-line shell (for example, Command or PowerShell), in your shell, run the.exe
file for the programming language. For example, runperl
,php
,python
, ornode
. In Task Manager, expand the process list for Windows Command Processor or Windows PowerShell, as appropriate, and check whether the process for your programming language contains(32-bit)
.
-
-
Do one of the following:
-
To create a data source that only the user you’re currently logged in as can access, choose the User tab.
If your application is a Windows service (for example, SQL Server or Oracle) creating a user data source won’t work, unless the service is running as the same user you’re logged in as. -
To create a data source that all users on this computer can access, choose the System tab.
-
-
Choose Add.
-
In the list of ODBC drivers, select Easysoft ODBC-Zoho Books Driver, and then choose Finish.
-
Complete the Easysoft ODBC-Zoho Books Driver configuration dialog box.
To find out how to do this, refer to the Connection attributes section. -
To test the connection to Zoho Books, choose Test.
Note that this doesn’t test that the Easysoft ODBC-Zoho Books Driver is licensed. If you haven’t yet licensed the Easysoft ODBC-Zoho Books Driver, this ODBC data source won’t work with your application, even if the Test button succeeds.
Authentication
Zoho Books uses the OAuth security standard to authorise users.
To use the Easysoft ODBC-Zoho Books Driver, you need to obtain a refresh token, which enables the driver to get the access tokens it needs to make Zoho Books API requests.
By default, the Easysoft ODBC-Zoho Books Driver uses an app that we have registered with Zoho Books to supply an OAuth client ID and secret. If you want to use your own Zoho Books OAuth app, specify its client ID and secret in your Easysoft ODBC-Zoho Books Driver data source.
The reasons for using your own OAuth app are:
-
You want to create more than one Easysoft ODBC-Zoho Books Driver data source. For example, you need three data sources:
-
For the first data source, don’t specify a client ID or secret, the Easysoft ODBC-Zoho Books Driver will supply one.
-
Create an OAuth app. Specify this app’s client ID and secret in the second data source.
-
Create another OAuth app. Specify this app’s client ID and secret in the third data source.
-
-
You want to replace "Easysoft ODBC-Zoho Books Driver" with your own text in the web page that prompts users to grant access to their Zoho Books data. This page displays when users initially authenticate and obtain a Zoho Books refresh token. This is done as when configuring an Easysoft ODBC-Zoho Books Driver data source.
To create an OAuth app:
-
In the Zoho Books API console, choose Add Client.
-
In the Choose a Client Type list, choose Server-based Applications > Create Now.
-
In the Client Name box, enter a name.
This name is displayed to users in the web page that prompts them to allow access to their Zoho Books data.
-
Enter a home page URL.
-
In the Authorized Redirect URIs box, enter
http://localhost:port
. For example,http://localhost:8096
. -
Choose Create.
The Client Secret tab contains the values you supply in the Easysoft ODBC-Zoho Books Driver DSN configuration dialog box.
To obtain a refresh token on Windows, choose the Authenticate and obtain token button in the configuration dialog box when setting up your data source. This launches your default browser. Sign into your Zoho Books account and grant the permissions the Easysoft ODBC-Zoho Books Driver needs when prompted. Close the web browser window or tab when prompted.
You now have a refresh token. The Easysoft ODBC-Zoho Books Driver uses this to request the access tokens it needs to access your Zoho Books data.
Connection attributes
Name | Value |
---|---|
DSN |
The name of the data source. You’ll need to specify this in your application. For example, your application may prompt you to choose this from a list of DSNs. |
Description |
Some applications display this to help users identify a particular data source. |
Acc Server |
The URI of your Zoho Books server. For example, If you leave this field blank, the Easysoft ODBC-Zoho Books Driver attempts to discover this value when you authenticate and obtain a refresh token. |
Location |
The location of your Zoho Books server. For example, If you leave this field blank, the Easysoft ODBC-Zoho Books Driver attempts to discover this value when you authenticate and obtain a refresh token. |
Refresh Token |
The Zoho Books refresh token that enables the Easysoft ODBC-Zoho Books Driver to work with your Zoho Books data. |
Local Filtering |
When turned on, the Easysoft ODBC-Zoho Books Driver increases its preferred batch size for queries, which alters the number of Zoho Books API calls it makes. Zoho Books may create batches that are larger or smaller than the requested size to maximise performance. There is no one correct setting for Local Filtering, it depends on how your application executes its queries. You may find that this attribute increases query performance for one application and decreases performance for another. By default, Local Filtering is turned off. |
Proxy |
If you use a proxy server connect to Zoho Books, use this attribute to specify this server’s details. Use this format: where address is the host name or IP address of the proxy server and port is the proxy server port. For example: |
Proxy User |
If your proxy server has authentication turned on, use this attribute to supply a user name that can connect to the proxy server. The Easysoft ODBC-Zoho Books Driver supports the Basic and Digest proxy authentication schemes. |
Proxy Password |
The password for the proxy user. |
Driver Logging |
Whether to turn on Easysoft ODBC-Zoho Books Driver logging. Normally, you’ll only do this if so directed by the Easysoft support team. |
Log File |
The file name and path of the file you want the driver to write log information to. For example: If the file doesn’t exist, the Easysoft ODBC-Zoho Books Driver creates it. |
Flush On Update |
Whether the Easysoft ODBC-Zoho Books Driver flushes its cache when it is used to update or delete Zoho Books data. When this setting is turned on, the effect of your changes will apply in your current session. For example, you turn on this setting and delete a record. If you then do a select in the same session, the record will no longer be present in the result set, If you do the same with Flush On Update turned off, the result set contains the deleted record until the Easysoft ODBC-Zoho Books Driver cache expires or you reconnect your application (for example, you restart your SQL Server instance). |
Cache Timeout |
The time in seconds that Easysoft ODBC-Zoho Books Driver stores records in its cache. If you set the timeout to 0, the Easysoft ODBC-Zoho Books Driver always caches records. The default value for Cache Timeout is 0. The Easysoft ODBC-Zoho Books Driver flushes the cache when you close the connection to Zoho Books. (For example, you quit your application or restart your application’s service.) To reduce Zoho Books API usage and reduce the amount of data retrieved over the network, the Easysoft ODBC-Zoho Books Driver caches Zoho Books records. By default, a record remains in the cache until the timeout elapses. Note that any changes to the record that happen at the Zoho Books end aren’t reflected in the cached copy until the cache is refreshed (that is, the timeout expires and the record is fetched again.) If a cached record is changed by the Easysoft ODBC-Zoho Books Driver, the cache is refreshed to reflect this change. |
Max Num |
The maximum number of records to return for each Rest API request the Easysoft ODBC-Zoho Books Driver makes. |
Organization Id |
The ID of your Zoho Books organization. If you leave this field blank, the Easysoft ODBC-Zoho Books Driver attempts to discover your organization ID. If you have multiple organizations and leave this field blank, the Easysoft ODBC-Zoho Books Driver gets all the available organizations, and uses the first one in the list.
To find out your organization ID, in the Zoho Books web interface, choose the down arrow that’s next to your organization’s name in the top right corner. |
Client Id |
If you have created your own Zoho Books OAuth client app, enter the app’s client id here. Otherwise, leave this field blank. |
Client Secret |
The client secret for your Zoho Books OAuth client app. |
DSN-less connections
Some applications allow you to make an ODBC connection without configuring a data source. To do this, you supply a connection string that contains the ODBC driver name and other driver-specific attribute-value pairs.
Here’s an example connection string for the Windows version of the Easysoft ODBC-Zoho Books Driver:
Driver={Easysoft Zoho Books ODBC Driver};Refresh_Token=2000.d2927da21cff612e6818f832a47c256e.379428ee4a4abc3040799dff191f8620;Location=eu;AccServer=https://accounts.zoho.eu;Logging=Yes;LogFile=C:\\Temp\\ZB2.log;
Connection string attributes have different names to the ones shown in the Easysoft ODBC-Zoho Books Driver data source configuration dialog box. Use these attribute names in a connection string:
-
Description
-
AccServer
-
Location
-
Refresh_Token
-
Organization
-
Proxy
-
Proxy_User
-
Proxy_Pass
-
Query_Timeout
-
Max_Num
-
Logging
-
Logfile
-
Filter_Local
-
Flush_On_Update
Logging
If you report an issue to us, we may ask you to turn on ODBC Driver Manager or Easysoft ODBC-Zoho Books Driver logging, to help us diagnose the cause of the issue.
To turn on logging, refer to the following sections.
If your application is a service (for example, Oracle or SQL Server), you may need to restart the service before enabling logging takes effect. To do this on Windows, use the Windows Services app. |
ODBC Driver Manager logging on Windows
-
In the Windows taskbar search box, enter “Run”.
-
Do one of the following:
-
If your application is 64-bit, in the Run dialog box, enter:
odbcad32.exe
-Or-
-
If your application is 32-bit, in the Run dialog box, enter:
%windir%\syswow64\odbcad32.exe
If your not sure whether your application is 32-bit or 64-bit, start your application, then in Windows Task Manager check whether your application’s process name contains (32-bit)
. For example, the process name for the 32-bit version of Excel isMicrosoft Excel (32-bit)
; the process name for the 64-bit version of Excel isMicrosoft Excel
. On older versions of Windows, 32-bit applications contain*32
in the process name rather than(32-bit)
.
For applications such as Oracle or SQL Server that run as a service, check the *Background processes* list rather than the Apps list in Task Manager.
If you’re running a programming language from within a Windows command-line shell (for example, Command or PowerShell), in your shell, run the.exe
file for the programming language. For example, runperl
,php
,python
, ornode
. In Task Manager, expand the process list for Windows Command Processor or Windows PowerShell, as appropriate, and check whether the process for your programming language contains(32-bit)
.
-
-
Choose the Tracing tab.
-
Select Machine-Wide tracing for all identities.
-
Enter a log file name and path in the space provided. For example:
C:\Windows\Temp\SQL.log
-
Choose Start Tracing Now.
With SQL Server, you may get two Driver Manager log files, we need both. The first log file is in the folder that you specify in ODBC Data Source Administrator. The second file’s location is defined by SQL Server. Two possible locations are the top-level folder (for example, C:\SQL.log ) or the SQL Server temporary folder (for example, C:\Users\MSSQL$SQLEXPRESS\AppData\Local\Temp\SQL.log ). If the Driver Manager log file isn’t in these folders, search for it on the drive where SQL Server is installed.
|
Easysoft ODBC-Zoho Books Driver logging on Windows
-
In the Windows taskbar search box, enter “Run”.
-
Do one of the following:
-
If your application is 64-bit, in the Run dialog box, enter:
odbcad32.exe
-Or-
-
If your application is 32-bit, in the Run dialog box, enter:
%windir%\syswow64\odbcad32.exe
If your not sure whether your application is 32-bit or 64-bit, start your application, then in Windows Task Manager check whether your application’s process name contains (32-bit)
. For example, the process name for the 32-bit version of Excel isMicrosoft Excel (32-bit)
; the process name for the 64-bit version of Excel isMicrosoft Excel
. On older versions of Windows, 32-bit applications contain*32
in the process name rather than(32-bit)
.
For applications such as Oracle or SQL Server that run as a service, check the *Background processes* list rather than the Apps list in Task Manager.
If you’re running a programming language from within a Windows command-line shell (for example, Command or PowerShell), in your shell, run the.exe
file for the programming language. For example, runperl
,php
,python
, ornode
. In Task Manager, expand the process list for Windows Command Processor or Windows PowerShell, as appropriate, and check whether the process for your programming language contains(32-bit)
.
-
-
Do one of the following:
-
If you configured a system data source, choose the System DSN tab.
-Or- -
If you configured a system data source, choose the System DSN tab.
-
-
Choose your Easysoft ODBC-Zoho Books Driver data source from the list, and then choose Configure.
-
In the Easysoft ODBC-Zoho Books Driver data source configuration dialog box, turn on Driver Logging.
-
Enter a log file name and path in the space provided. For example:
C:\Windows\Temp\Easysoft.log
Finding out what product version you have on Windows
If you have an issue with the Easysoft ODBC-Zoho Books Driver, we may ask you to tell us what your product version is. To find this out:
-
In the Windows taskbar, enter “Add or remove programs” in the Windows search box.
-
Select Easysoft ODBC-Zoho Books Driver in the list.
The product version displays below.
Working with Zoho Books data
The Easysoft ODBC-Zoho Books Driver lets you use SQL to work with Zoho Books data. Your application might build the SQL for you or you might have to specify the SQL statements yourself.
SELECT
statements
Use either a Zoho Books table or the API view in your queries. For example, both these statements fetch the comments for a particular bill:
SELECT
*
FROM
Bill_Comment
WHERE
Bill_Id = '579676000000081095'
=Or-
SELECT
*
FROM
API
WHERE
URL = 'books/v3/bills/579676000000081095/comments'
AND Method = 'GET'
INSERT
statements
When inserting a record that has one or more line items, specify the line items with a JSON array. For example, this line item is for a recurring expense
[
{
"description": "Cloud Storage Monthly",
"rate": 9.99,
"quantity": 3,
"tax_id": "579676000000050178"
}
]
In the INSERT
statement, specify the JSON as a single line. For example:
INSERT INTO
Recurring_Invoice (
Customer_Id,
Line_Items,
Recurrence_Name,
Recurrence_Frequency,
Repeat_Every,
Start_Date,
End_Date
)
VALUES
(
'579676000000050204',
'[{"description":"Cloud Storage Monthly","rate":9.99,"quantity":3,"tax_id":"579676000000050178"}]',
'Monthly Cloud Charge',
'weeks',
'1',
'2024-07-29',
'2024-12-30'
)
Example inserts
Bill
Create a new bill:
INSERT INTO
Bill (
Bill_Number,
Vendor_Id,
[Date],
Due_Date,
Currency_Code,
Line_Items
)
VALUES
(
'BILL-002',
'576438000000118013',
'2024-06-25',
'2024-07-25',
'USD',
'[
{
"item_order": 1,
"account_name": "IT and Internet Expenses",
"account_id": "576438000000000415",
"description": "Dell Laser Paper",
"rate": 3.5,
"quantity": 16,
"item_total": 56
}
]'
)
Use the yyyy-mm-dd
format for Date
and Due_Date
. Vendor_Id
is a Contact_Id
from the Contact
table where the Contact_Type
is 'vendor'. The JSON for the line items is:
[
{
"item_order": 1,
"account_name": "IT and Internet Expenses",
"account_id": "576438000000000415",
"description": "Dell Laser Paper",
"rate": 3.5,
"quantity": 16,
"item_total": 56
}
]
Invoice comment
Insert an invoice comment:
INSERT INTO
Invoice_Comment (
Invoice_Id,
Description,
Show_Comment_To_Clients,
Payment_Expected_Date
)
VALUES
(
'579676000000050234',
'Customer comment.',
1,
'2024-08-29'
)
Credit note
Create a new credit note:
INSERT INTO
Credit_Note (Customer_Id, Currency_Id, [Date], Line_Items)
values
(
'576438000000066678',
'576438000000000059',
'2021-06-14',
'[
{
"account_id": "576438000000000376",
"tax_type": "tax",
"item_id": "576438000000080083",
"name": "1000-99-9999-99-99-99-07",
"tax_id": "576438000000056007",
"item_order": 1,
"description": "Easysoft Contract - Renewal",
"quantity": 1,
"unit": "pcs",
"item_total": 404.73,
"sales_rate": 1,
"rate": 404.73,
"tax_percentage": 10,
"account_name": "Sales",
"tax_name": "10% Tax",
"pricing_scheme": "unit",
"item_type": "sales"
}
]'
)
As a minimum, you need to include Customer_Id
, Currency_Id
, Date
, and Line_Items
. If you don’t have auto numbering turned on in Zoho Books, include Creditnote_Number
.
The JSON for the line items is:
[
{
"account_id": "576438000000000376",
"tax_type": "tax",
"item_id": "576438000000080083",
"name": "1000-99-9999-99-99-99-07",
"tax_id": "576438000000056007",
"item_order": 1,
"description": "Easysoft Contract - Renewal",
"quantity": 1,
"unit": "pcs",
"item_total": 404.73,
"sales_rate": 1,
"rate": 404.73,
"tax_percentage": 10,
"account_name": "Sales",
"tax_name": "10% Tax",
"pricing_scheme": "unit",
"item_type": "sales"
}
]
Payment
Create a new payment:
INSERT INTO
Customer_Payment (Customer_Id, Payment_Mode, Amount, Invoices)
VALUES
(
'576438000000072770',
'cash',
373.76,
'[
{
"Invoice_Id": "576438000000104809",
"invoice_number": "39440",
"date": "2024-07-03",
"invoice_amount": "373.76",
"amount_applied": "373.76",
"balance_amount": "0"
}
]'
)
The JSON for Invoices
is:
[
{
"Invoice_Id": "576438000000104809",
"invoice_number": "39440",
"date": "2024-07-03",
"invoice_amount": "373.76",
"amount_applied": "373.76",
"balance_amount": "0"
}
]
You can pay several invoices at once by adding a new block to the array: [{Inv 1},{Inv 2],{Inv n}]
.
Delivery challan
Create a new delivery challan:
INSERT INTO
Delivery_Challan (
[Date],
Challan_Type,
Reference_Number,
Currency_Code,
Customer_Id,
Tax_Treatment,
Place_Of_Supply,
Line_Items
)
VALUES
(
'2024-09-01',
'job work',
'DelChallan2',
'BHD',
'633066000000053001',
'vat_registered',
'BH',
'{"description":"A5 Notepad","rate":9.99,"quantity":3}'
)
Estimate
Create a new estimate:
INSERT INTO
Estimate ([Date], Customer_Id, Line_Items)
VALUES
(
'2024-07-08',
'576438000000059096',
'[
{
"header_name": "Leads",
"description": "USB-C",
"rate": 2.75,
"quantity": 33,
"discount": "5.00%",
"tax_id": "576438000000056007"
},
{
"header_name": "Leads",
"description": "USB-B",
"rate": 0.68,
"quantity": 127,
"discount": "11.5%",
"tax_id": "576438000000056007"
},
{
"header_name": "Paper",
"description": "A4 (5 x per box)",
"rate": 9.99,
"quantity": 5,
"tax_id": "576438000000056007"
},
{
"header_name": "Paper",
"description": "A5 (10 x per box)",
"rate": 6.87,
"quantity": 12,
"tax_id": "576438000000056007"
}
]'
)
The JSON for the line items is:
[
{
"header_name": "Leads",
"description": "USB-C",
"rate": 2.75,
"quantity": 33,
"discount": "5.00%",
"tax_id": "576438000000056007"
},
{
"header_name": "Leads",
"description": "USB-B",
"rate": 0.68,
"quantity": 127,
"discount": "11.5%",
"tax_id": "576438000000056007"
},
{
"header_name": "Paper",
"description": "A4 (5 x per box)",
"rate": 9.99,
"quantity": 5,
"tax_id": "576438000000056007"
},
{
"header_name": "Paper",
"description": "A5 (10 x per box)",
"rate": 6.87,
"quantity": 12,
"tax_id": "576438000000056007"
}
]
There are two groups here: Leads
and Paper
. header_name
defines a group and the items that belong to each group. The items in the Leads
group have a discount applied to them. No total values are supplied, rate
, quantity
, and tax_id
are all that’s required.
Expense
Submit a new expense:
INSERT INTO
Expense (
Transaction_Type,
Account_Id,
Account_Name,
Vendor_Id,
Vendor_Name,
Currency_Code,
Line_Items
)
VALUES
(
'expense',
'576438000000000406',
'Air Travel Expense',
'576438000000166003',
'Air Travel USA',
'USD',
'[
{
"account_id": "576438000000000406",
"account_name": "Air Travel Expense",
"description": "New York to LA",
"tax_amount": 10,
"tax_type": "tax",
"tax_percentage": 10,
"item_total": 100,
"amount": 110,
"item_order": 1
},
{
"account_id": "576438000000000406",
"account_name": "Air Travel Expense",
"description": "LA to Miami",
"tax_amount": 30,
"tax_type": "tax",
"tax_percentage": 10,
"item_total": 300,
"amount": 330,
"item_order": 2
}
]'
)
The JSON for the line items is:
[
{
"account_id": "576438000000000406",
"account_name": "Air Travel Expense",
"description": "New York to LA",
"tax_amount": 10,
"tax_type": "tax",
"tax_percentage": 10,
"item_total": 100,
"amount": 110,
"item_order": 1
},
{
"account_id": "576438000000000406",
"account_name": "Air Travel Expense",
"description": "LA to Miami",
"tax_amount": 30,
"tax_type": "tax",
"tax_percentage": 10,
"item_total": 300,
"amount": 330,
"item_order": 2
}
]
Item
Insert an item that’s purchased and sold as goods:
INSERT INTO
Item (
[Name],
Description,
Tax_Id,
Item_Type,
Product_Type,
Unit_Id,
Rate,
Account_Id,
Purchase_Rate,
Purchase_Description,
Purchase_Account_Id,
Vendor_Id
)
VALUES
(
'1TB Hard Disk',
'WD 1TB HDD 3.5"',
'579676000000050178',
'sales_and_purchases',
'goods',
'579676000000050038',
'299',
'579676000000000376',
'249',
'1 x WD 1TB HDD 3.5"',
'579676000000000509',
'579676000000081069'
)
Journal
Create a new journal:
INSERT INTO
Journal (
Reference_Number,
Journal_Date,
Journal_Type,
Currency_Id,
Notes,
Vat_Treatment,
Tax_Treatment,
Product_Type,
Line_Items
)
VALUES
(
'Bank charge 2',
'2024-08-06',
'both',
'579676000000000065',
'Standard cheque processing charge.',
'non_eu',
'non_eu',
'service',
'[
{
"account_id": 579676000000000400,
"customer_id": 579676000000050200,
"description": "Standard cheque charge",
"tax_id": 579676000000050200,
"debit_or_credit": "debit",
"amount": 4.99
},
{
"account_id": 579676000000000500,
"customer_id": 579676000000050200,
"description": "Bank charge",
"debit_or_credit": "credit",
"amount": 4.99
}
]'
)
The JSON data for the line items is:
[
{
"account_id": 579676000000000400,
"customer_id": 579676000000050200,
"description": "Standard cheque charge",
"tax_id": 579676000000050200,
"debit_or_credit": "debit",
"amount": 4.99
},
{
"account_id": 579676000000000500,
"customer_id": 579676000000050200,
"description": "Bank charge",
"debit_or_credit": "credit",
"amount": 4.99
}
]
There needs to be at least one debit and one credit line.
Purchase order
Create a new purchase order:
INSERT INTO
Purchase_Order (Vendor_Id, [Date], Line_Items)
VALUES
(
'579676000000081069',
'2024-07-30',
'[
{
"description": "2TB Hard Disk",
"rate": 99,
"quantity": 3,
"account_id": "579676000000000415",
"tax_id": "579676000000050178"
}
]'
)
The JSON data for the line items is:
[
{
"description": "2TB Hard Disk",
"rate": 99,
"quantity": 3,
"account_id": "579676000000000415",
"tax_id": "579676000000050178"
}
]
Recurring bill
Create a new recurring bill:
INSERT INTO
Recurring_Bill (
Recurrence_Name,
Start_Date,
End_Date,
Recurrence_Frequency,
Repeat_Every,
Vendor_Id,
Line_Items
)
VALUES
(
'A5 notepads',
'2024-07-08',
'2026-12-12',
'months',
'1',
'548752000000052031',
'[
{
"account_id": "548752000000000430",
"description": "A5 Notepad",
"rate": 9.99,
"quantity": 3
}
]'
)
The JSON data for the line items is:
[
{
"account_id": "548752000000000430",
"description": "A5 Notepad",
"rate": 9.99,
"quantity": 3
}
]
Recurring expense
Create a new recurring expense:
INSERT INTO
Recurring_Expense (
Recurrence_Name,
Start_Date,
End_Date,
Recurrence_Frequency,
Repeat_Every,
Vendor_Id,
Paid_Through_Account_Id,
Line_Item
)
VALUES
(
'Window Clean',
'2024-07-08',
'2024-12-12',
'weeks',
'1',
'576438000000173100',
'576438000000118006',
'[
{
"account_id": "576438000000173094",
"account_name": "Cleaning",
"description": "Weekly Outside Window Clean",
"amount": 100
}
]'
)
The Recurrence_Name
value must be unique.
The JSON data for the line items is:
[
{
"account_id": "576438000000173094",
"account_name": "Cleaning",
"description": "Weekly Outside Window Clean",
"amount": 100
}
]
UPDATE
statements
To update records with JSON columns (for example, Line_Items
columns), you first need to retrieve the existing JSON. Then change the existing values, or add new JSON to the existing JSON. For example:
SELECT Line_Items FROM Journal WHERE Journal_Id = '579676000000130007'
returns the following (formatted for readability):
{
"account_id": 579676000000000400,
"customer_id": 579676000000050200,
"description": "Standard cheque charge",
"tax_id": 579676000000050200,
"debit_or_credit": "debit",
"amount": 4.99
},
{
"account_id": 579676000000000500,
"customer_id": 579676000000050200,
"description": "Bank charge",
"debit_or_credit": "credit",
"amount": 4.99
}
To change, say, the journal amounts, edit these parts of the JSON:
{
"account_id": 579676000000000400,
"customer_id": 579676000000050200,
"description": "Standard cheque charge",
"tax_id": 579676000000050200,
"debit_or_credit": "debit",
"amount": 5.99
},
{
"account_id": 579676000000000500,
"customer_id": 579676000000050200,
"description": "Bank charge",
"debit_or_credit": "credit",
"amount": 5.99
}
and include the revised JSON in an UPDATE
statement. Enclose the JSON in square brackets. For example:
UPDATE Journal
SET
Line_Items = '[
{
"account_id": 579676000000000400,
"customer_id": 579676000000050200,
"description": "Standard cheque charge",
"tax_id": 579676000000050200,
"debit_or_credit": "debit",
"amount": 5.99
},
{
"account_id": 579676000000000500,
"customer_id": 579676000000050200,
"description": "Bank charge",
"debit_or_credit": "credit",
"amount": 5.99
}
]'
WHERE
Journal_id = '579676000000130007'
In the next example, an additional line item is added to a delivery challan:
[
{
"description": "A5 Notepad",
"rate": 9.99,
"quantity": 3
}
]
becomes:
[
{
"account_id": "548752000000000430",
"description": "A5 Notepad",
"rate": 9.99,
"quantity": 3
},
{
"account_id": "548752000000000430",
"description": "A3 Paper box 100",
"rate": 9.99,
"quantity": 1
}
]
and is submitted by using:
UPDATE Delivery_Challan
SET
Line_Item = '[
{
"account_id": "548752000000000430",
"description": "A5 Notepad",
"rate": 9.99,
"quantity": 3
},
{
"account_id": "548752000000000430",
"description": "A3 Paper box 100",
"rate": 9.99,
"quantity": 1
}
]'
WHERE
deliverychallan_id = '576438000000176002'
If you need to clear the contents of a JSON column, set the value to []
.
UPDATE Invoice SET Contact_Persons = '[]' WHERE Invoice_Id = '579676000000050260'
Setting the value to an empty string (''
) or NULL
won’t work as the Zoho Books API does not support this.
You can also us the API
view to make updates to your Zoho Books data. Use PUT
as the method in your SELECT
statement. For example:
SELECT
*
FROM
API
WHERE
URL = 'books/v3/customerpayments/576438000000172004/refunds'
AND Method = 'PUT'
AND RequestBody = '{
"date": "2024-07-03",
"refund_mode": "cash",
"amount": 1010,
"from_account_id": "576438000000000346"
}'
Example updates
Bank account
Change the name of a bank account:
UPDATE Bank_Account
SET
Account_Name = 'COOP Account'
WHERE
Account_Id = '576438000000114002'
Chart of account
Update a chart of account’s description:
UPDATE Chart_Of_Account
SET
Description = 'Testing the COA'
WHERE
Account_Id = '579676000000106021'
Contact
Update a contact’s company name:
UPDATE Contact
SET
Company_Name = 'J. Jones Lumber'
WHERE
Contact_Id = '576438000000152001'
Credit note
Change the date of a credit note:
UPDATE Credit_Note
SET
[Date] = '2024-01-01'
WHERE
Creditnote_Id = '576438000000159004'
Customer payment
Change the description for a customer payment:
UPDATE Customer_Payment
SET
Description = 'Customer paid at till'
WHERE
Payment_Id = '576438000000168003'
Expense
Change the date of an expense:
UPDATE Expense
SET
[Date] = '2024-07-01'
WHERE
Expense_Id = '576438000000170042'
Invoice comment
Update an invoice comment:
UPDATE Invoice_Comment
SET
Description = 'Invoice updated.'
WHERE
Invoice_Id = '579676000000050234'
AND Comment_Id = '579676000000061089'
Item
Add 10% onto the sales price for all goods:
UPDATE Item SET Rate=Rate*1.1 WHERE product_type = 'goods'
Organization
Change the address of an organization:
UPDATE Organization
SET
Address_Street_Address1 = 'Building 1'
WHERE
organization_id = '20100387237'
Purchase order
Change the purchase order quantity from 3 to 4:
UPDATE Purchase_Order
SET
Line_Items = REPLACE (Line_Items, '{"quantity": 3', '{"quantity": 4')
WHERE
purchaseorder_id = '579676000000092047'
DELETE
statements
The Easysoft ODBC-Zoho Books Driver provides two ways to delete records. Either specify a table in your DELETE
statement:
DELETE FROM Bank_Account
WHERE
Account_Id = '579676000000088102'
or use the API
view instead:
SELECT
*
FROM
API
WHERE
URL = 'books/v3/bankaccounts/579676000000109001'
AND Method = 'DELETE'
If you’re only deleting a single record and have the ID of this record, using the API
view is faster and uses fewer Zoho Books API calls than using a DELETE
statement.
When you run a DELETE statement or use API Method='DELETE' , any rows that match your criteria are deleted. There’s no undo option and no way of getting the rows back.
|
Example deletes
Invoice comment
Delete a comment from an invoice:
DELETE FROM Invoice_Comment
WHERE
Invoice_Id = '579676000000050234'
AND Comment_Id = '579676000000165022'
You need to specify both the Invoice_Id
and Comment_Id
columns.
If you attempt to delete a system generated comment, history record, or customer comment you’ll get this error:
[{PRODUCT}]Error <4073: You cannot delete system generated or customer comments.>
Bill
Delete a single bill:
DELETE FROM Bill WHERE Bill_Id='579676000000088074'
-Or-
SELECT
*
FROM
API
WHERE
URL = 'books/v3/bills/579676000000089067'
AND Method = 'DELETE'
Customer payment
Delete a customer payment:
DELETE FROM Customer_Payment
WHERE
Payment_Id = '576438000000168003'
-Or-
SELECT
*
FROM
API
WHERE
URL = 'books/v3/customerpayments/579676000000107086'
AND Method = 'DELETE'
Journal
Delete a journal:
DELETE FROM Journal
WHERE
Journal_Id = '579676000000130007'
-Or-
SELECT
*
FROM
API
WHERE
URL = 'books/v3/journals/579676000000130007/'
AND Method = 'DELETE'
Address
Delete an address:
SELECT
*
FROM
API
WHERE
URL = '/books/v3/contacts/576438000000152001/address/576438000000149024'
AND Method = 'DELETE'
To delete (or insert or update) an address, you must use the API
view. You need to specify the Contact_Id
of the contact and the Address_Id
of the address.
API
view
The API
view lets you use SQL to make Zoho Books API calls. The view has these columns:
Column | Description | ||||||||||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
|
A Zoho Books API endpoint. |
||||||||||||||||||
|
|
||||||||||||||||||
|
HTTP status code.
|
||||||||||||||||||
|
If |
||||||||||||||||||
|
Data sent to the Zoho Books API. |
||||||||||||||||||
|
The type of data in the response. For example, |
||||||||||||||||||
|
Data returned from the Zoho Books API. |
Use SELECT
statements with the API
view. To select data set Method
to GET
. To insert data set Method
to POST
. To insert data set Method
to PUT
. To delete data set Method
to DELETE
.
Use a WHERE
clause to specify the URL
, Method
, and, if updating or inserting data, RequestBody
. For example:
-- List account transactions
SELECT
*
FROM
API
WHERE
URL = 'books/v3/chartofaccounts/transactions
?account_id=579676000000000352&amount.less_than=25384.04'
AND Method = 'GET'
-- List bank accounts
SELECT
ResponseBody
FROM
API
WHERE
URL = 'books/v3/bankaccounts'
AND Method = 'GET'
-- Remove an account a chart of accounts
SELECT
*
FROM
API
WHERE
URL = 'books/v3/chartofaccounts/579676000000107086'
AND Method = 'DELETE'
-- Add a contact address
SELECT
*
FROM
API
WHERE
URL = '/books/v3/contacts/576438000000152001/address'
AND Method = 'POST'
AND RequestBody = '[
{
"phone": "505-111-2222",
"attention": "Paul Smith",
"address": "The Main Office",
"street2": "Big Lumber Yard",
"city": "Ripon",
"state": "Colorado",
"state_code": "CO",
"zip": 22334,
"country_code": "US"
}
]'
-- Update a contact address
SELECT
*
FROM
API
WHERE
URL = '/books/v3/contacts/576438000000152001/address/576438000000149024'
AND Method = 'PUT'
AND RequestBody = '[
{
"phone": "505-111-2222",
"attention": "Paul Smith",
"address": "Admin Office",
"street2": "Big Lumber Yard",
"city": "Ripon",
"state": "Colorado",
"state_code": "CO",
"zip": 22334,
"country_code": "US"
}
]
]'
For more information, consult the Zoho Books API documentation.
JSON columns
Columns that can contain multiple values are in JSON format. For example, a bill’s line items (Bill
table’s Line_Items
column):
To update records with JSON columns (for example, Line_Items
columns), you first need to retrieve the existing JSON. Then change the existing values, or add new JSON to the existing JSON. For example:
SELECT Line_Items FROM Journal WHERE Journal_Id = '579676000000130007'
returns the following (formatted for readability):
{
"account_id": 579676000000000400,
"customer_id": 579676000000050200,
"description": "Standard cheque charge",
"tax_id": 579676000000050200,
"debit_or_credit": "debit",
"amount": 4.99
},
{
"account_id": 579676000000000500,
"customer_id": 579676000000050200,
"description": "Bank charge",
"debit_or_credit": "credit",
"amount": 4.99
}
To change, say, the journal amounts, edit these parts of the JSON:
{
"account_id": 579676000000000400,
"customer_id": 579676000000050200,
"description": "Standard cheque charge",
"tax_id": 579676000000050200,
"debit_or_credit": "debit",
"amount": 5.99
},
{
"account_id": 579676000000000500,
"customer_id": 579676000000050200,
"description": "Bank charge",
"debit_or_credit": "credit",
"amount": 5.99
}
and include the revised JSON in an UPDATE
statement. Enclose the JSON in square brackets. For example:
UPDATE Journal
SET
[Line_Items] = '[
{
"account_id": 579676000000000400,
"customer_id": 579676000000050200,
"description": "Standard cheque charge",
"tax_id": 579676000000050200,
"debit_or_credit": "debit",
"amount": 5.99
},
{
"account_id": 579676000000000500,
"customer_id": 579676000000050200,
"description": "Bank charge",
"debit_or_credit": "credit",
"amount": 5.99
}
]'
WHERE
Journal_id = '579676000000130007'
In the Zoho Books API, JSON has this format:
-
Data is in name/value pairs.
-
Data is separated by commas.
-
Curly braces (
{}
) hold objects. -
Square brackets (
[]
) hold arrays.
All the data names in the Zoho Books API are in lower case. JSON is case sensitive.
In the API we connect to, JSON values must be one of the following data types:
-
String
-
Number
-
Boolean
-
Array
-
Object
Timestamps are returned as a string in the YYYY-MM-DDThh:mm:ssTZD
format. For example:
"last_modified_time":"2024-06-19T08:04:44-0400"
Dates are returned as a string in the YYYY-MM-DD format
. For example:
"date":"2024-06-05"
In some of the JSON returned, you may get something like:
"tags":[]
This denotes an empty array.
String data needs to be escaped:
-
Backslash becomes
\\
-
Backspace becomes
\b
-
Form feed becomes
\f
-
Newline becomes
\n
-
Carriage return becomes
\r
-
Tab becomes
\t
-
Double quote becomes
\"
If you need to clear the contents of a JSON column, set the value to []
. For example:
UPDATE Invoice SET Contact_Persons = '[]' WHERE Invoice_Id = '579676000000050260'
LastId
view
Use this view to get information back from the Zoho Books API after you’ve run an INSERT
, UPDATE
, or DELETE
statement.
The LastId
view contains these columns:
Column | Description |
---|---|
|
API status code ( |
|
API response message. For example, The account has been created. |
|
|
|
The Zoho Books API called. |
|
Key column name. |
|
Key column value. |
|
JSON response sent back from the API. |
Successful inserts always update the LastId
view.
UPDATE
and DELETE
statements only change the LastId
view if at least one record is updated or deleted. If more than one record is updated or deleted, only the ID of the last record altered will be returned. If you attempt to update or delete but the statement does not alter any records, no data will be returned.
The data returned from the LastId
view only applies to the last action on the current connection.
Here’s an example that shows the LastId
result set retrieved after a successful update:
UPDATE Invoice
SET
Line_Items = '{
"line_item_id": "576438000000205017",
"tax_name": "10% Tax",
"item_order": 8,
"quantity": 2,
"header_name": "Storage",
"description": "8TB Surveillance Hard Drive",
"account_id": "576438000000000376",
"rate": 169.14,
"tax_id": "576438000000056007",
"bcy_rate": 169.14,
"account_name": "Sales",
"pricing_scheme": "unit",
"header_id": "576438000000197034",
"tax_type": "tax",
"tax_percentage": 10,
"item_total": 338.28,
"line_item_taxes": [
{
"tax_id": "576438000000056007",
"tax_name": "10% Tax (10%)",
"tax_amount": 33.81
}
]
}'
WHERE
Invoice_Id = '576438000000205001'
SELECT * FROM LastId
Code: 0
Message: Invoice information has been updated.
Operation: UPDATE
Api: invoice
Key: Invoice_Id
Value: 576438000000205001