This site contains the documentation that is relevant to older WSO2 product versions and offerings.
For the latest WSO2 documentation, visit https://wso2.com/documentation/.
Working with Invoices in Zoho Books
Overview
The following operations allow you to work with invoices. Click an operation name to see details on how to use it.
For a sample proxy service that illustrates how to work with invoices, see Sample configuration.
Operation | Description |
---|---|
Creates an invoice. | |
emailInvoices | Sends an invoice to the customer by e-mail. |
getInvoice | Retrieves details of an invoice. |
listInvoices | Retrieves all invoices with pagination. |
Operation details
This section provides further details on the operations related to invoices.
Creating an invoice
The createInvoice operation creates an invoice for the customer.
<zohobooks.createInvoice> <customerId>{$ctx:customerId}</customerId> <contactPersons>{$ctx:contactPersons}</contactPersons> <invoiceNumber>{$ctx:invoiceNumber}</invoiceNumber> <templateId>{$ctx:templateId}</templateId> <date>{$ctx:date}</date> <paymentTerms>{$ctx:paymentTerms}</paymentTerms> <paymentTermsLabel>{$ctx:paymentTermsLabel}</paymentTermsLabel> <dueDate>{$ctx:dueDate}</dueDate> <discount>{$ctx:discount}</discount> <isDiscountBeforeTax>{$ctx:isDiscountBeforeTax}</isDiscountBeforeTax> <discountType>{$ctx:discountType}</discountType> <exchangeRate>{$ctx:exchangeRate}</exchangeRate> <recurringInvoiceId>{$ctx:recurringInvoiceId}</recurringInvoiceId> <invoicedEstimateId>{$ctx:invoicedEstimateId}</invoicedEstimateId> <salespersonName>{$ctx:salespersonName}</salespersonName> <customFields>{$ctx:customFields}</customFields> <lineItems>{$ctx:lineItems}</lineItems> <allowPartialPayments>{$ctx:allowPartialPayments}</allowPartialPayments> <customBody>{$ctx:customBody}</customBody> <customSubject>{$ctx:customSubject}</customSubject> <notes>{$ctx:notes}</notes> <terms>{$ctx:terms}</terms> <shippingCharge>{$ctx:shippingCharge}</shippingCharge> <adjustment>{$ctx:adjustment}</adjustment> <adjustmentDescription>{$ctx:adjustmentDescription}</adjustmentDescription> <timeEntryIds>{$ctx:timeEntryIds}</timeEntryIds> <paymentOptions>{$ctx:paymentOptions}</paymentOptions> <taxId>{$ctx:taxId}</taxId> <taxAuthorityId>{$ctx:taxAuthorityId}</taxAuthorityId> <taxExemptionId>{$ctx:taxExemptionId}</taxExemptionId> <avataxUseCode>{$ctx:avataxUseCode}</avataxUseCode> <avataxExemptNo>{$ctx:avataxExemptNo}</avataxExemptNo> <vatTreatment>{$ctx:vatTreatment}</vatTreatment> <send>{$ctx:send}</send> <ignoreAutoNumberGeneration>{$ctx:ignoreAutoNumberGeneration}</ignoreAutoNumberGeneration> </zohobooks.createInvoice>
Properties
The ID of the customer for whom the invoice has to be created.customerId:
The array of contact persons to whom the invoice has to be sent.contactPersons:
Mandatory number if auto number generation is disabled.invoiceNumber:
The ID of the PDF template associated with the invoice.templateId:
The date on which the invoice is created.date:
Payment terms in days, e.g. 15, 30, 60. The invoice due date will be calculated based on this.paymentTerms:
Overrides the default payment terms label.paymentTermsLabel:
The date on which the invoice is due.dueDate:
The discount applied to the invoice. It can be either a percentage or an amount, e.g. 12.5% or 190.discount:
Specifies how the discount has to be applied, either before or after the calculation of tax.isDiscountBeforeTax:
Describes how the discount is specified. Allowed values: "entity_level" and "item_level".discountType:
The exchange rate of the currency.exchangeRate:
The ID of the recurring invoice from which the invoice is created.recurringInvoiceId:
The ID of the estimate from which the invoice is created.invoicedEstimateId:
The name of the sales person.salespersonName:
The custom fields for an invoice.customFields:
Line items of an invoice.lineItems:
Indicates whether the payment can be made partially for this invoice.allowPartialPayments:
The custom body for the invoice.customBody:
The custom subject for the invoice.customSubject:
Notes to be added to the Invoice.notes:
The terms and conditions applicable to the invoice.terms:
Shipping charges applied to the invoice.shippingCharge:
Adjustments made to the invoice.adjustment:
Customizes the adjustment description, e.g. "Rounding off".adjustmentDescription:
IDs of the time entries associated with the project.timeEntryIds:
Payment options for the invoice - online payment gateways. Will be displayed in the PDF.paymentOptions:
The ID of the tax or tax group applied to the line item.taxId:
The ID of the tax authority. The tax authority depends on the location of the customer. For example, if the customer is located in NY, the tax authority is the NY tax authority.taxAuthorityId:
The ID of the tax exemption.taxExemptionId:
Groups similar customers for exemption purposes. It is a custom value that links customers to a tax rule.avataxUseCode:
The exemption certificate number of the customer.avataxExemptNo:
The VAT treatment for the invoice. The VAT treatment denotes the location of the customer; if the customer resides in UK, the VAT treatment is "UK".vatTreatment:
Sends the invoice to the contact persons associated with the invoice. Allowed values: "true" and "false".send:
Ignores auto invoice number generation for this invoice. This mandates the invoice number. Allowed values: "true" and "false".ignoreAutoNumberGeneration:
Sample request
Following is a sample REST/JSON request that can be handled by the
operation.createInvoice
{ "apiUrl": "https://books.zoho.com", "authToken": "594cb85213f98ce15dfa9fe92330658a", "organizationId": "46892166", "send": "true", "ignoreAutoNumberGeneration": "true", "customerId": "119406000000052001", "contactPersons": [], "exchangeRate": 1, "terms": "", "recurringInvoiceId": "", "date": "2015-08-05", "adjustment": "", "discountType": "item_level", "vatTreatment": "", "taxExemptionId": "", "customSubject": "", "timeEntryIds": "", "avataxUseCode": "", "dueDate": "2015-10-20", "lineItems": [ { "item_id": "119406000000037013", "salesorder_item_id": "", "project_id": "", "time_entry_ids": "", "expense_id": "", "name": "Hard Drive", "description": "500GB, USB 2.0 interface 1400 rpm, protective hard case.", "item_order": 1, "bcy_rate": 120, "rate": 120, "quantity": 4, "unit": "Nos", "discount_amount": 0, "discount": 0, "tax_type": "tax", "tax_percentage": 0, "item_total": 480, "stock_on_hand": "100" }], "salespersonName": "John Michael", "customFields": [], "adjustmentDescription": "Rounding off", "invoicedEstimateId": "", "invoiceNumber": "INVOICE_1020", "isDiscountBeforeTax": "", "shippingCharge": "1000.00", "discount": "", "templateId": "", "customBody": "", "paymentTermsLabel": "Net 15", "paymentOptions": { "payment_gateways": [] }, "avataxExemptNo": "", "taxId": "", "allowPartialPayments": "false", "taxAuthorityId": "", "paymentTerms": "15", "notes": "Thanks for your business." }
Related Zoho Books documentation
https://www.zoho.com/books/api/v3/invoices/#create-an-invoice
Sending invoices to customers by e-mail
The emailInvoices operation sends invoices to customers by e-mail. A maximum of 10 invoices can be sent at once.
<zohobooks.emailInvoices> <invoiceId>{$ctx:invoiceId}</invoiceId> <contacts>{$ctx:contacts}</contacts> <invoiceIds>{$ctx:invoiceIds}</invoiceIds> </zohobooks.emailInvoices>
Properties
The ID of the invoice.invoiceId:
Contacts to whom an e-mail or snail mail has to be sent.contacts:
Comma separated invoice IDs which are to be e-mailed.invoiceIds:
Sample request
Following is a sample REST/JSON request that can be handled by the emailInvoices operation.
{ "invoiceIds": "119406000000052055,119406000000051027", "authToken": "594cb85213f98ce15dfa9fe92330658a", "apiUrl": "https://books.zoho.com", "organizationId": "46892166", "contacts": [ { "contact_id": "119406000000052049", "email": true, "snail_mail": false }] }
Related Zoho Books documentation
https://www.zoho.com/books/api/v3/invoices/#email-invoices
Retrieving details of an invoice
The getInvoice operation retrieves the details of an invoice.
<zohobooks.getInvoice> <invoiceId>{$ctx:invoiceId}</invoiceId> <shouldPrint>{$ctx:shouldPrint}</shouldPrint> <invoiceFormat>{$ctx:invoiceFormat}</invoiceFormat> </zohobooks.getInvoice>
Properties
invoiceId:
The ID of the invoice to retrieve.shouldPrint:
Prints the exported PDF.invoiceFormat:
Gets the details of a particular invoice in formats such as JSON, PDF, or HTML. Default format: JSON. Allowed values: JSON, PDF and HTML.
Sample request
Following is a sample REST/JSON request that can be handled by the getInvoice operation.
{ "invoiceId": "119406000000042031", "invoiceFormat": "pdf", "shouldPrint": "true", "authToken": "594cb85213f98ce15dfa9fe92330658a", "apiUrl": "https://books.zoho.com", "organizationId": "46892166" }
Related Zoho Books documentation
https://www.zoho.com/books/api/v3/invoices/#get-an-invoice
Retrieving all invoices
The listInvoices
operation retrieves all invoices with pagination.
<zohobooks.listInvoices> <page>{$ctx:page}</page> <perPage>{$ctx:perPage}</perPage> <appliedFilter>{$ctx:appliedFilter}</appliedFilter> <sortOrder>{$ctx:sortOrder}</sortOrder> <invoiceNumber>{$ctx:invoiceNumber}</invoiceNumber> <invoiceNumberStartsWith>{$ctx:invoiceNumberStartsWith}</invoiceNumberStartsWith> <invoiceNumberContains>{$ctx:invoiceNumberContains}</invoiceNumberContains> <itemName>{$ctx:itemName}</itemName> <itemNameStartsWith>{$ctx:itemNameStartsWith}</itemNameStartsWith> <itemNameContains>{$ctx:itemNameContains}</itemNameContains> <itemId>{$ctx:itemId}</itemId> <itemDescription>{$ctx:itemDescription}</itemDescription> <itemDescriptionStartsWith>{$ctx:itemDescriptionStartsWith}</itemDescriptionStartsWith> <itemDescriptionContains>{$ctx:itemDescriptionContains}</itemDescriptionContains> <referenceNumber>{$ctx:referenceNumber}</referenceNumber> <referenceNumberStartsWith>{$ctx:referenceNumberStartsWith}</referenceNumberStartsWith> <referenceNumberContains>{$ctx:referenceNumberContains}</referenceNumberContains> <customerName>{$ctx:customerName}</customerName> <customerNameStartsWith>{$ctx:customerNameStartsWith}</customerNameStartsWith> <customerNameContains>{$ctx:customerNameContains}</customerNameContains> <email>{$ctx:email}</email> <total>{$ctx:total}</total> <totalLessThan>{$ctx:totalLessThan}</totalLessThan> <totalLessEquals>{$ctx:totalLessEquals}</totalLessEquals> <totalGreaterThan>{$ctx:totalGreaterThan}</totalGreaterThan> <totalGreaterEquals>{$ctx:totalGreaterEquals}</totalGreaterEquals> <balanceLessThan>{$ctx:balanceLessThan}</balanceLessThan> <balanceLessEquals>{$ctx:balanceLessEquals}</balanceLessEquals> <balanceGreaterThan>{$ctx:balanceGreaterThan}</balanceGreaterThan> <balanceGreaterEquals>{$ctx:balanceGreaterEquals}</balanceGreaterEquals> <date>{$ctx:date}</date> <dateStart>{$ctx:dateStart}</dateStart> <dateEnd>{$ctx:dateEnd}</dateEnd> <dateBefore>{$ctx:dateBefore}</dateBefore> <dateAfter>{$ctx:dateAfter}</dateAfter> <dueDate>{$ctx:dueDate}</dueDate> <dueDateStart>{$ctx:dueDateStart}</dueDateStart> <dueDateEnd>{$ctx:dueDateEnd}</dueDateEnd> <dueDateBefore>{$ctx:dueDateBefore}</dueDateBefore> <dueDateAfter>{$ctx:dueDateAfter}</dueDateAfter> <status>{$ctx:status}</status> <customerId>{$ctx:customerId}</customerId> <customField>{$ctx:customField}</customField> <customFieldStartsWith>{$ctx:customFieldStartsWith}</customFieldStartsWith> <customFieldContains>{$ctx:customFieldContains}</customFieldContains> <searchText>{$ctx:searchText}</searchText> <sortColumn>{$ctx:sortColumn}</sortColumn> <filterBy>{$ctx:filterBy}</filterBy> <recurringInvoiceId>{$ctx:recurringInvoiceId}</recurringInvoiceId> <balance>{$ctx:balance}</balance> </zohobooks.listInvoices>
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".invoiceNumber:
Searches invoices by invoice number.invoiceNumberStartsWith:
Searches invoices by invoice number starting with this value.invoiceNumberContains:
Searches invoices by invoice number containing this value.itemName:
Searches invoices by item name.itemNameStartsWith:
Searches invoices by item name starting with this value.itemNameContains:
Searches invoices by item name containing this value.itemId:
Searches invoices by item ID.itemDescription:
Searches invoices by item description.itemDescriptionStartsWith:
Searches invoices by item description starting with this value.itemDescriptionContains:
Searches invoices by item description containing this value.referenceNumber:
Searches invoices by invoice reference number.referenceNumberStartsWith:
Searches invoices by invoice reference number starting with this value.referenceNumberContains:
Search invoices by invoice reference number containing this value.customerName:
Searches invoices by customer name.customerNameStartsWith:
Searches invoices by customer name starting with this value.customerNameContains:
Search invoices by customer name containing this value.email:
Searches invoices by customer contact person's e-mail address.total:
Searches invoices by invoice total.totalLessThan:
Searches invoices by invoice total less than this value.totalLessEquals:
Searches invoices by invoice total less than or equal to this value.totalGreaterThan:
Searches invoices by invoice total greater than this value.totalGreaterEquals:
Searches invoices by invoice total greater than or equal to this value.balanceLessThan:
Searches invoices by invoice balance less than this value.balanceLessEquals:
Searches invoices by invoice balance less than or equal to this value.balanceGreaterThan:
Searches invoices by invoice balance greater than this value.balanceGreaterEquals:
Searches invoices by invoice balance greater than or equal to this value.date:
Searches invoices by invoice date.dateStart:
Searches invoices by invoice date.dateEnd:
Searches invoices by invoice date.dateBefore:
Searches invoices by invoice date.dateAfter:
Searches invoices by invoice date.dueDate:
Searches invoices by invoice date.dueDateStart:
Searches invoices by invoice date.dueDateEnd:
Searches invoices by invoice date.dueDateBefore:
Searches invoices by invoice date.dueDateAfter:
Searches invoices by invoice date.status:
Searches invoices by invoice status.customerId:
Searches invoices by customer ID.customField:
Searches invoices by custom fields.customFieldStartsWith:
Searches invoices by custom fields starting with this value.customFieldContains:
Searches invoices by custom fields containing this value.searchText:
Searches invoices by invoice number or purchase order or customer name.sortColumn:
Sorts invoices. Allowed values: "customer_name", "invoice_number", "date", "due_date", "total", "balance" and "created_time".filterBy:
Filters invoices by any status or payment expected date. Allowed values: "Status.All", "Status.Sent", "Status.Draft", "Status.OverDue", "Status.Paid", "Status.Void", "Status.Unpaid", "Status.PartiallyPaid", "Status.Viewed" and "Date.PaymentExpectedDate".recurringInvoiceId:
Searches invoices by recurring profile ID.balance:
Searches invoices by invoice balance.
Sample request
Following is a sample REST/JSON request that can be handled by the listInvoices
operation.
{ "total": { "lessThan": "", "equals": "", "greaterThan": "", "lessEquals": "", "greaterEquals": "" }, "customerName": { "startsWith": "", "equals": "", "contains": "" }, "itemName": { "startsWith": "", "equals": "", "contains": "" }, "customField": { "startsWith": "", "equals": "", "contains": "" }, "status": "sent", "referenceNumber": { "startsWith": "", "equals": "", "contains": "" }, "authToken": "594cb85213f98ce15dfa9fe92330658a", "recurringInvoiceId": "", "invoiceNumber": { "startsWith": "", "equals": "", "contains": "" }, "organizationId": "46892166", "itemId": "", "date": { "after": "", "start": "", "equals": "", "before": "", "end": "" }, "balance": { "lessThan": "", "equals": "", "greaterThan": "", "lessEquals": "", "greaterEquals": "" }, "sortColumn": "", "perPage": 100, "page": 1, "appliedFilter": "", "sortOrder": "", "itemDescription": { "startsWith": "", "equals": "", "contains": "" }, "customerId": "", "email": "", "apiUrl": "https://books.zoho.com", "searchText": "", "filterBy": "", "dueDate": { "after": "", "start": "", "equals": "", "before": "", "end": "" } }
Related Zoho Books documentation
https://www.zoho.com/books/api/v3/invoices/#list-invoices
Sample configuration
Following is a sample proxy service that illustrates how to connect to Zoho Books with the init
operation and use the createInvoice
operation. The sample request for this proxy can be found in the createInvoice sample request. You can use this sample as a template for using other operations in this category.
<?xml version="1.0" encoding="UTF-8"?> <proxy name="zohobooks_createInvoice" 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="customerId" expression="json-eval($.customerId)"/> <property name="contactPersons" expression="json-eval($.contactPersons)"/> <property name="invoiceNumber" expression="json-eval($.invoiceNumber)"/> <property name="templateId" expression="json-eval($.templateId)"/> <property name="date" expression="json-eval($.date)"/> <property name="paymentTerms" expression="json-eval($.paymentTerms)"/> <property name="paymentTermsLabel" expression="json-eval($.paymentTermsLabel)"/> <property name="dueDate" expression="json-eval($.dueDate)"/> <property name="discount" expression="json-eval($.discount)"/> <property name="isDiscountBeforeTax" expression="json-eval($.isDiscountBeforeTax)"/> <property name="discountType" expression="json-eval($.discountType)"/> <property name="exchangeRate" expression="json-eval($.exchangeRate)"/> <property name="recurringInvoiceId" expression="json-eval($.recurringInvoiceId)"/> <property name="invoicedEstimateId" expression="json-eval($.invoicedEstimateId)"/> <property name="salespersonName" expression="json-eval($.salespersonName)"/> <property name="customFields" expression="json-eval($.customFields)"/> <property name="lineItems" expression="json-eval($.lineItems)"/> <property name="allowPartialPayments" expression="json-eval($.allowPartialPayments)"/> <property name="customBody" expression="json-eval($.customBody)"/> <property name="customSubject" expression="json-eval($.customSubject)"/> <property name="notes" expression="json-eval($.notes)"/> <property name="terms" expression="json-eval($.terms)"/> <property name="shippingCharge" expression="json-eval($.shippingCharge)"/> <property name="adjustment" expression="json-eval($.adjustment)"/> <property name="adjustmentDescription" expression="json-eval($.adjustmentDescription)"/> <property name="timeEntryIds" expression="json-eval($.timeEntryIds)"/> <property name="paymentOptions" expression="json-eval($.paymentOptions)"/> <property name="taxId" expression="json-eval($.taxId)"/> <property name="taxAuthorityId" expression="json-eval($.taxAuthorityId)"/> <property name="taxExemptionId" expression="json-eval($.taxExemptionId)"/> <property name="avataxUseCode" expression="json-eval($.avataxUseCode)"/> <property name="avataxExemptNo" expression="json-eval($.avataxExemptNo)"/> <property name="vatTreatment" expression="json-eval($.vatTreatment)"/> <property name="send" expression="json-eval($.send)"/> <property name="ignoreAutoNumberGeneration" expression="json-eval($.ignoreAutoNumberGeneration)"/> <zohobooks.init> <apiUrl>{$ctx:apiUrl}</apiUrl> <authToken>{$ctx:authToken}</authToken> <organizationId>{$ctx:organizationId}</organizationId> </zohobooks.init> <zohobooks.createInvoice> <customerId>{$ctx:customerId}</customerId> <contactPersons>{$ctx:contactPersons}</contactPersons> <invoiceNumber>{$ctx:invoiceNumber}</invoiceNumber> <templateId>{$ctx:templateId}</templateId> <date>{$ctx:date}</date> <paymentTerms>{$ctx:paymentTerms}</paymentTerms> <paymentTermsLabel>{$ctx:paymentTermsLabel}</paymentTermsLabel> <dueDate>{$ctx:dueDate}</dueDate> <discount>{$ctx:discount}</discount> <isDiscountBeforeTax>{$ctx:isDiscountBeforeTax}</isDiscountBeforeTax> <discountType>{$ctx:discountType}</discountType> <exchangeRate>{$ctx:exchangeRate}</exchangeRate> <recurringInvoiceId>{$ctx:recurringInvoiceId}</recurringInvoiceId> <invoicedEstimateId>{$ctx:invoicedEstimateId}</invoicedEstimateId> <salespersonName>{$ctx:salespersonName}</salespersonName> <customFields>{$ctx:customFields}</customFields> <lineItems>{$ctx:lineItems}</lineItems> <allowPartialPayments>{$ctx:allowPartialPayments}</allowPartialPayments> <customBody>{$ctx:customBody}</customBody> <customSubject>{$ctx:customSubject}</customSubject> <notes>{$ctx:notes}</notes> <terms>{$ctx:terms}</terms> <shippingCharge>{$ctx:shippingCharge}</shippingCharge> <adjustment>{$ctx:adjustment}</adjustment> <adjustmentDescription>{$ctx:adjustmentDescription}</adjustmentDescription> <timeEntryIds>{$ctx:timeEntryIds}</timeEntryIds> <paymentOptions>{$ctx:paymentOptions}</paymentOptions> <taxId>{$ctx:taxId}</taxId> <taxAuthorityId>{$ctx:taxAuthorityId}</taxAuthorityId> <taxExemptionId>{$ctx:taxExemptionId}</taxExemptionId> <avataxUseCode>{$ctx:avataxUseCode}</avataxUseCode> <avataxExemptNo>{$ctx:avataxExemptNo}</avataxExemptNo> <vatTreatment>{$ctx:vatTreatment}</vatTreatment> <send>{$ctx:send}</send> <ignoreAutoNumberGeneration>{$ctx:ignoreAutoNumberGeneration}</ignoreAutoNumberGeneration> </zohobooks.createInvoice> <respond/> </inSequence> <outSequence> <send/> </outSequence> </target> <description/> </proxy>