Working with Items in Zoho Books

Overview

The following operations allow you to work with items. Click an operation name to see details on how to use it.

For a sample proxy service that illustrates how to work with items, see Sample configuration.

Operation	Description
createItem	Creates a new item.
getItem	Retrieves the details of an item.
listItems	Retrieves the list of all items with pagination.

Operation details

This section provides further details on the operations related to items.

Creating a new item

The createItem operation creates a new item.

createItem

<zohobooks.createItem>
    <itemName>{$ctx:itemName}</itemName>
    <description>{$ctx:description}</description>
    <accountId>{$ctx:accountId}</accountId>
    <taxId>{$ctx:taxId}</taxId>
    <isTaxable>{$ctx:isTaxable}</isTaxable>
    <taxExemptionId>{$ctx:taxExemptionId}</taxExemptionId>
    <avataxTaxCode>{$ctx:avataxTaxCode}</avataxTaxCode>
    <avataxUseCode>{$ctx:avataxUseCode}</avataxUseCode>
    <productType>{$ctx:productType}</productType>
    <itemType>{$ctx:itemType}</itemType>
    <purchaseRate>{$ctx:purchaseRate}</purchaseRate>
    <purchaseAccountId>{$ctx:purchaseAccountId}</purchaseAccountId>
    <inventoryAccountId>{$ctx:inventoryAccountId}</inventoryAccountId>
    <vendorId>{$ctx:vendorId}</vendorId>
    <reorderLevel>{$ctx:reorderLevel}</reorderLevel>
    <initialStock>{$ctx:initialStock}</initialStock>
    <initialStockRate>{$ctx:initialStockRate}</initialStockRate>
    <purchaseDescription>{$ctx:purchaseDescription}</purchaseDescription>
    <rate>{$ctx:rate}</rate>
    <unit>{$ctx:unit}</unit>
    <taxPercentage>{$ctx:taxPercentage}</taxPercentage>
	<purchaseAccountName>{$ctx:purchaseAccountName}</purchaseAccountName>
</zohobooks.createItem>

Properties

itemName: The name of the item.
description: The description of the item.
accountId: The ID of the account with which the item has to be associated.
taxId: The ID of the tax to be associated with the item (not applicable for US Edition).
isTaxable: The Boolean value to track the taxability of the item (US Edition only).
taxExemptionId: The ID of the tax exemption. Mandatory, if "is_taxable" is "false" (US Edition only).
avataxTaxCode: A unique label used to group Items (products, services, or charges) together (Avalara integration only).
avataxUseCode: Groups similar customers for exemption purposes. It is a custom value that links customers to a tax rule (Avalara integration only).
productType: The product type of an item. Items with the type "digital_service" are treated as a service except for the cases where non-UK VAT is applied to the "digital_service" items (UK Edition only).
itemType: The type of the item. Allowed values: "sales", "purchase", "sales_and_purchase" and "inventory". Default value: "sales".
purchaseRate: The purchase price of the item (Mandatory, if "item_type" is "purchase", "sales and purchase", or "inventory").
purchaseAccountId: The ID of the COGS account with which the item has to be associated (Mandatory, if "item_type" is "purchase", "sales and purchase" or "inventory").
inventoryAccountId: The ID of the stock account with which the item has to be associated (Mandatory, if "item_type" is "inventory").
vendorId: The preferred vendor ID.
reorderLevel: The reorder level of the item.
initialStock: The opening stock of the item.
initialStockRate: The unit price of the opening stock.
purchaseDescription: The purchase description of the Item.
rate: The price of the item.
unit: The unit to measure the quantity of the item.
taxPercentage: The percentage of tax to be added to the item.
purchaseAccountName: The name of the purchase account.

Sample request

Following is a sample REST/JSON request that can be handled by the createItem operation.

Sample Request for createItem

{
    "apiUrl": "https://books.zoho.com",
    "authToken": "594cb85213f98ce15dfa9fe92330658a",
    "organizationId": "46892166",
    "itemName": "iPhone 1.7",
    "description": "Description for iPhone 1.7",
    "rate": 17.00,
    "purchaseAccountId": "ereer",
    "inventoryAccountId": "ererer",
    "reorderLevel": "erere",
    "accountId": "rerere",
    "purchaseDescription": "eer",
    "isTaxable": true,
    "purchaseRate": "erer",
    "itemType": "erer",
    "initialStockRate": "ererer",
    "initialStock": "ereer",
    "vendorId": "erere",
    "productType": "erere",
    "avataxTaxCode": "errer",
    "taxId": "ereer",
    "taxExemptionId": "ererer",
    "avataxUseCode": "erre",
    "unit": "ereer",
    "taxPercentage": "ererer",
    "purchaseAccountName": "erre"
}

Retrieving the details of an item

The getItem operation retrieves the details of an item.

getItem

<zohobooks.getItem>
	<itemId>{$ctx:itemId}</itemId>
</zohobooks.getItem>

Properties

itemId: The ID of the item to be retrieved.

Sample request

Following is a sample REST/JSON request that can be handled by the getItem operation.

Sample Request for getItem

{
    "authToken": "594cb85213f98ce15dfa9fe92330658a",
    "apiUrl": "https://books.zoho.com",
    "organizationId": "46892166",
    "itemId": ""
}

Retrieving the list of items with pagination

The listItems operation retrieves the list of all active items with pagination.

listItems

<zohobooks.listItems>
    <page>{$ctx:page}</page>
    <perPage>{$ctx:perPage}</perPage>
    <appliedFilter>{$ctx:appliedFilter}</appliedFilter>
    <sortOrder>{$ctx:sortOrder}</sortOrder>
    <sortColumn>{$ctx:sortColumn}</sortColumn>
    <searchText>{$ctx:searchText}</searchText>
    <filterBy>{$ctx:filterBy}</filterBy>
    <taxName>{$ctx:taxName}</taxName>
    <taxId>{$ctx:taxId}</taxId>
    <name>{$ctx:name}</name>
    <nameStartsWith>{$ctx:nameStartsWith}</nameStartsWith>
    <nameContains>{$ctx:nameContains}</nameContains>
    <rate>{$ctx:rate}</rate>
    <rateLessThan>{$ctx:rateLessThan}</rateLessThan>
    <rateLessEquals>{$ctx:rateLessEquals}</rateLessEquals>
    <rateGreaterEquals>{$ctx:rateGreaterEquals}</rateGreaterEquals>
    <accountId>{$ctx:accountId}</accountId>
    <taxExemptionId>{$ctx:taxExemptionId}</taxExemptionId>
    <isTaxable>{$ctx:isTaxable}</isTaxable>
    <description>{$ctx:description}</description>
    <descriptionStartsWith>{$ctx:descriptionStartsWith}</descriptionStartsWith>
    <descriptionContains>{$ctx:descriptionContains}</descriptionContains>
	<rateGreaterThan>{$ctx:rateGreaterThan}</rateGreaterThan>
</zohobooks.listItems>

Properties

page: The number of the page to be returned - pagination value.
perPage: Specifies how many entries should be returned in the response.
appliedFilter: Filters to be applied while querying.
sortOrder: The order of sorting - "ascending" or "descending".
sortColumn: Sort contacts. Allowed values: "contact_name", "first_name", "last_name", "email", "outstanding_receivable_amount", "outstanding_payable_amount", "created_time" and "last_modified_time".
searchText: Searches contacts by contact name or notes.
filterBy: Filters contacts by status. Allowed values: "Status.All", "Status.Active", "Status.Inactive", "Status.Duplicate", "Status.Customers", "Status.Vendors" and "Status".
taxName: The name of the tax to be associated.
taxId: The ID of the tax or tax group that can be collected from the contact. The tax can be given only if "is_taxable" is "true" (US Edition only).
name: Searches items by name.
nameStartsWith: Searches items by name starting with this value.
nameContains: Searches items by name containing this value.
rate: Searches items by rate.
rateLessThan: Searches items by rate less than this value.
rateLessEquals: Searches items by rate less than or equal to this value.
rateGreaterEquals: Searches items by rate greater than or equal to this value.
accountId: Searches items by account ID.
taxExemptionId: The ID of the tax exemption (US Edition only).
isTaxable: The Boolean value to track the taxability of the customer (US Edition only).
description: Searches items by description.
descriptionStartsWith: Searches items by description starting with this value.
descriptionContains: Searches items by description containing this value.
rateGreaterThan: Searches items by rate greater than this value.

Sample request

Following is a sample REST/JSON request that can be handled by the listTrainings operation.

Sample Request for listTrainings

{
    "apiUrl": "https://api.citrixonline.com",
    "accessToken": "zR14S7cGFWC0UXuujbYP5DGKbeOR",
    "organizerKey": "3596608450020387846",
    "grantType": "password",
    "userId": "wso2connector@gmail.com",
    "password": "1qaz2wsx@",
    "clientId": "2UVpqLxGDrkcQvs0JGvUMDyO1Mha9FT0"
}

Sample configuration

Following is a sample proxy service that illustrates how to connect to Zoho Books with the init operation and use the createItem operation. The sample request for this proxy can be found in the createItem sample request. You can use this sample as a template for using other operations in this category.

Sample Proxy

<?xml version="1.0" encoding="UTF-8"?>
<proxy name="zohobooks_createItem" startOnLoad="true" statistics="disable" trace="disable" transports="https,http" xmlns="http://ws.apache.org/ns/synapse">
   <target>
      <inSequence>
         <property name="apiUrl" expression="json-eval($.apiUrl)"/>
         <property name="authToken" expression="json-eval($.authToken)"/>
         <property name="organizationId" expression="json-eval($.organizationId)"/>
         <property name="itemName" expression="json-eval($.itemName)"/>
         <property name="description" expression="json-eval($.description)"/>
         <property name="accountId" expression="json-eval($.accountId)"/>
         <property name="taxId" expression="json-eval($.taxId)"/>
         <property name="isTaxable" expression="json-eval($.isTaxable)"/>
         <property name="taxExemptionId" expression="json-eval($.taxExemptionId)"/>
         <property name="avataxTaxCode" expression="json-eval($.avataxTaxCode)"/>
         <property name="avataxUseCode" expression="json-eval($.avataxUseCode)"/>
         <property name="productType" expression="json-eval($.productType)"/>
         <property name="itemType" expression="json-eval($.itemType)"/>
         <property name="purchaseRate" expression="json-eval($.purchaseRate)"/>
         <property name="purchaseAccountId" expression="json-eval($.purchaseAccountId)"/>
         <property name="inventoryAccountId" expression="json-eval($.inventoryAccountId)"/>
         <property name="vendorId" expression="json-eval($.vendorId)"/>
         <property name="reorderLevel" expression="json-eval($.reorderLevel)"/>
         <property name="initialStock" expression="json-eval($.initialStock)"/>
         <property name="initialStockRate" expression="json-eval($.initialStockRate)"/>
         <property name="purchaseDescription" expression="json-eval($.purchaseDescription)"/>
         <property name="rate" expression="json-eval($.rate)"/>
         <property name="unit" expression="json-eval($.unit)"/>
         <property name="taxPercentage" expression="json-eval($.taxPercentage)"/>
         <property name="purchaseAccountName" expression="json-eval($.purchaseAccountName)"/>
         <zohobooks.init>
            <apiUrl>{$ctx:apiUrl}</apiUrl>
            <authToken>{$ctx:authToken}</authToken>
            <organizationId>{$ctx:organizationId}</organizationId>
         </zohobooks.init>
         <zohobooks.createItem>
            <itemName>{$ctx:itemName}</itemName>
            <description>{$ctx:description}</description>
            <accountId>{$ctx:accountId}</accountId>
            <taxId>{$ctx:taxId}</taxId>
            <isTaxable>{$ctx:isTaxable}</isTaxable>
            <taxExemptionId>{$ctx:taxExemptionId}</taxExemptionId>
            <avataxTaxCode>{$ctx:avataxTaxCode}</avataxTaxCode>
            <avataxUseCode>{$ctx:avataxUseCode}</avataxUseCode>
            <productType>{$ctx:productType}</productType>
            <itemType>{$ctx:itemType}</itemType>
            <purchaseRate>{$ctx:purchaseRate}</purchaseRate>
            <purchaseAccountId>{$ctx:purchaseAccountId}</purchaseAccountId>
            <inventoryAccountId>{$ctx:inventoryAccountId}</inventoryAccountId>
            <vendorId>{$ctx:vendorId}</vendorId>
            <reorderLevel>{$ctx:reorderLevel}</reorderLevel>
            <initialStock>{$ctx:initialStock}</initialStock>
            <initialStockRate>{$ctx:initialStockRate}</initialStockRate>
            <purchaseDescription>{$ctx:purchaseDescription}</purchaseDescription>
            <rate>{$ctx:rate}</rate>
            <unit>{$ctx:unit}</unit>
            <taxPercentage>{$ctx:taxPercentage}</taxPercentage>
            <purchaseAccountName>{$ctx:purchaseAccountName}</purchaseAccountName>
         </zohobooks.createItem>
         <respond/>
      </inSequence>
      <outSequence>
         <send/>
      </outSequence>
   </target>
   <description/>
</proxy>

WSO2 ESB Connectors Documentation

Working with Items in Zoho Books

Overview

Operation details

Creating a new item

Properties

Sample request

Related Zoho Books documentation

Retrieving the details of an item

Properties

Sample request

Related Zoho Books documentation

Retrieving the list of items with pagination

Properties

Sample request

Related Zoho Books documentation

Sample configuration