Share this API doc
Introduction
Introduction
API Root Endpoint
https://books.zoho.com/api/v3
The Zoho Books API allows you to perform all the operations that you do with our web client.
Zoho Books API is built using REST principles which ensures predictable URLs that makes writing applications easy. This API follows HTTP rules, enabling a wide range of HTTP clients can be used to interact with the API.
Every resource is exposed as a URL. The URL of each resource can be obtained by accessing the API Root Endpoint.
Getting Started
Example
$ curl https://books.zoho.com/api/v3/organizations?organization_id=10234695 -H 'Authorization: Zoho-authtoken ba4604e8e433g9c892e360d53463oec5'
To use our API you must satisfy these prerequistes
- A valid Zoho username and password.
- An Authentication Token - authtoken in short!
Authentication
All Zoho Books API need to be authenticated using an authtoken.
You can obtain an authtoken in any one of the following ways:
- Through a URL in your browser.
- Programmatically using the Zoho Accounts API.
Sample Success Response
# #Fri Apr 11 06:14:13 PST 2016 AUTHTOKEN=ba4604e8e433g9c892e360d53463oec5 RESULT=TRUE
Sample Error Response
# #Fri Apr 11 06:32:13 PST 2016 CAUSE=INVALID_API_AUTHTOKEN_SCOPE RESULT=FALSE
In your browser
Obtaining an authtoken in your browser is very simple. Login to your Zoho Account and go to the URL below.
https://accounts.zoho.com/apiauthtoken/create?SCOPE=ZohoBooks/booksapi
Programmatically using the API
If you have chosen to obtain your authtoken via an API, please follow the instructions given below:
Submit an HTTP POST request to the below URL.
https://accounts.zoho.com/apiauthtoken/create.
The POST body should include a string in the below format.
?SCOPE=ZohoBooks/booksapi&EMAIL_ID=[ZohoID/EmailID]&PASSWORD=[Password]
Below are the mandatory case sensitive fields to be passed in the URL.
| Parameter | Description |
|---|---|
| SCOPE | ZohoBooks/booksapi |
| EMAIL_ID | Your Zoho ID or Email ID. |
| PASSWORD | Your Zoho password or your TFA* |
* To know more about TFA and creating application password click here.
Points To Note
- You can manage (regenerate or delete) your active authtokens created for different Zoho Services here.
- Authtokens do not get deleted unless you delete them from the Zoho Accounts page yourself. You do not need to create multiple authtokens to send out requests.
- Authtokens carry important information about your identity. So make sure, you keep them secure and it is secretive.
- It is not possible to obtain an authtoken via the Zoho Accounts API if you log in to Zoho Books with your Google, Yahoo or any other third party accounts.
Organization ID
Request Example
$ curl https://books.zoho.com/api/v3/organizations -H 'Authorization: Zoho-authtoken ba4604e8e433g9c892e360d53463oec5'
Response Example
HTTP/1.1 200 OK Content-Type:application/json;charset=UTF-8 { "code": 0, "message": "success", "organizations": [ { "organization_id": "10234695", "name": "Zillum", "contact_name": "John Smith", "email": "johnsmith@zillum.com", "is_default_org": false, "language_code": "en", "fiscal_year_start_month": 0, "account_created_date": "2016-02-18", "time_zone": "PST", "is_org_active": true, "currency_id": "460000000000097", "currency_code": "USD", "currency_symbol": "$", "currency_format": "###,##0.00", "price_precision": 2 }, {...}, {...} ]
In Zoho Books, your business is termed as an organization. If you have multiple businesses, you simply set each of those up as an individual organization. Each organization is an independent Zoho Books Organization with it’s own organization ID, base currency, time zone, language, contacts, reports, etc.
The parameter organization_id along with the organization ID should be sent in with every API request to identify the organization.
The organization_id can be obtained from the GET /organizations API’s JSON response. Alternatively, it can be obtained from the Manage Organizations page in the admin console:
Login to the Zoho Books admin console. Click the drop down with organization’s name as the label and click Manage Organizations.
Now you’ll be able to find Organization IDs for each of your organizations.
HTTP Methods
Using GET method, you can get the list of resources or details of a particular instance of a resource. To get a list of contacts
$ curl https://books.zoho.com/api/v3/contacts?organization_id=10234695 -H 'Authorization: Zoho-authtoken ba4604e8e433g9c892e360d53463oec5'
To get the details of a contact referred to by a specified contact_id
$ curl https://books.zoho.com/api/v3/contacts/903000000000099?organization_id=10234695 -H 'Authorization: Zoho-authtoken ba4604e8e433g9c892e360d53463oec5'
Zoho Books API uses appropriate HTTP verbs for every action.
| Method | Description |
|---|---|
| GET | Used for retrieving resources. |
| POST | Used for creating resources and performing resource actions. |
| PUT | Used for updating resources. |
| DELETE | Used for deleting resources. |
Response
Response Structure
The response structure for the Books API follows the below format.
{ "code" : 0, "message" : "success", "invoice" : { "invoice_id" : "..." } }
Request Example
$ curl https://books.zoho.com/api/v3/invoices/7000000079426?organization_id=10234695 -H 'Authorization: Zoho-authtoken ba4604e8e433g9c892e360d53463oec5' -H 'Accept: application/pdf'
OR
$ curl https://books.zoho.com/api/v3/invoices/7000000079426?accept=pdf \ '&organization_id=10234695' -H 'Authorization: Zoho-authtoken ba4604e8e433g9c892e360d53463oec5'
Responses will be in the JSON format.
| Node Name | Description |
|---|---|
| code | Zoho Books error code. This will be zero for a success response and non-zero in case of an error. |
| message | Message for the invoked API. |
| resource name | Comprises the invoked API’s Data. |
Response Header Example
HTTP/1.1 200 OK Content-Disposition: attachment; filename="INV-384.pdf" Content-Type: application/pdf;charset=UTF-8
Other Formats
Certain APIs support csv and pdf formats as well for which the
required response format needs to be specified in the respective
request’s Accept header or accept query parameter.
Date
All timestamps are returned in the ISO 8601 format - YYYY-MM-DDThh:mm:ssTZD.
Example: 2016-06-11T17:38:06-0700
Errors
Request Example
$ curl https://books.zoho.com/api/v3/invoices/700000007942?organization_id=10234695 -H 'Authorization: Zoho-authtoken ba4604e8e433g9c892e360d53463oec5'
Response Example
HTTP/1.1 201 Successfully Created Content-Type: application/json;charset=UTF-8 { "code": 0, "message": "Successfully created." }
HTTP/1.1 404 Not Found Content-Type: application/json;charset=UTF-8 { "code": 1002, "message": "Invoice does not exist." }
HTTP/1.1 500 Internal error Content-Type: application/json;charset=UTF-8 { "code": 1000, "message": "Internal error" }
Zoho Books uses HTTP status codes to indicate success or failure of an API call. In general, status codes in the 2xx range means success, 4xx range means there was an error in the provided information, and those in the 5xx range indicate server side errors. Commonly used HTTP status codes are listed below.
HTTP Status Codes
| Status Code | Descriptions |
|---|---|
| 2xx | Success |
| 4xx | Bad request sent to server |
| 5xx | Server side error |
| Status Code | Description |
|---|---|
| 200 | SuccessThe request was successfully completed. |
| 201 | CreatedThe request was a success and one or more resources have been created. |
| 400 | Bad requestThe request cannot be performed. Usually because of malformed parameter or missing parameter. |
| 401 | Unauthorized (Invalid AuthToken)Request was rejected because of invalid AuthToken. |
| 403 | ForbiddenThe user does not have enough permission or possibly not an user of the respective organization to access the resource. |
| 404 | URL Not Found The URL you’ve sent is wrong. It’s possible that the resource you’ve requested has been moved to another URL. |
| 405 | Method Not AllowedThe requested resource does not support the HTTP method used. For example, requesting List of all customers API with PUT as the HTTP method. |
| 406 | Not AcceptableThe requested response type is not supported by the client. |
| 429 | Too many requests Too many requests within a certain time frame. To know more about api call limits, click here. |
| 500 | Server errorZoho Books server encountered an error which prevents it from fulfilling the request. Although this rarely happens, we recommend you to contact us at support@zohobooks.com if you receive this error. |
Pagination
Example
$ curl https://books.zoho.com/api/v3/contacts?page=2&per_page=25 { "code": 0, "message": "success", "contacts": [ {...}, {...} ], "page_context": { "page": 2, "per_page": 25, "has_more_page": false } }
Zoho Books provides APIs to retrieve lists of contacts, plans and
other resources - paginated to 200 items by default. The pagination
information will be included in the list API response under the node
name page_context.
- By default first page will be listed. For navigating through pages, use the
pageparameter. - The
per_pageparameter can be used to set the number of records that you want to receive in response.
API Call Limit
API calls are limited to provide better quality of service and availability to all the users. The limits on total calls are illustrated below:
- Paid Organization - 2500 API calls/day and 100 API calls/minute
- Free Organization - 1000 API calls/day and 100 API calls/minute
API Collection
To try out our API, you can use the Postman, a REST client. You can download our API collection and give it a swing. Just click the button below.
After importing the collection, you have to configure the environment. You can either do it manualy or simply import our sample environment file and follow the steps given below.
- Download the sample environment file.
- Replace the values for
domain_url, organization_id, authtoken.domain_url: books.zoho.comOrganization.Organization_ID: organization IDUser.Auth_Token: authtoken - In the Postman app, click the settings icon (cog icon) on the top-right and go to
Manage Environment - Click the
Import buttonand upload this updated sample file and complete the process
Contacts
The list of contacts created.
Example
{ "contact_name": "Bowman and Co", "company_name": "Bowman and Co", "first_name": "Will", "last_name": "Smith", "email": "willsmith@bowmanfurniture.com", "phone": "+1-925-921-9201", "facebook": "zoho", "twitter": "zoho", "billing_address": { "attention": "Mr.John", "address": "4900 Hopyard Rd", "street2": "Suite 310", "state_code": "CA", "city": "Pleasanton", "state": "CA", "zip": 94588, "country": "U.S.A", "fax": "+1-925-924-9600" }, "shipping_address": { "attention": "Mr.John", "address": "4900 Hopyard Rd", "street2": "Suite 310", "state_code": "CA", "city": "Pleasanton", "state": "CA", "zip": 94588, "country": "U.S.A", "fax": "+1-925-924-9600" }, "contact_persons": [ { "salutation": "Mr", "first_name": "Will", "last_name": "Smith", "email": "willsmith@bowmanfurniture.com", "phone": "+1-925-921-9201", "mobile": "+1-4054439562", "designation": "Sales Executive", "department": "Sales and Marketing", "skype": "Zoho", "is_primary_contact": true } ] }
Attribute
|
contact_name
string
Display Name of the contact. Max-length [200]
company_name
string
Company Name of the contact. Max-length [200]
first_name
string
Max-length [100]
last_name
string
Max-length [100]
email
string
Email address of the contact person.
phone
string
Search contacts by phone number of the contact person. Variants:
phone_startswith and phone_contains
facebook
string
Facebook profile account. max-length [100]
twitter
string
Twitter account. max-length [100]
language_code
string
language of a contact. allowed values
de,en,es,fr,it,ja,nl,pt,pt_br,sv,zh,en_gb
billing_address
object
Billing address of the contact.
attention
string
address
string
Max-length [500]
street2
string
state_code
string
city
string
City of the customer’s billing address.
state
string
State of the customer’s billing address.
zip
string
Zip code of the customer’s billing address.
country
string
Country of the customer’s billing address.
fax
string
Customer's fax number.
shipping_address
object
Customer's shipping address object.
attention
string
address
string
Max-length [500]
street2
string
state_code
string
city
string
City of the customer’s billing address.
state
string
State of the customer’s billing address.
zip
string
Zip code of the customer’s billing address.
country
string
Country of the customer’s billing address.
fax
string
Customer's fax number.
contact_persons
list
salutation
string
Salutation for the contact
first_name
string
Max-length [100]
last_name
string
Max-length [100]
email
string
Email address of the contact person.
phone
string
Search contacts by phone number of the contact person. Variants:
phone_startswith and phone_contains
mobile
string
Search contacts by mobile number of the contact person.
designation
string
Designation for the contact person.
department
string
Department for the contact person.
skype
string
Skype details for the contact person.
is_primary_contact
boolean
To mark contact person as primary for contact. Allowed value is
true only. |
Create a Contact
Create a contact with given information.
POST /contacts
Request Example
$ curl https://books.zoho.com/api/v3/contacts?organization_id=10234695 -H "Authorization: Zoho-authtoken ba4604e8e433g9c892e360d53463oec5" -H "Content-Type: application/json;charset=UTF-8" -d '{ "contact_name": "Bowman and Co", "company_name": "Bowman and Co", "website": "www.bowmanfurniture.com", "contact_type": "customer", "currency_id": 460000000000097, "payment_terms": 15, "payment_terms_label": "Net 15", "notes": "Payment option : Through check", "billing_address": { "attention": "Mr.John", "address": "4900 Hopyard Rd", "street2": "Suite 310", "state_code": "CA", "city": "Pleasanton", "state": "CA", "zip": 94588, "country": "U.S.A", "fax": "+1-925-924-9600" }, "shipping_address": { "attention": "Mr.John", "address": "4900 Hopyard Rd", "street2": "Suite 310", "state_code": "CA", "city": "Pleasanton", "state": "CA", "zip": 94588, "country": "U.S.A", "fax": "+1-925-924-9600" }, "contact_persons": [ { "salutation": "Mr", "first_name": "Will", "last_name": "Smith", "email": "willsmith@bowmanfurniture.com", "phone": "+1-925-921-9201", "mobile": "+1-4054439562", "designation": "Sales Executive", "department": "Sales and Marketing", "skype": "Zoho", "is_primary_contact": true } ], "default_templates": { "invoice_template_id": 460000000052069, "estimate_template_id": 460000000000179, "creditnote_template_id": 460000000000211, "purchaseorder_template_id": 460000000000213, "salesorder_template_id": 460000000000214, "retainerinvoice_template_id": 460000000000215, "paymentthankyou_template_id": 460000000000216, "retainerinvoice_paymentthankyou_template_id": 460000000000217, "invoice_email_template_id": 460000000052071, "estimate_email_template_id": 460000000052073, "creditnote_email_template_id": 460000000052075, "purchaseorder_email_template_id": 460000000000218, "salesorder_email_template_id": 460000000000219, "retainerinvoice_email_template_id": 460000000000220, "paymentthankyou_email_template_id": 460000000000221, "retainerinvoice_paymentthankyou_email_template_id": 460000000000222 }, "custom_fields": [ { "index": 1, "value": "GBGD078" } ], "place_of_contact": "TN", "gst_no": "22AAAAA0000A1Z5", "gst_treatment": "business_gst", "tax_exemption_id": 11149000000061054, "tax_authority_id": 11149000000061052, "tax_id": 11149000000061058, "is_taxable": true, "facebook": "zoho", "twitter": "zoho" }
Response Example
HTTP/1.1 201 Created Content-Type:application/json;charset=UTF-8 { "code": 0, "message": "The contact has been created", "contact": { "contact": { "contact_id": 460000000026049, "contact_name": "Bowman and Co", "company_name": "Bowman and Co", "has_transaction": true, "contact_type": "customer", "is_taxable": true, "tax_id": 11149000000061058, "tax_name": "CGST", "tax_percentage": 12, "tax_authority_id": 11149000000061052, "tax_exemption_id": 11149000000061054, "place_of_contact": "TN", "gst_no": "22AAAAA0000A1Z5", "gst_treatment": "business_gst", "is_linked_with_zohocrm": false, "website": "www.bowmanfurniture.com", "primary_contact_id": 460000000026051, "payment_terms": 15, "payment_terms_label": "Net 15", "currency_id": 460000000000097, "currency_code": "USD", "currency_symbol": "$", "outstanding_receivable_amount": 250, "outstanding_receivable_amount_bcy": 250, "unused_credits_receivable_amount": 1369.66, "unused_credits_receivable_amount_bcy": 1369.66, "status": "active", "payment_reminder_enabled": true, "custom_fields": [ { "index": 1, "value": "GBGD078", "label": "VAT ID" } ], "billing_address": { "attention": "Mr.John", "address": "4900 Hopyard Rd", "street2": "Suite 310", "state_code": "CA", "city": "Pleasanton", "state": "CA", "zip": 94588, "country": "U.S.A", "fax": "+1-925-924-9600" }, "shipping_address": { "attention": "Mr.John", "address": "4900 Hopyard Rd", "street2": "Suite 310", "state_code": "CA", "city": "Pleasanton", "state": "CA", "zip": 94588, "country": "U.S.A", "fax": "+1-925-924-9600" }, "facebook": "zoho", "twitter": "zoho", "contact_persons": [ { "salutation": "Mr", "first_name": "Will", "last_name": "Smith", "email": "willsmith@bowmanfurniture.com", "phone": "+1-925-921-9201", "mobile": "+1-4054439562", "designation": "Sales Executive", "department": "Sales and Marketing", "skype": "Zoho", "is_primary_contact": true } ], "default_templates": { "invoice_template_id": 460000000052069, "estimate_template_id": 460000000000179, "creditnote_template_id": 460000000000211, "purchaseorder_template_id": 460000000000213, "salesorder_template_id": 460000000000214, "retainerinvoice_template_id": 460000000000215, "paymentthankyou_template_id": 460000000000216, "retainerinvoice_paymentthankyou_template_id": 460000000000217, "invoice_email_template_id": 460000000052071, "estimate_email_template_id": 460000000052073, "creditnote_email_template_id": 460000000052075, "purchaseorder_email_template_id": 460000000000218, "salesorder_email_template_id": 460000000000219, "retainerinvoice_email_template_id": 460000000000220, "paymentthankyou_email_template_id": 460000000000221, "retainerinvoice_paymentthankyou_email_template_id": 460000000000222 }, "notes": "Payment option : Through check", "created_time": "2013-08-05T12:06:10+0530", "last_modified_time": "2013-10-07T18:24:51+0530" } } }
ARGUMENTS
|
contact_name
Required
Display Name of the contact. Max-length [200]
company_name
Optional
Company Name of the contact. Max-length [200]
website
Optional
Website of the contact.
language_code
Optional
language of a contact. allowed values
de,en,es,fr,it,ja,nl,pt,pt_br,sv,zh,en_gb
contact_type
Optional
Contact type of the contact
currency_id
Optional
Currency ID of the customer's currency.
payment_terms
Optional
Net payment term for the customer.
payment_terms_label
Optional
Label for the paymet due details.
notes
Optional
Commennts about the payment made by the contact.
billing_address
Optional
Billing address of the contact.
attention
Optional
address
Optional
Max-length [500]
street2
Optional
state_code
Optional
city
Optional
City of the customer’s billing address.
state
Optional
State of the customer’s billing address.
zip
Optional
Zip code of the customer’s billing address.
country
Optional
Country of the customer’s billing address.
fax
Optional
Customer's fax number.
shipping_address
Optional
Customer's shipping address object.
attention
Optional
address
Optional
Max-length [500]
street2
Optional
state_code
Optional
city
Optional
City of the customer’s billing address.
state
Optional
State of the customer’s billing address.
zip
Optional
Zip code of the customer’s billing address.
country
Optional
Country of the customer’s billing address.
fax
Optional
Customer's fax number.
contact_persons
Optional , default isContact persons of a contact.
salutation
Optional
Salutation for the contact
first_name
Optional
Max-length [100]
last_name
Optional
Max-length [100]
email
Optional
Email address of the contact person.
phone
Optional
Search contacts by phone number of the contact person. Variants:
phone_startswith and phone_contains
mobile
Optional
Search contacts by mobile number of the contact person.
designation
Optional
Designation for the contact person.
department
Optional
Department for the contact person.
skype
Optional
Skype details for the contact person.
is_primary_contact
Optional
To mark contact person as primary for contact. Allowed value is
true only.
default_templates
Optional
invoice_template_id
Optional
Default invoice template id used for this contact while creating invoice.
estimate_template_id
Optional
Default estimate template id used for this contact while creating estimate.
creditnote_template_id
Optional
Default credit note template id used for this contact while creating credit note.
purchaseorder_template_id
Optional
Default purchase order template id used for this contact while creating purchase order(for Vendors only).
salesorder_template_id
Optional
Default sales order template id used for this contact while creating sales order.
retainerinvoice_template_id
Optional
Default retainer invoice template id used for this contact while creating retainer invoice.
paymentthankyou_template_id
Optional
Default payment thankyou template id used for this contact while sending payment thankyou note.
retainerinvoice_paymentthankyou_template_id
Optional
Default retainer invoice paymnet
thankyou template id used for this contact while sending payment
thankyou note for retainer invoice.
invoice_email_template_id
Optional
Default invoice email template id used for this contact while sending invoices.
estimate_email_template_id
Optional
Default estimate email template id used for this contact while sending estimates.
creditnote_email_template_id
Optional
Default credit note email template id used for this contact while sending credit notes.
purchaseorder_email_template_id
Optional
Default purchase order template id used for this contact while creating purchase order(for Vendors only).
salesorder_email_template_id
Optional
Default sales order template id used for this contact while creating sales order.
retainerinvoice_email_template_id
Optional
Default retainer invoice template id used for this contact while creating retainer invoice.
paymentthankyou_email_template_id
Optional
Default payment thankyou template id used for this contact while sending payment thankyou note.
retainerinvoice_paymentthankyou_email_template_id
Optional
Default retainer invoice paymnet
thankyou template id used for this contact while sending payment
thankyou note for retainer invoice.
custom_fields
Optional
index
Optional
Index of the custom field. It can hold any value from 1 to 10.
value
Optional
Value of the custom field.
vat_reg_no
UK Edition and Avalara integration only
Optional
For UK Edition: VAT Registration number of a contact with VAT treatment as
eu_vat_registered. Length should be between 2 and 12 characters.(This node is only available for EU VAT registered contacts.)For Avalara: If you are doing sales in the European Union (EU) then provide VAT Registration Number of your customers here. This is used to calculate VAT for B2B sales, from Avalara.
country_code
UK Edition and Avalara integration only
Optional
For UK Edition: Two letter country code of a contact with VAT treatment as
eu_vat_registered.(This node is only available for EU VAT registered contacts.)For Avalara: Two letter country code for the customer country, if your customer is not in US. Refer [AvaTax Codes for Countries and States][2].
vat_treatment
UK edition only
Optional
VAT treatment of the contact.Allowed Values:
uk, eu_vat_not_registered, eu_vat_registered and non_eu.
place_of_contact
India Edition only.
Optional
Location of the contact. (This node
identifies the place of supply and source of supply when invoices/bills
are raised for the customer/vendor respectively. This is not applicable
for Overseas contacts)
gst_no
India Edition only.
Optional
15 digit GST identification number of the customer/vendor.
gst_treatment
India Edition only.
Optional
Choose whether the contact is GST registered/unregistered/consumer/overseas. Allowed values are
business_gst , business_none , overseas , consumer .
tax_authority_name
Optional
Enter tax authority name.
avatax_exempt_no
Avalara integration only
Optional
Exemption certificate number of the customer.
avatax_use_code
Avalara integration only
Optional
Used to group like customers for
exemption purposes. It is a custom value that links customers to a tax
rule. Select from Avalara [standard codes][1] or enter a custom code.
tax_exemption_id
US, Canada, Australia and India editions only
Optional
ID of the tax exemption.
tax_exemption_code
US, Canada, Australia and India editions only
Optional
Enter tax exemption code
tax_authority_id
US edition only
Optional
ID of the tax authority. Tax authority
depends on the location of the customer. For example, if the customer
is located in NY, then the tax authority is NY tax authority.
tax_id
India edition and US edition only
Optional
ID of the tax or tax group that can be collected from the contact. Tax can be given only if
is_taxable is true.
is_taxable
US, Canada, Australia, and India Editions only.
Optional
Boolean to track the taxability of the customer.
facebook
Optional
Facebook profile account. max-length [100]
twitter
Optional
Twitter account. max-length [100]
track_1099
US Edition Only
Optional
Boolean to track a contact for 1099 reporting.
tax_id_type
US Edition Only
Optional
Tax ID type of the contact, it can be SSN, ATIN, ITIN or EIN.
tax_id_value
US Edition Only
Optional
Tax ID of the contact.
|
Update a contact
Update an existing contact. To delete a contact person remove it from the contact_persons list.
PUT /contacts/{contact_id}
Request Example
$ curl https://books.zoho.com/api/v3/contacts/{contact_id}?organization_id=10234695 -H "Authorization: Zoho-authtoken ba4604e8e433g9c892e360d53463oec5" -H "Content-Type: application/json;charset=UTF-8" -d '{ "contact_name": "Bowman and Co", "company_name": "Bowman and Co", "payment_terms": 15, "payment_terms_label": "Net 15", "contact_type": "customer", "currency_id": 460000000000097, "website": "www.bowmanfurniture.com", "custom_fields": [ { "index": 1, "value": "GBGD078", "label": "VAT ID" } ], "billing_address": { "attention": "Mr.John", "address": "4900 Hopyard Rd", "street2": "Suite 310", "state_code": "CA", "city": "Pleasanton", "state": "CA", "zip": 94588, "country": "U.S.A", "fax": "+1-925-924-9600" }, "shipping_address": { "attention": "Mr.John", "address": "4900 Hopyard Rd", "street2": "Suite 310", "state_code": "CA", "city": "Pleasanton", "state": "CA", "zip": 94588, "country": "U.S.A", "fax": "+1-925-924-9600" }, "contact_persons": [ { "salutation": "Mr", "first_name": "Will", "last_name": "Smith", "email": "willsmith@bowmanfurniture.com", "phone": "+1-925-921-9201", "mobile": "+1-4054439562", "designation": "Sales Executive", "department": "Sales and Marketing", "skype": "Zoho", "is_primary_contact": true } ], "default_templates": { "invoice_template_id": 460000000052069, "estimate_template_id": 460000000000179, "creditnote_template_id": 460000000000211, "purchaseorder_template_id": 460000000000213, "salesorder_template_id": 460000000000214, "retainerinvoice_template_id": 460000000000215, "paymentthankyou_template_id": 460000000000216, "retainerinvoice_paymentthankyou_template_id": 460000000000217, "invoice_email_template_id": 460000000052071, "estimate_email_template_id": 460000000052073, "creditnote_email_template_id": 460000000052075, "purchaseorder_email_template_id": 460000000000218, "salesorder_email_template_id": 460000000000219, "retainerinvoice_email_template_id": 460000000000220, "paymentthankyou_email_template_id": 460000000000221, "retainerinvoice_paymentthankyou_email_template_id": 460000000000222 }, "notes": "Payment option : Through check", "place_of_contact": "TN", "gst_no": "22AAAAA0000A1Z5", "gst_treatment": "business_gst", "tax_exemption_id": 11149000000061054, "tax_authority_id": 11149000000061052, "tax_id": 11149000000061058, "is_taxable": true, "facebook": "zoho", "twitter": "zoho" }
Response Example
HTTP/1.1 200 OK Content-Type:application/json;charset=UTF-8 { "code": 0, "message": "Contact has been updated successfully", "contact": { "contact": { "contact_id": 460000000026049, "contact_name": "Bowman and Co", "company_name": "Bowman and Co", "has_transaction": true, "contact_type": "customer", "is_taxable": true, "tax_id": 11149000000061058, "tax_name": "CGST", "tax_percentage": 12, "tax_authority_id": 11149000000061052, "tax_exemption_id": 11149000000061054, "place_of_contact": "TN", "gst_no": "22AAAAA0000A1Z5", "gst_treatment": "business_gst", "is_linked_with_zohocrm": false, "website": "www.bowmanfurniture.com", "primary_contact_id": 460000000026051, "payment_terms": 15, "payment_terms_label": "Net 15", "currency_id": 460000000000097, "currency_code": "USD", "currency_symbol": "$", "outstanding_receivable_amount": 250, "outstanding_receivable_amount_bcy": 250, "unused_credits_receivable_amount": 1369.66, "unused_credits_receivable_amount_bcy": 1369.66, "status": "active", "payment_reminder_enabled": true, "custom_fields": [ { "index": 1, "value": "GBGD078", "label": "VAT ID" } ], "billing_address": { "attention": "Mr.John", "address": "4900 Hopyard Rd", "street2": "Suite 310", "state_code": "CA", "city": "Pleasanton", "state": "CA", "zip": 94588, "country": "U.S.A", "fax": "+1-925-924-9600" }, "shipping_address": { "attention": "Mr.John", "address": "4900 Hopyard Rd", "street2": "Suite 310", "state_code": "CA", "city": "Pleasanton", "state": "CA", "zip": 94588, "country": "U.S.A", "fax": "+1-925-924-9600" }, "facebook": "zoho", "twitter": "zoho", "contact_persons": [ { "salutation": "Mr", "first_name": "Will", "last_name": "Smith", "email": "willsmith@bowmanfurniture.com", "phone": "+1-925-921-9201", "mobile": "+1-4054439562", "designation": "Sales Executive", "department": "Sales and Marketing", "skype": "Zoho", "is_primary_contact": true } ], "default_templates": { "invoice_template_id": 460000000052069, "estimate_template_id": 460000000000179, "creditnote_template_id": 460000000000211, "purchaseorder_template_id": 460000000000213, "salesorder_template_id": 460000000000214, "retainerinvoice_template_id": 460000000000215, "paymentthankyou_template_id": 460000000000216, "retainerinvoice_paymentthankyou_template_id": 460000000000217, "invoice_email_template_id": 460000000052071, "estimate_email_template_id": 460000000052073, "creditnote_email_template_id": 460000000052075, "purchaseorder_email_template_id": 460000000000218, "salesorder_email_template_id": 460000000000219, "retainerinvoice_email_template_id": 460000000000220, "paymentthankyou_email_template_id": 460000000000221, "retainerinvoice_paymentthankyou_email_template_id": 460000000000222 }, "notes": "Payment option : Through check", "created_time": "2013-08-05T12:06:10+0530", "last_modified_time": "2013-10-07T18:24:51+0530" } } }
ARGUMENTS
|
contact_name
Required
Display Name of the contact. Max-length [200]
company_name
Optional
Company Name of the contact. Max-length [200]
payment_terms
Optional
Net payment term for the customer.
payment_terms_label
Optional
Label for the paymet due details.
contact_type
Optional
Contact type of the contact
currency_id
Optional
Currency ID of the customer's currency.
website
Optional
Website of the contact.
custom_fields
Optional
index
Optional
Index of the custom field. It can hold any value from 1 to 10.
value
Optional
Value of the custom field.
label
Optional
Label of the custom field.
billing_address
Optional
Billing address of the contact.
attention
Optional
address
Optional
Max-length [500]
street2
Optional
state_code
Optional
city
Optional
City of the customer’s billing address.
state
Optional
State of the customer’s billing address.
zip
Optional
Zip code of the customer’s billing address.
country
Optional
Country of the customer’s billing address.
fax
Optional
Customer's fax number.
shipping_address
Optional
Customer's shipping address object.
attention
Optional
address
Optional
Max-length [500]
street2
Optional
state_code
Optional
city
Optional
City of the customer’s billing address.
state
Optional
State of the customer’s billing address.
zip
Optional
Zip code of the customer’s billing address.
country
Optional
Country of the customer’s billing address.
fax
Optional
Customer's fax number.
contact_persons
Optional , default isContact persons of a contact.
salutation
Optional
Salutation for the contact
first_name
Optional
Max-length [100]
last_name
Optional
Max-length [100]
email
Optional
Email address of the contact person.
phone
Optional
Search contacts by phone number of the contact person. Variants:
phone_startswith and phone_contains
mobile
Optional
Search contacts by mobile number of the contact person.
designation
Optional
Designation for the contact person.
department
Optional
Department for the contact person.
skype
Optional
Skype details for the contact person.
is_primary_contact
Optional
To mark contact person as primary for contact. Allowed value is
true only.
default_templates
Optional
invoice_template_id
Optional
Default invoice template id used for this contact while creating invoice.
estimate_template_id
Optional
Default estimate template id used for this contact while creating estimate.
creditnote_template_id
Optional
Default credit note template id used for this contact while creating credit note.
purchaseorder_template_id
Optional
Default purchase order template id used for this contact while creating purchase order(for Vendors only).
salesorder_template_id
Optional
Default sales order template id used for this contact while creating sales order.
retainerinvoice_template_id
Optional
Default retainer invoice template id used for this contact while creating retainer invoice.
paymentthankyou_template_id
Optional
Default payment thankyou template id used for this contact while sending payment thankyou note.
retainerinvoice_paymentthankyou_template_id
Optional
Default retainer invoice paymnet
thankyou template id used for this contact while sending payment
thankyou note for retainer invoice.
invoice_email_template_id
Optional
Default invoice email template id used for this contact while sending invoices.
estimate_email_template_id
Optional
Default estimate email template id used for this contact while sending estimates.
creditnote_email_template_id
Optional
Default credit note email template id used for this contact while sending credit notes.
purchaseorder_email_template_id
Optional
Default purchase order template id used for this contact while creating purchase order(for Vendors only).
salesorder_email_template_id
Optional
Default sales order template id used for this contact while creating sales order.
retainerinvoice_email_template_id
Optional
Default retainer invoice template id used for this contact while creating retainer invoice.
paymentthankyou_email_template_id
Optional
Default payment thankyou template id used for this contact while sending payment thankyou note.
retainerinvoice_paymentthankyou_email_template_id
Optional
Default retainer invoice paymnet
thankyou template id used for this contact while sending payment
thankyou note for retainer invoice.
notes
Optional
Commennts about the payment made by the contact.
vat_reg_no
UK Edition and Avalara integration only
Optional
For UK Edition: VAT Registration number of a contact with VAT treatment as
eu_vat_registered. Length should be between 2 and 12 characters.(This node is only available for EU VAT registered contacts.)For Avalara: If you are doing sales in the European Union (EU) then provide VAT Registration Number of your customers here. This is used to calculate VAT for B2B sales, from Avalara.
country_code
UK Edition and Avalara integration only
Optional
For UK Edition: Two letter country code of a contact with VAT treatment as
eu_vat_registered.(This node is only available for EU VAT registered contacts.)For Avalara: Two letter country code for the customer country, if your customer is not in US. Refer [AvaTax Codes for Countries and States][2].
vat_treatment
UK edition only
Optional
VAT treatment of the contact.Allowed Values:
uk, eu_vat_not_registered, eu_vat_registered and non_eu.
place_of_contact
India Edition only.
Optional
Location of the contact. (This node
identifies the place of supply and source of supply when invoices/bills
are raised for the customer/vendor respectively. This is not applicable
for Overseas contacts)
gst_no
India Edition only.
Optional
15 digit GST identification number of the customer/vendor.
gst_treatment
India Edition only.
Optional
Choose whether the contact is GST registered/unregistered/consumer/overseas. Allowed values are
business_gst , business_none , overseas , consumer .
tax_authority_name
Optional
Enter tax authority name.
avatax_exempt_no
Avalara integration only
Optional
Exemption certificate number of the customer.
avatax_use_code
Avalara integration only
Optional
Used to group like customers for
exemption purposes. It is a custom value that links customers to a tax
rule. Select from Avalara [standard codes][1] or enter a custom code.
tax_exemption_id
US, Canada, Australia and India editions only
Optional
ID of the tax exemption.
tax_exemption_code
US, Canada, Australia and India editions only
Optional
Enter tax exemption code
tax_authority_id
US edition only
Optional
ID of the tax authority. Tax authority
depends on the location of the customer. For example, if the customer
is located in NY, then the tax authority is NY tax authority.
tax_id
India edition and US edition only
Optional
ID of the tax or tax group that can be collected from the contact. Tax can be given only if
is_taxable is true.
is_taxable
US, Canada, Australia, and India Editions only.
Optional
Boolean to track the taxability of the customer.
facebook
Optional
Facebook profile account. max-length [100]
twitter
Optional
Twitter account. max-length [100]
track_1099
US Edition Only
Optional
Boolean to track a contact for 1099 reporting.
tax_id_type
US Edition Only
Optional
Tax ID type of the contact, it can be SSN, ATIN, ITIN or EIN.
tax_id_value
US Edition Only
Optional
Tax ID of the contact.
|
List contacts
List all contacts with pagination.
GET /contacts
Request Example
$ curl https://books.zoho.com/api/v3/contacts?organization_id=10234695 -H "Authorization: Zoho-authtoken ba4604e8e433g9c892e360d53463oec5" -H "Content-Type: application/json;charset=UTF-8"
Response Example
HTTP/1.1 200 OK Content-Type:application/json;charset=UTF-8 { "code": 0, "message": "success", "contacts": [ { "contacts": [ { "contact_id": 460000000026049, "contact_name": "Bowman and Co", "company_name": "Bowman and Co", "contact_type": "customer", "status": "active", "payment_terms": 15, "payment_terms_label": "Net 15", "currency_id": 460000000000097, "currency_code": "USD", "outstanding_receivable_amount": 250, "unused_credits_receivable_amount": 1369.66, "first_name": "Will", "last_name": "Smith", "email": "willsmith@bowmanfurniture.com", "phone": "+1-925-921-9201", "mobile": "+1-4054439562", "created_time": "2013-08-05T12:06:10+0530", "last_modified_time": "2013-10-07T18:24:51+0530" } ], "page_context": { "page": 1, "per_page": 200, "has_more_page": false, "applied_filter": "Status.All", "sort_column": "contact_name", "sort_order": "D" } }, {...}, {...} ] }
Query Params
|
contact_name
Optional
Search contacts by contact name. Max-length [100] Variants:
contact_name_startswith and contact_name_contains. Max-length [100]
company_name
Optional
Search contacts by company name. Max-length [100] Variants:
company_name_startswith and company_name_contains
first_name
Optional
Search contacts by first name of the contact person. Max-length [100] Variants:
first_name_startswith and first_name_contains
last_name
Optional
Search contacts by last name of the contact person. Max-length [100] Variants:
last_name_startswith and last_name_contains
address
Optional
Search contacts by any of the address fields. Max-length [100] Variants:
address_startswith and address_contains
email
Optional
Search contacts by email of the contact person. Max-length [100] Variants:
email_startswith and email_contains
phone
Optional
Search contacts by phone number of the contact person. Max-length [100] Variants:
phone_startswith and phone_contains
filter_by
Optional
Filter contacts by status. Allowed Values:
Status.All, Status.Active, Status.Inactive, Status.Duplicate and Status.Crm
search_text
Optional
Search contacts by contact name or notes. Max-length [100]
sort_column
Optional
Sort contacts. Allowed Values:
contact_name, first_name, last_name, email, outstanding_receivable_amount, created_time and last_modified_time |
Get contact
Get details of a contact.
GET /contacts/{:contacts_id}
Request Example
$ curl https://books.zoho.com/api/v3/contacts/{:contacts_id}?organization_id=10234695 -H "Authorization: Zoho-authtoken ba4604e8e433g9c892e360d53463oec5" -H "Content-Type: application/json;charset=UTF-8"
Response Example
HTTP/1.1 200 OK Content-Type:application/json;charset=UTF-8 { "code": 0, "message": "success", "contact": { "contact": { "contact_id": 460000000026049, "contact_name": "Bowman and Co", "company_name": "Bowman and Co", "has_transaction": true, "contact_type": "customer", "is_taxable": true, "tax_id": 11149000000061058, "tax_name": "CGST", "tax_percentage": 12, "tax_authority_id": 11149000000061052, "tax_exemption_id": 11149000000061054, "place_of_contact": "TN", "gst_no": "22AAAAA0000A1Z5", "gst_treatment": "business_gst", "is_linked_with_zohocrm": false, "website": "www.bowmanfurniture.com", "primary_contact_id": 460000000026051, "payment_terms": 15, "payment_terms_label": "Net 15", "currency_id": 460000000000097, "currency_code": "USD", "currency_symbol": "$", "outstanding_receivable_amount": 250, "outstanding_receivable_amount_bcy": 250, "unused_credits_receivable_amount": 1369.66, "unused_credits_receivable_amount_bcy": 1369.66, "status": "active", "facebook": "zoho", "twitter": "zoho", "payment_reminder_enabled": true, "custom_fields": [ { "index": 1, "value": "GBGD078", "label": "VAT ID" } ], "billing_address": { "attention": "Mr.John", "address": "4900 Hopyard Rd", "street2": "Suite 310", "state_code": "CA", "city": "Pleasanton", "state": "CA", "zip": 94588, "country": "U.S.A", "fax": "+1-925-924-9600" }, "shipping_address": { "attention": "Mr.John", "address": "4900 Hopyard Rd", "street2": "Suite 310", "state_code": "CA", "city": "Pleasanton", "state": "CA", "zip": 94588, "country": "U.S.A", "fax": "+1-925-924-9600" }, "contact_persons": [ { "salutation": "Mr", "first_name": "Will", "last_name": "Smith", "email": "willsmith@bowmanfurniture.com", "phone": "+1-925-921-9201", "mobile": "+1-4054439562", "designation": "Sales Executive", "department": "Sales and Marketing", "skype": "Zoho", "is_primary_contact": true } ], "default_templates": { "invoice_template_id": 460000000052069, "estimate_template_id": 460000000000179, "creditnote_template_id": 460000000000211, "purchaseorder_template_id": 460000000000213, "salesorder_template_id": 460000000000214, "retainerinvoice_template_id": 460000000000215, "paymentthankyou_template_id": 460000000000216, "retainerinvoice_paymentthankyou_template_id": 460000000000217, "invoice_email_template_id": 460000000052071, "estimate_email_template_id": 460000000052073, "creditnote_email_template_id": 460000000052075, "purchaseorder_email_template_id": 460000000000218, "salesorder_email_template_id": 460000000000219, "retainerinvoice_email_template_id": 460000000000220, "paymentthankyou_email_template_id": 460000000000221, "retainerinvoice_paymentthankyou_email_template_id": 460000000000222 }, "notes": "Payment option : Through check", "created_time": "2013-08-05T12:06:10+0530", "last_modified_time": "2013-10-07T18:24:51+0530" } } }
Delete a contact
Delete an existing contact.
DELETE /contacts/{:contact_id}
Request Example
$ curl https://books.zoho.com/api/v3/contacts/{:contact_id}?organization_id=10234695 -H "Authorization: Zoho-authtoken ba4604e8e433g9c892e360d53463oec5" -H "Content-Type: application/json;charset=UTF-8"
Response Example
HTTP/1.1 200 OK Content-Type:application/json;charset=UTF-8 { "code": 0, "message": "The contact has been deleted." }
Mark as active
Mark a contact as active.
POST /contact/{:contact_id}/active
Request Example
$ curl https://books.zoho.com/api/v3/contact/{:contact_id}/active?organization_id=10234695 -H "Authorization: Zoho-authtoken ba4604e8e433g9c892e360d53463oec5" -H "Content-Type: application/json;charset=UTF-8"
Response Example
HTTP/1.1 200 OK Content-Type:application/json;charset=UTF-8 { "code": 0, "message": "The contact has been marked as active." }
Mark as Inactive
Mark a contact as inactive.
POST /contacts/{:contact_id}/inactive
Request Example
$ curl https://books.zoho.com/api/v3/contacts/{:contact_id}/inactive?organization_id=10234695 -H "Authorization: Zoho-authtoken ba4604e8e433g9c892e360d53463oec5" -H "Content-Type: application/json;charset=UTF-8"
Response Example
HTTP/1.1 200 OK Content-Type:application/json;charset=UTF-8 { "code": 0, "message": "The contact has been marked as inactive." }
Enable portal access
Enable portal access for a contact
POST /contacts/{:contact_id}/portal/enable
Request Example
$ curl https://books.zoho.com/api/v3/contacts/{:contact_id}/portal/enable?organization_id=10234695 -H "Authorization: Zoho-authtoken ba4604e8e433g9c892e360d53463oec5" -H "Content-Type: application/json;charset=UTF-8" -d '{ "contact_persons": [ { "contact_person_id": 460000000026051 } ] }
Response Example
HTTP/1.1 200 OK Content-Type:application/json;charset=UTF-8 { "code": 0, "message": "Client Portal preferences have been updated" }
ARGUMENTS
|
contact_persons
Required
contact_person_id
Optional
The id of the contact person
|
Enable payment reminders
Enable automated payment reminders for a contact.
POST /contacts/{:contact_id}/paymentreminder/enable
Request Example
$ curl https://books.zoho.com/api/v3/contacts/{:contact_id}/paymentreminder/enable?organization_id=10234695 -H "Authorization: Zoho-authtoken ba4604e8e433g9c892e360d53463oec5" -H "Content-Type: application/json;charset=UTF-8"
Response Example
HTTP/1.1 200 OK Content-Type:application/json;charset=UTF-8 { "code": 0, "message": "All reminders associated with this contact have been enabled." }
Disable payment reminders
Disable automated payment reminders for a contact.
POST /contacts/{:contact_id}/paymentreminder/disable
Request Example
$ curl https://books.zoho.com/api/v3/contacts/{:contact_id}/paymentreminder/disable?organization_id=10234695 -H "Authorization: Zoho-authtoken ba4604e8e433g9c892e360d53463oec5" -H "Content-Type: application/json;charset=UTF-8"
Response Example
HTTP/1.1 200 OK Content-Type:application/json;charset=UTF-8 { "code": 0, "message": "All reminders associated with this contact have been stopped." }
Email statement
Email statement to the contact. If JSONString is not inputted, mail will be sent with the default mail content.
POST /contacts/{:contact_id}/statements/email
Request Example
$ curl https://books.zoho.com/api/v3/contacts/{:contact_id}/statements/email?organization_id=10234695 -H "Authorization: Zoho-authtoken ba4604e8e433g9c892e360d53463oec5" -H "Content-Type: application/json;charset=UTF-8" -d '{ "send_from_org_email_id": true, "to_mail_ids": [ "willsmith@bowmanfurniture.com" ], "cc_mail_ids": [ "peterparker@bowmanfurniture.com" ], "subject": "Statement of transactions with Zillium Inc", "body": "Dear Customer, <br/>We have attached with this email a list of all your transactions with us for the period 01 Sep 2013 to 30 Sep 2013. You can write to us or call us if you need any assistance or clarifications. <br/>Thanks for your business.<br/>Regards<br/>Zillium Inc" }
Response Example
HTTP/1.1 200 OK Content-Type:application/json;charset=UTF-8 { "code": 0, "message": "Statement has been sent to the customer." }
ARGUMENTS
|
send_from_org_email_id
Optional
Boolean to trigger the email from the organization's email address
to_mail_ids
Required
Array of email address of the recipients.
cc_mail_ids
Optional
Array of email address of the recipients to be cced.
subject
Required
Subject of an email has to be sent. Max-length [1000]
body
Required
Body of an email has to be sent. Max-length [5000]
|
Query Params
|
start_date
Optional
If start_date and end_date are not given, current month's statement will be sent to contact. Date format [yyyy-mm-dd]
end_date
Optional
End date for the statement. Date format [yyyy-mm-dd]
multipart_or_formdata
Optional
Files to be attached along with the statement.
|
Get Statement mail content
Get the statement mail content.
GET /contacts/{:contact_id}/statements/email
Request Example
$ curl https://books.zoho.com/api/v3/contacts/{:contact_id}/statements/email?organization_id=10234695 -H "Authorization: Zoho-authtoken ba4604e8e433g9c892e360d53463oec5" -H "Content-Type: application/json;charset=UTF-8"
Response Example
HTTP/1.1 200 OK Content-Type:application/json;charset=UTF-8 { "code": 0, "message": "success", "data": { "body": "Dear Customer, <br/>We have attached with this email a list of all your transactions with us for the period 01 Sep 2013 to 30 Sep 2013. You can write to us or call us if you need any assistance or clarifications. <br/>Thanks for your business.<br/>Regards<br/>Zillium Inc", "subject": "Statement of transactions with Zillium Inc", "to_contacts": [ { "first_name": "Will", "selected": true, "phone": "+1-925-921-9201", "email": "willsmith@bowmanfurniture.com", "contact_person_id": 460000000026051, "last_name": "Smith", "salutation": "Mr", "mobile": "+1-4054439562" } ], "file_name": "statement_BowmanandCo.pdf", "from_emails": [ { "user_name": "John Smith", "selected": true, "email": "willsmith@bowmanfurniture.com" } ], "contact_id": 460000000026049 } }
Query Params
|
start_date
Optional
If start_date and end_date are not given, current month's statement will be sent to contact. Date format [yyyy-mm-dd]
end_date
Optional
End date for the statement. Date format [yyyy-mm-dd]
|
Email contact
Send email to contact.
POST /contacts/{:contact_id}/email
Request Example
$ curl https://books.zoho.com/api/v3/contacts/{:contact_id}/email?organization_id=10234695 -H "Authorization: Zoho-authtoken ba4604e8e433g9c892e360d53463oec5" -H "Content-Type: application/json;charset=UTF-8" -d '{ "to_mail_ids": [ "willsmith@bowmanfurniture.com" ], "subject": "Welcome to Zillium Inc .", "body": "Dear Customer, <br/>We have attached with this email a list of all your transactions with us for the period 01 Sep 2013 to 30 Sep 2013. You can write to us or call us if you need any assistance or clarifications. <br/>Thanks for your business.<br/>Regards<br/>Zillium Inc" }
Response Example
HTTP/1.1 200 OK Content-Type:application/json;charset=UTF-8 { "code": 0, "message": "Email has been sent." }
ARGUMENTS
|
to_mail_ids
Required
Array of email address of the recipients.
subject
Required
Subject of an email has to be sent. Max-length [1000]
body
Required
Body of an email has to be sent. Max-length [5000]
attachments
Optional
Files to be attached to the email. It has to be sent in multipart/formdata
|
Query Params
|
send_customer_statement
Optional
Send customer statement pdf with email.
|
List Comments
List recent activities of a contact.
GET /contacts/{:contact_id}/comments
Request Example
$ curl https://books.zoho.com/api/v3/contacts/{:contact_id}/comments?organization_id=10234695 -H "Authorization: Zoho-authtoken ba4604e8e433g9c892e360d53463oec5" -H "Content-Type: application/json;charset=UTF-8"
Response Example
HTTP/1.1 200 OK Content-Type:application/json;charset=UTF-8 { "code": 0, "message": "success", "contact_comments": [ { "comment_id": 460000000053131, "contact_id": 460000000026049, "contact_name": "Bowman and Co", "description": "", "commented_by_id": 460000000024003, "commented_by": "John David", "date": "2013-11-19", "date_description": "4 days ago", "time": "6:03 PM", "transaction_id": 460000000053123, "transaction_type": "customer_payment", "is_entity_deleted": false, "operation_type": "added" } ], "page_context": { "page": 1, "per_page": 200, "has_more_page": false, "applied_filter": "Status.All", "sort_column": "contact_name", "sort_order": "D" } }
List Refunds
List the refund history of a contact.
GET /contacts/{:contact_id}/refunds
Request Example
$ curl https://books.zoho.com/api/v3/contacts/{:contact_id}/refunds?organization_id=10234695 -H "Authorization: Zoho-authtoken ba4604e8e433g9c892e360d53463oec5" -H "Content-Type: application/json;charset=UTF-8"
Response Example
HTTP/1.1 200 OK Content-Type:application/json;charset=UTF-8 { "code": 0, "message": "success", "creditnote_refunds": [ { "creditnote_refund_id": 982000000567158, "creditnote_id": 982000000567134, "date": "2013-11-19", "refund_mode": "cash", "reference_number": 782364, "creditnote_number": "CN-00001", "customer_name": "Bowman & Co", "description": "", "amount_bcy": 57.15, "amount_fcy": 57.15 } ], "page_context": { "page": 1, "per_page": 200, "has_more_page": false, "report_name": "Credit Notes Refund", "sort_column": "contact_name", "sort_order": "D" } }
Track 1099
Track a contact for 1099 reporting: (Note: This API is only available when the organization's country is U.S.A).
POST /contacts/{:contact_id}/track1099
Request Example
$ curl https://books.zoho.com/api/v3/contacts/{:contact_id}/track1099?organization_id=10234695 -H "Authorization: Zoho-authtoken ba4604e8e433g9c892e360d53463oec5" -H "Content-Type: application/json;charset=UTF-8"
Response Example
HTTP/1.1 200 OK Content-Type:application/json;charset=UTF-8 { "code": 0, "message": "1099 tracking is enabled." }
Untrack 1099
Use this API to stop tracking payments to a vendor for 1099 reporting. (Note: This API is only available when the organization's country is U.S.A).
POST /contacts/{:contact_id}/untrack1099
Request Example
$ curl https://books.zoho.com/api/v3/contacts/{:contact_id}/untrack1099?organization_id=10234695 -H "Authorization: Zoho-authtoken ba4604e8e433g9c892e360d53463oec5" -H "Content-Type: application/json;charset=UTF-8"
Response Example
HTTP/1.1 200 OK Content-Type:application/json;charset=UTF-8 { "code": 0, "message": "1099 tracking is disabled." }
Contact-Persons
The list of contacts created.
Example
{ "contact_id": 460000000026049, "first_name": "Will", "last_name": "Smith", "email": "willsmith@bowmanfurniture.com", "skype": "zoho", "designation": "Sales Engineer", "department": "Sales" }
Attribute
|
contact_id
string
Contact id of the contact
first_name
string
First name of the contact person. Max-length [100]
last_name
string
Last name of the contact person. Max-length [100]
email
string
Email address of the contact person. Max-length [100]
skype
string
skype address. Max-length [50]
designation
string
designation of a person. Max-length [50]
department
string
department on which a person belongs. Max-length [50]
|
Create a contact person
Create a contact person for contact.
POST /contacts/contactpersons
Request Example
$ curl https://books.zoho.com/api/v3/contacts/contactpersons?organization_id=10234695 -H "Authorization: Zoho-authtoken ba4604e8e433g9c892e360d53463oec5" -H "Content-Type: application/json;charset=UTF-8" -d '{ "contact_id": 460000000026049, "salutation": "Mr", "first_name": "Will", "last_name": "Smith", "email": "willsmith@bowmanfurniture.com", "phone": "+1-925-921-9201", "mobile": "+1-4054439562", "skype": "zoho", "designation": "Sales Engineer", "department": "Sales", "enable_portal": true }
Response Example
HTTP/1.1 201 Created Content-Type:application/json;charset=UTF-8 { "code": 0, "message": "The contactperson has been Created", "contact_person": { "contact_person": [ { "contact_id": 460000000026049, "contact_person_id": 460000000026051, "salutation": "Mr", "first_name": "Will", "last_name": "Smith", "email": "willsmith@bowmanfurniture.com", "phone": "+1-925-921-9201", "mobile": "+1-4054439562", "is_primary_contact": true, "skype": "zoho", "designation": "Sales Engineer", "department": "Sales", "is_added_in_portal": true } ] } }
ARGUMENTS
|
contact_id
Optional
Contact id of the contact
salutation
Optional
Salutation for the contact. Max-length [25]
first_name
Required
First name of the contact person. Max-length [100]
last_name
Optional
Last name of the contact person. Max-length [100]
email
Optional
Email address of the contact person. Max-length [100]
phone
Optional
Max-length [50]
mobile
Optional
Max-length [50]
skype
Optional
skype address. Max-length [50]
designation
Optional
designation of a person. Max-length [50]
department
Optional
department on which a person belongs. Max-length [50]
enable_portal
Optional
option to enable the portal access. allowed values
true,false |
Update a contact person
Update an existing contact person.
PUT /contacts/contactpersons/{:contact_person_id}
Request Example
$ curl https://books.zoho.com/api/v3/contacts/contactpersons/{:contact_person_id}?organization_id=10234695 -H "Authorization: Zoho-authtoken ba4604e8e433g9c892e360d53463oec5" -H "Content-Type: application/json;charset=UTF-8" -d '{ "contact_id": 460000000026049, "salutation": "Mr", "first_name": "Will", "last_name": "Smith", "email": "willsmith@bowmanfurniture.com", "phone": "+1-925-921-9201", "mobile": "+1-4054439562", "skype": "zoho", "designation": "Sales Engineer", "department": "Sales", "enable_portal": true, "is_primary_contact": true }
Response Example
HTTP/1.1 200 OK Content-Type:application/json;charset=UTF-8 { "code": 0, "message": "The contactperson details has been updated.", "contact_person": { "contact_person": [ { "contact_id": 460000000026049, "contact_person_id": 460000000026051, "salutation": "Mr", "first_name": "Will", "last_name": "Smith", "email": "willsmith@bowmanfurniture.com", "phone": "+1-925-921-9201", "mobile": "+1-4054439562", "is_primary_contact": true, "skype": "zoho", "designation": "Sales Engineer", "department": "Sales", "is_added_in_portal": true } ] } }
ARGUMENTS
|
contact_id
Required
Contact id of the contact
salutation
Optional
Salutation for the contact. Max-length [25]
first_name
Required
First name of the contact person. Max-length [100]
last_name
Optional
Last name of the contact person. Max-length [100]
email
Optional
Email address of the contact person. Max-length [100]
phone
Optional
Max-length [50]
mobile
Optional
Max-length [50]
skype
Optional
skype address. Max-length [50]
designation
Optional
designation of a person. Max-length [50]
department
Optional
department on which a person belongs. Max-length [50]
enable_portal
Optional
option to enable the portal access. allowed values
true,false
is_primary_contact
Optional
To mark contact person as primary for contact
|
List contact persons
List all contacts with pagination.
GET /contacts/{:contact_id}/contactpersons
Request Example
$ curl https://books.zoho.com/api/v3/contacts/{:contact_id}/contactpersons?organization_id=10234695 -H "Authorization: Zoho-authtoken ba4604e8e433g9c892e360d53463oec5" -H "Content-Type: application/json;charset=UTF-8"
Response Example
HTTP/1.1 200 OK Content-Type:application/json;charset=UTF-8 { "code": 0, "message": "success", "contact_persons": [ { "contact_persons": [ { "contact_person_id": 460000000026051, "salutation": "Mr", "first_name": "Will", "last_name": "Smith", "email": "willsmith@bowmanfurniture.com", "phone": "+1-925-921-9201", "mobile": "+1-4054439562", "is_primary_contact": true, "skype": "zoho", "designation": "Sales Engineer", "department": "Sales", "is_added_in_portal": true } ], "page_context": { "page": 1, "per_page": 200, "has_more_page": false, "sort_column": "contact_person_id", "sort_order": "A" } }, {...}, {...} ] }
Get a contact person
Get the contact person details.
GET /contacts/{:contact_id}/contactpersons/{:contact_person_id}
Request Example
$ curl https://books.zoho.com/api/v3/contacts/{:contact_id}/contactpersons/{:contact_person_id}?organization_id=10234695 -H "Authorization: Zoho-authtoken ba4604e8e433g9c892e360d53463oec5" -H "Content-Type: application/json;charset=UTF-8"
Response Example
HTTP/1.1 200 OK Content-Type:application/json;charset=UTF-8 { "code": 0, "message": "success", "contact_person": { "contact_person": { "contact_id": 460000000026049, "contact_person_id": 460000000026051, "salutation": "Mr", "first_name": "Will", "last_name": "Smith", "email": "willsmith@bowmanfurniture.com", "phone": "+1-925-921-9201", "mobile": "+1-4054439562", "is_primary_contact": true, "skype": "zoho", "designation": "Sales Engineer", "department": "Sales", "is_added_in_portal": true } } }
Delete a contact person
Delete an existing contact person.
DELETE /contacts/contactpersons/{:contact_person_id}
Request Example
$ curl https://books.zoho.com/api/v3/contacts/contactpersons/{:contact_person_id}?organization_id=10234695 -H "Authorization: Zoho-authtoken ba4604e8e433g9c892e360d53463oec5" -H "Content-Type: application/json;charset=UTF-8"
Response Example
HTTP/1.1 200 OK Content-Type:application/json;charset=UTF-8 { "code": 0, "message": "The contact person has been deleted." }
Mark as primary contact person
Mark a contact person as primary for the contact.
POST /contacts/contactpersons/{:contact_person_id}/primary
Request Example
$ curl https://books.zoho.com/api/v3/contacts/contactpersons/{:contact_person_id}/primary?organization_id=10234695 -H "Authorization: Zoho-authtoken ba4604e8e433g9c892e360d53463oec5" -H "Content-Type: application/json;charset=UTF-8"
Response Example
HTTP/1.1 200 OK Content-Type:application/json;charset=UTF-8 { "code": 0, "message": "This contact person has been marked as your primary contact person." }
Estimates
An estimate is a quote or a proposal for the products you sell or the services you render to your clients to take your business forward.
Example
{ "estimates": [ { "estimate_id": 982000000567011, "customer_name": "Bowman & Co", "customer_id": 982000000567001, "status": "draft", "estimate_number": "EST-00002", "reference_number": "QRT-12346", "date": "2013-11-18", "currency_id": 982000000000190, "currency_code": "USD", "total": 40.6, "created_time": "2013-11-18T02:17:40-0800", "accepted_date": " ", "declined_date": " ", "expiry_date": "2013-11-30" } ], "page_context": [ { "page": 1, "per_page": 200, "has_more_page": false, "report_name": "Estimates", "applied_filter": "Status.All", "sort_column": "created_time", "sort_order": "D" } ] }
Attribute
|
estimates
list
The list of all estimates
estimate_id
string
The unique id of a particular estimate
customer_name
string
Search estimates by customer name.Variants
customer_name_startswith and customer_name_contains
customer_id
string
Search estimates by customer id..
status
string
Search estimates by status.Allowed Values
draft, sent, invoiced , accepted, declined and expired
estimate_number
string
Search estimates by estimate number.Variants
estimate_number_startswith and estimate_number_contains
reference_number
string
Search estimates by reference number.Variants
reference_number_startswith and reference_number_contains
date
string
Search estimates by estimate date.Variants
date_start, date_end, date_before and date_after
currency_id
string
The id of the customer
currency_code
string
Currency code of the currency in which
the customer wants to pay. If currency_code is not specified here, the
currency chosen in your Zoho Subscriptions organization will be used for
billing. currency_id and currency_symbol are set automatically in
accordance to the currency_code.
total
double
Search estimates by estimate total.Variants
total_less_than, total_less_equals, total_greater_than and total_greater_equals
created_time
string
The time of creation of the estimates
accepted_date
string
The date of acceptance of the estimates
declined_date
string
The date of declination of the estimates
expiry_date
string
The date of expiration of the estimates
page_context
list
The context of a particular page.
page
integer
Number of pages
per_page
integer
Per page values
has_more_page
boolean
Check if has more pages
report_name
string
The report name
applied_filter
string
The filer applied for sorting
sort_column
string
Sort estimates. Allowed Values
customer_name, estimate_number, date, total and created_time
sort_order
string
The order for sorting
|
Create an Estimate
Create an estimate for your customer.
POST /estimates
Request Example
$ curl https://books.zoho.com/api/v3/estimates?organization_id=10234695 -H "Authorization: Zoho-authtoken ba4604e8e433g9c892e360d53463oec5" -H "Content-Type: application/json;charset=UTF-8" -d '{ "customer_id": 982000000567001, "template_id": 982000000000143, "place_of_supply": "TN", "gst_treatment": "business_gst", "gst_no": "22AAAAA0000A1Z5", "estimate_number": "EST-00002", "reference_number": "QRT-12346", "date": "2013-11-18", "expiry_date": "2013-11-30", "exchange_rate": 1, "discount": 0, "is_discount_before_tax": true, "discount_type": "item_level", "is_inclusive_tax": false, "custom_body": " ", "custom_subject": " ", "salesperson_name": "Will smith", "custom_fields": [ { "index": 1, "value": "15 Dec 2013" } ], "line_items": [ { "item_id": " ", "line_item_id": 982000000567021, "name": "Hard Drive", "description": "500GB, USB 2.0 interface 1400 rpm, protective hard case.", "product_type": "goods", "hsn_or_sac": 80540, "item_order": 1, "bcy_rate": 120, "rate": 120, "quantity": 1, "unit": " ", "discount_amount": 0, "discount": 0, "tax_id": 982000000557028, "tax_name": "VAT", "tax_type": "tax", "tax_percentage": 12.5, "item_total": 120 } ], "notes": "Looking forward for your business.", "terms": "Terms & Conditions apply", "shipping_charge": 0, "adjustment": 0, "adjustment_description": " ", "tax_id": 982000000557028, "tax_exemption_id": 11149000000061054, "tax_authority_id": 11149000000061052, "item_id": " ", "line_item_id": 982000000567021, "name": "Hard Drive", "description": "500GB, USB 2.0 interface 1400 rpm, protective hard case.", "rate": 120, "unit": " ", "quantity": 1 }
Response Example
HTTP/1.1 201 Created Content-Type:application/json;charset=UTF-8 { "code": 0, "message": "The estimate has been created", "estimate": { "estimate": { "estimate_id": 982000000567011, "estimate_number": "EST-00002", "date": "2013-11-18", "reference_number": "QRT-12346", "is_pre_gst": false, "place_of_supply": "TN", "gst_no": "22AAAAA0000A1Z5", "gst_treatment": "business_gst", "status": "draft", "customer_id": 982000000567001, "customer_name": "Bowman & Co", "currency_id": 982000000000190, "currency_code": "USD", "exchange_rate": 1, "expiry_date": "2013-11-30", "discount": 0, "is_discount_before_tax": true, "discount_type": "item_level", "is_inclusive_tax": false, "line_items": [ { "item_id": " ", "line_item_id": 982000000567021, "name": "Hard Drive", "description": "500GB, USB 2.0 interface 1400 rpm, protective hard case.", "item_order": 1, "product_type": "goods", "bcy_rate": 120, "rate": 120, "quantity": 1, "unit": " ", "discount_amount": 0, "discount": 0, "tax_id": 982000000557028, "tax_name": "VAT", "tax_type": "tax", "tax_percentage": 12.5, "item_total": 120 } ], "shipping_charge": 0, "adjustment": 0, "adjustment_description": " ", "sub_total": 153, "total": 40.6, "tax_total": 22.6, "price_precision": 2, "taxes": [ { "tax_name": "VAT", "tax_amount": 19.13 } ], "billing_address": { "address": "4900 Hopyard Rd, Suite 310", "city": "Pleasanton", "state": "CA", "zip": 94588, "country": "U.S.A", "fax": "+1-925-924-9600" }, "shipping_address": { "address": "4900 Hopyard Rd, Suite 310", "city": "Pleasanton", "state": "CA", "zip": 94588, "country": "U.S.A", "fax": "+1-925-924-9600" }, "notes": "Looking forward for your business.", "terms": "Terms & Conditions apply", "custom_fields": [ { "index": 1, "show_on_pdf": false, "value": "15 Dec 2013", "label": "Delivery Date" } ], "template_id": 982000000000143, "template_name": "Service - Classic", "created_time": "2013-11-18T02:17:40-0800", "last_modified_time": "2016-06-17T04:46:45-0500", "salesperson_id": 982000000567003, "salesperson_name": "Will smith" } } }
ARGUMENTS
|
customer_id
Required
Search estimates by customer id..
contact_persons
Optional
Array if contact person(S) for whom estimate has to be sent.
template_id
Optional
ID of the pdf template associated with the estimate.
place_of_supply
India Edition only.
Optional
Place where the goods/services are supplied to. (If not given,
place of contact given for the contact will be taken)
gst_treatment
India Edition only
Optional
Choose whether the contact is GST registered/unregistered/consumer/overseas. Allowed values are
business_gst , business_none , overseas , consumer .
gst_no
India Edition only
Optional
15 digit GST identification number of the customer.
estimate_number
Optional
Search estimates by estimate number.Variants
estimate_number_startswith and estimate_number_contains
reference_number
Optional
Search estimates by reference number.Variants
reference_number_startswith and reference_number_contains
date
Optional
Search estimates by estimate date.Variants
date_start, date_end, date_before and date_after
expiry_date
Optional
The date of expiration of the estimates
exchange_rate
Optional
Exchange rate of the currency.
discount
Optional
Discount applied to the invoice. It can be either in % or in amount. e.g. 12.5% or 190.
is_discount_before_tax
Optional
Used to specify how the discount has to applied. Either before or after the calculation of tax.
discount_type
Optional
How the discount is specified. Allowed values are entity_level or item_level.Allowed Values:
entity_level and item_level
is_inclusive_tax
Not applicable for US and Canada editions
Optional
Used to specify whether the line item rates are inclusive or exclusive of tax.
custom_body
Optional
custom_subject
Optional
salesperson_name
Optional
Name of the sales person.
custom_fields
Optional
Custom fields for an estimate.
index
Optional
value
Optional
line_items
Required
Line items of an estimate.
item_id
Optional
ID of the item.
line_item_id
Optional
ID of the line item. Mandatory, if the existing line item has to be updated. If empty, a new line item will be created.
name
Optional
The name of the line item
product_type
Optional
Enter goods/services
hsn_or_sac
India Edition only
Optional
Add HSN/SAC code for your goods/services
item_order
Optional
The order of the line item_order
bcy_rate
Optional
base currency rate
rate
Optional
Rate of the line item.
quantity
Optional
The quantity of line item
unit
Optional
Unit of the line item e.g. kgs, Nos.
discount_amount
Optional
The discount amount on the line item
discount
Optional
Discount applied to the invoice. It can be either in % or in amount. e.g. 12.5% or 190.
tax_id
US edition only
Optional
ID of the tax or tax group applied to the estimate
tax_name
Optional
The name of the tax
tax_type
Optional
The type of the tax
tax_percentage
Optional
The percentage of tax levied
item_total
Optional
The total amount of the line items
notes
Optional
The notes added below expressing gratitude or for conveying some information.
terms
Optional
shipping_charge
Optional
Shipping charges applied to the invoice.
adjustment
Optional
Adjustments made to the invoice.
adjustment_description
Optional
Customize the adjustment description. E.g. Rounding off.
tax_id
US edition only
Optional
ID of the tax or tax group applied to the estimate
tax_exemption_id
Inida and US edition only
Optional
ID of the tax exemption.
tax_authority_id
US edition only
Optional
ID of the tax authority. Tax authority
depends on the location of the customer. For example, if the customer
is located in NY, then the tax authority is NY tax authority.
avatax_use_code
Avalara integration only
Optional
Used to group like customers for
exemption purposes. It is a custom value that links customers to a tax
rule. Select from Avalara [standard codes][1] or enter a custom code.
avatax_exempt_no
Avalara integration only
Optional
Exemption certificate number of the customer.
vat_treatment
Optional
Enter vat treatment
item_id
Optional
ID of the item.
line_item_id
Optional
ID of the line item. Mandatory, if the existing line item has to be updated. If empty, a new line item will be created.
name
Optional
The name of the line item
description
Optional
The description of the line items
rate
Optional
Rate of the line item.
unit
Optional
Unit of the line item e.g. kgs, Nos.
quantity
Optional
The quantity of line item
|
Query Params
|
send
Optional
Send the estimate to the contact person(s) associated with the estimate.Allowed Values:
true and false
ignore_auto_number_generation
Optional
Ignore auto estimate number generation for this estimate. This mandates the estimate number.
|
Update an Estimate
Update an existing estimate. To delete a line item just remove it from the line_items list.
PUT /estimates/{:estimate_id}
Request Example
$ curl https://books.zoho.com/api/v3/estimates/{:estimate_id}?organization_id=10234695 -H "Authorization: Zoho-authtoken ba4604e8e433g9c892e360d53463oec5" -H "Content-Type: application/json;charset=UTF-8" -d '{ "customer_id": 982000000567001, "template_id": 982000000000143, "place_of_supply": "TN", "gst_treatment": "business_gst", "gst_no": "22AAAAA0000A1Z5", "estimate_number": "EST-00002", "reference_number": "QRT-12346", "date": "2013-11-18", "expiry_date": "2013-11-30", "exchange_rate": 1, "discount": 0, "is_discount_before_tax": true, "discount_type": "item_level", "is_inclusive_tax": false, "custom_body": " ", "custom_subject": " ", "salesperson_name": "Will smith", "custom_fields": [ { "index": 1, "value": "15 Dec 2013" } ], "line_items": [ { "item_id": " ", "line_item_id": 982000000567021, "name": "Hard Drive", "description": "500GB, USB 2.0 interface 1400 rpm, protective hard case.", "product_type": "goods", "hsn_or_sac": 80540, "item_order": 1, "bcy_rate": 120, "rate": 120, "quantity": 1, "unit": " ", "discount_amount": 0, "discount": 0, "tax_id": 982000000557028, "tax_name": "VAT", "tax_type": "tax", "tax_percentage": 12.5, "item_total": 120 } ], "notes": "Looking forward for your business.", "terms": "Terms & Conditions apply", "shipping_charge": 0, "adjustment": 0, "adjustment_description": " ", "tax_id": 982000000557028, "tax_exemption_id": 11149000000061054, "tax_authority_id": 11149000000061052, "item_id": " ", "line_item_id": 982000000567021, "name": "Hard Drive", "description": "500GB, USB 2.0 interface 1400 rpm, protective hard case.", "rate": 120, "unit": " ", "quantity": 1 }
Response Example
HTTP/1.1 200 OK Content-Type:application/json;charset=UTF-8 { "code": 0, "message": "Estimate information has been updated.", "estimate": { "estimate": { "estimate_id": 982000000567011, "estimate_number": "EST-00002", "date": "2013-11-18", "reference_number": "QRT-12346", "is_pre_gst": false, "place_of_supply": "TN", "gst_no": "22AAAAA0000A1Z5", "gst_treatment": "business_gst", "status": "draft", "customer_id": 982000000567001, "customer_name": "Bowman & Co", "currency_id": 982000000000190, "currency_code": "USD", "exchange_rate": 1, "expiry_date": "2013-11-30", "discount": 0, "is_discount_before_tax": true, "discount_type": "item_level", "is_inclusive_tax": false, "line_items": [ { "item_id": " ", "line_item_id": 982000000567021, "name": "Hard Drive", "description": "500GB, USB 2.0 interface 1400 rpm, protective hard case.", "item_order": 1, "product_type": "goods", "bcy_rate": 120, "rate": 120, "quantity": 1, "unit": " ", "discount_amount": 0, "discount": 0, "tax_id": 982000000557028, "tax_name": "VAT", "tax_type": "tax", "tax_percentage": 12.5, "item_total": 120 } ], "shipping_charge": 0, "adjustment": 0, "adjustment_description": " ", "sub_total": 153, "total": 40.6, "tax_total": 22.6, "price_precision": 2, "taxes": [ { "tax_name": "VAT", "tax_amount": 19.13 } ], "billing_address": { "address": "4900 Hopyard Rd, Suite 310", "city": "Pleasanton", "state": "CA", "zip": 94588, "country": "U.S.A", "fax": "+1-925-924-9600" }, "shipping_address": { "address": "4900 Hopyard Rd, Suite 310", "city": "Pleasanton", "state": "CA", "zip": 94588, "country": "U.S.A", "fax": "+1-925-924-9600" }, "notes": "Looking forward for your business.", "terms": "Terms & Conditions apply", "custom_fields": [ { "index": 1, "show_on_pdf": false, "value": "15 Dec 2013", "label": "Delivery Date" } ], "template_id": 982000000000143, "template_name": "Service - Classic", "created_time": "2013-11-18T02:17:40-0800", "last_modified_time": "2016-06-17T04:46:45-0500", "salesperson_id": 982000000567003, "salesperson_name": "Will smith" } } }
ARGUMENTS
|
customer_id
Required
Search estimates by customer id..
contact_persons
Optional
Array if contact person(S) for whom estimate has to be sent.
template_id
Optional
ID of the pdf template associated with the estimate.
place_of_supply
India Edition only.
Optional
Place where the goods/services are supplied to. (If not given,
place of contact given for the contact will be taken)
gst_treatment
India Edition only
Optional
Choose whether the contact is GST registered/unregistered/consumer/overseas. Allowed values are
business_gst , business_none , overseas , consumer .
gst_no
India Edition only
Optional
15 digit GST identification number of the customer.
estimate_number
Optional
Search estimates by estimate number.Variants
estimate_number_startswith and estimate_number_contains
reference_number
Optional
Search estimates by reference number.Variants
reference_number_startswith and reference_number_contains
date
Optional
Search estimates by estimate date.Variants
date_start, date_end, date_before and date_after
expiry_date
Optional
The date of expiration of the estimates
exchange_rate
Optional
Exchange rate of the currency.
discount
Optional
Discount applied to the invoice. It can be either in % or in amount. e.g. 12.5% or 190.
is_discount_before_tax
Optional
Used to specify how the discount has to applied. Either before or after the calculation of tax.
discount_type
Optional
How the discount is specified. Allowed values are entity_level or item_level.Allowed Values:
entity_level and item_level
is_inclusive_tax
Not applicable for US and Canada editions
Optional
Used to specify whether the line item rates are inclusive or exclusive of tax.
custom_body
Optional
custom_subject
Optional
salesperson_name
Optional
Name of the sales person.
custom_fields
Required
Custom fields for an estimate.
index
Optional
value
Optional
line_items
Optional
Line items of an estimate.
item_id
Optional
ID of the item.
line_item_id
Optional
ID of the line item. Mandatory, if the existing line item has to be updated. If empty, a new line item will be created.
name
Optional
The name of the line item
product_type
Optional
Enter goods/services
hsn_or_sac
India Edition only
Optional
Add HSN/SAC code for your goods/services
item_order
Optional
The order of the line item_order
bcy_rate
Optional
base currency rate
rate
Optional
Rate of the line item.
quantity
Optional
The quantity of line item
unit
Optional
Unit of the line item e.g. kgs, Nos.
discount_amount
Optional
The discount amount on the line item
discount
Optional
Discount applied to the invoice. It can be either in % or in amount. e.g. 12.5% or 190.
tax_id
US edition only
Optional
ID of the tax or tax group applied to the estimate
tax_name
Optional
The name of the tax
tax_type
Optional
The type of the tax
tax_percentage
Optional
The percentage of tax levied
item_total
Optional
The total amount of the line items
notes
Optional
The notes added below expressing gratitude or for conveying some information.
terms
Optional
shipping_charge
Optional
Shipping charges applied to the invoice.
adjustment
Optional
Adjustments made to the invoice.
adjustment_description
Optional
Customize the adjustment description. E.g. Rounding off.
tax_id
US edition only
Optional
ID of the tax or tax group applied to the estimate
tax_exemption_id
Inida and US edition only
Optional
ID of the tax exemption.
tax_authority_id
US edition only
Optional
ID of the tax authority. Tax authority
depends on the location of the customer. For example, if the customer
is located in NY, then the tax authority is NY tax authority.
avatax_use_code
Avalara integration only
Optional
Used to group like customers for
exemption purposes. It is a custom value that links customers to a tax
rule. Select from Avalara [standard codes][1] or enter a custom code.
avatax_exempt_no
Avalara integration only
Optional
Exemption certificate number of the customer.
vat_treatment
Optional
Enter vat treatment
item_id
Optional
ID of the item.
line_item_id
Optional
ID of the line item. Mandatory, if the existing line item has to be updated. If empty, a new line item will be created.
name
Optional
The name of the line item
description
Optional
The description of the line items
rate
Optional
Rate of the line item.
unit
Optional
Unit of the line item e.g. kgs, Nos.
quantity
Optional
The quantity of line item
|
Query Params
|
ignore_auto_number_generation
Optional
Ignore auto estimate number generation for this estimate. This mandates the estimate number.
|
Get an estimate
Get the details of an estimate.
GET /estimates/{:estimate_id}
Request Example
$ curl https://books.zoho.com/api/v3/estimates/{:estimate_id}?organization_id=10234695 -H "Authorization: Zoho-authtoken ba4604e8e433g9c892e360d53463oec5" -H "Content-Type: application/json;charset=UTF-8"
Response Example
HTTP/1.1 200 OK Content-Type:application/json;charset=UTF-8 { "code": 0, "message": "success", "estimate": { "estimate": { "estimate_id": 982000000567011, "estimate_number": "EST-00002", "date": "2013-11-18", "reference_number": "QRT-12346", "is_pre_gst": false, "place_of_supply": "TN", "gst_no": "22AAAAA0000A1Z5", "gst_treatment": "business_gst", "status": "draft", "customer_id": 982000000567001, "customer_name": "Bowman & Co", "currency_id": 982000000000190, "currency_code": "USD", "exchange_rate": 1, "expiry_date": "2013-11-30", "discount": 0, "is_discount_before_tax": true, "discount_type": "item_level", "is_inclusive_tax": false, "is_viewed_by_client": true, "client_viewed_time": "2016-06-19T05:49:12-0500", "line_items": [ { "item_id": " ", "line_item_id": 982000000567021, "name": "Hard Drive", "description": "500GB, USB 2.0 interface 1400 rpm, protective hard case.", "item_order": 1, "product_type": "goods", "bcy_rate": 120, "rate": 120, "quantity": 1, "unit": " ", "discount_amount": 0, "discount": 0, "tax_id": 982000000557028, "tax_name": "VAT", "tax_type": "tax", "tax_percentage": 12.5, "item_total": 120 } ], "shipping_charge": 0, "adjustment": 0, "adjustment_description": " ", "sub_total": 153, "total": 40.6, "tax_total": 22.6, "price_precision": 2, "taxes": [ { "tax_name": "VAT", "tax_amount": 19.13 } ], "billing_address": { "address": "4900 Hopyard Rd, Suite 310", "city": "Pleasanton", "state": "CA", "zip": 94588, "country": "U.S.A", "fax": "+1-925-924-9600" }, "shipping_address": { "address": "4900 Hopyard Rd, Suite 310", "city": "Pleasanton", "state": "CA", "zip": 94588, "country": "U.S.A", "fax": "+1-925-924-9600" }, "custom_fields": [ { "index": 1, "show_on_pdf": false, "value": "15 Dec 2013", "label": "Delivery Date" } ], "template_id": 982000000000143, "template_name": "Service - Classic", "created_time": "2013-11-18T02:17:40-0800", "last_modified_time": "2016-06-17T04:46:45-0500", "salesperson_id": 982000000567003, "salesperson_name": "Will smith" } } }
Query Params
|
print
Optional
Print the exported pdf.
accept
Optional
Get the details of a particular estimate in formats such as json/ pdf/ html. Default format is json.Allowed Values:
json, pdf and html |
List estimates
List all estimates with pagination.
GET /estimates
Request Example
$ curl https://books.zoho.com/api/v3/estimates?organization_id=10234695 -H "Authorization: Zoho-authtoken ba4604e8e433g9c892e360d53463oec5" -H "Content-Type: application/json;charset=UTF-8"
Response Example
HTTP/1.1 200 OK Content-Type:application/json;charset=UTF-8 { "code": 0, "message": "success", "estimates": [ { "estimates": [ { "estimate_id": 982000000567011, "customer_name": "Bowman & Co", "customer_id": 982000000567001, "status": "draft", "estimate_number": "EST-00002", "reference_number": "QRT-12346", "date": "2013-11-18", "currency_id": 982000000000190, "currency_code": "USD", "total": 40.6, "created_time": "2013-11-18T02:17:40-0800", "last_modified_time": "2016-06-17T04:46:45-0500", "accepted_date": " ", "declined_date": " ", "expiry_date": "2013-11-30", "has_attachment": false, "is_viewed_by_client": true, "client_viewed_time": "2016-06-19T05:49:12-0500" } ], "page_context": [ { "page": 1, "per_page": 200, "has_more_page": false, "report_name": "Estimates", "applied_filter": "Status.All", "sort_column": "created_time", "sort_order": "D" } ] }, {...}, {...} ] }
Query Params
|
estimate_number
Optional
Search estimates by estimate number.Variants
estimate_number_startswith and estimate_number_contains
reference_number
Optional
Search estimates by reference number.Variants
reference_number_startswith and reference_number_contains
customer_name
Optional
Search estimates by customer name.Variants
customer_name_startswith and customer_name_contains
total
Optional
Search estimates by estimate total.Variants
total_less_than, total_less_equals, total_greater_than and total_greater_equals
customer_id
Optional
Search estimates by customer id..
item_id
Optional
ID of the item.
item_name
Optional
Search estimates by item name.Variants
item_name_startswith and item_name_contains
item_description
Optional
Search estimates by item description.Variants
item_description_startswith and item_description_contains
custom_field
Optional
Search estimates by custom field.Variants
custom_field_startswith and custom_field_contains
expiry_date
Optional
The date of expiration of the estimates
date
Optional
Search estimates by estimate date.Variants
date_start, date_end, date_before and date_after
status
Optional
Search estimates by status.Allowed Values
draft, sent, invoiced , accepted, declined and expired
filter_by
Optional
Filter estimates by status.Allowed Values
Status.All, Status.Sent, Status.Draft, Status.Invoiced, Status.Accepted, Status.Declined and Status.Expired
search_text
Optional
Search estimates by estimate number or reference or customer name.
sort_column
Optional
Sort estimates. Allowed Values
customer_name, estimate_number, date, total and created_time |
Delete an Estimate
Delete an existing estimate
DELETE /estimates/{:estimate_id}
Request Example
$ curl https://books.zoho.com/api/v3/estimates/{:estimate_id}?organization_id=10234695 -H "Authorization: Zoho-authtoken ba4604e8e433g9c892e360d53463oec5" -H "Content-Type: application/json;charset=UTF-8"
Response Example
HTTP/1.1 200 OK Content-Type:application/json;charset=UTF-8 { "code": 0, "message": "The estimate has been deleted." }
Mark an estimate as sent
Mark a draft estimate as sent.
POST /estimates/{:estimate_id}/status/sent
Request Example
$ curl https://books.zoho.com/api/v3/estimates/{:estimate_id}/status/sent?organization_id=10234695 -H "Authorization: Zoho-authtoken ba4604e8e433g9c892e360d53463oec5" -H "Content-Type: application/json;charset=UTF-8"
Response Example
HTTP/1.1 200 OK Content-Type:application/json;charset=UTF-8 { "code": 0, "message": "Estimate status has been changed to Sent" }
Mark an estimate as accepted
Mark a sent estimate as accepted if the customer has accepted it.
POST /estimates/{:estimate_id}/status/accepted
Request Example
$ curl https://books.zoho.com/api/v3/estimates/{:estimate_id}/status/accepted?organization_id=10234695 -H "Authorization: Zoho-authtoken ba4604e8e433g9c892e360d53463oec5" -H "Content-Type: application/json;charset=UTF-8"
Response Example
HTTP/1.1 200 OK Content-Type:application/json;charset=UTF-8 { "code": 0, "message": "Estimate status has been changed to Accepted." }
Mark an estimate as declined
Mark a sent estimate as declined if the customer has rejected it.
POST /estimates/{:estimate_id}/status/declined
Request Example
$ curl https://books.zoho.com/api/v3/estimates/{:estimate_id}/status/declined?organization_id=10234695 -H "Authorization: Zoho-authtoken ba4604e8e433g9c892e360d53463oec5" -H "Content-Type: application/json;charset=UTF-8"
Response Example
HTTP/1.1 200 OK Content-Type:application/json;charset=UTF-8 { "code": 0, "message": "Estimate status has been changed to Declined." }
Email an estimate
Email an estimate to the customer. Input json string is not mandatory. If input json string is empty, mail will be send with default mail content.
POST /estimates/{:estimate_id}/email
Request Example
$ curl https://books.zoho.com/api/v3/estimates/{:estimate_id}/email?organization_id=10234695 -H "Authorization: Zoho-authtoken ba4604e8e433g9c892e360d53463oec5" -H "Content-Type: application/json;charset=UTF-8" -d '{ "send_from_org_email_id": false, "to_mail_ids": [ {} ], "cc_mail_ids": [ {} ], "subject": "Statement of transactions with Zillium Inc", "body": "Dear Customer, Thanks for your business enquiry. The estimate EST-000002 is attached with this email. We can get started if you send us your consent. For any assistance you can reach us via email or phone. Looking forward to hearing back from you. Here's an overview of the estimate for your reference. Estimate Overview: Estimate : EST-000002 Date : 03 Oct 2013 Amount : $36.47 Regards<br>\\nZillium Inc<br>\\n\"\"" }
Response Example
HTTP/1.1 200 OK Content-Type:application/json;charset=UTF-8 { "code": 0, "message": "Your estimate has been sent." }
ARGUMENTS
|
send_from_org_email_id
Optional
Boolean to trigger the email from the organization's email address
to_mail_ids
Required
Array of email address of the recipients.
cc_mail_ids
Optional
Array of email address of the recipients to be cced.
subject
Optional
Subject of an email has to be sent.
body
Optional
Body of an email has to be sent.
|
Query Params
|
attachments
Optional
Files to be attached to the email
|
Email multiple estimates
Send estimates to your customers by email. Maximum of 10 estimates can be sent at once.
POST /estimates/email
Request Example
$ curl https://books.zoho.com/api/v3/estimates/email?organization_id=10234695 -H "Authorization: Zoho-authtoken ba4604e8e433g9c892e360d53463oec5" -H "Content-Type: application/json;charset=UTF-8"
Response Example
HTTP/1.1 200 OK Content-Type:application/json;charset=UTF-8 { "code": 0, "message": "Mission accomplished! We've sent all the estimates." }
Query Params
|
estimate_ids
Required
Comma separated estimate ids which are to be emailed.
|
Get estimate email content
Get the email content of an estimate.
GET /estimates/{:estimate_id}/email
Request Example
$ curl https://books.zoho.com/api/v3/estimates/{:estimate_id}/email?organization_id=10234695 -H "Authorization: Zoho-authtoken ba4604e8e433g9c892e360d53463oec5" -H "Content-Type: application/json;charset=UTF-8"
Response Example
HTTP/1.1 200 OK Content-Type:application/json;charset=UTF-8 { "code": 0, "message": "success", "body": "Dear Customer, Thanks for your business enquiry. The estimate EST-000002 is attached with this email. We can get started if you send us your consent. For any assistance you can reach us via email or phone. Looking forward to hearing back from you. Here's an overview of the estimate for your reference. Estimate Overview: Estimate : EST-000002 Date : 03 Oct 2013 Amount : $36.47 Regards<br>\\nZillium Inc<br>\\n\"\"", "error_list": [ {...} ], "subject": "Statement of transactions with Zillium Inc", "emailtemplates": [ { "selected": true, "name": "Hard Drive", "email_template_id": 982000000000079 } ], "to_contacts": [ { "first_name": "Sujin", "selected": true, "phone": "+1-925-921-9201", "last_name": "Kumar", "salutation": ":Mr", "contact_person_id": "982000000567003", "mobile": "+1-4054439562" } ], "file_name": "EST-00001.pdf", "from_emails": [ { "user_name": "John Smith", "selected": true } ], "customer_id": 982000000567001 }
Query Params
|
email_template_id
Required
Get the email content based on a
specific email template. If this param is not inputted, then the content
will be based on the email template associated with the customer. If no
template is associated with the customer, then default template will be
used.
|
Bulk export estimates
Maximum of 25 estimates can be exported in a single pdf.
GET /estimates/pdf
Request Example
$ curl https://books.zoho.com/api/v3/estimates/pdf?organization_id=10234695 -H "Authorization: Zoho-authtoken ba4604e8e433g9c892e360d53463oec5" -H "Content-Type: application/json;charset=UTF-8"
Response Example
HTTP/1.1 200 OK Content-Type:application/json;charset=UTF-8 { "code": 0, "message": "Invalid value passed for estimate_ids" }
Query Params
|
estimate_ids
Required
Comma separated estimate ids which are to be emailed.
|
Bulk print estimates
Export estimates as pdf and print them. Maximum of 25 estimates can be printed.
GET /estimates/print
Request Example
$ curl https://books.zoho.com/api/v3/estimates/print?organization_id=10234695 -H "Authorization: Zoho-authtoken ba4604e8e433g9c892e360d53463oec5" -H "Content-Type: application/json;charset=UTF-8"
Response Example
HTTP/1.1 200 OK Content-Type:application/json;charset=UTF-8 { "code": 0, "message": "success" }
Query Params
|
estimate_ids
Required
Comma separated estimate ids which are to be emailed.
|
Update billing address
Updates the billing address for this estimate alone.
PUT /estimates/{:estimate_id}/address/billing
Request Example
$ curl https://books.zoho.com/api/v3/estimates/{:estimate_id}/address/billing?organization_id=10234695 -H "Authorization: Zoho-authtoken ba4604e8e433g9c892e360d53463oec5" -H "Content-Type: application/json;charset=UTF-8" -d '{ "address": "B-1104, 11F, \nHorizon International Tower, \nNo. 6, ZhiChun Road, HaiDian District,", "city": "Beijing", "state": "Beijing", "zip": 1000881, "country": "China", "fax": "+86-10-82637827" }
Response Example
HTTP/1.1 200 OK Content-Type:application/json;charset=UTF-8 { "code": 0, "message": "Billing address updated" }
ARGUMENTS
|
address
Optional
Billing address for the estimate
city
Optional
City of the customer’s billing address.
state
Optional
State of the customer’s billing address.
zip
Optional
Zip code of the customer’s billing address.
country
Optional
Country of the customer’s billing address.
fax
Optional
Customer's fax number.
|
Update shipping address
Updates the shipping address for an existing estimate alone.
PUT /estimates/{:estimate_id}/address/shipping
Request Example
$ curl https://books.zoho.com/api/v3/estimates/{:estimate_id}/address/shipping?organization_id=10234695 -H "Authorization: Zoho-authtoken ba4604e8e433g9c892e360d53463oec5" -H "Content-Type: application/json;charset=UTF-8" -d '{ "address": "4900 Hopyard Rd, Suite 310", "city": "Pleasanton", "state": "CA", "zip": 94588, "country": "U.S.A", "fax": "+1-925-924-9600" }
Response Example
HTTP/1.1 200 OK Content-Type:application/json;charset=UTF-8 { "code": 0, "message": "Shipping address updated" }
ARGUMENTS
|
address
Optional
Billing address for the estimate
city
Optional
City of the customer’s billing address.
state
Optional
State of the customer’s billing address.
zip
Optional
Zip code of the customer’s billing address.
country
Optional
Country of the customer’s billing address.
fax
Optional
Customer's fax number.
|
List estimate template
Get all estimate pdf templates.
GET /estimates/templates
Request Example
$ curl https://books.zoho.com/api/v3/estimates/templates?organization_id=10234695 -H "Authorization: Zoho-authtoken ba4604e8e433g9c892e360d53463oec5" -H "Content-Type: application/json;charset=UTF-8"
Response Example
HTTP/1.1 200 OK Content-Type:application/json;charset=UTF-8 { "code": 0, "message": "success", "templates": [ { "templates": { "template_name": "Service - Classic", "template_id": 982000000000143, "template_type": "classic" } }, {...}, {...} ] }
Update estimate template
Update the pdf template associated with the estimate.
PUT /estimates/{:estimate_id}/templates/{:template_id}
Request Example
$ curl https://books.zoho.com/api/v3/estimates/{:estimate_id}/templates/{:template_id}?organization_id=10234695 -H "Authorization: Zoho-authtoken ba4604e8e433g9c892e360d53463oec5" -H "Content-Type: application/json;charset=UTF-8"
Response Example
HTTP/1.1 200 OK Content-Type:application/json;charset=UTF-8 { "code": 0, "message": "Estimate information has been updated." }
List estimate comments & history
Get the complete history and comments of an estimate.
GET /estimates/{:estimate_id}/comments
Request Example
$ curl https://books.zoho.com/api/v3/estimates/{:estimate_id}/comments?organization_id=10234695 -H "Authorization: Zoho-authtoken ba4604e8e433g9c892e360d53463oec5" -H "Content-Type: application/json;charset=UTF-8"
Response Example
HTTP/1.1 200 OK Content-Type:application/json;charset=UTF-8 { "code": 0, "message": "success", "comments": [ { "comments": { "comment_id": 982000000567019, "estimate_id": 982000000567011, "description": "Estimate created", "commented_by_id": 982000000554041, "commented_by": "Sujin Kumar", "comment_type": "system", "date": "2013-11-18", "date_description": "yesterday", "time": "2:02 AM", "operation_type": "Added", "transaction_id": " ", "transaction_type": "estimate" } }, {...}, {...} ] }
Add Comments
Add a comment for an estimate.
POST /estimates/{:estimate_id}/comments
Request Example
$ curl https://books.zoho.com/api/v3/estimates/{:estimate_id}/comments?organization_id=10234695 -H "Authorization: Zoho-authtoken ba4604e8e433g9c892e360d53463oec5" -H "Content-Type: application/json;charset=UTF-8" -d '{ "description": "Estimate marked as sent", "show_comment_to_clients": true }
Response Example
HTTP/1.1 200 OK Content-Type:application/json;charset=UTF-8 { "code": 0, "message": "Comments added" }
ARGUMENTS
|
description
Optional
The description of the line items
show_comment_to_clients
Optional
Boolean to show the comments to contacts in portal.
|
Update comment
Update an existing comment of an estimate.
PUT /estimates/{:estimate_id}/comments/{:comment_id}
Request Example
$ curl https://books.zoho.com/api/v3/estimates/{:estimate_id}/comments/{:comment_id}?organization_id=10234695 -H "Authorization: Zoho-authtoken ba4604e8e433g9c892e360d53463oec5" -H "Content-Type: application/json;charset=UTF-8" -d '{ "description": "Estimate created", "show_comment_to_clients": " " }
Response Example
HTTP/1.1 200 OK Content-Type:application/json;charset=UTF-8 { "code": 0, "message": "Comment has been updated successfully.", "comment": { "comment_id": 982000000567019, "estimate_id": 982000000567011, "description": "500GB, USB 2.0 interface 1400 rpm, protective hard case.", "commented_by_id": 982000000554041, "commented_by": "Sujin Kumar", "date": "2013-11-18", "date_description": "yesterday", "time": "2:02 AM", "comment_type": "system" } }
ARGUMENTS
|
description
Optional
The description of the line items
show_comment_to_clients
Optional
Boolean to show the comments to contacts in portal.
|
Delete a comment
Delete an estimate comment.
DELETE /estimates/{:estimate_id}/comments/{:comment_id}
Request Example
$ curl https://books.zoho.com/api/v3/estimates/{:estimate_id}/comments/{:comment_id}?organization_id=10234695 -H "Authorization: Zoho-authtoken ba4604e8e433g9c892e360d53463oec5" -H "Content-Type: application/json;charset=UTF-8"
Response Example
HTTP/1.1 200 OK Content-Type:application/json;charset=UTF-8 { "code": 0, "message": "The comment has been deleted." }
Sales-Order
A sales order is a financial document that confirms an impending sale. It is raised when an initial estimate is approved and the transaction is underway, and details the exact quantity, price and delivery details of the products or services being sold.
Example
{ "salesorder": [ { "salesorder_id": "460000000039129", "documents": [ {} ], "is_pre_gst": false, "gst_no": "22AAAAA0000A1Z5", "gst_treatment": "business_gst", "place_of_supply": "TN", "salesorder_number": "SO-00001", "date": "2014-07-28", "status": "open", "reference_number": "REF-001", "customer_id": "460000000017138", "customer_name": "SAF Instruments Inc", "contact_persons": [ "460000000870911", "460000000870915" ], "currency_id": "460000000000097", "currency_code": "USD", "currency_symbol": "$", "exchange_rate": 1.233, "discount_amount": 0, "discount_applied_on_amount": 0, "is_discount_before_tax": true, "discount_type": "entity_level", "delivery_method": "Air", "is_inclusive_tax": false, "line_items": [ { "item_order": 0, "item_id": "460000000017088", "rate": 120, "name": "Hard Drive", "description": "500GB, USB 2.0 interface 1400 rpm, protective hard case.", "quantity": 40, "product_type": "goods", "hsn_or_sac": 80540, "tax_id": "460000000017094", "tags": [ {} ], "unit": "Nos", "item_custom_fields": [ { "index": 1, "value": "Normal", "label": "Priority" } ] } ], "shipping_charge": 2, "adjustment": 0.2, "adjustment_description": "Adjustment", "sub_total": 11800, "tax_total": 600, "total": 12400, "taxes": [ { "tax_id": "460000000017094", "tax_amount": 600 } ], "price_precision": 2, "is_emailed": false, "billing_address": { "address": "B-1104, 11F, \nHorizon International Tower, \nNo. 6, ZhiChun Road, HaiDian District", "street2": "McMillan Avenue", "city": "Beijing", "state": "Beijing", "zip": "1000881", "country": "China", "fax": "+86-10-82637827" }, "shipping_address": { "address": "B-1104, 11F, \nHorizon International Tower, \nNo. 6, ZhiChun Road, HaiDian District", "street2": "McMillan Avenue", "city": "Beijing", "state": "Beijing", "zip": "1000881", "country": "China", "fax": "+86-10-82637827" }, "custom_fields": [ { "index": 1, "value": "Normal", "label": "Priority" } ], "template_id": "460000000021001", "template_name": "Standard Template", "page_width": "8.27in", "page_height": "11.69in", "orientation": "portrait", "template_type": "standard", "created_time": "2014-07-28T08:29:07+0530", "last_modified_time": "2014-08-25T11:23:26+0530", "created_by_id": "460000000053001", "can_send_in_mail": true, "salesperson_name": "John Roberts" } ] }
Attribute
|
salesorder
list
salesorder_id
string
ID of the Sales Order
documents
list
is_pre_gst
India Edition only.
boolean
Applicable for transactions that fall before july 1, 2017
gst_no
India Edition only.
string
15 digit GST identification number of the customer.
gst_treatment
India Edition only.
string
Choose whether the contact is GST registered/unregistered/consumer/overseas. Allowed values are
business_gst , business_none , overseas , consumer .
place_of_supply
India Edition only.
string
Place where the goods/services are supplied to. (If not given,
place of contact given for the contact will be taken)
vat_treatment
string
Enter vat treatment
zcrm_potential_id
string
zcrm_potential_name
string
salesorder_number
string
Mandatory if auto number generation is disabled.
date
string
The date, the sales order is created.
status
string
Status of the Sales Order
shipment_date
string
Shipping date of sales order.
reference_number
string
Reference Number of the Sales Order.
customer_id
string
ID of the customer to whom the sales order has to be created.
customer_name
string
Name of the customer associated with the Sales Order
contact_persons
array
Array of contact person(s) for whom sales order has to be sent.
currency_id
string
ID of the Currency in Sales Order
currency_code
string
Code of the Currency involved in the Sales Order
currency_symbol
string
exchange_rate
double
Exchange rate of the currency.
discount_amount
double
discount
string
Discount applied to the sales order. It can be either in % or in amount. e.g. 12.5% or 190.
discount_applied_on_amount
integer
is_discount_before_tax
boolean
Used to specify how the discount has to applied. Either before or after the calculation of tax.
discount_type
string
How the discount is specified. Allowed values are entity_level or item_level. Allowed Values:
entity_level and item_level.
estimate_id
string
ID of the estimate from which the sales order is created.
delivery_method
string
delivery_method_id
string
is_inclusive_tax
Not applicable for US and CA editions
boolean
Used to specify whether the line item rates are inclusive or exclusive of tax.
line_items
list
Line items of a sales order.
item_order
integer
item_id
string
ID of the item.
rate
double
Rate of the line item.
name
string
Name of the line item.
quantity
double
Quantity of the line item.
product_type
string
Enter goods/services
hsn_or_sac
India Edition only
string
Add HSN/SAC code for your goods/services
warehouse_id
string
ID of the warehouse
discount
string
Discount applied to the sales order. It can be either in % or in amount. e.g. 12.5% or 190.
tax_id
string
ID of the tax or tax group applied
tags
list
unit
string
Unit of the line item e.g. kgs, Nos.
item_custom_fields
list
Custom fields for a sales order items.
custom_field_id
long
ID of the Custom Field
index
integer
value
string
label
string
tax_exemption_id
India Edition and US Edition only
string
ID of the tax exemption applied
tax_exemption_code
India Edition and US Edition Only
string
Code of Tax Exemption that is applied
avatax_exempt_no
Avalara integration only
string
Exemption certificate number of the customer.
avatax_use_code
Avalara integration only
string
Used to group like customers for exemption purposes. It is a custom value that links customers to a tax rule.
shipping_charge
double
adjustment
double
adjustment_description
string
sub_total
double
Sub Total of the Sales Order
tax_total
double
total
double
Total of the Sales Order
taxes
list
tax_id
string
ID of the tax or tax group applied
tax_name
string
tax_amount
double
price_precision
integer
is_emailed
boolean
Check if the Sales Order is emailed to the customer
billing_address
object
address
string
Address
street2
string
city
string
City of the address
state
string
State of the Address
zip
string
ZIP Code of the Address
country
string
Country of the Address
fax
string
Fax Number
attention
string
shipping_address
object
address
string
Address
street2
string
city
string
City of the address
state
string
State of the Address
zip
string
ZIP Code of the Address
country
string
Country of the Address
fax
string
Fax Number
attention
string
notes
string
Notes for this Sales Order
terms
string
custom_fields
list
Custom fields for a sales order.
custom_field_id
long
ID of the Custom Field
index
integer
value
string
label
string
template_id
string
ID of the pdf template.
template_name
string
Name of the template
page_width
string
page_height
string
orientation
string
template_type
string
Type of the template
created_time
string
Creation Time of the Sales Order
last_modified_time
string
Last Modified time of the Sales Order
created_by_id
string
attachment_name
string
can_send_in_mail
boolean
Can the file be sent in mail.
salesperson_id
string
salesperson_name
string
Name of the sales person.
|
Create a sales order
Create a sales order for your customer.
POST /salesorders
Request Example
$ curl https://books.zoho.com/api/v3/salesorders?organization_id=10234695 -H "Authorization: Zoho-authtoken ba4604e8e433g9c892e360d53463oec5" -H "Content-Type: application/json;charset=UTF-8" -d '{ "customer_id": "460000000017138", "contact_persons": [ "460000000870911", "460000000870915" ], "date": "2014-07-28", "custom_fields": [ { "index": 1, "value": "Normal", "label": "Priority" } ], "place_of_supply": "TN", "gst_treatment": "business_gst", "gst_no": "22AAAAA0000A1Z5", "is_inclusive_tax": false, "line_items": [ { "item_order": 0, "item_id": "460000000017088", "rate": 120, "name": "Hard Drive", "description": "500GB, USB 2.0 interface 1400 rpm, protective hard case.", "quantity": 40, "product_type": "goods", "hsn_or_sac": 80540, "tags": [ {} ], "unit": "Nos", "item_custom_fields": [ { "index": 1, "value": "Normal", "label": "Priority" } ] } ], "billing_address_id": 460000000032174, "salesorder_number": "SO-00001", "reference_number": "REF-001", "is_update_customer": false, "exchange_rate": 1.233, "salesperson_name": "John Roberts", "shipping_charge": 2, "adjustment": 0.2, "delivery_method": "Air", "is_discount_before_tax": true, "discount_type": "entity_level", "adjustment_description": "Adjustment", "template_id": "460000000021001", "documents": [ {} ] }
Response Example
HTTP/1.1 201 Created Content-Type:application/json;charset=UTF-8 { "code": 0, "message": "Sales Order Created Successfully.", "salesorder": [ { "salesorder_id": "460000000039129", "documents": [ {...} ], "is_pre_gst": false, "gst_no": "22AAAAA0000A1Z5", "gst_treatment": "business_gst", "place_of_supply": "TN", "salesorder_number": "SO-00001", "date": "2014-07-28", "status": "open", "reference_number": "REF-001", "customer_id": "460000000017138", "customer_name": "SAF Instruments Inc", "contact_persons": [ "460000000870911", "460000000870915" ], "currency_id": "460000000000097", "currency_code": "USD", "currency_symbol": "$", "exchange_rate": 1.233, "discount_amount": 0, "discount_applied_on_amount": 0, "is_discount_before_tax": true, "discount_type": "entity_level", "delivery_method": "Air", "is_inclusive_tax": false, "line_items": [ { "item_order": 0, "item_id": "460000000017088", "rate": 120, "name": "Hard Drive", "description": "500GB, USB 2.0 interface 1400 rpm, protective hard case.", "quantity": 40, "product_type": "goods", "hsn_or_sac": 80540, "tax_id": "460000000017094", "tags": [ {...} ], "unit": "Nos", "item_custom_fields": [ { "index": 1, "value": "Normal", "label": "Priority" } ] } ], "shipping_charge": 2, "adjustment": 0.2, "adjustment_description": "Adjustment", "sub_total": 11800, "tax_total": 600, "total": 12400, "taxes": [ { "tax_id": "460000000017094", "tax_amount": 600 } ], "price_precision": 2, "is_emailed": false, "billing_address": { "address": "B-1104, 11F, \nHorizon International Tower, \nNo. 6, ZhiChun Road, HaiDian District", "street2": "McMillan Avenue", "city": "Beijing", "state": "Beijing", "zip": "1000881", "country": "China", "fax": "+86-10-82637827" }, "shipping_address": { "address": "B-1104, 11F, \nHorizon International Tower, \nNo. 6, ZhiChun Road, HaiDian District", "street2": "McMillan Avenue", "city": "Beijing", "state": "Beijing", "zip": "1000881", "country": "China", "fax": "+86-10-82637827" }, "custom_fields": [ { "index": 1, "value": "Normal", "label": "Priority" } ], "template_id": "460000000021001", "template_name": "Standard Template", "page_width": "8.27in", "page_height": "11.69in", "orientation": "portrait", "template_type": "standard", "created_time": "2014-07-28T08:29:07+0530", "last_modified_time": "2014-08-25T11:23:26+0530", "created_by_id": "460000000053001", "can_send_in_mail": true, "salesperson_name": "John Roberts" } ] }
ARGUMENTS
|
customer_id
Required
ID of the customer to whom the sales order has to be created.
contact_persons
Optional
Array of contact person(s) for whom sales order has to be sent.
date
Optional
The date, the sales order is created.
shipment_date
Optional
Shipping date of sales order.
custom_fields
Optional
Custom fields for a sales order.
custom_field_id
Optional
ID of the Custom Field
index
Optional
value
Optional
label
Optional
place_of_supply
India Edition only.
Optional
Place where the goods/services are supplied to. (If not given,
place of contact given for the contact will be taken)
gst_treatment
India Edition only.
Optional
Choose whether the contact is GST registered/unregistered/consumer/overseas. Allowed values are
business_gst , business_none , overseas , consumer .
gst_no
India Edition only.
Optional
15 digit GST identification number of the customer.
is_inclusive_tax
Not applicable for US and CA editions
Optional
Used to specify whether the line item rates are inclusive or exclusive of tax.
line_items
Optional
Line items of a sales order.
item_order
Optional
item_id
Optional
ID of the item.
rate
Optional
Rate of the line item.
name
Optional
Name of the line item.
quantity
Optional
Quantity of the line item.
product_type
Optional
Enter goods/services
hsn_or_sac
India Edition only
Optional
Add HSN/SAC code for your goods/services
warehouse_id
Optional
ID of the warehouse
discount
Optional
Discount applied to the sales order. It can be either in % or in amount. e.g. 12.5% or 190.
tax_id
Optional
Tax ID for the Sales Order.
tags
Optional
unit
Optional
Unit of the line item e.g. kgs, Nos.
item_custom_fields
Optional
Custom fields for a sales order items.
custom_field_id
Optional
ID of the Custom Field
index
Optional
value
Optional
label
Optional
tax_exemption_id
India Edition and US Edition only
Optional
ID of the tax exemption applied
tax_exemption_code
India Edition and US Edition Only
Optional
Code of Tax Exemption that is applied
avatax_exempt_no
Avalara integration only
Optional
Exemption certificate number of the customer.
avatax_use_code
Avalara integration only
Optional
Used to group like customers for exemption purposes. It is a custom value that links customers to a tax rule.
notes
Optional
Notes for this Sales Order
terms
Optional
billing_address_id
Optional
ID of the Billing Address
shipping_address_id
Optional
ID of the Shipping Address
crm_owner_id
Optional
crm_custom_reference_id
Optional
vat_treatment
Optional
Enter vat treatment
salesorder_number
Optional
Mandatory if auto number generation is disabled.
reference_number
Optional
Reference Number of the Sales Order.
is_update_customer
Optional
Boolean to update billing address of customer.
discount
Optional
Discount applied to the sales order. It can be either in % or in amount. e.g. 12.5% or 190.
exchange_rate
Optional
Exchange rate of the currency.
salesperson_name
Optional
Name of the sales person.
notes_default
Optional
Default Notes for the Sales Order
terms_default
Optional
Default Terms of the Sales Order
tax_id
Optional
Tax ID for the Sales Order.
tax_authority_id
US Edition only
Optional
ID of the tax authority. Tax authority depends on the location of the customer.
tax_exemption_id
India Edition and US Edition only
Optional
ID of the tax exemption applied
tax_authority_name
US Edition Only
Optional
Tax Authority's name.
tax_exemption_code
India Edition and US Edition Only
Optional
Code of Tax Exemption that is applied
avatax_exempt_no
Avalara integration only
Optional
Exemption certificate number of the customer.
avatax_use_code
Avalara integration only
Optional
Used to group like customers for exemption purposes. It is a custom value that links customers to a tax rule.
shipping_charge
Optional
adjustment
Optional
delivery_method
Optional
estimate_id
Optional
ID of the estimate associated with the Sales Order
is_discount_before_tax
Optional
Used to specify how the discount has to applied. Either before or after the calculation of tax.
discount_type
Optional
How the discount is specified. Allowed values are entity_level or item_level. Allowed Values:
entity_level and item_level.
adjustment_description
Optional
pricebook_id
Optional
template_id
Optional
ID of the pdf template.
documents
Optional
zcrm_potential_id
Optional
zcrm_potential_name
Optional
|
Query Params
|
ignore_auto_number_generation
Optional
Ignore auto sales order number generation for this sales order. This mandates the sales order number.
can_send_in_mail
Optional
Can the file be sent in mail.
totalFiles
Optional
Total number of files.
doc
Optional
Document that is to be attached
|
Update a sales order
Update an existing sales order. To delete a line item just remove it from the line_items list.
PUT /salesorders/{salesorder_id}
Request Example
$ curl https://books.zoho.com/api/v3/salesorders/{salesorder_id}?organization_id=10234695 -H "Authorization: Zoho-authtoken ba4604e8e433g9c892e360d53463oec5" -H "Content-Type: application/json;charset=UTF-8" -d '{ "customer_id": "460000000017138", "contact_persons": [ "460000000870911", "460000000870915" ], "date": "2014-07-28", "custom_fields": [ { "index": 1, "value": "Normal", "label": "Priority" } ], "place_of_supply": "TN", "gst_treatment": "business_gst", "gst_no": "22AAAAA0000A1Z5", "is_inclusive_tax": false, "line_items": [ { "item_order": 0, "line_item_id": "460000000039131", "item_id": "460000000017088", "rate": 120, "name": "Hard Drive", "description": "500GB, USB 2.0 interface 1400 rpm, protective hard case.", "quantity": 40, "tags": [ {} ], "unit": "Nos", "item_custom_fields": [ { "index": 1, "value": "Normal", "label": "Priority" } ] } ], "billing_address_id": 460000000032174, "salesorder_number": "SO-00001", "reference_number": "REF-001", "is_update_customer": false, "exchange_rate": 1.233, "salesperson_name": "John Roberts", "shipping_charge": 2, "adjustment": 0.2, "delivery_method": "Air", "is_discount_before_tax": true, "discount_type": "entity_level", "adjustment_description": "Adjustment", "template_id": "460000000021001", "documents": [ {} ] }
Response Example
HTTP/1.1 200 OK Content-Type:application/json;charset=UTF-8 { "code": 0, "message": "Sales Order Updated Successfully.", "salesorder": [ { "salesorder_id": "460000000039129", "documents": [ {...} ], "is_pre_gst": false, "gst_no": "22AAAAA0000A1Z5", "gst_treatment": "business_gst", "place_of_supply": "TN", "salesorder_number": "SO-00001", "date": "2014-07-28", "status": "open", "reference_number": "REF-001", "customer_id": "460000000017138", "customer_name": "SAF Instruments Inc", "contact_persons": [ "460000000870911", "460000000870915" ], "currency_id": "460000000000097", "currency_code": "USD", "currency_symbol": "$", "exchange_rate": 1.233, "discount_amount": 0, "discount_applied_on_amount": 0, "is_discount_before_tax": true, "discount_type": "entity_level", "delivery_method": "Air", "is_inclusive_tax": false, "line_items": [ { "item_order": 0, "item_id": "460000000017088", "rate": 120, "name": "Hard Drive", "description": "500GB, USB 2.0 interface 1400 rpm, protective hard case.", "quantity": 40, "product_type": "goods", "hsn_or_sac": 80540, "tax_id": "460000000017094", "tags": [ {...} ], "unit": "Nos", "item_custom_fields": [ { "index": 1, "value": "Normal", "label": "Priority" } ] } ], "shipping_charge": 2, "adjustment": 0.2, "adjustment_description": "Adjustment", "sub_total": 11800, "tax_total": 600, "total": 12400, "taxes": [ { "tax_id": "460000000017094", "tax_amount": 600 } ], "price_precision": 2, "is_emailed": false, "billing_address": { "address": "B-1104, 11F, \nHorizon International Tower, \nNo. 6, ZhiChun Road, HaiDian District", "street2": "McMillan Avenue", "city": "Beijing", "state": "Beijing", "zip": "1000881", "country": "China", "fax": "+86-10-82637827" }, "shipping_address": { "address": "B-1104, 11F, \nHorizon International Tower, \nNo. 6, ZhiChun Road, HaiDian District", "street2": "McMillan Avenue", "city": "Beijing", "state": "Beijing", "zip": "1000881", "country": "China", "fax": "+86-10-82637827" }, "custom_fields": [ { "index": 1, "value": "Normal", "label": "Priority" } ], "template_id": "460000000021001", "template_name": "Standard Template", "page_width": "8.27in", "page_height": "11.69in", "orientation": "portrait", "template_type": "standard", "created_time": "2014-07-28T08:29:07+0530", "last_modified_time": "2014-08-25T11:23:26+0530", "created_by_id": "460000000053001", "can_send_in_mail": true, "salesperson_name": "John Roberts" } ] }
ARGUMENTS
|
customer_id
Required
ID of the customer to whom the sales order has to be created.
contact_persons
Optional
Array of contact person(s) for whom sales order has to be sent.
date
Optional
The date, the sales order is created.
shipment_date
Optional
Shipping date of sales order.
custom_fields
Optional
Custom fields for a sales order.
custom_field_id
Optional
ID of the Custom Field
index
Optional
value
Optional
label
Optional
place_of_supply
India Edition only.
Optional
Place where the goods/services are supplied to. (If not given,
place of contact given for the contact will be taken)
gst_treatment
India Edition only.
Optional
Choose whether the contact is GST registered/unregistered/consumer/overseas. Allowed values are
business_gst , business_none , overseas , consumer .
gst_no
India Edition only.
Optional
15 digit GST identification number of the customer.
is_inclusive_tax
Not applicable for US and CA editions
Optional
Used to specify whether the line item rates are inclusive or exclusive of tax.
line_items
Optional
Line items of a sales order.
item_order
Optional
line_item_id
Optional
ID of the line item. Mandatory if the existing line item has to be updated. If empty, a new line item will be created.
item_id
Optional
ID of the item.
rate
Optional
Rate of the line item.
name
Optional
Name of the line item.
quantity
Optional
Quantity of the line item.
discount
Optional
Discount applied to the sales order. It can be either in % or in amount. e.g. 12.5% or 190.
tax_id
Optional
Tax ID for the Sales Order.
tags
Optional
unit
Optional
Unit of the line item e.g. kgs, Nos.
item_custom_fields
Optional
Custom fields for a sales order items.
custom_field_id
Optional
ID of the Custom Field
index
Optional
value
Optional
label
Optional
tax_exemption_id
India Edition and US Edition only
Optional
ID of the tax exemption applied
tax_exemption_code
India Edition and US Edition Only
Optional
Code of Tax Exemption that is applied
avatax_exempt_no
Avalara integration only
Optional
Exemption certificate number of the customer.
avatax_use_code
Avalara integration only
Optional
Used to group like customers for exemption purposes. It is a custom value that links customers to a tax rule.
notes
Optional
Notes for this Sales Order
terms
Optional
billing_address_id
Optional
ID of the Billing Address
shipping_address_id
Optional
ID of the Shipping Address
crm_owner_id
Optional
crm_custom_reference_id
Optional
vat_treatment
Optional
Enter vat treatment
salesorder_number
Optional
Mandatory if auto number generation is disabled.
reference_number
Optional
Reference Number of the Sales Order.
is_update_customer
Optional
Boolean to update billing address of customer.
discount
Optional
Discount applied to the sales order. It can be either in % or in amount. e.g. 12.5% or 190.
exchange_rate
Optional
Exchange rate of the currency.
salesperson_name
Optional
Name of the sales person.
notes_default
Optional
Default Notes for the Sales Order
terms_default
Optional
Default Terms of the Sales Order
tax_id
Optional
Tax ID for the Sales Order.
tax_authority_id
US Edition only
Optional
ID of the tax authority. Tax authority depends on the location of the customer.
tax_exemption_id
India Edition and US Edition only
Optional
ID of the tax exemption applied
tax_authority_name
US Edition Only
Optional
Tax Authority's name.
tax_exemption_code
India Edition and US Edition Only
Optional
Code of Tax Exemption that is applied
avatax_exempt_no
Avalara integration only
Optional
Exemption certificate number of the customer.
avatax_use_code
Avalara integration only
Optional
Used to group like customers for exemption purposes. It is a custom value that links customers to a tax rule.
shipping_charge
Optional
adjustment
Optional
delivery_method
Optional
is_discount_before_tax
Optional
Used to specify how the discount has to applied. Either before or after the calculation of tax.
discount_type
Optional
How the discount is specified. Allowed values are entity_level or item_level. Allowed Values:
entity_level and item_level.
adjustment_description
Optional
pricebook_id
Optional
template_id
Optional
ID of the pdf template.
documents
Optional
zcrm_potential_id
Optional
zcrm_potential_name
Optional
|
Query Params
|
ignore_auto_number_generation
Optional
Ignore auto sales order number generation for this sales order. This mandates the sales order number.
can_send_in_mail
Optional
Can the file be sent in mail.
totalFiles
Optional
Total number of files.
doc
Optional
Document that is to be attached
|
List sales orders
List all sales orders.
GET /salesorders
Request Example
$ curl https://books.zoho.com/api/v3/salesorders?organization_id=10234695 -H "Authorization: Zoho-authtoken ba4604e8e433g9c892e360d53463oec5" -H "Content-Type: application/json;charset=UTF-8"
Response Example
HTTP/1.1 200 OK Content-Type:application/json;charset=UTF-8 { "code": 0, "message": "success", "salesorders": [ { "salesorder_id": "460000000039129", "customer_name": "SAF Instruments Inc", "customer_id": "460000000017138", "status": "open", "salesorder_number": "SO-00001", "reference_number": "REF-001", "date": "2014-07-28", "shipment_days": 2, "currency_id": "460000000000097", "currency_code": "USD", "total": 12400, "sub_total": 11800, "bcy_total": 400, "created_time": "2014-07-28T08:29:07+0530", "last_modified_time": "2014-08-25T11:23:26+0530", "is_emailed": false, "has_attachment": false, "custom_fields": [ { "index": 1, "value": "Normal", "label": "Priority" } ] }, {...}, {...} ] }
Query Params
|
sort_column
Optional
Sort sales orders. Allowed Values:
customer_name, salesorder_number, shipment_date, total, date and created_time.
search_text
Optional
Search sales order by sales order number or reference number or customer name.
filter_by
Optional
Filter sales order by status. Allowed Values:
Status.All, Status.Open, Status.Draft, Status.OverDue, Status.PartiallyInvoiced, Status.Invoiced, Status.Void and Status.Closed
salesorder_number
Optional
Search Sales Order by Sales Order Number. Variants:
salesorder_number.startswith, salesorder_number.contains. Maximum Length : 100
item_name
Optional
Search sales order by item name. Variants:
item_name.startswith and item_name.contains. Maximum Length : 100
item_id
Optional
Search Sales Order Based on Item ID.
item_description
Optional
Search sales order by item description. Variants:
item_description.startswith and item_description.contains. Maximum Length: 100
reference_number
Optional
Search sales order by reference number. Variants:
reference_number.startswith and reference_number.contains.
customer_name
Optional
Search sales order by customer name. Variants:
customer_name.startswith and customer_name.contains. Maximum Length : 100
total
Optional
Search sales order by sales order total. Variants:
total.start, total.end, total.less_than, total.less_equals, total.greater_than and total.greater_equals.
date
Optional
Search sales order by sales order date. Variants:
date.start, date.end, date.before and date.after. Default date format : yyyy-mm-dd
shipment_date
Optional
Search sales order by sales order shipment date. Variants:
shipment_date.start, shipment_date.end, shipment_date.before and shipment_date.after. Default date format : yyyy-mm-dd
status
Optional
Search sales order by sales order status. Allowed Values:
draft, open, invoiced, partially_invoiced, void and overdue.
customer_id
Optional
Search Sales Order based on customer_id
|
Get a sales order
Get the details of a sales order.
GET /salesorders/{salesorder_id}
Request Example
$ curl https://books.zoho.com/api/v3/salesorders/{salesorder_id}?organization_id=10234695 -H "Authorization: Zoho-authtoken ba4604e8e433g9c892e360d53463oec5" -H "Content-Type: application/json;charset=UTF-8"
Response Example
HTTP/1.1 200 OK Content-Type:application/json;charset=UTF-8 { "code": 0, "message": "success", "salesorder": [ { "customer_id": "460000000017138", "billing_address_id": 460000000032174, "is_pre_gst": false, "gst_no": "22AAAAA0000A1Z5", "gst_treatment": "business_gst", "place_of_supply": "TN", "is_update_customer": false, "contact_persons": [ {...} ], "salesorder_number": "SO-00001", "reference_number": "REF-001", "template_id": "460000000021001", "documents": [ {...} ], "exchange_rate": 1.233, "is_discount_before_tax": true, "discount_type": "entity_level", "salesperson_name": "John Roberts", "tax_id": "460000000017094", "is_inclusive_tax": false, "custom_fields": [ { "index": 1, "value": "Normal", "label": "Priority" } ], "line_items": [ { "line_item_id": "460000000039131", "bcy_rate": 120, "is_taxable": false, "item_total_inclusive_of_tax": 48, "product_type": "goods", "hsn_or_sac": 80540, "is_invoiced": false } ], "shipping_charge": 2, "adjustment": 0.2, "adjustment_description": "Adjustment", "delivery_method": "Air" } ] }
Query Params
|
print
Optional
Print the exported pdf.
accept
Optional
Get the details of a particular sales order in formats such as json/ pdf/ html. Default format is json. Allowed Values:
json, pdf and html. |
Delete a sales order
Delete an existing sales order. Invoiced sales order cannot be deleted.
DELETE /salesorders/{salesorder_id}
Request Example
$ curl https://books.zoho.com/api/v3/salesorders/{salesorder_id}?organization_id=10234695 -H "Authorization: Zoho-authtoken ba4604e8e433g9c892e360d53463oec5" -H "Content-Type: application/json;charset=UTF-8"
Response Example
HTTP/1.1 200 OK Content-Type:application/json;charset=UTF-8 { "code": 0, "message": "Sales Order Deleted Successfully." }
Mark a sales order as open
Mark a draft sales order as open.
POST /salesorders/{salesorder_id}/status/open
Request Example
$ curl https://books.zoho.com/api/v3/salesorders/{salesorder_id}/status/open?organization_id=10234695 -H "Authorization: Zoho-authtoken ba4604e8e433g9c892e360d53463oec5" -H "Content-Type: application/json;charset=UTF-8"
Response Example
HTTP/1.1 201 Created Content-Type:application/json;charset=UTF-8 { "code": 0, "message": "Sales order status has been changed to Open." }
Mark a sales order as void
Mark a sales order as void.
POST /salesorders/{salesorder_id}/status/void
Request Example
$ curl https://books.zoho.com/api/v3/salesorders/{salesorder_id}/status/void?organization_id=10234695 -H "Authorization: Zoho-authtoken ba4604e8e433g9c892e360d53463oec5" -H "Content-Type: application/json;charset=UTF-8"
Response Example
HTTP/1.1 201 Created Content-Type:application/json;charset=UTF-8 { "code": 0, "message": "Sales order status has been changed to Void." }
Email a sales order
Email a sales order to the customer. Input json string is not mandatory. If input json string is empty, mail will be send with default mail content.
POST /salesorders/{salesorder_id}/email
Request Example
$ curl https://books.zoho.com/api/v3/salesorders/{salesorder_id}/email?organization_id=10234695 -H "Authorization: Zoho-authtoken ba4604e8e433g9c892e360d53463oec5" -H "Content-Type: application/json;charset=UTF-8" -d '{ "from_address_id": "johnRoberts@safInstrument.com", "send_from_org_email_id": true, "to_mail_ids": [ {} ], "cc_mail_ids": [ {} ], "bcc_mail_ids": [ {} ], "subject": "Sales Order from Zillium Inc (Sales Order #: SO-00001)", "invoice_id": 460000000028192, "body": "<br>Dear SAF Instruments Inc, <br><br>Thanks for your interest in our services. Please find our sales order attached with this mail.<br><br> An overview of the sales order is available below for your reference: <br><br> ----------------------------------------------------------------------------------------<br> <h2>Sales Order # : SO-00001</h2><br> ----------------------------------------------------------------------------------------<br> <b> Order Date : 28 Jul 2014</b><br><b> Amount : $12,400.00</b><br>----------------------------------------------------------------------------------------<br><br><span>Assuring you of our best services at all times.</span><br><br><br>Regards,<br><br>John<br>Zillium Inc<br><br><br>" }
Response Example
HTTP/1.1 201 Created Content-Type:application/json;charset=UTF-8 { "code": 0, "message": "Your Sales Order has been sent." }
ARGUMENTS
|
from_address_id
Optional
From Address of the Email Address
send_from_org_email_id
Optional
Boolean to trigger the email from the organization's email address.
to_mail_ids
Required
Array of email address of the recipients.
cc_mail_ids
Optional
Array of email address of the recipients to be CC ed.
bcc_mail_ids
Optional
Array of email address of the recipients to be BCC ed.
subject
Required
Subject of the mail.
documents
Optional
invoice_id
Optional
ID of the invoice
body
Required
Body of the mail.
|
Query Params
|
salesorder_id
Optional
ID of the Sales Order
attachments
Optional
Attachments of the Sales Order
send_attachment
Optional
Send the sales order attachment a with the email.
file_name
Optional
Name of the file.
|
Get sales order email content
Get the email content of a sales order.
GET /salesorders/{salesorder_id}/email
Request Example
$ curl https://books.zoho.com/api/v3/salesorders/{salesorder_id}/email?organization_id=10234695 -H "Authorization: Zoho-authtoken ba4604e8e433g9c892e360d53463oec5" -H "Content-Type: application/json;charset=UTF-8"
Response Example
HTTP/1.1 200 OK Content-Type:application/json;charset=UTF-8 { "code": 0, "message": "success", "data": [ { "bcc_mails": [ {...} ], "body": "<br>Dear SAF Instruments Inc, <br><br>Thanks for your interest in our services. Please find our sales order attached with this mail.<br><br> An overview of the sales order is available below for your reference: <br><br> ----------------------------------------------------------------------------------------<br> <h2>Sales Order # : SO-00001</h2><br> ----------------------------------------------------------------------------------------<br> <b> Order Date : 28 Jul 2014</b><br><b> Amount : $12,400.00</b><br>----------------------------------------------------------------------------------------<br><br><span>Assuring you of our best services at all times.</span><br><br><br>Regards,<br><br>John<br>Zillium Inc<br><br><br>", "error_list": [ {...} ], "documents": [ {...} ], "subject": "Sales Order from Zillium Inc (Sales Order #: SO-00001)", "customer_name": "SAF Instruments Inc", "entity_id": "460000000058039", "cc_mails_list": [], "from_emails": [ { "organization_contact_id": "460000000053003", "selected": true, "is_org_email_id": true } ], "file_name_without_extension": "SO-00001", "emailtemplates": [ { "selected": true, "name": "Hard Drive", "email_template_id": 460000000001287 } ], "to_contacts": [ { "selected": true, "salutation": "Ms." } ], "customer_id": "460000000017138" } ] }
Query Params
|
email_template_id
Optional
Get the email content based on a
specific email template. If this param is not inputted, then the content
will be based on the email template associated with the customer. If no
template is associated with the customer, then default template will be
used.
|
Bulk export sales orders
Maximum of 25 sales orders can be exported in a single pdf.
GET /salesorders/pdf
Request Example
$ curl https://books.zoho.com/api/v3/salesorders/pdf?organization_id=10234695 -H "Authorization: Zoho-authtoken ba4604e8e433g9c892e360d53463oec5" -H "Content-Type: application/json;charset=UTF-8" -d '{ "salesorder_ids": 460108000000072000 }
Response Example
HTTP/1.1 200 OK Content-Type:application/json;charset=UTF-8 { "code": 0, "message": "success" }
ARGUMENTS
|
salesorder_ids
Required
Comma separated sales order ids which are to be export as pdf.
|
Bulk print sales orders
Export sales orders as pdf and print them. Maximum of 25 sales orders can be printed.
GET /salesorders/print
Request Example
$ curl https://books.zoho.com/api/v3/salesorders/print?organization_id=10234695 -H "Authorization: Zoho-authtoken ba4604e8e433g9c892e360d53463oec5" -H "Content-Type: application/json;charset=UTF-8" -d '{ "salesorder_ids": 460108000000072000 }
Response Example
HTTP/1.1 200 OK Content-Type:application/json;charset=UTF-8 { "code": 0, "message": "success" }
ARGUMENTS
|
salesorder_ids
Required
Comma separated sales order ids which are to be export as pdf.
|
Update billing address
Updates the billing address for this sales order alone.
PUT /salesorders/{salesorder_id}/address/billing
Request Example
$ curl https://books.zoho.com/api/v3/salesorders/{salesorder_id}/address/billing?organization_id=10234695 -H "Authorization: Zoho-authtoken ba4604e8e433g9c892e360d53463oec5" -H "Content-Type: application/json;charset=UTF-8" -d '{ "address": "B-1104, 11F, \nHorizon International Tower, \nNo. 6, ZhiChun Road, HaiDian District", "city": "Beijing", "state": "Beijing", "zip": "1000881", "country": "China", "fax": "+86-10-82637827", "is_one_off_address": true, "is_update_customer": false }
Response Example
HTTP/1.1 200 OK Content-Type:application/json;charset=UTF-8 { "code": 0, "message": "Billing address updated." }
ARGUMENTS
|
address
Optional
Address
city
Optional
City of the address
state
Optional
State of the Address
zip
Optional
ZIP Code of the Address
country
Optional
Country of the Address
fax
Optional
Fax Number
attention
Optional
is_one_off_address
Optional
is_update_customer
Optional
Boolean to update billing address of customer.
is_verified
Avalara Integration Only
Optional
Check if the Address is verified
|
Update shipping address
Updates the shipping address for this sales order alone.
PUT /salesorders/{salesorder_id}/address/shipping
Request Example
$ curl https://books.zoho.com/api/v3/salesorders/{salesorder_id}/address/shipping?organization_id=10234695 -H "Authorization: Zoho-authtoken ba4604e8e433g9c892e360d53463oec5" -H "Content-Type: application/json;charset=UTF-8" -d '{ "address": "B-1104, 11F, \nHorizon International Tower, \nNo. 6, ZhiChun Road, HaiDian District", "city": "Beijing", "state": "Beijing", "zip": "1000881", "country": "China", "fax": "+86-10-82637827", "is_one_off_address": true, "is_update_customer": false }
Response Example
HTTP/1.1 200 OK Content-Type:application/json;charset=UTF-8 { "code": 0, "message": "Shipping address updated." }
ARGUMENTS
|
address
Optional
Address
city
Optional
City of the address
state
Optional
State of the Address
zip
Optional
ZIP Code of the Address
country
Optional
Country of the Address
fax
Optional
Fax Number
attention
Optional
is_one_off_address
Optional
is_update_customer
Optional
Boolean to update billing address of customer.
is_verified
Avalara Integration Only
Optional
Check if the Address is verified
|
List sales order templates
Get all sales order pdf templates.
GET /salesorders/templates
Request Example
$ curl https://books.zoho.com/api/v3/salesorders/templates?organization_id=10234695 -H "Authorization: Zoho-authtoken ba4604e8e433g9c892e360d53463oec5" -H "Content-Type: application/json;charset=UTF-8"
Response Example
HTTP/1.1 200 OK Content-Type:application/json;charset=UTF-8 { "code": 0, "message": "success", "templates": [ { "template_name": "Standard Template", "template_id": "460000000021001", "template_type": "standard" } ] }
Update sales order template
Update the pdf template associated with the sales order.
PUT /salesorders/{salesorder_id}/templates/{template_id}
Request Example
$ curl https://books.zoho.com/api/v3/salesorders/{salesorder_id}/templates/{template_id}?organization_id=10234695 -H "Authorization: Zoho-authtoken ba4604e8e433g9c892e360d53463oec5" -H "Content-Type: application/json;charset=UTF-8"
Response Example
HTTP/1.1 200 OK Content-Type:application/json;charset=UTF-8 { "code": 0, "message": "Sales Order Updated Successfully." }
Get a sales order attachment
Returns the file attached to the sales order.
GET /salesorders/{salesorder_id}/attachment
Request Example
$ curl https://books.zoho.com/api/v3/salesorders/{salesorder_id}/attachment?organization_id=10234695 -H "Authorization: Zoho-authtoken ba4604e8e433g9c892e360d53463oec5" -H "Content-Type: application/json;charset=UTF-8"
Response Example
HTTP/1.1 200 OK Content-Type:application/json;charset=UTF-8 { "code": 0, "message": "Success" }
Query Params
|
preview
Optional
Check if preview of the Sales Order is required
inline
Optional
Check if inline response is required
|
Add attachment to a sales order
Attach a file to a sales order
POST /salesorders/{salesorder_id}/attachment
Request Example
$ curl https://books.zoho.com/api/v3/salesorders/{salesorder_id}/attachment?organization_id=10234695 -H "Authorization: Zoho-authtoken ba4604e8e433g9c892e360d53463oec5" -H "Content-Type: application/json;charset=UTF-8"
Response Example
HTTP/1.1 201 Created Content-Type:application/json;charset=UTF-8 { "code": 0, "message": "Your file has been successfully attached to the sales order." }
Query Params
|
attachment
Optional
The file that is to be added as an Attachment in the Sales Order
can_send_in_mail
Optional
Can the file be sent in mail.
doc
Optional
Document that is to be attached
totalFiles
Optional
Total number of files.
document_ids
Optional
ID's of the document
|
Update attachment preference
Set whether you want to send the attached file while emailing the sales order.
PUT /salesorders/{salesorder_id}/attachment
Request Example
$ curl https://books.zoho.com/api/v3/salesorders/{salesorder_id}/attachment?organization_id=10234695 -H "Authorization: Zoho-authtoken ba4604e8e433g9c892e360d53463oec5" -H "Content-Type: application/json;charset=UTF-8"
Response Example
HTTP/1.1 200 OK Content-Type:application/json;charset=UTF-8 { "code": 0, "message": "Sales Oder Updated Successfully." }
Query Params
|
can_send_in_mail
Required
Can the file be sent in mail.
|
Delete an attachment
Delete the file attached to the sales order.
DELETE /salesorders/{salesorder_id}/attachment
Request Example
$ curl https://books.zoho.com/api/v3/salesorders/{salesorder_id}/attachment?organization_id=10234695 -H "Authorization: Zoho-authtoken ba4604e8e433g9c892e360d53463oec5" -H "Content-Type: application/json;charset=UTF-8"
Response Example
HTTP/1.1 200 OK Content-Type:application/json;charset=UTF-8 { "code": 0, "message": "Your file is no longer attached to the sales order." }
List sales order comments & history
Get the complete history and comments of sales order.
GET /salesorders/{salesorder_id}/comments
Request Example
$ curl https://books.zoho.com/api/v3/salesorders/{salesorder_id}/comments?organization_id=10234695 -H "Authorization: Zoho-authtoken ba4604e8e433g9c892e360d53463oec5" -H "Content-Type: application/json;charset=UTF-8"
Response Example
HTTP/1.1 200 OK Content-Type:application/json;charset=UTF-8 { "code": 0, "message": "success" }
Add comment
Add a comment for a sales order.
POST /salesorders/{salesorder_id}/comments
Request Example
$ curl https://books.zoho.com/api/v3/salesorders/{salesorder_id}/comments?organization_id=10234695 -H "Authorization: Zoho-authtoken ba4604e8e433g9c892e360d53463oec5" -H "Content-Type: application/json;charset=UTF-8" -d '{ "description": "500GB, USB 2.0 interface 1400 rpm, protective hard case." }
Response Example
HTTP/1.1 200 OK Content-Type:application/json;charset=UTF-8 { "code": 0, "message": "Comments added.", "comment": [ { "salesorder_id": "460000000039129", "comment_id": "460000000048023", "description": "500GB, USB 2.0 interface 1400 rpm, protective hard case.", "commented_by_id": "460000000017003", "commented_by": "John", "comment_type": "system", "date": "2014-07-28", "date_description": "6 minutes ago", "time": "2:12 PM", "operation_type": "Added", "transaction_type": "salesorder" } ] }
ARGUMENTS
|
description
Optional
Description of the line item.
|
Update comment
Update existing comment of a sales order.
PUT /salesorders/{salesorder_id}/comments/{comment_id}
Request Example
$ curl https://books.zoho.com/api/v3/salesorders/{salesorder_id}/comments/{comment_id}?organization_id=10234695 -H "Authorization: Zoho-authtoken ba4604e8e433g9c892e360d53463oec5" -H "Content-Type: application/json;charset=UTF-8" -d '{ "description": "500GB, USB 2.0 interface 1400 rpm, protective hard case." }
Response Example
HTTP/1.1 200 OK Content-Type:application/json;charset=UTF-8 { "code": 0, "message": "Comment has been updated.", "comment": [ { "salesorder_id": "460000000039129", "comment_id": "460000000048023", "description": "500GB, USB 2.0 interface 1400 rpm, protective hard case.", "commented_by_id": "460000000017003", "commented_by": "John", "comment_type": "system", "date": "2014-07-28", "date_description": "6 minutes ago", "time": "2:12 PM", "operation_type": "Added", "transaction_type": "salesorder" } ] }
ARGUMENTS
|
description
Optional
Description of the line item.
|
Delete a comment
Delete a sales order comment.
DELETE /salesorders/{salesorder_id}/comments/{comment_id}
Request Example
$ curl https://books.zoho.com/api/v3/salesorders/{salesorder_id}/comments/{comment_id}?organization_id=10234695 -H "Authorization: Zoho-authtoken ba4604e8e433g9c892e360d53463oec5" -H "Content-Type: application/json;charset=UTF-8"
Response Example
HTTP/1.1 200 OK Content-Type:application/json;charset=UTF-8 { "code": 0, "message": "The comment has been deleted." }
Invoices
Invoice is a document sent to your client that indicates the products/services sold by you with the payment information that the client has to make.
Example
{ "invoice_number": "INV-00003", "item_name": "Desktop Units", "item_id": 982000000030049, "recurring_invoice_id": " ", "custom_field": " ", "search_text": " ", "sort_column": "created_time", "invoices": [ {} ] }
Attribute
|
invoice_number
string
Search invoices by invoice number.Variants:
invoice_number_startswith and invoice_number_contains. Max-length [100]
item_name
string
Search invoices by item name.Variants:
item_name_startswith and item_name_contains. Max-length [100]
item_id
string
Search invoices by item id.
recurring_invoice_id
string
ID of the recurring invoice from which the invoice is created.
email
Search contacts by email id. Max-length [100]
custom_field
string
Search invoices by custom fields.Variants:
custom_field_startswith and custom_field_contains
search_text
string
Search invoices by invoice number or purchase order or customer name. Max-length [100]
sort_column
string
Sort invoices.Allowed Values:
customer_name, invoice_number, date, due_date, total, balance and created_time
invoices
list
The invoices created by the user
|
Create an invoice
Create an invoice for your customer.
POST /invoices
Request Example
$ curl https://books.zoho.com/api/v3/invoices?organization_id=10234695 -H "Authorization: Zoho-authtoken ba4604e8e433g9c892e360d53463oec5" -H "Content-Type: application/json;charset=UTF-8" -d '{ "customer_id": 982000000567001, "contact_persons": [ "982000000870911", "982000000870915" ], "invoice_number": "INV-00003", "place_of_supply": "TN", "gst_treatment": "business_gst", "gst_no": "22AAAAA0000A1Z5", "reference_number": " ", "template_id": 982000000000143, "date": "2013-11-17", "payment_terms": 15, "payment_terms_label": "Net 15", "due_date": "2013-12-03", "discount": 0, "is_discount_before_tax": true, "discount_type": "item_level", "is_inclusive_tax": false, "exchange_rate": 1, "recurring_invoice_id": " ", "invoiced_estimate_id": " ", "salesperson_name": " ", "custom_fields": [ {} ], "project_id": " ", "line_items": [ { "item_id": 982000000030049, "project_id": " ", "time_entry_ids": [ {} ], "product_type": "goods", "hsn_or_sac": 80540, "warehouse_id": "", "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": 1, "unit": " ", "discount_amount": 0, "discount": 0, "tax_id": 982000000557028, "tax_name": "VAT", "tax_type": "tax", "tax_percentage": 12.5, "item_total": 120 } ], "payment_options": {}, "allow_partial_payments": true, "custom_body": " ", "custom_subject": " ", "notes": "Looking forward for your business.", "terms": "Terms & Conditions apply", "shipping_charge": 0, "adjustment": 0, "adjustment_description": " ", "reason": " ", "tax_authority_id": 11149000000061052, "tax_exemption_id": 11149000000061054, "tax_id": 982000000557028, "item_id": 982000000030049, "expense_id": " ", "salesorder_item_id": " ", "name": "Hard Drive", "description": "500GB, USB 2.0 interface 1400 rpm, protective hard case.", "account_id": " ", "rate": 120, "unit": " ", "quantity": 1, "time_entry_ids": [ {} ], "payment_gateways": [ {} ], "gateway_name": "paypal", "additional_field1": "standard" }
Response Example
HTTP/1.1 201 Created Content-Type:application/json;charset=UTF-8 { "code": 0, "message": "The invoice has been created.", "invoice": { "invoice": { "invoice_id": 982000000567114, "ach_payment_initiated": false, "invoice_number": "INV-00003", "is_pre_gst": true, "place_of_supply": "TN", "gst_no": "22AAAAA0000A1Z5", "gst_treatment": "business_gst", "date": "2013-11-17", "status": "draft", "payment_terms": 15, "payment_terms_label": "Net 15", "due_date": "2013-12-03", "payment_expected_date": " ", "last_payment_date": " ", "reference_number": " ", "customer_id": 982000000567001, "customer_name": "Bowman & Co", "contact_persons": [ "982000000870911", "982000000870915" ], "currency_id": 982000000000190, "currency_code": "USD", "exchange_rate": 1, "discount": 0, "is_discount_before_tax": true, "discount_type": "item_level", "is_inclusive_tax": false, "recurring_invoice_id": " ", "is_viewed_by_client": false, "has_attachment": false, "client_viewed_time": "", "line_items": [ { "line_item_id": 982000000567021, "item_id": 982000000030049, "project_id": " ", "time_entry_ids": [ {...} ], "warehouses": [ { "warehouse_id": "", "warehouse_name": "", "warehouse_stock_on_hand": "" } ], "item_type": "goods", "product_type": "goods", "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": 1, "unit": " ", "discount_amount": 0, "discount": 0, "tax_id": 982000000557028, "tax_name": "VAT", "tax_type": "tax", "tax_percentage": 12.5, "item_total": 120 } ], "shipping_charge": 0, "adjustment": 0, "adjustment_description": " ", "sub_total": 153, "tax_total": 22.6, "total": 40.6, "taxes": [ { "tax_name": "VAT", "tax_amount": 19.13 } ], "payment_reminder_enabled": true, "payment_made": 26.91, "credits_applied": 22.43, "tax_amount_withheld": 0, "balance": 40.6, "write_off_amount": 0, "allow_partial_payments": true, "price_precision": 2, "payment_options": {...}, "is_emailed": false, "reminders_sent": 1, "last_reminder_sent_date": " ", "billing_address": {...}, "shipping_address": {...}, "notes": "Looking forward for your business.", "terms": "Terms & Conditions apply", "custom_fields": [ {...} ], "template_id": 982000000000143, "template_name": "Service - Classic", "created_time": "2013-11-18T02:17:40-0800", "last_modified_time": "2013-11-18T02:02:51-0800", "attachment_name": " ", "can_send_in_mail": true, "salesperson_id": " ", "salesperson_name": " ", "invoice_url": "https://invoice.zoho.com/SecurePayment?CInvoiceID=23d84d0cf64f9a72ea0c66fded25a08c8bafd0ab508aff05323a9f80e2cd03fdc5dd568d3d6407bbda969d3e870d740b6fce549a9438c4ea" } } }
ARGUMENTS
|
customer_id
Required
ID of the customer the invoice has to be created.
contact_persons
Optional
Array of contact person(s) for whom invoice has to be sent.
invoice_number
Optional
Search invoices by invoice number.Variants:
invoice_number_startswith and invoice_number_contains. Max-length [100]
place_of_supply
India Edition only.
Optional
Place where the goods/services are supplied to. (If not given,
place of contact given for the contact will be taken)
vat_treatment
Optional
Enter vat treatment
gst_treatment
India Edition only.
Optional
Choose whether the contact is GST registered/unregistered/consumer/overseas. Allowed values are
business_gst , business_none , overseas , consumer .
gst_no
India Edition only.
Optional
15 digit GST identification number of the customer.
reference_number
Optional
The reference number of the invoice
template_id
Optional
ID of the pdf template associated with the invoice.
date
Optional
Search invoices by invoice date. Default date format is yyyy-mm-dd.
Variants: due_date_start, due_date_end, due_date_before and due_date_after.
payment_terms
Optional
Payment terms in days e.g. 15, 30, 60. Invoice due date will be calculated based on this. Max-length [100]
payment_terms_label
Optional
Used to override the default payment terms label. Default value for 15 days is "Net 15 Days". Max-length [100]
due_date
Optional
Search invoices by due date. Default date format is yyyy-mm-dd.
Variants: due_date_start, due_date_end, due_date_before and due_date_after
discount
Optional
Discount applied to the invoice. It can be either in % or in amount. e.g. 12.5% or 190. Max-length [100]
is_discount_before_tax
Optional
Used to specify how the discount has to applied. Either before or after the calculation of tax.
discount_type
Optional
How the discount is specified. Allowed values:
entity_level and item_level.
is_inclusive_tax
Optional
Used to specify whether the line item rates are inclusive or exclusivr of tax.
exchange_rate
Optional
Exchange rate of the currency.
recurring_invoice_id
Optional
ID of the recurring invoice from which the invoice is created.
invoiced_estimate_id
Optional
ID of the invoice from which the invoice is created.
salesperson_name
Optional
Name of the salesperson. Max-length [200]
custom_fields
Optional
Custom fields for an invoice.
project_id
Optional
line_items
Required
Line items of an invoice.
item_id
Optional
Search invoices by item id.
project_id
Optional
time_entry_ids
Optional
IDs of the time entries associated with the project.
product_type
Optional
Enter goods/services
hsn_or_sac
India Edition only
Optional
Add HSN/SAC code for your goods/services
warehouse_id
Optional
Enter warehouse ID
expense_id
Optional
expense_receipt_name
Optional
name
Optional
The name of the line item. Max-length [100]
item_order
Optional
The order of the line item_order
bcy_rate
Optional
base currency rate
rate
Optional
Rate of the line item.
quantity
Optional
The quantity of line item
unit
Optional
Unit of the line item e.g. kgs, Nos. Max-length [100]
discount_amount
Optional
The discount amount on the line item
discount
Optional
Discount applied to the invoice. It can be either in % or in amount. e.g. 12.5% or 190. Max-length [100]
tax_id
Optional
ID of the tax.
tax_name
Optional
The name of the tax
tax_type
Optional
The type of the tax
tax_percentage
Optional
The percentage of tax levied
item_total
Optional
The total amount of the line items
payment_options
Optional
Payment options for the invoice, online payment gateways and bank accounts. Will be displayed in the pdf.
allow_partial_payments
Optional
Boolean to check if partial payments are allowed for the contact
custom_body
Optional
custom_subject
Optional
notes
Optional
The notes added below expressing gratitude or for conveying some information.
terms
Optional
The terms added below expressing gratitude or for conveying some information.
shipping_charge
Optional
Shipping charges applied to the invoice. Max-length [100]
adjustment
Optional
Adjustments made to the invoice.
adjustment_description
Optional
Customize the adjustment description. E.g. Rounding off.
reason
Optional
tax_authority_id
US edition only
Optional
ID of the tax authority. Tax authority
depends on the location of the customer. For example, if the customer
is located in NY, then the tax authority is NY tax authority.
tax_exemption_id
India and US edition only
Optional
ID of the tax exemption.
avatax_use_code
Avalara integration only
Optional
Used to group like customers for
exemption purposes. It is a custom value that links customers to a tax
rule. Select from Avalara [standard codes][1] or enter a custom code.
Max-length [25]
avatax_exempt_no
Avalara integration only
Optional
Exemption certificate number of the customer. Max-length [25]
vat_treatment
Optional
Enter vat treatment
tax_id
Optional
ID of the tax.
item_id
Optional
Search invoices by item id.
expense_id
Optional
salesorder_item_id
Optional
ID of the sales order line item which is invoices.
name
Optional
The name of the line item. Max-length [100]
description
Optional
The description of the line items. Max-length [2000]
account_id
Optional
Account ID that has to be associated to the line item.
rate
Optional
Rate of the line item.
unit
Optional
Unit of the line item e.g. kgs, Nos. Max-length [100]
quantity
Optional
The quantity of line item
avatax_tax_code
Avalara integration only
Optional
A tax code is a unique label used to
group Items (products, services, or charges) together. Refer the
[link][2] for more deails. Max-length [25]
time_entry_ids
Optional
IDs of the time entries associated with the project.
payment_gateways
Optional
Online payment gateways through which payment can be made.
gateway_name
Optional
Name of the payment gateway associated with the invoice. E.g. paypal, stripe.Allowed Values:
paypal, authorize_net, payflow_pro, stripe, 2checkout and braintree
additional_field1
Optional
Paypal payment method. Allowed Values:
standard and adaptive |
Query Params
|
send
Optional
Send the invoice to the contact person(s) associated with the invoice. Allowed values
true and false.
ignore_auto_number_generation
Optional
Ignore auto invoice number generation for this invoice. This mandates the invoice number. Allowed values
true and false |
Update an invoice
Update an existing invoice. To delete a line item just remove it from the line_items list.
PUT /invoices/:invoice_id
Request Example
$ curl https://books.zoho.com/api/v3/invoices/:invoice_id?organization_id=10234695 -H "Authorization: Zoho-authtoken ba4604e8e433g9c892e360d53463oec5" -H "Content-Type: application/json;charset=UTF-8" -d '{ "customer_id": 982000000567001, "contact_persons": [ "982000000870911", "982000000870915" ], "invoice_number": "INV-00003", "place_of_supply": "TN", "gst_treatment": "business_gst", "gst_no": "22AAAAA0000A1Z5", "reference_number": " ", "template_id": 982000000000143, "date": "2013-11-17", "payment_terms": 15, "payment_terms_label": "Net 15", "due_date": "2013-12-03", "discount": 0, "is_discount_before_tax": true, "discount_type": "item_level", "is_inclusive_tax": false, "exchange_rate": 1, "recurring_invoice_id": " ", "invoiced_estimate_id": " ", "salesperson_name": " ", "custom_fields": [ {} ], "project_id": " ", "line_items": [ { "item_id": 982000000030049, "project_id": " ", "time_entry_ids": [ {} ], "product_type": "goods", "hsn_or_sac": 80540, "warehouse_id": "", "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": 1, "unit": " ", "discount_amount": 0, "discount": 0, "tax_id": 982000000557028, "tax_name": "VAT", "tax_type": "tax", "tax_percentage": 12.5, "item_total": 120 } ], "payment_options": {}, "allow_partial_payments": true, "custom_body": " ", "custom_subject": " ", "notes": "Looking forward for your business.", "terms": "Terms & Conditions apply", "shipping_charge": 0, "adjustment": 0, "adjustment_description": " ", "reason": " ", "tax_authority_id": 11149000000061052, "tax_exemption_id": 11149000000061054, "tax_id": 982000000557028, "item_id": 982000000030049, "expense_id": " ", "salesorder_item_id": " ", "name": "Hard Drive", "description": "500GB, USB 2.0 interface 1400 rpm, protective hard case.", "account_id": " ", "payment_gateways": [ {} ], "gateway_name": "paypal", "additional_field1": "standard", "line_item_id": 982000000567021 }
Response Example
HTTP/1.1 200 OK Content-Type:application/json;charset=UTF-8 { "code": 0, "message": "Invoice information has been updated.", "invoice": { "invoice_id": 982000000567114, "ach_payment_initiated": false, "invoice_number": "INV-00003", "is_pre_gst": true, "place_of_supply": "TN", "gst_no": "22AAAAA0000A1Z5", "gst_treatment": "business_gst", "date": "2013-11-17", "status": "draft", "payment_terms": 15, "payment_terms_label": "Net 15", "due_date": "2013-12-03", "payment_expected_date": " ", "last_payment_date": " ", "reference_number": " ", "customer_id": 982000000567001, "customer_name": "Bowman & Co", "contact_persons": [ "982000000870911", "982000000870915" ], "currency_id": 982000000000190, "currency_code": "USD", "exchange_rate": 1, "discount": 0, "is_discount_before_tax": true, "discount_type": "item_level", "is_inclusive_tax": false, "recurring_invoice_id": " ", "is_viewed_by_client": false, "has_attachment": false, "client_viewed_time": "", "line_items": [ { "line_item_id": 982000000567021, "item_id": 982000000030049, "project_id": " ", "time_entry_ids": [ {...} ], "warehouses": [ { "warehouse_id": "", "warehouse_name": "", "warehouse_stock_on_hand": "" } ], "item_type": "goods", "product_type": "goods", "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": 1, "unit": " ", "discount_amount": 0, "discount": 0, "tax_id": 982000000557028, "tax_name": "VAT", "tax_type": "tax", "tax_percentage": 12.5, "item_total": 120 } ], "shipping_charge": 0, "adjustment": 0, "adjustment_description": " ", "sub_total": 153, "tax_total": 22.6, "total": 40.6, "taxes": [ { "tax_name": "VAT", "tax_amount": 19.13 } ], "payment_reminder_enabled": true, "payment_made": 26.91, "credits_applied": 22.43, "tax_amount_withheld": 0, "balance": 40.6, "write_off_amount": 0, "allow_partial_payments": true, "price_precision": 2, "payment_options": {...}, "is_emailed": false, "reminders_sent": 1, "last_reminder_sent_date": " ", "billing_address": {...}, "shipping_address": {...}, "notes": "Looking forward for your business.", "terms": "Terms & Conditions apply", "custom_fields": [ {...} ], "template_id": 982000000000143, "template_name": "Service - Classic", "created_time": "2013-11-18T02:17:40-0800", "last_modified_time": "2013-11-18T02:02:51-0800", "attachment_name": " ", "can_send_in_mail": true, "salesperson_id": " ", "salesperson_name": " ", "invoice_url": "https://invoice.zoho.com/SecurePayment?CInvoiceID=23d84d0cf64f9a72ea0c66fded25a08c8bafd0ab508aff05323a9f80e2cd03fdc5dd568d3d6407bbda969d3e870d740b6fce549a9438c4ea" } }
ARGUMENTS
|
customer_id
Required
ID of the customer the invoice has to be created.
contact_persons
Optional
Array of contact person(s) for whom invoice has to be sent.
invoice_number
Optional
Search invoices by invoice number.Variants:
invoice_number_startswith and invoice_number_contains. Max-length [100]
place_of_supply
India Edition only.
Optional
Place where the goods/services are supplied to. (If not given,
place of contact given for the contact will be taken)
vat_treatment
Optional
Enter vat treatment
gst_treatment
India Edition only.
Optional
Choose whether the contact is GST registered/unregistered/consumer/overseas. Allowed values are
business_gst , business_none , overseas , consumer .
gst_no
India Edition only.
Optional
15 digit GST identification number of the customer.
reference_number
Optional
The reference number of the invoice
template_id
Optional
ID of the pdf template associated with the invoice.
date
Optional
Search invoices by invoice date. Default date format is yyyy-mm-dd.
Variants: due_date_start, due_date_end, due_date_before and due_date_after.
payment_terms
Optional
Payment terms in days e.g. 15, 30, 60. Invoice due date will be calculated based on this. Max-length [100]
payment_terms_label
Optional
Used to override the default payment terms label. Default value for 15 days is "Net 15 Days". Max-length [100]
due_date
Optional
Search invoices by due date. Default date format is yyyy-mm-dd.
Variants: due_date_start, due_date_end, due_date_before and due_date_after
discount
Optional
Discount applied to the invoice. It can be either in % or in amount. e.g. 12.5% or 190. Max-length [100]
is_discount_before_tax
Optional
Used to specify how the discount has to applied. Either before or after the calculation of tax.
discount_type
Optional
How the discount is specified. Allowed values:
entity_level and item_level.
is_inclusive_tax
Optional
Used to specify whether the line item rates are inclusive or exclusivr of tax.
exchange_rate
Optional
Exchange rate of the currency.
recurring_invoice_id
Optional
ID of the recurring invoice from which the invoice is created.
invoiced_estimate_id
Optional
ID of the invoice from which the invoice is created.
salesperson_name
Optional
Name of the salesperson. Max-length [200]
custom_fields
Optional
Custom fields for an invoice.
project_id
Optional
line_items
Required
Line items of an invoice.
item_id
Optional
Search invoices by item id.
project_id
Optional
time_entry_ids
Optional
IDs of the time entries associated with the project.
product_type
Optional
Enter goods/services
hsn_or_sac
India Edition only
Optional
Add HSN/SAC code for your goods/services
warehouse_id
Optional
Enter warehouse ID
expense_id
Optional
expense_receipt_name
Optional
name
Optional
The name of the line item. Max-length [100]
item_order
Optional
The order of the line item_order
bcy_rate
Optional
base currency rate
rate
Optional
Rate of the line item.
quantity
Optional
The quantity of line item
unit
Optional
Unit of the line item e.g. kgs, Nos. Max-length [100]
discount_amount
Optional
The discount amount on the line item
discount
Optional
Discount applied to the invoice. It can be either in % or in amount. e.g. 12.5% or 190. Max-length [100]
tax_id
Optional
ID of the tax.
tax_name
Optional
The name of the tax
tax_type
Optional
The type of the tax
tax_percentage
Optional
The percentage of tax levied
item_total
Optional
The total amount of the line items
payment_options
Optional
Payment options for the invoice, online payment gateways and bank accounts. Will be displayed in the pdf.
allow_partial_payments
Optional
Boolean to check if partial payments are allowed for the contact
custom_body
Optional
custom_subject
Optional
notes
Optional
The notes added below expressing gratitude or for conveying some information.
terms
Optional
The terms added below expressing gratitude or for conveying some information.
shipping_charge
Optional
Shipping charges applied to the invoice. Max-length [100]
adjustment
Optional
Adjustments made to the invoice.
adjustment_description
Optional
Customize the adjustment description. E.g. Rounding off.
reason
Optional
tax_authority_id
US edition only
Optional
ID of the tax authority. Tax authority
depends on the location of the customer. For example, if the customer
is located in NY, then the tax authority is NY tax authority.
tax_exemption_id
India and US edition only
Optional
ID of the tax exemption.
avatax_use_code
Avalara integration only
Optional
Used to group like customers for
exemption purposes. It is a custom value that links customers to a tax
rule. Select from Avalara [standard codes][1] or enter a custom code.
Max-length [25]
avatax_exempt_no
Avalara integration only
Optional
Exemption certificate number of the customer. Max-length [25]
vat_treatment
Optional
Enter vat treatment
tax_id
Optional
ID of the tax.
custom_fields
Optional
Custom fields for an invoice.
item_id
Optional
Search invoices by item id.
expense_id
Optional
salesorder_item_id
Optional
ID of the sales order line item which is invoices.
name
Optional
The name of the line item. Max-length [100]
description
Optional
The description of the line items. Max-length [2000]
account_id
Optional
Account ID that has to be associated to the line item.
avatax_tax_code
Avalara integration only
Optional
A tax code is a unique label used to
group Items (products, services, or charges) together. Refer the
[link][2] for more deails. Max-length [25]
payment_gateways
Optional
Online payment gateways through which payment can be made.
gateway_name
Optional
Name of the payment gateway associated with the invoice. E.g. paypal, stripe.Allowed Values:
paypal, authorize_net, payflow_pro, stripe, 2checkout and braintree
additional_field1
Optional
Paypal payment method. Allowed Values:
standard and adaptive
line_item_id
Optional
The line item id
|
Query Params
|
ignore_auto_number_generation
Optional
Ignore auto invoice number generation for this invoice. This mandates the invoice number. Allowed values
true and false |
Get an invoice
Get the details of an invoice.
GET /invoices/:invoice_id
Request Example
$ curl https://books.zoho.com/api/v3/invoices/:invoice_id?organization_id=10234695 -H "Authorization: Zoho-authtoken ba4604e8e433g9c892e360d53463oec5" -H "Content-Type: application/json;charset=UTF-8"
Response Example
HTTP/1.1 200 OK Content-Type:application/json;charset=UTF-8 { "code": 0, "message": "success", "invoice": { "invoice": { "invoice_id": 982000000567114, "ach_payment_initiated": false, "invoice_number": "INV-00003", "is_pre_gst": true, "place_of_supply": "TN", "gst_no": "22AAAAA0000A1Z5", "gst_treatment": "business_gst", "date": "2013-11-17", "status": "draft", "payment_terms": 15, "payment_terms_label": "Net 15", "due_date": "2013-12-03", "payment_expected_date": " ", "last_payment_date": " ", "reference_number": " ", "customer_id": 982000000567001, "customer_name": "Bowman & Co", "contact_persons": [ "982000000870911", "982000000870915" ], "currency_id": 982000000000190, "currency_code": "USD", "exchange_rate": 1, "discount": 0, "is_discount_before_tax": true, "discount_type": "item_level", "is_inclusive_tax": false, "recurring_invoice_id": " ", "is_viewed_by_client": false, "has_attachment": false, "client_viewed_time": "", "line_items": [ { "line_item_id": 982000000567021, "item_id": 982000000030049, "project_id": " ", "time_entry_ids": [ {...} ], "warehouses": [ { "warehouse_id": "", "warehouse_name": "", "warehouse_stock_on_hand": "" } ], "item_type": "goods", "product_type": "goods", "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": 1, "unit": " ", "discount_amount": 0, "discount": 0, "tax_id": 982000000557028, "tax_name": "VAT", "tax_type": "tax", "tax_percentage": 12.5, "item_total": 120 } ], "shipping_charge": 0, "adjustment": 0, "adjustment_description": " ", "sub_total": 153, "tax_total": 22.6, "total": 40.6, "taxes": [ { "tax_name": "VAT", "tax_amount": 19.13 } ], "payment_reminder_enabled": true, "payment_made": 26.91, "credits_applied": 22.43, "tax_amount_withheld": 0, "balance": 40.6, "write_off_amount": 0, "allow_partial_payments": true, "price_precision": 2, "payment_options": {...}, "is_emailed": false, "reminders_sent": 1, "last_reminder_sent_date": " ", "billing_address": {...}, "shipping_address": {...}, "notes": "Looking forward for your business.", "terms": "Terms & Conditions apply", "custom_fields": [ {...} ], "template_id": 982000000000143, "template_name": "Service - Classic", "created_time": "2013-11-18T02:17:40-0800", "last_modified_time": "2013-11-18T02:02:51-0800", "attachment_name": " ", "can_send_in_mail": true, "salesperson_id": " ", "salesperson_name": " ", "invoice_url": "https://invoice.zoho.com/SecurePayment?CInvoiceID=23d84d0cf64f9a72ea0c66fded25a08c8bafd0ab508aff05323a9f80e2cd03fdc5dd568d3d6407bbda969d3e870d740b6fce549a9438c4ea" } } }
Query Params
|
print
Optional
Print the exported pdf.
accept
Optional
Get the details of a particular invoice in formats such as json/ pdf/ html. Default format is json. Allowed values
json pdf and html |
List invoices
List all invoices with pagination.
GET /invoices
Request Example
$ curl https://books.zoho.com/api/v3/invoices?organization_id=10234695 -H "Authorization: Zoho-authtoken ba4604e8e433g9c892e360d53463oec5" -H "Content-Type: application/json;charset=UTF-8"
Response Example
HTTP/1.1 200 OK Content-Type:application/json;charset=UTF-8 { "code": 0, "message": "success", "invoices": [ { "invoice_id": 982000000567114, "ach_payment_initiated": false, "customer_name": "Bowman & Co", "customer_id": 982000000567001, "status": "draft", "invoice_number": "INV-00003", "reference_number": " ", "date": "2013-11-17", "due_date": "2013-12-03", "due_days": "Due in 14 day(s)", "currency_id": 982000000000190, "schedule_time": "", "currency_code": "USD", "is_viewed_by_client": false, "has_attachment": false, "client_viewed_time": "", "total": 40.6, "balance": 40.6, "created_time": "2013-11-18T02:17:40-0800", "last_modified_time": "2013-11-18T02:02:51-0800", "is_emailed": false, "reminders_sent": 1, "last_reminder_sent_date": " ", "payment_expected_date": " ", "last_payment_date": " ", "custom_fields": [ {...} ], "documents": "", "salesperson_id": " ", "salesperson_name": " ", "shipping_charge": 0, "adjustment": 0, "write_off_amount": 0, "exchange_rate": 1 } ], "page_context": [ { "page": 1, "per_page": 200, "has_more_page": false, "report_name": "Invoices", "applied_filter": "Status.All", "sort_column": "created_time", "sort_order": "D" } ] }
Query Params
|
invoice_number
Optional
Search invoices by invoice number.Variants:
invoice_number_startswith and invoice_number_contains. Max-length [100]
item_name
Optional
Search invoices by item name.Variants:
item_name_startswith and item_name_contains. Max-length [100]
item_id
Optional
Search invoices by item id.
item_description
Optional
Search invoices by item description.Variants:
item_description_startswith and item_description_contains. Max-length [100]
reference_number
Optional
The reference number of the invoice
customer_name
Optional
The name of the customer. Max-length [100]
recurring_invoice_id
Optional
ID of the recurring invoice from which the invoice is created.
email
Optional
Search contacts by email id. Max-length [100]
total
Optional
The total amount to be paid
balance
Optional
The unpaid amount
custom_field
Optional
Search invoices by custom fields.Variants:
custom_field_startswith and custom_field_contains
date
Optional
Search invoices by invoice date. Default date format is yyyy-mm-dd.
Variants: due_date_start, due_date_end, due_date_before and due_date_after.
due_date
Optional
Search invoices by due date. Default date format is yyyy-mm-dd.
Variants: due_date_start, due_date_end, due_date_before and due_date_after
status
Optional
Search invoices by invoice status.Allowed Values:
sent, draft, overdue, paid, void, unpaid, partially_paid and viewed
customer_id
Optional
ID of the customer the invoice has to be created.
filter_by
Optional
Filter 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
search_text
Optional
Search invoices by invoice number or purchase order or customer name. Max-length [100]
sort_column
Optional
Sort invoices.Allowed Values:
customer_name, invoice_number, date, due_date, total, balance and created_time |
Delete an invoice
Delete an existing invoice. Invoices which have payment or credits note applied cannot be deleted.
DELETE /invoices/:invoice_id
Request Example
$ curl https://books.zoho.com/api/v3/invoices/:invoice_id?organization_id=10234695 -H "Authorization: Zoho-authtoken ba4604e8e433g9c892e360d53463oec5" -H "Content-Type: application/json;charset=UTF-8"
Response Example
HTTP/1.1 200 OK Content-Type:application/json;charset=UTF-8 { "code": 0, "message": "The invoice has been deleted." }
Mark an invoice as sent
Mark a draft invoice as sent.
POST /invoices/:invoice_id/status/sent
Request Example
$ curl https://books.zoho.com/api/v3/invoices/:invoice_id/status/sent?organization_id=10234695 -H "Authorization: Zoho-authtoken ba4604e8e433g9c892e360d53463oec5" -H "Content-Type: application/json;charset=UTF-8"
Response Example
HTTP/1.1 200 OK Content-Type:application/json;charset=UTF-8 { "code": 0, "message": "Invoice status has been changed to Sent." }
Void an invoice
Mark an invoice status as void. Upon voiding, the payments and credits associated with the invoices will be unassociated and will be under customer credits.
POST /invoices/:invoice_id/status/void
Request Example
$ curl https://books.zoho.com/api/v3/invoices/:invoice_id/status/void?organization_id=10234695 -H "Authorization: Zoho-authtoken ba4604e8e433g9c892e360d53463oec5" -H "Content-Type: application/json;charset=UTF-8"
Response Example
HTTP/1.1 200 OK Content-Type:application/json;charset=UTF-8 { "code": 0, "message": "Invoice status has been changed to Void." }
Mark as draft
Mark a voided invoice as draft.
POST /invoices/:invoice_id/status/draft
Request Example
$ curl https://books.zoho.com/api/v3/invoices/:invoice_id/status/draft?organization_id=10234695 -H "Authorization: Zoho-authtoken ba4604e8e433g9c892e360d53463oec5" -H "Content-Type: application/json;charset=UTF-8"
Response Example
HTTP/1.1 200 OK Content-Type:application/json;charset=UTF-8 { "code": 0, "message": "Status of invoice changed from void to draft" }
Email an invoice
Email an invoice to the customer. Input json string is not mandatory. If input json string is empty, mail will be send with default mail content.
POST /invoices/:invoice_id/email
Request Example
$ curl https://books.zoho.com/api/v3/invoices/:invoice_id/email?organization_id=10234695 -H "Authorization: Zoho-authtoken ba4604e8e433g9c892e360d53463oec5" -H "Content-Type: application/json;charset=UTF-8" -d '{ "send_from_org_email_id": false, "to_mail_ids": [ "willsmith@bowmanfurniture.com" ], "cc_mail_ids": [ "peterparker@bowmanfurniture.com" ], "subject": "Invoice from Zillium Inc (Invoice#: INV-00001)", "body": "Dear Customer, <br><br><br><br>Thanks for your business. <br><br><br><br>The invoice INV-00001 is attached with this email. You can choose the easy way out and <a href= https://invoice.zoho.com/SecurePayment?CInvoiceID=b9800228e011ae86abe71227bdacb3c68e1af685f647dcaed747812e0b9314635e55ac6223925675b371fcbd2d5ae3dc >pay online for this invoice.</a> <br><br>Here's an overview of the invoice for your reference. <br><br><br><br>Invoice Overview: <br><br>Invoice : INV-00001 <br><br>Date : 05 Aug 2013 <br><br>Amount : $541.82 <br><br><br><br>It was great working with you. Looking forward to working with you again.<br><br><br>\\nRegards<br>\\nZillium Inc<br>\\n\"," }
Response Example
HTTP/1.1 200 OK Content-Type:application/json;charset=UTF-8 { "code": 0, "message": "Your invoice has been sent." }
ARGUMENTS
|
send_from_org_email_id
Optional
Boolean to trigger the email from the organization's email address
to_mail_ids
Required
Array of email address of the recipients.
cc_mail_ids
Optional
Array of email address of the recipients to be cced.
subject
Optional
The subject of the mail
body
Optional
The body of the mail
|
Query Params
|
send_customer_statement
Optional
Send customer statement pdf a with email.
send_attachment
Optional
Send the invoice attachment a with the email.
attachments
Optional
Files to be attached to the email
|
Email invoices
Send invoices to your customers by email. Maximum of 10 invoices can be sent at once.
POST /invoices/email
Request Example
$ curl https://books.zoho.com/api/v3/invoices/email?organization_id=10234695 -H "Authorization: Zoho-authtoken ba4604e8e433g9c892e360d53463oec5" -H "Content-Type: application/json;charset=UTF-8" -d '{ "contacts": [ {} ], "contact_id": 460000000026049 }
Response Example
HTTP/1.1 200 OK Content-Type:application/json;charset=UTF-8 { "code": 0, "message": "Mission accomplished! We've sent all the invoices." }
ARGUMENTS
|
contacts
Optional
Contacts for whom email or snail mail has to be sent.
contact_id
Required
ID of the contact. Can specify if email or snail mail has to be sent for each contact.
|
Query Params
|
invoice_ids
Required
Comma separated invoice ids which are to be emailed.
|
Get invoice email content
Get the email content of an invoice.
GET /invoices/{:invoice_id}/email
Request Example
$ curl https://books.zoho.com/api/v3/invoices/{:invoice_id}/email?organization_id=10234695 -H "Authorization: Zoho-authtoken ba4604e8e433g9c892e360d53463oec5" -H "Content-Type: application/json;charset=UTF-8"
Response Example
HTTP/1.1 200 OK Content-Type:application/json;charset=UTF-8 { "code": 0, "message": "success", "data": { "bcc_mails": [ {...} ], "gateways_configured": true, "gateways_associated": true, "bcc_mails_str": "", "body": "Dear Customer, <br><br><br><br>Thanks for your business. <br><br><br><br>The invoice INV-00001 is attached with this email. You can choose the easy way out and <a href= https://invoice.zoho.com/SecurePayment?CInvoiceID=b9800228e011ae86abe71227bdacb3c68e1af685f647dcaed747812e0b9314635e55ac6223925675b371fcbd2d5ae3dc >pay online for this invoice.</a> <br><br>Here's an overview of the invoice for your reference. <br><br><br><br>Invoice Overview: <br><br>Invoice : INV-00001 <br><br>Date : 05 Aug 2013 <br><br>Amount : $541.82 <br><br><br><br>It was great working with you. Looking forward to working with you again.<br><br><br>\\nRegards<br>\\nZillium Inc<br>\\n\",", "documents": "", "customer_name": "Bowman & Co", "attach_pdf": true, "entity_id": "2000000007037", "cc_mails_list": [ { "user_name": "Sujin Kumar" } ], "file_name_without_extension": "INV-000004", "to_mails_str": "", "cc_mails_str": "", "from_email": "", "from_address": "", "deprecated_placeholders_used": [ {...} ], "error_list": [ {...} ], "subject": "Invoice from Zillium Inc (Invoice#: INV-00001)", "emailtemplates": [ { "selected": true, "name": "Hard Drive" } ], "emailtemplate_documents": [ {...} ], "to_contacts": [ { "first_name": "Sujin", "selected": true, "phone": "+1-925-921-9201", "last_name": "Kumar", "salutation": "Mr", "contact_person_id": 982000000567003, "mobile": "+1-4054439562" } ], "attachment_name": " ", "file_name": "INV-00001.pdf", "from_emails": [ { "user_name": "Sujin Kumar", "selected": true, "organization_contact_id": "2000000002266", "is_org_email_id": true } ], "customer_id": 982000000567001 } }
Query Params
|
email_template_id
Optional
Get the email content based on a
specific email template. If this param is not inputted, then the content
will be based on the email template associated with the customer. If no
template is associated with the customer, then default template will be
used.
|
Remind Customer
Remind your customer about an unpaid invoice by email. Reminder will be sent, only for the invoices which are in open or overdue status.
POST /invoices/{:invoice_id}/paymentreminder
Request Example
$ curl https://books.zoho.com/api/v3/invoices/{:invoice_id}/paymentreminder?organization_id=10234695 -H "Authorization: Zoho-authtoken ba4604e8e433g9c892e360d53463oec5" -H "Content-Type: application/json;charset=UTF-8" -d '{ "to_mail_ids": [ "willsmith@bowmanfurniture.com" ], "cc_mail_ids": [ "peterparker@bowmanfurniture.com" ], "subject": "Invoice from Zillium Inc (Invoice#: INV-00001)", "body": "<br>Dear Mr. Sujin, <br><br>You might have missed the payment date and the invoice is now overdue by 1 days.<br><br>----------------------------------------------------------------------------------------<br><h2>Invoice# : INV-000004 </h2>Dated : 23 Dec 2016<br>----------------------------------------------------------------------------------------<br><b> Due Date : 23 Dec 2016</b><br><b> Amount : $139.65</b><br>----------------------------------------------------------------------------------------<br><br><span>Not to worry at all ! </span>View your invoice and take the easy way out by making an <a href=\"https://books.zoho.com/portal/zilliuminc/index#/invoices/invoice/2000000007037 \">online payment</a>.<br><br>If you have already paid, please accept our apologies and kindly ignore this payment reminder.<br><br><br>Regards,<br><br>David Sujin<br>Zillium Inc<br><br><br>", "send_from_org_email_id": false }
Response Example
HTTP/1.1 200 OK Content-Type:application/json;charset=UTF-8 { "code": 0, "message": "Your payment reminder has been sent." }
ARGUMENTS
|
to_mail_ids
Optional
Array of email address of the recipients.
cc_mail_ids
Required
Array of email address of the recipients to be cced.
subject
Optional
The subject of the mail
body
Optional
The body of the mail
send_from_org_email_id
Optional
Boolean to trigger the email from the organization's email address
|
Query Params
|
send_customer_statement
Optional
Send customer statement pdf a with email.
attachments
Optional
Files to be attached to the email
|
Bulk invoice reminder
Remind your customer about an unpaid invoices by email. Reminder mail will be send, only for the invoices is in open or overdue status. Maximum 10 invoices can be reminded at once.
POST /invoices/paymentreminder
Request Example
$ curl https://books.zoho.com/api/v3/invoices/paymentreminder?organization_id=10234695 -H "Authorization: Zoho-authtoken ba4604e8e433g9c892e360d53463oec5" -H "Content-Type: application/json;charset=UTF-8"
Response Example
HTTP/1.1 201 Created Content-Type:application/json;charset=UTF-8 { "code": 0, "message": "success", "info": { "email_success_info": { "message": "The reminders were successfully sent", "sent_count": 2 }, "email_errors_info": [ { "message": "The reminders were successfully sent", "ids": [ {...} ] } ], "code": 4083 } }
Query Params
|
invoice_ids
Required
Array of invoice ids for which the reminder has to be sent.
|
Get payment reminder mail content
Get the mail content of the payment reminder.
GET /invoices/{:invoice_id}/paymentreminder
Request Example
$ curl https://books.zoho.com/api/v3/invoices/{:invoice_id}/paymentreminder?organization_id=10234695 -H "Authorization: Zoho-authtoken ba4604e8e433g9c892e360d53463oec5" -H "Content-Type: application/json;charset=UTF-8"
Response Example
HTTP/1.1 200 OK Content-Type:application/json;charset=UTF-8 { "code": 0, "message": "success", "data": { "bcc_mails": [ {...} ], "gateways_configured": true, "gateways_associated": true, "bcc_mails_str": "", "body": "<br>Dear Mr. Sujin, <br><br>You might have missed the payment date and the invoice is now overdue by 1 days.<br><br>----------------------------------------------------------------------------------------<br><h2>Invoice# : INV-000004 </h2>Dated : 23 Dec 2016<br>----------------------------------------------------------------------------------------<br><b> Due Date : 23 Dec 2016</b><br><b> Amount : $139.65</b><br>----------------------------------------------------------------------------------------<br><br><span>Not to worry at all ! </span>View your invoice and take the easy way out by making an <a href=\"https://books.zoho.com/portal/zilliuminc/index#/invoices/invoice/2000000007037 \">online payment</a>.<br><br>If you have already paid, please accept our apologies and kindly ignore this payment reminder.<br><br><br>Regards,<br><br>David Sujin<br>Zillium Inc<br><br><br>", "documents": "", "customer_name": "Bowman & Co", "attach_pdf": true, "entity_id": "2000000007037", "cc_mails_list": [ { "user_name": "Sujin Kumar" } ], "file_name_without_extension": "INV-000004", "to_mails_str": "", "cc_mails_str": "", "from_email": "", "from_address": "", "deprecated_placeholders_used": [ {...} ], "error_list": [ {...} ], "subject": "Invoice from Zillium Inc (Invoice#: INV-00001)", "emailtemplates": [ { "selected": true, "name": "Hard Drive" } ], "emailtemplate_documents": [ {...} ], "to_contacts": [ { "first_name": "Sujin", "selected": true, "phone": "+1-925-921-9201", "last_name": "Kumar", "salutation": "Mr", "contact_person_id": 982000000567003, "mobile": "+1-4054439562" } ], "attachment_name": " ", "file_name": "INV-00001.pdf", "from_emails": [ { "user_name": "Sujin Kumar", "selected": true, "organization_contact_id": "2000000002266", "is_org_email_id": true } ], "customer_id": 982000000567001 } }
Bulk export Invoices
Maximum of 25 invoices can be exported in a single pdf.
GET /invoices/pdf
Request Example
$ curl https://books.zoho.com/api/v3/invoices/pdf?organization_id=10234695 -H "Authorization: Zoho-authtoken ba4604e8e433g9c892e360d53463oec5" -H "Content-Type: application/json;charset=UTF-8"
Response Example
HTTP/1.1 200 OK Content-Type:application/json;charset=UTF-8 { "code": 0, "message": "success" }
Query Params
|
invoice_ids
Required
Comma separated invoice ids which are to be export as pdf.
|
Bulk print invoices
Export invoices as pdf and print them. Maximum of 25 invoices can be printed.
GET /invoices/print
Request Example
$ curl https://books.zoho.com/api/v3/invoices/print?organization_id=10234695 -H "Authorization: Zoho-authtoken ba4604e8e433g9c892e360d53463oec5" -H "Content-Type: application/json;charset=UTF-8"
Response Example
HTTP/1.1 200 OK Content-Type:application/json;charset=UTF-8 { "code": 0, "message": "success" }
Query Params
|
invoice_ids
Required
Export invoices as pdf and print them. Maximum of 25 invoices can be printed.
|
Disable payment reminder
Disable automated payment reminders for an invoice.
POST /invoices/{:invoice_id}/paymentreminder/disable
Request Example
$ curl https://books.zoho.com/api/v3/invoices/{:invoice_id}/paymentreminder/disable?organization_id=10234695 -H "Authorization: Zoho-authtoken ba4604e8e433g9c892e360d53463oec5" -H "Content-Type: application/json;charset=UTF-8"
Response Example
HTTP/1.1 200 OK Content-Type:application/json;charset=UTF-8 { "code": 0, "message": "Reminders stopped." }
Enable payment reminder
Enable automated payment reminders for an invoice.
POST /invoices/{:invoice_id}/paymentreminder/enable
Request Example
$ curl https://books.zoho.com/api/v3/invoices/{:invoice_id}/paymentreminder/enable?organization_id=10234695 -H "Authorization: Zoho-authtoken ba4604e8e433g9c892e360d53463oec5" -H "Content-Type: application/json;charset=UTF-8"
Response Example
HTTP/1.1 200 OK Content-Type:application/json;charset=UTF-8 { "code": 0, "message": "Reminders enabled." }
Write off invoice
Write off the invoice balance amount of an invoice.
POST /invoices/{:invoice_id}/writeoff
Request Example
$ curl https://books.zoho.com/api/v3/invoices/{:invoice_id}/writeoff?organization_id=10234695 -H "Authorization: Zoho-authtoken ba4604e8e433g9c892e360d53463oec5" -H "Content-Type: application/json;charset=UTF-8"
Response Example
HTTP/1.1 200 OK Content-Type:application/json;charset=UTF-8 { "code": 0, "message": "Invoice has been written off" }
Cancel write off
Cancel the write off amount of an invoice.
POST /invoices/{:invoice_id}/writeoff/cancel
Request Example
$ curl https://books.zoho.com/api/v3/invoices/{:invoice_id}/writeoff/cancel?organization_id=10234695 -H "Authorization: Zoho-authtoken ba4604e8e433g9c892e360d53463oec5" -H "Content-Type: application/json;charset=UTF-8"
Response Example
HTTP/1.1 200 OK Content-Type:application/json;charset=UTF-8 { "code": 0, "message": "The write off done for this invoice has been cancelled." }
Update billing address
Updates the billing address for this invoice alone.
PUT /invoices/{:invoice_id}/address/billing
Request Example
$ curl https://books.zoho.com/api/v3/invoices/{:invoice_id}/address/billing?organization_id=10234695 -H "Authorization: Zoho-authtoken ba4604e8e433g9c892e360d53463oec5" -H "Content-Type: application/json;charset=UTF-8" -d '{ "address": "B-1104, 11F, \nHorizon International Tower, \nNo. 6, ZhiChun Road, HaiDian District", "city": "Beijing", "state": "Beijing", "zip": 1000881, "fax": "+86-10-82637827" }
Response Example
HTTP/1.1 200 OK Content-Type:application/json;charset=UTF-8 { "code": 0, "message": "Billing address updated" }
ARGUMENTS
|
address
Optional
Billing address for the invoice
city
Optional
City of the customer’s billing address.
state
Optional
State of the customer’s billing address.
zip
Optional
Zip code of the customer’s billing address.
country
Optional
Country of the customer’s billing address.
fax
Optional
Customer's fax number.
|
Update shipping address
Updates the shipping address for this invoice alone.
PUT /invoices/{:invoice_id}/address/shipping
Request Example
$ curl https://books.zoho.com/api/v3/invoices/{:invoice_id}/address/shipping?organization_id=10234695 -H "Authorization: Zoho-authtoken ba4604e8e433g9c892e360d53463oec5" -H "Content-Type: application/json;charset=UTF-8" -d '{ "address": "4900 Hopyard Rd, Suit 310", "city": "Pleasanton", "state": "CA", "zip": 945881, "country": "USA", "fax": "+1-925-924-9600" }
Response Example
HTTP/1.1 200 OK Content-Type:application/json;charset=UTF-8 { "code": 0, "message": "Shipping address updated" }
ARGUMENTS
|
address
Optional
Billing address for the invoice
city
Optional
City of the customer’s billing address.
state
Optional
State of the customer’s billing address.
zip
Optional
Zip code of the customer’s billing address.
country
Optional
Country of the customer’s billing address.
fax
Optional
Customer's fax number.
|
List invoice templates
Get all invoice pdf templates.
Get /invoices/templates
Request Example
$ curl https://books.zoho.com/api/v3/invoices/templates?organization_id=10234695 -H "Authorization: Zoho-authtoken ba4604e8e433g9c892e360d53463oec5" -H "Content-Type: application/json;charset=UTF-8"
Response Example
HTTP/1.1 200 OK Content-Type:application/json;charset=UTF-8 { "code": 0, "message": "success", "templates": [ { "template_name": "Service - Classic", "template_id": 982000000000143, "template_type": "classic" } ] }
Update invoice template
Update the pdf template associated with the invoice.
PUT /invoices/{:invoice_id}/templates/{:template_id}
Request Example
$ curl https://books.zoho.com/api/v3/invoices/{:invoice_id}/templates/{:template_id}?organization_id=10234695 -H "Authorization: Zoho-authtoken ba4604e8e433g9c892e360d53463oec5" -H "Content-Type: application/json;charset=UTF-8"
Response Example
HTTP/1.1 200 OK Content-Type:application/json;charset=UTF-8 { "code": 0, "message": "Invoice information has been updated." }
List invoice payments
Get the list of payments made for an invoice.
GET /invoices/{:invoice_id}/payments
Request Example
$ curl https://books.zoho.com/api/v3/invoices/{:invoice_id}/payments?organization_id=10234695 -H "Authorization: Zoho-authtoken ba4604e8e433g9c892e360d53463oec5" -H "Content-Type: application/json;charset=UTF-8"
Response Example
HTTP/1.1 200 OK Content-Type:application/json;charset=UTF-8 { "code": 0, "message": "success", "payments": [ { "payment_id": 982000000567190, "payment_number": 7, "invoice_id": 982000000567114, "invoice_payment_id": 982000000567192, "payment_mode": "cash", "description": "500GB, USB 2.0 interface 1400 rpm, protective hard case.", "date": "2013-11-17", "reference_number": " ", "exchange_rate": 1, "amount": 10.57, "tax_amount_withheld": 0, "online_transaction_id": "", "is_single_invoice_payment": true } ] }
List credits applied
Get the list of credits applied for an invoice.
GET /invoices/{:invoice_id}/creditsapplied
Request Example
$ curl https://books.zoho.com/api/v3/invoices/{:invoice_id}/creditsapplied?organization_id=10234695 -H "Authorization: Zoho-authtoken ba4604e8e433g9c892e360d53463oec5" -H "Content-Type: application/json;charset=UTF-8"
Response Example
HTTP/1.1 200 OK Content-Type:application/json;charset=UTF-8 { "code": 0, "message": "success", "credits": [ { "creditnote_id": 982000000567134, "creditnotes_invoice_id": "982000000567172", "creditnotes_number": "CN-00001", "credited_date": "2013-11-18", "amount_applied": 12.2 } ] }
Apply credits
Apply the customer credits either from credit notes or excess customer payments to an invoice. Multiple credits can be applied at once.
POST /invoices/{:invoice_id}/credits
Request Example
$ curl https://books.zoho.com/api/v3/invoices/{:invoice_id}/credits?organization_id=10234695 -H "Authorization: Zoho-authtoken ba4604e8e433g9c892e360d53463oec5" -H "Content-Type: application/json;charset=UTF-8" -d '{ "invoice_payments": [ { "payment_id": 982000000567190, "amount_applied": 12.2 } ], "apply_creditnotes": [ { "creditnote_id": 982000000567134, "amount_applied": 12.2 } ], "payment_id": 982000000567190, "amount_applied": 12.2, "creditnote_id": 982000000567134 }
Response Example
HTTP/1.1 200 OK Content-Type:application/json;charset=UTF-8 { "code": 0, "message": "Credits have been applied to the invoice(s)." }
ARGUMENTS
|
invoice_payments
Optional
payment_id
Optional
The id of the payment
amount_applied
Optional
The applied amount to the creditnote
apply_creditnotes
Optional
creditnote_id
Optional
The id of creditnote
amount_applied
Optional
The applied amount to the creditnote
payment_id
Optional
The id of the payment
amount_applied
Optional
The applied amount to the creditnote
creditnote_id
Optional
The id of creditnote
|
Delete a payment
Delete a payment made to an invoice.
DELETE /invoices/{:invoice_id}/payments/{:invoice_payment_id}
Request Example
$ curl https://books.zoho.com/api/v3/invoices/{:invoice_id}/payments/{:invoice_payment_id}?organization_id=10234695 -H "Authorization: Zoho-authtoken ba4604e8e433g9c892e360d53463oec5" -H "Content-Type: application/json;charset=UTF-8"
Response Example
HTTP/1.1 200 OK Content-Type:application/json;charset=UTF-8 { "code": 0, "message": "The payment has been deleted." }
Delete applied credit
Delete a particular credit applied to an invoice.
DELETE /invoices/{:invoice_id}/creditsapplied/{:creditnotes_invoice_id}
Request Example
$ curl https://books.zoho.com/api/v3/invoices/{:invoice_id}/creditsapplied/{:creditnotes_invoice_id}?organization_id=10234695 -H "Authorization: Zoho-authtoken ba4604e8e433g9c892e360d53463oec5" -H "Content-Type: application/json;charset=UTF-8"
Response Example
HTTP/1.1 200 OK Content-Type:application/json;charset=UTF-8 { "code": 0, "message": "Credits applied to an invoice have been deleted." }
Get an invoice attachment
Returns the file attached to the invoice.
GET /invoices/{:invoice_id}/attachment
Request Example
$ curl https://books.zoho.com/api/v3/invoices/{:invoice_id}/attachment?organization_id=10234695 -H "Authorization: Zoho-authtoken ba4604e8e433g9c892e360d53463oec5" -H "Content-Type: application/json;charset=UTF-8"
Response Example
HTTP/1.1 200 OK Content-Type:application/json;charset=UTF-8 { "code": 0, "message": "success" }
Query Params
|
preview
Optional
Get the thumbnail of the attachment.
|
Add attachment to an invoice
Attach a file to an invoice.
POST /invoices/{:invoice_id}/attachment
Request Example
$ curl https://books.zoho.com/api/v3 /invoices/{:invoice_id}/attachment?organization_id=10234695 -H "Authorization: Zoho-authtoken ba4604e8e433g9c892e360d53463oec5" -H "Content-Type: application/json;charset=UTF-8"
Response Example
HTTP/1.1 200 OK Content-Type:application/json;charset=UTF-8 { "code": 0, "message": "Your file has been successfully attached to the invoice." }
Query Params
|
can_send_in_mail
Optional
True to send the attachment with the invoice when emailed.
attachment
Optional
The file to be attached.Allowed Extensions:
gif, png, jpeg, jpg, bmp and pdf |
Update attachment preference
Set whether you want to send the attached file while emailing the invoice.
PUT /invoices/{:invoice_id}/attachment
Request Example
$ curl https://books.zoho.com/api/v3 /invoices/{:invoice_id}/attachment?organization_id=10234695 -H "Authorization: Zoho-authtoken ba4604e8e433g9c892e360d53463oec5" -H "Content-Type: application/json;charset=UTF-8"
Response Example
HTTP/1.1 200 OK Content-Type:application/json;charset=UTF-8 { "code": 0, "message": "Invoice information has been updated." }
Query Params
|
can_send_in_mail
Required
Boolean to send the attachment with the invoice when emailed.
|
Delete an attachment
Delete the file attached to the invoice.
DELETE /invoices/{:invoice_id}/attachment
Request Example
$ curl https://books.zoho.com/api/v3/invoices/{:invoice_id}/attachment?organization_id=10234695 -H "Authorization: Zoho-authtoken ba4604e8e433g9c892e360d53463oec5" -H "Content-Type: application/json;charset=UTF-8"
Response Example
HTTP/1.1 200 OK Content-Type:application/json;charset=UTF-8 { "code": 0, "message": "Your file is no longer attached to the invoice." }
Delete the expense receipt
Delete the expense receipts attached to an invoice which is raised from an expense.
DELETE /invoices/expenses/{:expense_id}/receipt
Request Example
$ curl https://books.zoho.com/api/v3 /invoices/expenses/{:expense_id}/receipt?organization_id=10234695 -H "Authorization: Zoho-authtoken ba4604e8e433g9c892e360d53463oec5" -H "Content-Type: application/json;charset=UTF-8"
Response Example
HTTP/1.1 200 OK Content-Type:application/json;charset=UTF-8 { "code": 0, "message": "The attached expense receipt has been deleted." }
List invoice comments & history
Get the complete history and comments of an invoice.
GET /invoices/{:invoice_id}/comments
Request Example
$ curl https://books.zoho.com/api/v3 /invoices/{:invoice_id}/comments?organization_id=10234695 -H "Authorization: Zoho-authtoken ba4604e8e433g9c892e360d53463oec5" -H "Content-Type: application/json;charset=UTF-8"
Response Example
HTTP/1.1 200 OK Content-Type:application/json;charset=UTF-8 { "code": 0, "message": "success", "comments": [ { "comments": [ { "comment_id": 982000000567019, "invoice_id": 982000000567114, "description": "500GB, USB 2.0 interface 1400 rpm, protective hard case.", "commented_by_id": 982000000554041, "commented_by": "John David", "comment_type": "system", "operation_type": "Added", "date": "2013-11-17", "date_description": "yesterday", "time": "2:02 AM", "transaction_id": " ", "transaction_type": "invoice" } ] }, {...}, {...} ] }
Add comment
Add a comment for an invoice.
POST /invoices/{:invoice_id}/comments
Request Example
$ curl https://books.zoho.com/api/v3/invoices/{:invoice_id}/comments?organization_id=10234695 -H "Authorization: Zoho-authtoken ba4604e8e433g9c892e360d53463oec5" -H "Content-Type: application/json;charset=UTF-8"
Response Example
HTTP/1.1 200 OK Content-Type:application/json;charset=UTF-8 { "code": 0, "message": "Comments added." }
Query Params
|
description
Optional
The description of the line items. Max-length [2000]
payment_expected_date
Optional
The expected date of payment
show_comment_to_clients
Optional
Boolean to check if the comment to be shown to the clients
|
Update comment
Update an existing comment of an invoice.
PUT /invoices/{:invoice_id}/comments/:comment_id
Request Example
$ curl https://books.zoho.com/api/v3/invoices/{:invoice_id}/comments/:comment_id?organization_id=10234695 -H "Authorization: Zoho-authtoken ba4604e8e433g9c892e360d53463oec5" -H "Content-Type: application/json;charset=UTF-8"
Response Example
HTTP/1.1 200 OK Content-Type:application/json;charset=UTF-8 { "code": 0, "message": "success", "comment": { "comment_id": 982000000567019, "invoice_id": 982000000567114, "description": "500GB, USB 2.0 interface 1400 rpm, protective hard case.", "commented_by_id": 982000000554041, "commented_by": "John David", "date": "2013-11-17", "date_description": "yesterday", "time": "2:02 AM", "comment_type": "system" } }
Query Params
|
description
Optional
The comment on a invoice
show_comment_to_clients
Optional
Boolean to check if the comment to be shown to the clients
|
Delete a comment
Delete an invoice comment.
DELETE /invoices/{:invoice_id}/comments/{:comment_id}
Request Example
$ curl https://books.zoho.com/api/v3/invoices/{:invoice_id}/comments/{:comment_id}?organization_id=10234695 -H "Authorization: Zoho-authtoken ba4604e8e433g9c892e360d53463oec5" -H "Content-Type: application/json;charset=UTF-8"
Response Example
HTTP/1.1 200 OK Content-Type:application/json;charset=UTF-8 { "code": 0, "message": "The comment has been deleted." }
Recurring-Invoices
Recurring invoices are invoices that are created and sent to your customers on a recurring schedule.
Example
{ "recurring_invoice_id": "90300000072369", "recurrence_name": "MonthlyInvoice", "customer_name": "Sujin Kumar", "customer_id": "903000000000099", "date": "2016-06-05", "start_date": "2016-06-12", "end_date": "2017-06-12", "last_sent_date": "2016-06-12", "next_invoice_date": "2016-06-17", "recurrence_frequency": "weeks", "repeat_every": 2, "status": "active", "email": "benjamin.george@bowmanfurniture.com", "item_id": "90300000081501", "description": "prorated amount for items", "type": 1, "quantity": 1, "price": 100, "item_total": 100, "currency_id": "982000000000190", "currency_code": "USD", "created_time": "2016-06-05T02:30:08-0700", "updated_time": "2016-06-05T02:30:08-0700", "contact_persons": [ "90300000065322" ], "exchange_rate": "5.5", "notes": "Offer for the referral", "terms": "", "tax_name": "Basic Tax", "tax_percentage": "10%", "tax_amount": "2.50", "recurring_invoice_items": [ { "item_id": "90300000081501", "description": "prorated amount for items", "quantity": 1, "price": 100, "item_total": 100 } ] }
Attribute
|
recurring_invoice_id
string
Unique ID of the recurring invoice generated by the server.
recurrence_name
string
Unique name for the recurring profile given by the user. Max-length [100]
customer_name
string
Name of the customer to whom the recurring invoice is raised.
customer_id
string
Customer ID of the customer for whom the recurring invoice is raised.
date
string
The date on which recurring invoice is raised.
start_date
string
The date on which the recurring invoice starts.
end_date
string
The date on which the recurring invoice expires.
last_sent_date
string
The date at which the last invoice was sent.
next_invoice_date
string
The date at which next invoice is to be sent.
recurrence_frequency
enum
The frequency of time interval at which the invoice is to be generated.
repeat_every
integer
The period between every recurrency frequency.
status
string
Status of the recurring invoice. This can be
active, stopped or expired.
email
string
Email address of the customer.
item_id
string
Unique string generated for the item for which invoice is to be sent.
description
required
A small description about the item. Max-length [2000]
type
integer
Type of the recurring invoice line item.
quantity
required
Quantity of the item included.
price
double
The price of the item included.
item_total
double
Total rate raised by this item. This would be the multiplicative product of item price and quantity.
currency_id
string
The currenct id of the currency
currency_code
string
The currency code in which the invoice is created.
created_time
string
Time at which the recurring invoice was created.
updated_time
string
Time at which the recurring invoice details were last updated.
contact_persons
array
Contact Persons associated with the recurring invoice.
exchange_rate
string
Exchange rate for the currency associated with the customer.
notes
string
A short note for the recurring invoice.
terms
string
Terms & condition to be displayed in the recurring invoice.
tax_name
string
Unique name for tax.
tax_percentage
string
Percentage of tax
tax_amount
string
Tax amount applied to the subscription.
recurring_invoice_items
list
item_id
string
Unique string generated for the item for which invoice is to be sent.
description
required
A small description about the item. Max-length [2000]
quantity
required
Quantity of the item included.
price
double
The price of the item included.
item_total
double
Total rate raised by this item. This would be the multiplicative product of item price and quantity.
|
Create a Recurring Invoice
Creating a new recurring invoice.
POST /recurringinvoices
Request Example
$ curl https://books.zoho.com/api/v3/recurringinvoices?organization_id=10234695 -H "Authorization: Zoho-authtoken ba4604e8e433g9c892e360d53463oec5" -H "Content-Type: application/json;charset=UTF-8" -d '{ "recurrence_name": "MonthlyInvoice", "reference_number": "12314", "customer_id": "903000000000099", "contact_persons": [ "90300000065322" ], "place_of_supply": "TN", "gst_treatment": "business_gst", "gst_no": "22AAAAA0000A1Z5", "start_date": "2016-06-12", "end_date": "2017-06-12", "recurrence_frequency": "weeks", "repeat_every": 2, "line_items": [ { "line_item_id": "982000000567021", "quantity": 1, "name": "Hard Drive", "item_total": 100, "product_type": "goods", "hsn_or_sac": 80540, "warehouse_id": "" } ], "tax_id": "903000000000356", "email": "benjamin.george@bowmanfurniture.com", "billing_address": { "address": "4900 Hopyard Rd, Suite 310", "street2": "McMillan Avenue", "city": "Pleasanton", "state": "CA", "zip": "94588", "country": "U.S.A", "fax": "+1-925-924-9600" }, "shipping_address": { "address": "4900 Hopyard Rd, Suite 310", "city": "Pleasanton", "state": "CA", "zip": "94588", "country": "U.S.A", "fax": "+1-925-924-9600" }, "payment_gateways": [ { "configured": true, "additional_field1": "standard", "gateway_name": "paypal" } ], "template_id": "90300000001336", "payment_terms": 0, "payment_terms_label": "Next 15 days", "tax_authority_id": "903000006345", "tax_exemption_id": "903000006345", "exchange_rate": "5.5", "payment_options": { "payment_gateways": [ { "configured": true, "additional_field1": "standard", "gateway_name": "paypal" } ] }, "gateway_name": "paypal", "additional_field1": "standard", "discount": "30%", "is_discount_before_tax": true, "discount_type": "entity level", "is_inclusive_tax": false, "item_id": "90300000081501", "name": "Hard Drive", "description": "prorated amount for items", "rate": 0, "quantity": 1, "unit": "kgs", "avatax_tax_code": " ", "salesperson_name": " ", "shipping_charge": 0, "adjustment": 0, "adjustment_description": "Rounding off" }
Response Example
HTTP/1.1 201 Created Content-Type:application/json;charset=UTF-8 { "code": 0, "message": "The recurring invoice has been created.", "recurring_invoice": { "recurring_invoice": { "recurring_invoice_id": "90300000072369", "recurrence_name": "MonthlyInvoice", "reference_number": "12314", "customer_name": "Sujin Kumar", "is_pre_gst": false, "gst_no": "22AAAAA0000A1Z5", "gst_treatment": "business_gst", "place_of_supply": "TN", "customer_id": "903000000000099", "currency_id": "982000000000190", "currency_code": "USD", "start_date": "2016-06-12", "end_date": "2017-06-12", "last_sent_date": "2016-06-12", "next_invoice_date": "2016-06-17", "line_items": [ { "line_item_id": "982000000567021", "quantity": 1, "name": "Hard Drive", "item_total": 100, "sku": "LEV-JN-SL-36-GN", "product_type": "goods", "warehouse_id": "", "warehouses": [ { "warehouse_id": "", "warehouse_stock_on_hand": "" } ] } ], "billing_address": { "address": "4900 Hopyard Rd, Suite 310", "street2": "McMillan Avenue", "city": "Pleasanton", "state": "CA", "zip": "94588", "country": "U.S.A", "fax": "+1-925-924-9600" }, "shipping_address": { "address": "4900 Hopyard Rd, Suite 310", "city": "Pleasanton", "state": "CA", "zip": "94588", "country": "U.S.A", "fax": "+1-925-924-9600" }, "payment_gateways": [ { "configured": true, "additional_field1": "standard", "gateway_name": "paypal" } ], "payment_options": { "configured": true, "additional_field1": "standard", "gateway_name": "paypal" } }, "page_context": { "page": 1, "per_page": 200, "has_more_page": false, "report_name": "Recurring Invoices", "applied_filter": "Status.All", "sort_column": "created_time", "sort_order": "D" } } }
ARGUMENTS
|
recurrence_name
Required
Unique name for the recurring profile given by the user. Max-length [100]
reference_number
Optional
The Order number of the Recurring Invoice.
customer_id
Required
Customer ID of the customer for whom the recurring invoice is raised.
contact_persons
Optional
Contact Persons associated with the recurring invoice.
place_of_supply
India Edition only.
Optional
Place where the goods/services are supplied to. (If not given,
place of contact given for the contact will be taken)
vat_treatment
Optional
Enter vat treatment
gst_treatment
India Edition only.
Optional
Choose whether the contact is GST registered/unregistered/consumer/overseas. Allowed values are
business_gst , business_none , overseas , consumer .
gst_no
India Edition only.
Optional
15 digit GST identification number of the customer.
start_date
Optional
The date on which the recurring invoice starts.
end_date
Optional
The date on which the recurring invoice expires.
recurrence_frequency
Required
The frequency of time interval at which the invoice is to be generated.
repeat_every
Optional
The period between every recurrency frequency.
line_items
Optional
Line items of an invoice.
line_item_id
Optional
The line item id
quantity
Optional
Quantity of the item included.
name
Optional
The name of the line item. max-length [100]
item_total
Optional
Total rate raised by this item. This would be the multiplicative product of item price and quantity.
product_type
Optional
Enter goods/services
hsn_or_sac
India Edition only
Optional
Add HSN/SAC code for your goods/services
warehouse_id
Optional
Enter ID of the warehouse
tax_id
Optional
Unique to denote the tax associate to the recurring invoice.
email
Optional
Email address of the customer.
billing_address
Optional
address
Optional
Billing address for the invoice
street2
Optional
city
Optional
City of the customer’s billing address.
state
Optional
State of the customer’s billing address.
zip
Optional
Zip code of the customer’s billing address.
country
Optional
Country of the customer’s billing address.
fax
Optional
Customer's fax number.
shipping_address
Optional
address
Optional
Billing address for the invoice
city
Optional
City of the customer’s billing address.
state
Optional
State of the customer’s billing address.
zip
Optional
Zip code of the customer’s billing address.
country
Optional
Country of the customer’s billing address.
fax
Optional
Customer's fax number.
payment_gateways
Optional
configured
Optional
Boolean check to see if a payment gateway ahs been configured
additional_field1
Optional
Paypal payment method. Allowed Values:
standard and adaptive
gateway_name
Optional
Name of the payment gateway associated with the invoice. E.g. paypal, stripe.Allowed Values:
paypal, authorize_net, payflow_pro, stripe, 2checkout and braintree
avatax_use_code
Avalara integration only
Optional
Used to group like customers for
exemption purposes. It is a custom value that links customers to a tax
rule. Select from Avalara [standard codes][1] or enter a custom code.
Max-length [25]
avatax_exempt_no
Avalara integration only
Optional
Exemption certificate number of the customer. Max-length [25]
template_id
Optional
Unique ID of the recurring invoice template.
payment_terms
Optional
Payment terms in days. E.g: 15,30,60. Invoice due date will be calculated based on this.
payment_terms_label
Optional
Used to overridethe default payment terms label. Default value for 15 days is "Next 15 days".
tax_authority_id
US edition Only
Optional
Unique ID of the tax authority. Tax
authority depends on the location of the customer. For example, if the
customer is located in NY, then the tax authority is NY tax authority.
tax_exemption_id
Applicable for India, US, AU and CA Editions Only
Optional
Unique ID of the tax exemption.
vat_treatment
Optional
Enter vat treatment
exchange_rate
Optional
Exchange rate for the currency associated with the customer.
payment_options
Optional
gateway_name
Optional
Name of the payment gateway associated with the invoice. E.g. paypal, stripe.Allowed Values:
paypal, authorize_net, payflow_pro, stripe, 2checkout and braintree
additional_field1
Optional
Paypal payment method. Allowed Values:
standard and adaptive
discount
Optional
Discount applied to the invoice. It can be either in % or in amount. E.g: 12.5% or 190.
is_discount_before_tax
Optional
Used to specify how the discount has to applied. Either before or after the calculation of tax.
discount_type
Optional
How the discount is specified. Allowed values:
entity_level and item_level.
is_inclusive_tax
Not applicable for US and CA editions.
Optional
Used to specify whether the line item rates are inclusive or exclusive of tax.
item_id
Optional
Unique string generated for the item for which invoice is to be sent.
name
Optional
The name of the line item. max-length [100]
description
Optional
A small description about the item. Max-length [2000]
rate
Optional
Rate of the line item.
quantity
Optional
Quantity of the item included.
unit
Optional
Unit of the line item. E.g: kgs, Nos.
avatax_tax_code
Optional
A tax code is a unique label used to group items together.
salesperson_name
Applicable for US, AU and CA Editions Only
Optional
Name of the sales person
shipping_charge
Optional
Shipping charges applied to the invoice.
adjustment
Optional
Adjustments made to the invoice.
adjustment_description
Optional
Customize the adjustment description. E.g: Rounding off.
|
Update Recurring Invoice
Update the recurring invoice.
PUT /recurringinvoices/{recurring_invoice_id}
Request Example
$ curl https://books.zoho.com/api/v3/recurringinvoices/{recurring_invoice_id}?organization_id=10234695 -H "Authorization: Zoho-authtoken ba4604e8e433g9c892e360d53463oec5" -H "Content-Type: application/json;charset=UTF-8" -d '{ "recurrence_name": "MonthlyInvoice", "reference_number": "12314", "customer_id": "903000000000099", "contact_persons": [ "90300000065322" ], "start_date": "2016-06-12", "end_date": "2017-06-12", "recurrence_frequency": "weeks", "repeat_every": 2, "place_of_supply": "TN", "gst_treatment": "business_gst", "gst_no": "22AAAAA0000A1Z5", "line_items": [ { "item_id": "90300000081501", "name": "Hard Drive", "description": "prorated amount for items", "rate": 0, "quantity": 1, "discount": "30%", "tax_id": "903000000000356", "tax_exemption_id": "903000006345", "avatax_tax_code": " ", "item_total": 100, "product_type": "goods", "hsn_or_sac": 80540, "warehouse_id": "" } ], "tax_id": "903000000000356", "email": "benjamin.george@bowmanfurniture.com", "payment_gateways": [ { "configured": true, "additional_field1": "standard", "gateway_name": "paypal" } ], "tax_authority_id": "903000006345", "tax_exemption_id": "903000006345" }
Response Example
HTTP/1.1 200 OK Content-Type:application/json;charset=UTF-8 { "code": 0, "message": "success", "recurring_invoice": { "recurring_invoice_id": "90300000072369", "recurrence_name": "MonthlyInvoice", "reference_number": "12314", "customer_name": "Sujin Kumar", "is_pre_gst": false, "gst_no": "22AAAAA0000A1Z5", "gst_treatment": "business_gst", "place_of_supply": "TN", "customer_id": "903000000000099", "currency_id": "982000000000190", "currency_code": "USD", "start_date": "2016-06-12", "end_date": "2017-06-12", "last_sent_date": "2016-06-12", "next_invoice_date": "2016-06-17", "line_items": [ { "line_item_id": "982000000567021", "quantity": 1, "name": "Hard Drive", "item_total": 100, "sku": "LEV-JN-SL-36-GN", "product_type": "goods", "warehouse_id": "", "warehouses": [ { "warehouse_id": "", "warehouse_stock_on_hand": "" } ] } ], "billing_address": { "address": "4900 Hopyard Rd, Suite 310", "street2": "McMillan Avenue", "city": "Pleasanton", "state": "CA", "zip": "94588", "country": "U.S.A", "fax": "+1-925-924-9600" }, "shipping_address": { "address": "4900 Hopyard Rd, Suite 310", "city": "Pleasanton", "state": "CA", "zip": "94588", "country": "U.S.A", "fax": "+1-925-924-9600" }, "payment_gateways": [ { "configured": true, "additional_field1": "standard", "gateway_name": "paypal" } ], "payment_options": { "configured": true, "additional_field1": "standard", "gateway_name": "paypal" } } }
ARGUMENTS
|
recurrence_name
Required
Unique name for the recurring profile given by the user. Max-length [100]
reference_number
Optional
The Order number of the Recurring Invoice.
customer_id
Required
Customer ID of the customer for whom the recurring invoice is raised.
contact_persons
Optional
Contact Persons associated with the recurring invoice.
start_date
Optional
The date on which the recurring invoice starts.
end_date
Optional
The date on which the recurring invoice expires.
recurrence_frequency
Required
The frequency of time interval at which the invoice is to be generated.
repeat_every
Optional
The period between every recurrency frequency.
place_of_supply
India Edition only.
Optional
Place where the goods/services are supplied to. (If not given,
place of contact given for the contact will be taken)
vat_treatment
Optional
Enter vat treatment
gst_treatment
India Edition only.
Optional
Choose whether the contact is GST registered/unregistered/consumer/overseas. Allowed values are
business_gst , business_none , overseas , consumer .
gst_no
India Edition only.
Optional
15 digit GST identification number of the customer.
line_items
Optional
Line items of an invoice.
item_id
Optional
Unique string generated for the item for which invoice is to be sent.
name
Optional
The name of the line item. max-length [100]
rate
Optional
Rate of the line item.
quantity
Optional
Quantity of the item included.
discount
Optional
Discount applied to the invoice. It can be either in % or in amount. E.g: 12.5% or 190.
tax_id
Optional
Unique to denote the tax associate to the recurring invoice.
tax_exemption_id
Applicable for India, US, AU and CA Editions Only
Optional
Unique ID of the tax exemption.
avatax_tax_code
Optional
A tax code is a unique label used to group items together.
avatax_use_code
Avalara integration only
Optional
Used to group like customers for
exemption purposes. It is a custom value that links customers to a tax
rule. Select from Avalara [standard codes][1] or enter a custom code.
Max-length [25]
item_total
Optional
Total rate raised by this item. This would be the multiplicative product of item price and quantity.
product_type
Optional
Enter goods/services
hsn_or_sac
India Edition only
Optional
Add HSN/SAC code for your goods/services
warehouse_id
Optional
Enter ID of the warehouse
tax_id
Optional
Unique to denote the tax associate to the recurring invoice.
email
Optional
Email address of the customer.
payment_gateways
Optional
configured
Optional
Boolean check to see if a payment gateway ahs been configured
additional_field1
Optional
Paypal payment method. Allowed Values:
standard and adaptive
gateway_name
Optional
Name of the payment gateway associated with the invoice. E.g. paypal, stripe.Allowed Values:
paypal, authorize_net, payflow_pro, stripe, 2checkout and braintree
tax_authority_id
US edition Only
Optional
Unique ID of the tax authority. Tax
authority depends on the location of the customer. For example, if the
customer is located in NY, then the tax authority is NY tax authority.
tax_exemption_id
Applicable for India, US, AU and CA Editions Only
Optional
Unique ID of the tax exemption.
vat_treatment
Optional
Enter vat treatment
avatax_use_code
Avalara integration only
Optional
Used to group like customers for
exemption purposes. It is a custom value that links customers to a tax
rule. Select from Avalara [standard codes][1] or enter a custom code.
Max-length [25]
avatax_exempt_no
Avalara integration only
Optional
Exemption certificate number of the customer. Max-length [25]
|
Get a Recurring Invoice
Get the details of a recurring invoice.
get /recurringinvoices/:recurring_invoice_id
Request Example
$ curl https://books.zoho.com/api/v3/recurringinvoices/:recurring_invoice_id?organization_id=10234695 -H "Authorization: Zoho-authtoken ba4604e8e433g9c892e360d53463oec5" -H "Content-Type: application/json;charset=UTF-8"
Response Example
HTTP/1.1 200 OK Content-Type:application/json;charset=UTF-8 { "code": 0, "message": "Details of a recurring invoice is displayed successfully.", "recurring_invoice": { "recurring_invoice": { "recurring_invoice_id": "90300000072369", "recurrence_name": "MonthlyInvoice", "reference_number": "12314", "customer_name": "Sujin Kumar", "customer_id": "903000000000099", "company_name": "ABC Studios", "is_pre_gst": false, "gst_no": "22AAAAA0000A1Z5", "gst_treatment": "business_gst", "place_of_supply": "TN", "customer_email": "emailid@abcstudios.com", "customer_mobile_phone": 9876543210, "customer_phone": "012-12345678", "photo_url": "https://secure.gravatar.com/avatar/xxxxxxxxxx?&d=mm", "currency_id": "982000000000190", "currency_code": "USD", "start_date": "2016-06-12", "end_date": "2017-06-12", "last_sent_date": "2016-06-12", "next_invoice_date": "2016-06-17", "line_items": [ { "line_item_id": "982000000567021", "quantity": 1, "name": "Hard Drive", "item_total": 100, "sku": "LEV-JN-SL-36-GN", "product_type": "goods", "warehouse_id": "", "warehouses": [ { "warehouse_id": "", "warehouse_stock_on_hand": "" } ] } ], "paid_invoices_total": 100, "unpaid_invoices_balance": 100, "billing_address": { "address": "4900 Hopyard Rd, Suite 310", "street2": "McMillan Avenue", "city": "Pleasanton", "state": "CA", "zip": "94588", "country": "U.S.A", "fax": "+1-925-924-9600" }, "shipping_address": { "address": "4900 Hopyard Rd, Suite 310", "city": "Pleasanton", "state": "CA", "zip": "94588", "country": "U.S.A", "fax": "+1-925-924-9600" }, "payment_gateways": [ { "configured": true, "additional_field1": "standard", "gateway_name": "paypal" } ], "payment_options": { "configured": true, "additional_field1": "standard", "gateway_name": "paypal" } }, "page_context": { "page": 1, "per_page": 200, "has_more_page": false, "report_name": "Recurring Invoices", "applied_filter": "Status.All", "sort_column": "created_time", "sort_order": "D" } } }
List all Recurring Invoice
List the details of all recurring invoice.
get /recurringinvoices
Request Example
$ curl https://books.zoho.com/api/v3/recurringinvoices?organization_id=10234695 -H "Authorization: Zoho-authtoken ba4604e8e433g9c892e360d53463oec5" -H "Content-Type: application/json;charset=UTF-8"
Response Example
HTTP/1.1 200 OK Content-Type:application/json;charset=UTF-8 { "code": 0, "message": "Details of a recurring invoice is displayed successfully.", "recurring_invoice": [ { "recurring_invoices": [ { "recurring_invoice_id": "90300000072369", "recurrence_name": "MonthlyInvoice", "customer_name": "Sujin Kumar", "customer_id": "903000000000099", "currency_id": "982000000000190", "currency_code": "USD", "start_date": "2016-06-12", "end_date": "2017-06-12", "last_sent_date": "2016-06-12", "next_invoice_date": "2016-06-17", "line_items": [ { "line_item_id": "982000000567021", "quantity": 1, "name": "Hard Drive", "item_total": 100 } ], "billing_address": { "address": "4900 Hopyard Rd, Suite 310", "street2": "McMillan Avenue", "city": "Pleasanton", "state": "CA", "zip": "94588", "country": "U.S.A", "fax": "+1-925-924-9600" }, "shipping_address": { "address": "4900 Hopyard Rd, Suite 310", "city": "Pleasanton", "state": "CA", "zip": "94588", "country": "U.S.A", "fax": "+1-925-924-9600" }, "payment_gateways": [ { "configured": true, "additional_field1": "standard", "gateway_name": "paypal" } ], "payment_options": { "configured": true, "additional_field1": "standard", "gateway_name": "paypal" } } ], "page_context": { "page": 1, "per_page": 200, "has_more_page": false, "report_name": "Recurring Invoices", "applied_filter": "Status.All", "sort_column": "created_time", "sort_order": "D" } }, {...}, {...} ] }
Query Params
|
recurrence_name
Optional
Unique name for the recurring profile given by the user. Max-length [100]
item_name
Optional
Search recurring invoices by item name. Variants:
item_name_startswith and profileitemname_contains.
item_description
Optional
Search recurring invoices by item description. Variants:
item_description_startswith and item_description_contains.
customer_name
Optional
Name of the customer to whom the recurring invoice is raised.
line_item_id
Optional
The line item id
item_id
Optional
Unique string generated for the item for which invoice is to be sent.
tax_id
Optional
Unique to denote the tax associate to the recurring invoice.
notes
Optional
A short note for the recurring invoice.
start_date
Optional
The date on which the recurring invoice starts.
end_date
Optional
The date on which the recurring invoice expires.
customer_id
Optional
Customer ID of the customer for whom the recurring invoice is raised.
status
Optional
Status of the recurring invoice. This can be
active, stopped or expired.
filter_by
Optional
Filter Recurring invoices by any status or payment expected date.Allowed Values:
Status.All, Status.Active, Status.Stopped, Status.Expired
search_text
Optional
Search invoices by invoice number or purchase order or customer name. Max-length [100]
sort_column
Optional
|
Delete a Recurring Invoice
Delete an existing recurring invoice.
delete /recurringinvoices/:recurring_invoice_id
Request Example
$ curl https://books.zoho.com/api/v3/recurringinvoices/:recurring_invoice_id?organization_id=10234695 -H "Authorization: Zoho-authtoken ba4604e8e433g9c892e360d53463oec5" -H "Content-Type: application/json;charset=UTF-8" -d '{ "recurring_invoice_id": "90300000072369" }
Response Example
HTTP/1.1 200 OK Content-Type:application/json;charset=UTF-8 { "code": 0, "message": "The recurring invoice is deleted successfully.", "recurring_invoice": {...} }
ARGUMENTS
|
recurring_invoice_id
Optional
Unique ID of the recurring invoice generated by the server.
|
Stop a Recurring Invoice
Stop an active recurring invoice.
post /recurringinvoices/:recurring_invoice_id/status/stop
Request Example
$ curl https://books.zoho.com/api/v3/recurringinvoices/:recurring_invoice_id/status/stop?organization_id=10234695 -H "Authorization: Zoho-authtoken ba4604e8e433g9c892e360d53463oec5" -H "Content-Type: application/json;charset=UTF-8" -d '{ "recurring_invoice_id": "90300000072369" }
Response Example
HTTP/1.1 201 Created Content-Type:application/json;charset=UTF-8 { "code": 0, "message": "The recurring invoice has been stopped.", "recurring_invoice": {...} }
ARGUMENTS
|
recurring_invoice_id
Optional
Unique ID of the recurring invoice generated by the server.
|
Resume a Recurring Invoice
Resume a stopped recurring invoice.
post /recurringinvoices/:recurring_invoice_id/status/resume
Request Example
$ curl https://books.zoho.com/api/v3/recurringinvoices/:recurring_invoice_id/status/resume?organization_id=10234695 -H "Authorization: Zoho-authtoken ba4604e8e433g9c892e360d53463oec5" -H "Content-Type: application/json;charset=UTF-8" -d '{ "recurring_invoice_id": "90300000072369" }
Response Example
HTTP/1.1 201 Created Content-Type:application/json;charset=UTF-8 { "code": 0, "message": "The recurring invoice has been resumed.", "recurring_invoice": {...} }
ARGUMENTS
|
recurring_invoice_id
Optional
Unique ID of the recurring invoice generated by the server.
|
Update Recurring Invoice template
Update the pdf template associated with the recurring invoice.
put /recurringinvoices/:recurring_invoice_id/templates/:template_id
Request Example
$ curl https://books.zoho.com/api/v3/recurringinvoices/:recurring_invoice_id/templates/:template_id?organization_id=10234695 -H "Authorization: Zoho-authtoken ba4604e8e433g9c892e360d53463oec5" -H "Content-Type: application/json;charset=UTF-8" -d '{ "recurring_invoice_id": "90300000072369", "template_id": "90300043563547" }
Response Example
HTTP/1.1 200 OK Content-Type:application/json;charset=UTF-8 { "code": 0, "message": "The template of the recurring invoice has been updated.", "recurring_invoice": {...} }
ARGUMENTS
|
recurring_invoice_id
Optional
Unique ID of the recurring invoice generated by the server.
template_id
Optional
Unique ID of the recurring invoice template.
|
List Recurring Invoice History
Get the complete history and comments of a recurring invoice.
get /recurringinvoices/:recurring_invoice_id/comments
Request Example
$ curl https://books.zoho.com/api/v3/recurringinvoices/:recurring_invoice_id/comments?organization_id=10234695 -H "Authorization: Zoho-authtoken ba4604e8e433g9c892e360d53463oec5" -H "Content-Type: application/json;charset=UTF-8" -d '{ "recurring_invoice_id": "90300000072369" }
Response Example
HTTP/1.1 200 OK Content-Type:application/json;charset=UTF-8 { "code": 0, "message": "The complete history and comments of a recurring invoice are displayed successfully.", "recurring_invoice": [ { "comments": [ { "comment_id": "982000000567019", "recurring_invoice_id": "90300000072369", "comment_description": "Recurring Invoice created", "commented_by_id": "982000000554041", "commented_by": "Sujin Kumar", "comment_type": "system", "operation_type": "Added", "date": "2016-06-05", "date_description": "yesterday", "time": "2:02 AM", "transaction_id": "903000002072369", "transaction_type": "estimate" } ] }, {...}, {...} ] }
ARGUMENTS
|
recurring_invoice_id
Optional
Unique ID of the recurring invoice generated by the server.
|
Credit-Notes
Credit notes are created when a refund is to be made to a customer. A credit note object allows you to keep track of all credit note related information.
Example
{ "creditnote_id": "90300000072369", "creditnote_number": "CN-29", "ignore_auto_number_generation": false, "date": "2016-06-05", "status": "open", "customer_id": "903000000000099", "customer_name": "Bowman Furniture", "custom_fields": [ {} ], "reference_number": "INV-384", "email": "benjamin.george@bowmanfurniture.com", "total": 450, "balance": 10, "line_items": [ { "item_id": "90300000081501", "line_item_id": 903000006245, "account_id": "903000000000388", "name": "Basic Monthly", "description": "prorated amount for items", "item_order": 0, "rate": 0, "quantity": 1, "unit": "kgs", "discount": 10, "tax_id": "903000000000356", "tax_exemption_id": "903000006345", "tax_exemption_code": "GST FREE", "product_type": "goods", "hsn_or_sac": 80540, "item_custom_fields": [ {} ], "warehouse_id": 90300000072378 } ], "invoices": [ {} ], "currency_code": "USD", "currency_symbol": "$", "created_time": "2016-06-05T02:30:08-0700", "updated_time": "2016-06-05T02:30:08-0700", "template_id": "90300000001336", "template_name": "Standard Template" }
Attribute
|
creditnote_id
string
Unique ID of the credit note generated by the server.
creditnote_number
string
Unique number generated (starts with CN) which will be displayed in the interface and credit notes. Max-Length [100]
ignore_auto_number_generation
boolean
Set to true if you need to provide your own credit note number.
date
string
The date on which credit note is raised. Format [yyyy-mm-dd]
status
string
Status of the credit note. This can be
open, closed or void.
customer_id
string
Customer ID of the customer for whom the credit note is raised.
customer_name
string
Name of the customer to whom the credit note is raised. Max-Length [100]
custom_fields
list
Additional fields for the Credit-Notes.
reference_number
string
Reference number generated for the payment. A string of your choice can also be used as the reference number. Max-Length [100]
email
string
Email address of the customer.
total
double
Total credits raised in this credit note.
balance
double
The unapplied credits.
line_items
list
Line items of a credit note.
item_id
string
Unique string generated for the item to which a refund is to be made.
line_item_id
string
Search credit notes by credit note line item id.
account_id
string
Unique ID to denote the account.
name
string
Name of the credit
item_order
integer
Enter order of the item
rate
double
Rate of the line item.
quantity
required
Quantity of the item included.
unit
string
Unit of the line item. E.g: kgs, Nos.
discount
double
Enter discount percentage.
tax_id
string
Unique to denote the tax associate dto the creditnote
tax_exemption_id
Applicable for Inida, US, AU and CA Editions Only
string
Unique ID of the tax exemption.
tax_exemption_code
Applicable for Inida, US, AU and CA Editions Only
string
Unique code of the tax exemption.
avatax_use_code
Avalara integration only
string
Used to group like customers for
exemption purposes. It is a custom value that links customers to a tax
rule. Select from Avalara [standard codes][1] or enter a custom code.
Max-length [25]
avatax_tax_code
Avalara integration only
string
A tax code is a unique label used to
group Items (products, services, or charges) together. Refer the
[link][2] for more deails. Max-length [25]
product_type
string
Enter goods/services
hsn_or_sac
India Edition only
string
Add HSN/SAC code for your goods/services
item_custom_fields
list
Enter custom field information
warehouse_id
string
ID of the warehouse
serial_numbers
string
Enter serial number
invoices
list
List of invoices for which the credit note has been raised. This contains
invoice_id and amount.
currency_code
string
Customer's currency code. This currency code is used in credit notes.
currency_symbol
string
Customer's currency symbol.
created_time
string
Time at which the credit note was created.
updated_time
string
Time at which the credit note details were last updated.
template_id
string
Unique ID of the creditnote template
template_name
string
Name of the default template of the creditnote.
|
Create a credit note
Details of an existing creditnote.
POST /creditnotes
Request Example
$ curl https://books.zoho.com/api/v3/creditnotes?organization_id=10234695 -H "Authorization: Zoho-authtoken ba4604e8e433g9c892e360d53463oec5" -H "Content-Type: application/json;charset=UTF-8" -d '{ "customer_id": "903000000000099", "contact_persons": [ "903000006532" ], "date": "2016-06-05", "exchange_rate": "5.5", "line_items": [ { "item_id": "90300000081501", "description": "prorated amount for items", "code": "basic-monthly", "name": "Basic Monthly", "type": 1, "account_id": "903000000000388", "account_name": "Sales", "quantity": 1, "tax_id": "903000000000356", "price": 100, "item_total": 100, "product_type": "goods", "warehouse_id": 90300000072378 } ], "creditnote_number": "CN-29", "gst_treatment": "business_gst", "gst_no": "22AAAAA0000A1Z5", "place_of_supply": "TN", "ignore_auto_number_generation": false, "reference_number": "INV-384", "custom_fields": [ {} ], "notes": "Offer for the referral", "terms": "", "template_id": "90300000001336", "tax_id": "903000000000356", "tax_authority_id": "903000006345", "tax_exemption_id": "903000006345", "is_inclusive_tax": "fasle" }
Response Example
HTTP/1.1 201 Created Content-Type:application/json;charset=UTF-8 { "code": 0, "message": "The credit note has been created.", "credit_note": { "creditnote": { "creditnote_id": "90300000072369", "creditnote_number": "CN-29", "date": "2016-06-05", "is_pre_gst": true, "place_of_supply": "TN", "gst_no": "22AAAAA0000A1Z5", "gst_treatment": "business_gst", "status": "open", "customer_id": "903000000000099", "customer_name": "Bowman Furniture", "custom_fields": [ { "index": 1, "value": 129890, "label": "label", "data_type": "text" } ], "reference_number": "INV-384", "email": "benjamin.george@bowmanfurniture.com", "total": 450, "balance": 10, "line_items": [ { "item_id": "90300000081501", "line_item_id": 903000006245, "account_id": "903000000000388", "name": "Basic Monthly", "description": "prorated amount for items", "item_order": 0, "rate": 0, "quantity": 1, "unit": "kgs", "discount": 10, "tax_id": "903000000000356", "tax_exemption_id": "903000006345", "tax_exemption_code": "GST FREE", "product_type": "goods", "hsn_or_sac": 80540, "item_custom_fields": [ {...} ], "warehouse_id": 90300000072378 } ], "invoices": [ { "invoice_id": "90300000079426", "invoice_number": "INV-384", "amount": 450 } ], "taxes": [ { "tax_id": "903000000000356", "tax_name": "Basic Tax", "tax_amount": "2.50" } ], "currency_code": "USD", "currency_symbol": "$", "billing_address": { "address": "4900 Hopyard Rd, Suite 310", "street2": "McMillan Avenue", "city": "Pleasanton", "state": "CA", "zip": 94588, "country": "U.S.A", "fax": "+1-925-924-9600" }, "shipping_address": { "address": "4900 Hopyard Rd, Suite 310", "street2": "McMillan Avenue", "city": "Pleasanton", "state": "CA", "zip": 94588, "country": "U.S.A", "fax": "+1-925-924-9600" }, "created_time": "2016-06-05T02:30:08-0700", "updated_time": "2016-06-05T02:30:08-0700", "template_id": "90300000001336", "template_name": "Standard Template", "notes": "Offer for the referral", "terms": "" } } }
ARGUMENTS
|
customer_id
Required
Customer ID of the customer for whom the credit note is raised.
contact_persons
Optional
Contact Persons associated with the credit note.
date
Required
The date on which credit note is raised. Format [yyyy-mm-dd]
exchange_rate
Optional
Exchange rate for the currency associated with the customer.
line_items
Required
Line items of a credit note.
item_id
Optional
Unique string generated for the item to which a refund is to be made.
code
Optional
Unique code for the creditnote line item.
name
Optional
Name of the credit
account_id
Optional
Unique ID to denote the account.
account_name
Optional
Name of the account.
quantity
Optional
Quantity of the item included.
tax_id
Optional
Unique to denote the tax associate dto the creditnote
price
Optional
The price of the item included.
item_total
Optional
Total credits raised by this item. This would be the multiplicative product of item price and quantity.
product_type
Optional
Enter goods/services
serial_numbers
Optional
Enter serial number
warehouse_id
Optional
ID of the warehouse
warehouse_name
Optional
Name of the warehouse.
creditnote_number
Required
Unique number generated (starts with CN) which will be displayed in the interface and credit notes. Max-Length [100]
gst_treatment
India Edition only
Optional
Choose whether the contact is GST registered/unregistered/consumer/overseas. Allowed values are
business_gst , business_none , overseas , consumer .
gst_no
India Edition only
Optional
15 digit GST identification number of the customer.
place_of_supply
India Edition only.
Optional
Place where the goods/services are supplied to. (If not given,
place of contact given for the contact will be taken)
ignore_auto_number_generation
Optional
Set to true if you need to provide your own credit note number.
reference_number
Optional
Reference number generated for the payment. A string of your choice can also be used as the reference number. Max-Length [100]
custom_fields
Optional
Additional fields for the Credit-Notes.
notes
Optional
A short note for the credit note. Max-length [5000]
terms
Optional
Terms & condition to be displayed in the credit note. Max-length [10000]
template_id
Optional
Unique ID of the creditnote template
tax_id
Optional
Unique to denote the tax associate dto the creditnote
tax_authority_id
US edition Only
Optional
Unique ID of the tax authority. Tax
authority depends on the location of the customer. For example, if the
customer is located in NY, then the tax authority is NY tax authority.
tax_exemption_id
Applicable for Inida, US, AU and CA Editions Only
Optional
Unique ID of the tax exemption.
avatax_use_code
Avalara integration only
Optional
Used to group like customers for
exemption purposes. It is a custom value that links customers to a tax
rule. Select from Avalara [standard codes][1] or enter a custom code.
Max-length [25]
avatax_exempt_no
Avalara integration only
Optional
Exemption certificate number of the customer. Max-length [25]
vat_treatment
Optional
Enter vat treatment
is_inclusive_tax
Not applicable for US and CA editions.
Optional
Used to specify whether the line item rates are inclusive or exclusive of tax.
avatax_tax_code
Avalara integration only
Optional
A tax code is a unique label used to
group Items (products, services, or charges) together. Refer the
[link][2] for more deails. Max-length [25]
|
Query Params
|
invoice_id
Optional
Invoice ID of the required invoice.
ignore_auto_number_generation
Optional
Set to true if you need to provide your own credit note number.
|
Update a credit note
Details of an existing creditnote.
PUT /creditnotes/{:creditnote_id}
Request Example
$ curl https://books.zoho.com/api/v3/creditnotes/{:creditnote_id}?organization_id=10234695 -H "Authorization: Zoho-authtoken ba4604e8e433g9c892e360d53463oec5" -H "Content-Type: application/json;charset=UTF-8" -d '{ "customer_id": "903000000000099", "contact_persons": [ "903000006532" ], "date": "2016-06-05", "exchange_rate": "5.5", "line_items": [ { "item_id": "90300000081501", "line_item_id": 903000006245, "account_id": "903000000000388", "name": "Basic Monthly", "description": "prorated amount for items", "item_order": 0, "rate": 0, "quantity": 1, "unit": "kgs", "discount": 10, "tax_id": "903000000000356", "tax_exemption_id": "903000006345", "tax_exemption_code": "GST FREE", "product_type": "goods", "hsn_or_sac": 80540, "item_custom_fields": [ {} ], "warehouse_id": 90300000072378 } ], "creditnote_number": "CN-29", "gst_treatment": "business_gst", "gst_no": "22AAAAA0000A1Z5", "place_of_supply": "TN", "ignore_auto_number_generation": false, "reference_number": "INV-384", "custom_fields": [ {} ], "notes": "Offer for the referral", "terms": "", "template_id": "90300000001336", "tax_id": "903000000000356", "tax_authority_id": "903000006345", "tax_exemption_id": "903000006345", "is_inclusive_tax": "fasle", "item_id": "90300000081501", "account_id": "903000000000388", "name": "Basic Monthly", "description": "prorated amount for items", "unit": "kgs", "rate": 0, "quantity": 1 }
Response Example
HTTP/1.1 200 OK Content-Type:application/json;charset=UTF-8 { "code": 0, "message": "The credit note has been updated.", "credit_note": { "creditnote": { "creditnote_id": "90300000072369", "creditnote_number": "CN-29", "date": "2016-06-05", "is_pre_gst": true, "place_of_supply": "TN", "gst_no": "22AAAAA0000A1Z5", "gst_treatment": "business_gst", "status": "open", "customer_id": "903000000000099", "customer_name": "Bowman Furniture", "custom_fields": [ { "index": 1, "value": 129890, "label": "label", "data_type": "text" } ], "reference_number": "INV-384", "email": "benjamin.george@bowmanfurniture.com", "total": 450, "balance": 10, "line_items": [ { "item_id": "90300000081501", "description": "prorated amount for items", "code": "basic-monthly", "name": "Basic Monthly", "type": 1, "account_id": "903000000000388", "account_name": "Sales", "quantity": 1, "tax_id": "903000000000356", "price": 100, "item_total": 100, "product_type": "goods", "warehouse_id": 90300000072378 } ], "invoices": [ { "invoice_id": "90300000079426", "invoice_number": "INV-384", "amount": 450 } ], "taxes": [ { "tax_id": "903000000000356", "tax_name": "Basic Tax", "tax_amount": "2.50" } ], "currency_code": "USD", "currency_symbol": "$", "billing_address": { "address": "4900 Hopyard Rd, Suite 310", "street2": "McMillan Avenue", "city": "Pleasanton", "state": "CA", "zip": 94588, "country": "U.S.A", "fax": "+1-925-924-9600", "attention": " " }, "shipping_address": { "address": "4900 Hopyard Rd, Suite 310", "street2": "McMillan Avenue", "city": "Pleasanton", "state": "CA", "zip": 94588, "country": "U.S.A", "fax": "+1-925-924-9600", "attention": " " }, "created_time": "2016-06-05T02:30:08-0700", "updated_time": "2016-06-05T02:30:08-0700", "template_id": "90300000001336", "template_name": "Standard Template", "notes": "Offer for the referral", "terms": "" } } }
ARGUMENTS
|
customer_id
Required
Customer ID of the customer for whom the credit note is raised.
contact_persons
Optional
Contact Persons associated with the credit note.
date
Required
The date on which credit note is raised. Format [yyyy-mm-dd]
exchange_rate
Optional
Exchange rate for the currency associated with the customer.
line_items
Required
Line items of a credit note.
item_id
Optional
Unique string generated for the item to which a refund is to be made.
line_item_id
Optional
Search credit notes by credit note line item id.
account_id
Optional
Unique ID to denote the account.
name
Optional
Name of the credit
item_order
Optional
Enter order of the item
rate
Optional
Rate of the line item.
quantity
Optional
Quantity of the item included.
unit
Optional
Unit of the line item. E.g: kgs, Nos.
discount
Optional
Enter discount percentage.
tax_id
Optional
Unique to denote the tax associate dto the creditnote
tax_exemption_id
Applicable for Inida, US, AU and CA Editions Only
Optional
Unique ID of the tax exemption.
tax_exemption_code
Applicable for Inida, US, AU and CA Editions Only
Optional
Unique code of the tax exemption.
avatax_use_code
Avalara integration only
Optional
Used to group like customers for
exemption purposes. It is a custom value that links customers to a tax
rule. Select from Avalara [standard codes][1] or enter a custom code.
Max-length [25]
avatax_tax_code
Avalara integration only
Optional
A tax code is a unique label used to
group Items (products, services, or charges) together. Refer the
[link][2] for more deails. Max-length [25]
product_type
Optional
Enter goods/services
hsn_or_sac
India Edition only
Optional
Add HSN/SAC code for your goods/services
item_custom_fields
Optional
Enter custom field information
warehouse_id
Optional
ID of the warehouse
serial_numbers
Optional
Enter serial number
creditnote_number
Required
Unique number generated (starts with CN) which will be displayed in the interface and credit notes. Max-Length [100]
gst_treatment
India Edition only
Optional
Choose whether the contact is GST registered/unregistered/consumer/overseas. Allowed values are
business_gst , business_none , overseas , consumer .
gst_no
India Edition only
Optional
15 digit GST identification number of the customer.
place_of_supply
India Edition only.
Optional
Place where the goods/services are supplied to. (If not given,
place of contact given for the contact will be taken)
ignore_auto_number_generation
Optional
Set to true if you need to provide your own credit note number.
reference_number
Optional
Reference number generated for the payment. A string of your choice can also be used as the reference number. Max-Length [100]
custom_fields
Optional
Additional fields for the Credit-Notes.
notes
Optional
A short note for the credit note. Max-length [5000]
terms
Optional
Terms & condition to be displayed in the credit note. Max-length [10000]
template_id
Optional
Unique ID of the creditnote template
tax_id
Optional
Unique to denote the tax associate dto the creditnote
tax_authority_id
US edition Only
Optional
Unique ID of the tax authority. Tax
authority depends on the location of the customer. For example, if the
customer is located in NY, then the tax authority is NY tax authority.
tax_exemption_id
Applicable for Inida, US, AU and CA Editions Only
Optional
Unique ID of the tax exemption.
avatax_use_code
Avalara integration only
Optional
Used to group like customers for
exemption purposes. It is a custom value that links customers to a tax
rule. Select from Avalara [standard codes][1] or enter a custom code.
Max-length [25]
avatax_exempt_no
Avalara integration only
Optional
Exemption certificate number of the customer. Max-length [25]
vat_treatment
Optional
Enter vat treatment
is_inclusive_tax
Not applicable for US and CA editions.
Optional
Used to specify whether the line item rates are inclusive or exclusive of tax.
line_items
Required
Line items of a credit note.
item_id
Optional
Unique string generated for the item to which a refund is to be made.
line_item_id
Optional
Search credit notes by credit note line item id.
account_id
Optional
Unique ID to denote the account.
name
Optional
Name of the credit
item_order
Optional
Enter order of the item
rate
Optional
Rate of the line item.
quantity
Optional
Quantity of the item included.
unit
Optional
Unit of the line item. E.g: kgs, Nos.
discount
Optional
Enter discount percentage.
tax_id
Optional
Unique to denote the tax associate dto the creditnote
tax_exemption_id
Applicable for Inida, US, AU and CA Editions Only
Optional
Unique ID of the tax exemption.
tax_exemption_code
Applicable for Inida, US, AU and CA Editions Only
Optional
Unique code of the tax exemption.
avatax_use_code
Avalara integration only
Optional
Used to group like customers for
exemption purposes. It is a custom value that links customers to a tax
rule. Select from Avalara [standard codes][1] or enter a custom code.
Max-length [25]
avatax_tax_code
Avalara integration only
Optional
A tax code is a unique label used to
group Items (products, services, or charges) together. Refer the
[link][2] for more deails. Max-length [25]
product_type
Optional
Enter goods/services
hsn_or_sac
India Edition only
Optional
Add HSN/SAC code for your goods/services
item_custom_fields
Optional
Enter custom field information
warehouse_id
Optional
ID of the warehouse
serial_numbers
Optional
Enter serial number
item_id
Optional
Unique string generated for the item to which a refund is to be made.
account_id
Optional
Unique ID to denote the account.
name
Optional
Name of the credit
avatax_tax_code
Avalara integration only
Optional
A tax code is a unique label used to
group Items (products, services, or charges) together. Refer the
[link][2] for more deails. Max-length [25]
description
Optional
A small description about the item.
unit
Optional
Unit of the line item. E.g: kgs, Nos.
rate
Optional
Rate of the line item.
quantity
Optional
Quantity of the item included.
|
Query Params
|
ignore_auto_number_generation
Optional
Set to true if you need to provide your own credit note number.
|
Get a credit note
Details of an existing creditnote.
GET /creditnotes/{creditnote_id}
Request Example
$ curl https://books.zoho.com/api/v3/creditnotes/{creditnote_id}?organization_id=10234695 -H "Authorization: Zoho-authtoken ba4604e8e433g9c892e360d53463oec5" -H "Content-Type: application/json;charset=UTF-8"
Response Example
HTTP/1.1 200 OK Content-Type:application/json;charset=UTF-8 { "code": 0, "message": "success", "credit_note": { "creditnote": { "creditnote_id": "90300000072369", "creditnote_number": "CN-29", "date": "2016-06-05", "is_pre_gst": true, "place_of_supply": "TN", "gst_no": "22AAAAA0000A1Z5", "gst_treatment": "business_gst", "status": "open", "customer_id": "903000000000099", "customer_name": "Bowman Furniture", "custom_fields": [ { "index": 1, "value": 129890, "label": "label", "data_type": "text" } ], "reference_number": "INV-384", "email": "benjamin.george@bowmanfurniture.com", "total": 450, "balance": 10, "line_items": [ { "item_id": "90300000081501", "description": "prorated amount for items", "code": "basic-monthly", "name": "Basic Monthly", "type": 1, "account_id": "903000000000388", "account_name": "Sales", "quantity": 1, "tax_id": "903000000000356", "price": 100, "item_total": 100, "product_type": "goods", "warehouse_id": 90300000072378 } ], "invoices": [ { "invoice_id": "90300000079426", "invoice_number": "INV-384", "amount": 450 } ], "taxes": [ { "tax_id": "903000000000356", "tax_name": "Basic Tax", "tax_amount": "2.50" } ], "currency_code": "USD", "currency_symbol": "$", "created_time": "2016-06-05T02:30:08-0700", "updated_time": "2016-06-05T02:30:08-0700", "billing_address": { "address": "4900 Hopyard Rd, Suite 310", "street2": "McMillan Avenue", "city": "Pleasanton", "state": "CA", "zip": 94588, "country": "U.S.A", "fax": "+1-925-924-9600", "attention": " " }, "shipping_address": { "address": "4900 Hopyard Rd, Suite 310", "street2": "McMillan Avenue", "city": "Pleasanton", "state": "CA", "zip": 94588, "country": "U.S.A", "fax": "+1-925-924-9600", "attention": " " }, "template_id": "90300000001336", "template_name": "Standard Template", "notes": "Offer for the referral", "terms": "" } } }
Query Params
|
print
Optional
Export credit note pdf with default print option. Allowed Values:
true, false, on and off
accept
Optional
You can get credit note details as json/pdf/html. Default format is html. Allowed Values:
json, pdf and html |
List all Credit Notes
List all the Credit Notes .
GET /creditnotes
Request Example
$ curl https://books.zoho.com/api/v3/creditnotes?organization_id=10234695 -H "Authorization: Zoho-authtoken ba4604e8e433g9c892e360d53463oec5" -H "Content-Type: application/json;charset=UTF-8"
Response Example
HTTP/1.1 200 OK Content-Type:application/json;charset=UTF-8 { "code": 0, "message": "success", "credit_note": [ { "creditnotes": { "creditnote_id": "90300000072369", "creditnote_number": "CN-29", "status": "open", "reference_number": "INV-384", "date": "2016-06-05", "total": 450, "balance": 10, "customer_id": "903000000000099", "customer_name": "Bowman Furniture", "currency_id": "982000000567240", "currency_code": "USD", "created_time": "2016-06-05T02:30:08-0700", "last_modified_time": "2016-06-05T02:30:08-0700", "is_emailed": true } }, {...}, {...} ] }
Query Params
|
creditnote_number
Optional
Unique number generated (starts with CN) which will be displayed in the interface and credit notes. Max-Length [100]
date
Optional
The date on which credit note is raised. Format [yyyy-mm-dd]
status
Optional
Status of the credit note. This can be
open, closed or void.
total
Optional
Total credits raised in this credit note.
reference_number
Optional
Reference number generated for the payment. A string of your choice can also be used as the reference number. Max-Length [100]
customer_name
Optional
Name of the customer to whom the credit note is raised. Max-Length [100]
item_name
Optional
Search credit notes by item name.Max_lenght [100]
customer_id
Optional
Customer ID of the customer for whom the credit note is raised.
item_description
Optional
description for the item.Variants
item_description_startswith and item_description_contains. Max-length [100]
item_id
Optional
Unique string generated for the item to which a refund is to be made.
line_item_id
Optional
Search credit notes by credit note line item id.
tax_id
Optional
Unique to denote the tax associate dto the creditnote
filter_by
Optional
Filter credit notes by statuses. Allowed values
Status.All Status.Open Status.Draft Status.Closed and Status.Void
search_text
Optional
Search credit notes by credit note number or customer name or credit note reference number. Max-length [100]
sort_column
Optional
Sort credit notes by following columns customer_name, creditnote_number, balance, total, date and created_time. Allowed Values
customer_name creditnote_number balance total date and created_time |
Email a credit note
Email a credit note.
POST /creditnotes/{creditnote_id}/email
Request Example
$ curl https://books.zoho.com/api/v3/creditnotes/{creditnote_id}/email?organization_id=10234695 -H "Authorization: Zoho-authtoken ba4604e8e433g9c892e360d53463oec5" -H "Content-Type: application/json;charset=UTF-8" -d '{ "to_mail_ids": [ "benjamin.george@bowmanfurniture.com", "paul@bowmanfurniture.com" ], "cc_mail_ids": [ "accounts@bowmanfurniture.com" ], "subject": "Credit note for subscription.", "body": "Please find attached the credit note for your subscription." }
Response Example
HTTP/1.1 200 OK Content-Type:application/json;charset=UTF-8 { "code": 0, "message": "Your creditnote has been sent." }
ARGUMENTS
|
to_mail_ids
Required
The email IDs to which the credit note is to be mailed.
cc_mail_ids
Optional
The email IDs that have to be copied when the credit note is to be mailed.
subject
Required
The subject of the email. Max-length [1000]
body
Required
The body of the email. Max-length [5000]
|
Query Params
|
customer_id
Optional
Customer ID of the customer for whom the credit note is raised.
attachments
Optional
The files to be attached with the email.
|
Void a credit note
Details of an existing creditnote.
POST /creditnotes/{creditnote_id}/void
Request Example
$ curl https://books.zoho.com/api/v3/creditnotes/{creditnote_id}/void?organization_id=10234695 -H "Authorization: Zoho-authtoken ba4604e8e433g9c892e360d53463oec5" -H "Content-Type: application/json;charset=UTF-8"
Response Example
HTTP/1.1 200 OK Content-Type:application/json;charset=UTF-8 { "code": 0, "message": "The credit note has been marked as void." }
Open a voided credit note
Convert a voided credit note to open
POST /creditnotes/{creditnote_id}/converttoopen
Request Example
$ curl https://books.zoho.com/api/v3/creditnotes/{creditnote_id}/converttoopen?organization_id=10234695 -H "Authorization: Zoho-authtoken ba4604e8e433g9c892e360d53463oec5" -H "Content-Type: application/json;charset=UTF-8"
Response Example
HTTP/1.1 200 OK Content-Type:application/json;charset=UTF-8 { "code": 0, "message": "Status of the credit note has been changed to open." }
Delete a credit note
Delete an existing credit note
DELETE /creditnotes/{creditnote_id}
Request Example
$ curl https://books.zoho.com/api/v3/creditnotes/{creditnote_id}?organization_id=10234695 -H "Authorization: Zoho-authtoken ba4604e8e433g9c892e360d53463oec5" -H "Content-Type: application/json;charset=UTF-8"
Response Example
HTTP/1.1 200 OK Content-Type:application/json;charset=UTF-8 { "code": 0, "message": "The credit note has been deleted." }
Email history
Get email history of a credit code.
GET /creditnotes/{creditnote_id}/emailhistory
Request Example
$ curl https://books.zoho.com/api/v3/creditnotes/{creditnote_id}/emailhistory?organization_id=10234695 -H "Authorization: Zoho-authtoken ba4604e8e433g9c892e360d53463oec5" -H "Content-Type: application/json;charset=UTF-8"
Response Example
HTTP/1.1 200 OK Content-Type:application/json;charset=UTF-8 { "code": 0, "message": "success", "email_history": [ { "mailhistory_id": 982000000570005, "from": "gator@zillum.com", "to_mail_ids": [ "benjamin.george@bowmanfurniture.com", "paul@bowmanfurniture.com" ], "subject": "Credit note for subscription.", "date": "2016-06-05" } ] }
Get email content
Get email content of a credit note.
GET /creditnotes/{creditnote_id}/email
Request Example
$ curl https://books.zoho.com/api/v3/creditnotes/{creditnote_id}/email?organization_id=10234695 -H "Authorization: Zoho-authtoken ba4604e8e433g9c892e360d53463oec5" -H "Content-Type: application/json;charset=UTF-8"
Response Example
HTTP/1.1 200 OK Content-Type:application/json;charset=UTF-8 { "code": 0, "message": "success", "data": [ { "body": "The credit note is attached with this email.", "error_list": [], "subject": "Credit Note from Zillium Inc(Credit Note #: CN-00001)", "emailtemplates": [ { "selected": "fasle", "name": "Default", "email_template_id": "460000000000085" } ], "to_contacts": [ { "first_name": "Will", "selected": "fasle", "phone": "+1-925-921-9201", "email": "willsmith@bowmanfurniture.com", "contact_person_id": "460000000026051", "last_name": "Parker", "salutation": "Mr.", "mobile": "+1-4054439760" } ], "file_name": "CN-00001.pdf", "from_emails": [ { "user_name": "John Smith", "selected": "fasle", "email": "willsmith@bowmanfurniture.com" } ], "customer_id": "46000000002609" } ] }
Query Params
|
email_template_id
Optional
Get the email content based on a
specific email template. If this param is not inputted, then the content
will be based on the email template associated with the customer. If no
template is associated with the customer, then default template will be
used.
|
Update billing address
Updates the billing address for an existing credit note alone.
PUT /creditnotes/{creditnote_id}/address/billing
Request Example
$ curl https://books.zoho.com/api/v3/creditnotes/{creditnote_id}/address/billing?organization_id=10234695 -H "Authorization: Zoho-authtoken ba4604e8e433g9c892e360d53463oec5" -H "Content-Type: application/json;charset=UTF-8" -d '{ "address": "4900 Hopyard Rd, Suite 310", "city": "Pleasanton", "state": "CA", "zip": 94588, "country": "USA", "fax": "+1-925-924-9600" }
Response Example
HTTP/1.1 200 OK Content-Type:application/json;charset=UTF-8 { "code": 0, "message": "Billing address updated" }
ARGUMENTS
|
address
Optional
Billing address for the invoice
city
Optional
City of the customer’s billing address.
state
Optional
State of the customer’s billing address.
zip
Optional
Zip code of the customer’s billing address.
country
Optional
Country of the customer’s billing address.
fax
Optional
Customer's fax number.
|
Update Shipping address
Updates the shipping address for an existing credit note alone.
PUT /creditnotes/{creditnote_id}/address/shipping
Request Example
$ curl https://books.zoho.com/api/v3/creditnotes/{creditnote_id}/address/shipping?organization_id=10234695 -H "Authorization: Zoho-authtoken ba4604e8e433g9c892e360d53463oec5" -H "Content-Type: application/json;charset=UTF-8" -d '{ "address": "Suite 125, McMillan Avenue", "city": "San Francisco", "state": "CA", "zip": 94134, "country": "USA", "fax": "+1-925-924-9600" }
Response Example
HTTP/1.1 200 OK Content-Type:application/json;charset=UTF-8 { "code": 0, "message": "Shipping address updated" }
ARGUMENTS
|
address
Optional
Billing address for the invoice
city
Optional
City of the customer’s billing address.
state
Optional
State of the customer’s billing address.
zip
Optional
Zip code of the customer’s billing address.
country
Optional
Country of the customer’s billing address.
fax
Optional
Customer's fax number.
|
List credit note template
Get all credit note pdf templates.
GET /creditnotes/templates
Request Example
$ curl https://books.zoho.com/api/v3/creditnotes/templates?organization_id=10234695 -H "Authorization: Zoho-authtoken ba4604e8e433g9c892e360d53463oec5" -H "Content-Type: application/json;charset=UTF-8"
Response Example
HTTP/1.1 200 OK Content-Type:application/json;charset=UTF-8 { "code": 0, "message": "success", "templates": [ { "template_name": "Standard Template", "template_id": "90300000001336", "template_type": "professional" } ] }
Update a credit note template
Update the pdf template associated with the credit note.
PUT /creditnotes/{creditnote_id}/templates/{template_id}
Request Example
$ curl https://books.zoho.com/api/v3/creditnotes/{creditnote_id}/templates/{template_id}?organization_id=10234695 -H "Authorization: Zoho-authtoken ba4604e8e433g9c892e360d53463oec5" -H "Content-Type: application/json;charset=UTF-8"
Response Example
HTTP/1.1 200 OK Content-Type:application/json;charset=UTF-8 { "code": 0, "message": "The credit note has been updated." }
List invoices credited
List invoices to which the credit note is applied.
GET /creditnotes/:creditnote_id/invoices
Request Example
$ curl https://books.zoho.com/api/v3/creditnotes/:creditnote_id/invoices?organization_id=10234695 -H "Authorization: Zoho-authtoken ba4604e8e433g9c892e360d53463oec5" -H "Content-Type: application/json;charset=UTF-8"
Response Example
HTTP/1.1 200 OK Content-Type:application/json;charset=UTF-8 { "code": 0, "message": "success", "invoices_credited": [ { "creditnote_id": "90300000072369", "invoice_id": "90300000079426", "creditnote_invoice_id": "982000000567172", "date": "2016-06-05", "invoice_number": "INV-384", "creditnote_number": "CN-29", "credited_amount": 12.02 } ] }
Credit to an invoice
Apply credit note to existing invoices.
POST /creditnotes/:creditnote_id/invoices
Request Example
$ curl https://books.zoho.com/api/v3/creditnotes/:creditnote_id/invoices?organization_id=10234695 -H "Authorization: Zoho-authtoken ba4604e8e433g9c892e360d53463oec5" -H "Content-Type: application/json;charset=UTF-8" -d '{ "invoices": [ { "invoice_id": "90300000079426", "amount_applied": 41.82 } ], "invoice_id": "90300000079426", "amount_applied": 41.82 }
Response Example
HTTP/1.1 200 OK Content-Type:application/json;charset=UTF-8 { "code": 0, "message": "Credits have been applied to the invoice(s)." }
ARGUMENTS
|
invoices
Optional
List of invoices for which the credit note has been raised. This contains
invoice_id and amount.
invoice_id
Required
Invoice ID of the required invoice.
amount_applied
Required
The total amount applied form the credit note on an invoice.
invoice_id
Required
Invoice ID of the required invoice.
amount_applied
Required
The total amount applied form the credit note on an invoice.
|
Delete invoices credited
Delete the credits applied to an invoice.
DELETE /creditnotes/:creditnote_id/invoices/:creditnote_invoice_id
Request Example
$ curl https://books.zoho.com/api/v3/creditnotes/:creditnote_id/invoices/:creditnote_invoice_id?organization_id=10234695 -H "Authorization: Zoho-authtoken ba4604e8e433g9c892e360d53463oec5" -H "Content-Type: application/json;charset=UTF-8"
Response Example
HTTP/1.1 200 OK Content-Type:application/json;charset=UTF-8 { "code": 0, "message": "Credits applied to an invoice have been deleted." }
List credit note comments & history
Get history and comments of a credit note.
GET /creditnotes/:creditnote_id/comments
Request Example
$ curl https://books.zoho.com/api/v3/creditnotes/:creditnote_id/comments?organization_id=10234695 -H "Authorization: Zoho-authtoken ba4604e8e433g9c892e360d53463oec5" -H "Content-Type: application/json;charset=UTF-8"
Response Example
HTTP/1.1 200 OK Content-Type:application/json;charset=UTF-8 { "code": 0, "message": "Comments of the credit note are displayed successfully.", "comments": [ { "comment_id": "982000000570001", "creditnote_id": "90300000072369", "description": "Credits applied to invoice INV-00004", "commented_by_id": "982000000554041", "commented_by": "Sujin Kumar", "comment_type": "system", "date": "2016-06-05", "date_description": "7 hours ago", "time": "10:43 PM", "operation_type": "Updated", "transaction_id": "903000002072369", "transaction_type": "email" } ] }
Add a comment
Add a comment to an existing credit note.
POST /creditnotes/:creditnote_id/comments
Request Example
$ curl https://books.zoho.com/api/v3/creditnotes/:creditnote_id/comments?organization_id=10234695 -H "Authorization: Zoho-authtoken ba4604e8e433g9c892e360d53463oec5" -H "Content-Type: application/json;charset=UTF-8" -d '{ "description": "Credits applied to invoice INV-00004" }
Response Example
HTTP/1.1 200 OK Content-Type:application/json;charset=UTF-8 { "code": 0, "message": "Comments added." }
ARGUMENTS
|
description
Optional
A small description about the item.
|
Delete a Comment
Delete a credit note comment.
DELETE /creditnotes/:creditnote_id/comments/:comment_id
Request Example
$ curl https://books.zoho.com/api/v3/creditnotes/:creditnote_id/comments/:comment_id?organization_id=10234695 -H "Authorization: Zoho-authtoken ba4604e8e433g9c892e360d53463oec5" -H "Content-Type: application/json;charset=UTF-8"
Response Example
HTTP/1.1 200 OK Content-Type:application/json;charset=UTF-8 { "code": 0, "message": "The comment has been deleted." }
List credit note refunds
List all refunds with pagination.
GET /creditnotes/refunds
Request Example
$ curl https://books.zoho.com/api/v3/creditnotes/refunds?organization_id=10234695 -H "Authorization: Zoho-authtoken ba4604e8e433g9c892e360d53463oec5" -H "Content-Type: application/json;charset=UTF-8"
Response Example
HTTP/1.1 200 OK Content-Type:application/json;charset=UTF-8 { "code": 0, "message": "The list of credit note refunds are displayed successfully.", "creditnote_refunds": [ { "creditnote_refund_id": "982000000567158", "creditnote_id": "90300000072369", "date": "2016-06-05", "refund_mode": "cash", "reference_number": "INV-384", "creditnote_number": "CN-29", "customer_name": "Bowman Furniture", "description": "", "amount_bcy": 10, "amount_fcy": 10 } ], "page_context": { "page": 1, "per_page": 200, "has_more_page": false, "report_name": "Credit Notes Refund", "sort_column": "created_time", "sort_order": "D" } }
Query Params
|
customer_id
Optional
Customer ID of the customer for whom the credit note is raised.
sort_column
Optional
Sort refunds list. Allowed Values:
refund_mode, reference_number, date, creditnote_number, customer_name, amount_bcy and amount_fcy |
List refunds of a credit note
List all refunds of an existing credit note.
GET /creditnotes/:creditnote_id/refunds
Request Example
$ curl https://books.zoho.com/api/v3/creditnotes/:creditnote_id/refunds?organization_id=10234695 -H "Authorization: Zoho-authtoken ba4604e8e433g9c892e360d53463oec5" -H "Content-Type: application/json;charset=UTF-8"
Response Example
HTTP/1.1 200 OK Content-Type:application/json;charset=UTF-8 { "code": 0, "message": "The refunds of the existing credit note are displayed successfully.", "creditnote_refunds": [ { "creditnote_refund_id": "982000000567158", "creditnote_id": "90300000072369", "date": "2016-06-05", "refund_mode": "cash", "reference_number": "INV-384", "creditnote_number": "CN-29", "customer_name": "Bowman Furniture", "description": "", "amount_bcy": 10, "amount_fcy": 10 } ], "page_context": { "page": 1, "per_page": 200, "has_more_page": false, "report_name": "Credit Notes Refund", "sort_column": "created_time", "sort_order": "D" } }
Get credit note refund
Get refund of a particular credit note.
GET /creditnotes/:creditnote_id/refunds/:creditnote_refund_id
Request Example
$ curl https://books.zoho.com/api/v3/creditnotes/:creditnote_id/refunds/:creditnote_refund_id?organization_id=10234695 -H "Authorization: Zoho-authtoken ba4604e8e433g9c892e360d53463oec5" -H "Content-Type: application/json;charset=UTF-8"
Response Example
HTTP/1.1 200 OK Content-Type:application/json;charset=UTF-8 { "code": 0, "message": "The refund of the credit note is displayed successfully.", "creditnote_refund": { "creditnote_refund_id": "982000000567158", "creditnote_id": "90300000072369", "date": "2016-06-05", "refund_mode": "cash", "reference_number": "INV-384", "amount": 450, "customer_name": "Bowman Furniture", "description": "prorated amount for items" } }
Refund credit note
Refund credit note amount.
POST /creditnotes/:creditnote_id/refunds
Request Example
$ curl https://books.zoho.com/api/v3/creditnotes/:creditnote_id/refunds?organization_id=10234695 -H "Authorization: Zoho-authtoken ba4604e8e433g9c892e360d53463oec5" -H "Content-Type: application/json;charset=UTF-8" -d '{ "date": "2016-06-05", "refund_mode": "cash", "reference_number": "INV-384", "amount": 450, "exchange_rate": "5.5", "from_account_id": " ", "description": "prorated amount for items" }
Response Example
HTTP/1.1 200 OK Content-Type:application/json;charset=UTF-8 { "code": 0, "message": "The credit note amount is refunded successfully.", "creditnote_refund": { "creditnote_refund_id": "982000000567158", "creditnote_id": "90300000072369", "date": "2016-06-05", "refund_mode": "cash", "reference_number": "INV-384", "amount": 450, "customer_name": "Bowman Furniture", "description": "prorated amount for items" } }
ARGUMENTS
|
date
Optional
The date on which credit note is raised. Format [yyyy-mm-dd]
refund_mode
Optional
The method of refund.
reference_number
Optional
Reference number generated for the payment. A string of your choice can also be used as the reference number. Max-Length [100]
amount
Optional
Amount paid for the invoice.
exchange_rate
Optional
Exchange rate for the currency associated with the customer.
from_account_id
Optional
The account from which credit note is refunded.
description
Optional
A small description about the item.
|
Update credit note refund
Update the refunded transaction.
PUT /creditnotes/:creditnote_id/refunds/:creditnote_refund_id
Request Example
$ curl https://books.zoho.com/api/v3/creditnotes/:creditnote_id/refunds/:creditnote_refund_id?organization_id=10234695 -H "Authorization: Zoho-authtoken ba4604e8e433g9c892e360d53463oec5" -H "Content-Type: application/json;charset=UTF-8" -d '{ "date": "2016-06-05", "refund_mode": "cash", "reference_number": "INV-384", "amount": 450, "exchange_rate": "5.5", "from_account_id": " ", "description": "prorated amount for items" }
Response Example
HTTP/1.1 200 OK Content-Type:application/json;charset=UTF-8 { "code": 0, "message": "The credit note refund is updated successfully.", "creditnote_refund": { "creditnote_refund_id": "982000000567158", "creditnote_id": "90300000072369", "date": "2016-06-05", "refund_mode": "cash", "reference_number": "INV-384", "amount": 450, "customer_name": "Bowman Furniture", "description": "prorated amount for items" } }
ARGUMENTS
|
date
Optional
The date on which credit note is raised. Format [yyyy-mm-dd]
refund_mode
Optional
The method of refund.
reference_number
Optional
Reference number generated for the payment. A string of your choice can also be used as the reference number. Max-Length [100]
amount
Optional
Amount paid for the invoice.
exchange_rate
Optional
Exchange rate for the currency associated with the customer.
from_account_id
Optional
The account from which credit note is refunded.
description
Optional
A small description about the item.
|
Delete credit note refund
Delete a credit note refund.
DELETE /creditnotes/:creditnote_id/refunds/:creditnote_refund_id
Request Example
$ curl https://books.zoho.com/api/v3/creditnotes/:creditnote_id/refunds/:creditnote_refund_id?organization_id=10234695 -H "Authorization: Zoho-authtoken ba4604e8e433g9c892e360d53463oec5" -H "Content-Type: application/json;charset=UTF-8"
Response Example
HTTP/1.1 200 OK Content-Type:application/json;charset=UTF-8 { "code": 0, "message": "The refund has been successfully deleted." }
Customer-Payments
Payments from Customers towards Invoices.
Example
{ "payment_id": "9030000079467", "payment_mode": "cash", "amount": 450, "amount_refunded": 50, "date": "2016-06-05", "status": "success", "reference_number": "INV-384", "description": "Payment has been added to INV-384", "customer_id": "903000000000099", "customer_name": "Bowman Furniture", "email": "benjamin.george@bowmanfurniture.com", "invoices": [ { "invoice_id": "90300000079426", "invoice_number": "INV-384", "date": "2016-06-05", "invoice_amount": 450, "amount_applied": 450, "balance_amount": 0 } ], "currency_code": "USD", "currency_symbol": "$", "exchange_rate": 1, "bank_charges": 10, "custom_fields": [ { "value": 129890, "label": "label", "data_type": "text" } ] }
Attribute
|
payment_id
string
Unique ID of the payment generated by the server. Max-length [2000]
payment_mode
string
Mode through which payment is made. This can be
check, cash, creditcard, banktransfer, bankremittance, autotransaction or others. Max-length [100]
amount
double
Amount paid in the respective payment.
amount_refunded
double
Amount that is refund. Refunds are applicable only for payments whose payment_mode is
autotransaction. Refunds would be made to the respective card provided by the customer.
date
string
Date on which payment is made. Format [yyyy-mm-dd]
status
string
Status of the payment. It can either be
success or failure.
reference_number
string
Reference number generated for the payment. A string of your choice can also be used as the reference number. Max-length [100]
description
string
Description about the payment.
customer_id
string
Customer ID of the customer involved in the payment.
customer_name
string
Name of the customer to whom the invoice is raised. Max-length [100]
email
string
Email address of the customer involved in the payment.
invoices
list
List of invoices associated with the payment. Each invoice object contains
invoice_id, invoice_number, date, invoice_amount, amount_applied and balance_amount.
invoice_id
string
Invoice ID of the required invoice.
invoice_number
string
Unique ID (starts with INV) of an invoice.
date
string
Date on which payment is made. Format [yyyy-mm-dd]
invoice_amount
double
Total amount raised for the invoice.
amount_applied
double
Amount paid for the invoice.
balance_amount
double
Unpaid amount of the invoice.
currency_code
string
Currency code in which the payment is made.
currency_symbol
string
Customer's currency symbol.
exchange_rate
double
Exchange rate for the currency used in
the invoices and customer's currency. The payment amount would be the
multiplicative product of the original amount and the exchange rate.
bank_charges
double
Denotes any additional bank charges.
custom_fields
list
Additional fields for the payments.
value
string
Value of the custom field.
label
string
Label of the custom field.
data_type
string
Data type of the custom field.
|
Create a payment
Create a new payment.
POST /customerpayments
Request Example
$ curl https://books.zoho.com/api/v3/customerpayments?organization_id=10234695 -H "Authorization: Zoho-authtoken ba4604e8e433g9c892e360d53463oec5" -H "Content-Type: application/json;charset=UTF-8" -d '{ "customer_id": "903000000000099", "payment_mode": "cash", "amount": 450, "date": "2016-06-05", "reference_number": "INV-384", "description": "Payment has been added to INV-384", "invoices": [ { "invoice_id": "90300000079426", "amount_applied": 450 } ], "exchange_rate": 1, "bank_charges": 10, "custom_fields": [ { "label": "label", "value": 129890 } ], "invoice_id": "90300000079426", "amount_applied": 450, "tax_amount_withheld": 0, "account_id": " ", "contact_persons": [ "982000000870911", "982000000870915" ] }
Response Example
HTTP/1.1 201 Created Content-Type:application/json;charset=UTF-8 { "code": 0, "message": "The payment has been created.", "payment": { "payment": { "payment_id": "9030000079467", "payment_mode": "cash", "amount": 450, "amount_refunded": 50, "bank_charges": 10, "date": "2016-06-05", "status": "success", "reference_number": "INV-384", "description": "Payment has been added to INV-384", "customer_id": "903000000000099", "customer_name": "Bowman Furniture", "email": "benjamin.george@bowmanfurniture.com", "invoices": [ { "invoice_id": "90300000079426", "invoice_number": "INV-384", "date": "2016-06-05", "invoice_amount": 450, "amount_applied": 450, "balance_amount": 0 } ], "currency_code": "USD", "currency_symbol": "$", "custom_fields": [ { "index": 1, "value": 129890, "label": "label", "data_type": "text" } ] } } }
ARGUMENTS
|
customer_id
Required
Customer ID of the customer involved in the payment.
payment_mode
Required
Mode through which payment is made. This can be
check, cash, creditcard, banktransfer, bankremittance, autotransaction or others. Max-length [100]
amount
Required
Amount paid in the respective payment.
date
Required
Date on which payment is made. Format [yyyy-mm-dd]
reference_number
Optional
Reference number generated for the payment. A string of your choice can also be used as the reference number. Max-length [100]
description
Optional
Description about the payment.
invoices
Required
List of invoices associated with the payment. Each invoice object contains
invoice_id, invoice_number, date, invoice_amount, amount_applied and balance_amount.
invoice_id
Optional
Invoice ID of the required invoice.
amount_applied
Optional
Amount paid for the invoice.
exchange_rate
Optional , default is 1
Exchange rate for the currency used in
the invoices and customer's currency. The payment amount would be the
multiplicative product of the original amount and the exchange rate.
bank_charges
Optional
Denotes any additional bank charges.
custom_fields
Optional
Additional fields for the payments.
label
Optional
Label of the custom field.
value
Optional
Value of the custom field.
invoice_id
Optional
Invoice ID of the required invoice.
amount_applied
Optional
Amount paid for the invoice.
tax_amount_withheld
Optional
Amount withheld for tax.
account_id
Optional
ID of the cash/bank account the payment has to be deposited.
contact_persons
Optional
IDs of the contact personsthe thank you mail has to be triggered.
|
Update a payment
Update an existing payment information.
PUT /customerpayments/{payment_id}
Request Example
$ curl https://books.zoho.com/api/v3/customerpayments/{payment_id}?organization_id=10234695 -H "Authorization: Zoho-authtoken ba4604e8e433g9c892e360d53463oec5" -H "Content-Type: application/json;charset=UTF-8" -d '{ "customer_id": "903000000000099", "payment_mode": "cash", "amount": 450, "date": "2016-06-05", "reference_number": "INV-384", "description": "Payment has been added to INV-384", "invoices": [ { "invoice_id": "90300000079426", "amount_applied": 450 } ], "exchange_rate": 1, "bank_charges": 10, "custom_fields": [ { "label": "label", "value": 129890 } ], "invoice_id": "90300000079426", "amount_applied": 450, "tax_amount_withheld": 0, "account_id": " " }
Response Example
HTTP/1.1 200 OK Content-Type:application/json;charset=UTF-8 { "code": 0, "message": "The payment details have been updated.", "payment": { "payment": { "payment_id": "9030000079467", "payment_mode": "cash", "amount": 450, "amount_refunded": 50, "bank_charges": 10, "date": "2016-06-05", "status": "success", "reference_number": "INV-384", "description": "Payment has been added to INV-384", "customer_id": "903000000000099", "customer_name": "Bowman Furniture", "email": "benjamin.george@bowmanfurniture.com", "invoices": [ { "invoice_id": "90300000079426", "invoice_number": "INV-384", "date": "2016-06-05", "invoice_amount": 450, "amount_applied": 450, "balance_amount": 0 } ], "currency_code": "USD", "currency_symbol": "$", "custom_fields": [ { "index": 1, "value": 129890, "label": "label", "data_type": "text" } ] } } }
ARGUMENTS
|
customer_id
Required
Customer ID of the customer involved in the payment.
payment_mode
Required
Mode through which payment is made. This can be
check, cash, creditcard, banktransfer, bankremittance, autotransaction or others. Max-length [100]
amount
Required
Amount paid in the respective payment.
date
Optional
Date on which payment is made. Format [yyyy-mm-dd]
reference_number
Optional
Reference number generated for the payment. A string of your choice can also be used as the reference number. Max-length [100]
description
Optional
Description about the payment.
invoices
Required
List of invoices associated with the payment. Each invoice object contains
invoice_id, invoice_number, date, invoice_amount, amount_applied and balance_amount.
invoice_id
Optional
Invoice ID of the required invoice.
amount_applied
Optional
Amount paid for the invoice.
exchange_rate
Optional , default is 1
Exchange rate for the currency used in
the invoices and customer's currency. The payment amount would be the
multiplicative product of the original amount and the exchange rate.
bank_charges
Optional
Denotes any additional bank charges.
custom_fields
Optional
Additional fields for the payments.
label
Optional
Label of the custom field.
value
Optional
Value of the custom field.
invoice_id
Optional
Invoice ID of the required invoice.
amount_applied
Optional
Amount paid for the invoice.
tax_amount_withheld
Optional
Amount withheld for tax.
account_id
Optional
ID of the cash/bank account the payment has to be deposited.
|
Retrieve a payment
Details of an existing payment.
GET /customerpayments/{payment_id}
Request Example
$ curl https://books.zoho.com/api/v3/customerpayments/{payment_id}?organization_id=10234695 -H "Authorization: Zoho-authtoken ba4604e8e433g9c892e360d53463oec5" -H "Content-Type: application/json;charset=UTF-8"
Response Example
HTTP/1.1 200 OK Content-Type:application/json;charset=UTF-8 { "code": 0, "message": "success", "payment": { "payment": { "payment_id": "9030000079467", "payment_mode": "cash", "amount": 450, "amount_refunded": 50, "bank_charges": 10, "date": "2016-06-05", "status": "success", "reference_number": "INV-384", "description": "Payment has been added to INV-384", "customer_id": "903000000000099", "customer_name": "Bowman Furniture", "email": "benjamin.george@bowmanfurniture.com", "invoices": [ { "invoice_id": "90300000079426", "invoice_number": "INV-384", "date": "2016-06-05", "invoice_amount": 450, "amount_applied": 450, "balance_amount": 0 } ], "currency_code": "USD", "currency_symbol": "$", "custom_fields": [ { "index": 1, "value": 129890, "label": "label", "data_type": "text" } ] } } }
List Customer Payments
List all the payments made by your customer
GET /customerpayments
Request Example
$ curl https://books.zoho.com/api/v3/customerpayments?organization_id=10234695 -H "Authorization: Zoho-authtoken ba4604e8e433g9c892e360d53463oec5" -H "Content-Type: application/json;charset=UTF-8"
Response Example
HTTP/1.1 200 OK Content-Type:application/json;charset=UTF-8 { "code": 0, "message": "success", "customer_payments": [ { "payment_id": "9030000079467", "payment_number": "2", "invoice_number": "INV-384", "date": "2016-06-05", "payment_mode": "cash", "amount": 450, "bcy_amount": 450 } ] }
Query Params
|
customer_name
Optional
Search payments by customer name. Variants:
customer_name_startswith and customer_name_contains. Max-len [100]
reference_number
Optional
Search payments by reference number. Variants:
reference_number_startswith and reference_number_contains. Max-len [100]
date
Optional
Date on which payment is made. Format [yyyy-mm-dd]
amount
Optional
Search payments by payment amount. Variants:
amount_less_than, amount_less_equals, amount_greater_than and amount_greater_equals
notes
Optional
Search payments by customer notes. Variants:
notes_startswith and notes_contains
payment_mode
Optional
Search payments by payment mode. Variants:
payment_mode_startswith and payment_mode_contains
filter_by
Optional
Filter payments by mode.Allowed Values: PaymentMode.All, PaymentMode.Check, PaymentMode.Cash, PaymentMode.BankTransfer, PaymentMode.Paypal, PaymentMode.CreditCard, PaymentMode.GoogleCheckout, PaymentMode.Credit, PaymentMode.Authorizenet, PaymentMode.BankRemittance, PaymentMode.Payflowpro, PaymentMode.Stripe, PaymentMode.TwoCheckout, PaymentMode.Braintree,/code> and
|
Delete a payment
Delete an existing payment.
DELETE /customerpayments/{payment_id}
Request Example
$ curl https://books.zoho.com/api/v3/customerpayments/{payment_id}?organization_id=10234695 -H "Authorization: Zoho-authtoken ba4604e8e433g9c892e360d53463oec5" -H "Content-Type: application/json;charset=UTF-8"
Response Example
HTTP/1.1 200 OK Content-Type:application/json;charset=UTF-8 { "code": 0, "message": "The payment has been deleted." }
List refunds of a customer payment
List all the refunds pertaining to an existing customer payment.
GET /customerpayments/{customer_payment_id}/refunds
Request Example
$ curl https://books.zoho.com/api/v3/customerpayments/{customer_payment_id}/refunds?organization_id=10234695 -H "Authorization: Zoho-authtoken ba4604e8e433g9c892e360d53463oec5" -H "Content-Type: application/json;charset=UTF-8"
Response Example
HTTP/1.1 200 OK Content-Type:application/json;charset=UTF-8 { "code": 0, "message": "The list of refunds of the customer is displayed successfully.", "payment": { "payment_refunds": [ { "payment_refund_id": "3000000003017", "payment_id": "9030000079467", "date": "2016-06-05", "refund_mode": "cash", "reference_number": "INV-384", "payment_number": "2", "customer_name": "Bowman Furniture", "amount_bcy": 10, "amount_fcy": 10 } ], "page_context": { "page": 1, "per_page": 200, "has_more_page": false, "report_name": "Customer Payments Refund", "sort_column": "created_time", "sort_order": "D" } } }
Details of a refund
Obtain details of a particular refund of a customer payment.
GET /customerpayments/{customer_payment_id}/refunds/:refund_id
Request Example
$ curl https://books.zoho.com/api/v3/customerpayments/{customer_payment_id}/refunds/:refund_id?organization_id=10234695 -H "Authorization: Zoho-authtoken ba4604e8e433g9c892e360d53463oec5" -H "Content-Type: application/json;charset=UTF-8"
Response Example
HTTP/1.1 200 OK Content-Type:application/json;charset=UTF-8 { "code": 0, "message": "The details of the refund are displayed successfully.", "payment": { "payment_refunds": [ { "payment_refund_id": "3000000003017", "payment_id": "9030000079467", "date": "2016-06-05", "refund_mode": "cash", "reference_number": "INV-384", "amount": 450, "exchange_rate": 1, "description": "Payment has been added to INV-384" } ] } }
Refund an excess customer payment
Refund the excess amount paid by the customer.
POST /customerpayments/{customer_payment_id}/refunds
Request Example
$ curl https://books.zoho.com/api/v3/customerpayments/{customer_payment_id}/refunds?organization_id=10234695 -H "Authorization: Zoho-authtoken ba4604e8e433g9c892e360d53463oec5" -H "Content-Type: application/json;charset=UTF-8" -d '{ "date": "2016-06-05", "refund_mode": "cash", "reference_number": "INV-384", "amount": 450, "exchange_rate": 1, "from_account_id": " ", "description": "Payment has been added to INV-384" }
Response Example
HTTP/1.1 200 OK Content-Type:application/json;charset=UTF-8 { "code": 0, "message": "The refund information for this payment has been saved.", "payment": { "payment_refunds": [ { "payment_refund_id": "3000000003017", "payment_id": "9030000079467", "date": "2016-06-05", "refund_mode": "cash", "reference_number": "INV-384", "amount": 450, "exchange_rate": 1, "description": "Payment has been added to INV-384" } ] } }
ARGUMENTS
|
date
Required
Date on which payment is made. Format [yyyy-mm-dd]
refund_mode
Optional
The method of refund. Max-length [50]
reference_number
Optional
Reference number generated for the payment. A string of your choice can also be used as the reference number. Max-length [100]
amount
Required
Amount paid in the respective payment.
exchange_rate
Optional , default is 1
Exchange rate for the currency used in
the invoices and customer's currency. The payment amount would be the
multiplicative product of the original amount and the exchange rate.
from_account_id
Required
The account from which payment is refunded.
description
Optional
Description about the payment.
|
Update a refund
Update the refunded transaction.
PUT /customerpayments/{customer_payment_id}/refunds/:refund_id
Request Example
$ curl https://books.zoho.com/api/v3/customerpayments/{customer_payment_id}/refunds/:refund_id?organization_id=10234695 -H "Authorization: Zoho-authtoken ba4604e8e433g9c892e360d53463oec5" -H "Content-Type: application/json;charset=UTF-8" -d '{ "date": "2016-06-05", "refund_mode": "cash", "reference_number": "INV-384", "amount": 450, "exchange_rate": 1, "description": "Payment has been added to INV-384", "from_account_id": " " }
Response Example
HTTP/1.1 200 OK Content-Type:application/json;charset=UTF-8 { "code": 0, "message": "The refund information has been saved.", "payment": { "payment_refunds": [ { "payment_refund_id": "3000000003017", "payment_id": "9030000079467", "date": "2016-06-05", "refund_mode": "cash", "reference_number": "INV-384", "amount": 450, "exchange_rate": 1, "description": "Payment has been added to INV-384" } ] } }
ARGUMENTS
|
date
Required
Date on which payment is made. Format [yyyy-mm-dd]
refund_mode
Optional
The method of refund. Max-length [50]
reference_number
Optional
Reference number generated for the payment. A string of your choice can also be used as the reference number. Max-length [100]
amount
Required
Amount paid in the respective payment.
exchange_rate
Optional , default is 1
Exchange rate for the currency used in
the invoices and customer's currency. The payment amount would be the
multiplicative product of the original amount and the exchange rate.
description
Optional
Description about the payment.
from_account_id
Required
The account from which payment is refunded.
|
Delete a Refund
Delete refund pertaining to an existing customer payment.
DELETE /customerpayments/{customer_payment_id}/refunds/:refund_id
Request Example
$ curl https://books.zoho.com/api/v3/customerpayments/{customer_payment_id}/refunds/:refund_id?organization_id=10234695 -H "Authorization: Zoho-authtoken ba4604e8e433g9c892e360d53463oec5" -H "Content-Type: application/json;charset=UTF-8"
Response Example
HTTP/1.1 200 OK Content-Type:application/json;charset=UTF-8 { "code": 0, "message": "The refund has been deleted.", "payment": {...} }
Expenses
A typical expense is incurred when money goes out of your pocket. Whether its a product you buy from your vendor to run your business, or food that you eat while on business trips, it’s important to track the money you spend.
Example
{ "description": "Marketing", "reference_number": null, "date": "2013-11-18T00:00:00.000Z", "status": "unbilled", "amount": 112.5, "customer_name": "Bowman & Co", "is_billable": true }
Attribute
|
description
String
Description of the expense. Max-length [100]
reference_number
String
Reference number of the expense. Max-length [100]
date
String
Date of the expense
status
String
Expense status
amount
double
Amount of the Expense.
customer_name
String
Name of the Custome for which expense is raised. Max-length [100]
is_billable
boolean
|
Create an Expense
Create billable or non-billable expense
POST /expenses
Request Example
$ curl https://books.zoho.com/api/v3/expenses?organization_id=10234695 -H "Authorization: Zoho-authtoken ba4604e8e433g9c892e360d53463oec5" -H "Content-Type: application/json;charset=UTF-8" -d '{ "account_id": 982000000561057, "date": "2013-11-18T00:00:00.000Z", "amount": 112.5, "tax_id": 982000000566007, "source_of_supply": "AP", "destination_of_supply": "TN", "hsn_or_sac": 80540, "gst_no": "22AAAAA0000A1Z5", "reverse_charge_tax_id": 982000000561063, "line_items": [ { "line_item_id": 10763000000140068, "account_id": 982000000561057, "description": "Marketing", "amount": 112.5, "tax_id": 982000000566007, "item_order": 1, "product_type": "goods", "acquisition_vat_id": " ", "reverse_charge_vat_id": " ", "reverse_charge_tax_id": 982000000561063, "tax_exemption_id": 982000000561067 } ], "is_inclusive_tax": false, "is_billable": true, "reference_number": null, "description": "Marketing", "customer_id": 982000000567001, "currency_id": 982000000567001, "exchange_rate": 1, "project_id": 982000000567226, "mileage_type": "non_mileage", "vat_treatment": "eu_vat_not_registered", "product_type": "goods", "acquisition_vat_id": " ", "reverse_charge_vat_id": " ", "start_reading": " ", "end_reading": " ", "distance": " ", "mileage_unit": " ", "mileage_rate": " ", "employee_id": " ", "vehicle_type": " ", "can_reclaim_vat_on_mileage": " ", "fuel_type": " ", "engine_capacity_range": " ", "paid_through_account_id": 982000000567250, "vendor_id": " ", "custom_fields": [ {} ] }
Response Example
HTTP/1.1 200 OK Content-Type:application/json;charset=UTF-8 { "code": 0, "message": "The expense has been recorded.", "expense": { "expense": { "expense_id": 982000000030049, "transaction_id": " ", "transaction_type": "expense", "gst_no": "22AAAAA0000A1Z5", "gst_treatment": "business_gst", "destination_of_supply": "TN", "destination_of_supply_state": "TN", "hsn_or_sac": 80540, "source_of_supply": "AP", "paid_through_account_name": "Petty Cash", "reverse_charge_tax_id": 982000000561063, "reverse_charge_tax_name": "intra", "reverse_charge_tax_percentage": 10, "reverse_charge_tax_amount": 12, "tax_amount": 11.85, "is_itemized_expense": false, "is_pre_gst": "fasle", "trip_id": "", "trip_number": "", "reverse_charge_vat_total": 1.2, "acquisition_vat_total": 0, "acquisition_vat_summary": [ { "tax": { "tax_name": "SalesTax", "tax_amount": 11.85 } } ], "reverse_charge_vat_summary": [ { "tax": { "tax_name": "SalesTax", "tax_amount": 11.85 } } ], "expense_item_id": 982000000567220, "account_id": 982000000561057, "account_name": "Rent", "date": "2013-11-18T00:00:00.000Z", "tax_id": 982000000566007, "tax_name": "SalesTax", "tax_percentage": 10.5, "currency_id": 982000000567001, "currency_code": "USD", "exchange_rate": 1, "sub_total": 90, "total": 100, "bcy_total": 100, "amount": 112.5, "is_inclusive_tax": false, "reference_number": null, "description": "Marketing", "is_billable": true, "is_personal": false, "customer_id": 982000000567001, "customer_name": "Bowman & Co", "expense_receipt_name": " ", "expense_receipt_type": " ", "last_modified_time": " ", "status": "unbilled", "invoice_id": " ", "invoice_number": " ", "project_id": 982000000567226, "project_name": " ", "mileage_rate": " ", "mileage_type": "non_mileage", "expense_type": "non-mileage", "start_reading": " ", "end_reading": " " } } }
ARGUMENTS
|
account_id
Optional
ID of the expense account.
date
Optional
Date of the expense
amount
Required
Amount of the Expense.
tax_id
Optional
source_of_supply
India Edition only
Optional
Place from where the goods/services are supplied. (If not given,
place of contact given for the contact will be taken)
destination_of_supply
India Edition only
Optional
Place where the goods/services are supplied to. (If not given, organisation's home state will be taken)
hsn_or_sac
India Edition only
Optional
Add HSN/SAC code for your goods/services
gst_no
India Edition only
Optional
15 digit GST identification number of the vendor.
reverse_charge_tax_id
Optional
ID of the reverse charge tax
line_items
Optional
line_item_id
Optional
account_id
Optional
ID of the expense account.
description
Optional
Description of the expense. Max-length [100]
amount
Required
Amount of the Expense.
tax_id
Optional
item_order
Optional
product_type
UK Edition only
Optional
Type of the expense. This denotes whether the expense is to be treated as a goods or service purchase. Allowed Values:
digital_service , goods and service.
acquisition_vat_id
UK Edition only
Optional
This is the ID of the tax applied in case this is an EU - goods expense and acquisition VAT needs to be reported.
reverse_charge_vat_id
UK Edition only
Optional
This is the ID of the tax applied in case this is a non UK - service expense and reverse charge VAT needs to be reported.
reverse_charge_tax_id
Optional
ID of the reverse charge tax
tax_exemption_code
India Edition only
Optional
Enter tax exemption code
tax_exemption_id
India Edition only
Optional
Enter tax exemption ID
is_inclusive_tax
Optional
is_billable
Optional
reference_number
Required
Reference number of the expense. Max-length [100]
description
Optional
Description of the expense. Max-length [100]
customer_id
Optional
ID of the expense account.
currency_id
Optional
exchange_rate
Optional
project_id
Optional
ID of the project associated with the customer.
mileage_type
Optional
vat_treatment
UK Edition only
Optional
VAT treatment for the expense. VAT
treatment denotes the location of the vendor, if the vendor resides in
UK then the VAT treatment is
uk. If the vendor is in an EU country & if he is VAT registered then his VAT treatment is eu_vat_registered, if he resides in EU & if he is not VAT registered then his VAT treatment is eu_vat_not_registered and if he resides outside the EU then his VAT treatment is non_eu.
product_type
UK Edition only
Optional
Type of the expense. This denotes whether the expense is to be treated as a goods or service purchase. Allowed Values:
digital_service , goods and service.
acquisition_vat_id
UK Edition only
Optional
This is the ID of the tax applied in case this is an EU - goods expense and acquisition VAT needs to be reported.
reverse_charge_vat_id
UK Edition only
Optional
This is the ID of the tax applied in case this is a non UK - service expense and reverse charge VAT needs to be reported.
start_reading
Optional
Start reading of odometer when creating a mileage expense where
mileage_type is odometer.
end_reading
Optional
End reading of odometer when creating a mileage expense where
mileage_type is odometer.
distance
Optional
Distance travelled for a particular mileage expense where
mileage_type is manual
mileage_unit
Optional
Unit of the distance travelled. Allowed Values:
km and mile
mileage_rate
Optional
Mileage rate for a particular mileage expense.
employee_id
UK Edition only
Optional
ID of the employee who has submitted this mileage expense.
vehicle_type
UK Edition only
Optional
Vehicle type for a particular mileage expense. Allowed Values:
car, van, motorcycle and bike
can_reclaim_vat_on_mileage
UK Edition only
Optional
To specify if tax can be reclaimed for this mileage expense.
fuel_type
UK Edition only
Optional
Fuel type for a particular mileage expense. Allowed Values:
petrol, lpg and diesel
engine_capacity_range
UK Edition only
Optional
Engine capacity range for a particular mileage expense. Allowed Values:
less_than_1400cc, between_1400cc_and_1600cc, between_1600cc_and_2000cc and more_than_2000cc
paid_through_account_id
Optional
Search expenses by paid through account id.
vendor_id
Optional
ID of the vendor the expense is made.
custom_fields
Optional
Custom fields for an expense.
|
Query Params
|
receipt
Optional
Expense receipt file to attach. Allowed Extensions:
gif, png, jpeg, jpg, bmp, pdf, xls, xlsx, doc and docx. |
Update an Expense
Update an existing Expense
PUT /expenses/{expense_id}
Request Example
$ curl https://books.zoho.com/api/v3/expenses/{expense_id}?organization_id=10234695 -H "Authorization: Zoho-authtoken ba4604e8e433g9c892e360d53463oec5" -H "Content-Type: application/json;charset=UTF-8" -d '{ "account_id": 982000000561057, "date": "2013-11-18T00:00:00.000Z", "amount": 120.5, "tax_id": 982000000566007, "source_of_supply": "AP", "destination_of_supply": "TN", "hsn_or_sac": 80540, "gst_no": "22AAAAA0000A1Z5", "reverse_charge_tax_id": 982000000561063, "line_items": [ { "line_item_id": 10763000000140068, "account_id": 982000000561057, "description": "Marketing", "amount": 120.5, "tax_id": 982000000566007, "item_order": 1, "product_type": "goods", "acquisition_vat_id": " ", "reverse_charge_vat_id": " ", "reverse_charge_tax_id": 982000000561063, "tax_exemption_id": 982000000561067 } ], "is_inclusive_tax": false, "is_billable": true, "reference_number": null, "description": "Marketing", "customer_id": 982000000567001, "currency_id": 982000000567001, "exchange_rate": 1, "project_id": 982000000567226, "mileage_type": "non_mileage", "vat_treatment": "eu_vat_not_registered", "product_type": "goods", "acquisition_vat_id": " ", "reverse_charge_vat_id": " ", "start_reading": " ", "end_reading": " ", "distance": " ", "mileage_unit": " ", "mileage_rate": " ", "employee_id": " ", "vehicle_type": " ", "can_reclaim_vat_on_mileage": " ", "fuel_type": " ", "engine_capacity_range": " ", "paid_through_account_id": 982000000567250, "vendor_id": " ", "custom_fields": [ {} ] }
Response Example
HTTP/1.1 200 OK Content-Type:application/json;charset=UTF-8 { "code": 0, "message": "Expense information has been updated.", "expense": { "expense": { "expense_id": 982000000030049, "transaction_id": " ", "transaction_type": "expense", "gst_no": "22AAAAA0000A1Z5", "gst_treatment": "business_gst", "destination_of_supply": "TN", "destination_of_supply_state": "TN", "hsn_or_sac": 80540, "source_of_supply": "AP", "paid_through_account_name": "Petty Cash", "reverse_charge_tax_id": 982000000561063, "reverse_charge_tax_name": "intra", "reverse_charge_tax_percentage": 10, "reverse_charge_tax_amount": 12, "tax_amount": 11.85, "is_itemized_expense": false, "is_pre_gst": "fasle", "trip_id": "", "trip_number": "", "reverse_charge_vat_total": 1.2, "acquisition_vat_total": 0, "acquisition_vat_summary": [ { "tax": { "tax_name": "SalesTax", "tax_amount": 11.85 } } ], "reverse_charge_vat_summary": [ { "tax": { "tax_name": "SalesTax", "tax_amount": 11.85 } } ], "expense_item_id": 982000000567220, "account_id": 982000000561057, "account_name": "Rent", "date": "2013-11-18T00:00:00.000Z", "tax_id": 982000000566007, "tax_name": "SalesTax", "tax_percentage": 10.5, "currency_id": 982000000567001, "currency_code": "USD", "exchange_rate": 1, "sub_total": 90, "total": 100, "bcy_total": 100, "amount": 120.5, "is_inclusive_tax": false, "reference_number": null, "description": "Marketing", "is_billable": true, "is_personal": false, "customer_id": 982000000567001, "customer_name": "Bowman & Co", "expense_receipt_name": " ", "expense_receipt_type": " ", "last_modified_time": " ", "status": "unbilled", "invoice_id": " ", "invoice_number": " ", "project_id": 982000000567226, "project_name": " ", "mileage_rate": " ", "mileage_type": "non_mileage", "expense_type": "non-mileage", "start_reading": " ", "end_reading": " " } } }
ARGUMENTS
|
account_id
Optional
ID of the expense account.
date
Optional
Date of the expense
amount
Required
Amount of the Expense.
tax_id
Optional
source_of_supply
India Edition only
Optional
Place from where the goods/services are supplied. (If not given,
place of contact given for the contact will be taken)
destination_of_supply
India Edition only
Optional
Place where the goods/services are supplied to. (If not given, organisation's home state will be taken)
hsn_or_sac
India Edition only
Optional
Add HSN/SAC code for your goods/services
gst_no
India Edition only
Optional
15 digit GST identification number of the vendor.
reverse_charge_tax_id
Optional
ID of the reverse charge tax
line_items
Optional
line_item_id
Optional
account_id
Optional
ID of the expense account.
description
Optional
Description of the expense. Max-length [100]
amount
Required
Amount of the Expense.
tax_id
Optional
item_order
Optional
product_type
UK Edition only
Optional
Type of the expense. This denotes whether the expense is to be treated as a goods or service purchase. Allowed Values:
digital_service , goods and service.
acquisition_vat_id
UK Edition only
Optional
This is the ID of the tax applied in case this is an EU - goods expense and acquisition VAT needs to be reported.
reverse_charge_vat_id
UK Edition only
Optional
This is the ID of the tax applied in case this is a non UK - service expense and reverse charge VAT needs to be reported.
reverse_charge_tax_id
Optional
ID of the reverse charge tax
tax_exemption_code
India Edition only
Optional
Enter tax exemption code
tax_exemption_id
India Edition only
Optional
Enter tax exemption ID
is_inclusive_tax
Optional
is_billable
Optional
reference_number
Required
Reference number of the expense. Max-length [100]
description
Optional
Description of the expense. Max-length [100]
customer_id
Optional
ID of the expense account.
currency_id
Optional
exchange_rate
Optional
project_id
Optional
ID of the project associated with the customer.
mileage_type
Optional
vat_treatment
UK Edition only
Optional
VAT treatment for the expense. VAT
treatment denotes the location of the vendor, if the vendor resides in
UK then the VAT treatment is
uk. If the vendor is in an EU country & if he is VAT registered then his VAT treatment is eu_vat_registered, if he resides in EU & if he is not VAT registered then his VAT treatment is eu_vat_not_registered and if he resides outside the EU then his VAT treatment is non_eu.
product_type
UK Edition only
Optional
Type of the expense. This denotes whether the expense is to be treated as a goods or service purchase. Allowed Values:
digital_service , goods and service.
acquisition_vat_id
UK Edition only
Optional
This is the ID of the tax applied in case this is an EU - goods expense and acquisition VAT needs to be reported.
reverse_charge_vat_id
UK Edition only
Optional
This is the ID of the tax applied in case this is a non UK - service expense and reverse charge VAT needs to be reported.
mileage_type
Optional
start_reading
Optional
Start reading of odometer when creating a mileage expense where
mileage_type is odometer.
end_reading
Optional
End reading of odometer when creating a mileage expense where
mileage_type is odometer.
distance
Optional
Distance travelled for a particular mileage expense where
mileage_type is manual
mileage_unit
Optional
Unit of the distance travelled. Allowed Values:
km and mile
mileage_rate
Optional
Mileage rate for a particular mileage expense.
employee_id
UK Edition only
Optional
ID of the employee who has submitted this mileage expense.
vehicle_type
UK Edition only
Optional
Vehicle type for a particular mileage expense. Allowed Values:
car, van, motorcycle and bike
can_reclaim_vat_on_mileage
UK Edition only
Optional
To specify if tax can be reclaimed for this mileage expense.
fuel_type
UK Edition only
Optional
Fuel type for a particular mileage expense. Allowed Values:
petrol, lpg and diesel
engine_capacity_range
UK Edition only
Optional
Engine capacity range for a particular mileage expense. Allowed Values:
less_than_1400cc, between_1400cc_and_1600cc, between_1600cc_and_2000cc and more_than_2000cc
paid_through_account_id
Optional
Search expenses by paid through account id.
vendor_id
Optional
ID of the vendor the expense is made.
custom_fields
Optional
Custom fields for an expense.
|
Query Params
|
receipt
Optional
Expense receipt file to attach. Allowed Extensions:
gif, png, jpeg, jpg, bmp, pdf, xls, xlsx, doc and docx.
delete_receipt
Optional
|
List Expenses
List all the Expenses with pagination.
GET /expenses
Request Example
$ curl https://books.zoho.com/api/v3/expenses?organization_id=10234695 -H "Authorization: Zoho-authtoken ba4604e8e433g9c892e360d53463oec5" -H "Content-Type: application/json;charset=UTF-8"
Response Example
HTTP/1.1 200 OK Content-Type:application/json;charset=UTF-8 { "code": 0, "message": "success", "expenses": [ { "expenses": [ { "expense_id": 982000000030049, "date": "2013-11-18T00:00:00.000Z", "account_name": "Rent", "description": "Marketing", "currency_id": 982000000567001, "currency_code": "USD", "bcy_total": 100, "bcy_total_without_tax": 100, "total": 100, "total_without_tax": 100, "is_billable": true, "reference_number": null, "customer_id": 982000000567001, "customer_name": "Bowman & Co", "status": "unbilled", "created_time": "2013-11-18T02:17:40.080Z", "last_modified_time": " ", "expense_receipt_name": " ", "mileage_rate": " ", "mileage_unit": " ", "expense_type": "non-mileage", "start_reading": " ", "end_reading": " " } ], "page_context": [ { "sort_column": "total", "filter_by": "Status.Billable", "search_text": "Rent", "applied_filter": "Status.All", "page": 1, "per_page": 100 } ] }, {...}, {...} ] }
Query Params
|
description
Optional
Search expenses by description.Variants
description_startswith and description_contains. Max-length [100]
reference_number
Optional
Search expenses by reference number. Variants
reference_number_startswith and reference_number_contains. Max-length [100]
date
Optional
Search expenses by expense date. Variants
date_start, date_end, date_before and date_after. Format [yyyy-mm-dd]
status
Optional
Search expenses by expense status. Allowed Values
unbilled, invoiced, reimbursed, non-billable and billable
amount
Optional
Search expenses by amount. Variants:
amount_less_than, amount_less_equals, amount_greater_than and amount_greater_than
account_name
Optional
Search expenses by expense account name. Variants
account_name_startswith and account_name_contains. Max-length [100]
customer_name
Optional
Search expenses by customer name. Variants:
customer_name_startswith and customer_name_contains. Max-length [100]
vendor_name
Optional
Search expenses by vendor name. Variants: vendor_name_startswith and .
Filter expenses by expense status. Allowed Values |
Get an Expense
Get the details of the Expense
GET /expenses/{expense_id}
Request Example
$ curl https://books.zoho.com/api/v3/expenses/{expense_id}?organization_id=10234695 -H "Authorization: Zoho-authtoken ba4604e8e433g9c892e360d53463oec5" -H "Content-Type: application/json;charset=UTF-8"
Response Example
HTTP/1.1 200 OK Content-Type:application/json;charset=UTF-8 { "code": 0, "message": "success", "expense": { "expense": { "expense_id": 982000000030049, "transaction_id": " ", "transaction_type": "expense", "gst_no": "22AAAAA0000A1Z5", "gst_treatment": "business_gst", "destination_of_supply": "TN", "destination_of_supply_state": "TN", "hsn_or_sac": 80540, "source_of_supply": "AP", "paid_through_account_name": "Petty Cash", "reverse_charge_tax_id": 982000000561063, "reverse_charge_tax_name": "intra", "reverse_charge_tax_percentage": 10, "reverse_charge_tax_amount": 12, "tax_amount": 11.85, "is_itemized_expense": false, "is_pre_gst": "fasle", "trip_id": "", "trip_number": "", "reverse_charge_vat_total": 1.2, "acquisition_vat_total": 0, "acquisition_vat_summary": [ { "tax": { "tax_name": "SalesTax", "tax_amount": 11.85 } } ], "reverse_charge_vat_summary": [ { "tax": { "tax_name": "SalesTax", "tax_amount": 11.85 } } ], "expense_item_id": 982000000567220, "account_id": 982000000561057, "account_name": "Rent", "date": "2013-11-18T00:00:00.000Z", "tax_id": 982000000566007, "tax_name": "SalesTax", "tax_percentage": 10.5, "currency_id": 982000000567001, "currency_code": "USD", "exchange_rate": 1, "sub_total": 90, "total": 100, "bcy_total": 100, "amount": 112.5, "is_inclusive_tax": false, "reference_number": null, "description": "Marketing", "is_billable": true, "is_personal": false, "customer_id": 982000000567001, "customer_name": "Bowman & Co", "expense_receipt_name": " ", "expense_receipt_type": " ", "last_modified_time": " ", "status": "unbilled", "invoice_id": " ", "invoice_number": " ", "project_id": 982000000567226, "project_name": " ", "mileage_rate": " ", "mileage_type": "non_mileage", "expense_type": "non-mileage", "start_reading": " ", "end_reading": " ", "line_item": { "line_item_id": 10763000000140068, "account_id": 982000000561057, "account_name": "Rent", "description": "Marketing", "tax_amount": 11.85, "tax_id": 982000000566007, "tax_name": "SalesTax", "tax_type": "tax", "tax_percentage": 10.5, "item_total": 100, "item_order": 1, "amount": 112.5, "hsn_or_sac": 80540, "reverse_charge_tax_id": 982000000561063, "reverse_charge_tax_name": "intra", "reverse_charge_tax_percentage": 10, "reverse_charge_tax_amount": 12 } } } }
Delete an Expense
Delete an existing expense.
DELETE /expenses/{expense_id}
Request Example
$ curl https://books.zoho.com/api/v3/expenses/{expense_id}?organization_id=10234695 -H "Authorization: Zoho-authtoken ba4604e8e433g9c892e360d53463oec5" -H "Content-Type: application/json;charset=UTF-8"
Response Example
HTTP/1.1 200 OK Content-Type:application/json;charset=UTF-8 { "code": 0, "message": "The expense has been deleted." }
List expense History & Comments
Get history and comments of expense
GET /expense/{expense_id}/comments
Request Example
$ curl https://books.zoho.com/api/v3/expense/{expense_id}/comments?organization_id=10234695 -H "Authorization: Zoho-authtoken ba4604e8e433g9c892e360d53463oec5" -H "Content-Type: application/json;charset=UTF-8"
Response Example
HTTP/1.1 200 OK Content-Type:application/json;charset=UTF-8 { "code": 0, "message": "success", "comments": { "comments": [ { "comment_id": 982000000567272, "expense_id": 982000000030049, "description": "Marketing", "commented_by_id": 982000000554041, "commented_by": "John David", "date_description": "16 hours ago", "time": "4.22AM", "operation_type": "Added", "transaction_id": " ", "transaction_type": "expense" } ] } }
List employees
List employees with pagination
GET /employees
Request Example
$ curl https://books.zoho.com/api/v3/employees?organization_id=10234695 -H "Authorization: Zoho-authtoken ba4604e8e433g9c892e360d53463oec5" -H "Content-Type: application/json;charset=UTF-8" -d '{ "sort_column": "total", "filter_by": "Status.Billable" }
Response Example
HTTP/1.1 200 OK Content-Type:application/json;charset=UTF-8 { "code": 0, "message": "success", "employees": { "employees": [ { "employee_id": " ", "name": "John David", "email": "johnsmith@zilliuminc.com" } ], "page_context": [ { "sort_column": "total", "filter_by": "Status.Billable", "search_text": "Rent", "applied_filter": "Status.All", "page": 1, "per_page": 100 } ] } }
ARGUMENTS
|
sort_column
Optional
Sort expenses.Allowed Values
date, account_name, total, bcy_total, reference_number, customer_name and created_time
filter_by
Optional
Filter expenses by expense status. Allowed Values
Status.All, Status.Billable, Status.Nonbillable, Status.Reimbursed, Status.InvoicedStatus.Unbilled |
Get an employee
Get the details of the employee
GET /employees/{employee_id}
Request Example
$ curl https://books.zoho.com/api/v3/employees/{employee_id}?organization_id=10234695 -H "Authorization: Zoho-authtoken ba4604e8e433g9c892e360d53463oec5" -H "Content-Type: application/json;charset=UTF-8"
Response Example
HTTP/1.1 200 OK Content-Type:application/json;charset=UTF-8 { "code": 0, "message": "success", "employee": { "employee": { "employee_id": " ", "name": "John David", "email": "johnsmith@zilliuminc.com" } } }
Create an employee
Create an employee for an expense
POST /employees
Request Example
$ curl https://books.zoho.com/api/v3/employees?organization_id=10234695 -H "Authorization: Zoho-authtoken ba4604e8e433g9c892e360d53463oec5" -H "Content-Type: application/json;charset=UTF-8" -d '{ "name": "John David", "email": "johnsmith@zilliuminc.com" }
Response Example
HTTP/1.1 201 Created Content-Type:application/json;charset=UTF-8 { "code": 0, "message": "success", "employee": { "employee": { "employee_id": " ", "name": "John David", "email": "johnsmith@zilliuminc.com" } } }
ARGUMENTS
|
name
Required
email
Required
|
Delete an employee
Delete an existing employee
DELETE /employee/{employee_id}
Request Example
$ curl https://books.zoho.com/api/v3/employee/{employee_id}?organization_id=10234695 -H "Authorization: Zoho-authtoken ba4604e8e433g9c892e360d53463oec5" -H "Content-Type: application/json;charset=UTF-8"
Response Example
HTTP/1.1 200 OK Content-Type:application/json;charset=UTF-8 { "code": 0, "message": "Employee has been deleted." }
Get an expense receipt
Returns the receipt attached to the expense.
GET /expenses/{expense_id}/receipt
Request Example
$ curl https://books.zoho.com/api/v3/expenses/{expense_id}/receipt?organization_id=10234695 -H "Authorization: Zoho-authtoken ba4604e8e433g9c892e360d53463oec5" -H "Content-Type: application/json;charset=UTF-8"
Response Example
HTTP/1.1 200 OK Content-Type:application/json;charset=UTF-8 { "code": 0, "message": "success" }
Query Params
|
preview
Optional
Get the thumbnail of the receipt.
|
Add receipt to an expense.
Attach a receipt to an expense.
POST /expenses/{expense_id}/receipt
Request Example
$ curl https://books.zoho.com/api/v3/expenses/{expense_id}/receipt?organization_id=10234695 -H "Authorization: Zoho-authtoken ba4604e8e433g9c892e360d53463oec5" -H "Content-Type: application/json;charset=UTF-8"
Response Example
HTTP/1.1 200 OK Content-Type:application/json;charset=UTF-8 { "code": 0, "message": "The expense receipt has been attached." }
Query Params
|
receipt
Optional
Expense receipt file to attach. Allowed Extensions:
gif, png, jpeg, jpg, bmp, pdf, xls, xlsx, doc and docx. |
Delete a receipt
Delete the receipt attached to the expense.
DELETE /expenses/{expense_id}/receipt
Request Example
$ curl https://books.zoho.com/api/v3/expenses/{expense_id}/receipt?organization_id=10234695 -H "Authorization: Zoho-authtoken ba4604e8e433g9c892e360d53463oec5" -H "Content-Type: application/json;charset=UTF-8"
Response Example
HTTP/1.1 200 OK Content-Type:application/json;charset=UTF-8 { "code": 0, "message": "The attached expense receipt has been deleted." }
Recurring-Expenses
Recurring expenses are those expenses that repeat itself after a fixed interval of time.
Example
{ "recurrence_name": "Monthly Rental", "status": "active", "account_id": 982000000561057, "account_name": "Rent", "amount": 112.5, "customer_name": "Bowman & Co", "is_billable": true }
Attribute
|
recurrence_name
String
Name of the Recurring Expense. Max-length [100]
status
String
Status of the recurring expense
account_id
String
account_name
String
For which Account the Expense is raised. Max-length [100]
amount
double
Recurring Expense amount.
customer_name
String
Name of the Custome for which expense is raised. Max-length [100]
is_billable
boolean
|
Create a recurring expense
Create a recurring expense
POST /recurringexpenses
Request Example
$ curl https://books.zoho.com/api/v3/recurringexpenses?organization_id=10234695 -H "Authorization: Zoho-authtoken ba4604e8e433g9c892e360d53463oec5" -H "Content-Type: application/json;charset=UTF-8" -d '{ "account_id": 982000000561057, "recurrence_name": "Monthly Rental", "start_date": "2016-11-19T00:00:00.000Z", "end_date": " ", "recurrence_frequency": "months", "repeat_every": 1, "gst_no": "22AAAAA0000A1Z5", "source_of_supply": "AP", "destination_of_supply": "TN", "reverse_charge_tax_id": 982000000567254, "line_items": [ { "line_item_id": 10763000000140068, "account_id": 982000000561057, "description": " ", "amount": 112.5, "tax_id": 982000000566007, "item_order": 1, "product_type": "goods", "acquisition_vat_id": " ", "reverse_charge_vat_id": " ", "reverse_charge_tax_id": 982000000567254, "tax_exemption_id": 982000000567267 } ], "amount": 112.5, "vat_treatment": "eu_vat_not_registered", "product_type": "goods", "acquisition_vat_id": " ", "reverse_charge_vat_id": " ", "tax_id": 982000000566007, "is_inclusive_tax": false, "is_billable": true, "customer_id": 982000000567001, "project_id": " ", "currency_id": 982000000567001, "exchange_rate": 1 }
Response Example
HTTP/1.1 200 OK Content-Type:application/json;charset=UTF-8 { "code": 0, "message": "The recurring expense has been created", "recurring_expense": { "account_id": 982000000561057, "recurrence_name": "Monthly Rental", "start_date": "2016-11-19T00:00:00.000Z", "end_date": " ", "is_pre_gst": false, "source_of_supply": "AP", "destination_of_supply": "TN", "gst_no": "22AAAAA0000A1Z5", "gst_treatment": "business_gst", "destination_of_supply_state": "AP", "hsn_or_sac": 80540, "vat_treatment": "eu_vat_not_registered", "reverse_charge_tax_id": 982000000567254, "reverse_charge_tax_name": "inter", "reverse_charge_tax_percentage": 10, "reverse_charge_tax_amount": 10, "is_reverse_charge_applied": false, "acquisition_vat_total": 0, "reverse_charge_vat_total": 10, "acquisition_vat_summary": [ { "tax_name": "SalesTax", "tax_amount": 11.85 } ], "reverse_charge_vat_summary": [ { "tax_name": "SalesTax", "tax_amount": 11.85 } ], "recurrence_frequency": "months", "repeat_every": 1, "amount": 112.5, "total": 128.25, "sub_total": 90, "bcy_total": 100, "product_type": "goods", "acquisition_vat_id": " ", "reverse_charge_vat_id": " ", "tax_id": 982000000566007, "tax_name": "SalesTax", "tax_percentage": 10.5, "created_time": "2013-11-18T02:17:40.080Z", "last_modified_time": " ", "is_inclusive_tax": false, "is_billable": true, "customer_id": 982000000567001, "currency_id": 982000000567001, "exchange_rate": 1, "project_id": " ", "project_name": " ", "line_item": { "line_item_id": 10763000000140068, "account_id": 982000000561057, "account_name": "Rent", "description": " ", "tax_amount": 11.85, "tax_id": 982000000566007, "tax_name": "SalesTax", "tax_type": "tax", "tax_percentage": 10.5, "item_total": 100, "item_order": 1, "hsn_or_sac": 80540, "reverse_charge_tax_id": 982000000567254, "reverse_charge_tax_name": "inter", "reverse_charge_tax_percentage": 10, "reverse_charge_tax_amount": 10 } } }
ARGUMENTS
|
account_id
Required
recurrence_name
Required
Name of the Recurring Expense. Max-length [100]
start_date
Required
Start date of the recurring expense. Expenses will not be generated for dates prior to the current date. Format [yyyy-mm-dd].
end_date
Optional
Date on which recurring expense has to expire. Can be left as empty to run forever. Format [yyyy-mm-dd].
recurrence_frequency
Required
repeat_every
Required
gst_no
India Edition only.
Optional
15 digit GST identification number of the vendor.
source_of_supply
India Edition only.
Optional
Place from where the goods/services are supplied. (If not given,
place of contact given for the contact will be taken)
destination_of_supply
India Edition only.
Optional
Place where the goods/services are supplied to. (If not given, organisation's home state will be taken)
reverse_charge_tax_id
India Edition only.
Optional
Enter reverse charge tax ID
line_items
Optional
line_item_id
Optional
account_id
Required
description
Optional
Search recurring expenses by description. Max-length [100]
amount
Required
Recurring Expense amount.
tax_id
Optional
item_order
Optional
product_type
UK Edition only
Optional
Type of the expense. This denotes whether the expense is to be treated as a goods or service purchase. Allowed Values:
digital_service, goods and service.
acquisition_vat_id
UK Edition only
Optional
This is the ID of the tax applied in case this is an EU - goods expense and acquisition VAT needs to be reported.
reverse_charge_vat_id
India Edition and UK Edition only
Optional
This is the ID of the tax applied in case this is a non UK - service expense and reverse charge VAT needs to be reported.
reverse_charge_tax_id
India Edition only.
Optional
Enter reverse charge tax ID
tax_exemption_code
India Edition only.
Optional
Enter the code for tax exemption
tax_exemption_id
India Edition only.
Optional
Enter ID of the tax exemption
amount
Required
Recurring Expense amount.
vat_treatment
UK Edition only
Optional
VAT treatment for the expense. VAT
treatment denotes the location of the vendor, if the vendor resides in
UK then the VAT treatment is
uk. If the vendor is in an EU country & if he is VAT registered then his VAT treatment is eu_vat_registered, if he resides in EU & if he is not VAT registered then his VAT treatment is eu_vat_not_registered and if he resides outside the EU then his VAT treatment is non_eu.
product_type
UK Edition only
Optional
Type of the expense. This denotes whether the expense is to be treated as a goods or service purchase. Allowed Values:
digital_service, goods and service.
acquisition_vat_id
UK Edition only
Optional
This is the ID of the tax applied in case this is an EU - goods expense and acquisition VAT needs to be reported.
reverse_charge_vat_id
India Edition and UK Edition only
Optional
This is the ID of the tax applied in case this is a non UK - service expense and reverse charge VAT needs to be reported.
tax_id
Optional
is_inclusive_tax
Optional
is_billable
Optional
customer_id
Optional
Search expenses by customer id.
project_id
Optional
currency_id
Optional
exchange_rate
Optional
|
Update a recurring expense
Update a recurring expense
POST /recurringexpenses/{recurring_expense_id}
Request Example
$ curl https://books.zoho.com/api/v3/recurringexpenses/{recurring_expense_id}?organization_id=10234695 -H "Authorization: Zoho-authtoken ba4604e8e433g9c892e360d53463oec5" -H "Content-Type: application/json;charset=UTF-8" -d '{ "account_id": 982000000561057, "recurrence_name": "Monthly Rental", "start_date": "2016-11-19T00:00:00.000Z", "end_date": " ", "recurrence_frequency": "months", "repeat_every": 1, "gst_no": "22AAAAA0000A1Z5", "source_of_supply": "AP", "destination_of_supply": "TN", "reverse_charge_tax_id": 982000000567254, "line_items": [ { "line_item_id": 10763000000140068, "account_id": 982000000561057, "description": " ", "amount": 112.5, "tax_id": 982000000566007, "item_order": 1, "product_type": "goods", "acquisition_vat_id": " ", "reverse_charge_vat_id": " ", "reverse_charge_tax_id": 982000000567254, "tax_exemption_id": 982000000567267 } ], "amount": 112.5, "vat_treatment": "eu_vat_not_registered", "product_type": "goods", "acquisition_vat_id": " ", "reverse_charge_vat_id": " ", "tax_id": 982000000566007, "is_inclusive_tax": false, "is_billable": true, "customer_id": 982000000567001, "project_id": " ", "currency_id": 982000000567001, "exchange_rate": 1 }
Response Example
HTTP/1.1 200 OK Content-Type:application/json;charset=UTF-8 { "code": 0, "message": "Recurring expense information has been updated", "recurring_expense": { "account_id": 982000000561057, "recurrence_name": "Monthly Rental", "start_date": "2016-11-19T00:00:00.000Z", "end_date": " ", "is_pre_gst": false, "source_of_supply": "AP", "destination_of_supply": "TN", "gst_no": "22AAAAA0000A1Z5", "gst_treatment": "business_gst", "destination_of_supply_state": "AP", "hsn_or_sac": 80540, "vat_treatment": "eu_vat_not_registered", "reverse_charge_tax_id": 982000000567254, "reverse_charge_tax_name": "inter", "reverse_charge_tax_percentage": 10, "reverse_charge_tax_amount": 10, "is_reverse_charge_applied": false, "acquisition_vat_total": 0, "reverse_charge_vat_total": 10, "acquisition_vat_summary": [ { "tax_name": "SalesTax", "tax_amount": 11.85 } ], "reverse_charge_vat_summary": [ { "tax_name": "SalesTax", "tax_amount": 11.85 } ], "recurrence_frequency": "months", "repeat_every": 1, "amount": 120.5, "total": 128.25, "sub_total": 90, "bcy_total": 100, "product_type": "goods", "acquisition_vat_id": " ", "reverse_charge_vat_id": " ", "tax_id": 982000000566007, "tax_name": "SalesTax", "tax_percentage": 10.5, "created_time": "2013-11-18T02:17:40.080Z", "last_modified_time": " ", "is_inclusive_tax": false, "is_billable": true, "customer_id": 982000000567001, "currency_id": 982000000567001, "exchange_rate": 1, "project_id": " ", "project_name": " ", "line_item": { "line_item_id": 10763000000140068, "account_id": 982000000561057, "account_name": "Rent", "description": " ", "tax_amount": 11.85, "tax_id": 982000000566007, "tax_name": "SalesTax", "tax_type": "tax", "tax_percentage": 10.5, "item_total": 100, "item_order": 1, "hsn_or_sac": 80540, "reverse_charge_tax_id": 982000000567254, "reverse_charge_tax_name": "inter", "reverse_charge_tax_percentage": 10, "reverse_charge_tax_amount": 10 } } }
ARGUMENTS
|
account_id
Required
recurrence_name
Required
Name of the Recurring Expense. Max-length [100]
start_date
Required
Start date of the recurring expense. Expenses will not be generated for dates prior to the current date. Format [yyyy-mm-dd].
end_date
Optional
Date on which recurring expense has to expire. Can be left as empty to run forever. Format [yyyy-mm-dd].
recurrence_frequency
Required
repeat_every
Required
gst_no
India Edition only.
Optional
15 digit GST identification number of the vendor.
source_of_supply
India Edition only.
Optional
Place from where the goods/services are supplied. (If not given,
place of contact given for the contact will be taken)
destination_of_supply
India Edition only.
Optional
Place where the goods/services are supplied to. (If not given, organisation's home state will be taken)
reverse_charge_tax_id
India Edition only.
Optional
Enter reverse charge tax ID
line_items
Optional
line_item_id
Optional
account_id
Required
description
Optional
Search recurring expenses by description. Max-length [100]
amount
Required
Recurring Expense amount.
tax_id
Optional
item_order
Optional
product_type
UK Edition only
Optional
Type of the expense. This denotes whether the expense is to be treated as a goods or service purchase. Allowed Values:
digital_service, goods and service.
acquisition_vat_id
UK Edition only
Optional
This is the ID of the tax applied in case this is an EU - goods expense and acquisition VAT needs to be reported.
reverse_charge_vat_id
India Edition and UK Edition only
Optional
This is the ID of the tax applied in case this is a non UK - service expense and reverse charge VAT needs to be reported.
reverse_charge_tax_id
India Edition only.
Optional
Enter reverse charge tax ID
tax_exemption_code
India Edition only.
Optional
Enter the code for tax exemption
tax_exemption_id
India Edition only.
Optional
Enter ID of the tax exemption
amount
Required
Recurring Expense amount.
vat_treatment
UK Edition only
Optional
VAT treatment for the expense. VAT
treatment denotes the location of the vendor, if the vendor resides in
UK then the VAT treatment is
uk. If the vendor is in an EU country & if he is VAT registered then his VAT treatment is eu_vat_registered, if he resides in EU & if he is not VAT registered then his VAT treatment is eu_vat_not_registered and if he resides outside the EU then his VAT treatment is non_eu.
product_type
UK Edition only
Optional
Type of the expense. This denotes whether the expense is to be treated as a goods or service purchase. Allowed Values:
digital_service, goods and service.
acquisition_vat_id
UK Edition only
Optional
This is the ID of the tax applied in case this is an EU - goods expense and acquisition VAT needs to be reported.
reverse_charge_vat_id
India Edition and UK Edition only
Optional
This is the ID of the tax applied in case this is a non UK - service expense and reverse charge VAT needs to be reported.
tax_id
Optional
is_inclusive_tax
Optional
is_billable
Optional
customer_id
Optional
Search expenses by customer id.
project_id
Optional
currency_id
Optional
exchange_rate
Optional
|
List recurring expenses
List all the Expenses with pagination.
GET recurringexpenses
Request Example
$ curl https://books.zoho.com/api/v3recurringexpenses?organization_id=10234695 -H "Authorization: Zoho-authtoken ba4604e8e433g9c892e360d53463oec5" -H "Content-Type: application/json;charset=UTF-8"
Response Example
HTTP/1.1 200 OK Content-Type:application/json;charset=UTF-8 { "code": 0, "message": "success", "recurring_expenses": [ { "recurring_expenses": [ { "recurring_expense_id": 982000000567240, "recurrence_name": "Monthly Rental", "recurrence_frequency": "months", "repeat_every": 1, "last_created_date": "2013-11-18T00:00:00.000Z", "next_expense_date": "2013-12-18T00:00:00.000Z", "account_name": "Rent", "description": " ", "currency_id": 982000000567001, "currency_code": "USD", "total": 128.25, "is_billable": true, "customer_name": "Bowman & Co", "status": "active", "created_time": "2013-11-18T02:17:40.080Z", "last_modified_time": " " } ], "page_context": [ { "sort_column": "account_name", "filter_by": "Status.Billable", "search_text": "Rent" } ] }, {...}, {...} ] }
Query Params
|
recurrence_name
Optional
Search recurring expenses by recurring expense name. Variants:
recurrence_name_startswith and recurrence_name_contains. Max-length [100]
last_created_date
Optional
Search recurring expenses by date on when last expense was generated. Variants:
last_created_date_start, last_created_date_end, last_created_date_before and last_created_date_after . Format [yyyy-mm-dd]
next_expense_date
Optional
Search recurring expenses by date on which next expense will be generated. Variants:
next_expense_date_start, next_expense_date_end, next_expense_date_before and next_expense_date_after . Format [yyyy-mm-dd]
status
Optional
Search expenses by expense status. Allowed Values
active, stopped and expired
account_id
Optional
account_name
Optional
Search expenses by expense account name. Variants
account_name_startswith and account_name_contains . Max-length [100]
amount
Optional
Search expenses by amount. Variants:
amount_less_than, amount_less_equals, amount_greater_than and amount_greater_than
customer_name
Optional
Search expenses by customer name. Variants:
customer_name_startswith and customer_name_contains . Max-length [100]
customer_id
Optional
Search expenses by customer id.
paid_through_account_id
Optional
Search expenses by paid through account id.
filter_by
Optional
Filter expenses by expense status. Allowed Values
Status.All, Status.Active, Status.Expired and Status.Stopped
search_text
Optional
Search expenses by account name or description or
customer name or vendor name. Max-length [100] .
sort_column
Optional
Sort expenses.Allowed Values
next_expense_date, account_name, total, last_created_date, recurrence_name, customer_name and created_time |
Get a recurring expense
Get the details of the recurring expense
GET /recurringexpenses/{recurring_expense_id}
Request Example
$ curl https://books.zoho.com/api/v3/recurringexpenses/{recurring_expense_id}?organization_id=10234695 -H "Authorization: Zoho-authtoken ba4604e8e433g9c892e360d53463oec5" -H "Content-Type: application/json;charset=UTF-8"
Response Example
HTTP/1.1 200 OK Content-Type:application/json;charset=UTF-8 { "code": 0, "message": "success", "expense": { "recurring_expense": { "recurring_expense_id": 982000000567240, "recurrence_name": "Monthly Rental", "start_date": "2016-11-19T00:00:00.000Z", "end_date": " ", "is_pre_gst": false, "source_of_supply": "AP", "destination_of_supply": "TN", "gst_no": "22AAAAA0000A1Z5", "gst_treatment": "business_gst", "destination_of_supply_state": "AP", "hsn_or_sac": 80540, "vat_treatment": "eu_vat_not_registered", "reverse_charge_tax_id": 982000000567254, "reverse_charge_tax_name": "inter", "reverse_charge_tax_percentage": 10, "reverse_charge_tax_amount": 10, "is_reverse_charge_applied": false, "acquisition_vat_total": 0, "reverse_charge_vat_total": 10, "acquisition_vat_summary": [ { "tax_name": "SalesTax", "tax_amount": 11.85 } ], "reverse_charge_vat_summary": [ { "tax_name": "SalesTax", "tax_amount": 11.85 } ], "recurrence_frequency": "months", "repeat_every": 1, "last_created_date": "2013-11-18T00:00:00.000Z", "next_expense_date": "2013-12-18T00:00:00.000Z", "account_id": 982000000561057, "account_name": "Rent", "currency_id": 982000000567001, "currency_code": "USD", "exchange_rate": 1, "tax_id": 982000000566007, "tax_name": "SalesTax", "tax_percentage": 10.5, "tax_amount": 11.85, "sub_total": 90, "total": 128.25, "bcy_total": 100, "amount": 112.5, "description": " ", "is_inclusive_tax": false, "is_billable": true, "customer_id": 982000000567001, "customer_name": "Bowman & Co", "status": "active", "created_time": "2013-11-18T02:17:40.080Z", "last_modified_time": " ", "project_id": " ", "project_name": " ", "line_item": { "line_item_id": 10763000000140068, "account_id": 982000000561057, "account_name": "Rent", "description": " ", "tax_amount": 11.85, "tax_id": 982000000566007, "tax_name": "SalesTax", "tax_type": "tax", "tax_percentage": 10.5, "item_total": 100, "item_order": 1, "hsn_or_sac": 80540, "reverse_charge_tax_id": 982000000567254, "reverse_charge_tax_name": "inter", "reverse_charge_tax_percentage": 10, "reverse_charge_tax_amount": 10 } } } }
Delete a recurring expense
Deleting an existing recurring expense
DELETE /recurringexpenses/{recurring_expense_id}
Request Example
$ curl https://books.zoho.com/api/v3 /recurringexpenses/{recurring_expense_id}?organization_id=10234695 -H "Authorization: Zoho-authtoken ba4604e8e433g9c892e360d53463oec5" -H "Content-Type: application/json;charset=UTF-8"
Response Example
HTTP/1.1 200 OK Content-Type:application/json;charset=UTF-8 { "code": 0, "message": "The recurring expense has been deleted." }
Stop a recurring expense
Stop an active recurring expense
POST /recurringexpenses/{recurring_expense_id}/status/stop
Request Example
$ curl https://books.zoho.com/api/v3/recurringexpenses/{recurring_expense_id}/status/stop?organization_id=10234695 -H "Authorization: Zoho-authtoken ba4604e8e433g9c892e360d53463oec5" -H "Content-Type: application/json;charset=UTF-8"
Response Example
HTTP/1.1 200 OK Content-Type:application/json;charset=UTF-8 { "code": 0, "message": "The recurring expense has been stopped." }
Resume a recurring Expense
Resume a stopped recurring expense.
POST /recurringexpenses/{recurring_expense_id}/status/resume
Request Example
$ curl https://books.zoho.com/api/v3/recurringexpenses/{recurring_expense_id}/status/resume?organization_id=10234695 -H "Authorization: Zoho-authtoken ba4604e8e433g9c892e360d53463oec5" -H "Content-Type: application/json;charset=UTF-8"
Response Example
HTTP/1.1 200 OK Content-Type:application/json;charset=UTF-8 { "code": 0, "message": "The recurring expense has been activated." }
List child expenses created
List child expenses created from recurring expense.
GET /recurringexpenses/{recurring_expense_id}/expenses
Request Example
$ curl https://books.zoho.com/api/v3/recurringexpenses/{recurring_expense_id}/expenses?organization_id=10234695 -H "Authorization: Zoho-authtoken ba4604e8e433g9c892e360d53463oec5" -H "Content-Type: application/json;charset=UTF-8"
Response Example
HTTP/1.1 200 OK Content-Type:application/json;charset=UTF-8 { "code": 0, "message": "success", "expensehistory": [ { "expense_id": 982000000567250, "account_name": "Rent", "customer_name": "Bowman & Co", "total": 128.25, "status": "active", "vendor_name": " ", "paid_through_account_name": "Undeposited Funds" } ], "page_context": [ { "sort_column": "account_name", "filter_by": "Status.Billable", "search_text": "Rent" } ] }
Query Params
|
sort_column
Optional
Sort expenses.Allowed Values
next_expense_date, account_name, total, last_created_date, recurrence_name, customer_name and created_time |
List recurring expense history
Get history and comments of a recurring expense.
GET /recurringexpenses/{recurring_expense_id}/comments
Request Example
$ curl https://books.zoho.com/api/v3/recurringexpenses/{recurring_expense_id}/comments?organization_id=10234695 -H "Authorization: Zoho-authtoken ba4604e8e433g9c892e360d53463oec5" -H "Content-Type: application/json;charset=UTF-8"
Response Example
HTTP/1.1 200 OK Content-Type:application/json;charset=UTF-8 { "code": 0, "message": "success", "comments": { "comment_id": 982000000567272, "recurring_expense_id": 982000000567240, "description": " ", "commented_by_id": 982000000554041, "commented_by": "John David", "time": "2.41 AM", "operation_type": "Added", "transaction_id": " ", "transaction_type": "expense" } }
Retainer-Invoices
A lot of businesses collect an advance payment (or retainer) for products sold or services rendered by them. This amount collected will not be an income but a liability to the company. The revenue is earned only when the product is delivered or the service is completed, if not delivered or completed the advance payment made will be returned to the customer.
Example
{ "retainerinvoice_id": 982000000567114, "customer_name": "Bowman & Co", "retainerinvoice_number": "RET-00003", "customer_id": 982000000567001, "status": "draft", "reference_number": " ", "project_or_estimate_name": "new project", "date": "2013-11-17", "currency_id": 982000000000190, "currency_code": "USD", "is_viewed_by_client": true, "client_viewed_time": true, "total": 40.6, "balance": 40.6, "created_time": "2013-11-18T02:31:51-0800", "last_modified_time": "2013-11-18T02:31:51-0800", "is_emailed": false, "last_payment_date": " ", "has_attachment": true }
Attribute
|
retainerinvoice_id
string
The id of the retainerinvoice
customer_name
string
The name of the customer. Max-length [100]
retainerinvoice_number
string
number of the retainer invoice.Variants:
retainerinvoice_number_startswith and retainerinvoice_number_contains. Max-length [100]
customer_id
string
ID of the customer the retainer invoice has to be created.
status
string
retainer invoice status.Allowed Values:
sent, draft, overdue, paid, void, unpaid, partially_paid and viewed
reference_number
string
The reference number of the retainer invoice. Max-length [100]
project_or_estimate_name
string
date
string
The date of creation of the retainer invoice.
currency_id
string
The currenct id of the currency
currency_code
string
The currency code in which the retainer invoice is created.
is_viewed_by_client
boolean
Boolean is retainer invoice viewed by client in client portal.
client_viewed_time
boolean
client viewed time for retainer invoice in client portal.
total
string
The total amount to be paid
balance
string
The unpaid amount
created_time
string
The time of creation of the retainer invoice
last_modified_time
string
The time of last modification of the retainer invoice
is_emailed
string
Boolean check to if the email was sent
last_payment_date
string
The last payment date of the retainer invoice
has_attachment
boolean
Boolean retainer invoice has attachment
|
Create a retainerinvoice
Create a retainer invoice for your customer.
POST /retainerinvoices
Request Example
$ curl https://books.zoho.com/api/v3/retainerinvoices?organization_id=10234695 -H "Authorization: Zoho-authtoken ba4604e8e433g9c892e360d53463oec5" -H "Content-Type: application/json;charset=UTF-8" -d '{ "customer_id": 982000000567001, "reference_number": " ", "date": "2013-11-17", "contact_persons": [ "982000000567003" ], "custom_fields": [ { "index": 1, "show_on_pdf": false, "value": "The value of the custom field", "label": "Delivery Date" } ], "notes": "Looking forward for your business.", "terms": "Terms & Conditions apply", "line_items": [ { "description": "500GB, USB 2.0 interface 1400 rpm, protective hard case.", "item_order": 1, "rate": 120 } ], "payment_options": { "payment_gateways": [ { "gateway_name": "paypal" } ] }, "template_id": 982000000000143, "place_of_supply": "TN" }
Response Example
HTTP/1.1 201 Created Content-Type:application/json;charset=UTF-8 { "code": 0, "message": "The retainer invoice has been created.", "retainerinvoice": { "retainerinvoices": { "retainerinvoice_id": 982000000567114, "retainerinvoice_number": "RET-00003", "date": "2013-11-17", "status": "draft", "is_pre_gst": false, "place_of_supply": "TN", "project_id": 982000000567154, "last_payment_date": " ", "reference_number": " ", "customer_id": 982000000567001, "customer_name": "Bowman & Co", "contact_persons": [ "982000000567003" ], "currency_id": 982000000000190, "currency_code": "USD", "currency_symbol": "USD", "exchange_rate": 1, "is_viewed_by_client": true, "client_viewed_time": true, "is_inclusive_tax": false, "line_items": [ { "line_item_id": 982000000567021, "description": "500GB, USB 2.0 interface 1400 rpm, protective hard case.", "item_order": 1, "rate": 120, "bcy_rate": 120, "tax_id": 982000000557028, "tax_name": "VAT", "tax_type": "tax", "tax_percentage": 12.5, "item_total": 120 } ], "sub_total": 153, "total": 40.6, "taxes": [ { "tax_name": "VAT", "tax_amount": 19.13 } ], "payment_made": 26.91, "payment_drawn": 26.91, "balance": 40.6, "allow_partial_payments": true, "price_precision": 2, "payment_options": { "payment_gateways": [ { "gateway_name": "paypal" } ] }, "is_emailed": false, "documents": [ {...} ], "billing_address": { "address": "Suite 125, McMillan Avenue", "street2": "McMillan Avenue", "city": "San Francisco", "state": "CA", "zip": 94134, "country": "U.S.A", "fax": "+86-10-82637827" }, "shipping_address": { "address": "Suite 125, McMillan Avenue", "city": "San Francisco", "state": "CA", "zip": 94134, "country": "U.S.A", "fax": "+86-10-82637827" }, "notes": "Looking forward for your business.", "terms": "Terms & Conditions apply", "custom_fields": [ { "index": 1, "show_on_pdf": false, "value": "The value of the custom field", "label": "Delivery Date" } ], "template_id": 982000000000143, "template_name": "Service - Classic", "page_width": "8.27in", "page_height": "11.69in", "orientation": "portrait", "template_type": "classic", "created_time": "2013-11-18T02:31:51-0800", "last_modified_time": "2013-11-18T02:31:51-0800", "created_by_id": 14909000000072000, "attachment_name": "new file", "can_send_in_mail": true, "invoice_url": "https://invoice.zoho.com/SecurePayment?CInvoiceID=23d84d0cf64f9a72ea0c66fded25a08c8bafd0ab508aff05323a9f80e2cd03fdc5dd568d3d6407bbda969d3e870d740b6fce549a9438c4ea" } } }
ARGUMENTS
|
customer_id
Required
ID of the customer the retainer invoice has to be created.
reference_number
Optional
The reference number of the retainer invoice. Max-length [100]
date
Optional
The date of creation of the retainer invoice.
contact_persons
Optional
custom_fields
Optional
Custom fields for a reatiner invoice.
index
Optional
The index of the custom field
show_on_pdf
Optional
Boolean value to check if the custom field is to be dispplayed on the pdf.
value
Optional
label
Optional
The label of the custom field.
notes
Optional
The notes added below expressing gratitude or for conveying some information.
terms
Optional
The terms added below expressing gratitude or for conveying some information.
line_items
Required
Line items of a retainer invoice.
item_order
Optional
The order of the line item_order
rate
Optional
Rate of the line item.
payment_options
Optional
Payment options for the retainer invoice, online payment gateways and bank accounts. Will be displayed in the pdf.
template_id
Optional
ID of the pdf template associated with the retainer invoice.
place_of_supply
India Edition only.
Optional
Place where the goods/services are supplied to. (If not given,
place of contact given for the contact will be taken) |
Query Params
|
ignore_auto_number_generation
Optional
Ignore auto invoice number generation for this invoice. This mandates the invoice number. Allowed values
true and false |
update a retainerinvoice
Update an existing invoice.
PUT /retainerinvoices/:retainerinvoice_id
Request Example
$ curl https://books.zoho.com/api/v3/retainerinvoices/:retainerinvoice_id?organization_id=10234695 -H "Authorization: Zoho-authtoken ba4604e8e433g9c892e360d53463oec5" -H "Content-Type: application/json;charset=UTF-8" -d '{ "customer_id": 982000000567001, "reference_number": " ", "date": "2013-11-17", "contact_persons": [ "982000000567003" ], "custom_fields": [ { "index": 1, "show_on_pdf": false, "value": "The value of the custom field", "label": "Delivery Date" } ], "notes": "Looking forward for your business.", "terms": "Terms & Conditions apply", "line_items": [ { "description": "500GB, USB 2.0 interface 1400 rpm, protective hard case.", "item_order": 1, "rate": 120 } ], "payment_options": { "payment_gateways": [ { "gateway_name": "paypal" } ] }, "template_id": 982000000000143, "place_of_supply": "TN" }
Response Example
HTTP/1.1 200 OK Content-Type:application/json;charset=UTF-8 { "code": 0, "message": "Retainer Invoice information has been updated.", "retainerinvoice": { "retainerinvoices": { "retainerinvoice_id": 982000000567114, "retainerinvoice_number": "RET-00003", "date": "2013-11-17", "status": "draft", "is_pre_gst": false, "place_of_supply": "TN", "project_id": 982000000567154, "last_payment_date": " ", "reference_number": " ", "customer_id": 982000000567001, "customer_name": "Bowman & Co", "contact_persons": [ "982000000567003" ], "currency_id": 982000000000190, "currency_code": "USD", "currency_symbol": "USD", "exchange_rate": 1, "is_viewed_by_client": true, "client_viewed_time": true, "is_inclusive_tax": false, "line_items": [ { "line_item_id": 982000000567021, "description": "500GB, USB 2.0 interface 1400 rpm, protective hard case.", "item_order": 1, "rate": 120, "bcy_rate": 120, "tax_id": 982000000557028, "tax_name": "VAT", "tax_type": "tax", "tax_percentage": 12.5, "item_total": 120 } ], "sub_total": 153, "total": 40.6, "taxes": [ { "tax_name": "VAT", "tax_amount": 19.13 } ], "payment_made": 26.91, "payment_drawn": 26.91, "balance": 40.6, "allow_partial_payments": true, "price_precision": 2, "payment_options": { "payment_gateways": [ { "gateway_name": "paypal" } ] }, "is_emailed": false, "documents": [ {...} ], "billing_address": { "address": "Suite 125, McMillan Avenue", "street2": "McMillan Avenue", "city": "San Francisco", "state": "CA", "zip": 94134, "country": "U.S.A", "fax": "+86-10-82637827" }, "shipping_address": { "address": "Suite 125, McMillan Avenue", "city": "San Francisco", "state": "CA", "zip": 94134, "country": "U.S.A", "fax": "+86-10-82637827" }, "notes": "Looking forward for your business.", "terms": "Terms & Conditions apply", "custom_fields": [ { "index": 1, "show_on_pdf": false, "value": "The value of the custom field", "label": "Delivery Date" } ], "template_id": 982000000000143, "template_name": "Service - Classic", "page_width": "8.27in", "page_height": "11.69in", "orientation": "portrait", "template_type": "classic", "created_time": "2013-11-18T02:31:51-0800", "last_modified_time": "2013-11-18T02:31:51-0800", "created_by_id": 14909000000072000, "attachment_name": "new file", "can_send_in_mail": true, "invoice_url": "https://invoice.zoho.com/SecurePayment?CInvoiceID=23d84d0cf64f9a72ea0c66fded25a08c8bafd0ab508aff05323a9f80e2cd03fdc5dd568d3d6407bbda969d3e870d740b6fce549a9438c4ea" } } }
ARGUMENTS
|
customer_id
Required
ID of the customer the retainer invoice has to be created.
reference_number
Optional
The reference number of the retainer invoice. Max-length [100]
date
Optional
The date of creation of the retainer invoice.
contact_persons
Optional
custom_fields
Optional
Custom fields for a reatiner invoice.
index
Optional
The index of the custom field
show_on_pdf
Optional
Boolean value to check if the custom field is to be dispplayed on the pdf.
value
Optional
label
Optional
The label of the custom field.
notes
Optional
The notes added below expressing gratitude or for conveying some information.
terms
Optional
The terms added below expressing gratitude or for conveying some information.
line_items
Required
Line items of a retainer invoice.
item_order
Optional
The order of the line item_order
rate
Optional
Rate of the line item.
payment_options
Optional
Payment options for the retainer invoice, online payment gateways and bank accounts. Will be displayed in the pdf.
template_id
Optional
ID of the pdf template associated with the retainer invoice.
place_of_supply
India Edition only.
Optional
Place where the goods/services are supplied to. (If not given,
place of contact given for the contact will be taken) |
List a retainer invoices
List all retainer invoices with pagination.
GET /retainerinvoices
Request Example
$ curl https://books.zoho.com/api/v3/retainerinvoices?organization_id=10234695 -H "Authorization: Zoho-authtoken ba4604e8e433g9c892e360d53463oec5" -H "Content-Type: application/json;charset=UTF-8"
Response Example
HTTP/1.1 200 OK Content-Type:application/json;charset=UTF-8 { "code": 0, "message": "success", "retainerinvoices": [ { "retainerinvoice_id": 982000000567114, "customer_name": "Bowman & Co", "retainerinvoice_number": "RET-00003", "customer_id": 982000000567001, "status": "draft", "reference_number": " ", "project_or_estimate_name": "new project", "date": "2013-11-17", "currency_id": 982000000000190, "currency_code": "USD", "is_viewed_by_client": true, "client_viewed_time": true, "total": 40.6, "balance": 40.6, "created_time": "2013-11-18T02:31:51-0800", "last_modified_time": "2013-11-18T02:31:51-0800", "is_emailed": false, "last_payment_date": " ", "has_attachment": true } ], "page_context": { "page": 1, "per_page": 200, "has_more_page": false, "report_name": "Retainer Invoices", "applied_filter": "Status.All", "sort_column": "created_time", "sort_order": "D" } }
Query Params
|
print
Optional
Print the exported pdf.
sort_column
Optional
Sort retainer invoices.Allowed Values:
customer_name, retainer invoice_number, date, due_date, total, balance and created_time
filter_by
Optional
Filter 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
sort_order
Optional
The order for sorting
page
Optional
Number of pages
|
Get a retainer invoice
Get the details of a retainer invoice.
GET /retainerinvoices/:retainerinvoice_id
Request Example
$ curl https://books.zoho.com/api/v3/retainerinvoices/:retainerinvoice_id?organization_id=10234695 -H "Authorization: Zoho-authtoken ba4604e8e433g9c892e360d53463oec5" -H "Content-Type: application/json;charset=UTF-8"
Response Example
HTTP/1.1 200 OK Content-Type:application/json;charset=UTF-8 { "code": 0, "message": "success", "retainerinvoice": { "retainerinvoice": { "retainerinvoice_id": 982000000567114, "retainerinvoice_number": "RET-00003", "date": "2013-11-17", "status": "draft", "is_pre_gst": false, "place_of_supply": "TN", "project_id": 982000000567154, "last_payment_date": " ", "reference_number": " ", "customer_id": 982000000567001, "customer_name": "Bowman & Co", "contact_persons": [ "982000000567003" ], "currency_id": 982000000000190, "currency_code": "USD", "currency_symbol": "USD", "exchange_rate": 1, "is_viewed_by_client": true, "client_viewed_time": true, "is_inclusive_tax": false, "line_items": [ { "line_item_id": 982000000567021, "description": "500GB, USB 2.0 interface 1400 rpm, protective hard case.", "item_order": 1, "rate": 120, "bcy_rate": 120, "tax_id": 982000000557028, "tax_name": "VAT", "tax_type": "tax", "tax_percentage": 12.5, "item_total": 120 } ], "sub_total": 153, "total": 40.6, "taxes": [ { "tax_name": "VAT", "tax_amount": 19.13 } ], "payment_made": 26.91, "payment_drawn": 26.91, "balance": 40.6, "allow_partial_payments": true, "price_precision": 2, "payment_options": { "payment_gateways": [ { "gateway_name": "paypal" } ] }, "is_emailed": false, "documents": [ {...} ], "billing_address": { "address": "Suite 125, McMillan Avenue", "street2": "McMillan Avenue", "city": "San Francisco", "state": "CA", "zip": 94134, "country": "U.S.A", "fax": "+86-10-82637827" }, "shipping_address": { "address": "Suite 125, McMillan Avenue", "city": "San Francisco", "state": "CA", "zip": 94134, "country": "U.S.A", "fax": "+86-10-82637827" }, "notes": "Looking forward for your business.", "terms": "Terms & Conditions apply", "custom_fields": [ { "index": 1, "show_on_pdf": false, "value": "The value of the custom field", "label": "Delivery Date" } ], "template_id": 982000000000143, "template_name": "Service - Classic", "page_width": "8.27in", "page_height": "11.69in", "orientation": "portrait", "template_type": "classic", "created_time": "2013-11-18T02:31:51-0800", "last_modified_time": "2013-11-18T02:31:51-0800", "created_by_id": 14909000000072000, "attachment_name": "new file", "can_send_in_mail": true, "invoice_url": "https://invoice.zoho.com/SecurePayment?CInvoiceID=23d84d0cf64f9a72ea0c66fded25a08c8bafd0ab508aff05323a9f80e2cd03fdc5dd568d3d6407bbda969d3e870d740b6fce549a9438c4ea" } } }
Delete a retainer invoice
Delete an existing retainer invoice. Invoices which have payment or credits note applied cannot be deleted.
DELETE /retainerinvoices/:retainerinvoice_id
Request Example
$ curl https://books.zoho.com/api/v3/retainerinvoices/:retainerinvoice_id?organization_id=10234695 -H "Authorization: Zoho-authtoken ba4604e8e433g9c892e360d53463oec5" -H "Content-Type: application/json;charset=UTF-8"
Response Example
HTTP/1.1 200 OK Content-Type:application/json;charset=UTF-8 { "code": 0, "message": "The retainer invoice has been deleted." }
Mark a retainer invoice as sent
Mark a draft retainer invoice as sent.
POST /retainerinvoices/:retainerinvoice_id/status/sent
Request Example
$ curl https://books.zoho.com/api/v3/retainerinvoices/:retainerinvoice_id/status/sent?organization_id=10234695 -H "Authorization: Zoho-authtoken ba4604e8e433g9c892e360d53463oec5" -H "Content-Type: application/json;charset=UTF-8"
Response Example
HTTP/1.1 200 OK Content-Type:application/json;charset=UTF-8 { "code": 0, "message": "Retainer Invoice status has been changed to Sent." }
Update retainer invoice template
Update the pdf template associated with the retainer invoice.
PUT /retainerinvoices/:retainerinvoice_id/templates/:template_id
Request Example
$ curl https://books.zoho.com/api/v3/retainerinvoices/:retainerinvoice_id/templates/:template_id?organization_id=10234695 -H "Authorization: Zoho-authtoken ba4604e8e433g9c892e360d53463oec5" -H "Content-Type: application/json;charset=UTF-8"
Response Example
HTTP/1.1 200 OK Content-Type:application/json;charset=UTF-8 { "code": 0, "message": "Retainer Invoice information has been updated." }
Void a retainer invoice
Mark an invoice status as void. Upon voiding, the payments and credits associated with the retainer invoices will be unassociated and will be under customer credits.
POST /retainerinvoices/:retainerinvoice_id/status/void
Request Example
$ curl https://books.zoho.com/api/v3/retainerinvoices/:retainerinvoice_id/status/void?organization_id=10234695 -H "Authorization: Zoho-authtoken ba4604e8e433g9c892e360d53463oec5" -H "Content-Type: application/json;charset=UTF-8"
Response Example
HTTP/1.1 200 OK Content-Type:application/json;charset=UTF-8 { "code": 0, "message": "Retainer Invoice status has been changed to 'Void'." }
Mark as draft
Mark a voided retainer invoice as draft.
POST /retainerinvoices/:reatinerinvoice_id/status/draft
Request Example
$ curl https://books.zoho.com/api/v3/retainerinvoices/:reatinerinvoice_id/status/draft?organization_id=10234695 -H "Authorization: Zoho-authtoken ba4604e8e433g9c892e360d53463oec5" -H "Content-Type: application/json;charset=UTF-8"
Response Example
HTTP/1.1 200 OK Content-Type:application/json;charset=UTF-8 { "code": 0, "message": "Status of retainer invoice changed from void to draft." }
Email a retainer invoice
Email a retainer invoice to the customer. Input json string is not mandatory. If input json string is empty, mail will be send with default mail content.
POST /retainerinvoices/:retainerinvoice_id/email
Request Example
$ curl https://books.zoho.com/api/v3/retainerinvoices/:retainerinvoice_id/email?organization_id=10234695 -H "Authorization: Zoho-authtoken ba4604e8e433g9c892e360d53463oec5" -H "Content-Type: application/json;charset=UTF-8" -d '{ "send_from_org_email_id": false, "to_mail_ids": [ "willsmith@bowmanfurniture.com" ], "cc_mail_ids": [ "peterparker@bowmanfurniture.com" ], "subject": "Retainer Invoice from Zillium Inc (Retainer Invoice#: RET-00001)", "body": "Dear Customer, <br><br><br><br>Thanks for your business. <br><br><br><br>The retainer invoice RET-00001 is attached with this email. You can choose the easy way out and <a href= https://invoice.zoho.com/SecurePayment?CInvoiceID=b9800228e011ae86abe71227bdacb3c68e1af685f647dcaed747812e0b9314635e55ac6223925675b371fcbd2d5ae3dc >pay online for this invoice.</a> <br><br>Here's an overview of the invoice for your reference. <br><br><br><br>Invoice Overview: <br><br>Invoice : INV-00001 <br><br>Date : 05 Aug 2013 <br><br>Amount : $541.82 <br><br><br><br>It was great working with you. Looking forward to working with you again.<br><br><br>\\nRegards<br>\\nZillium Inc<br>\\n\"," }
Response Example
HTTP/1.1 200 OK Content-Type:application/json;charset=UTF-8 { "code": 0, "message": "Your retainer invoice has been sent." }
ARGUMENTS
|
send_from_org_email_id
Optional
Boolean to trigger the email from the organization's email address
to_mail_ids
Required
Array of email address of the recipients.
cc_mail_ids
Optional
Array of email address of the recipients to be cced.
subject
Optional
The subject of the mail
body
Optional
The body of the mail
|
Query Params
|
send_customer_statement
Optional
Send customer statement pdf a with email.
send_attachment
Optional
Send the retainer invoice attachment a with the email.
attachments
Optional
Files to be attached to the email
|
Get retainer invoice email content
Get the email content of a retainer invoice.
GET /retainerinvoices/:retainerinvoice_id/email
Request Example
$ curl https://books.zoho.com/api/v3/retainerinvoices/:retainerinvoice_id/email?organization_id=10234695 -H "Authorization: Zoho-authtoken ba4604e8e433g9c892e360d53463oec5" -H "Content-Type: application/json;charset=UTF-8" -d '{}
Response Example
HTTP/1.1 200 OK Content-Type:application/json;charset=UTF-8 { "code": 0, "message": "success", "gateways_configured": true, "deprecated_placeholders_used": [ {...} ], "body": "Dear Customer, <br><br><br><br>Thanks for your business. <br><br><br><br>The retainer invoice RET-00001 is attached with this email. You can choose the easy way out and <a href= https://invoice.zoho.com/SecurePayment?CInvoiceID=b9800228e011ae86abe71227bdacb3c68e1af685f647dcaed747812e0b9314635e55ac6223925675b371fcbd2d5ae3dc >pay online for this invoice.</a> <br><br>Here's an overview of the invoice for your reference. <br><br><br><br>Invoice Overview: <br><br>Invoice : INV-00001 <br><br>Date : 05 Aug 2013 <br><br>Amount : $541.82 <br><br><br><br>It was great working with you. Looking forward to working with you again.<br><br><br>\\nRegards<br>\\nZillium Inc<br>\\n\",", "error_list": [ {...} ], "subject": "Retainer Invoice from Zillium Inc (Retainer Invoice#: RET-00001)", "to_contacts": [ { "first_name": "Will", "selected": false, "phone": "+1-925-921-9201", "email": "willsmith@bowmanfurniture.com", "last_name": "Smith", "salutation": "Mr", "contact_person_id": 982000000567003, "mobile": "+1-4054439562" } ], "attachment_name": "new file", "file_name": "RET-00001.pdf", "from_emails": [ { "user_name": [ {...} ], "selected": false, "email": "willsmith@bowmanfurniture.com" } ], "customer_id": 982000000567001 }
ARGUMENTS
|
email_template_id
Optional
Get the email content based on a
specific email template. If this param is not inputted, then the content
will be based on the email template associated with the customer. If no
template is associated with the customer, then default template will be
used.
|
Update billing address
Updates the billing address for this retainer invoice alone.
PUT /retainerinvoices/:retainerinvoice_id/address/billing
Request Example
$ curl https://books.zoho.com/api/v3/retainerinvoices/:retainerinvoice_id/address/billing?organization_id=10234695 -H "Authorization: Zoho-authtoken ba4604e8e433g9c892e360d53463oec5" -H "Content-Type: application/json;charset=UTF-8" -d '{ "address": "B-1104, 11F, \nHorizon International Tower, \nNo. 6, ZhiChun Road, HaiDian District", "city": "Beijing", "state": "Beijing", "zip": 1000881, "fax": "+86-10-82637827" }
Response Example
HTTP/1.1 200 OK Content-Type:application/json;charset=UTF-8 { "code": 0, "message": "Billing address updated" }
ARGUMENTS
|
address
Optional
address of the customer
city
Optional
city of the customer
state
Optional
state of the customer
zip
Optional
zip of the customer
country
Optional
country of the customer
fax
Optional
fax of the customer
|
List retainer invoice templates
Get all retainer invoice pdf templates.
Get /retainerinvoices/templates
Request Example
$ curl https://books.zoho.com/api/v3/retainerinvoices/templates?organization_id=10234695 -H "Authorization: Zoho-authtoken ba4604e8e433g9c892e360d53463oec5" -H "Content-Type: application/json;charset=UTF-8"
Response Example
HTTP/1.1 200 OK Content-Type:application/json;charset=UTF-8 { "code": 0, "message": "success", "templates": [ { "template_name": "Service - Classic", "template_id": 982000000000143, "template_type": "classic" } ] }
List retainer payments
Get the list of payments made for a retainer invoices.
GET /customerpayments/:retainerinvoice_id
Request Example
$ curl https://books.zoho.com/api/v3/customerpayments/:retainerinvoice_id?organization_id=10234695 -H "Authorization: Zoho-authtoken ba4604e8e433g9c892e360d53463oec5" -H "Content-Type: application/json;charset=UTF-8"
Response Example
HTTP/1.1 200 OK Content-Type:application/json;charset=UTF-8 { "code": 0, "message": "success", "payments": [ { "payment_id": "982000000567190", "documents": [ {...} ], "customer_id": 982000000567001, "customer_name": "Bowman & Co", "retainerinvoice_id": 982000000567114, "payment_mode": "cash", "date": "2013-11-17", "currency_id": 982000000000190, "currency_code": "USD", "exchange_rate": 1, "amount": 100, "unused_amount": 100, "bank_charges": 20, "is_client_review_settings_enabled": true, "tax_amount_withheld": 10, "discount_amount": 10, "description": "500GB, USB 2.0 interface 1400 rpm, protective hard case.", "reference_number": " ", "online_transaction_id": "7843653940324085", "invoices": [ {...} ], "retainerinvoice": { "retainerinvoice_id": 982000000567114, "retainerinvoice_number": "RET-00003", "retainerinvoice_total": 3478, "retainerinvoice_balance": 3478, "retainerinvoice_date": "2016-12-20" }, "payment_refunds": [ {...} ], "last_four_digits": "", "html_string": "", "template_id": 982000000000143, "template_name": "Service - Classic", "page_width": "8.27in", "page_height": "11.69in", "orientation": "portrait", "template_type": "classic", "attachment_name": "new file", "can_send_in_mail": true, "is_payment_drawn_details_required": true, "custom_fields": [ { "index": 1, "show_on_pdf": false, "value": "The value of the custom field", "label": "Delivery Date" } ] } ] }
Delete a retainer payment
Delete a payment made to a retainer invoice.
DELETE /customerpayments/:retainer_payment_id
Request Example
$ curl https://books.zoho.com/api/v3/customerpayments/:retainer_payment_id?organization_id=10234695 -H "Authorization: Zoho-authtoken ba4604e8e433g9c892e360d53463oec5" -H "Content-Type: application/json;charset=UTF-8"
Response Example
HTTP/1.1 200 OK Content-Type:application/json;charset=UTF-8 { "code": 0, "message": "The payment has been deleted." }
Get a retainer invoice attachment
Returns the file attached to the retainer invoice.
GET /retainerinvoices/:retainerinvoice_id/attachment
Request Example
$ curl https://books.zoho.com/api/v3/retainerinvoices/:retainerinvoice_id/attachment?organization_id=10234695 -H "Authorization: Zoho-authtoken ba4604e8e433g9c892e360d53463oec5" -H "Content-Type: application/json;charset=UTF-8" -d '{}
Response Example
HTTP/1.1 200 OK Content-Type:application/json;charset=UTF-8 { "code": 0, "message": "success" }
ARGUMENTS
|
preview
Optional
Get the thumbnail of the attachment.
|
Add attachment to a retainer invoice
Attach a file to an invoice.
POST /retainerinvoices/:retainerinvoice_id/attachment
Request Example
$ curl https://books.zoho.com/api/v3/retainerinvoices/:retainerinvoice_id/attachment?organization_id=10234695 -H "Authorization: Zoho-authtoken ba4604e8e433g9c892e360d53463oec5" -H "Content-Type: application/json;charset=UTF-8" -d '{ "can_send_in_mail": true }
Response Example
HTTP/1.1 200 OK Content-Type:application/json;charset=UTF-8 { "code": 0, "message": "Your file has been attached." }
ARGUMENTS
|
can_send_in_mail
Optional
attachment
Optional
The file to be attached. It has to be sent in multipart/formdata
|
Delete an attachment
Delete the file attached to the retainer invoice.
DELETE /retainerinvoices/:retainerinvoice_id/documents/:document_id
Request Example
$ curl https://books.zoho.com/api/v3/retainerinvoices/:retainerinvoice_id/documents/:document_id?organization_id=10234695 -H "Authorization: Zoho-authtoken ba4604e8e433g9c892e360d53463oec5" -H "Content-Type: application/json;charset=UTF-8"
Response Example
HTTP/1.1 200 OK Content-Type:application/json;charset=UTF-8 { "code": 0, "message": "Your file is no longer attached to the invoice." }
List retainer invoice comments & history
Get the complete history and comments of a retainer invoice.
GET /retainerinvoices/:retainernvoice_id/comments
Request Example
$ curl https://books.zoho.com/api/v3 /retainerinvoices/:retainernvoice_id/comments?organization_id=10234695 -H "Authorization: Zoho-authtoken ba4604e8e433g9c892e360d53463oec5" -H "Content-Type: application/json;charset=UTF-8"
Response Example
HTTP/1.1 200 OK Content-Type:application/json;charset=UTF-8 { "code": 0, "message": "success", "comments": [ { "comments": [ { "comment_id": 982000000567019, "retainerinvoice_id": 982000000567114, "description": "500GB, USB 2.0 interface 1400 rpm, protective hard case.", "commented_by_id": 982000000554041, "commented_by": "John David", "comment_type": "system", "operation_type": "Added", "date": "2013-11-17", "date_description": "yesterday", "time": "2:38 AM", "transaction_id": "982000000567204", "transaction_type": "retainer_payment" } ] }, {...}, {...} ] }
Add comment
Add a comment for a retainer invoice.
POST /retainerinvoices/:retainerinvoice_id/comments
Request Example
$ curl https://books.zoho.com/api/v3/retainerinvoices/:retainerinvoice_id/comments?organization_id=10234695 -H "Authorization: Zoho-authtoken ba4604e8e433g9c892e360d53463oec5" -H "Content-Type: application/json;charset=UTF-8" -d '{ "description": "comment added", "payment_expected_date": " ", "show_comment_to_clients": true }
Response Example
HTTP/1.1 200 OK Content-Type:application/json;charset=UTF-8 { "code": 0, "message": "Comments added." }
ARGUMENTS
|
description
Optional
The description of the line items. Max-length [2000]
payment_expected_date
Optional
show_comment_to_clients
Optional
Boolean to check if the comment to be shown to the clients
|
Delete a comment
Delete a retainer invoice comment.
DELETE /retainerinvoices/:retainerinvoice_id/comments/:comment_id
Request Example
$ curl https://books.zoho.com/api/v3/retainerinvoices/:retainerinvoice_id/comments/:comment_id?organization_id=10234695 -H "Authorization: Zoho-authtoken ba4604e8e433g9c892e360d53463oec5" -H "Content-Type: application/json;charset=UTF-8"
Response Example
HTTP/1.1 200 OK Content-Type:application/json;charset=UTF-8 { "code": 0, "message": "The comment has been deleted." }
Update comment
Update an existing comment of a retainer invoice.
PUT /retainerinvoices/:retainerinvoice_id/comments/:comment_id
Request Example
$ curl https://books.zoho.com/api/v3/retainerinvoices/:retainerinvoice_id/comments/:comment_id?organization_id=10234695 -H "Authorization: Zoho-authtoken ba4604e8e433g9c892e360d53463oec5" -H "Content-Type: application/json;charset=UTF-8" -d '{ "show_comment_to_clients": true }
Response Example
HTTP/1.1 200 OK Content-Type:application/json;charset=UTF-8 { "code": 0, "message": "The comment has been deleted.", "comment": { "comment_id": 982000000567019, "retainerinvoice_id": 982000000567114, "description": "500GB, USB 2.0 interface 1400 rpm, protective hard case.", "commented_by_id": 982000000554041, "commented_by": "John David", "date": "2013-11-17", "date_description": "yesterday", "time": "2:38 AM", "comment_type": "system" } }
ARGUMENTS
|
description
Optional
The comment on a retainer invoice
show_comment_to_clients
Optional
Boolean to check if the comment to be shown to the clients
|
Purchase-Order
A purchase order is an official document that a buyer issues to a seller, indicating relevant information about what they want to buy, the quantity, the price agreed for that particular product or service.
Example
{ "purchaseorder": { "purchaseorder_id": "460000000062001", "documents": [ {} ], "gst_no": "22AAAAA0000A1Z5", "gst_treatment": "business_gst", "is_pre_gst": false, "source_of_supply": "AP", "destination_of_supply": "TN", "pricebook_id": 460000000026089, "pricebook_name": "", "is_reverse_charge_applied": false, "purchaseorder_number": "PO-00001", "date": "2014-02-10", "reference_number": "ER/0034", "status": "draft", "vendor_id": "460000000026049", "contact_persons": [ "460000000026051" ], "currency_id": "460000000000099", "currency_code": "INR", "exchange_rate": 1, "delivery_date": "2014-02-10", "is_emailed": false, "is_inclusive_tax": false, "line_items": [ { "item_id": "460000000027009", "line_item_id": "460000000074009", "warehouse_id": 460000000026051, "reverse_charge_tax_id": 460000000026068, "reverse_charge_tax_name": "inter", "reverse_charge_tax_percentage": 10, "reverse_charge_tax_amount": 100, "account_id": "460000000074003", "account_name": "Other Expenses", "name": "Hard Drive", "item_order": 0, "bcy_rate": 40, "unit": "Nos", "rate": 112, "quantity": 1, "item_total": 40, "item_total_inclusive_of_tax": 40, "tax_type": "tax", "tax_percentage": 0, "tags": [ {} ], "item_custom_fields": [ { "custom_field_id": "46000000012845", "index": 1, "value": "Normal", "label": "Priority" } ] } ], "sub_total": 40, "tax_total": 0, "total": 40, "taxes": [ {} ], "acquisition_vat_summary": [ {} ], "reverse_charge_vat_summary": [ {} ], "billing_address": { "street2": "McMillan Avenue" }, "notes": "Please deliver as soon as possible.", "terms": "Thanks for your business.", "delivery_address": { "is_verifiable": true, "email": "peterparker@bowmanfurniture.com", "phone": "+1-925-929-7211", "is_verified": false }, "price_precision": 2, "custom_fields": [ { "custom_field_id": "46000000012845", "index": 1, "value": "Normal", "label": "Priority" } ], "attachment_name": "7.png", "can_send_in_mail": false, "template_id": "460000000011003", "template_name": "Standard Template", "page_width": "8.27in", "page_height": "11.69in", "orientation": "portrait", "template_type": "standard", "created_time": "2014-02-10T15:26:26+0530", "created_by_id": "460000000053001", "last_modified_time": "2014-02-10T15:26:26+0530", "can_mark_as_bill": false, "can_mark_as_unbill": false } }
Attribute
|
purchaseorder
object
purchaseorder_id
string
documents
list
document_id
long
ID of the Document
file_name
string
Name of the file
vat_treatment
UK Edition only
string
(Optional) VAT treatment for the
purchase order. VAT treatment denotes the location of the vendor, if the
vendor resides in UK then the VAT treatment is
uk. If the vendor is in an EU country & if he is VAT registered then his VAT treatment is eu_vat_registered, if he resides in EU & if he is not VAT registered then his VAT treatment is eu_vat_not_registered and if he resides outside the EU then his VAT treatment is non_eu.
gst_no
India Edition only.
string
15 digit GST identification number of the vendor.
gst_treatment
India Edition only.
string
Choose whether the contact is GST registered/unregistered/consumer/overseas. Allowed values are
business_gst , business_none , overseas , consumer .
is_pre_gst
India Edition only.
boolean
Applicable for transactions that fall before july 1, 2017
source_of_supply
India Edition only.
string
Place from where the goods/services are supplied. (If not given,
place of contact given for the contact will be taken)
destination_of_supply
India Edition only.
string
Place where the goods/services are supplied to. (If not given, organisation's home state will be taken)
pricebook_id
string
Enter pricebook ID
pricebook_name
string
Enter pricebook name
is_reverse_charge_applied
India Edition only.
boolean
Applicable for transactions where you pay reverse charge
purchaseorder_number
string
Mandatory if auto number generation is disabled.
date
string
The date the purchase order is created.
expected_delivery_date
string
Date the goods is expected to arrive.
reference_number
string
Reference number of purchase order.
status
string
Status of the Purchase Order
vendor_id
string
ID of the vendor the purchase order has to be created.
vendor_name
string
Name of the Vendor in Purchase Order
crm_owner_id
string
ID of the CRM Owner
contact_persons
array
Array of contact person(s) for whom purchase order has to be sent.
currency_id
sring
ID of the Currency
currency_code
string
Code of the Currency
currency_symbol
string
Symbol of the Currency
exchange_rate
double
Exchange rate of the currency.
delivery_date
string
Date of delivery of the purchase order
is_emailed
boolean
Check if the purchase order is emailed
is_inclusive_tax
Not applicable for US edition
boolean
Used to specify whether the line item rates are inclusive or exclusive of tax.
line_items
list
Line items of purchase order.
item_id
string
ID of the item.
line_item_id
string
ID of the line item. Mandatory if the existing line item has to be updated. If empty, a new line item will be created.
sku
string
SKU of the Item
warehouse_id
string
Enter warehouse ID
warehouse_name
string
Enter warehouse name
product_type
UK Edition only
string
This denotes whether the Purchase
Order line item is to be treated as a goods or service purchase. This
only need to be specified in case purchase order is not enabled. Allowed
Values:
goods, digital_service and service.
reverse_charge_tax_id
string
Enter reverse charge tax ID
reverse_charge_tax_name
India Edition only.
string
Enter reverse charge tax name
reverse_charge_tax_percentage
Indian Edition only.
double
Enter reverse charge tax percentage
reverse_charge_tax_amount
India Edition only.
double
Tax amount for the reverse charge.
account_id
string
ID of the account, the line item is associated with.
account_name
string
Name of the Account
name
string
Name of the line item.
item_order
integer
Order of the items in Purhcase Order
bcy_rate
integer
Rate in Base Currency
unit
string
Unit of the line item e.g. kgs, Nos.
rate
double
Rate of the line item.
quantity
string
Quantity of the line item.
item_total
integer
Total of the Item
item_total_inclusive_of_tax
integer
Total of the Item inclusive tax
tax_exemption_id
India, CA and AU Editions Only
string
ID of the Tax Exemption
tax_exemption_code
India, CA and AU Editions Only
string
Code of the Tax Exemption
tax_id
string
tax_name
string
Name of the Tax
tax_type
string
Type of the Tax
tax_percentage
integer
Percentage of the Tax
product_type
UK Edition only
string
This denotes whether the Purchase
Order line item is to be treated as a goods or service purchase. This
only need to be specified in case purchase order is not enabled. Allowed
Values:
goods, digital_service and service.
hsn_or_sac
India Edition Only
string
HSN or SAC Code for the Item
acquisition_vat_id
UK and EU Editions Only
string
ID of the VAT Acquistion
acquisition_vat_name
UK and EU Editions Only
string
Name of the VAT Acquistion
acquisition_vat_percentage
UK and EU Editions Only
string
Percentage of the VAT Acquistion
acquisition_vat_amount
UK and EU Editions Only
string
Amount of the VAT Acquistion
reverse_charge_vat_id
UK and EU Editions Only
string
ID of the Reverse Charge
reverse_charge_vat_name
UK and EU Editions Only
string
Name of the Reverse Charge
reverse_charge_vat_percentage
UK and EU Editions Only
string
Percentage of the Reverse Charge
reverse_charge_vat_amount
UK and EU Editions Only
string
Percentage of the Reverse Charge
tags
list
item_custom_fields
list
custom_field_id
long
index
integer
Index of the Custom Field
value
string
Value of the Custom Field
label
string
Label of the Custom Field
sub_total
double
Sub Total of the Purchase Order
tax_total
double
Total of the Tax
total
double
Total of the Purchase Order
taxes
list
acquisition_vat_summary
UK and EU Editions Only
list
Summary of the VAT Acquistion
tax_name
string
Name of the Tax
tax_amount
double
Amount of Tax
acquisition_vat_total
UK and EU Editions Only
double
Total of the VAT Acquistion
reverse_charge_vat_summary
UK and EU Editions Only
list
Summary of the Reverse Charge
tax_name
string
Name of the Tax
tax_amount
double
Amount of Tax
reverse_charge_vat_total
UK and EU Editions Only
double
Total of the Reverse Charge
billing_address
object
address
string
Address associated with the Purchase Order
street2
string
city
string
City involved in the Address
state
string
State Involved in the Address
zip
string
ZIP Code of the Address
country
string
Country involved in the Address
fax
string
Fax Number
attention
string
Delivery contact person.
notes
string
Delivery note for vendor.
terms
string
Terms for the purchase order
ship_via
string
Shipment Preference
ship_via_id
string
ID of the Shipment Preference
attention
string
Delivery contact person.
delivery_org_address_id
string
ID of the Delivery Address
delivery_customer_id
string
ID of the Customer associated with the Purchase Order
delivery_address
object
zip
string
ZIP Code of the Address
is_verifiable
boolean
state
string
State Involved in the Address
address1
string
address2
string
is_valid
string
city
string
City involved in the Address
country
string
Country involved in the Address
address
string
Address associated with the Purchase Order
email
string
Email ID of the Vendor
is_primary
string
organization_address_id
string
ID of organization address.
phone
string
Phone Number of the Associated Contact
is_verified
boolean
price_precision
integer
Price Precision for the Values
custom_fields
list
custom_field_id
long
index
integer
Index of the Custom Field
value
string
Value of the Custom Field
label
string
Label of the Custom Field
attachment_name
string
Name of the Attachment
can_send_in_mail
boolean
Boolean to send the attachment with the purchase order when emailed.
template_id
string
ID of the pdf template associated with the purchase order.
template_name
string
Name of the template
page_width
string
Width of the Page
page_height
string
Height of the Page
orientation
string
Orientation of the Page
template_type
string
Type of the Template
created_time
string
Created Time of the Purchase Order
created_by_id
string
ID of the User who created the Purchase Order
last_modified_time
string
Last Modified Time of the Purchase Order
can_mark_as_bill
boolean
can_mark_as_unbill
boolean
|
Create a purchase order
Create a purchase order for your vendor.
POST /purchaseorders
Request Example
$ curl https://books.zoho.com/api/v3/purchaseorders?organization_id=10234695 -H "Authorization: Zoho-authtoken ba4604e8e433g9c892e360d53463oec5" -H "Content-Type: application/json;charset=UTF-8" -d '{ "vendor_id": "460000000026049", "contact_persons": [ "460000000026051" ], "purchaseorder_number": "PO-00001", "gst_treatment": "business_gst", "gst_no": "22AAAAA0000A1Z5", "source_of_supply": "AP", "destination_of_supply": "TN", "pricebook_id": 460000000026089, "reference_number": "ER/0034", "billing_address_id": "460000000017491", "template_id": "460000000011003", "date": "2014-02-10", "delivery_date": "2014-02-10", "exchange_rate": 1, "is_inclusive_tax": false, "notes": "Please deliver as soon as possible.", "terms": "Thanks for your business.", "salesorder_id": "460000124728314", "line_items": [ { "item_id": "460000000027009", "account_id": "460000000074003", "name": "Hard Drive", "unit": "Nos", "warehouse_id": 460000000026051, "reverse_charge_tax_id": 460000000026068, "rate": 112, "quantity": 1, "item_order": 0, "item_custom_fields": [ { "index": 1, "value": "Normal" } ], "tags": [ {} ] } ], "custom_fields": [ { "index": 1, "value": "Normal" } ], "documents": [ {} ] }
Response Example
HTTP/1.1 201 Created Content-Type:application/json;charset=UTF-8 { "code": 0, "message": "Purchase Order has been added.", "purchaseorder": { "purchaseorder_id": "460000000062001", "documents": [ {...} ], "gst_no": "22AAAAA0000A1Z5", "gst_treatment": "business_gst", "is_pre_gst": false, "source_of_supply": "AP", "destination_of_supply": "TN", "pricebook_id": 460000000026089, "pricebook_name": "", "is_reverse_charge_applied": false, "purchaseorder_number": "PO-00001", "date": "2014-02-10", "reference_number": "ER/0034", "status": "draft", "vendor_id": "460000000026049", "contact_persons": [ "460000000026051" ], "currency_id": "460000000000099", "currency_code": "INR", "exchange_rate": 1, "delivery_date": "2014-02-10", "is_emailed": false, "is_inclusive_tax": false, "line_items": [ { "item_id": "460000000027009", "line_item_id": "460000000074009", "warehouse_id": 460000000026051, "reverse_charge_tax_id": 460000000026068, "reverse_charge_tax_name": "inter", "reverse_charge_tax_percentage": 10, "reverse_charge_tax_amount": 100, "account_id": "460000000074003", "account_name": "Other Expenses", "name": "Hard Drive", "item_order": 0, "bcy_rate": 40, "unit": "Nos", "rate": 112, "quantity": 1, "item_total": 40, "item_total_inclusive_of_tax": 40, "tax_type": "tax", "tax_percentage": 0, "tags": [ {...} ], "item_custom_fields": [ { "custom_field_id": "46000000012845", "index": 1, "value": "Normal", "label": "Priority" } ] } ], "sub_total": 40, "tax_total": 0, "total": 40, "taxes": [ {...} ], "acquisition_vat_summary": [ {...} ], "reverse_charge_vat_summary": [ {...} ], "billing_address": { "street2": "McMillan Avenue" }, "notes": "Please deliver as soon as possible.", "terms": "Thanks for your business.", "delivery_address": { "is_verifiable": true, "email": "peterparker@bowmanfurniture.com", "phone": "+1-925-929-7211", "is_verified": false }, "price_precision": 2, "custom_fields": [ { "custom_field_id": "46000000012845", "index": 1, "value": "Normal", "label": "Priority" } ], "attachment_name": "7.png", "can_send_in_mail": false, "template_id": "460000000011003", "template_name": "Standard Template", "page_width": "8.27in", "page_height": "11.69in", "orientation": "portrait", "template_type": "standard", "created_time": "2014-02-10T15:26:26+0530", "created_by_id": "460000000053001", "last_modified_time": "2014-02-10T15:26:26+0530", "can_mark_as_bill": false, "can_mark_as_unbill": false } }
ARGUMENTS
|
vendor_id
Required
ID of the vendor the purchase order has to be created.
contact_persons
Optional
Array of contact person(s) for whom purchase order has to be sent.
purchaseorder_number
Optional
Mandatory if auto number generation is disabled.
gst_treatment
India Edition only.
Optional
Choose whether the contact is GST registered/unregistered/consumer/overseas. Allowed values are
business_gst , business_none , overseas , consumer .
gst_no
India Edition only.
Optional
15 digit GST identification number of the vendor.
source_of_supply
India Edition only.
Optional
Place from where the goods/services are supplied. (If not given,
place of contact given for the contact will be taken)
destination_of_supply
India Edition only.
Optional
Place where the goods/services are supplied to. (If not given, organisation's home state will be taken)
pricebook_id
Optional
Enter pricebook ID
reference_number
Optional
Reference number of purchase order.
billing_address_id
Optional
ID of the Billing Address
crm_owner_id
Optional
ID of the CRM Owner
crm_custom_reference_id
Optional
ID of CRM Custom Reference
template_id
Optional
ID of the pdf template associated with the purchase order.
date
Optional
The date the purchase order is created.
delivery_date
Optional
Date of delivery of the purchase order
due_date
Optional
Delivery date of purchase order.
exchange_rate
Optional
Exchange rate of the currency.
is_inclusive_tax
Not applicable for US edition
Optional
Used to specify whether the line item rates are inclusive or exclusive of tax.
notes
Optional
Delivery note for vendor.
notes_default
Optional
Default notes for purchase order
terms
Optional
Terms for the purchase order
terms_default
Optional
Default terms for Purchase Orders
ship_via
Optional
Shipment Preference
delivery_org_address_id
Optional
ID of the Delivery Address
delivery_customer_id
Optional
ID of the Customer associated with the Purchase Order
attention
Optional
Delivery contact person.
vat_treatment
UK Edition only
Optional
(Optional) VAT treatment for the
purchase order. VAT treatment denotes the location of the vendor, if the
vendor resides in UK then the VAT treatment is
uk. If the vendor is in an EU country & if he is VAT registered then his VAT treatment is eu_vat_registered, if he resides in EU & if he is not VAT registered then his VAT treatment is eu_vat_not_registered and if he resides outside the EU then his VAT treatment is non_eu.
is_update_customer
Optional
Check if customer should be updated
salesorder_id
Optional
ID of the Sales Order
line_items
Required
Line items of purchase order.
item_id
Optional
ID of the item.
account_id
Optional
ID of the account, the line item is associated with.
name
Optional
Name of the line item.
unit
Optional
Unit of the line item e.g. kgs, Nos.
warehouse_id
Optional
Enter warehouse ID
hsn_or_sac
India Edition Only
Optional
HSN or SAC Code for the Item
reverse_charge_tax_id
Optional
Enter reverse charge tax ID
rate
Optional
Rate of the line item.
quantity
Optional
Quantity of the line item.
item_order
Optional
Order of the items in Purhcase Order
tax_id
Optional
hsn_or_sac
India Edition Only
Optional
HSN or SAC Code for the Item
tax_exemption_code
India, CA and AU Editions Only
Optional
Code of the Tax Exemption
tax_exemption_id
India, CA and AU Editions Only
Optional
ID of the Tax Exemption
acquisition_vat_id
UK and EU Editions Only
Optional
ID of the VAT Acquistion
reverse_charge_vat_id
UK and EU Editions Only
Optional
ID of the Reverse Charge
item_custom_fields
Optional
index
Optional
Index of the Custom Field
value
Optional
Value of the Custom Field
item_custom_fields
Optional
index
Optional
Index of the Custom Field
value
Optional
Value of the Custom Field
tags
Optional
custom_fields
Optional
index
Optional
Index of the Custom Field
value
Optional
Value of the Custom Field
documents
Optional
document_id
Optional
ID of the Document
file_name
Optional
Name of the file
|
Query Params
|
attachment
Optional
Allowed Extensions:
gif, png, jpeg, jpg, bmp, pdf, xls, xlsx, doc and docx.
ignore_auto_number_generation
Optional
Ignore auto purchase order number generation for this purchase order. This mandates the purchase order number.
|
Update a purchase order
Update an existing purchase order.
PUT /purchaseorders/{purchase_order_id}
Request Example
$ curl https://books.zoho.com/api/v3/purchaseorders/{purchase_order_id}?organization_id=10234695 -H "Authorization: Zoho-authtoken ba4604e8e433g9c892e360d53463oec5" -H "Content-Type: application/json;charset=UTF-8" -d '{ "vendor_id": "460000000026049", "contact_persons": [ "460000000026051" ], "purchaseorder_number": "PO-00001", "gst_treatment": "business_gst", "gst_no": "22AAAAA0000A1Z5", "source_of_supply": "AP", "destination_of_supply": "TN", "pricebook_id": 460000000026089, "reference_number": "ER/0034", "billing_address_id": "460000000017491", "template_id": "460000000011003", "date": "2014-02-10", "delivery_date": "2014-02-10", "exchange_rate": 1, "is_inclusive_tax": false, "notes": "Please deliver as soon as possible.", "terms": "Thanks for your business.", "salesorder_id": "460000124728314", "line_items": [ { "line_item_id": "460000000074009", "item_id": "460000000027009", "account_id": "460000000074003", "name": "Hard Drive", "unit": "Nos", "warehouse_id": 460000000026051, "reverse_charge_tax_id": 460000000026068, "rate": 112, "quantity": 1, "item_order": 0, "item_custom_fields": [ { "index": 1, "value": "Normal" } ], "tags": [ {} ] } ], "custom_fields": [ { "index": 1, "value": "Normal" } ], "documents": [ {} ] }
Response Example
HTTP/1.1 200 OK Content-Type:application/json;charset=UTF-8 { "code": 0, "message": "Purchase Order has been updated.", "purchaseorder": { "purchaseorder_id": "460000000062001", "documents": [ {...} ], "gst_no": "22AAAAA0000A1Z5", "gst_treatment": "business_gst", "is_pre_gst": false, "source_of_supply": "AP", "destination_of_supply": "TN", "pricebook_id": 460000000026089, "pricebook_name": "", "is_reverse_charge_applied": false, "purchaseorder_number": "PO-00001", "date": "2014-02-10", "reference_number": "ER/0034", "status": "draft", "vendor_id": "460000000026049", "contact_persons": [ "460000000026051" ], "currency_id": "460000000000099", "currency_code": "INR", "exchange_rate": 1, "delivery_date": "2014-02-10", "is_emailed": false, "is_inclusive_tax": false, "line_items": [ { "item_id": "460000000027009", "line_item_id": "460000000074009", "warehouse_id": 460000000026051, "reverse_charge_tax_id": 460000000026068, "reverse_charge_tax_name": "inter", "reverse_charge_tax_percentage": 10, "reverse_charge_tax_amount": 100, "account_id": "460000000074003", "account_name": "Other Expenses", "name": "Hard Drive", "item_order": 0, "bcy_rate": 40, "unit": "Nos", "rate": 112, "quantity": 1, "item_total": 40, "item_total_inclusive_of_tax": 40, "tax_type": "tax", "tax_percentage": 0, "tags": [ {...} ], "item_custom_fields": [ { "custom_field_id": "46000000012845", "index": 1, "value": "Normal", "label": "Priority" } ] } ], "sub_total": 40, "tax_total": 0, "total": 40, "taxes": [ {...} ], "acquisition_vat_summary": [ {...} ], "reverse_charge_vat_summary": [ {...} ], "billing_address": { "street2": "McMillan Avenue" }, "notes": "Please deliver as soon as possible.", "terms": "Thanks for your business.", "delivery_address": { "is_verifiable": true, "email": "peterparker@bowmanfurniture.com", "phone": "+1-925-929-7211", "is_verified": false }, "price_precision": 2, "custom_fields": [ { "custom_field_id": "46000000012845", "index": 1, "value": "Normal", "label": "Priority" } ], "attachment_name": "7.png", "can_send_in_mail": false, "template_id": "460000000011003", "template_name": "Standard Template", "page_width": "8.27in", "page_height": "11.69in", "orientation": "portrait", "template_type": "standard", "created_time": "2014-02-10T15:26:26+0530", "created_by_id": "460000000053001", "last_modified_time": "2014-02-10T15:26:26+0530", "can_mark_as_bill": false, "can_mark_as_unbill": false } }
ARGUMENTS
|
vendor_id
Required
ID of the vendor the purchase order has to be created.
contact_persons
Optional
Array of contact person(s) for whom purchase order has to be sent.
purchaseorder_number
Optional
Mandatory if auto number generation is disabled.
gst_treatment
India Edition only.
Optional
Choose whether the contact is GST registered/unregistered/consumer/overseas. Allowed values are
business_gst , business_none , overseas , consumer .
gst_no
India Edition only.
Optional
15 digit GST identification number of the vendor.
source_of_supply
India Edition only.
Optional
Place from where the goods/services are supplied. (If not given,
place of contact given for the contact will be taken)
destination_of_supply
India Edition only.
Optional
Place where the goods/services are supplied to. (If not given, organisation's home state will be taken)
pricebook_id
Optional
Enter pricebook ID
reference_number
Optional
Reference number of purchase order.
billing_address_id
Optional
ID of the Billing Address
crm_owner_id
Optional
ID of the CRM Owner
crm_custom_reference_id
Optional
ID of CRM Custom Reference
template_id
Optional
ID of the pdf template associated with the purchase order.
date
Optional
The date the purchase order is created.
delivery_date
Optional
Date of delivery of the purchase order
due_date
Optional
Delivery date of purchase order.
exchange_rate
Optional
Exchange rate of the currency.
is_inclusive_tax
Not applicable for US edition
Optional
Used to specify whether the line item rates are inclusive or exclusive of tax.
notes
Optional
Delivery note for vendor.
notes_default
Optional
Default notes for purchase order
terms
Optional
Terms for the purchase order
terms_default
Optional
Default terms for Purchase Orders
ship_via
Optional
Shipment Preference
delivery_org_address_id
Optional
ID of the Delivery Address
delivery_customer_id
Optional
ID of the Customer associated with the Purchase Order
attention
Optional
Delivery contact person.
vat_treatment
UK Edition only
Optional
(Optional) VAT treatment for the
purchase order. VAT treatment denotes the location of the vendor, if the
vendor resides in UK then the VAT treatment is
uk. If the vendor is in an EU country & if he is VAT registered then his VAT treatment is eu_vat_registered, if he resides in EU & if he is not VAT registered then his VAT treatment is eu_vat_not_registered and if he resides outside the EU then his VAT treatment is non_eu.
is_update_customer
Optional
Check if customer should be updated
salesorder_id
Optional
ID of the Sales Order
line_items
Required
Line items of purchase order.
line_item_id
Optional
ID of the line item. Mandatory if the existing line item has to be updated. If empty, a new line item will be created.
item_id
Optional
ID of the item.
account_id
Optional
ID of the account, the line item is associated with.
name
Optional
Name of the line item.
unit
Optional
Unit of the line item e.g. kgs, Nos.
warehouse_id
Optional
Enter warehouse ID
hsn_or_sac
India Edition Only
Optional
HSN or SAC Code for the Item
reverse_charge_tax_id
Optional
Enter reverse charge tax ID
rate
Optional
Rate of the line item.
quantity
Optional
Quantity of the line item.
item_order
Optional
Order of the items in Purhcase Order
tax_id
Optional
hsn_or_sac
India Edition Only
Optional
HSN or SAC Code for the Item
tax_exemption_code
India, CA and AU Editions Only
Optional
Code of the Tax Exemption
tax_exemption_id
India, CA and AU Editions Only
Optional
ID of the Tax Exemption
acquisition_vat_id
UK and EU Editions Only
Optional
ID of the VAT Acquistion
reverse_charge_vat_id
UK and EU Editions Only
Optional
ID of the Reverse Charge
item_custom_fields
Optional
index
Optional
Index of the Custom Field
value
Optional
Value of the Custom Field
item_custom_fields
Optional
index
Optional
Index of the Custom Field
value
Optional
Value of the Custom Field
tags
Optional
custom_fields
Optional
index
Optional
Index of the Custom Field
value
Optional
Value of the Custom Field
documents
Optional
document_id
Optional
ID of the Document
file_name
Optional
Name of the file
|
Query Params
|
attachment
Optional
Allowed Extensions:
gif, png, jpeg, jpg, bmp, pdf, xls, xlsx, doc and docx.
ignore_auto_number_generation
Optional
Ignore auto purchase order number generation for this purchase order. This mandates the purchase order number.
|
List purchase orders
List all purchase orders.
GET /purchaseorders
Request Example
$ curl https://books.zoho.com/api/v3/purchaseorders?organization_id=10234695 -H "Authorization: Zoho-authtoken ba4604e8e433g9c892e360d53463oec5" -H "Content-Type: application/json;charset=UTF-8"
Response Example
HTTP/1.1 200 OK Content-Type:application/json;charset=UTF-8 { "code": 0, "message": "success", "purchaseorders": [ { "purchaseorder_id": "460000000062001", "vendor_id": "460000000026049", "status": "draft", "purchaseorder_number": "PO-00001", "reference_number": "ER/0034", "date": "2014-02-10", "delivery_date": "2014-02-10", "currency_id": "460000000000099", "currency_code": "INR", "price_precision": 2, "total": 40, "has_attachment": false, "created_time": "2014-02-10T15:26:26+0530", "last_modified_time": "2014-02-10T15:26:26+0530", "custom_fields": [ { "custom_field_id": "46000000012845", "index": 1, "value": "Normal", "label": "Priority" } ] }, {...}, {...} ] }
Query Params
|
purchaseorder_number
Optional
Search purchase order by purchase order number. Variants:
purchaseorder_number.startswith and purchaseorder_number.contains
reference_number
Optional
Search purchase order by reference number.Variants:
reference_number.startswith and reference_number.contains
date
Optional
The date the purchase order is created.
status
Optional
Search purchase order by purchase order status. Allowed Values:
draft, open, billed and cancelled
item_description
Optional
Search purchase order by purchase order item description. Variants:
item_description.startswith and item_description.contains
vendor_name
Optional
Search purchase order by vendor name. Variants:
vendor_name.startswith and vendor_name.contains
total
Optional
Search purchase order by purchase order total. Variants:
total.start, total.end, total.less_than, total.less_equals, total.greater_than and total.greater_equals
vendor_id
Optional
Search purchase order by vendor id.
last_modified_time
Optional
Search purchase order by last modified time.
item_id
Optional
Search purchase order by item id.
filter_by
Optional
Filter purchase order by any status. Allowed Values:
Status.All, Status.Draft, Status.Open, Status.Billed and Status.Cancelled.
search_text
Optional
Search purchase order by purchase order number or reference number or vendor name.
sort_column
Optional
Sort purchase orders. Allowed Values:
vendor_name, purchaseorder_number, date, delivery_date, total and created_time.
custom_field
Optional
Search purchase order by purchase order’s custom field. Variants:
custom_field_startswith, custom_field_contains |
Get a purchase order
Get the details of a purchase order.
GET /purchaseorders/{purchaseorder_id}
Request Example
$ curl https://books.zoho.com/api/v3/purchaseorders/{purchaseorder_id}?organization_id=10234695 -H "Authorization: Zoho-authtoken ba4604e8e433g9c892e360d53463oec5" -H "Content-Type: application/json;charset=UTF-8"
Response Example
HTTP/1.1 200 OK Content-Type:application/json;charset=UTF-8 { "code": 0, "message": "success", "purchaseorder": { "purchaseorder_id": "460000000062001", "documents": [ {...} ], "gst_no": "22AAAAA0000A1Z5", "gst_treatment": "business_gst", "is_pre_gst": false, "source_of_supply": "AP", "destination_of_supply": "TN", "pricebook_id": 460000000026089, "pricebook_name": "", "is_reverse_charge_applied": false, "purchaseorder_number": "PO-00001", "date": "2014-02-10", "reference_number": "ER/0034", "status": "draft", "vendor_id": "460000000026049", "contact_persons": [ "460000000026051" ], "currency_id": "460000000000099", "currency_code": "INR", "exchange_rate": 1, "delivery_date": "2014-02-10", "is_emailed": false, "is_inclusive_tax": false, "line_items": [ { "item_id": "460000000027009", "line_item_id": "460000000074009", "warehouse_id": 460000000026051, "reverse_charge_tax_id": 460000000026068, "reverse_charge_tax_name": "inter", "reverse_charge_tax_percentage": 10, "reverse_charge_tax_amount": 100, "account_id": "460000000074003", "account_name": "Other Expenses", "name": "Hard Drive", "item_order": 0, "bcy_rate": 40, "unit": "Nos", "rate": 112, "quantity": 1, "item_total": 40, "item_total_inclusive_of_tax": 40, "tax_type": "tax", "tax_percentage": 0, "tags": [ {...} ], "item_custom_fields": [ { "custom_field_id": "46000000012845", "index": 1, "value": "Normal", "label": "Priority" } ] } ], "sub_total": 40, "tax_total": 0, "total": 40, "taxes": [ {...} ], "acquisition_vat_summary": [ {...} ], "reverse_charge_vat_summary": [ {...} ], "billing_address": { "street2": "McMillan Avenue" }, "notes": "Please deliver as soon as possible.", "terms": "Thanks for your business.", "delivery_address": { "is_verifiable": true, "email": "peterparker@bowmanfurniture.com", "phone": "+1-925-929-7211", "is_verified": false }, "price_precision": 2, "custom_fields": [ { "custom_field_id": "46000000012845", "index": 1, "value": "Normal", "label": "Priority" } ], "attachment_name": "7.png", "can_send_in_mail": false, "template_id": "460000000011003", "template_name": "Standard Template", "page_width": "8.27in", "page_height": "11.69in", "orientation": "portrait", "template_type": "standard", "created_time": "2014-02-10T15:26:26+0530", "created_by_id": "460000000053001", "last_modified_time": "2014-02-10T15:26:26+0530", "can_mark_as_bill": false, "can_mark_as_unbill": false } }
Query Params
|
print
Optional
Print the exported pdf.
accept
Optional
Get the details of a particular purchase order in formats such as json/ pdf/ html. Default format is json. Allowed Values:
json, pdf and html. |
Delete purchase order
Delete an existing purchase order.
DELETE /purchaseorders/{purchaseorder_id}
Request Example
$ curl https://books.zoho.com/api/v3/purchaseorders/{purchaseorder_id}?organization_id=10234695 -H "Authorization: Zoho-authtoken ba4604e8e433g9c892e360d53463oec5" -H "Content-Type: application/json;charset=UTF-8"
Response Example
HTTP/1.1 200 OK Content-Type:application/json;charset=UTF-8 { "code": 0, "message": "The purchase order has been deleted." }
Mark a purchase order as open
Mark a draft purchase order as open.
POST /purchaseorders/{purchaseorder_id}/status/open
Request Example
$ curl https://books.zoho.com/api/v3/purchaseorders/{purchaseorder_id}/status/open?organization_id=10234695 -H "Authorization: Zoho-authtoken ba4604e8e433g9c892e360d53463oec5" -H "Content-Type: application/json;charset=UTF-8"
Response Example
HTTP/1.1 201 Created Content-Type:application/json;charset=UTF-8 { "code": 0, "message": "The purchase order has been marked as open." }
Mark as billed
Mark a purchase order as billed.
POST /purchaseorders/{purchaseorder_id}/status/billed
Request Example
$ curl https://books.zoho.com/api/v3/purchaseorders/{purchaseorder_id}/status/billed?organization_id=10234695 -H "Authorization: Zoho-authtoken ba4604e8e433g9c892e360d53463oec5" -H "Content-Type: application/json;charset=UTF-8"
Response Example
HTTP/1.1 201 Created Content-Type:application/json;charset=UTF-8 { "code": 0, "message": "The purchase order has been marked as billed." }
Cancel a purchase order
Mark a purchase order as cancelled.
POST /purchaseorders/{purchaseorder_id}/status/cancelled
Request Example
$ curl https://books.zoho.com/api/v3/purchaseorders/{purchaseorder_id}/status/cancelled?organization_id=10234695 -H "Authorization: Zoho-authtoken ba4604e8e433g9c892e360d53463oec5" -H "Content-Type: application/json;charset=UTF-8"
Response Example
HTTP/1.1 201 Created Content-Type:application/json;charset=UTF-8 { "code": 0, "message": "The purchase order has been cancelled." }
Email a purchase order
Email a purchase order to the vendor. Input json string is not mandatory. If input json string is empty, mail will be send with default mail content.
POST /purchaseorders/{purchaseorder_id}/email
Request Example
$ curl https://books.zoho.com/api/v3/purchaseorders/{purchaseorder_id}/email?organization_id=10234695 -H "Authorization: Zoho-authtoken ba4604e8e433g9c892e360d53463oec5" -H "Content-Type: application/json;charset=UTF-8" -d '{ "send_from_org_email_id": true, "from_address_id": "460000008392548", "to_mail_ids": [ {} ], "cc_mail_ids": [ {} ], "bcc_mail_ids": [ {} ], "subject": "Purchase Order from Zillium Inc (PO #: PO-00001)", "body": "Dear Bowman and Co, <br><br>The purchase order (PO-00001) is attached with this email. <br><br>An overview of the purchase order is available below: <br>Purchase Order # : PO-00001 <br>Date : 10 Feb 2014 <br>Amount : $112.00(in USD) <br><br>Please go through it and confirm the order. We look forward to working with you again<br><br><br><br>Regards<br><br>Zillium Inc<br><br>", "mail_documents": [ {} ] }
Response Example
HTTP/1.1 201 Created Content-Type:application/json;charset=UTF-8 { "code": 0, "message": "Your purchase order has been sent." }
ARGUMENTS
|
send_from_org_email_id
Optional
Boolean to trigger the email from the organization's email address.
from_address_id
Optional
ID of From Address of the Email Address
to_mail_ids
Required
Array of email address of the recipients.
cc_mail_ids
Optional
Array of email address of the recipients to be cced.
bcc_mail_ids
Optional
Array of email address of the recipients to be BCC ed.
subject
Optional
Subject of the mail.
body
Required
Body of the mail
mail_documents
Optional
document_id
Optional
ID of the Document
file_name
Optional
Name of the file
|
Query Params
|
attachments
Optional
The files to be attached with the email.
send_attachment
Optional
Send the purchase order attachment a with the email.
file_name
Optional
Name of the file
|
Get purchase order email content
Get the email content of a purchase order.
GET /purchaseorders/{purchaseorder_id}/email
Request Example
$ curl https://books.zoho.com/api/v3/purchaseorders/{purchaseorder_id}/email?organization_id=10234695 -H "Authorization: Zoho-authtoken ba4604e8e433g9c892e360d53463oec5" -H "Content-Type: application/json;charset=UTF-8"
Response Example
HTTP/1.1 200 OK Content-Type:application/json;charset=UTF-8 { "code": 0, "message": "success" }
Query Params
|
email_template_id
Optional
Get the email content based on a
specific email template. If this param is not inputted, then the content
will be based on the email template associated with the customer. If no
template is associated with the customer, then default template will be
used.
|
Update billing address
Updates the billing address for this purchase order alone.
PUT /purchaseorders/{purchaseorder_id}/address/billing
Request Example
$ curl https://books.zoho.com/api/v3/purchaseorders/{purchaseorder_id}/address/billing?organization_id=10234695 -H "Authorization: Zoho-authtoken ba4604e8e433g9c892e360d53463oec5" -H "Content-Type: application/json;charset=UTF-8" -d '{}
Response Example
HTTP/1.1 200 OK Content-Type:application/json;charset=UTF-8 { "code": 0, "message": "Billing address updated." }
ARGUMENTS
|
address
Optional
Address associated with the Purchase Order
city
Optional
City involved in the Address
state
Optional
State Involved in the Address
zip
Optional
ZIP Code of the Address
country
Optional
Country involved in the Address
fax
Optional
Fax Number
attention
Optional
Delivery contact person.
is_update_customer
Optional
Check if customer should be updated
|
List purchase order templates
Get all purchase order pdf templates.
GET /purchaseorders/templates
Request Example
$ curl https://books.zoho.com/api/v3/purchaseorders/templates?organization_id=10234695 -H "Authorization: Zoho-authtoken ba4604e8e433g9c892e360d53463oec5" -H "Content-Type: application/json;charset=UTF-8"
Response Example
HTTP/1.1 200 OK Content-Type:application/json;charset=UTF-8 { "code": 0, "message": "success", "templates": [ { "template_name": "Standard Template", "template_id": "460000000011003", "template_type": "standard" } ] }
Update purchase order template
Update the pdf template associated with the purchase order.
PUT /purchaseorders/{purchaseorder_id}/templates/{template_id}
Request Example
$ curl https://books.zoho.com/api/v3/purchaseorders/{purchaseorder_id}/templates/{template_id}?organization_id=10234695 -H "Authorization: Zoho-authtoken ba4604e8e433g9c892e360d53463oec5" -H "Content-Type: application/json;charset=UTF-8"
Response Example
HTTP/1.1 200 OK Content-Type:application/json;charset=UTF-8 { "code": 0, "message": "Purchase Order has been updated." }
Query Params
|
templates
Optional
template_name
Optional
Name of the template
template_id
Optional
ID of the pdf template associated with the purchase order.
template_type
Optional
Type of the Template
|
Get a purchase order attachment
Returns the file attached to the purchase order.
GET /purchaseorders/{purchaseorder_id}/attachment
Request Example
$ curl https://books.zoho.com/api/v3/purchaseorders/{purchaseorder_id}/attachment?organization_id=10234695 -H "Authorization: Zoho-authtoken ba4604e8e433g9c892e360d53463oec5" -H "Content-Type: application/json;charset=UTF-8"
Response Example
HTTP/1.1 200 OK Content-Type:application/json;charset=UTF-8 { "code": 0, "message": "success" }
Query Params
|
preview
Optional
Get the thumbnail of the attachment.
|
Add attachment to a purchase order
Attach a file to a purchase order
POST /purchaseorders/{purchaseorder_id}/attachment
Request Example
$ curl https://books.zoho.com/api/v3/purchaseorders/{purchaseorder_id}/attachment?organization_id=10234695 -H "Authorization: Zoho-authtoken ba4604e8e433g9c892e360d53463oec5" -H "Content-Type: application/json;charset=UTF-8"
Response Example
HTTP/1.1 201 Created Content-Type:application/json;charset=UTF-8 { "code": 0, "message": "The document has been attached." }
Query Params
|
attachment
Optional
Allowed Extensions:
gif, png, jpeg, jpg, bmp, pdf, xls, xlsx, doc and docx. |
Update attachment preference
Set whether you want to send the attached file while emailing the purchase order.
PUT /purchaseorders/{purchaseorder_id}/attachment
Request Example
$ curl https://books.zoho.com/api/v3/purchaseorders/{purchaseorder_id}/attachment?organization_id=10234695 -H "Authorization: Zoho-authtoken ba4604e8e433g9c892e360d53463oec5" -H "Content-Type: application/json;charset=UTF-8"
Response Example
HTTP/1.1 200 OK Content-Type:application/json;charset=UTF-8 { "code": 0, "message": "Purchase Order has been updated." }
Query Params
|
can_send_in_mail
Required
Boolean to send the attachment with the purchase order when emailed.
|
Delete an attachment
Delete the file attached to the purchase order.
DELETE purchaseorders/{purchaseorder_id}/attachment
Request Example
$ curl https://books.zoho.com/api/v3purchaseorders/{purchaseorder_id}/attachment?organization_id=10234695 -H "Authorization: Zoho-authtoken ba4604e8e433g9c892e360d53463oec5" -H "Content-Type: application/json;charset=UTF-8"
Response Example
HTTP/1.1 200 OK Content-Type:application/json;charset=UTF-8 { "code": 0, "message": "The attachment has been deleted." }
List purchase order comments & history
Get the complete history and comments of purchase order.
GET /purchaseorders/{purchaseorder_id}/comments
Request Example
$ curl https://books.zoho.com/api/v3/purchaseorders/{purchaseorder_id}/comments?organization_id=10234695 -H "Authorization: Zoho-authtoken ba4604e8e433g9c892e360d53463oec5" -H "Content-Type: application/json;charset=UTF-8"
Response Example
HTTP/1.1 200 OK Content-Type:application/json;charset=UTF-8 { "code": 0, "message": "success", "comments": [ { "comment_id": "460000000012345", "comment_type": "system", "date": "2014-02-10", "date_description": "22 hours ago.", "time": "3.26PM", "operation_type": "Updated", "transaction_type": "purchaseorder" }, {...}, {...} ] }
Add comment
Add a comment for a purchase order.
POST /purchaseorders/{purchaseorder_id}/comments
Request Example
$ curl https://books.zoho.com/api/v3/purchaseorders/{purchaseorder_id}/comments?organization_id=10234695 -H "Authorization: Zoho-authtoken ba4604e8e433g9c892e360d53463oec5" -H "Content-Type: application/json;charset=UTF-8" -d '{}
Response Example
HTTP/1.1 201 Created Content-Type:application/json;charset=UTF-8 { "code": 0, "message": "Comments added.", "comment": { "comment_id": "460000000012345", "purchaseorder_id": "460000000062001", "comment_type": "system", "date": "2014-02-10", "date_description": "22 hours ago.", "time": "3.26PM" } }
ARGUMENTS
|
description
Required
expected_delivery_date
Required
Date the goods is expected to arrive.
|
Update comment
Update an existing comment of a purchase order.
PUT /purchaseorders/{purchaseorder_id}/comments/{comment_id}
Request Example
$ curl https://books.zoho.com/api/v3/purchaseorders/{purchaseorder_id}/comments/{comment_id}?organization_id=10234695 -H "Authorization: Zoho-authtoken ba4604e8e433g9c892e360d53463oec5" -H "Content-Type: application/json;charset=UTF-8" -d '{}
Response Example
HTTP/1.1 200 OK Content-Type:application/json;charset=UTF-8 { "code": 0, "message": "Comment has been updated." }
ARGUMENTS
|
description
Optional
expected_delivery_date
Optional
Date the goods is expected to arrive.
|
Delete a comment
Delete a purchase order comment.
DELETE /purchaseorders/{purchaseorder_id}/comments/{comment_id}
Request Example
$ curl https://books.zoho.com/api/v3/purchaseorders/{purchaseorder_id}/comments/{comment_id}?organization_id=10234695 -H "Authorization: Zoho-authtoken ba4604e8e433g9c892e360d53463oec5" -H "Content-Type: application/json;charset=UTF-8"
Response Example
HTTP/1.1 200 OK Content-Type:application/json;charset=UTF-8 { "code": 0, "message": "The comment has been deleted." }
Bills
When your vendor supplies goods/services to you on credit, you’re sent an invoice that details the amount of money you owe him. You can record this as a bill in Zoho Books and track it until it’s paid.
Example
{ "bill": { "bill_id": "460000000098765", "purchaseorder_ids": [ 460000000068231, 460000000068233 ], "vendor_id": "460000000038029", "source_of_supply": "AP", "destination_of_supply": "TN", "gst_no": "22AAAAA0000A1Z5", "gst_treatment": "business_gst", "is_pre_gst": false, "pricebook_id": 460000000038090, "is_reverse_charge_applied": true, "unused_credits_payable_amount": 187, "status": "open", "bill_number": "00454", "date": "2013-09-11", "due_date": "2013-09-26", "payment_terms": 0, "payment_terms_label": "Due on Receipt", "reference_number": "4321133", "due_in_days": 0, "currency_id": "460000000000099", "currency_code": "INR", "documents": [ {} ], "price_precision": 2, "exchange_rate": 1.23, "custom_fields": [ {} ], "is_item_level_tax_calc": false, "is_inclusive_tax": false, "line_items": [ { "line_item_id": "460000000067009", "item_id": "460000000054135", "account_id": "460000000000403", "account_name": "Other Expenses", "image_document_id": 460000000038067, "warehouse_id": 460000000038089, "reverse_charge_tax_id": 460000000038056, "reverse_charge_tax_name": "inter", "reverse_charge_tax_percentage": 10, "reverse_charge_tax_amount": 100, "bcy_rate": 40, "rate": 10, "tags": [ {} ], "quantity": 1, "tax_id": "460000000027005", "tax_name": "VAT (12.5%)", "tax_type": "tax", "tax_percentage": 0, "item_total": 40, "item_total_inclusive_of_tax": 40, "item_order": 1, "unit": "kgs", "hsn_or_sac": 80540, "is_billable": false, "item_custom_fields": [ {} ] } ], "sub_total": 40, "tax_total": 0, "total": 40, "payment_made": 0, "vendor_credits_applied": 0, "is_line_item_invoiced": false, "purchaseorders": [ { "purchaseorder_id": "460000000068231", "purchaseorder_number": "PO-0001", "purchaseorder_date": "19 Jan 2017", "purchaseorder_status": "billed" } ], "taxes": [ { "tax_name": "VAT (12.5%)", "tax_amount": 1.25 } ], "acquisition_vat_summary": [ { "tax_name": "VAT (12.5%)", "tax_amount": 1.25 } ], "reverse_charge_vat_summary": [ { "tax_name": "VAT (12.5%)", "tax_amount": 1.25 } ], "balance": 40, "billing_address": { "street2": "Suite 310" }, "payments": [ { "payment_id": "460000000042059", "bill_id": "460000000098765", "bill_payment_id": "460000000042061", "payment_mode": "Cash", "date": "2013-09-11", "reference_number": "4321133", "exchange_rate": 1.23, "amount": 31.25, "paid_through_account_id": "460000000000358", "paid_through_account_name": "Undeposited Funds", "is_single_bill_payment": true, "is_paid_via_print_check": false, "check_details": [ {} ], "is_ach_payment": false } ], "vendor_credits": [ { "vendor_credit_id": "4600000053221", "vendor_credit_bill_id": "4600000211221", "vendor_credit_number": "DN-001", "date": "2013-09-11", "amount": 31.25 } ], "created_time": "2013-09-11T17:18:32+0530", "created_by_id": "4600000053001", "last_modified_time": "2013-09-11T17:18:32+0530", "notes": "Thanks for your business.", "terms": "Terms and conditions apply.", "open_purchaseorders_count": 1 } }
Attribute
|
bill
object
bill_id
string
ID of the Bill
purchaseorder_ids
array
vendor_id
string
ID of the vendor the bill has to be created.
vendor_name
string
Name of the Vendor
vat_treatment
UK Edition only
string
(Optional) VAT treatment for the bill.
VAT treatment denotes the location of the vendor, if the vendor resides
in UK then the VAT treatment is
uk. If the vendor is in an EU country & if he is VAT registered then his VAT treatment is eu_vat_registered, if he resides in EU & if he is not VAT registered then his VAT treatment is eu_vat_not_registered and if he resides outside the EU then his VAT treatment is non_eu.
vat_reg_no
UK Edition and Avalara integration only
string
For UK Edition: VAT Registration number of a contact with VAT treatment as
eu_vat_registered. Length should be between 2 and 12 characters.(This node is only available for EU VAT registered contacts.)For Avalara: If you are doing sales in the European Union (EU) then provide VAT Registration Number of your customers here. This is used to calculate VAT for B2B sales, from Avalara.
source_of_supply
India Edition only
string
Place from where the goods/services are supplied. (If not given,
place of contact given for the contact will be taken)
destination_of_supply
India Edition only
string
Place where the goods/services are supplied to. (If not given, organisation's home state will be taken)
gst_no
India Edition only
string
15 digit GST identification number of the vendor.
gst_treatment
India Edition only
string
Choose whether the contact is GST registered/unregistered/consumer/overseas. Allowed values are
business_gst , business_none , overseas , consumer .
is_pre_gst
India Edition only
boolean
Applicable for transactions that fall before july 1, 2017
pricebook_id
string
Enter ID of the price book.
pricebook_name
string
Name of the price book
is_reverse_charge_applied
India Edition only
boolean
Applicable for transactions where you pay reverse charge
unused_credits_payable_amount
integer
Unused Credits for this Vendor
status
string
Status of the Bill
bill_number
string
The bill number.
date
string
The date the bill was created. [yyyy-mm-dd]
due_date
string
Date bill is due.
payment_terms
integer
Number Referring to Payment Terms
payment_terms_label
string
Label of the Payment Terms
payment_expected_date
string
Expected Payment date of the Bill
reference_number
string
Reference Number of the entity
recurring_bill_id
string
ID of the Recurring Bill
due_by_days
string
Days by which Bill is Due
due_in_days
integer
Days in which Bill will be Due
currency_id
string
ID of the Currency
currency_code
string
Code of the Currency
currency_symbol
string
Symbol of the Currency
documents
list
document_id
long
ID of the Document
file_name
string
Name of the file
price_precision
integer
Precision for the values
exchange_rate
double
Exchange rate of the currency.
custom_fields
list
custom_field_id
long
index
integer
Index of the custom field
label
stirng
Label of the Custom Field
value
string
Value of the Custom Field
is_tds_applied
Only for India, Global and AU Editions
boolean
Check if TDS is applied
is_item_level_tax_calc
boolean
Check if Item Level Tax Calculation is present
is_inclusive_tax
Not applicable for US edition.
boolean
Used to specify whether the line item rates are inclusive or exclusive of tax.
filed_in_vat_return_id
UK Edition Only
string
ID of the VAT Return the Vendor Credit is filed in
filed_in_vat_return_name
UK Edition Only
string
Name of the VAT Return the Vendor Credit is filed in
filed_in_vat_return_type
UK Edition Only
string
Type of the VAT Return the Vendor Credit is filed in
is_abn_quoted
AU Edition Only
string
line_items
list
Line items of a bill.
purchaseorder_item_id
string
ID of the Item in Purchase Order
line_item_id
string
ID of the Line Item
item_id
string
ID of the Item
sku
string
SKU of the Item
name
string
account_id
string
ID of the account associated with the line item.
account_name
string
Name of the Account
image_document_id
India Edition only
string
ID of the image document
warehouse_id
India Edition only
string
Warehoude ID
warehouse_name
string
Name of the warehouse
reverse_charge_tax_id
India Edition only
string
Reverse charge tax ID
reverse_charge_tax_name
India Edition only
string
Name of the reverse charge tax
reverse_charge_tax_percentage
India Edition only
double
Enter reverse charge percentage
reverse_charge_tax_amount
India Edition only
double
Enter reverse charge amount
bcy_rate
integer
Rate in Base Currency of the Organization
rate
double
Rate of the line item.
tags
list
quantity
double
Quantity of the line item.
tax_id
Not applicable for the US Edition.
string
ID of the tax or tax group applied to the line item.
tax_exemption_id
India, AU and CA Editions Only
string
ID of the Tax Exemption Applied
tax_exemption_code
India, AU and CA Editions Only
string
Code of the Tax Exemption Applied
tax_name
string
Name of the Tax
tax_type
string
Type of tax
tax_percentage
integer
Percentage of Tax
item_total
integer
Total of the Item
item_total_inclusive_of_tax
double
Total of the Item Inclusive of Tax
item_order
integer
unit
string
Unit of the Item
product_type
Allowed for EU and UK Edition only
string
Type of the bill. This denotes whether
the bill line item is to be treated as a goods or service purchase.
This only need to be specified in case purchase order is not enabled.
Allowed Values:
digital_service, goods and service.
hsn_or_sac
India Edition only
string
Add HSN/SAC code for your goods/services
acquisition_vat_id
UK Edition only
string
(Optional) This is the ID of the tax applied in case this is an EU - goods purchase and acquisition VAT needs to be reported.
acquisition_vat_name
UK and EU Editions Only
string
Name of the VAT Acquistion
acquisition_vat_percentage
UK and EU Editions Only
string
Percentage of the VAT Acquistion
acquisition_vat_amount
UK and EU Editions Only
string
Amount of the VAT Acquistion
reverse_charge_vat_id
UK Edition only
string
(Optional) This is the ID of the tax
applied in case this is a non UK - service purchase and reverse charge
VAT needs to be reported.
reverse_charge_vat_name
UK and EU Editions Only
string
Name of the Reverse Charge
reverse_charge_vat_percentage
UK and EU Editions Only
string
Percentage of the Reverse Charge
reverse_charge_vat_amount
UK and EU Editions Only
string
Percentage of the Reverse Charge
is_billable
boolean
Check if entity is Billable
customer_id
string
ID of the Customer
customer_name
string
Name of the Customer
project_id
string
ID of the Project
project_name
string
Name of the Project
invoice_id
string
ID of the Invoice
invoice_number
string
Number associated with the Invoice
item_custom_fields
list
custom_field_id
long
index
integer
Index of the custom field
value
string
Value of the Custom Field
label
stirng
Label of the Custom Field
sub_total
integer
Sub Total of the Bill
tax_total
integer
Tax Total of the Bill
total
integer
Total of the Bill
payment_made
integer
Amount of Payment made
vendor_credits_applied
integer
Amount of credits applied
is_line_item_invoiced
boolean
Check if line item is invoiced
purchaseorders
list
purchaseorder_id
string
ID of the Purchase Order
purchaseorder_number
string
Number of the Purchase Order
purchaseorder_date
string
Date of the Purchase Order
purchaseorder_status
string
Status of the Purchase Order
taxes
list
tax_name
string
Name of the Tax
tax_amount
string
Amount of Tax in the Bill
acquisition_vat_summary
UK and EU Editions Only
list
Summary of the VAT Acquistion
tax_name
string
Name of the Tax
tax_amount
string
Amount of Tax in the Bill
acquisition_vat_total
UK and EU Editions Only
double
Total of the VAT Acquistion
reverse_charge_vat_summary
UK and EU Editions Only
list
Summary of the Reverse Charge
tax_name
string
Name of the Tax
tax_amount
string
Amount of Tax in the Bill
reverse_charge_vat_total
UK and EU Editions Only
double
Total of the Reverse Charge
balance
integer
Balance in the Bill
billing_address
object
address
string
Address involved in the Bill
street2
string
Address details
city
string
City in the Address
state
string
State involved in the Address
zip
string
ZIP Code involved in the Address
country
string
Country Involved in the Address
fax
string
Fax of the Vendor
attention
string
payments
list
payment_id
string
ID of the Payment
bill_id
string
ID of the Bill
bill_payment_id
string
ID of the Bill Payment
payment_mode
string
Mode of Payment
payment_number
string
Number of the Payment Made
description
string
Description of the line item.
date
string
The date the bill was created. [yyyy-mm-dd]
reference_number
string
Reference Number of the entity
exchange_rate
double
Exchange rate of the currency.
amount
double
paid_through_account_id
string
ID of the Account through which Bill is Paid
paid_through_account_name
string
Name of the Account through which Bill is Paid
is_single_bill_payment
boolean
Check if it is a Single Bill Payment
is_paid_via_print_check
US and CA Edition Only.
boolean
Check if the Bill Payment is paid Via Print Check Option
check_details
US and CA Edition Only.
list
check_status
US and CA Edition Only.
string
Status of the Check
check_number
US and CA Edition Only.
string
Check Number that is printed
is_ach_payment
boolean
Check If Vendor Payment ACH
ach_payment_status
string
Status of the ACH Payment
ach_gw_transaction_id
string
ID of the ACH Payment Transaction
filed_in_vat_return_id
UK Edition Only
string
ID of the VAT Return the Vendor Credit is filed in
filed_in_vat_return_name
UK Edition Only
string
Name of the VAT Return the Vendor Credit is filed in
filed_in_vat_return_type
UK Edition Only
string
Type of the VAT Return the Vendor Credit is filed in
vendor_credits
list
vendor_credit_id
string
ID of the Vendor Credit
vendor_credit_bill_id
string
ID of the Bill Credited using the Vendor Credit
vendor_credit_number
string
Number of the Vendor Credit
date
string
Date Vendor Credit was applied
amount
double
Amount of Credit applied to the Bill
created_time
string
Created time of the bill
created_by_id
string
Name of User who created the Bill
last_modified_time
string
Last Modified Time of the Bill
reference_id
string
notes
string
Notes for the Bill
terms
string
Terms and Conditions for the Bill
attachment_name
string
Name of the Attachment
open_purchaseorders_count
integer
Number of Open Purchase Orders
|
Create a bill
Create a bill received from your vendor.
POST /bills
Request Example
$ curl https://books.zoho.com/api/v3/bills?organization_id=10234695 -H "Authorization: Zoho-authtoken ba4604e8e433g9c892e360d53463oec5" -H "Content-Type: application/json;charset=UTF-8" -d '{ "vendor_id": "460000000038029", "is_update_customer": false, "purchaseorder_ids": [ 460000000068231, 460000000068233 ], "bill_number": "00454", "documents": [ {} ], "source_of_supply": "AP", "destination_of_supply": "TN", "gst_treatment": "business_gst", "gst_no": "22AAAAA0000A1Z5", "pricebook_id": 460000000038090, "reference_number": "4321133", "date": "2013-09-11", "due_date": "2013-09-26", "payment_terms": 0, "payment_terms_label": "Due on Receipt", "exchange_rate": 1.23, "is_item_level_tax_calc": false, "is_inclusive_tax": false, "custom_fields": [ {} ], "line_items": [ { "line_item_id": "460000000067009", "item_id": "460000000054135", "account_id": "460000000000403", "rate": 10, "hsn_or_sac": 80540, "reverse_charge_tax_id": 460000000038056, "warehouse_id": 460000000038089, "quantity": 1, "tax_id": "460000000027005", "item_order": 1, "unit": "kgs", "tags": [ {} ], "is_billable": false, "item_custom_fields": [ {} ], "serial_numbers": [ {} ] } ], "taxes": [ { "tax_id": "460000000027005", "tax_name": "VAT (12.5%)", "tax_amount": 1.25 } ], "notes": "Thanks for your business.", "terms": "Terms and conditions apply.", "approvers": [ {} ] }
Response Example
HTTP/1.1 201 Created Content-Type:application/json;charset=UTF-8 { "code": 0, "message": "success", "bill": { "bill_id": "460000000098765", "purchaseorder_ids": [ 460000000068231, 460000000068233 ], "vendor_id": "460000000038029", "source_of_supply": "AP", "destination_of_supply": "TN", "gst_no": "22AAAAA0000A1Z5", "gst_treatment": "business_gst", "is_pre_gst": false, "pricebook_id": 460000000038090, "is_reverse_charge_applied": true, "unused_credits_payable_amount": 187, "status": "open", "bill_number": "00454", "date": "2013-09-11", "due_date": "2013-09-26", "payment_terms": 0, "payment_terms_label": "Due on Receipt", "reference_number": "4321133", "due_in_days": 0, "currency_id": "460000000000099", "currency_code": "INR", "documents": [ {...} ], "price_precision": 2, "exchange_rate": 1.23, "custom_fields": [ {...} ], "is_item_level_tax_calc": false, "is_inclusive_tax": false, "line_items": [ { "line_item_id": "460000000067009", "item_id": "460000000054135", "account_id": "460000000000403", "account_name": "Other Expenses", "image_document_id": 460000000038067, "warehouse_id": 460000000038089, "reverse_charge_tax_id": 460000000038056, "reverse_charge_tax_name": "inter", "reverse_charge_tax_percentage": 10, "reverse_charge_tax_amount": 100, "bcy_rate": 40, "rate": 10, "tags": [ {...} ], "quantity": 1, "tax_id": "460000000027005", "tax_name": "VAT (12.5%)", "tax_type": "tax", "tax_percentage": 0, "item_total": 40, "item_total_inclusive_of_tax": 40, "item_order": 1, "unit": "kgs", "hsn_or_sac": 80540, "is_billable": false, "item_custom_fields": [ {...} ] } ], "sub_total": 40, "tax_total": 0, "total": 40, "payment_made": 0, "vendor_credits_applied": 0, "is_line_item_invoiced": false, "purchaseorders": [ { "purchaseorder_id": "460000000068231", "purchaseorder_number": "PO-0001", "purchaseorder_date": "19 Jan 2017", "purchaseorder_status": "billed" } ], "taxes": [ { "tax_name": "VAT (12.5%)", "tax_amount": 1.25 } ], "acquisition_vat_summary": [ { "tax_name": "VAT (12.5%)", "tax_amount": 1.25 } ], "reverse_charge_vat_summary": [ { "tax_name": "VAT (12.5%)", "tax_amount": 1.25 } ], "balance": 40, "billing_address": { "street2": "Suite 310" }, "payments": [ { "payment_id": "460000000042059", "bill_id": "460000000098765", "bill_payment_id": "460000000042061", "payment_mode": "Cash", "date": "2013-09-11", "reference_number": "4321133", "exchange_rate": 1.23, "amount": 31.25, "paid_through_account_id": "460000000000358", "paid_through_account_name": "Undeposited Funds", "is_single_bill_payment": true, "is_paid_via_print_check": false, "check_details": [ {...} ], "is_ach_payment": false } ], "vendor_credits": [ { "vendor_credit_id": "4600000053221", "vendor_credit_bill_id": "4600000211221", "vendor_credit_number": "DN-001", "date": "2013-09-11", "amount": 31.25 } ], "created_time": "2013-09-11T17:18:32+0530", "created_by_id": "4600000053001", "last_modified_time": "2013-09-11T17:18:32+0530", "notes": "Thanks for your business.", "terms": "Terms and conditions apply.", "open_purchaseorders_count": 1 } }
ARGUMENTS
|
vendor_id
Required
ID of the vendor the bill has to be created.
vat_treatment
UK Edition only
Optional
(Optional) VAT treatment for the bill.
VAT treatment denotes the location of the vendor, if the vendor resides
in UK then the VAT treatment is
uk. If the vendor is in an EU country & if he is VAT registered then his VAT treatment is eu_vat_registered, if he resides in EU & if he is not VAT registered then his VAT treatment is eu_vat_not_registered and if he resides outside the EU then his VAT treatment is non_eu.
is_update_customer
Optional
Check if cutomer should be updated
purchaseorder_ids
Optional
bill_number
Required
The bill number.
documents
Optional
document_id
Optional
ID of the Document
file_name
Optional
Name of the file
source_of_supply
India Edition only
Optional
Place from where the goods/services are supplied. (If not given,
place of contact given for the contact will be taken)
destination_of_supply
India Edition only
Optional
Place where the goods/services are supplied to. (If not given, organisation's home state will be taken)
gst_treatment
India Edition only
Optional
Choose whether the contact is GST registered/unregistered/consumer/overseas. Allowed values are
business_gst , business_none , overseas , consumer .
gst_no
India Edition only
Optional
15 digit GST identification number of the vendor.
pricebook_id
Optional
Enter ID of the price book.
reference_number
Optional
Reference Number of the entity
date
Optional
The date the bill was created. [yyyy-mm-dd]
due_date
Optional
Date bill is due.
payment_terms
Optional
Number Referring to Payment Terms
payment_terms_label
Optional
Label of the Payment Terms
recurring_bill_id
Optional
ID of the Recurring Bill
exchange_rate
Optional
Exchange rate of the currency.
is_item_level_tax_calc
Optional
Check if Item Level Tax Calculation is present
is_inclusive_tax
Not applicable for US edition.
Optional
Used to specify whether the line item rates are inclusive or exclusive of tax.
custom_fields
Optional
index
Optional
Index of the custom field
value
Optional
Value of the Custom Field
line_items
Optional
Line items of a bill.
purchaseorder_item_id
Optional
ID of the Item in Purchase Order
line_item_id
Optional
ID of the Line Item
item_id
Optional
ID of the Item
name
Optional
account_id
Optional
ID of the account associated with the line item.
rate
Optional
Rate of the line item.
hsn_or_sac
India Edition only
Optional
Add HSN/SAC code for your goods/services
reverse_charge_tax_id
India Edition only
Optional
Reverse charge tax ID
warehouse_id
India Edition only
Optional
Warehoude ID
quantity
Optional
Quantity of the line item.
tax_id
Not applicable for the US Edition.
Optional
ID of the tax or tax group applied to the line item.
tax_exemption_id
India, AU and CA Editions Only
Optional
ID of the Tax Exemption Applied
tax_exemption_code
India, AU and CA Editions Only
Optional
Code of the Tax Exemption Applied
item_order
Optional
product_type
Allowed for EU and UK Edition only
Optional
Type of the bill. This denotes whether
the bill line item is to be treated as a goods or service purchase.
This only need to be specified in case purchase order is not enabled.
Allowed Values:
digital_service, goods and service.
hsn_or_sac
India Edition only
Optional
Add HSN/SAC code for your goods/services
acquisition_vat_id
UK Edition only
Optional
(Optional) This is the ID of the tax applied in case this is an EU - goods purchase and acquisition VAT needs to be reported.
reverse_charge_vat_id
UK Edition only
Optional
(Optional) This is the ID of the tax
applied in case this is a non UK - service purchase and reverse charge
VAT needs to be reported.
unit
Optional
Unit of the Item
tags
Optional
is_billable
Optional
Check if entity is Billable
project_id
Optional
ID of the Project
customer_id
Optional
ID of the Customer
item_custom_fields
Optional
custom_field_id
Optional
index
Optional
Index of the custom field
value
Optional
Value of the Custom Field
label
Optional
Label of the Custom Field
serial_numbers
Optional
taxes
Optional
tax_id
Not applicable for the US Edition.
Optional
ID of the tax or tax group applied to the line item.
tax_name
Optional
Name of the Tax
tax_amount
Optional
Amount of Tax in the Bill
notes
Optional
Notes for the Bill
terms
Optional
Terms and Conditions for the Bill
approvers
Optional
approver_id
Optional
ID of the Approver
order
Optional
Order of the Approver
|
Query Params
|
attachment
Optional
File to attach. Allowed Extensions:
gif, png, jpeg, jpg, bmp and pdf. |
Update a bill
Update a bill. To delete a line item just remove it from the line_items list.
PUT /bills/{bill_id}
Request Example
$ curl https://books.zoho.com/api/v3/bills/{bill_id}?organization_id=10234695 -H "Authorization: Zoho-authtoken ba4604e8e433g9c892e360d53463oec5" -H "Content-Type: application/json;charset=UTF-8" -d '{ "vendor_id": "460000000038029", "is_update_customer": false, "purchaseorder_ids": [ 460000000068231, 460000000068233 ], "bill_number": "00454", "documents": [ {} ], "source_of_supply": "AP", "destination_of_supply": "TN", "gst_treatment": "business_gst", "gst_no": "22AAAAA0000A1Z5", "pricebook_id": 460000000038090, "reference_number": "4321133", "date": "2013-09-11", "due_date": "2013-09-26", "payment_terms": 0, "payment_terms_label": "Due on Receipt", "exchange_rate": 1.23, "is_item_level_tax_calc": false, "is_inclusive_tax": false, "custom_fields": [ {} ], "line_items": [ { "line_item_id": "460000000067009", "item_id": "460000000054135", "account_id": "460000000000403", "rate": 10, "hsn_or_sac": 80540, "reverse_charge_tax_id": 460000000038056, "warehouse_id": 460000000038089, "quantity": 1, "tax_id": "460000000027005", "item_order": 1, "unit": "kgs", "tags": [ {} ], "is_billable": false, "item_custom_fields": [ {} ], "serial_numbers": [ {} ] } ], "taxes": [ { "tax_id": "460000000027005", "tax_name": "VAT (12.5%)", "tax_amount": 1.25 } ], "notes": "Thanks for your business.", "terms": "Terms and conditions apply.", "approvers": [ {} ] }
Response Example
HTTP/1.1 200 OK Content-Type:application/json;charset=UTF-8 { "code": 0, "message": "Bill information has been updated.", "bill": { "bill_id": "460000000098765", "purchaseorder_ids": [ 460000000068231, 460000000068233 ], "vendor_id": "460000000038029", "source_of_supply": "AP", "destination_of_supply": "TN", "gst_no": "22AAAAA0000A1Z5", "gst_treatment": "business_gst", "is_pre_gst": false, "pricebook_id": 460000000038090, "is_reverse_charge_applied": true, "unused_credits_payable_amount": 187, "status": "open", "bill_number": "00454", "date": "2013-09-11", "due_date": "2013-09-26", "payment_terms": 0, "payment_terms_label": "Due on Receipt", "reference_number": "4321133", "due_in_days": 0, "currency_id": "460000000000099", "currency_code": "INR", "documents": [ {...} ], "price_precision": 2, "exchange_rate": 1.23, "custom_fields": [ {...} ], "is_item_level_tax_calc": false, "is_inclusive_tax": false, "line_items": [ { "line_item_id": "460000000067009", "item_id": "460000000054135", "account_id": "460000000000403", "account_name": "Other Expenses", "image_document_id": 460000000038067, "warehouse_id": 460000000038089, "reverse_charge_tax_id": 460000000038056, "reverse_charge_tax_name": "inter", "reverse_charge_tax_percentage": 10, "reverse_charge_tax_amount": 100, "bcy_rate": 40, "rate": 10, "tags": [ {...} ], "quantity": 1, "tax_id": "460000000027005", "tax_name": "VAT (12.5%)", "tax_type": "tax", "tax_percentage": 0, "item_total": 40, "item_total_inclusive_of_tax": 40, "item_order": 1, "unit": "kgs", "hsn_or_sac": 80540, "is_billable": false, "item_custom_fields": [ {...} ] } ], "sub_total": 40, "tax_total": 0, "total": 40, "payment_made": 0, "vendor_credits_applied": 0, "is_line_item_invoiced": false, "purchaseorders": [ { "purchaseorder_id": "460000000068231", "purchaseorder_number": "PO-0001", "purchaseorder_date": "19 Jan 2017", "purchaseorder_status": "billed" } ], "taxes": [ { "tax_name": "VAT (12.5%)", "tax_amount": 1.25 } ], "acquisition_vat_summary": [ { "tax_name": "VAT (12.5%)", "tax_amount": 1.25 } ], "reverse_charge_vat_summary": [ { "tax_name": "VAT (12.5%)", "tax_amount": 1.25 } ], "balance": 40, "billing_address": { "street2": "Suite 310" }, "payments": [ { "payment_id": "460000000042059", "bill_id": "460000000098765", "bill_payment_id": "460000000042061", "payment_mode": "Cash", "date": "2013-09-11", "reference_number": "4321133", "exchange_rate": 1.23, "amount": 31.25, "paid_through_account_id": "460000000000358", "paid_through_account_name": "Undeposited Funds", "is_single_bill_payment": true, "is_paid_via_print_check": false, "check_details": [ {...} ], "is_ach_payment": false } ], "vendor_credits": [ { "vendor_credit_id": "4600000053221", "vendor_credit_bill_id": "4600000211221", "vendor_credit_number": "DN-001", "date": "2013-09-11", "amount": 31.25 } ], "created_time": "2013-09-11T17:18:32+0530", "created_by_id": "4600000053001", "last_modified_time": "2013-09-11T17:18:32+0530", "notes": "Thanks for your business.", "terms": "Terms and conditions apply.", "open_purchaseorders_count": 1 } }
ARGUMENTS
|
vendor_id
Required
ID of the vendor the bill has to be created.
vat_treatment
UK Edition only
Optional
(Optional) VAT treatment for the bill.
VAT treatment denotes the location of the vendor, if the vendor resides
in UK then the VAT treatment is
uk. If the vendor is in an EU country & if he is VAT registered then his VAT treatment is eu_vat_registered, if he resides in EU & if he is not VAT registered then his VAT treatment is eu_vat_not_registered and if he resides outside the EU then his VAT treatment is non_eu.
is_update_customer
Optional
Check if cutomer should be updated
purchaseorder_ids
Optional
bill_number
Required
The bill number.
documents
Optional
document_id
Optional
ID of the Document
file_name
Optional
Name of the file
source_of_supply
India Edition only
Optional
Place from where the goods/services are supplied. (If not given,
place of contact given for the contact will be taken)
destination_of_supply
India Edition only
Optional
Place where the goods/services are supplied to. (If not given, organisation's home state will be taken)
gst_treatment
India Edition only
Optional
Choose whether the contact is GST registered/unregistered/consumer/overseas. Allowed values are
business_gst , business_none , overseas , consumer .
gst_no
India Edition only
Optional
15 digit GST identification number of the vendor.
pricebook_id
Optional
Enter ID of the price book.
reference_number
Optional
Reference Number of the entity
date
Optional
The date the bill was created. [yyyy-mm-dd]
due_date
Optional
Date bill is due.
payment_terms
Optional
Number Referring to Payment Terms
payment_terms_label
Optional
Label of the Payment Terms
recurring_bill_id
Optional
ID of the Recurring Bill
exchange_rate
Optional
Exchange rate of the currency.
is_item_level_tax_calc
Optional
Check if Item Level Tax Calculation is present
is_inclusive_tax
Not applicable for US edition.
Optional
Used to specify whether the line item rates are inclusive or exclusive of tax.
custom_fields
Optional
index
Optional
Index of the custom field
value
Optional
Value of the Custom Field
line_items
Optional
Line items of a bill.
purchaseorder_item_id
Optional
ID of the Item in Purchase Order
line_item_id
Optional
ID of the Line Item
item_id
Optional
ID of the Item
name
Optional
account_id
Optional
ID of the account associated with the line item.
rate
Optional
Rate of the line item.
hsn_or_sac
India Edition only
Optional
Add HSN/SAC code for your goods/services
reverse_charge_tax_id
India Edition only
Optional
Reverse charge tax ID
warehouse_id
India Edition only
Optional
Warehoude ID
quantity
Optional
Quantity of the line item.
tax_id
Not applicable for the US Edition.
Optional
ID of the tax or tax group applied to the line item.
tax_exemption_id
India, AU and CA Editions Only
Optional
ID of the Tax Exemption Applied
tax_exemption_code
India, AU and CA Editions Only
Optional
Code of the Tax Exemption Applied
item_order
Optional
product_type
Allowed for EU and UK Edition only
Optional
Type of the bill. This denotes whether
the bill line item is to be treated as a goods or service purchase.
This only need to be specified in case purchase order is not enabled.
Allowed Values:
digital_service, goods and service.
hsn_or_sac
India Edition only
Optional
Add HSN/SAC code for your goods/services
acquisition_vat_id
UK Edition only
Optional
(Optional) This is the ID of the tax applied in case this is an EU - goods purchase and acquisition VAT needs to be reported.
reverse_charge_vat_id
UK Edition only
Optional
(Optional) This is the ID of the tax
applied in case this is a non UK - service purchase and reverse charge
VAT needs to be reported.
unit
Optional
Unit of the Item
tags
Optional
is_billable
Optional
Check if entity is Billable
project_id
Optional
ID of the Project
customer_id
Optional
ID of the Customer
item_custom_fields
Optional
custom_field_id
Optional
index
Optional
Index of the custom field
value
Optional
Value of the Custom Field
label
Optional
Label of the Custom Field
serial_numbers
Optional
taxes
Optional
tax_id
Not applicable for the US Edition.
Optional
ID of the tax or tax group applied to the line item.
tax_name
Optional
Name of the Tax
tax_amount
Optional
Amount of Tax in the Bill
notes
Optional
Notes for the Bill
terms
Optional
Terms and Conditions for the Bill
approvers
Optional
approver_id
Optional
ID of the Approver
order
Optional
Order of the Approver
|
Query Params
|
attachment
Optional
File to attach. Allowed Extensions:
gif, png, jpeg, jpg, bmp and pdf. |
List bills
List all bills with pagination.
GET /bills
Request Example
$ curl https://books.zoho.com/api/v3/bills?organization_id=10234695 -H "Authorization: Zoho-authtoken ba4604e8e433g9c892e360d53463oec5" -H "Content-Type: application/json;charset=UTF-8"
Response Example
HTTP/1.1 200 OK Content-Type:application/json;charset=UTF-8 { "code": 0, "message": "success", "bills": [ { "bills": [ { "bill_id": "460000000098765", "vendor_id": "460000000038029", "status": "open", "bill_number": "00454", "reference_number": "4321133", "date": "2013-09-11", "due_date": "2013-09-26", "currency_id": "460000000000099", "currency_code": "INR", "price_precision": 2, "exchange_rate": 1.23, "total": 40, "balance": 40, "created_time": "2013-09-11T17:18:32+0530", "last_modified_time": "2013-09-11T17:18:32+0530", "has_attachment": false } ], "page_context": { "page": 1, "per_page": 200, "has_more_page": false, "report_name": "Bills", "applied_filter": "Status.All", "sort_order": "D" } }, {...}, {...} ] }
Query Params
|
bill_number
Optional
Search bills by bill number. Variants:
bill_number_startswith and bill_number_contains
reference_number
Optional
Search bills by reference_number number. Variants:
reference_number_startswith and reference_number_contains
date
Optional
Search bills by bill date. Variants:
date_start, date_end, date_before and date.after
status
Optional
Search bills by bill status. Allowed Values:
paid, open, overdue, void and partially_paid
description
Optional
Search bills by description. Variants:
description_startswith and description_contains
vendor_name
Optional
Search bills by vendor name. Variants:
vendor_name_startswith and vendor_name_contains
total
Optional
Search bills by bill total. Variants:
total_less_than, total_less_equals, total_greater_than and total_greater_equals
vendor_id
Optional
Search bills by Vendor ID
item_id
Optional
Search bills by Item ID
recurring_bill_id
Optional
Search bills by Recurring Bill ID
purchaseorder_id
Optional
Search bills by Purchase Order ID
last_modified_time
Optional
Search bills by Last Modified Time
filter_by
Optional
Filter bills by any status. Allowed Values:
Status.All, Status.PartiallyPaid, Status.Paid, Status.Overdue, Status.Void and Status.Open.
search_text
Optional
Search bills by bill number or reference number or vendor name.
sort_column
Optional
Sort bills. Allowed Values:
vendor_name, bill_number, date, due_date, total, balance and created_time. |
Get a bill
Get the details of a bill.
GET /bills/{bill_id}
Request Example
$ curl https://books.zoho.com/api/v3/bills/{bill_id}?organization_id=10234695 -H "Authorization: Zoho-authtoken ba4604e8e433g9c892e360d53463oec5" -H "Content-Type: application/json;charset=UTF-8"
Response Example
HTTP/1.1 200 OK Content-Type:application/json;charset=UTF-8 { "code": 0, "message": "success", "bill": { "bill_id": "460000000098765", "purchaseorder_ids": [ 460000000068231, 460000000068233 ], "vendor_id": "460000000038029", "source_of_supply": "AP", "destination_of_supply": "TN", "gst_no": "22AAAAA0000A1Z5", "gst_treatment": "business_gst", "is_pre_gst": false, "pricebook_id": 460000000038090, "is_reverse_charge_applied": true, "unused_credits_payable_amount": 187, "status": "open", "bill_number": "00454", "date": "2013-09-11", "due_date": "2013-09-26", "payment_terms": 0, "payment_terms_label": "Due on Receipt", "reference_number": "4321133", "due_in_days": 0, "currency_id": "460000000000099", "currency_code": "INR", "documents": [ {...} ], "price_precision": 2, "exchange_rate": 1.23, "custom_fields": [ {...} ], "is_item_level_tax_calc": false, "is_inclusive_tax": false, "line_items": [ { "line_item_id": "460000000067009", "item_id": "460000000054135", "account_id": "460000000000403", "account_name": "Other Expenses", "image_document_id": 460000000038067, "warehouse_id": 460000000038089, "reverse_charge_tax_id": 460000000038056, "reverse_charge_tax_name": "inter", "reverse_charge_tax_percentage": 10, "reverse_charge_tax_amount": 100, "bcy_rate": 40, "rate": 10, "tags": [ {...} ], "quantity": 1, "tax_id": "460000000027005", "tax_name": "VAT (12.5%)", "tax_type": "tax", "tax_percentage": 0, "item_total": 40, "item_total_inclusive_of_tax": 40, "item_order": 1, "unit": "kgs", "hsn_or_sac": 80540, "is_billable": false, "item_custom_fields": [ {...} ] } ], "sub_total": 40, "tax_total": 0, "total": 40, "payment_made": 0, "vendor_credits_applied": 0, "is_line_item_invoiced": false, "purchaseorders": [ { "purchaseorder_id": "460000000068231", "purchaseorder_number": "PO-0001", "purchaseorder_date": "19 Jan 2017", "purchaseorder_status": "billed" } ], "taxes": [ { "tax_name": "VAT (12.5%)", "tax_amount": 1.25 } ], "acquisition_vat_summary": [ { "tax_name": "VAT (12.5%)", "tax_amount": 1.25 } ], "reverse_charge_vat_summary": [ { "tax_name": "VAT (12.5%)", "tax_amount": 1.25 } ], "balance": 40, "billing_address": { "street2": "Suite 310" }, "payments": [ { "payment_id": "460000000042059", "bill_id": "460000000098765", "bill_payment_id": "460000000042061", "payment_mode": "Cash", "date": "2013-09-11", "reference_number": "4321133", "exchange_rate": 1.23, "amount": 31.25, "paid_through_account_id": "460000000000358", "paid_through_account_name": "Undeposited Funds", "is_single_bill_payment": true, "is_paid_via_print_check": false, "check_details": [ {...} ], "is_ach_payment": false } ], "vendor_credits": [ { "vendor_credit_id": "4600000053221", "vendor_credit_bill_id": "4600000211221", "vendor_credit_number": "DN-001", "date": "2013-09-11", "amount": 31.25 } ], "created_time": "2013-09-11T17:18:32+0530", "created_by_id": "4600000053001", "last_modified_time": "2013-09-11T17:18:32+0530", "notes": "Thanks for your business.", "terms": "Terms and conditions apply.", "open_purchaseorders_count": 1 } }
Delete a bill
Delete an existing bill. Bills which have payments applied cannot be deleted.
DELETE /bills/{bill_id}
Request Example
$ curl https://books.zoho.com/api/v3/bills/{bill_id}?organization_id=10234695 -H "Authorization: Zoho-authtoken ba4604e8e433g9c892e360d53463oec5" -H "Content-Type: application/json;charset=UTF-8"
Response Example
HTTP/1.1 200 OK Content-Type:application/json;charset=UTF-8 { "code": 0, "message": "The bill has been deleted." }
Void a bill
Mark a bill status as void.
POST /bills/{bill_id}/status/void
Request Example
$ curl https://books.zoho.com/api/v3/bills/{bill_id}/status/void?organization_id=10234695 -H "Authorization: Zoho-authtoken ba4604e8e433g9c892e360d53463oec5" -H "Content-Type: application/json;charset=UTF-8"
Response Example
HTTP/1.1 201 Created Content-Type:application/json;charset=UTF-8 { "code": 0, "message": "The bill has been marked as void." }
Mark a bill as open
Mark a void bill as open.
POST /bills/{bill_id}/status/open
Request Example
$ curl https://books.zoho.com/api/v3/bills/{bill_id}/status/open?organization_id=10234695 -H "Authorization: Zoho-authtoken ba4604e8e433g9c892e360d53463oec5" -H "Content-Type: application/json;charset=UTF-8"
Response Example
HTTP/1.1 201 Created Content-Type:application/json;charset=UTF-8 { "code": 0, "message": "The status of the bill has been chaged to open." }
Update billing address
Updates the billing address for this bill.
PUT /bills/{bill_id}/address/billing
Request Example
$ curl https://books.zoho.com/api/v3/bills/{bill_id}/address/billing?organization_id=10234695 -H "Authorization: Zoho-authtoken ba4604e8e433g9c892e360d53463oec5" -H "Content-Type: application/json;charset=UTF-8" -d '{ "is_update_customer": false }
Response Example
HTTP/1.1 200 OK Content-Type:application/json;charset=UTF-8 { "code": 0, "message": "Billing address updated.", "billing_address": { "street2": "Suite 310" } }
ARGUMENTS
|
address
Optional
Address involved in the Bill
city
Optional
City in the Address
state
Optional
State involved in the Address
zip
Optional
ZIP Code involved in the Address
country
Optional
Country Involved in the Address
fax
Optional
Fax of the Vendor
attention
Optional
is_update_customer
Optional
Check if cutomer should be updated
|
List bill payments
Get the list of payments made for a bill.
GET /bills/{bill_id}/payments
Request Example
$ curl https://books.zoho.com/api/v3/bills/{bill_id}/payments?organization_id=10234695 -H "Authorization: Zoho-authtoken ba4604e8e433g9c892e360d53463oec5" -H "Content-Type: application/json;charset=UTF-8"
Response Example
HTTP/1.1 200 OK Content-Type:application/json;charset=UTF-8 { "code": 0, "message": "success", "payments": [ { "payment_id": "460000000042059", "bill_id": "460000000098765", "bill_payment_id": "460000000042061", "vendor_id": "460000000038029", "payment_mode": "Cash", "date": "2013-09-11", "reference_number": "4321133", "exchange_rate": 1.23, "amount": 31.25, "paid_through": "Petty Cash", "is_single_bill_payment": true }, {...}, {...} ] }
Apply credits
Apply the vendor credits from excess vendor payments to a bill. Multiple credits can be applied at once.
POST /bills/{bill_id}/credits
Request Example
$ curl https://books.zoho.com/api/v3/bills/{bill_id}/credits?organization_id=10234695 -H "Authorization: Zoho-authtoken ba4604e8e433g9c892e360d53463oec5" -H "Content-Type: application/json;charset=UTF-8" -d '{ "bill_payments": [ { "payment_id": "460000000042059", "amount_applied": 31.25 } ], "apply_vendor_credits": [ { "vendor_credit_id": "4600000053221", "amount_applied": 31.25 } ] }
Response Example
HTTP/1.1 201 Created Content-Type:application/json;charset=UTF-8 { "code": 0, "message": "Credits have been applied to the bill(s).\"" }
ARGUMENTS
|
bill_payments
Optional
payment_id
Optional
ID of the Payment
amount_applied
Optional
Amount applied to the bill.
apply_vendor_credits
Optional
vendor_credit_id
Optional
ID of the Vendor Credit
amount_applied
Optional
Amount applied to the bill.
|
Delete a payment
Delete a payment made to a bill.
DELETE /bills/{bill_id}/payments/{bill_payment_id}
Request Example
$ curl https://books.zoho.com/api/v3/bills/{bill_id}/payments/{bill_payment_id}?organization_id=10234695 -H "Authorization: Zoho-authtoken ba4604e8e433g9c892e360d53463oec5" -H "Content-Type: application/json;charset=UTF-8"
Response Example
HTTP/1.1 200 OK Content-Type:application/json;charset=UTF-8 { "code": 0, "message": "The payment has been deleted." }
Get a bill attachment
Returns the file attached to the bill.
GET /bills/{bill_id}/attachment
Request Example
$ curl https://books.zoho.com/api/v3/bills/{bill_id}/attachment?organization_id=10234695 -H "Authorization: Zoho-authtoken ba4604e8e433g9c892e360d53463oec5" -H "Content-Type: application/json;charset=UTF-8"
Response Example
HTTP/1.1 200 OK Content-Type:application/json;charset=UTF-8 { "code": 0, "message": "success" }
Query Params
|
preview
Optional
Get the thumbnail of the attachment.
|
Add attachment to a bill
Attach a file to a bill.
POST /bills/{bill_id}/attachment
Request Example
$ curl https://books.zoho.com/api/v3/bills/{bill_id}/attachment?organization_id=10234695 -H "Authorization: Zoho-authtoken ba4604e8e433g9c892e360d53463oec5" -H "Content-Type: application/json;charset=UTF-8"
Response Example
HTTP/1.1 201 Created Content-Type:application/json;charset=UTF-8 { "code": 0, "message": "The document has been attached." }
Query Params
|
attachment
Optional
File to attach. Allowed Extensions:
gif, png, jpeg, jpg, bmp and pdf. |
Delete an attachment
Delete the file attached to a bill.
DELETE /bills/{bill_id}/attachment
Request Example
$ curl https://books.zoho.com/api/v3/bills/{bill_id}/attachment?organization_id=10234695 -H "Authorization: Zoho-authtoken ba4604e8e433g9c892e360d53463oec5" -H "Content-Type: application/json;charset=UTF-8"
Response Example
HTTP/1.1 200 OK Content-Type:application/json;charset=UTF-8 { "code": 0, "message": "The attachment has been deleted." }
List bill comments & history
Get the complete history and comments of a bill.
GET /bills/{bill_id}/comments
Request Example
$ curl https://books.zoho.com/api/v3/bills/{bill_id}/comments?organization_id=10234695 -H "Authorization: Zoho-authtoken ba4604e8e433g9c892e360d53463oec5" -H "Content-Type: application/json;charset=UTF-8"
Response Example
HTTP/1.1 200 OK Content-Type:application/json;charset=UTF-8 { "code": 0, "message": "success", "comments": [ { "comment_id": "460000000069037", "bill_id": "460000000098765", "commented_by_id": "460000000053001", "commented_by": "John Roberts", "comment_type": "internal", "date": "17 Nov 2016", "date_description": "few seconds ago", "time": "12:09 PM", "operation_type": "Added", "transaction_id": "460000000068015", "transaction_type": "bill_payment" }, {...}, {...} ] }
Add comment
Add a comment for a bill.
POST /bills/{bill_id}/comments
Request Example
$ curl https://books.zoho.com/api/v3/bills/{bill_id}/comments?organization_id=10234695 -H "Authorization: Zoho-authtoken ba4604e8e433g9c892e360d53463oec5" -H "Content-Type: application/json;charset=UTF-8" -d '{}
Response Example
HTTP/1.1 201 Created Content-Type:application/json;charset=UTF-8 { "code": 0, "message": "Comments added.", "comment": { "comment_id": "460000000069037", "bill_id": "460000000098765", "commented_by_id": "460000000053001", "commented_by": "John Roberts", "comment_type": "internal", "date": "17 Nov 2016", "date_description": "few seconds ago", "time": "12:09 PM" } }
ARGUMENTS
|
description
Required
Description of the line item.
|
Delete a comment
Delete a bill comment.
DELETE /bills/{bill_id}/comments/{comment_id}
Request Example
$ curl https://books.zoho.com/api/v3/bills/{bill_id}/comments/{comment_id}?organization_id=10234695 -H "Authorization: Zoho-authtoken ba4604e8e433g9c892e360d53463oec5" -H "Content-Type: application/json;charset=UTF-8"
Response Example
HTTP/1.1 200 OK Content-Type:application/json;charset=UTF-8 { "code": 0, "message": "The comment has been deleted." }
Vendor-Credits
Vendor credits are credits that you receive from your vendor, and is treated as an equivalent of physical cash that the vendor owes you. This helps you track the money you’re owed until it is either paid by said vendor at a later date i.e refunded, or subtracted from any future bill amount due to that vendor.
Example
{ "vendor_credit": { "vendor_credit_id": "3000000002075", "vendor_credit_number": "DN-00002", "date": "2014-08-28", "status": "open", "vendor_id": "460000000020029", "vendor_name": "Bowman and Co", "currency_id": "3000000000083", "currency_code": "USD", "exchange_rate": 1, "price_precision": 2, "is_inclusive_tax": false, "line_items": [ { "item_id": "460000000020071", "line_item_id": "460000000020077", "account_id": "460000000020097", "name": "Premium Plan - Web hosting", "reverse_charge_tax_id": 460000000057089, "item_order": 0, "quantity": 1, "unit": "Nos", "rate": 30, "tags": [ {} ], "item_custom_fields": [ {} ], "serial_numbers": [ {} ] } ], "acquisition_vat_summary": [ { "tax": {} } ], "reverse_charge_vat_summary": [ { "tax": {} } ], "documents": [ {} ], "custom_fields": [ {} ], "sub_total": 30, "total": 30, "total_credits_used": 0, "total_refunded_amount": 0, "balance": 30, "comments": [ { "comment_id": "3000000002089", "vendor_credit_id": "3000000002075", "commented_by_id": "3000000000741", "commented_by": "rajdeep.a", "comment_type": "system", "date": "2014-08-28", "date_description": "32 minutes ago", "time": "10:52 PM", "operation_type": "Added", "transaction_id": "460000000069087", "transaction_type": "vendor_credit" } ], "vendor_credit_refunds": [ { "vendor_credit_refund_id": "3000000003151", "vendor_credit_id": "3000000002075", "date": "2014-08-28", "refund_mode": "cash", "amount_bcy": 13, "amount_fcy": 13 } ], "bills_credited": [ { "bill_id": "460000000057075", "date": "2014-08-28", "amount": 13 } ], "created_time": "2014-08-28T22:53:31-0700", "last_modified_time": "2014-08-28T22:53:31-0700" } }
Attribute
|
vendor_credit
object
vendor_credit_id
string
ID of the Vendor Credit
vendor_credit_number
string
Number of the Vendor Credit
date
string
The date the vendor credit is created. [yyyy-mm-dd]
status
string
reference_number
string
Reference number for the refund recorded.
vendor_id
string
ID of the vendor the vendor credit associated with the Vendor Credit
vendor_name
string
Name of the Vendor Associated with the Vendor Credit
currency_id
string
ID of the Currency Involved in the Vendor Credit
currency_code
string
Code of the Currency Involved in the Vendor Credit
exchange_rate
double
Exchange rate of the currency.
price_precision
integer
vat_treatment
UK Edition only
string
VAT treatment for the invoice. VAT
treatment denotes the location of the customer, if the customer resides
in UK then the VAT treatment is
uk. If the customer is in a EU country & if he is VAT registered then his VAT treatment is eu_vat_registered, if he resides in EU & if he is not VAT registered then his VAT treatment is eu_vat_not_registered and if he resides outside the EU then his VAT treatment is non_eu.
filed_in_vat_return_id
UK Edition Only
string
ID of the VAT Return the Vendor Credit is filed in
filed_in_vat_return_name
UK Edition Only
string
Name of the VAT Return the Vendor Credit is filed in
filed_in_vat_return_type
UK Edition Only
string
Type of the VAT Return the Vendor Credit is filed in
is_inclusive_tax
Not applicable for US edition.
boolean
Used to specify whether the line item rates are inclusive or exclusive of tax.
line_items
list
Line items of a vendor credit.
item_id
string
ID of the item.
line_item_id
string
ID of the Line Item
account_id
string
ID of the account, the line item is associated with
name
string
Name of the line item.
hsn_or_sac
India Edition Only
string
HSN Code
reverse_charge_tax_id
India Edition only.
string
ID of the reverse charge tax
warehouse_id
string
ID of the warehouse
item_order
integer
Order of the line item
quantity
double
Quantity of the line item.
unit
string
Unit of the line item e.g. kgs, Nos.
rate
double
Rate of the line item.
tax_id
string
ID of the Tax associated with the Vendor Credit
tags
list
item_custom_fields
list
custom_field_id
long
ID of the Custom Field
label
string
Label of the Custom Field
value
string
Value of the Custom Field
index
integer
Index of the Custom Field
serial_numbers
list
acquisition_vat_summary
UK and EU Editions Only
list
Summary of the VAT Acquistion
tax
object
tax_name
string
Name of the Tax
tax_amount
double
Amount of the Tax
acquisition_vat_total
UK and EU Editions Only
double
Total of the VAT Acquistion
reverse_charge_vat_summary
UK and EU Editions Only
list
Summary of the Reverse Charge
tax
object
tax_name
string
Name of the Tax
tax_amount
double
Amount of the Tax
reverse_charge_vat_total
UK and EU Editions Only
double
Total of the Reverse Charge
documents
list
document_id
long
ID of the Document
file_name
string
Name of the file
custom_fields
list
custom_field_id
long
ID of the Custom Field
label
string
Label of the Custom Field
value
string
Value of the Custom Field
index
integer
Index of the Custom Field
sub_total
double
total
double
total_credits_used
double
total_refunded_amount
double
balance
double
Balance in the Vendor Credit
notes
string
Notes for the Vendor Credit
comments
list
comment_id
string
ID of the Comment
vendor_credit_id
string
ID of the Vendor Credit
description
string
Description of the line item.
commented_by_id
string
ID of the User who caused the comment
commented_by
string
Name of the User who caused the comment
comment_type
string
Type of the comment
date
string
The date the vendor credit is created. [yyyy-mm-dd]
date_description
string
Description of the Date of the Comment
time
string
Time of the Comment
operation_type
string
Type of operation that caused the Comment
transaction_id
string
Transaction ID that caused the Comment
transaction_type
string
Transaction Type that caused the Comment
vendor_credit_refunds
list
vendor_credit_refund_id
string
ID of the Vendor Credit Refund
vendor_credit_id
string
ID of the Vendor Credit
date
string
The date the vendor credit is created. [yyyy-mm-dd]
refund_mode
string
Mode of Refund
reference_number
string
Reference number for the refund recorded.
description
string
Description of the line item.
amount_bcy
double
Refund Amount in Base Currency
amount_fcy
double
Refund Amount in Foreign Currency
filed_in_vat_return_id
UK Edition Only
string
ID of the VAT Return the Vendor Credit is filed in
filed_in_vat_return_name
UK Edition Only
string
Name of the VAT Return the Vendor Credit is filed in
filed_in_vat_return_type
UK Edition Only
string
Type of the VAT Return the Vendor Credit is filed in
bills_credited
list
bill_id
string
ID of the Bill Credited
vendor_credit_bill_id
string
ID of the Vendor Credited Bill ID
date
string
Date of the Bill Credit
bill_number
string
Number of the Bill Credited
amount
double
Amount that is credited in the bill
created_time
string
Time of Vendor Credit Creation
last_modified_time
string
Last Modified Time of Vendor Credit
|
Create a vendor credit
Create a vendor credit for a vendor.
POST /vendorcredits
Request Example
$ curl https://books.zoho.com/api/v3/vendorcredits?organization_id=10234695 -H "Authorization: Zoho-authtoken ba4604e8e433g9c892e360d53463oec5" -H "Content-Type: application/json;charset=UTF-8" -d '{ "vendor_id": "460000000020029", "vendor_credit_number": "DN-00002", "gst_treatment": "business_gst", "gst_no": "22AAAAA0000A1Z5", "source_of_supply": "TN", "destination_of_supply": "TN", "is_update_customer": false, "date": "2014-08-28", "exchange_rate": 1, "is_inclusive_tax": false, "line_items": [ { "item_id": "460000000020071", "line_item_id": "460000000020077", "account_id": "460000000020097", "name": "Premium Plan - Web hosting", "reverse_charge_tax_id": 460000000057089, "item_order": 0, "quantity": 1, "unit": "Nos", "rate": 30, "tags": [ {} ], "item_custom_fields": [ {} ], "serial_numbers": [ {} ] } ], "documents": [ {} ], "custom_fields": [ {} ] }
Response Example
HTTP/1.1 201 Created Content-Type:application/json;charset=UTF-8 { "code": 0, "message": "Vendor credit has been created.", "vendor_credit": { "vendor_credit_id": "3000000002075", "vendor_credit_number": "DN-00002", "date": "2014-08-28", "source_of_supply": "TN", "destination_of_supply": "TN", "gst_no": "22AAAAA0000A1Z5", "gst_treatment": "business_gst", "is_reverse_charge_applied": true, "status": "open", "vendor_id": "460000000020029", "vendor_name": "Bowman and Co", "currency_id": "3000000000083", "currency_code": "USD", "exchange_rate": 1, "price_precision": 2, "is_inclusive_tax": false, "line_items": { "item_id": "460000000020071", "line_item_id": "460000000020077", "account_id": "460000000020097", "reverse_charge_tax_id": 460000000057089, "reverse_charge_tax_name": "intra", "reverse_charge_tax_percentage": 10, "reverse_charge_tax_amount": 100, "account_name": "IT and Internet Expenses", "name": "Premium Plan - Web hosting", "item_order": 0, "quantity": 1, "unit": "Nos", "bcy_rate": 30, "rate": 30, "item_total": 30, "item_total_inclusive_of_tax": 30, "tags": [ {...} ], "item_custom_fields": [ {...} ] }, "acquisition_vat_summary": [ { "tax": {...} } ], "reverse_charge_vat_summary": [ { "tax": {...} } ], "documents": [ {...} ], "custom_fields": [ {...} ], "sub_total": 30, "total": 30, "total_credits_used": 0, "total_refunded_amount": 0, "balance": 30, "comments": [ { "comment_id": "3000000002089", "vendor_credit_id": "3000000002075", "commented_by_id": "3000000000741", "commented_by": "rajdeep.a", "comment_type": "system", "date": "2014-08-28", "date_description": "32 minutes ago", "time": "10:52 PM", "operation_type": "Added", "transaction_id": "460000000069087", "transaction_type": "vendor_credit" } ], "vendor_credit_refunds": [ { "vendor_credit_refund_id": "3000000003151", "vendor_credit_id": "3000000002075", "date": "2014-08-28", "refund_mode": "cash", "amount_bcy": 13, "amount_fcy": 13 } ], "bills_credited": [ { "bill_id": "460000000057075", "date": "2014-08-28", "amount": 13 } ], "created_time": "2014-08-28T22:53:31-0700", "last_modified_time": "2014-08-28T22:53:31-0700" } }
ARGUMENTS
|
vendor_id
Required
ID of the vendor the vendor credit associated with the Vendor Credit
vat_treatment
UK Edition only
Optional
VAT treatment for the invoice. VAT
treatment denotes the location of the customer, if the customer resides
in UK then the VAT treatment is
uk. If the customer is in a EU country & if he is VAT registered then his VAT treatment is eu_vat_registered, if he resides in EU & if he is not VAT registered then his VAT treatment is eu_vat_not_registered and if he resides outside the EU then his VAT treatment is non_eu.
vendor_credit_number
Optional
Mandatory if auto number generation is disabled.
gst_treatment
India Edition only.
Optional
Choose whether the contact is GST registered/unregistered/consumer/overseas. Allowed values are
business_gst , business_none , overseas , consumer .
gst_no
India Edition only.
Optional
15 digit GST identification number of the vendor.
source_of_supply
India Edition only.
Optional
Place from where the goods/services are supplied. (If not given,
place of contact given for the contact will be taken)
destination_of_supply
India Edition only.
Optional
Place where the goods/services are supplied to. (If not given, organisation's home state will be taken)
pricebook_id
Optional
ID of the pricebook
reference_number
Optional
Reference number for the refund recorded.
is_update_customer
Optional
Check if customer should be updated
date
Optional
The date the vendor credit is created. [yyyy-mm-dd]
exchange_rate
Optional
Exchange rate of the currency.
is_inclusive_tax
Not applicable for US edition.
Optional
Used to specify whether the line item rates are inclusive or exclusive of tax.
line_items
Optional
Line items of a vendor credit.
item_id
Optional
ID of the item.
line_item_id
Optional
ID of the Line Item
account_id
Optional
ID of the account, the line item is associated with
name
Optional
Name of the line item.
hsn_or_sac
India Edition Only
Optional
HSN Code
reverse_charge_tax_id
India Edition only.
Optional
ID of the reverse charge tax
warehouse_id
Optional
ID of the warehouse
item_order
Optional
Order of the line item
quantity
Optional
Quantity of the line item.
unit
Optional
Unit of the line item e.g. kgs, Nos.
rate
Optional
Rate of the line item.
tax_id
Optional
ID of the Tax associated with the Vendor Credit
tags
Optional
item_custom_fields
Optional
custom_field_id
Optional
ID of the Custom Field
label
Optional
Label of the Custom Field
value
Optional
Value of the Custom Field
index
Optional
Index of the Custom Field
serial_numbers
Optional
notes
Optional
Notes for the Vendor Credit
documents
Optional
document_id
Optional
ID of the Document
file_name
Optional
Name of the file
custom_fields
Optional
custom_field_id
Optional
ID of the Custom Field
label
Optional
Label of the Custom Field
value
Optional
Value of the Custom Field
index
Optional
Index of the Custom Field
|
Query Params
|
ignore_auto_number_generation
Optional
Ignore auto number generation for this vendor credit only. On enabling this option vendor credit number is mandatory.
bill_id
Optional
Bill Associated with the Vendor Credit
|
Update vendor credit
Update an existing vendor credit.
PUT /vendorcredits/{vendor_credit_id}
Request Example
$ curl https://books.zoho.com/api/v3/vendorcredits/{vendor_credit_id}?organization_id=10234695 -H "Authorization: Zoho-authtoken ba4604e8e433g9c892e360d53463oec5" -H "Content-Type: application/json;charset=UTF-8" -d '{ "vendor_id": "460000000020029", "vendor_credit_number": "DN-00002", "gst_treatment": "business_gst", "gst_no": "22AAAAA0000A1Z5", "source_of_supply": "TN", "destination_of_supply": "TN", "is_update_customer": false, "date": "2014-08-28", "exchange_rate": 1, "is_inclusive_tax": false, "line_items": [ { "item_id": "460000000020071", "line_item_id": "460000000020077", "account_id": "460000000020097", "name": "Premium Plan - Web hosting", "reverse_charge_tax_id": 460000000057089, "item_order": 0, "quantity": 1, "unit": "Nos", "rate": 30, "tags": [ {} ], "item_custom_fields": [ {} ], "serial_numbers": [ {} ] } ], "documents": [ {} ], "custom_fields": [ {} ] }
Response Example
HTTP/1.1 200 OK Content-Type:application/json;charset=UTF-8 { "code": 0, "message": "Vendor credit information has been updated.", "vendor_credit": { "vendor_credit_id": "3000000002075", "vendor_credit_number": "DN-00002", "date": "2014-08-28", "source_of_supply": "TN", "destination_of_supply": "TN", "gst_no": "22AAAAA0000A1Z5", "gst_treatment": "business_gst", "is_reverse_charge_applied": true, "status": "open", "vendor_id": "460000000020029", "vendor_name": "Bowman and Co", "currency_id": "3000000000083", "currency_code": "USD", "exchange_rate": 1, "price_precision": 2, "taxes": [ {...} ], "is_inclusive_tax": false, "line_items": { "item_id": "460000000020071", "line_item_id": "460000000020077", "account_id": "460000000020097", "reverse_charge_tax_id": 460000000057089, "reverse_charge_tax_name": "intra", "reverse_charge_tax_percentage": 10, "reverse_charge_tax_amount": 100, "account_name": "IT and Internet Expenses", "name": "Premium Plan - Web hosting", "item_order": 0, "quantity": 1, "unit": "Nos", "bcy_rate": 30, "rate": 30, "item_total": 30, "item_total_inclusive_of_tax": 30, "tags": [ {...} ], "item_custom_fields": [ {...} ] }, "acquisition_vat_summary": [ { "tax": {...} } ], "reverse_charge_vat_summary": [ { "tax": {...} } ], "documents": [ {...} ], "custom_fields": [ {...} ], "sub_total": 30, "total": 30, "total_credits_used": 0, "total_refunded_amount": 0, "balance": 30, "comments": [ { "comment_id": "3000000002089", "vendor_credit_id": "3000000002075", "commented_by_id": "3000000000741", "commented_by": "rajdeep.a", "comment_type": "system", "date": "2014-08-28", "date_description": "32 minutes ago", "time": "10:52 PM", "operation_type": "Added", "transaction_id": "460000000069087", "transaction_type": "vendor_credit" } ], "vendor_credit_refunds": [ { "vendor_credit_refund_id": "3000000003151", "vendor_credit_id": "3000000002075", "date": "2014-08-28", "refund_mode": "cash", "amount_bcy": 13, "amount_fcy": 13 } ], "bills_credited": [ { "bill_id": "460000000057075", "date": "2014-08-28", "amount": 13 } ], "created_time": "2014-08-28T22:53:31-0700", "last_modified_time": "2014-08-28T22:53:31-0700" } }
ARGUMENTS
|
vendor_id
Required
ID of the vendor the vendor credit associated with the Vendor Credit
vat_treatment
UK Edition only
Optional
VAT treatment for the invoice. VAT
treatment denotes the location of the customer, if the customer resides
in UK then the VAT treatment is
uk. If the customer is in a EU country & if he is VAT registered then his VAT treatment is eu_vat_registered, if he resides in EU & if he is not VAT registered then his VAT treatment is eu_vat_not_registered and if he resides outside the EU then his VAT treatment is non_eu.
vendor_credit_number
Optional
Mandatory if auto number generation is disabled.
gst_treatment
India Edition only.
Optional
Choose whether the contact is GST registered/unregistered/consumer/overseas. Allowed values are
business_gst , business_none , overseas , consumer .
gst_no
India Edition only.
Optional
15 digit GST identification number of the vendor.
source_of_supply
India Edition only.
Optional
Place from where the goods/services are supplied. (If not given,
place of contact given for the contact will be taken)
destination_of_supply
India Edition only.
Optional
Place where the goods/services are supplied to. (If not given, organisation's home state will be taken)
pricebook_id
Optional
ID of the pricebook
reference_number
Optional
Reference number for the refund recorded.
is_update_customer
Optional
Check if customer should be updated
date
Optional
The date the vendor credit is created. [yyyy-mm-dd]
exchange_rate
Optional
Exchange rate of the currency.
is_inclusive_tax
Not applicable for US edition.
Optional
Used to specify whether the line item rates are inclusive or exclusive of tax.
line_items
Optional
Line items of a vendor credit.
item_id
Optional
ID of the item.
line_item_id
Optional
ID of the Line Item
account_id
Optional
ID of the account, the line item is associated with
name
Optional
Name of the line item.
hsn_or_sac
India Edition Only
Optional
HSN Code
reverse_charge_tax_id
India Edition only.
Optional
ID of the reverse charge tax
warehouse_id
Optional
ID of the warehouse
item_order
Optional
Order of the line item
quantity
Optional
Quantity of the line item.
unit
Optional
Unit of the line item e.g. kgs, Nos.
rate
Optional
Rate of the line item.
tax_id
Optional
ID of the Tax associated with the Vendor Credit
tags
Optional
item_custom_fields
Optional
custom_field_id
Optional
ID of the Custom Field
label
Optional
Label of the Custom Field
value
Optional
Value of the Custom Field
index
Optional
Index of the Custom Field
serial_numbers
Optional
notes
Optional
Notes for the Vendor Credit
documents
Optional
document_id
Optional
ID of the Document
file_name
Optional
Name of the file
custom_fields
Optional
custom_field_id
Optional
ID of the Custom Field
label
Optional
Label of the Custom Field
value
Optional
Value of the Custom Field
index
Optional
Index of the Custom Field
|
List vendor credits
List vendor credits with pagination.
GET /vendorcredits
Request Example
$ curl https://books.zoho.com/api/v3/vendorcredits?organization_id=10234695 -H "Authorization: Zoho-authtoken ba4604e8e433g9c892e360d53463oec5" -H "Content-Type: application/json;charset=UTF-8"
Response Example
HTTP/1.1 200 OK Content-Type:application/json;charset=UTF-8 { "code": 0, "message": "success", "vendorcredits": [ { "vendor_credit_id": "3000000002075", "vendor_credit_number": "DN-00002", "status": "open", "date": "2014-08-28", "total": 30, "balance": 30, "vendor_id": "460000000020029", "vendor_name": "Bowman and Co", "currency_id": "3000000000083", "currency_code": "USD", "created_time": "2014-08-28T22:53:31-0700", "last_modified_time": "2014-08-28T22:53:31-0700", "has_attachment": false, "exchange_rate": 1 }, {...}, {...} ] }
Query Params
|
vendor_credit_number
Optional
Search vendor credits by vendor credit number. Variants:
vendor_credit_number.startswith and vendor_credit_number.contains
date
Optional
General Format: yyyy-mm-dd. Search vendor credits by date. Variants:
date.start, date.end, date.before and date.after
status
Optional
Search vendor credits by vendor credit status. Allowed statuses are open, closed and void. Allowed Values:
open, closed and void
total
Optional
Search vendor credits by total amount. Variants:
total.start, total.end, total.less_than, total.less_equals, total.greater_than and total.greater_equals
reference_number
Optional
Search vendor credits by vendor credit reference number. Variants:
reference_number.startswith and reference_number.contains
customer_name
Optional
Search vendor credits by vendor name. Variants:
customer_name.startswith and customer_name.contains
item_name
Optional
Search vendor credits by item name. Variants:
item_name.startswith and item_name.contains
item_description
Optional
Search vendor credits by vendor credit item description. Variants:
item_description.startswith and item_description.contains
notes
Optional
Search vendor credits by vendor credit notes. Variants:
notes.startswith and notes.contains
custom_field
Optional
Search vendor credits by custom field. Variants :
custom_field_startswith and custom_field_contains
last_modified_time
Optional
Search vendor credits by vendor credit last modfified time
customer_id
Optional
Search vendor credits by vendor credit customer ID
line_item_id
Optional
Search vendor credits by vendor credit line item ID
item_id
Optional
Search vendor credits by vendor credit item ID
tax_id
Optional
Search vendor credits by vendor credit tax ID
filter_by
Optional
Filter vendor credits by statuses. Allowed Values:
Status.All, Status.Open, Status.Draft, Status.Closed and Status.Void.
search_text
Optional
Search vendor credits by vendor credit number or vendor name or vendor credit reference number.
sort_column
Optional
Sort vendor credits by following
columns vendor_name, vendorcredit_number, balance, total, date and
created_time. Allowed Values:
vendor_name, vendor_credit_number, balance, total, date, created_time, last_modified_time and reference_number. |
Get vendor credit
Get details of a vendor credit.
GET /vendorcredits/{vendor_credit_id}
Request Example
$ curl https://books.zoho.com/api/v3/vendorcredits/{vendor_credit_id}?organization_id=10234695 -H "Authorization: Zoho-authtoken ba4604e8e433g9c892e360d53463oec5" -H "Content-Type: application/json;charset=UTF-8"
Response Example
HTTP/1.1 200 OK Content-Type:application/json;charset=UTF-8 { "code": 0, "message": "success", "vendor_credit": { "vendor_credit_id": "3000000002075", "vendor_credit_number": "DN-00002", "date": "2014-08-28", "status": "open", "source_of_supply": "TN", "destination_of_supply": "TN", "gst_no": "22AAAAA0000A1Z5", "gst_treatment": "business_gst", "is_reverse_charge_applied": true, "vendor_id": "460000000020029", "vendor_name": "Bowman and Co", "currency_id": "3000000000083", "currency_code": "USD", "exchange_rate": 1, "price_precision": 2, "is_inclusive_tax": false, "line_items": { "item_id": "460000000020071", "line_item_id": "460000000020077", "account_id": "460000000020097", "reverse_charge_tax_id": 460000000057089, "reverse_charge_tax_name": "intra", "reverse_charge_tax_percentage": 10, "reverse_charge_tax_amount": 100, "account_name": "IT and Internet Expenses", "name": "Premium Plan - Web hosting", "item_order": 0, "quantity": 1, "unit": "Nos", "bcy_rate": 30, "rate": 30, "item_total": 30, "item_total_inclusive_of_tax": 30, "tags": [ {...} ], "item_custom_fields": [ {...} ] }, "acquisition_vat_summary": [ { "tax": {...} } ], "reverse_charge_vat_summary": [ { "tax": {...} } ], "documents": [ {...} ], "custom_fields": [ {...} ], "sub_total": 30, "total": 30, "total_credits_used": 0, "total_refunded_amount": 0, "balance": 30, "comments": [ { "comment_id": "3000000002089", "vendor_credit_id": "3000000002075", "commented_by_id": "3000000000741", "commented_by": "rajdeep.a", "comment_type": "system", "date": "2014-08-28", "date_description": "32 minutes ago", "time": "10:52 PM", "operation_type": "Added", "transaction_id": "460000000069087", "transaction_type": "vendor_credit" } ], "vendor_credit_refunds": [ { "vendor_credit_refund_id": "3000000003151", "vendor_credit_id": "3000000002075", "date": "2014-08-28", "refund_mode": "cash", "amount_bcy": 13, "amount_fcy": 13 } ], "bills_credited": [ { "bill_id": "460000000057075", "date": "2014-08-28", "amount": 13 } ], "created_time": "2014-08-28T22:53:31-0700", "last_modified_time": "2014-08-28T22:53:31-0700" } }
Query Params
|
print
Optional
Export vendor credit pdf with default print option. Allowed Values:
true, false, on and off.
accept
Optional
You can get vendor credit details as json/pdf/html. Default format is html. Allowed Values:
json, xml, csv, xls, pdf, html and jhtml. |
Delete vendor credit
Delete a vendor credit.
DELETE /vendorcredits/{vendor_credit_id}
Request Example
$ curl https://books.zoho.com/api/v3/vendorcredits/{vendor_credit_id}?organization_id=10234695 -H "Authorization: Zoho-authtoken ba4604e8e433g9c892e360d53463oec5" -H "Content-Type: application/json;charset=UTF-8"
Response Example
HTTP/1.1 200 OK Content-Type:application/json;charset=UTF-8 { "code": 0, "message": "The vendor credit has been deleted." }
Convert to open
Change an existing vendor credit status to open.
POST /vendorcredits/{vendor_credit_id}/status/open
Request Example
$ curl https://books.zoho.com/api/v3/vendorcredits/{vendor_credit_id}/status/open?organization_id=10234695 -H "Authorization: Zoho-authtoken ba4604e8e433g9c892e360d53463oec5" -H "Content-Type: application/json;charset=UTF-8"
Response Example
HTTP/1.1 201 Created Content-Type:application/json;charset=UTF-8 { "code": 0, "message": "The status of the vendor credit has been changed to open." }
Void vendor credit
Mark an existing vendor credit as void.
POST /vendorcredits/{vendor_credit_id}/status/void
Request Example
$ curl https://books.zoho.com/api/v3/vendorcredits/{vendor_credit_id}/status/void?organization_id=10234695 -H "Authorization: Zoho-authtoken ba4604e8e433g9c892e360d53463oec5" -H "Content-Type: application/json;charset=UTF-8"
Response Example
HTTP/1.1 201 Created Content-Type:application/json;charset=UTF-8 { "code": 0, "message": "The vendor credit has been voided." }
List bills credited
List bills to which the vendor credit is applied.
GET /vendorcredits/{vendor_credit_id}/bills
Request Example
$ curl https://books.zoho.com/api/v3/vendorcredits/{vendor_credit_id}/bills?organization_id=10234695 -H "Authorization: Zoho-authtoken ba4604e8e433g9c892e360d53463oec5" -H "Content-Type: application/json;charset=UTF-8"
Response Example
HTTP/1.1 200 OK Content-Type:application/json;charset=UTF-8 { "code": 0, "message": "success", "bills_credited": [ { "vendor_credit_id": "3000000002075", "bill_id": "460000000057075", "date": "2014-08-28" }, {...}, {...} ] }
Apply credits to a bill
Apply vendor credit to existing bills.
POST /vendorcredits/{vendor_credit_id}/bills
Request Example
$ curl https://books.zoho.com/api/v3/vendorcredits/{vendor_credit_id}/bills?organization_id=10234695 -H "Authorization: Zoho-authtoken ba4604e8e433g9c892e360d53463oec5" -H "Content-Type: application/json;charset=UTF-8" -d '{}
Response Example
HTTP/1.1 201 Created Content-Type:application/json;charset=UTF-8 { "code": 0, "message": "Credits have been applied to the bill(s)." }
ARGUMENTS
|
bills
Required
Amount applied from vendor credits to specified bills.
bill_id
Required
Bill Associated with the Vendor Credit
amount_applied
Required
Amount applied to the bill.
|
Delete bills credited
Delete the credits applied to a bill.
DELETE /vendorcredits/{vendor_credit_id}/bills/{vendor_credit_bill_id}
Request Example
$ curl https://books.zoho.com/api/v3/vendorcredits/{vendor_credit_id}/bills/{vendor_credit_bill_id}?organization_id=10234695 -H "Authorization: Zoho-authtoken ba4604e8e433g9c892e360d53463oec5" -H "Content-Type: application/json;charset=UTF-8"
Response Example
HTTP/1.1 200 OK Content-Type:application/json;charset=UTF-8 { "code": 0, "message": "Credits applied to the bill have been deleted." }
Refund a vendor credit
Refund vendor credit amount.
POST /vendorcredits/{vendor_credit_id}/refunds
Request Example
$ curl https://books.zoho.com/api/v3/vendorcredits/{vendor_credit_id}/refunds?organization_id=10234695 -H "Authorization: Zoho-authtoken ba4604e8e433g9c892e360d53463oec5" -H "Content-Type: application/json;charset=UTF-8" -d '{ "date": "2014-08-30", "refund_mode": "cash", "amount": 13, "exchange_rate": 1, "account_id": "460000000020097" }
Response Example
HTTP/1.1 201 Created Content-Type:application/json;charset=UTF-8 { "code": 0, "message": "The refund information for this vendor credit has been saved.", "vendor_credit_refund": { "vendor_credit_refund_id": "3000000003151", "vendor_credit_id": "3000000002075", "date": "2014-08-28", "refund_mode": "cash", "amount": 13, "exchange_rate": 1, "account_id": "460000000020097", "account_name": "IT and Internet Expenses", "imported_transactions": [ { "imported_transaction_id": "460000000013297", "date": "2014-08-28", "amount": 13, "payee": "John Roberts", "status": "open", "account_id": "460000000020097" } ] } }
ARGUMENTS
|
date
Required
Date of Vendor Credit Refund
refund_mode
Optional
Mode of Refund
reference_number
Optional
Reference number for the refund recorded.
amount
Required
exchange_rate
Optional
Exchange rate of the currency.
account_id
Required
ID of the account, the line item is associated with
description
Optional
Description of the line item.
|
Update vendor credit refund
Update the refunded transaction.
PUT /vendorcredits/{vendor_credit_id}/refunds/{vendor_credit_refund_id}
Request Example
$ curl https://books.zoho.com/api/v3/vendorcredits/{vendor_credit_id}/refunds/{vendor_credit_refund_id}?organization_id=10234695 -H "Authorization: Zoho-authtoken ba4604e8e433g9c892e360d53463oec5" -H "Content-Type: application/json;charset=UTF-8" -d '{ "date": "2014-08-28", "refund_mode": "cash", "amount": 13, "exchange_rate": 1, "account_id": "460000000020097" }
Response Example
HTTP/1.1 200 OK Content-Type:application/json;charset=UTF-8 { "code": 0, "message": "The refund information has been saved.", "vendor_credit_refund": { "vendor_credit_refund_id": "3000000003151", "vendor_credit_id": "3000000002075", "date": "2014-08-28", "refund_mode": "cash", "amount": 13, "exchange_rate": 1, "account_id": "460000000020097", "account_name": "IT and Internet Expenses", "imported_transactions": [ { "imported_transaction_id": "460000000013297", "date": "2014-08-28", "amount": 13, "payee": "John Roberts", "status": "open", "account_id": "460000000020097" } ] } }
ARGUMENTS
|
date
Required
The date the vendor credit is created. [yyyy-mm-dd]
refund_mode
Optional
Mode of Refund
reference_number
Optional
Reference number for the refund recorded.
amount
Required
exchange_rate
Optional
Exchange rate of the currency.
account_id
Required
ID of the account, the line item is associated with
description
Optional
Description of the line item.
|
Get vendor credit refund
Get refund of a particular vendor credit.
GET /vendorcredits/{vendor_credit_id}/refunds/{vendor_credit_refund_id}
Request Example
$ curl https://books.zoho.com/api/v3/vendorcredits/{vendor_credit_id}/refunds/{vendor_credit_refund_id}?organization_id=10234695 -H "Authorization: Zoho-authtoken ba4604e8e433g9c892e360d53463oec5" -H "Content-Type: application/json;charset=UTF-8"
Response Example
HTTP/1.1 200 OK Content-Type:application/json;charset=UTF-8 { "code": 0, "message": "success", "vendor_credit_refund": { "vendor_credit_refund_id": "3000000003151", "vendor_credit_id": "3000000002075", "date": "2014-08-28", "refund_mode": "cash", "amount": 13, "exchange_rate": 1, "account_id": "460000000020097", "account_name": "IT and Internet Expenses", "imported_transactions": [ { "imported_transaction_id": "460000000013297", "date": "2014-08-28", "amount": 13, "payee": "John Roberts", "status": "open", "account_id": "460000000020097" } ] } }
List vendor credit refunds
List all refunds with pagination.
GET /vendorcredits/refunds
Request Example
$ curl https://books.zoho.com/api/v3/vendorcredits/refunds?organization_id=10234695 -H "Authorization: Zoho-authtoken ba4604e8e433g9c892e360d53463oec5" -H "Content-Type: application/json;charset=UTF-8"
Response Example
HTTP/1.1 200 OK Content-Type:application/json;charset=UTF-8 { "code": 0, "message": "success", "vendor_credit_refunds": [ { "vendor_credit_refund_id": "3000000003151", "vendor_credit_id": "3000000002075", "date": "2017-01-22", "refund_mode": "cash", "amount": 13, "vendor_credit_number": "DN-00002", "customer_name": "Bowman and Co", "description": "Cheque deposit", "amount_bcy": 13, "amount_fcy": 13 }, {...}, {...} ] }
Query Params
|
customer_id
Optional
Search vendor credits by vendor credit customer ID
last_modified_time
Optional
Search vendor credits by vendor credit last modfified time
sort_column
Optional
Sort vendor credits by following
columns vendor_name, vendorcredit_number, balance, total, date and
created_time. Allowed Values:
vendor_name, vendor_credit_number, balance, total, date, created_time, last_modified_time and reference_number. |
List refunds of a vendor credit
List all refunds of an existing vendor credit.
GET /vendorcredits/{vendor_credit_id}/refunds
Request Example
$ curl https://books.zoho.com/api/v3/vendorcredits/{vendor_credit_id}/refunds?organization_id=10234695 -H "Authorization: Zoho-authtoken ba4604e8e433g9c892e360d53463oec5" -H "Content-Type: application/json;charset=UTF-8"
Response Example
HTTP/1.1 200 OK Content-Type:application/json;charset=UTF-8 { "code": 0, "message": "success", "vendor_credit_refunds": [ { "vendor_credit_refund_id": "3000000003151", "vendor_credit_id": "3000000002075", "date": "2017-01-22", "refund_mode": "cash", "amount": 13, "vendor_credit_number": "DN-00002", "customer_name": "Bowman and Co", "description": "Cheque deposit", "amount_bcy": 13, "amount_fcy": 13 }, {...}, {...} ] }
Delete vendor credit refund
Delete a vendor credit refund.
DELETE /vendorcredits/{vendor_credit_id}/refunds/{vendor_credit_refund_id}
Request Example
$ curl https://books.zoho.com/api/v3/vendorcredits/{vendor_credit_id}/refunds/{vendor_credit_refund_id}?organization_id=10234695 -H "Authorization: Zoho-authtoken ba4604e8e433g9c892e360d53463oec5" -H "Content-Type: application/json;charset=UTF-8"
Response Example
HTTP/1.1 200 OK Content-Type:application/json;charset=UTF-8 { "code": 0, "message": "The refund has been successfully deleted." }
Add a comment
Add a comment to an existing vendor credit.
POST /vendorcredits/{vendor_credit_id}/comments
Request Example
$ curl https://books.zoho.com/api/v3/vendorcredits/{vendor_credit_id}/comments?organization_id=10234695 -H "Authorization: Zoho-authtoken ba4604e8e433g9c892e360d53463oec5" -H "Content-Type: application/json;charset=UTF-8" -d '{ "description": "Credits applied to Bill 1" }
Response Example
HTTP/1.1 201 Created Content-Type:application/json;charset=UTF-8 { "code": 0, "message": "Comments added.", "comment": {...} }
ARGUMENTS
|
description
Required
Description of the Comment
|
List vendor credit comments & history
Get history and comments of a vendor credit.
GET /vendorcredits/{vendor_credit_id}/comments
Request Example
$ curl https://books.zoho.com/api/v3/vendorcredits/{vendor_credit_id}/comments?organization_id=10234695 -H "Authorization: Zoho-authtoken ba4604e8e433g9c892e360d53463oec5" -H "Content-Type: application/json;charset=UTF-8"
Response Example
HTTP/1.1 200 OK Content-Type:application/json;charset=UTF-8 { "code": 0, "message": "success", "comments": [ { "comment_id": "3000000002089", "vendor_credit_id": "3000000002075", "description": "Credits applied to Bill 1", "commented_by_id": "3000000000741", "commented_by": "rajdeep.a", "comment_type": "system", "date": "2017-01-18", "date_description": "32 minutes ago", "time": "10:52 PM", "operation_type": "Added", "transaction_id": "460000000069087", "transaction_type": "vendor_credit" }, {...}, {...} ] }
Delete a comment
Delete a vendor credit comment.
DELETE /vendorcredits/{vendor_credit_id}/comments/{comment_id}
Request Example
$ curl https://books.zoho.com/api/v3/vendorcredits/{vendor_credit_id}/comments/{comment_id}?organization_id=10234695 -H "Authorization: Zoho-authtoken ba4604e8e433g9c892e360d53463oec5" -H "Content-Type: application/json;charset=UTF-8"
Response Example
HTTP/1.1 200 OK Content-Type:application/json;charset=UTF-8 { "code": 0, "message": "The comment has been deleted." }
Vendor-Payments
Payments to Vendors towards Bills.
Example
{ "vendorpayment": [ { "payment_id": "460000000053219", "vendor_id": "460000000026049", "vendor_name": "Bowman and Co", "payment_mode": "Stripe", "payment_number": 4, "custom_fields": [ {} ], "documents": [ {} ], "date": "2013-10-07", "reference_number": "REF#912300", "exchange_rate": 1, "amount": 500, "balance": 300, "currency_id": "460000000000099", "currency_symbol": "$", "created_time": "2016-12-16T00:18:42-0500", "paid_through_account_id": "460000000000358", "paid_through_account_name": "Undeposited Funds", "paid_through_account_type": "cash", "is_paid_via_print_check": false, "is_ach_payment": false, "check_details": [ {} ], "billing_address": [ {} ], "bills": [ { "bill_payment_id": "460000000053221", "bill_id": "460000000053199", "amount_applied": 150 } ], "vendorpayment_refunds": [ { "vendorpayment_refund_id": "460000000003017", "date": "2013-10-07", "refund_mode": "cash", "reference_number": "REF#912300", "amount_bcy": 10, "amount_fcy": 10 } ], "imported_transactions": [ {} ] } ] }
Attribute
|
vendorpayment
list
payment_id
string
ID of the Payment
vendor_id
string
ID of the vendor associated with the Vendor Payment.
vendor_name
string
Name of the Vendor Associated with the Vendor Payment
payment_mode
string
Mode of Vendor Payment
payment_number
integer
Number of the Vendor Payment
custom_fields
list
custom_field_id
string
ID of the Custom Field
index
integer
Index of the Custom Field
label
string
Label of the Custom Field
value
string
Value for the Custom Field
description
string
Description for the Vendor Payment recorded.
documents
list
date
string
Date the payment is made.
reference_number
string
Reference number for the Vendor Payment recorded.
exchange_rate
double
Exchange rate of the currency.
tax_account_name
string
Name of the tax Account
tax_amount_withheld
Only for Global, India and AU Editions
double
Tax Amount Withheld during Bill Payment
amount
double
Total Amount of Vendor Payment
balance
double
Balance due for the Bill
currency_id
string
ID of the Currency.
currency_symbol
string
Symbol of the Currency
created_time
string
Creation Time of the Vendor Payment
last_modified_time
string
The Last Modified Time of the Vendor Payment
paid_through_account_id
string
ID of the cash/ bank account from which the payment is made.
paid_through_account_name
string
Name of the Cash/Bank Account through which the Vendor Payment is made.
paid_through_account_type
string
The type of Paid Through Account
is_paid_via_print_check
US and CA Edition Only.
boolean
Check if the Bill Payment is paid Via Print Check Option
is_ach_payment
boolean
Check If Vendor Payment ACH
ach_payment_status
string
Status of the ACH Payment
check_details
US and CA Editions Only
list
billing_address
list
bills
list
Individual bill payment details as array.
bill_payment_id
string
ID of the Bill Payment
bill_id
string
ID of the bill the payment is to be applied.
amount_applied
double
Amount applied to the bill.
tax_amount_withheld
Only for Global, India and AU Editions
double
Tax Amount Withheld during Bill Payment
vendorpayment_refunds
list
[object Object]
vendorpayment_refund_id
string
ID of the Vendor Payment Refund
date
string
Date of the Vendor Payment Refund.
refund_mode
string
Mode in which refund is made.
reference_number
string
Reference Number of the Payment Refund
reference_number
string
Reference Number of the Payment Refund
description
string
Description of the Payment Refund
amount_bcy
double
Payment Refund Amount in Base Currency
amount_fcy
double
Payment Refund Amount in Foreign Currency
imported_transactions
list
|
Create a vendor payment
Create a payment made to your vendor and you can also apply them to bills either partially or fully.
POST /vendorpayments
Request Example
$ curl https://books.zoho.com/api/v3/vendorpayments?organization_id=10234695 -H "Authorization: Zoho-authtoken ba4604e8e433g9c892e360d53463oec5" -H "Content-Type: application/json;charset=UTF-8" -d '{ "vendor_id": "460000000026049", "bills": [ { "bill_payment_id": "460000000053221", "bill_id": "460000000053199", "amount_applied": 150 } ], "date": "2013-10-07", "exchange_rate": 1, "amount": 500, "paid_through_account_id": "460000000000358", "payment_mode": "Stripe", "reference_number": "REF#912300", "check_details": [ {} ], "is_paid_via_print_check": false, "custom_fields": [ {} ] }
Response Example
HTTP/1.1 201 Created Content-Type:application/json;charset=UTF-8 { "code": 0, "message": "The payment made to the vendor has been recorded.", "amount": 500, "balance": 300, "billing_address": [ {...} ], "bills": [ { "bill_payment_id": "460000000053221", "bill_id": "460000000053199", "amount_applied": 150, "balance": 300, "bill_number": "B-1000", "date": "2013-10-07", "due_date": "2013-10-07", "price_precision": 2, "total": 450 } ], "check_details": {...}, "created_time": "2016-12-16T00:18:42-0500", "currency_id": "460000000000099", "currency_symbol": "$", "custom_fields": [ {...} ], "date": "2013-10-07", "exchange_rate": 1, "imported_transactions": [ {...} ], "documents": [ {...} ], "is_ach_payment": false, "is_paid_via_print_check": false, "paid_through_account_id": "460000000000358", "paid_through_account_name": "Undeposited Funds", "paid_through_account_type": "cash", "payment_id": "460000000053219", "payment_mode": "Stripe", "payment_number": 4, "reference_number": "REF#912300", "vendor_id": "460000000026049", "vendor_name": "Bowman and Co", "vendorpayment_refunds": [ { "vendorpayment_refund_id": "460000000003017", "date": "2013-10-07", "refund_mode": "cash", "reference_number": "REF#912300", "amount_bcy": 10, "amount_fcy": 10 } ] }
ARGUMENTS
|
vendor_id
Optional
ID of the vendor associated with the Vendor Payment.
bills
Optional
Individual bill payment details as array.
bill_payment_id
Optional
ID of the Bill Payment
bill_id
Optional
ID of the bill the payment is to be applied.
amount_applied
Optional
Amount applied to the bill.
tax_amount_withheld
Only for Global, India and AU Editions
Optional
Tax Amount Withheld during Bill Payment
date
Optional
Date the payment is made.
exchange_rate
Optional
Exchange rate of the currency.
amount
Required
Total Amount of Vendor Payment
paid_through_account_id
Optional
ID of the cash/ bank account from which the payment is made.
payment_mode
Optional
Mode of Vendor Payment
description
Optional
Description for the Vendor Payment recorded.
reference_number
Optional
Reference number for the Vendor Payment recorded.
check_details
US and CA Editions Only
Optional
is_paid_via_print_check
US and CA Edition Only.
Optional
Check if the Bill Payment is paid Via Print Check Option
custom_fields
Optional
index
Optional
Index of the Custom Field
value
Optional
Value for the Custom Field
|
Update a vendor payment
Update an existing vendor payment. You can also modify the amount applied to the bills.
PUT /vendorpayments/{payment_id}
Request Example
$ curl https://books.zoho.com/api/v3/vendorpayments/{payment_id}?organization_id=10234695 -H "Authorization: Zoho-authtoken ba4604e8e433g9c892e360d53463oec5" -H "Content-Type: application/json;charset=UTF-8" -d '{ "vendor_id": "460000000026049", "bills": [ { "bill_payment_id": "460000000053221", "bill_id": "460000000053199", "amount_applied": 150 } ], "date": "2013-10-07", "exchange_rate": 1, "amount": 500, "paid_through_account_id": "460000000000358", "payment_mode": "Stripe", "reference_number": "REF#912300", "is_paid_via_print_check": false, "check_details": [ {} ], "custom_fields": [ {} ] }
Response Example
HTTP/1.1 200 OK Content-Type:application/json;charset=UTF-8 { "code": 0, "message": "The details of the payment made to the vendor has been updated", "vendorpayment": [ { "payment_id": "460000000053219", "vendor_id": "460000000026049", "vendor_name": "Bowman and Co", "payment_mode": "Stripe", "payment_number": 4, "custom_fields": [ {...} ], "documents": [ {...} ], "date": "2013-10-07", "reference_number": "REF#912300", "exchange_rate": 1, "amount": 500, "balance": 300, "currency_id": "460000000000099", "currency_symbol": "$", "created_time": "2016-12-16T00:18:42-0500", "paid_through_account_id": "460000000000358", "paid_through_account_name": "Undeposited Funds", "paid_through_account_type": "cash", "is_paid_via_print_check": false, "is_ach_payment": false, "check_details": [ {...} ], "billing_address": [ {...} ], "bills": [ { "bill_payment_id": "460000000053221", "bill_id": "460000000053199", "amount_applied": 150 } ], "vendorpayment_refunds": [ { "vendorpayment_refund_id": "460000000003017", "date": "2013-10-07", "refund_mode": "cash", "reference_number": "REF#912300", "amount_bcy": 10, "amount_fcy": 10 } ], "imported_transactions": [ {...} ] } ] }
ARGUMENTS
|
vendor_id
Optional
ID of the vendor associated with the Vendor Payment.
bills
Optional
Individual bill payment details as array.
bill_payment_id
Optional
ID of the Bill Payment
bill_id
Optional
ID of the bill the payment is to be applied.
amount_applied
Optional
Amount applied to the bill.
tax_amount_withheld
Only for Global, India and AU Editions
Optional
Tax Amount Withheld during Bill Payment
date
Optional
Date the payment is made.
exchange_rate
Optional
Exchange rate of the currency.
amount
Required
Total Amount of Vendor Payment
paid_through_account_id
Optional
ID of the cash/ bank account from which the payment is made.
payment_mode
Optional
Mode of Vendor Payment
description
Optional
Description for the Vendor Payment recorded.
reference_number
Optional
Reference number for the Vendor Payment recorded.
is_paid_via_print_check
US and CA Edition Only.
Optional
Check if the Bill Payment is paid Via Print Check Option
check_details
US and CA Editions Only
Optional
custom_fields
Optional
index
Optional
Index of the Custom Field
value
Optional
Value for the Custom Field
|
List vendor payments
List all the payments made to your vendor.
GET /vendorpayments
Request Example
$ curl https://books.zoho.com/api/v3/vendorpayments?organization_id=10234695 -H "Authorization: Zoho-authtoken ba4604e8e433g9c892e360d53463oec5" -H "Content-Type: application/json;charset=UTF-8"
Response Example
HTTP/1.1 200 OK Content-Type:application/json;charset=UTF-8 { "code": 0, "message": "success", "vendorpayments": [ { "vendorpayment": { "payment_id": "460000000053219", "vendor_id": "460000000026049", "vendor_name": "Bowman and Co", "payment_mode": "Stripe", "payment_number": 4, "date": "2013-10-07", "reference_number": "REF#912300", "exchange_rate": 1, "amount": 500, "bcy_amount": 76, "paid_through_account_id": "460000000000358", "paid_through_account_name": "Undeposited Funds", "balance": 300, "bcy_balance": 76, "created_time": "2016-12-16T00:18:42-0500", "is_paid_via_print_check": false, "has_attachment": false, "is_ach_payment": false, "check_details": [ {...} ] } }, {...}, {...} ] }
Query Params
|
vendor_name
Optional
Search payments by vendor name. Variants:
vendor_name_startswith and vendor_name_contains.
reference_number
Optional
Search payments by reference number. Variants:
reference_number_startswith and reference_number_contains. In refunds, reference number for the refund recorded.
payment_number
Optional
Search with Payment Number. Variant:
payment_number_startswith, payment_number_contains
date
Optional
Date the payment is made. Search payments by payment made date. Variants:
date_start, date_end, date_before and date_after.
amount
Optional
Payment amount made to the vendor. Search payments by payment amount. Variants:
amount_less_than, amount_less_equals, amount_greater_than and amount_greater_equals. In refunds, Amount refunded from the vendor payment.
payment_mode
Optional
Search payments by payment mode. Variants:
payment_mode_startswith and payment_mode_contains.
notes
Optional
Search with Payment Notes. Variant:
notes_startswith, notes_contains
vendor_id
Optional
ID of the vendor. Search payments by vendor id.
last_modified_time
Optional
Search with the Last Modified Time of the Vendor Payment
bill_id
Optional
Search payments by Bill ID.
description
Optional
Search payments by description. Variants:
description_startswith and description_contains.
filter_by
Optional
Filter payments by mode. Allowed Values:
PaymentMode.All, PaymentMode.Check, PaymentMode.Cash, PaymentMode.BankTransfer, PaymentMode.Paypal, PaymentMode.CreditCard, PaymentMode.GoogleCheckout, PaymentMode.Credit, PaymentMode.Authorizenet, PaymentMode.BankRemittance, PaymentMode.Payflowpro and PaymentMode.Others.
search_text
Optional
Search payments by reference number or vendor name or payment description.
sort_column
Optional
Sort the payment list. Allowed Values:
vendor_name, date, reference_number, amount and balance. |
Get a vendor payment
Get the details of a vendor payment.
GET /vendorpayments/{payment_id}
Request Example
$ curl https://books.zoho.com/api/v3/vendorpayments/{payment_id}?organization_id=10234695 -H "Authorization: Zoho-authtoken ba4604e8e433g9c892e360d53463oec5" -H "Content-Type: application/json;charset=UTF-8"
Response Example
HTTP/1.1 200 OK Content-Type:application/json;charset=UTF-8 { "code": 0, "message": "success", "vendorpayment": { "payment_id": "460000000053219", "vendor_id": "460000000026049", "vendor_name": "Bowman and Co", "payment_mode": "Stripe", "payment_number": 4, "date": "2013-10-07", "reference_number": "REF#912300", "exchange_rate": 1, "amount": 500, "balance": 300, "currency_id": "460000000000099", "currency_symbol": "$", "created_time": "2016-12-16T00:18:42-0500", "paid_through_account_id": "460000000000358", "paid_through_account_name": "Undeposited Funds", "paid_through_account_type": "cash", "is_paid_via_print_check": false, "is_ach_payment": false, "check_details": {...}, "billing_address": [ {...} ], "vendorpayment_refunds": [ { "vendorpayment_refund_id": "460000000003017", "date": "2013-10-07", "refund_mode": "cash", "reference_number": "REF#912300", "amount_bcy": 10, "amount_fcy": 10 } ], "bills": [ { "bill_payment_id": "460000000053221", "bill_id": "460000000053199", "amount_applied": 150 } ], "documents": [ {...} ], "custom_fields": [ {...} ] } }
Query Params
|
fetchTaxInfo
Optional
Check if tax information should be fetched
fetchstatementlineinfo
Optional
Check is Statement Line Information for Vendor Payment be fetched
print
Optional
Check if Vendor Payment must be printed.
is_bill_payment_id
Optional
Check if the ID is Bill Payment or Vendor Payment
|
Delete a vendor payment
Delete an existing vendor payment.
DELETE /vendorpayments/{payment_id}
Request Example
$ curl https://books.zoho.com/api/v3/vendorpayments/{payment_id}?organization_id=10234695 -H "Authorization: Zoho-authtoken ba4604e8e433g9c892e360d53463oec5" -H "Content-Type: application/json;charset=UTF-8"
Response Example
HTTP/1.1 200 OK Content-Type:application/json;charset=UTF-8 { "code": 0, "message": "The payment has been deleted." }
List refunds of a vendor payment
List all the refunds pertaining to an existing vendor payment.
GET /vendorpayments/{payment_id}/refunds
Request Example
$ curl https://books.zoho.com/api/v3/vendorpayments/{payment_id}/refunds?organization_id=10234695 -H "Authorization: Zoho-authtoken ba4604e8e433g9c892e360d53463oec5" -H "Content-Type: application/json;charset=UTF-8"
Response Example
HTTP/1.1 200 OK Content-Type:application/json;charset=UTF-8 { "code": 0, "message": "success", "vendorpayment_refunds": [ {...}, {...}, {...} ] }
Details of a refund
Obtain details of a particular refund of a vendor payment.
GET /vendorpayments/{payment_id}/refunds/{vendorpayment_refund_id}
Request Example
$ curl https://books.zoho.com/api/v3/vendorpayments/{payment_id}/refunds/{vendorpayment_refund_id}?organization_id=10234695 -H "Authorization: Zoho-authtoken ba4604e8e433g9c892e360d53463oec5" -H "Content-Type: application/json;charset=UTF-8"
Response Example
HTTP/1.1 200 OK Content-Type:application/json;charset=UTF-8 { "code": 0, "message": "success", "vendorpayment_refund": [ { "vendorpayment_refund_id": "460000000003017", "vendorpayment_id": "460000000003001", "date": "2013-10-07", "refund_mode": "cash", "reference_number": "REF#912300", "amount": 500, "exchange_rate": 1, "to_account_id": "460000000000385", "to_account_name": "Petty Cash" } ] }
Refund an excess vendor payment
Refund the excess amount paid to the vendor.
POST /vendorpayments/{payment_id}/refunds
Request Example
$ curl https://books.zoho.com/api/v3/vendorpayments/{payment_id}/refunds?organization_id=10234695 -H "Authorization: Zoho-authtoken ba4604e8e433g9c892e360d53463oec5" -H "Content-Type: application/json;charset=UTF-8" -d '{ "date": "2017-01-10", "refund_mode": "cash", "amount": 500, "exchange_rate": 1, "to_account_id": "460000000000385", "description": "Payment Refund" }
Response Example
HTTP/1.1 201 Created Content-Type:application/json;charset=UTF-8 { "code": 0, "message": "Vendor Payment Refunded successfully", "vendorpayment_refund": [ { "vendorpayment_refund_id": "460000000003017", "vendorpayment_id": "460000000003001", "date": "2013-10-07", "refund_mode": "cash", "reference_number": "REF#912300", "amount": 500, "exchange_rate": 1, "to_account_id": "460000000000385", "to_account_name": "Petty Cash" } ] }
ARGUMENTS
|
date
Required
Date of the Vendor Payment Refund.
refund_mode
Optional
Mode in which refund is made.
reference_number
Optional
Reference Number of the Payment Refund
amount
Required
Total Amount of Vendor Payment
exchange_rate
Optional
Exchange rate of the currency.
to_account_id
Required
The account to which payment is refunded.
description
Optional
Description of the Payment Refund
|
Update a refund
Update the refunded transaction.
PUT /vendorpayments/{payment_id}/refunds/{refund_id}
Request Example
$ curl https://books.zoho.com/api/v3/vendorpayments/{payment_id}/refunds/{refund_id}?organization_id=10234695 -H "Authorization: Zoho-authtoken ba4604e8e433g9c892e360d53463oec5" -H "Content-Type: application/json;charset=UTF-8" -d '{ "date": "2017-01-10", "refund_mode": "cash", "amount": 500, "exchange_rate": 1, "to_account_id": "460000000000385", "description": "Payment Refund" }
Response Example
HTTP/1.1 200 OK Content-Type:application/json;charset=UTF-8 { "code": 0, "message": "The refund information has been saved.", "vendorpayment_refund": [ { "vendorpayment_refund_id": "460000000003017", "vendorpayment_id": "460000000003001", "date": "2013-10-07", "refund_mode": "cash", "reference_number": "REF#912300", "amount": 500, "exchange_rate": 1, "to_account_id": "460000000000385", "to_account_name": "Petty Cash" } ] }
ARGUMENTS
|
date
Required
Date of the Vendor Payment Refund.
refund_mode
Optional
Mode in which refund is made.
reference_number
Optional
Reference Number of the Payment Refund
amount
Required
Total Amount of Vendor Payment
exchange_rate
Optional
Exchange rate of the currency.
to_account_id
Required
The account to which payment is refunded.
description
Optional
Description of the Payment Refund
|
Delete a refund
Delete refund pertaining to an existing vendor payment.
DELETE /vendorpayments/{payment_id}/refunds/{refund_id}
Request Example
$ curl https://books.zoho.com/api/v3/vendorpayments/{payment_id}/refunds/{refund_id}?organization_id=10234695 -H "Authorization: Zoho-authtoken ba4604e8e433g9c892e360d53463oec5" -H "Content-Type: application/json;charset=UTF-8"
Response Example
HTTP/1.1 200 OK Content-Type:application/json;charset=UTF-8 { "code": 0, "message": "The refund has been deleted." }
Bank-Accounts
In Zoho Books, you can track your transactions, have manual and automatic feeds imported for your bank and credit card accounts.
Example
{ "account_name": "Corporate Account", "account_type": "bank", "account_number": "80000009823", "currency_id": "460000000000097", "currency_code": "USD", "description": "Salary details.", "bank_name": "Xavier Bank" }
Attribute
|
account_name
string
Name of the account
account_type
string
Type of the account
account_number
string
Number associated with the Bank Account
account_code
string
Code of the Account
currency_id
string
ID of the Currency associated with the Account
currency_code
string
Code of the currency associated with the Bank Account
description
string
Description of the Account
bank_name
string
Name of the Bank
|
Create a bank account
Create a bank account or a credit card account for your organization.
POST /bankaccounts
Request Example
$ curl https://books.zoho.com/api/v3/bankaccounts?organization_id=10234695 -H "Authorization: Zoho-authtoken ba4604e8e433g9c892e360d53463oec5" -H "Content-Type: application/json;charset=UTF-8" -d '{ "account_name": "Corporate Account", "account_type": "bank", "account_number": "80000009823", "currency_id": "460000000000097", "currency_code": "USD", "description": "Salary details.", "bank_name": "Xavier Bank", "routing_number": "123456789", "is_primary_account": false, "is_paypal_account": true, "paypal_email_address": "johnsmith@zilliuminc.com" }
Response Example
HTTP/1.1 201 Created Content-Type:application/json;charset=UTF-8 { "code": 0, "message": "The account has been created.", "bankaccount": { "account_id": "460000000050127", "account_name": "Corporate Account", "currency_id": "460000000000097", "currency_code": "USD", "currency_symbol": "$", "price_precision": 2, "account_type": "bank", "account_number": "80000009823", "uncategorized_transactions": 0, "total_unprinted_checks": 0, "is_active": true, "is_feeds_subscribed": false, "is_feeds_active": false, "balance": 0, "bank_balance": 0, "bcy_balance": 0, "bank_name": "Xavier Bank", "routing_number": "123456789", "is_primary_account": false, "is_paypal_account": true, "description": "Salary details.", "is_system_account": false, "is_show_warning_for_feeds_refresh": false } }
ARGUMENTS
|
account_name
Required
Name of the account
account_type
Required
Type of the account
account_number
Optional
Number associated with the Bank Account
account_code
Optional
Code of the Account
currency_id
Optional
ID of the Currency associated with the Account
currency_code
Optional
Code of the currency associated with the Bank Account
description
Optional
Description of the Account
bank_name
Optional
Name of the Bank
routing_number
Optional
Routing Number of the Account
is_primary_account
Optional
Check if the Account is Primary Account in Zoho Books
is_paypal_account
Optional
Check if the Account is Paypal Account
paypal_type
Optional
The type of Payment for the Paypal Account. Allowed Values :
standard and adaptive
paypal_email_address
Optional
Email Address of the Paypal account.
|
Update bank account
Modify the account that was created.
PUT /bankaccounts/{account_id}
Request Example
$ curl https://books.zoho.com/api/v3/bankaccounts/{account_id}?organization_id=10234695 -H "Authorization: Zoho-authtoken ba4604e8e433g9c892e360d53463oec5" -H "Content-Type: application/json;charset=UTF-8" -d '{ "account_name": "Corporate Account", "account_type": "bank", "account_number": "80000009823", "currency_id": "460000000000097", "currency_code": "USD", "description": "Salary details.", "bank_name": "Xavier Bank", "routing_number": "123456789", "is_primary_account": false, "is_paypal_account": true, "paypal_email_address": "johnsmith@zilliuminc.com" }
Response Example
HTTP/1.1 200 OK Content-Type:application/json;charset=UTF-8 { "code": 0, "message": "The details of the account has been updated.", "bankaccount": { "account_id": "460000000050127", "account_name": "Corporate Account", "currency_id": "460000000000097", "currency_code": "USD", "currency_symbol": "$", "price_precision": 2, "account_type": "bank", "account_number": "80000009823", "uncategorized_transactions": 0, "total_unprinted_checks": 0, "is_active": true, "is_feeds_subscribed": false, "is_feeds_active": false, "balance": 0, "bank_balance": 0, "bcy_balance": 0, "bank_name": "Xavier Bank", "routing_number": "123456789", "is_primary_account": false, "is_paypal_account": true, "description": "Salary details.", "is_system_account": false, "is_show_warning_for_feeds_refresh": false } }
ARGUMENTS
|
account_name
Required
Name of the account
account_type
Required
Type of the account
account_number
Optional
Number associated with the Bank Account
account_code
Optional
Code of the Account
currency_id
Optional
ID of the Currency associated with the Account
currency_code
Optional
Code of the currency associated with the Bank Account
description
Optional
Description of the Account
bank_name
Optional
Name of the Bank
routing_number
Optional
Routing Number of the Account
is_primary_account
Optional
Check if the Account is Primary Account in Zoho Books
is_paypal_account
Optional
Check if the Account is Paypal Account
paypal_type
Optional
The type of Payment for the Paypal Account. Allowed Values :
standard and adaptive
paypal_email_address
Optional
Email Address of the Paypal account.
|
Get account details
Get a detailed look of the account specified.
GET /bankaccounts/{account_id}
Request Example
$ curl https://books.zoho.com/api/v3/bankaccounts/{account_id}?organization_id=10234695 -H "Authorization: Zoho-authtoken ba4604e8e433g9c892e360d53463oec5" -H "Content-Type: application/json;charset=UTF-8"
Response Example
HTTP/1.1 200 OK Content-Type:application/json;charset=UTF-8 { "code": 0, "message": "success", "bankaccount": { "account_id": "460000000050127", "account_name": "Corporate Account", "currency_id": "460000000000097", "currency_code": "USD", "currency_symbol": "$", "price_precision": 2, "account_type": "bank", "account_number": "80000009823", "uncategorized_transactions": 0, "total_unprinted_checks": 0, "is_active": true, "is_feeds_subscribed": false, "is_feeds_active": false, "balance": 0, "bank_balance": 0, "bcy_balance": 0, "bank_name": "Xavier Bank", "routing_number": "123456789", "is_primary_account": false, "is_paypal_account": true, "description": "Salary details.", "is_system_account": false, "is_show_warning_for_feeds_refresh": false } }
List view of accounts
List all bank and credit card accounts for your organization.
GET /bankaccounts
Request Example
$ curl https://books.zoho.com/api/v3/bankaccounts?organization_id=10234695 -H "Authorization: Zoho-authtoken ba4604e8e433g9c892e360d53463oec5" -H "Content-Type: application/json;charset=UTF-8"
Response Example
HTTP/1.1 200 OK Content-Type:application/json;charset=UTF-8 { "code": 0, "message": "success", "bankaccounts": [ { "account_id": "460000000050127", "account_name": "Corporate Account", "currency_id": "460000000000097", "currency_code": "USD", "account_type": "bank", "account_number": "80000009823", "uncategorized_transactions": 0, "total_unprinted_checks": 0, "is_active": true, "balance": 0, "bank_balance": 0, "bcy_balance": 0, "bank_name": "Xavier Bank", "routing_number": "123456789", "is_primary_account": false, "is_paypal_account": true }, {...}, {...} ] }
Query Params
|
filter_by
Optional
Filter the account by their status. Allowed Values:
Status.All, Status.Active and Status.Inactive.
sort_column
Optional
Sort the values based on the allowed values. Allowed Values:
account_name,account_type and account_code. |
Delete an account
Delete a bank account from your organization.
DELETE /bankaccounts/{account_id}
Request Example
$ curl https://books.zoho.com/api/v3/bankaccounts/{account_id}?organization_id=10234695 -H "Authorization: Zoho-authtoken ba4604e8e433g9c892e360d53463oec5" -H "Content-Type: application/json;charset=UTF-8"
Response Example
HTTP/1.1 200 OK Content-Type:application/json;charset=UTF-8 { "code": 0, "message": "The account has been deleted." }
Deactivate account.
Make an account inactive.
POST /bankaccounts/{account_id}/inactive
Request Example
$ curl https://books.zoho.com/api/v3/bankaccounts/{account_id}/inactive?organization_id=10234695 -H "Authorization: Zoho-authtoken ba4604e8e433g9c892e360d53463oec5" -H "Content-Type: application/json;charset=UTF-8"
Response Example
HTTP/1.1 201 Created Content-Type:application/json;charset=UTF-8 { "code": 0, "message": "The account has been marked as inactive." }
Activate account
Make an account active.
POST /bankaccounts/{account_id}/active
Request Example
$ curl https://books.zoho.com/api/v3/bankaccounts/{account_id}/active?organization_id=10234695 -H "Authorization: Zoho-authtoken ba4604e8e433g9c892e360d53463oec5" -H "Content-Type: application/json;charset=UTF-8"
Response Example
HTTP/1.1 201 Created Content-Type:application/json;charset=UTF-8 { "code": 0, "message": "The account has been marked as active." }
Get last imported statement
Get the details of previously imported statement for the account.
GET /bankaccounts/{account_id}/statement/lastimported
Request Example
$ curl https://books.zoho.com/api/v3/bankaccounts/{account_id}/statement/lastimported?organization_id=10234695 -H "Authorization: Zoho-authtoken ba4604e8e433g9c892e360d53463oec5" -H "Content-Type: application/json;charset=UTF-8"
Response Example
HTTP/1.1 200 OK Content-Type:application/json;charset=UTF-8 { "code": 0, "message": "success", "statement": [ { "statement_id": "460000000049013", "from_date": "2012-01-12", "to_date": "2012-01-19", "source": "csv", "transactions": [ { "transaction_id": "460000000049023", "debit_or_credit": "credit", "date": "2012-01-14", "customer_id": "460000000026049", "payee": "Bowman and Co", "reference_number": "Ref-2134", "transaction_type": "expense", "amount": 7500, "status": "categorized" } ] }, {...}, {...} ] }
Delete last imported statement
Delete the statement that was previously imported.
DELETE /bankaccounts/{account_id}/statement/{statement_id}
Request Example
$ curl https://books.zoho.com/api/v3/bankaccounts/{account_id}/statement/{statement_id}?organization_id=10234695 -H "Authorization: Zoho-authtoken ba4604e8e433g9c892e360d53463oec5" -H "Content-Type: application/json;charset=UTF-8"
Response Example
HTTP/1.1 200 OK Content-Type:application/json;charset=UTF-8 { "code": 0, "message": "You have successfully deleted the last imported statement." }
Bank-Transactions
In many instances, you would wish to record manual entries for your offline transactions for your bank or credit card accounts. These entries might not be a part of your bank feeds but would make an important entry for your business records.
Example
{ "transaction_id": "460000000048017", "date": "2013-10-01", "amount": 2000, "transaction_type": "deposit", "status": "categorized", "source": "manually_added", "account_id": "460000000048001", "account_name": "Petty Cash", "account_type": "cash", "price_precision": 2, "customer_id": "460000000000111", "payee": "Smith", "is_paid_via_print_check": false, "currency_id": "460000000000097", "currency_code": "USD", "currency_symbol": "$", "debit_or_credit": "debit", "offset_account_name": "Petty Cash", "is_offsetaccount_matched": false, "reference_number": "Ref-121", "imported_transaction_id": "460000000013297", "is_rule_exist": false, "rule_details": {} }
Attribute
|
transaction_id
string
ID of the Transaction
date
string
Transaction date.
amount
double
Amount of the transaction
transaction_type
string
Transaction Type of the transaction
status
string
Transaction status wise list view - All, uncategorized, manually_added, matched, excluded, categorized
source
string
Source of the transaction
account_id
string
Mandatory Account id for which transactions are to be listed.
account_name
string
Name of the Account
account_type
string
Type of the Account
price_precision
integer
Price Precision of the Values
customer_id
string
ID of the customer or vendor.
payee
string
Payee involved in the transaction
is_paid_via_print_check
US and CA Edition Only
boolean
Is the entity paid via print check
description
string
A brief description about the transaction.
currency_id
string
The currency ID involved in the transaction.
currency_code
string
Code of the currency involved in the transaction
currency_symbol
string
Symbol of the currency involved in the transaction
debit_or_credit
string
Indicates if transaction is Credit or Debit
offset_account_name
string
Name of the Offset Account
is_offsetaccount_matched
boolean
Check if Offset Account is matched
reference_number
string
Reference Number of the transaction
imported_transaction_id
long
ID of the Imported Transaction
is_rule_exist
boolean
Check if rule exists for the transaction
rule_details
object
Details of the Rule
|
Create a transaction for an account
Create a bank transaction based on the allowed transaction types.
POST /banktransactions
Request Example
$ curl https://books.zoho.com/api/v3/banktransactions?organization_id=10234695 -H "Authorization: Zoho-authtoken ba4604e8e433g9c892e360d53463oec5" -H "Content-Type: application/json;charset=UTF-8" -d '{ "from_account_id": "460000000070003", "to_account_id": "460000000048001", "transaction_type": "deposit", "amount": 2000, "payment_mode": "Cash", "exchange_rate": 1, "date": "2013-10-01", "customer_id": "460000000000111", "reference_number": "Ref-121", "currency_id": "460000000000097", "is_inclusive_tax": false, "tags": [ {} ], "from_account_tags": [ {} ], "to_account_tags": [ {} ], "documents": [ {} ], "bank_charges": 0, "custom_fields": [ {} ] }
Response Example
HTTP/1.1 201 Created Content-Type:application/json;charset=UTF-8 { "code": 0, "message": "The bank transaction has been recorded.", "banktransaction": { "transaction_id": "460000000048017", "from_account_id": "460000000070003", "from_account_name": "Sales", "to_account_id": "460000000048001", "to_account_name": "Corporate Account", "transaction_type": "deposit", "currency_id": "460000000000097", "currency_code": "USD", "payment_mode": "Cash", "exchange_rate": 1, "date": "2013-10-01", "customer_id": "460000000000111", "vendor_id": "460000000026049", "vendor_name": "Bowmen and co", "reference_number": "Ref-121", "bank_charges": 0, "documents": [ {...} ], "is_inclusive_tax": false, "tax_percentage": 0, "tax_amount": 0, "sub_total": 33, "total": 33, "bcy_total": 33, "amount": 2000, "imported_transactions": [ { "imported_transaction_id": "460000000013297", "date": "2013-10-01", "amount": 2000, "payee": "Smith", "reference_number": "Ref-121", "status": "categorized", "account_id": "460000000048001" } ], "tags": [ {...} ], "line_items": [ { "from_account_id": "460000000070003", "from_account_name": "Sales", "payment_mode": "Cash", "customer_id": "460000000000111", "vendor_id": "460000000026049", "vendor_name": "Bowmen and co", "sub_total": 33, "total": 33, "bcy_total": 33, "tags": [ {...} ] } ] } }
ARGUMENTS
|
from_account_id
Optional
The account ID from which money will
be transferred(Mandatory for specific type of transactions). These
accounts differ with respect to transaction_type. Ex: To a bank account,
from-account can be: bank , card, income, refund. To a card account,
from account can be: bank, card, refund.
to_account_id
Optional
ID of the account to which the money
gets transferred(Mandatory for specific type of transactions). Ex: From a
bank account, to-account can be: bank, card, drawings, expense,credit
notes. From a card account, to-account can be: card, bank, expense.
transaction_type
Required
Transaction Type of the transaction
amount
Optional
Amount of the transaction
payment_mode
Optional
Mode of payment for the transaction. (not applicable for transfer_fund, card_payment, owner_drawings). Ex:cash, cheque, etc.,
exchange_rate
Optional
The foreign currency exchange rate value.
date
Optional
Transaction date.
customer_id
Optional
ID of the customer or vendor.
reference_number
Optional
Reference Number of the transaction
description
Optional
A brief description about the transaction.
currency_id
Optional
The currency ID involved in the transaction.
tax_id
Not applicable for the US Edition.
Optional
ID of the tax or tax group applied
is_inclusive_tax
Optional
Check if transaction is tax Inclusive
tags
Optional
from_account_tags
Optional
to_account_tags
Optional
documents
Optional
bank_charges
Optional
Bank Charges applied to the transaction
user_id
Optional
ID of the User involved in the Transaction
tax_authority_id
US, AU and CA Editions Only
Optional
ID of the Tax Authority
tax_exemption_id
Inida, US, AU and CA Editions Only
Optional
ID of the Tax Exemption
custom_fields
Optional
custom_field_id
Optional
index
Optional
Index of the custom field
label
Optional
Label of the Custom Field
value
Optional
Value of the Custom Field
|
Update a transaction
Make changes in the applicable fields of a transaction and update it.
PUT /banktransactions/{bank_transaction_id}
Request Example
$ curl https://books.zoho.com/api/v3/banktransactions/{bank_transaction_id}?organization_id=10234695 -H "Authorization: Zoho-authtoken ba4604e8e433g9c892e360d53463oec5" -H "Content-Type: application/json;charset=UTF-8" -d '{ "from_account_id": "460000000070003", "to_account_id": "460000000048001", "transaction_type": "deposit", "amount": 2000, "payment_mode": "Cash", "exchange_rate": 1, "date": "2013-10-01", "customer_id": "460000000000111", "reference_number": "Ref-121", "currency_id": "460000000000097", "is_inclusive_tax": false, "tags": [ {} ], "from_account_tags": [ {} ], "to_account_tags": [ {} ], "documents": [ {} ], "bank_charges": 0, "custom_fields": [ {} ], "line_items": [ { "line_id": "46000000001234", "account_id": "460000000048001", "account_name": "Petty Cash", "tax_amount": 0, "tax_type": "tax", "tax_percentage": 0, "item_total": 7500, "item_total_inclusive_of_tax": 7500, "item_order": 1, "tags": [ {} ] } ] }
Response Example
HTTP/1.1 200 OK Content-Type:application/json;charset=UTF-8 { "code": 0, "message": "The bank transaction has been updated.", "banktransaction": { "transaction_id": "460000000048017", "from_account_id": "460000000070003", "from_account_name": "Sales", "to_account_id": "460000000048001", "to_account_name": "Corporate Account", "transaction_type": "deposit", "currency_id": "460000000000097", "currency_code": "USD", "payment_mode": "Cash", "exchange_rate": 1, "date": "2013-10-01", "customer_id": "460000000000111", "vendor_id": "460000000026049", "vendor_name": "Bowmen and co", "reference_number": "Ref-121", "bank_charges": 0, "documents": [ {...} ], "is_inclusive_tax": false, "tax_percentage": 0, "tax_amount": 0, "sub_total": 33, "total": 33, "bcy_total": 33, "amount": 2000, "imported_transactions": [ { "imported_transaction_id": "460000000013297", "date": "2013-10-01", "amount": 2000, "payee": "Smith", "reference_number": "Ref-121", "status": "categorized", "account_id": "460000000048001" } ], "tags": [ {...} ], "line_items": [ { "from_account_id": "460000000070003", "from_account_name": "Sales", "payment_mode": "Cash", "customer_id": "460000000000111", "vendor_id": "460000000026049", "vendor_name": "Bowmen and co", "sub_total": 33, "total": 33, "bcy_total": 33, "tags": [ {...} ] } ] } }
ARGUMENTS
|
from_account_id
Optional
The account ID from which money will
be transferred(Mandatory for specific type of transactions). These
accounts differ with respect to transaction_type. Ex: To a bank account,
from-account can be: bank , card, income, refund. To a card account,
from account can be: bank, card, refund.
to_account_id
Optional
ID of the account to which the money
gets transferred(Mandatory for specific type of transactions). Ex: From a
bank account, to-account can be: bank, card, drawings, expense,credit
notes. From a card account, to-account can be: card, bank, expense.
transaction_type
Required
Transaction Type of the transaction
amount
Optional
Amount of the transaction
payment_mode
Optional
Mode of payment for the transaction. (not applicable for transfer_fund, card_payment, owner_drawings). Ex:cash, cheque, etc.,
exchange_rate
Optional
The foreign currency exchange rate value.
date
Optional
Transaction date.
customer_id
Optional
ID of the customer or vendor.
reference_number
Optional
Reference Number of the transaction
description
Optional
A brief description about the transaction.
currency_id
Optional
The currency ID involved in the transaction.
tax_id
Not applicable for the US Edition.
Optional
ID of the tax or tax group applied
is_inclusive_tax
Optional
Check if transaction is tax Inclusive
tags
Optional
from_account_tags
Optional
to_account_tags
Optional
documents
Optional
bank_charges
Optional
Bank Charges applied to the transaction
user_id
Optional
ID of the User involved in the Transaction
tax_authority_id
US, AU and CA Editions Only
Optional
ID of the Tax Authority
tax_exemption_id
Inida, US, AU and CA Editions Only
Optional
ID of the Tax Exemption
custom_fields
Optional
custom_field_id
Optional
index
Optional
Index of the custom field
label
Optional
Label of the Custom Field
value
Optional
Value of the Custom Field
line_items
Optional
line_id
Optional
ID of the Line in Bank Transactions
account_id
Optional
Mandatory Account id for which transactions are to be listed.
account_name
Optional
Name of the Account
description
Optional
A brief description about the transaction.
tax_amount
Optional
Amount of Tax
tax_id
Not applicable for the US Edition.
Optional
ID of the tax or tax group applied
tax_name
Optional
Name of the Tax
tax_type
Optional
tax_percentage
Optional
Percentage of the Tax
item_total
Optional
Total of the Item
item_total_inclusive_of_tax
Optional
Total of the Item inclusive of Tax
item_order
Optional
Order of the Item
tags
Optional
|
Get transaction
Fetch the details of a transaction by specifying the transaction_id.
GET /banktransactions/{transaction_id}
Request Example
$ curl https://books.zoho.com/api/v3/banktransactions/{transaction_id}?organization_id=10234695 -H "Authorization: Zoho-authtoken ba4604e8e433g9c892e360d53463oec5" -H "Content-Type: application/json;charset=UTF-8"
Response Example
HTTP/1.1 200 OK Content-Type:application/json;charset=UTF-8 { "code": 0, "message": "success", "banktransaction": { "transaction_id": "460000000048017", "from_account_id": "460000000070003", "from_account_name": "Sales", "to_account_id": "460000000048001", "to_account_name": "Corporate Account", "transaction_type": "deposit", "currency_id": "460000000000097", "currency_code": "USD", "payment_mode": "Cash", "exchange_rate": 1, "date": "2013-10-01", "customer_id": "460000000000111", "vendor_id": "460000000026049", "vendor_name": "Bowmen and co", "reference_number": "Ref-121", "bank_charges": 0, "documents": [ {...} ], "is_inclusive_tax": false, "tax_percentage": 0, "tax_amount": 0, "sub_total": 33, "total": 33, "bcy_total": 33, "amount": 2000, "imported_transactions": [ { "imported_transaction_id": "460000000013297", "date": "2013-10-01", "amount": 2000, "payee": "Smith", "reference_number": "Ref-121", "status": "categorized", "account_id": "460000000048001" } ], "tags": [ {...} ], "line_items": [ { "from_account_id": "460000000070003", "from_account_name": "Sales", "payment_mode": "Cash", "customer_id": "460000000000111", "vendor_id": "460000000026049", "vendor_name": "Bowmen and co", "sub_total": 33, "total": 33, "bcy_total": 33, "tags": [ {...} ] } ] } }
Get transactions list
Get all the transaction details involved in an account.
GET /banktransactions
Request Example
$ curl https://books.zoho.com/api/v3/banktransactions?organization_id=10234695 -H "Authorization: Zoho-authtoken ba4604e8e433g9c892e360d53463oec5" -H "Content-Type: application/json;charset=UTF-8"
Response Example
HTTP/1.1 200 OK Content-Type:application/json;charset=UTF-8 { "code": 0, "message": "success", "banktransactions": [ { "transaction_id": "460000000048017", "date": "2013-10-01", "amount": 2000, "transaction_type": "deposit", "status": "categorized", "source": "manually_added", "account_id": "460000000048001", "account_name": "Petty Cash", "account_type": "cash", "price_precision": 2, "customer_id": "460000000000111", "payee": "Smith", "is_paid_via_print_check": false, "currency_id": "460000000000097", "currency_code": "USD", "currency_symbol": "$", "debit_or_credit": "debit", "offset_account_name": "Petty Cash", "is_offsetaccount_matched": false, "reference_number": "Ref-121", "imported_transaction_id": "460000000013297", "is_rule_exist": false, "rule_details": {...} }, {...}, {...} ] }
Query Params
|
account_id
Optional
Mandatory Account id for which transactions are to be listed.
transaction_type
Optional
Transaction Type of the transaction
date
Optional
Start and end date, to provide a range within which the transaction date exist. Variants:
date_start and date_end
amount
Optional
Start and end amount, to provide a range within which the transaction amount exist. Variants:
amount_start and amount_end
status
Optional
Transaction status wise list view - All, uncategorized, manually_added, matched, excluded, categorized
reference_number
Optional
Search using Reference Number of the transaction
filter_by
Optional
Filters the transactions based on the allowed types. Allowed Values:
Status.All, Status.Uncategorized, Status.Categorized, Status.ManuallyAdded, Status.Excluded and Status.Matched.
sort_column
Optional
Sorts the transactions based on the allowed sort types. Allowed Values:
date.
transaction_status
Optional
Transaction status wise list view - All, uncategorized, manually_added, matched, excluded, categorized
search_text
Optional
Search Transactions by contact name or description
|
Delete a transaction
Delete a transaction from an account by specifying the transaction_id.
DELETE /banktransactions/{transaction_id}
Request Example
$ curl https://books.zoho.com/api/v3/banktransactions/{transaction_id}?organization_id=10234695 -H "Authorization: Zoho-authtoken ba4604e8e433g9c892e360d53463oec5" -H "Content-Type: application/json;charset=UTF-8"
Response Example
HTTP/1.1 200 OK Content-Type:application/json;charset=UTF-8 { "code": 0, "message": "The transaction has been deleted." }
Get matching transactions
Provide criteria to search for matching uncategorised transactions. The list of transactions can also include invoices/bills/credit-notes which will not be matched directly. Instead, a new (payment/refund) transaction is recorded and matched.
GET /banktransactions/uncategorized/{transaction_id}/match
Request Example
$ curl https://books.zoho.com/api/v3/banktransactions/uncategorized/{transaction_id}/match?organization_id=10234695 -H "Authorization: Zoho-authtoken ba4604e8e433g9c892e360d53463oec5" -H "Content-Type: application/json;charset=UTF-8"
Response Example
HTTP/1.1 200 OK Content-Type:application/json;charset=UTF-8 { "code": 0, "message": "success", "matching_transactions": [ { "transaction_id": "460000000048017", "date": "2013-10-01", "transaction_type": "deposit", "reference_number": "Ref-121", "amount": 2000, "debit_or_credit": "debit", "transaction_number": "INV-000007", "is_paid_via_print_check": false, "contact_name": "Bowman and co", "is_best_match": true }, {...}, {...} ] }
Query Params
|
transaction_id
Optional
ID of the Transaction
transaction_type
Optional
Transaction Type of the transaction
date_after
Optional
Date after which Transactions are to be filtered
date_before
Optional
Date before which Transactions are to be filtered
amount_start
Optional
Starting amout with which transactions are to be filtered
amount_end
Optional
Starting amout with which transactions are to be filtered
contact
Optional
Contact person name, involved in the transaction.
reference_number
Optional
Reference Number of the transaction
show_all_transactions
Optional
Check if all transactions must be shown
|
Match a transaction
Match an uncategorized transaction with an existing transaction in the account.
POST /banktransactions/uncategorized/{transaction_id}/match
Request Example
$ curl https://books.zoho.com/api/v3/banktransactions/uncategorized/{transaction_id}/match?organization_id=10234695 -H "Authorization: Zoho-authtoken ba4604e8e433g9c892e360d53463oec5" -H "Content-Type: application/json;charset=UTF-8" -d '{ "transactions_to_be_matched": [ { "transaction_id": "460000000048017", "transaction_type": "deposit" } ] }
Response Example
HTTP/1.1 201 Created Content-Type:application/json;charset=UTF-8 { "code": 0, "message": "The transaction has been matched." }
ARGUMENTS
|
transactions_to_be_matched
Optional
transaction_id
Optional
ID of the Transaction
transaction_type
Optional
Transaction Type of the transaction
|
Query Params
|
account_id
Optional
Mandatory Account id for which transactions are to be listed.
|
Unmatch a matched transaction
Unmatch a transaction that was previously matched and make it uncategorized.
POST /banktransactions/{transaction_id}/unmatch
Request Example
$ curl https://books.zoho.com/api/v3/banktransactions/{transaction_id}/unmatch?organization_id=10234695 -H "Authorization: Zoho-authtoken ba4604e8e433g9c892e360d53463oec5" -H "Content-Type: application/json;charset=UTF-8"
Response Example
HTTP/1.1 201 Created Content-Type:application/json;charset=UTF-8 { "code": 0, "message": "The transaction has been unmatched." }
Query Params
|
account_id
Optional
Mandatory Account id for which transactions are to be listed.
|
Exclude a transaction
Exclude a transaction from your bank or credit card account.
POST /banktransactions/uncategorized/{transaction_id}/exclude
Request Example
$ curl https://books.zoho.com/api/v3/banktransactions/uncategorized/{transaction_id}/exclude?organization_id=10234695 -H "Authorization: Zoho-authtoken ba4604e8e433g9c892e360d53463oec5" -H "Content-Type: application/json;charset=UTF-8"
Response Example
HTTP/1.1 201 Created Content-Type:application/json;charset=UTF-8 { "code": 0, "message": "The transaction has been excluded." }
Query Params
|
account_id
Optional
Mandatory Account id for which transactions are to be listed.
|
Restore a transaction
Restore an excluded transaction in your account.
POST /banktransactions/uncategorized/{transaction_id}/restore
Request Example
$ curl https://books.zoho.com/api/v3/banktransactions/uncategorized/{transaction_id}/restore?organization_id=10234695 -H "Authorization: Zoho-authtoken ba4604e8e433g9c892e360d53463oec5" -H "Content-Type: application/json;charset=UTF-8"
Response Example
HTTP/1.1 201 Created Content-Type:application/json;charset=UTF-8 { "code": 0, "message": "The excluded transaction(s) have been restored." }
Query Params
|
account_id
Optional
Mandatory Account id for which transactions are to be listed.
|
Categorize an uncategorized transaction
Categorize an uncategorized transaction by creating a new transaction.
POST /banktransactions/uncategorized/{transaction_id}/categorize
Request Example
$ curl https://books.zoho.com/api/v3/banktransactions/uncategorized/{transaction_id}/categorize?organization_id=10234695 -H "Authorization: Zoho-authtoken ba4604e8e433g9c892e360d53463oec5" -H "Content-Type: application/json;charset=UTF-8" -d '{ "from_account_id": "460000000070003", "to_account_id": "460000000048001", "transaction_type": "deposit", "amount": 2000, "date": "2013-10-01", "reference_number": "Ref-121", "payment_mode": "Cash", "exchange_rate": 1, "customer_id": "460000000000111", "tags": [ {} ], "documents": [ {} ], "currency_id": "460000000000097", "to_account_tags": [ {} ], "from_account_tags": [ {} ], "is_inclusive_tax": false, "bank_charges": 0, "custom_fields": [ {} ], "line_items": [ { "line_id": "46000000001234", "account_id": "460000000048001", "account_name": "Petty Cash", "tax_amount": 0, "tax_type": "tax", "tax_percentage": 0, "item_total": 7500, "item_total_inclusive_of_tax": 7500, "item_order": 1, "tags": [ {} ] } ] }
Response Example
HTTP/1.1 201 Created Content-Type:application/json;charset=UTF-8 { "code": 0, "message": "The transaction(s) have been categorized." }
ARGUMENTS
|
from_account_id
Optional
The account ID from which money will
be transferred(Mandatory for specific type of transactions). These
accounts differ with respect to transaction_type. Ex: To a bank account,
from-account can be: bank , card, income, refund. To a card account,
from account can be: bank, card, refund.
to_account_id
Optional
ID of the account to which the money
gets transferred(Mandatory for specific type of transactions). Ex: From a
bank account, to-account can be: bank, card, drawings, expense,credit
notes. From a card account, to-account can be: card, bank, expense.
transaction_type
Required
Transaction Type of the transaction
amount
Optional
Amount of the transaction
date
Optional
Transaction date.
reference_number
Optional
Reference Number of the transaction
payment_mode
Optional
Mode of payment for the transaction. (not applicable for transfer_fund, card_payment, owner_drawings). Ex:cash, cheque, etc.,
exchange_rate
Optional
The foreign currency exchange rate value.
description
Optional
A brief description about the transaction.
customer_id
Optional
ID of the customer or vendor.
tags
Optional
documents
Optional
currency_id
Optional
The currency ID involved in the transaction.
tax_id
Not applicable for the US Edition.
Optional
ID of the tax or tax group applied
tags
Optional
to_account_tags
Optional
from_account_tags
Optional
is_inclusive_tax
Optional
Check if transaction is tax Inclusive
bank_charges
Optional
Bank Charges applied to the transaction
user_id
Optional
ID of the User involved in the Transaction
tax_authority_id
US, AU and CA Editions Only
Optional
ID of the Tax Authority
tax_exemption_id
Inida, US, AU and CA Editions Only
Optional
ID of the Tax Exemption
custom_fields
Optional
custom_field_id
Optional
index
Optional
Index of the custom field
label
Optional
Label of the Custom Field
value
Optional
Value of the Custom Field
line_items
Optional
line_id
Optional
ID of the Line in Bank Transactions
account_id
Optional
Mandatory Account id for which transactions are to be listed.
account_name
Optional
Name of the Account
description
Optional
A brief description about the transaction.
tax_amount
Optional
Amount of Tax
tax_id
Not applicable for the US Edition.
Optional
ID of the tax or tax group applied
tax_name
Optional
Name of the Tax
tax_type
Optional
tax_percentage
Optional
Percentage of the Tax
item_total
Optional
Total of the Item
item_total_inclusive_of_tax
Optional
Total of the Item inclusive of Tax
item_order
Optional
Order of the Item
tags
Optional
|
Categorize as expense
Categorize an Uncategorized transaction as expense
POST /banktransactions/uncategorized/{transaction_id}/categorize/expenses
Request Example
$ curl https://books.zoho.com/api/v3/banktransactions/uncategorized/{transaction_id}/categorize/expenses?organization_id=10234695 -H "Authorization: Zoho-authtoken ba4604e8e433g9c892e360d53463oec5" -H "Content-Type: application/json;charset=UTF-8" -d '{ "account_id": "460000000048001", "paid_through_account_id": "460000000000358", "date": "2013-10-01", "amount": 2000, "is_inclusive_tax": false, "reference_number": "Ref-121", "customer_id": "460000000000111", "vendor_id": "460000000026049", "mileage_unit": "km", "mileage_rate": 0, "mileage_type": "non_mileage", "expense_type": "non_mileage", "distance": 4, "currency_id": "460000000000097", "custom_fields": [ {} ], "tags": [ {} ], "documents": [ {} ], "exchange_rate": 1, "is_update_customer": false, "taxes": [ { "tax_amount": 0 } ], "line_items": [ { "line_item_id": "460000000012834", "account_id": "460000000048001", "amount": 2000, "item_order": 1, "tags": [ {} ] } ] }
Response Example
HTTP/1.1 201 Created Content-Type:application/json;charset=UTF-8 { "code": 0, "message": "The transaction(s) have been categorized." }
ARGUMENTS
|
account_id
Optional
Mandatory Account id for which transactions are to be listed.
paid_through_account_id
Optional
ID of the credit/ bank account the payment is made.
date
Optional
Transaction date.
tax_id
Not applicable for the US Edition.
Optional
ID of the tax or tax group applied
amount
Optional
Amount of the transaction
project_id
Optional
ID of the project associated with the expense.
tax_exemption_code
Inida, US, AU and CA Editions Only
Optional
Code of the Tax Exemption
tax_exemption_id
Inida, US, AU and CA Editions Only
Optional
ID of the Tax Exemption
is_inclusive_tax
Optional
Check if transaction is tax Inclusive
is_billable
Optional
A boolean value to specify if the expense is billable.
reference_number
Optional
Reference Number of the transaction
description
Optional
A brief description about the transaction.
customer_id
Optional
ID of the customer or vendor.
zp_project_id
Optional
ID of the Project
zp_project_name
Optional
Name of the Project
zp_client_id
Optional
ID of client
vendor_id
Optional
ID of the Vendor
vehicle_id
Optional
ID of the Vehicle
mileage_unit
Optional
Unit of Mileage
mileage_rate
Optional
Mileage Rate to be Applied
can_reclaim_vat_on_mileage
UK and EU Versions Only
Optional
Check if VAT can be reclaimed on mileage
fuel_type
UK and EU Edition Only
Optional
Type of Fuel Used. Allowed Values :
petrol, lpg, diesel
engine_capacity_range
UK and EU Edition Only
Optional
Type of Fuel Used. Allowed Values :
less_than_1400cc, between_1401cc_and_1600cc, between_1601cc_and_2000cc and more_than_2000cc
claimant_id
Optional
ID of the Claimant
mileage_type
Optional
Type of Mileage. Allowed Values :
gmaps,imaps,gps,odometer,wmaps,manual,non_mileage and per_diem
expense_type
Optional
Type of Expense
distance
Optional
Distance Covered
start_reading
Optional
Start Reading of the Odometer
end_reading
Optional
End Reading of the Odometer
currency_id
Optional
The currency ID involved in the transaction.
custom_fields
Optional
index
Optional
Index of the custom field
value
Optional
Value of the Custom Field
tags
Optional
documents
Optional
exchange_rate
Optional
The foreign currency exchange rate value.
recurring_expense_id
Optional
ID of the Recurring Expense
vat_treatment
UK and EU Edition only
Optional
VAT treatment for the bank
transaction. VAT treatment denotes the location of the customer or
vendor. If the customer or vendor resides in the UK then the VAT
treatment is
uk. If the customer or vendor is in an EU country and if he has VAT registered, then his VAT treatment is eu_vat_registered. If he resides in EU and if he is not VAT registered, then his VAT treatment is eu_vat_not_registered. And, if he resides outside the EU then his VAT treatment is non_eu.
acquisition_vat_id
UK and EU Edition only
Optional
(Optional) This is the ID of the tax
applied in case this is an EU - goods purchase or expense and
acquisition VAT needs to be reported.
reverse_charge_vat_id
UK and EU Edition only
Optional
(Optional) This is the ID of the tax
applied in case this is a non UK - service purchase or expense and
reverse charge VAT needs to be reported.
is_update_customer
Optional
Check if Customer should be updated
product_type
UK and EU Edition only
Optional
Type of the transaction. This denotes
whether the transaction line item is to be treated as goods or as a
service. Allowed Values:
goods, service and digital_service .
taxes
Optional
tax_name
Optional
Name of the Tax
tax_amount
Optional
Amount of Tax
tax_id
Not applicable for the US Edition.
Optional
ID of the tax or tax group applied
reason
Optional
Reason
line_items
Optional
line_item_id
Optional
ID of the Line Item
account_id
Optional
Mandatory Account id for which transactions are to be listed.
description
Optional
A brief description about the transaction.
amount
Optional
Amount of the transaction
tax_id
Not applicable for the US Edition.
Optional
ID of the tax or tax group applied
item_order
Optional
Order of the Item
product_type
UK and EU Edition only
Optional
Type of the transaction. This denotes
whether the transaction line item is to be treated as goods or as a
service. Allowed Values:
goods, service and digital_service .
acquisition_vat_id
UK and EU Edition only
Optional
(Optional) This is the ID of the tax
applied in case this is an EU - goods purchase or expense and
acquisition VAT needs to be reported.
reverse_charge_vat_id
UK and EU Edition only
Optional
(Optional) This is the ID of the tax
applied in case this is a non UK - service purchase or expense and
reverse charge VAT needs to be reported.
tax_exemption_code
Inida, US, AU and CA Editions Only
Optional
Code of the Tax Exemption
tax_exemption_id
Inida, US, AU and CA Editions Only
Optional
ID of the Tax Exemption
tags
Optional
zcrm_potential_id
Optional
|
Query Params
|
doc
Optional
Document that is to be attached
totalFiles
Optional
Total number of files.
document_ids
Optional
|
Uncategorize a categorized transaction
Revert a categorized transaction as uncategorized.
POST /banktransactions/{transaction_id}/uncategorize
Request Example
$ curl https://books.zoho.com/api/v3/banktransactions/{transaction_id}/uncategorize?organization_id=10234695 -H "Authorization: Zoho-authtoken ba4604e8e433g9c892e360d53463oec5" -H "Content-Type: application/json;charset=UTF-8"
Response Example
HTTP/1.1 201 Created Content-Type:application/json;charset=UTF-8 { "code": 0, "message": "Transaction(s) have been uncategorized." }
Query Params
|
account_id
Optional
Mandatory Account id for which transactions are to be listed.
|
Categorize a vendor payment
Categorize an uncategorized transaction as Vendor Payment.
POST /banktransactions/uncategorized/{transaction_id}/categorize/vendorpayments
Request Example
$ curl https://books.zoho.com/api/v3/banktransactions/uncategorized/{transaction_id}/categorize/vendorpayments?organization_id=10234695 -H "Authorization: Zoho-authtoken ba4604e8e433g9c892e360d53463oec5" -H "Content-Type: application/json;charset=UTF-8" -d '{ "vendor_id": "460000000026049", "bills": [ { "bill_id": "460000000053199", "amount_applied": 150, "tax_amount_withheld": 0 } ], "payment_mode": "Cash", "date": "2013-10-01", "reference_number": "Ref-121", "exchange_rate": 1, "paid_through_account_id": "460000000000358", "amount": 2000, "custom_fields": [ {} ], "is_paid_via_print_check": false, "check_details": [ {} ] }
Response Example
HTTP/1.1 201 Created Content-Type:application/json;charset=UTF-8 { "code": 0, "message": "The transaction(s) have been categorized." }
ARGUMENTS
|
vendor_id
Optional
ID of the Vendor
bills
Optional
bill_payment_id
Optional
ID of the Bill Payment
bill_id
Optional
ID of the Bill
amount_applied
Optional
Amount applied to the Entity
tax_amount_withheld
Optional
payment_mode
Optional
Mode of payment for the transaction. (not applicable for transfer_fund, card_payment, owner_drawings). Ex:cash, cheque, etc.,
description
Optional
A brief description about the transaction.
date
Optional
Transaction date.
reference_number
Optional
Reference Number of the transaction
exchange_rate
Optional
The foreign currency exchange rate value.
paid_through_account_id
Optional
ID of the credit/ bank account the payment is made.
amount
Optional
Amount of the transaction
custom_fields
Optional
index
Optional
Index of the custom field
value
Optional
Value of the Custom Field
is_paid_via_print_check
US and CA Edition Only
Optional
Is the entity paid via print check
check_details
Optional
memo
Optional
check_number
Optional
Number of the Check Created
|
Categorize as customer payment
Categorize an uncategorized transaction as Customer Payment.
POST /banktransactions/uncategorized/{transaction_id}/categorize/customerpayments
Request Example
$ curl https://books.zoho.com/api/v3/banktransactions/uncategorized/{transaction_id}/categorize/customerpayments?organization_id=10234695 -H "Authorization: Zoho-authtoken ba4604e8e433g9c892e360d53463oec5" -H "Content-Type: application/json;charset=UTF-8" -d '{ "customer_id": "460000000000111", "invoices": [ { "invoice_payment_id": "460000000134123", "invoice_id": "460000000000481", "amount_applied": 150, "tax_amount_withheld": 0, "discount_amount": 20 } ], "payment_mode": "Cash", "reference_number": "Ref-121", "exchange_rate": 1, "amount": 2000, "bank_charges": 0, "account_id": "460000000048001", "custom_fields": [ {} ], "documents": [ {} ], "date": "2013-10-01", "contact_persons": [ "460000000870911", "460000000870915" ] }
Response Example
HTTP/1.1 201 Created Content-Type:application/json;charset=UTF-8 { "code": 0, "message": "The transaction(s) have been categorized." }
ARGUMENTS
|
customer_id
Optional
ID of the customer or vendor.
retainerinvoice_id
Optional
ID of the Retainer Invoice
invoices
Optional
invoice_payment_id
Optional
ID of the Invoice Payment
invoice_id
Optional
ID of the Invoice
amount_applied
Optional
Amount applied to the Entity
tax_amount_withheld
Optional
discount_amount
Optional
Amount of discount in the Invoice
payment_mode
Optional
Mode of payment for the transaction. (not applicable for transfer_fund, card_payment, owner_drawings). Ex:cash, cheque, etc.,
description
Optional
A brief description about the transaction.
reference_number
Optional
Reference Number of the transaction
exchange_rate
Optional
The foreign currency exchange rate value.
amount
Optional
Amount of the transaction
bank_charges
Optional
Bank Charges applied to the transaction
account_id
Optional
Mandatory Account id for which transactions are to be listed.
custom_fields
Optional
index
Optional
Index of the custom field
value
Optional
Value of the Custom Field
documents
Optional
date
Optional
Transaction date.
template_id
Optional
ID of the template
contact_persons
Optional
Array of contact person(s) for whom invoice has to be sent.
|
Categorize as credit note refunds
Categorize an Uncategorized transaction as a refund from a credit note.
POST /banktransactions/uncategorized/{transaction_id}/categorize/creditnoterefunds
Request Example
$ curl https://books.zoho.com/api/v3/banktransactions/uncategorized/{transaction_id}/categorize/creditnoterefunds?organization_id=10234695 -H "Authorization: Zoho-authtoken ba4604e8e433g9c892e360d53463oec5" -H "Content-Type: application/json;charset=UTF-8" -d '{ "creditnote_id": "4000000030049", "date": "2013-10-01", "refund_mode": "Cash", "reference_number": "Ref-121", "amount": 2000, "exchange_rate": 1, "from_account_id": "460000000070003" }
Response Example
HTTP/1.1 201 Created Content-Type:application/json;charset=UTF-8 { "code": 0, "message": "The transaction(s) have been categorized." }
ARGUMENTS
|
creditnote_id
Required
ID of the credit note that has to be refunded.
date
Required
Transaction date.
refund_mode
Optional
Mode of the Refund
reference_number
Optional
Reference Number of the transaction
amount
Optional
Amount of the transaction
exchange_rate
Optional
The foreign currency exchange rate value.
from_account_id
Optional
The account ID from which money will
be transferred(Mandatory for specific type of transactions). These
accounts differ with respect to transaction_type. Ex: To a bank account,
from-account can be: bank , card, income, refund. To a card account,
from account can be: bank, card, refund.
description
Optional
A brief description about the transaction.
|
Categorize as vendor credit refunds
Categorize an uncategorized transaction as a refund from a vendor credit.
POST /banktransactions/uncategorized/{transaction_id}/categorize/vendorcreditrefunds
Request Example
$ curl https://books.zoho.com/api/v3/banktransactions/uncategorized/{transaction_id}/categorize/vendorcreditrefunds?organization_id=10234695 -H "Authorization: Zoho-authtoken ba4604e8e433g9c892e360d53463oec5" -H "Content-Type: application/json;charset=UTF-8" -d '{ "vendor_credit_id": "460000000030049", "date": "2013-10-01", "refund_mode": "Cash", "reference_number": "Ref-121", "amount": 2000, "exchange_rate": 1, "account_id": "460000000048001" }
Response Example
HTTP/1.1 201 Created Content-Type:application/json;charset=UTF-8 { "code": 0, "message": "The transaction(s) have been categorized." }
ARGUMENTS
|
vendor_credit_id
Required
ID of the vendor credit that has to be refunded.
date
Required
Transaction date.
refund_mode
Optional
Mode of the Refund
reference_number
Optional
Reference Number of the transaction
amount
Optional
Amount of the transaction
exchange_rate
Optional
The foreign currency exchange rate value.
account_id
Optional
Mandatory Account id for which transactions are to be listed.
description
Optional
A brief description about the transaction.
|
Categorize as Customer Payment refund
Categorizing bank transactions as Payment Refund.
POST /banktransactions/uncategorized/{statement_line_id}/categorize/paymentrefunds
Request Example
$ curl https://books.zoho.com/api/v3/banktransactions/uncategorized/{statement_line_id}/categorize/paymentrefunds?organization_id=10234695 -H "Authorization: Zoho-authtoken ba4604e8e433g9c892e360d53463oec5" -H "Content-Type: application/json;charset=UTF-8" -d '{ "date": "2013-10-01", "refund_mode": "Cash", "reference_number": "Ref-121", "amount": 2000, "exchange_rate": 1, "from_account_id": "460000000070003" }
Response Example
HTTP/1.1 201 Created Content-Type:application/json;charset=UTF-8 { "code": 0, "message": "The transaction(s) have been categorized." }
ARGUMENTS
|
date
Required
Transaction date.
refund_mode
Optional
Mode of the Refund
reference_number
Optional
Reference Number of the transaction
amount
Required
Amount of the transaction
exchange_rate
Optional
The foreign currency exchange rate value.
from_account_id
Required
The account ID from which money will
be transferred(Mandatory for specific type of transactions). These
accounts differ with respect to transaction_type. Ex: To a bank account,
from-account can be: bank , card, income, refund. To a card account,
from account can be: bank, card, refund.
description
Optional
A brief description about the transaction.
|
Categorize as Vendor Payment refund
Categorizing bank transactions as Vendor Payment Refund.
POST /banktransactions/uncategorized/{statement_line_id}/categorize/vendorpaymentrefunds
Request Example
$ curl https://books.zoho.com/api/v3/banktransactions/uncategorized/{statement_line_id}/categorize/vendorpaymentrefunds?organization_id=10234695 -H "Authorization: Zoho-authtoken ba4604e8e433g9c892e360d53463oec5" -H "Content-Type: application/json;charset=UTF-8" -d '{ "vendorpayment_id": "460000000012345", "date": "2013-10-01", "refund_mode": "Cash", "reference_number": "Ref-121", "amount": 2000, "exchange_rate": 1, "to_account_id": "460000000048001" }
Response Example
HTTP/1.1 201 Created Content-Type:application/json;charset=UTF-8 { "code": 0, "message": "The transaction(s) have been categorized." }
ARGUMENTS
|
vendorpayment_id
Optional
Vendor Payment to which you want to record the refund.
date
Required
Transaction date.
refund_mode
Optional
Mode of the Refund
reference_number
Optional
Reference Number of the transaction
amount
Required
Amount of the transaction
exchange_rate
Optional
The foreign currency exchange rate value.
to_account_id
Required
ID of the account to which the money
gets transferred(Mandatory for specific type of transactions). Ex: From a
bank account, to-account can be: bank, card, drawings, expense,credit
notes. From a card account, to-account can be: card, bank, expense.
description
Optional
A brief description about the transaction.
|
Bank-Rules
In Zoho Books, you can automate the categorization of the bank feeds. The transaction rules feature in banking will help you in automatically identifying the bank transaction and categorizing it under the criteria provided by you.
Example
{ "rule_id": "460000000048005", "rule_name": "Minimum Deposit Rule", "rule_order": 0, "apply_to": "deposits", "criteria_type": "and", "record_as": "deposit", "account_id": "460000000000361", "account_name": "Petty Cash", "criterion": [ { "criteria_id": "460000000048009", "field": "amount", "comparator": "greater_than_or_equals", "value": "500.00" } ] }
Attribute
|
rule_id
string
ID of the Rule
rule_name
string
Name of the Rule
rule_order
integer
Order of the rule
apply_to
string
Entities to which Rule must be applied
criteria_type
string
Type of Criteria
record_as
string
Entity as which it should be recorded
account_id
string
Account ID of the Bank
account_name
string
Name of the account
criterion
list
criteria_id
string
ID of the Criteria
field
string
Field involved in the Criteria
comparator
string
Comparator used in Criteria
value
string
Value to be compared with
|
Get Rules List
Fetch all the rules created for a specified bank or credit card account ID
GET /bankaccounts/rules
Request Example
$ curl https://books.zoho.com/api/v3/bankaccounts/rules?organization_id=10234695 -H "Authorization: Zoho-authtoken ba4604e8e433g9c892e360d53463oec5" -H "Content-Type: application/json;charset=UTF-8"
Response Example
HTTP/1.1 200 OK Content-Type:application/json;charset=UTF-8 { "code": 0, "message": "success", "rules": [ { "rule_id": "460000000048005", "rule_name": "Minimum Deposit Rule", "rule_order": 0, "apply_to": "deposits", "criteria_type": "and", "record_as": "deposit", "account_id": "460000000000361", "account_name": "Petty Cash", "criterion": [ { "criteria_id": "460000000048009", "field": "amount", "comparator": "greater_than_or_equals", "value": "500.00" } ] }, {...}, {...} ] }
Query Params
|
account_id
Required
ID of the Bank Account
|
Get a rule
Get details of a specific rule.
GET /bankaccounts/rules/{rule_id}
Request Example
$ curl https://books.zoho.com/api/v3/bankaccounts/rules/{rule_id}?organization_id=10234695 -H "Authorization: Zoho-authtoken ba4604e8e433g9c892e360d53463oec5" -H "Content-Type: application/json;charset=UTF-8"
Response Example
HTTP/1.1 200 OK Content-Type:application/json;charset=UTF-8 { "code": 0, "message": "success", "rule_id": "460000000048005", "rule_name": "Minimum Deposit Rule", "rule_order": 0, "apply_to": "deposits", "criteria_type": "and", "criterion": [ { "criteria_id": "460000000048009", "field": "amount", "comparator": "greater_than_or_equals", "value": "500.00" } ], "record_as": "deposit", "account_id": "460000000000361", "account_name": "Petty Cash", "tax_id": "460000000048238", "customer_id": "46000000000111", "customer_name": "Trendz", "reference_number": "from_statement", "payment_mode": "Cash" }
Create a rule
Create a rule and apply it on deposit/withdrawal for bank accounts and on refund/charges for credit card accounts.
POST /bankaccounts/rules
Request Example
$ curl https://books.zoho.com/api/v3/bankaccounts/rules?organization_id=10234695 -H "Authorization: Zoho-authtoken ba4604e8e433g9c892e360d53463oec5" -H "Content-Type: application/json;charset=UTF-8" -d '{ "rule_name": "Minimum Deposit Rule", "target_account_id": 460000000048001, "apply_to": "deposits", "criteria_type": "and", "criterion": [ { "field": "amount", "comparator": "greater_than_or_equals", "value": "500.00" } ], "record_as": "deposit", "account_id": 460000000049001, "customer_id": 46000000000111, "tax_id": "460000000048238", "reference_number": "manual" }
Response Example
HTTP/1.1 201 Created Content-Type:application/json;charset=UTF-8 { "code": 0, "message": "The bank rule has been created.", "rule": { "rule_id": "460000000048005", "rule_name": "Minimum Deposit Rule", "rule_order": 0, "apply_to": "deposits", "criteria_type": "and", "criterion": [ { "criteria_id": "460000000048009", "field": "amount", "comparator": "greater_than_or_equals", "value": "500.00" } ], "record_as": "deposit", "account_id": "460000000000361", "account_name": "Petty Cash", "tax_id": "460000000048238", "customer_id": "46000000000111", "customer_name": "Trendz", "reference_number": "from_statement", "payment_mode": "Cash" } }
ARGUMENTS
|
rule_name
Required
Name of the Rule
target_account_id
Required
The account on which the rule has to be applied.
apply_to
Required
Rule applies to either deposits or
withdrawals for bank accounts and to refunds or charges for credit card
account. Allowed Values :
withdrawals, deposits, refunds and charges.
criteria_type
Required
Specifies whether all the criteria have to be satisfied or not. Allowed Values :
and and or
criterion
Required
field
Optional
Field involved in the Criteria
comparator
Optional
Comparator used in Criteria
value
Optional
Value to be compared with
record_as
Required
Record transaction based on value
specified in apply_to node. For bank accounts: If apply_to is deposits:
sales_without_invoices, transfer_fund, interest_income, other_income,
expense_refund, deposit. If apply_to is withdrawals: expense,
transfer_fund, card_payment, owner_drawings. For credit_card accounts:
If apply_to is refunds: card_payment, transfer_fund, expense_refund,
refund. If apply_to is charges: expense, transfer_fund. Allowed Values:
expense, deposit, refund, transfer_fund, card_payment, sales_without_invoices, expense_refund, interest_income, other_income and owner_drawings
account_id
Optional
Account which is involved in the rule with the target account.
customer_id
Optional
ID of the customer.(Applicable for sales_without_invoices,deposit, expense)
tax_id
Optional
Tax ID involved in the transaction.
reference_number
Optional
Specifies if Reference number is manual or generated from the statement. Allowed Values:
manual and from_statement
vat_treatment
UK and EU Edition Only
Optional
Vat Treatment Associated with the Rule
product_type
UK and EU Edition Only
Optional
Product Type associated with the Rule. Allowed values:
goods or service or digital_service.
tax_authority_id
US Edition Only
Optional
ID of the Tax Authority Associated with the Rule
tax_exemption_id
Inida Edition and US Edition Only
Optional
ID of the Tax Exemption Associated with the Rule
|
Update a rule
Make changes to the rule, add or modify it and update.
PUT /bankaccounts/rules/{rule_id}
Request Example
$ curl https://books.zoho.com/api/v3/bankaccounts/rules/{rule_id}?organization_id=10234695 -H "Authorization: Zoho-authtoken ba4604e8e433g9c892e360d53463oec5" -H "Content-Type: application/json;charset=UTF-8" -d '{ "rule_name": "Minimum Deposit Rule", "target_account_id": 460000000048001, "apply_to": "deposits", "criteria_type": "and", "criterion": [ { "criteria_id": "460000000048009", "field": "amount", "comparator": "greater_than_or_equals", "value": "500.00" } ], "record_as": "deposit", "account_id": 460000000049001, "customer_id": 46000000000111, "tax_id": "460000000048238", "reference_number": "manual" }
Response Example
HTTP/1.1 200 OK Content-Type:application/json;charset=UTF-8 { "code": 0, "message": "The bank rule has been updated.", "rule": { "rule_id": "460000000048005", "rule_name": "Minimum Deposit Rule", "rule_order": 0, "apply_to": "deposits", "criteria_type": "and", "criterion": [ { "criteria_id": "460000000048009", "field": "amount", "comparator": "greater_than_or_equals", "value": "500.00" } ], "record_as": "deposit", "account_id": "460000000000361", "account_name": "Petty Cash", "tax_id": "460000000048238", "customer_id": "46000000000111", "customer_name": "Trendz", "reference_number": "from_statement", "payment_mode": "Cash" } }
ARGUMENTS
|
rule_name
Required
Name of the Rule
target_account_id
Required
The account on which the rule has to be applied.
apply_to
Required
Rule applies to either deposits or
withdrawals for bank accounts and to refunds or charges for credit card
account. Allowed Values :
withdrawals, deposits, refunds and charges.
criteria_type
Required
Specifies whether all the criteria have to be satisfied or not. Allowed Values :
and and or
criterion
Required
criteria_id
Optional
ID of the Criteria
field
Optional
Field involved in the Criteria
comparator
Optional
Comparator used in Criteria
value
Optional
Value to be compared with
record_as
Required
Record transaction based on value
specified in apply_to node. For bank accounts: If apply_to is deposits:
sales_without_invoices, transfer_fund, interest_income, other_income,
expense_refund, deposit. If apply_to is withdrawals: expense,
transfer_fund, card_payment, owner_drawings. For credit_card accounts:
If apply_to is refunds: card_payment, transfer_fund, expense_refund,
refund. If apply_to is charges: expense, transfer_fund. Allowed Values:
expense, deposit, refund, transfer_fund, card_payment, sales_without_invoices, expense_refund, interest_income, other_income and owner_drawings
account_id
Optional
Account which is involved in the rule with the target account.
customer_id
Optional
ID of the customer.(Applicable for sales_without_invoices,deposit, expense)
tax_id
Optional
Tax ID involved in the transaction.
reference_number
Optional
Specifies if Reference number is manual or generated from the statement. Allowed Values:
manual and from_statement
vat_treatment
UK and EU Edition Only
Optional
Vat Treatment Associated with the Rule
product_type
UK and EU Edition Only
Optional
Product Type associated with the Rule. Allowed values:
goods or service or digital_service.
tax_authority_id
US Edition Only
Optional
ID of the Tax Authority Associated with the Rule
tax_exemption_id
Inida Edition and US Edition Only
Optional
ID of the Tax Exemption Associated with the Rule
|
Delete a rule
Delete a rule from your account and make it no longer applicable on the transactions.
DELETE /bankaccounts/rules/{rule_id}
Request Example
$ curl https://books.zoho.com/api/v3/bankaccounts/rules/{rule_id}?organization_id=10234695 -H "Authorization: Zoho-authtoken ba4604e8e433g9c892e360d53463oec5" -H "Content-Type: application/json;charset=UTF-8"
Response Example
HTTP/1.1 200 OK Content-Type:application/json;charset=UTF-8 { "code": 0, "message": "The rule has been deleted." }
Chart-Of-Accounts
The Chart of Accounts in Zoho Books consists of a wide range of accounts that are generally used with any type of business. The accounts are classified into different types such as Income, Expense, Equity, Liability & Assets.
Example
{ "chart_of_account": { "account_id": "460000000038079", "account_name": "Notes Payable", "is_active": true, "account_type": "long_term_liability", "currency_id": "460000000000097", "currency_code": "INR", "description": "A Liability account which can be paid off in a time period longer than one year.", "can_show_in_ze": false, "has_transaction": false, "custom_fields": [ {} ], "documents": [ {} ], "created_time": "2013-01-17T15:27:23+0530", "last_modified_time": "2013-01-17T15:27:23+0530" } }
Attribute
|
chart_of_account
object
account_id
string
ID of the Account
account_name
string
Name of the account
account_code
string
Code Associated with the Account
is_active
boolean
Check if account is Active or Inactive
account_type
string
Type of the account. Allowed Values:
other_asset, other_current_asset, cash, bank, fixed_asset, other_current_liability, credit_card, long_term_liability, other_liability, equity, income, other_income, expense, cost_of_goods_sold, other_expense, accounts_receivable and accounts_payable.
currency_id
string
ID of the account currency.
currency_code
string
Code of the Currency Associated with the Account
description
string
Description of the account
can_show_in_ze
boolean
has_transaction
boolean
Check if the account has transactions associated with it
include_in_vat_return
UK Edition only
boolean
Boolean to include an account in VAT returns.
custom_fields
list
custom_field_id
long
index
integer
Index of the custom field
label
stirng
Label of the Custom Field
value
string
Value of the Custom Field
parent_account_id
string
ID of the Parent Account
documents
list
created_time
string
Created Time associated with the Entity
last_modified_time
string
Last Modified time associated with the entity
|
Create an account
Creates an account with the given account type.
POST /chartofaccounts
Request Example
$ curl https://books.zoho.com/api/v3/chartofaccounts?organization_id=10234695 -H "Authorization: Zoho-authtoken ba4604e8e433g9c892e360d53463oec5" -H "Content-Type: application/json;charset=UTF-8" -d '{ "account_name": "Notes Payable", "account_type": "long_term_liability", "currency_id": "460000000000097", "description": "A Liability account which can be paid off in a time period longer than one year.", "show_on_dashboard": false, "can_show_in_ze": false, "custom_fields": [ {} ] }
Response Example
HTTP/1.1 201 Created Content-Type:application/json;charset=UTF-8 { "code": 0, "message": "The account has been created.", "chart_of_account": { "account_id": "460000000038079", "account_name": "Notes Payable", "is_active": true, "account_type": "long_term_liability", "currency_id": "460000000000097", "currency_code": "INR", "description": "A Liability account which can be paid off in a time period longer than one year.", "can_show_in_ze": false, "has_transaction": false, "custom_fields": [ {...} ], "documents": [ {...} ], "created_time": "2013-01-17T15:27:23+0530", "last_modified_time": "2013-01-17T15:27:23+0530" } }
ARGUMENTS
|
account_name
Optional
Name of the account
account_code
Optional
Code Associated with the Account
account_type
Optional
Type of the account. Allowed Values:
other_asset, other_current_asset, cash, bank, fixed_asset, other_current_liability, credit_card, long_term_liability, other_liability, equity, income, other_income, expense, cost_of_goods_sold, other_expense, accounts_receivable and accounts_payable.
currency_id
Optional
ID of the account currency.
description
Optional
Description of the account
show_on_dashboard
Optional
can_show_in_ze
Optional
include_in_vat_return
UK Edition only
Optional
Boolean to include an account in VAT returns.
custom_fields
Optional
index
Optional
Index of the custom field
value
Optional
Value of the Custom Field
parent_account_id
Optional
ID of the Parent Account
|
Update an account
Updates the account information.
PUT /chartofaccounts/{account_id}
Request Example
$ curl https://books.zoho.com/api/v3/chartofaccounts/{account_id}?organization_id=10234695 -H "Authorization: Zoho-authtoken ba4604e8e433g9c892e360d53463oec5" -H "Content-Type: application/json;charset=UTF-8" -d '{ "account_name": "Notes Payable", "account_type": "long_term_liability", "currency_id": "460000000000097", "description": "A Liability account which can be paid off in a time period longer than one year.", "show_on_dashboard": false, "can_show_in_ze": false, "custom_fields": [ {} ] }
Response Example
HTTP/1.1 200 OK Content-Type:application/json;charset=UTF-8 { "code": 0, "message": "The details of the account have been updated.", "chart_of_account": { "account_id": "460000000038079", "account_name": "Notes Payable", "is_active": true, "account_type": "long_term_liability", "currency_id": "460000000000097", "currency_code": "INR", "description": "A Liability account which can be paid off in a time period longer than one year.", "can_show_in_ze": false, "has_transaction": false, "custom_fields": [ {...} ], "documents": [ {...} ], "created_time": "2013-01-17T15:27:23+0530", "last_modified_time": "2013-01-17T15:27:23+0530" } }
ARGUMENTS
|
account_name
Optional
Name of the account
account_code
Optional
Code Associated with the Account
account_type
Optional
Type of the account. Allowed Values:
other_asset, other_current_asset, cash, bank, fixed_asset, other_current_liability, credit_card, long_term_liability, other_liability, equity, income, other_income, expense, cost_of_goods_sold, other_expense, accounts_receivable and accounts_payable.
currency_id
Optional
ID of the account currency.
description
Optional
Description of the account
show_on_dashboard
Optional
can_show_in_ze
Optional
include_in_vat_return
UK Edition only
Optional
Boolean to include an account in VAT returns.
custom_fields
Optional
index
Optional
Index of the custom field
value
Optional
Value of the Custom Field
parent_account_id
Optional
ID of the Parent Account
|
Get an account
Gets the details of an account
GET /chartofaccounts/{account_id}
Request Example
$ curl https://books.zoho.com/api/v3/chartofaccounts/{account_id}?organization_id=10234695 -H "Authorization: Zoho-authtoken ba4604e8e433g9c892e360d53463oec5" -H "Content-Type: application/json;charset=UTF-8"
Response Example
HTTP/1.1 200 OK Content-Type:application/json;charset=UTF-8 { "code": 0, "message": "success", "chart_of_account": { "account_id": "460000000038079", "account_name": "Notes Payable", "is_active": true, "account_type": "long_term_liability", "currency_id": "460000000000097", "currency_code": "INR", "description": "A Liability account which can be paid off in a time period longer than one year.", "can_show_in_ze": false, "has_transaction": false, "custom_fields": [ {...} ], "documents": [ {...} ], "created_time": "2013-01-17T15:27:23+0530", "last_modified_time": "2013-01-17T15:27:23+0530" } }
List chart of accounts
List all chart of accounts along with pagination.
GET /chartofaccounts
Request Example
$ curl https://books.zoho.com/api/v3/chartofaccounts?organization_id=10234695 -H "Authorization: Zoho-authtoken ba4604e8e433g9c892e360d53463oec5" -H "Content-Type: application/json;charset=UTF-8"
Response Example
HTTP/1.1 200 OK Content-Type:application/json;charset=UTF-8 { "code": 0, "message": "success", "chartofaccounts": [ { "account_id": "460000000038079", "account_name": "Notes Payable", "account_type": "long_term_liability", "is_user_created": true, "is_system_account": true, "is_active": true, "can_show_in_ze": false, "is_involved_in_transaction": false, "has_attachment": false, "documents": [ {...} ], "created_time": "2013-01-17T15:27:23+0530", "last_modified_time": "2013-01-17T15:27:23+0530" }, {...}, {...} ] }
Query Params
|
showbalance
Optional
Boolean to get current balance of accounts.
filter_by
Optional
Filter accounts based on its account type and status. Allowed Values:
AccountType.All, AccountType.Active, AccountType.Inactive, AccountType.Asset, AccountType.Liability, AccountType.Equity, AccountType.Income and AccountType.Expense.
sort_column
Optional
Sort accounts. Allowed Values:
account_name and account_type.
last_modified_time
Optional
Last Modified time associated with the entity
|
Delete an account
Deletes the given account. Accounts associated in any transaction/products could not be deleted.
DELETE /chartofaccounts/{account_id}
Request Example
$ curl https://books.zoho.com/api/v3/chartofaccounts/{account_id}?organization_id=10234695 -H "Authorization: Zoho-authtoken ba4604e8e433g9c892e360d53463oec5" -H "Content-Type: application/json;charset=UTF-8"
Response Example
HTTP/1.1 200 OK Content-Type:application/json;charset=UTF-8 { "code": 0, "message": "The account has been deleted." }
Mark an account as active
Updates the account status as active.
POST /chartofaccounts/{account_id}/active
Request Example
$ curl https://books.zoho.com/api/v3/chartofaccounts/{account_id}/active?organization_id=10234695 -H "Authorization: Zoho-authtoken ba4604e8e433g9c892e360d53463oec5" -H "Content-Type: application/json;charset=UTF-8"
Response Example
HTTP/1.1 201 Created Content-Type:application/json;charset=UTF-8 { "code": 0, "message": "The account has been marked as active." }
Mark an account as inactive
Updates the account status as inactive.
POST /chartofaccounts/{account_id}/inactive
Request Example
$ curl https://books.zoho.com/api/v3/chartofaccounts/{account_id}/inactive?organization_id=10234695 -H "Authorization: Zoho-authtoken ba4604e8e433g9c892e360d53463oec5" -H "Content-Type: application/json;charset=UTF-8"
Response Example
HTTP/1.1 201 Created Content-Type:application/json;charset=UTF-8 { "code": 0, "message": "The account has been marked as inactive." }
List of transactions for an account
List all involved transactions for the given account.
GET /chartofaccounts/transactions
Request Example
$ curl https://books.zoho.com/api/v3/chartofaccounts/transactions?organization_id=10234695 -H "Authorization: Zoho-authtoken ba4604e8e433g9c892e360d53463oec5" -H "Content-Type: application/json;charset=UTF-8"
Response Example
HTTP/1.1 200 OK Content-Type:application/json;charset=UTF-8 { "code": 0, "message": "success", "transactions": [ { "categorized_transaction_id": "460000000052051", "transaction_type": "customer_payment", "transaction_id": "460000000050163", "transaction_date": "2013-10-04", "account_id": "460000000038079", "customer_id": "460000000044001", "payee": "Richards Electric Company", "description": "A Liability account which can be paid off in a time period longer than one year.", "entry_number": "INV-00004", "currency_id": "460000000000097", "currency_code": "INR", "debit_or_credit": "credit", "credit_amount": 25 }, {...}, {...} ] }
Query Params
|
account_id
Optional
ID of the Account
date
Optional
Search account transactions with the given date range. Default date format is yyyy-mm-dd. Variants:
date.start, date.end, date.before and date.after.
amount
Optional
Search account transactions with given amount range. Variants:
amount.less_than, amount.less_equals, amount.greater_than and amount.greater_equals.
filter_by
Optional
Filter accounts based on its account type and status. Allowed Values:
AccountType.All, AccountType.Active, AccountType.Inactive, AccountType.Asset, AccountType.Liability, AccountType.Equity, AccountType.Income and AccountType.Expense.
transaction_type
Optional
Search transactions based on the given transaction type. Allowed Values:
invoice, customer_payment, bills, vendor_payment, credit_notes, creditnote_refund, expense, card_payment, purchase_or_charges, journal, deposit, refund, transfer_fund, base_currency_adjustment, opening_balance, sales_without_invoices, expense_refund, tax_refund, receipt_from_initial_debtors, owner_contribution, interest_income, other_income, owner_drawings and payment_to_initial_creditors.
sort_column
Optional
Sort accounts. Allowed Values:
account_name and account_type. |
Delete a transaction
Deletes the transaction.
DELETE /chartofaccounts/transactions/{transaction_id}
Request Example
$ curl https://books.zoho.com/api/v3/chartofaccounts/transactions/{transaction_id}?organization_id=10234695 -H "Authorization: Zoho-authtoken ba4604e8e433g9c892e360d53463oec5" -H "Content-Type: application/json;charset=UTF-8"
Response Example
HTTP/1.1 200 OK Content-Type:application/json;charset=UTF-8 { "code": 0, "message": "The transaction has been deleted." }
Journals
Journals are used by accountants to work directly with the general ledger to create both debit and credit entries for unique financial transactions.
Example
{ "journal": { "journal_id": "460000000038001", "entry_number": "1", "reference_number": "7355", "notes": "Loan repayment", "currency_id": "460000000000097", "currency_code": "USD", "currency_symbol": "$", "exchange_rate": 1, "journal_date": "2013-09-04", "journal_type": "both", "line_items": [ { "line_id": "460000000038005", "account_id": "460000000000361", "account_name": "Petty Cash", "debit_or_credit": "credit", "tax_type": "tax", "amount": 5000, "bcy_amount": 100, "tags": [ {} ] } ], "line_item_total": 5000, "total": 5000, "bcy_total": 100, "price_precision": 2, "taxes": [ { "debit_or_credit": "credit" } ], "created_time": "2013-09-04T09:40:07+0530", "last_modified_time": "2013-09-05T17:13:31+0530", "custom_fields": [ {} ] } }
Attribute
|
journal
object
journal_id
string
ID of the Journal
entry_number
string
Entry Number of the Journal
reference_number
string
Reference number for the journal.
notes
string
Notes for the journal.
currency_id
string
ID of the Currency Associated with the Journal
currency_code
string
Code of the Currency Associated with the Journal
currency_symbol
string
Symbol of the Currency Associated with the Journal
exchange_rate
double
Exchange Rate between the Currencies
journal_date
string
Date on which the journal to be recorded.
journal_type
string
Type of the Journal. Allowed values:
Cash and Both .
vat_treatment
UK Edition only
string
(Optional) VAT treatment for the journal.
product_type
UK Edition only
string
Type of the journal. This denotes whether the journal is to be treated as goods or service. Allowed Values:
digital_service, goods and service.
include_in_vat_return
EU and UK Edition Only
boolean
Check if Journal should be included in VAT Return
is_bas_adjustment
AU Edition Only
boolean
Check if Journal is created for BAS Adjustment
line_items
list
line_id
string
ID of the Line
account_id
string
ID of account for which journals to be recorded.
customer_id
string
ID of the Customer/Vendor
customer_name
string
Name of the Customer/Vendor
account_name
string
Name of the Account
description
string
Description that can be given at the line item level.
debit_or_credit
string
Whether the accounts needs to be debited or credited. Allowed Values:
debit and credit.
tax_exemption_id
Inida, US, AU and CA Editions Only
string
ID of the Tax Exemption
tax_exemption_type
India, US, AU and CA Editions Only
string
Type of the Tax Exemption. Allowed Values :
customer and item
tax_exemption_code
India, US, AU and CA Editions Only
string
Code of the Tax Exemption
tax_authority_id
US, AU and CA Editions Only
string
ID of the Tax Authority
tax_authority_name
US, AU and CA Editions Only
string
Name of the Tax Authority
tax_id
string
ID of the tax.
tax_name
string
Name of the Tax
tax_type
string
Type of the Tax
tax_percentage
string
Percentage of the Tax
amount
double
Amount to be recorded for the journal.
bcy_amount
double
Amount in Base Currency
acquisition_vat_id
UK Edition only
string
(Optional) This is the ID of the tax applied in case this is an EU - goods journal and acquisition VAT needs to be reported.
acquisition_vat_name
UK and EU Editions Only
string
Name of the VAT Acquistion
acquisition_vat_percentage
UK and EU Editions Only
string
Percentage of the VAT Acquistion
acquisition_vat_amount
UK and EU Editions Only
string
Amount of the VAT Acquistion
reverse_charge_vat_id
UK Edition only
string
(Optional) This is the ID of the tax
applied in case this is a non UK - service journal and reverse charge
VAT needs to be reported.
reverse_charge_vat_name
UK and EU Editions Only
string
Name of the Reverse Charge
reverse_charge_vat_percentage
UK and EU Editions Only
string
Percentage of the Reverse Charge
reverse_charge_vat_amount
UK and EU Editions Only
string
Percentage of the Reverse Charge
tags
list
line_item_total
double
Total of the Line Item
total
double
Total of the Journal
bcy_total
double
Total in Base Currency
price_precision
integer
Price Precision for the Values
taxes
list
tax_name
string
Name of the Tax
tax_amount
double
Amount of Tax
debit_or_credit
string
Whether the accounts needs to be debited or credited. Allowed Values:
debit and credit.
tax_account
boolean
Account for recording Tax
created_time
string
Created Time of the Journal
last_modified_time
string
Last Modified Time of the Journal
custom_fields
list
custom_field_id
long
ID of the Custom Field
label
string
Label of the Custom Field
index
integer
Index of the Custom Field
value
string
Value of the Custom Field
|
Create a journal
Create a journal
POST /journals
Request Example
$ curl https://books.zoho.com/api/v3/journals?organization_id=10234695 -H "Authorization: Zoho-authtoken ba4604e8e433g9c892e360d53463oec5" -H "Content-Type: application/json;charset=UTF-8" -d '{ "journal_date": "2013-09-04", "reference_number": "7355", "notes": "Loan repayment", "journal_type": "both", "currency_id": "460000000000097", "exchange_rate": 1, "line_items": [ { "account_id": "460000000000361", "line_id": "460000000038005", "amount": 5000, "debit_or_credit": "credit", "tags": [ {} ] } ], "custom_fields": [ {} ] }
Response Example
HTTP/1.1 201 Created Content-Type:application/json;charset=UTF-8 { "code": 0, "message": "The journal entry has been created.", "journal": { "journal_id": "460000000038001", "entry_number": "1", "reference_number": "7355", "notes": "Loan repayment", "currency_id": "460000000000097", "currency_code": "USD", "currency_symbol": "$", "exchange_rate": 1, "journal_date": "2013-09-04", "journal_type": "both", "line_items": [ { "line_id": "460000000038005", "account_id": "460000000000361", "account_name": "Petty Cash", "debit_or_credit": "credit", "tax_type": "tax", "amount": 5000, "bcy_amount": 100, "tags": [ {...} ] } ], "line_item_total": 5000, "total": 5000, "bcy_total": 100, "price_precision": 2, "taxes": [ { "debit_or_credit": "credit" } ], "created_time": "2013-09-04T09:40:07+0530", "last_modified_time": "2013-09-05T17:13:31+0530", "custom_fields": [ {...} ] } }
ARGUMENTS
|
journal_date
Required
Date on which the journal to be recorded.
reference_number
Optional
Reference number for the journal.
notes
Optional
Notes for the journal.
journal_type
Optional
Type of the Journal. Allowed values:
Cash and Both .
vat_treatment
UK Edition only
Optional
(Optional) VAT treatment for the journal.
include_in_vat_return
EU and UK Edition Only
Optional
Check if Journal should be included in VAT Return
product_type
UK Edition only
Optional
Type of the journal. This denotes whether the journal is to be treated as goods or service. Allowed Values:
digital_service, goods and service.
is_bas_adjustment
AU Edition Only
Optional
Check if Journal is created for BAS Adjustment
currency_id
Optional
ID of the Currency Associated with the Journal
exchange_rate
Optional
Exchange Rate between the Currencies
line_items
Optional
account_id
Optional
ID of account for which journals to be recorded.
customer_id
Optional
ID of the Customer/Vendor
line_id
Optional
ID of the Line
description
Optional
Description that can be given at the line item level.
tax_exemption_id
Inida, US, AU and CA Editions Only
Optional
ID of the Tax Exemption
tax_authority_id
US, AU and CA Editions Only
Optional
ID of the Tax Authority
tax_exemption_type
India, US, AU and CA Editions Only
Optional
Type of the Tax Exemption. Allowed Values :
customer and item
tax_exemption_code
India, US, AU and CA Editions Only
Optional
Code of the Tax Exemption
tax_authority_name
US, AU and CA Editions Only
Optional
Name of the Tax Authority
tax_id
Optional
ID of the tax.
amount
Required
Amount to be recorded for the journal.
debit_or_credit
Required
Whether the accounts needs to be debited or credited. Allowed Values:
debit and credit.
acquisition_vat_id
UK Edition only
Optional
(Optional) This is the ID of the tax applied in case this is an EU - goods journal and acquisition VAT needs to be reported.
reverse_charge_vat_id
UK Edition only
Optional
(Optional) This is the ID of the tax
applied in case this is a non UK - service journal and reverse charge
VAT needs to be reported.
tags
Optional
tax_exemption_code
India, US, AU and CA Editions Only
Optional
Code of the Tax Exemption
tax_exemption_type
India, US, AU and CA Editions Only
Optional
Type of the Tax Exemption. Allowed Values :
customer and item
custom_fields
Optional
index
Optional
Index of the Custom Field
value
Optional
Value of the Custom Field
|
Update a journal
Updates the journal with given information
PUT /journals/{journal_id}
Request Example
$ curl https://books.zoho.com/api/v3/journals/{journal_id}?organization_id=10234695 -H "Authorization: Zoho-authtoken ba4604e8e433g9c892e360d53463oec5" -H "Content-Type: application/json;charset=UTF-8" -d '{ "journal_date": "2013-09-04", "reference_number": "7355", "notes": "Loan repayment", "journal_type": "both", "currency_id": "460000000000097", "exchange_rate": 1, "line_items": [ { "account_id": "460000000000361", "line_id": "460000000038005", "amount": 5000, "debit_or_credit": "credit", "tags": [ {} ] } ], "custom_fields": [ {} ] }
Response Example
HTTP/1.1 200 OK Content-Type:application/json;charset=UTF-8 { "code": 0, "message": "The journal entry has been updated.", "journal": { "journal_id": "460000000038001", "entry_number": "1", "reference_number": "7355", "notes": "Loan repayment", "currency_id": "460000000000097", "currency_code": "USD", "currency_symbol": "$", "exchange_rate": 1, "journal_date": "2013-09-04", "journal_type": "both", "line_items": [ { "line_id": "460000000038005", "account_id": "460000000000361", "account_name": "Petty Cash", "debit_or_credit": "credit", "tax_type": "tax", "amount": 5000, "bcy_amount": 100, "tags": [ {...} ] } ], "line_item_total": 5000, "total": 5000, "bcy_total": 100, "price_precision": 2, "taxes": [ { "debit_or_credit": "credit" } ], "created_time": "2013-09-04T09:40:07+0530", "last_modified_time": "2013-09-05T17:13:31+0530", "custom_fields": [ {...} ] } }
ARGUMENTS
|
journal_date
Required
Date on which the journal to be recorded.
reference_number
Optional
Reference number for the journal.
notes
Optional
Notes for the journal.
journal_type
Optional
Type of the Journal. Allowed values:
Cash and Both .
vat_treatment
UK Edition only
Optional
(Optional) VAT treatment for the journal.
include_in_vat_return
EU and UK Edition Only
Optional
Check if Journal should be included in VAT Return
product_type
UK Edition only
Optional
Type of the journal. This denotes whether the journal is to be treated as goods or service. Allowed Values:
digital_service, goods and service.
is_bas_adjustment
AU Edition Only
Optional
Check if Journal is created for BAS Adjustment
currency_id
Optional
ID of the Currency Associated with the Journal
exchange_rate
Optional
Exchange Rate between the Currencies
line_items
Optional
account_id
Optional
ID of account for which journals to be recorded.
customer_id
Optional
ID of the Customer/Vendor
line_id
Optional
ID of the Line
description
Optional
Description that can be given at the line item level.
tax_exemption_id
Inida, US, AU and CA Editions Only
Optional
ID of the Tax Exemption
tax_authority_id
US, AU and CA Editions Only
Optional
ID of the Tax Authority
tax_exemption_type
India, US, AU and CA Editions Only
Optional
Type of the Tax Exemption. Allowed Values :
customer and item
tax_exemption_code
India, US, AU and CA Editions Only
Optional
Code of the Tax Exemption
tax_authority_name
US, AU and CA Editions Only
Optional
Name of the Tax Authority
tax_id
Optional
ID of the tax.
amount
Required
Amount to be recorded for the journal.
debit_or_credit
Required
Whether the accounts needs to be debited or credited. Allowed Values:
debit and credit.
acquisition_vat_id
UK Edition only
Optional
(Optional) This is the ID of the tax applied in case this is an EU - goods journal and acquisition VAT needs to be reported.
reverse_charge_vat_id
UK Edition only
Optional
(Optional) This is the ID of the tax
applied in case this is a non UK - service journal and reverse charge
VAT needs to be reported.
tags
Optional
tax_exemption_code
India, US, AU and CA Editions Only
Optional
Code of the Tax Exemption
tax_exemption_type
India, US, AU and CA Editions Only
Optional
Type of the Tax Exemption. Allowed Values :
customer and item
custom_fields
Optional
index
Optional
Index of the Custom Field
value
Optional
Value of the Custom Field
|
Get journal
Get the details of the journal
GET /journals/{journal_id}
Request Example
$ curl https://books.zoho.com/api/v3/journals/{journal_id}?organization_id=10234695 -H "Authorization: Zoho-authtoken ba4604e8e433g9c892e360d53463oec5" -H "Content-Type: application/json;charset=UTF-8"
Response Example
HTTP/1.1 200 OK Content-Type:application/json;charset=UTF-8 { "code": 0, "message": "success", "journal": { "journal_id": "460000000038001", "entry_number": "1", "reference_number": "7355", "notes": "Loan repayment", "currency_id": "460000000000097", "currency_code": "USD", "currency_symbol": "$", "exchange_rate": 1, "journal_date": "2013-09-04", "journal_type": "both", "line_items": [ { "line_id": "460000000038005", "account_id": "460000000000361", "account_name": "Petty Cash", "debit_or_credit": "credit", "tax_type": "tax", "amount": 5000, "bcy_amount": 100, "tags": [ {...} ] } ], "line_item_total": 5000, "total": 5000, "bcy_total": 100, "price_precision": 2, "taxes": [ { "debit_or_credit": "credit" } ], "created_time": "2013-09-04T09:40:07+0530", "last_modified_time": "2013-09-05T17:13:31+0530", "custom_fields": [ {...} ] } }
Get journal list
Get journal list
GET /journals
Request Example
$ curl https://books.zoho.com/api/v3/journals?organization_id=10234695 -H "Authorization: Zoho-authtoken ba4604e8e433g9c892e360d53463oec5" -H "Content-Type: application/json;charset=UTF-8"
Response Example
HTTP/1.1 200 OK Content-Type:application/json;charset=UTF-8 { "code": 0, "message": "success", "journals": [ { "journal_id": "460000000038001", "journal_date": "2013-09-04", "entry_number": "1", "reference_number": "7355", "currency_id": "460000000000097", "notes": "Loan repayment", "journal_type": "both", "entity_type": "journal", "total": 5000, "bcy_total": 100 }, {...}, {...} ] }
Query Params
|
entry_number
Optional
Search journals by journal entry number. Variants:
entry_number_startswith and entry_number_contains
reference_number
Optional
Search journals by journal reference number. Variants:
reference_number_startswith and reference_number_contains
date
Optional
Search journals by journal date. Variants:
date_start, date_end, date_before and date_after
notes
Optional
Search journals by journal notes. Variants:
notes_startswith and notes_contains
last_modified_time
Optional
Search the journals using Last Modified Time
total
Optional
Search journals by journal total. Variants:
total_less_than, total_less_equals, total_greater_than and total_greater_equals
customer_id
Optional
Search Journals using Customer ID
vendor_id
Optional
Search the journals using Vendor ID
filter_by
Optional
Filter journals by journal date. Allowed Values:
JournalDate.All, JournalDate.Today, JournalDate.ThisWeek, JournalDate.ThisMonth, JournalDate.ThisQuarter and JournalDate.ThisYear
sort_column
Optional
Sort journal list. Allowed Values:
journal_date, entry_number, reference_number and total |
Delete a journal
Deletes the given journal
DELETE journals/{journal_id}
Request Example
$ curl https://books.zoho.com/api/v3journals/{journal_id}?organization_id=10234695 -H "Authorization: Zoho-authtoken ba4604e8e433g9c892e360d53463oec5" -H "Content-Type: application/json;charset=UTF-8"
Response Example
HTTP/1.1 200 OK Content-Type:application/json;charset=UTF-8 { "code": 0, "message": "The selected journal entry has been deleted." }
Base-Currency-Adjustment
In Zoho Books you can have an insight on the profit or loss incurred due to the change in exchange rates and also can apply the changes to open transactions.
Example
{ "data": { "base_currency_adjustment_id": "460000000039001", "adjustment_date": "2013-09-05", "exchange_rate": 1, "currency_id": "460000000000109", "accounts": [ { "account_id": "460000000000364", "account_name": "Accounts Receivable", "bcy_balance": 171.47, "fcy_balance": 139.41, "adjusted_balance": 209.12, "gain_or_loss": 37.65, "gl_specific_type": 5 } ], "notes": "Base Currency Adjustment against EUR", "currency_code": "EUR" } }
Attribute
|
data
object
base_currency_adjustment_id
string
ID of the Base Currency Adjustment
adjustment_date
string
Date of adjustment.
exchange_rate
double
Exchange rate of the currency.
currency_id
string
ID of currency for which we need to post adjustment.
accounts
list
account_id
string
ID of the Account in Base Currency Adjustment
account_name
string
Name of the Account in Base Currency Adjustment
bcy_balance
double
Balance in Base Currency of the Organisation
fcy_balance
double
Balance in Foreign Currency
adjusted_balance
double
Adjusted Balance
gain_or_loss
double
Amount in Total Gain/Loss
gl_specific_type
integer
GL Specific Type of the Account Involved
notes
string
Notes for base currency adjustment.
currency_code
string
Currency Code involved in the Adjustment
|
Create a base currency adjustment
Creates a base currency adjustment for the given information
POST /basecurrencyadjustment
Request Example
$ curl https://books.zoho.com/api/v3/basecurrencyadjustment?organization_id=10234695 -H "Authorization: Zoho-authtoken ba4604e8e433g9c892e360d53463oec5" -H "Content-Type: application/json;charset=UTF-8" -d '{ "currency_id": "460000000000109", "adjustment_date": "2013-09-05", "exchange_rate": 1, "notes": "Base Currency Adjustment against EUR" }
Response Example
HTTP/1.1 200 OK Content-Type:application/json;charset=UTF-8 { "code": 0, "message": "The adjustment has been made. The account balances will now reflect the adjustment.", "data": { "base_currency_adjustment_id": "460000000039001", "adjustment_date": "2013-09-05", "exchange_rate": 1, "currency_id": "460000000000109", "accounts": [ { "account_id": "460000000000364", "account_name": "Accounts Receivable", "bcy_balance": 171.47, "fcy_balance": 139.41, "adjusted_balance": 209.12, "gain_or_loss": 37.65, "gl_specific_type": 5 } ], "notes": "Base Currency Adjustment against EUR", "currency_code": "EUR" } }
ARGUMENTS
|
currency_id
Required
ID of currency for which we need to post adjustment.
adjustment_date
Required
Date of adjustment.
exchange_rate
Required
Exchange rate of the currency.
notes
Required
Notes for base currency adjustment.
|
Query Params
|
account_ids
Required
ID of the accounts for which base currency adjustments need to be posted.
|
Get a base currency adjustment
Get the base currency adjustment details
GET /basecurrencyadjustment/{base_currency_adjustment_id}
Request Example
$ curl https://books.zoho.com/api/v3/basecurrencyadjustment/{base_currency_adjustment_id}?organization_id=10234695 -H "Authorization: Zoho-authtoken ba4604e8e433g9c892e360d53463oec5" -H "Content-Type: application/json;charset=UTF-8"
Response Example
HTTP/1.1 200 OK Content-Type:application/json;charset=UTF-8 { "code": 0, "message": "success", "data": { "base_currency_adjustment_id": "460000000039001", "adjustment_date": "2013-09-05", "exchange_rate": 1, "currency_id": "460000000000109", "accounts": [ { "account_id": "460000000000364", "account_name": "Accounts Receivable", "bcy_balance": 171.47, "fcy_balance": 139.41, "adjusted_balance": 209.12, "gain_or_loss": 37.65, "gl_specific_type": 5 } ], "notes": "Base Currency Adjustment against EUR", "currency_code": "EUR" } }
List base currency adjustment
Lists base currency adjustment
GET /basecurrencyadjustment
Request Example
$ curl https://books.zoho.com/api/v3/basecurrencyadjustment?organization_id=10234695 -H "Authorization: Zoho-authtoken ba4604e8e433g9c892e360d53463oec5" -H "Content-Type: application/json;charset=UTF-8"
Response Example
HTTP/1.1 200 OK Content-Type:application/json;charset=UTF-8 { "code": 0, "message": "success", "base_currency_adjustments": [ { "base_currency_adjustment_id": "460000000039001", "adjustment_date": "2013-09-05", "exchange_rate": 1, "currency_id": "460000000000109", "currency_code": "EUR", "notes": "Base Currency Adjustment against EUR", "gain_or_loss": 37.65 }, {...}, {...} ] }
Query Params
|
filter_by
Optional
Filter base currency adjustment list. Allowed Values:
Date.All, Date.Today, Date.ThisWeek, Date.ThisMonth, Date.ThisQuarter and Date.ThisYear.
sort_column
Optional
Sort base currency adjustment list. Allowed Values:
adjustment_date, exchange_rate, currency_code, debit_or_credit and gain_or_loss.
last_modified_time
Optional
Search using the Last Modified Time of the Base Currency Adjustment
|
List account details for base currency adjustment
List of accounts having transaction with effect to the given exchange rate.
GET /basecurrencyadjustment/accounts
Request Example
$ curl https://books.zoho.com/api/v3/basecurrencyadjustment/accounts?organization_id=10234695 -H "Authorization: Zoho-authtoken ba4604e8e433g9c892e360d53463oec5" -H "Content-Type: application/json;charset=UTF-8"
Response Example
HTTP/1.1 200 OK Content-Type:application/json;charset=UTF-8 { "code": 0, "message": "success", "data": { "adjustment_date": "2013-09-05", "exchange_rate": 1, "currency_id": "460000000000109", "accounts": [ { "account_id": "460000000000364", "account_name": "Accounts Receivable", "bcy_balance": 171.47, "fcy_balance": 139.41, "adjusted_balance": 209.12, "gain_or_loss": 37.65, "gl_specific_type": 5 } ], "notes": "Base Currency Adjustment against EUR", "currency_code": "EUR" } }
Query Params
|
currency_id
Required
ID of currency for which we need to post adjustment.
adjustment_date
Required
Date of adjustment.
exchange_rate
Required
Exchange rate of the currency.
notes
Required
Notes for base currency adjustment.
|
Delete a base currency adjustment
Deletes the base currency adjustment
DELETE /basecurrencyadjustment/{base_currency_adjustment_id}
Request Example
$ curl https://books.zoho.com/api/v3/basecurrencyadjustment/{base_currency_adjustment_id}?organization_id=10234695 -H "Authorization: Zoho-authtoken ba4604e8e433g9c892e360d53463oec5" -H "Content-Type: application/json;charset=UTF-8"
Response Example
HTTP/1.1 200 OK Content-Type:application/json;charset=UTF-8 { "code": 0, "message": "The selected base currency adjustment has been deleted." }
Projects
A project is a series of tasks performed over a period of time, to achieve certain targets. There can be many number of people working on a single project and a project may consist of single or multiple tasks. A project is billed and charged upon a customer whom the project was taken up for.
Example
{ "project_name": "REAL TIME TRAFFIC FLUX", "customer_id": "460000000044001", "billing_type": "fixed_cost_for_project", "user_id": "460000000024003" }
Attribute
|
project_name
string
Name of the project.
Max-length [100]
customer_id
string
Search projects by customer id.
billing_type
string
The way you bill your customer. Allowed Values:
fixed_cost_for_project, based_on_project_hours, based_on_staff_hours and based_on_task_hours
user_id
string
ID of the user to be added to the project.
|
Create a project
Get the details of a project.
POST /projects
Request Example
$ curl https://books.zoho.com/api/v3/projects?organization_id=10234695 -H "Authorization: Zoho-authtoken ba4604e8e433g9c892e360d53463oec5" -H "Content-Type: application/json;charset=UTF-8" -d '{ "project_name": "Network Distribution", "customer_id": "460000000044001", "description": "Distribution for the system of intermediaries between the producer of goods and/or services and the final user", "billing_type": "based_on_task_hours", "rate": " ", "budget_type": " ", "budget_hours": " ", "budget_amount": " ", "user_id": "INV-00003", "tasks": [ { "task_name": "Distribution Analysis", "description": "Distribution for the system of intermediaries between the producer of goods and/or services and the final user", "rate": " ", "budget_hours": " " } ], "users": [ { "user_id": "INV-00003", "is_current_user": true, "user_name": "John David", "email": "johndavid@zilliuminc.com", "user_role": "admin", "status": "active", "rate": " ", "budget_hours": " ", "total_hours": "12:26", "billed_hours": "12:27", "un_billed_hours": "00:00" } ] }
Response Example
HTTP/1.1 201 Created Content-Type:application/json;charset=UTF-8 { "code": 0, "message": "The project has been created.", "projects": { "project": { "project_id": "460000000044019", "project_name": "REAL TIME TRAFFIC FLUX", "customer_id": "460000000044001", "customer_name": "SAF Instruments Inc", "currency_code": "USD", "description": "A simple algorithm is to be tested with vehicle detection application.", "status": "active", "billing_type": "fixed_cost_for_project", "rate": 5000, "budget_type": " ", "total_hours": "12:26", "total_amount": 500, "billed_hours": "12:27", "billed_amount": 500, "un_billed_hours": "00:00", "un_billed_amount": 0, "billable_hours": "12:26", "billable_amount": 500, "non_billable_hours": "0.00", "non_billable_amount": 0, "is_recurrence_associated": false, "recurring_invoices": [ {...} ], "created_time": "2013-09-18T18:05:27+0530", "show_in_dashboard": true, "tasks": [ { "task_id": "460000000044009", "task_name": "Distribution Analysis", "description": "A simple algorithm is to be tested with vehicle detection application.", "rate": 5000, "budget_hours": "0", "total_hours": "12:26", "billed_hours": "12:27", "un_billed_hours": "00:00", "non_billable_hours": "0.00", "status": "active", "is_billable": true, "task_custom_fields": "" } ], "users": [ { "user_id": "460000000024003", "is_current_user": true, "user_name": "John David", "email": "johndavid@zilliuminc.com", "user_role": "admin", "status": "active", "rate": 5000, "budget_hours": "0", "total_hours": "12:26", "billed_hours": "12:27", "un_billed_hours": "00:00" } ] } } }
ARGUMENTS
|
project_name
Required
Name of the project.
Max-length [100]
customer_id
Required
ID of the customer.
description
Optional
Project description.
Max-length [500]
billing_type
Required
The way you bill your customer. Allowed Values:
fixed_cost_for_project, based_on_project_hours, based_on_staff_hours and based_on_task_hours
rate
Optional
Hourly rate for a task.
budget_type
Optional
The way you budget. Allowed Values:
total_project_cost, total_project_hours, hours_per_task and hours_per_staff
budget_hours
Optional
Task budget hours
budget_amount
Optional
Give value, if you are estimating total project cost.
user_id
Required
ID of the user to be added to the project.
rate
Optional
Hourly rate for a task.
budget_hours
Optional
Task budget hours
tasks
Optional
task_name
Required
description
Optional
Project description.
Max-length [500]
rate
Optional
Hourly rate for a task.
budget_hours
Optional
Task budget hours
users
Optional
user_id
Required
ID of the user to be added to the project.
is_current_user
Optional
user_name
Optional
Name of the user.
Max-length [200]
email
Optional
Email of the user.
Max-length [100]
user_role
Optional
Role to be assigned. Allowed Values:
staff, admin and timesheetstaff
status
Optional
rate
Optional
Hourly rate for a task.
budget_hours
Optional
Task budget hours
total_hours
Optional
billed_hours
Optional
un_billed_hours
Optional
|
Update project
Update details of a project.
PUT /projects/:project_id
Request Example
$ curl https://books.zoho.com/api/v3/projects/:project_id?organization_id=10234695 -H "Authorization: Zoho-authtoken ba4604e8e433g9c892e360d53463oec5" -H "Content-Type: application/json;charset=UTF-8" -d '{ "project_name": "Network Distribution", "customer_id": "460000000044001", "description": "Distribution for the system of intermediaries between the producer of goods and/or services and the final user", "billing_type": "based_on_task_hours", "rate": " ", "budget_type": " ", "budget_hours": " ", "budget_amount": " ", "user_id": "INV-00003", "tasks": [ { "task_name": "Distribution Analysis", "description": "Distribution for the system of intermediaries between the producer of goods and/or services and the final user", "rate": " ", "budget_hours": " " } ], "users": [ { "user_id": "INV-00003", "is_current_user": true, "user_name": "John David", "email": "johndavid@zilliuminc.com", "user_role": "admin", "status": "active", "rate": " ", "budget_hours": " ", "total_hours": "12:26", "billed_hours": "12:27", "un_billed_hours": "00:00" } ] }
Response Example
HTTP/1.1 200 OK Content-Type:application/json;charset=UTF-8 { "code": 0, "message": "The project information has been updated.", "projects": { "project": { "project_id": "460000000044019", "project_name": "REAL TIME TRAFFIC FLUX", "customer_id": "460000000044001", "customer_name": "SAF Instruments Inc", "currency_code": "USD", "description": "A simple algorithm is to be tested with vehicle detection application.", "status": "active", "billing_type": "fixed_cost_for_project", "rate": 5000, "budget_type": " ", "total_hours": "12:26", "total_amount": 500, "billed_hours": "12:27", "billed_amount": 500, "un_billed_hours": "00:00", "un_billed_amount": 0, "billable_hours": "12:26", "billable_amount": 500, "non_billable_hours": "0.00", "non_billable_amount": 0, "is_recurrence_associated": false, "recurring_invoices": [ {...} ], "created_time": "2013-09-18T18:05:27+0530", "show_in_dashboard": true, "tasks": [ { "task_id": "460000000044009", "task_name": "Distribution Analysis", "description": "A simple algorithm is to be tested with vehicle detection application.", "rate": 5000, "budget_hours": "0", "total_hours": "12:26", "billed_hours": "12:27", "un_billed_hours": "00:00", "non_billable_hours": "0.00", "status": "active", "is_billable": true, "task_custom_fields": "" } ], "users": [ { "user_id": "460000000024003", "is_current_user": true, "user_name": "John David", "email": "johndavid@zilliuminc.com", "user_role": "admin", "status": "active", "rate": 5000, "budget_hours": "0", "total_hours": "12:26", "billed_hours": "12:27", "un_billed_hours": "00:00" } ] } } }
ARGUMENTS
|
project_name
Required
Name of the project.
Max-length [100]
customer_id
Required
ID of the customer.
description
Optional
Project description.
Max-length [500]
billing_type
Required
The way you bill your customer. Allowed Values:
fixed_cost_for_project, based_on_project_hours, based_on_staff_hours and based_on_task_hours
rate
Optional
Hourly rate for a task.
budget_type
Optional
The way you budget. Allowed Values:
total_project_cost, total_project_hours, hours_per_task and hours_per_staff
budget_hours
Optional
Task budget hours
budget_amount
Optional
Give value, if you are estimating total project cost.
user_id
Required
ID of the user to be added to the project.
rate
Optional
Hourly rate for a task.
budget_hours
Optional
Task budget hours
tasks
Optional
task_name
Required
description
Optional
Project description.
Max-length [500]
rate
Optional
Hourly rate for a task.
budget_hours
Optional
Task budget hours
users
Optional
user_id
Required
ID of the user to be added to the project.
is_current_user
Optional
user_name
Optional
Name of the user.
Max-length [200]
email
Optional
Email of the user.
Max-length [100]
user_role
Optional
Role to be assigned. Allowed Values:
staff, admin and timesheetstaff
status
Optional
rate
Optional
Hourly rate for a task.
budget_hours
Optional
Task budget hours
total_hours
Optional
billed_hours
Optional
un_billed_hours
Optional
|
List projects
List all projects with pagination.
GET /projects
Request Example
$ curl https://books.zoho.com/api/v3/projects?organization_id=10234695 -H "Authorization: Zoho-authtoken ba4604e8e433g9c892e360d53463oec5" -H "Content-Type: application/json;charset=UTF-8"
Response Example
HTTP/1.1 200 OK Content-Type:application/json;charset=UTF-8 { "code": 0, "message": "success", "projects": [ { "project_id": "460000000044019", "project_name": "REAL TIME TRAFFIC FLUX", "customer_id": "460000000044001", "customer_name": "SAF Instruments Inc", "description": "A simple algorithm is to be tested with vehicle detection application.", "status": "active", "billing_type": "fixed_cost_for_project", "rate": 5000, "created_time": "2013-09-18T18:05:27+0530", "has_attachment": false, "total_hours": "12:26", "billable_hours": "12:26" } ], "page_context": [ { "page": 10, "per_page": 450, "report_name": "Projects", "has_more_page": false, "sort_order": "D", "sort_column": "created_time" } ] }
Query Params
|
filter_by
Optional
Filter projects by any status. Allowed Values:
Status.All, Status.Active and Status.Inactive
customer_id
Optional
Search projects by customer id.
sort_column
Optional
Sort projects. Allowed Values:
project_name, customer_name, rate and created_time |
Get a project
Get the details of a project.
GET /projects/:project_id
Request Example
$ curl https://books.zoho.com/api/v3/projects/:project_id?organization_id=10234695 -H "Authorization: Zoho-authtoken ba4604e8e433g9c892e360d53463oec5" -H "Content-Type: application/json;charset=UTF-8"
Response Example
HTTP/1.1 200 OK Content-Type:application/json;charset=UTF-8 { "code": 0, "message": "success", "project": { "project_id": "460000000044019", "project_name": "REAL TIME TRAFFIC FLUX", "customer_id": "460000000044001", "customer_name": "SAF Instruments Inc", "currency_code": "USD", "description": "A simple algorithm is to be tested with vehicle detection application.", "status": "active", "billing_type": "fixed_cost_for_project", "rate": 5000, "budget_type": " ", "total_hours": "12:26", "total_amount": 500, "billed_hours": "12:27", "billed_amount": 500, "un_billed_hours": "00:00", "un_billed_amount": 0, "billable_hours": "12:26", "billable_amount": 500, "non_billable_hours": "0.00", "non_billable_amount": 0, "is_recurrence_associated": false, "recurring_invoices": [ {...} ], "created_time": "2013-09-18T18:05:27+0530", "show_in_dashboard": true, "tasks": [ { "task_id": "460000000044009", "task_name": "Distribution Analysis", "description": "A simple algorithm is to be tested with vehicle detection application.", "rate": 5000, "budget_hours": "0", "total_hours": "12:26", "billed_hours": "12:27", "un_billed_hours": "00:00", "non_billable_hours": "0.00", "status": "active", "is_billable": true, "task_custom_fields": "" } ] } }
Delete project
Deleting a existing project.
DELETE /projects/:project_id
Request Example
$ curl https://books.zoho.com/api/v3/projects/:project_id?organization_id=10234695 -H "Authorization: Zoho-authtoken ba4604e8e433g9c892e360d53463oec5" -H "Content-Type: application/json;charset=UTF-8"
Response Example
HTTP/1.1 200 OK Content-Type:application/json;charset=UTF-8 { "code": 0, "message": "The project has been deleted." }
Activate project
Mark project as active
POST /projects/:project_id/active
Request Example
$ curl https://books.zoho.com/api/v3/projects/:project_id/active?organization_id=10234695 -H "Authorization: Zoho-authtoken ba4604e8e433g9c892e360d53463oec5" -H "Content-Type: application/json;charset=UTF-8"
Response Example
HTTP/1.1 200 OK Content-Type:application/json;charset=UTF-8 { "code": 0, "message": "The selected Projects have been marked as active." }
Inactivate a project
Marking a project as inactive.
POST /projects/:project_id/inactive
Request Example
$ curl https://books.zoho.com/api/v3/projects/:project_id/inactive?organization_id=10234695 -H "Authorization: Zoho-authtoken ba4604e8e433g9c892e360d53463oec5" -H "Content-Type: application/json;charset=UTF-8"
Response Example
HTTP/1.1 200 OK Content-Type:application/json;charset=UTF-8 { "code": 0, "message": "The selected projects have been marked as inactive." }
Clone project
Cloning a project
POST /projects/:project_id/clone
Request Example
$ curl https://books.zoho.com/api/v3/projects/:project_id/clone?organization_id=10234695 -H "Authorization: Zoho-authtoken ba4604e8e433g9c892e360d53463oec5" -H "Content-Type: application/json;charset=UTF-8" -d '{ "project_name": "Network Distribution", "description": "Distribution for the system of intermediaries between the producer of goods and/or services and the final user" }
Response Example
HTTP/1.1 200 OK Content-Type:application/json;charset=UTF-8 { "code": 0, "message": "Project has been cloned successfully.", "projects": { "project": { "project_id": "460000000044019", "project_name": "REAL TIME TRAFFIC FLUX", "customer_id": "460000000044001", "customer_name": "SAF Instruments Inc", "currency_code": "USD", "description": "A simple algorithm is to be tested with vehicle detection application.", "status": "active", "billing_type": "fixed_cost_for_project", "rate": 5000, "budget_type": " ", "total_hours": "12:26", "total_amount": 500, "billed_hours": "12:27", "billed_amount": 500, "un_billed_hours": "00:00", "un_billed_amount": 0, "billable_hours": "12:26", "billable_amount": 500, "non_billable_hours": "0.00", "non_billable_amount": 0, "is_recurrence_associated": false, "recurring_invoices": [ {...} ], "created_time": "2013-09-18T18:05:27+0530", "show_in_dashboard": true, "tasks": [ { "task_id": "460000000044009", "task_name": "Distribution Analysis", "description": "A simple algorithm is to be tested with vehicle detection application.", "rate": 5000, "budget_hours": "0", "total_hours": "12:26", "billed_hours": "12:27", "un_billed_hours": "00:00", "non_billable_hours": "0.00", "status": "active", "is_billable": true, "task_custom_fields": "" } ], "users": [ { "user_id": "460000000024003", "is_current_user": true, "user_name": "John David", "email": "johndavid@zilliuminc.com", "user_role": "admin", "status": "active", "rate": 5000, "budget_hours": "0", "total_hours": "12:26", "billed_hours": "12:27", "un_billed_hours": "00:00" } ] } } }
ARGUMENTS
|
project_name
Required
Name of the project.
Max-length [100]
description
Optional
Project description.
Max-length [500] |
Assign users
Assign a users to a project
POST /projects/{project_id}/users
Request Example
$ curl https://books.zoho.com/api/v3/projects/{project_id}/users?organization_id=10234695 -H "Authorization: Zoho-authtoken ba4604e8e433g9c892e360d53463oec5" -H "Content-Type: application/json;charset=UTF-8" -d '{ "user_id": "INV-00003", "rate": 5000, "budget_hours": "0" }
Response Example
HTTP/1.1 201 Created Content-Type:application/json;charset=UTF-8 { "code": 0, "message": "Users added.", "users": { "users": [ { "user_id": "460000000024003", "is_current_user": true, "user_name": "John David", "email": "johndavid@zilliuminc.com", "user_role": "admin", "status": "active", "rate": 5000, "budget_hours": "0" } ] } }
ARGUMENTS
|
user_id
Required
ID of the user to be added to the project.
rate
Optional
budget_hours
Optional
Task budget hours.
|
Invite user
Invite and user to the project
POST /projects/{project_id}/users/invite
Request Example
$ curl https://books.zoho.com/api/v3 /projects/{project_id}/users/invite?organization_id=10234695 -H "Authorization: Zoho-authtoken ba4604e8e433g9c892e360d53463oec5" -H "Content-Type: application/json;charset=UTF-8" -d '{ "user_name": "John David", "email": "johndavid@zilliuminc.com", "user_role": "admin", "rate": " ", "budget_hours": "0" }
Response Example
HTTP/1.1 201 Created Content-Type:application/json;charset=UTF-8 { "code": 0, "message": "The staff has been added.", "user": { "users": [ { "user_id": "460000000024003", "user_name": "John David", "email": "johndavid@zilliuminc.com", "user_role": "admin", "is_current_user": true } ] } }
ARGUMENTS
|
user_name
Required
Name of the user.
Max-length [200]
email
Required
Email of the user.
Max-length [100]
user_role
Optional
Role to be assigned. Allowed Values:
staff, admin and timesheetstaff
rate
Optional
Hourly rate for a task.
budget_hours
Optional
Task budget hours.
|
Update user
Update details of a user
PUT /projects/{project_id}/users/:user_id
Request Example
$ curl https://books.zoho.com/api/v3/projects/{project_id}/users/:user_id?organization_id=10234695 -H "Authorization: Zoho-authtoken ba4604e8e433g9c892e360d53463oec5" -H "Content-Type: application/json;charset=UTF-8" -d '{ "user_name": "John David", "user_role": "admin", "rate": 5000, "budget_hours": "0" }
Response Example
HTTP/1.1 200 OK Content-Type:application/json;charset=UTF-8 { "code": 0, "message": "The staff information has been updated.", "user": { "users": [ { "user_id": "460000000024003", "user_name": "John David", "email": "johndavid@zilliuminc.com", "user_role": "admin", "is_current_user": true } ] } }
ARGUMENTS
|
user_name
Optional
Name of the user.
Max-length [200]
user_role
Optional
Role to be assigned. Allowed Values:
staff, admin and timesheetstaff
rate
Optional
budget_hours
Optional
Task budget hours.
|
List Users
Get list of users associated with a project.
GET /projects/{project_id}/users
Request Example
$ curl https://books.zoho.com/api/v3/projects/{project_id}/users?organization_id=10234695 -H "Authorization: Zoho-authtoken ba4604e8e433g9c892e360d53463oec5" -H "Content-Type: application/json;charset=UTF-8"
Response Example
HTTP/1.1 200 OK Content-Type:application/json;charset=UTF-8 { "code": 0, "message": "success", "users": [ { "users": { "user_id": "460000000024003", "is_current_user": true, "user_name": "John David", "email": "johndavid@zilliuminc.com", "user_role": "admin", "status": "active", "rate": 5000, "budget_hours": "0" } }, {...}, {...} ] }
Get a User
Get details of a user in project
GET /projects/{project_id}/users/:user_id
Request Example
$ curl https://books.zoho.com/api/v3/projects/{project_id}/users/:user_id?organization_id=10234695 -H "Authorization: Zoho-authtoken ba4604e8e433g9c892e360d53463oec5" -H "Content-Type: application/json;charset=UTF-8"
Response Example
HTTP/1.1 200 OK Content-Type:application/json;charset=UTF-8 { "code": 0, "message": "success", "user": { "users": { "user_id": "460000000024003", "is_current_user": true, "user_name": "John David", "email": "johndavid@zilliuminc.com", "user_role": "admin" } } }
Delete user
Remove user from a project
DELETE /projects/{project_id}/users/:user_id
Request Example
$ curl https://books.zoho.com/api/v3/projects/{project_id}/users/:user_id?organization_id=10234695 -H "Authorization: Zoho-authtoken ba4604e8e433g9c892e360d53463oec5" -H "Content-Type: application/json;charset=UTF-8"
Response Example
HTTP/1.1 200 OK Content-Type:application/json;charset=UTF-8 { "code": 0, "message": "The staff has been removed" }
Post comment
Post comment to a project
POST /projects/:project_id/comments
Request Example
$ curl https://books.zoho.com/api/v3/projects/:project_id/comments?organization_id=10234695 -H "Authorization: Zoho-authtoken ba4604e8e433g9c892e360d53463oec5" -H "Content-Type: application/json;charset=UTF-8" -d '{ "description": "Billing based on task hours" }
Response Example
HTTP/1.1 201 Created Content-Type:application/json;charset=UTF-8 { "code": 0, "message": "Comments added.", "comments": [ { "project_id": "460000000044019", "comment_id": "460000000044027", "description": "A simple algorithm is to be tested with vehicle detection application.", "commented_by_id": "460000000024003", "commented_by": "John David", "date": "6:52 PM", "date_description": "19 days ago", "time": "6:52 PM" } ] }
ARGUMENTS
|
description
Required
Project description.
Max-length [500] |
List comments
Get comments for a project.
GET /projects/:project_id/comments
Request Example
$ curl https://books.zoho.com/api/v3/projects/:project_id/comments?organization_id=10234695 -H "Authorization: Zoho-authtoken ba4604e8e433g9c892e360d53463oec5" -H "Content-Type: application/json;charset=UTF-8"
Response Example
HTTP/1.1 200 OK Content-Type:application/json;charset=UTF-8 { "code": 0, "message": "success", "comments": [ { "comment_id": "460000000044027", "project_id": "460000000044019", "description": "A simple algorithm is to be tested with vehicle detection application.", "commented_by_id": "460000000024003", "commented_by": "John David", "is_current_user": true, "date": "6:52 PM", "date_description": "19 days ago", "time": "6:52 PM" } ] }
Delete comment
Deleting a comment
DELETE /projects/:project_id
Request Example
$ curl https://books.zoho.com/api/v3/projects/:project_id?organization_id=10234695 -H "Authorization: Zoho-authtoken ba4604e8e433g9c892e360d53463oec5" -H "Content-Type: application/json;charset=UTF-8"
Response Example
HTTP/1.1 200 OK Content-Type:application/json;charset=UTF-8 { "code": 0, "message": "The comment has been deleted." }
List invoices
Lists invoices created for this project.
GET /projects/:project_id/invoices
Request Example
$ curl https://books.zoho.com/api/v3/projects/:project_id/invoices?organization_id=10234695 -H "Authorization: Zoho-authtoken ba4604e8e433g9c892e360d53463oec5" -H "Content-Type: application/json;charset=UTF-8"
Response Example
HTTP/1.1 200 OK Content-Type:application/json;charset=UTF-8 { "code": 0, "message": "success", "invoices": [ { "invoice_id": "460000000044001", "customer_name": "SAF Instruments Inc", "status": "active", "invoice_number": "INV-00004", "reference_number": " ", "date": "6:52 PM", "due_date": "6:52 PM", "total": "310.75", "balance": "48.75", "created_time": "2013-09-18T18:05:27+0530" } ], "page_context": { "page": 10, "per_page": 450, "report_name": "Projects", "has_more_page": false, "sort_order": "D", "sort_column": "created_time" } }
Query Params
|
sort_column
Optional
Sort invoices raised. Allowed Values:
invoice_number, date, total, balance and created_time |
Tasks
A project comprises of a single or multiple tasks that need to be completed. You need a task to the project before you log time.
Example
{ "project_id": "90300000072369", "task_id": "90300000072369", "customer_id": "903000000000099", "currency_id": 982000000000190, "task_name": "Painting", "project_name": "Furniture Manufacturing", "customer_name": "Sujin Kumar", "billed_hours": "12:06", "log_time": "13:06", "un_billed_hours": "01:00", "description": "", "rate": 3, "budget_hours": "" }
Attribute
|
project_id
string
Unique ID of the project generated by the server.
task_id
string
Unique ID of the task generated by the server.
customer_id
string
Customer ID of the customer for whom the task is created.
currency_id
string
The currenct id of the currency
task_name
string
The name of the task.
Max-length [100]
project_name
string
The name of the project
customer_name
string
Name of the customer to whom the task is created.
billed_hours
double
The total hours that are billed.
log_time
double
Total hours logged in the project.
un_billed_hours
double
Total hours that are unbilled.
description
string
The description of the project.
rate
integer
Hourly rate for a task.
budget_hours
integer
Task budget hours.
|
Add a task
The task has been added.
POST /projects/:project_id/tasks
Request Example
$ curl https://books.zoho.com/api/v3/projects/:project_id/tasks?organization_id=10234695 -H "Authorization: Zoho-authtoken ba4604e8e433g9c892e360d53463oec5" -H "Content-Type: application/json;charset=UTF-8" -d '{ "task_name": "Painting", "description": "", "rate": 3, "budget_hours": "" }
Response Example
HTTP/1.1 201 Created Content-Type:application/json;charset=UTF-8 { "code": 0, "message": "The project information has been updated.", "tasks": { "task": [ { "project_id": "90300000072369", "task_id": "90300000072369", "currency_id": 982000000000190, "customer_id": "903000000000099", "task_name": "Painting", "project_name": "Furniture Manufacturing", "customer_name": "Sujin Kumar", "billed_hours": "12:06", "log_time": "13:06", "un_billed_hours": "01:00" } ] } }
ARGUMENTS
|
task_name
Required
The name of the task.
Max-length [100]
description
Optional
The description of the project.
rate
Optional
Hourly rate for a task.
budget_hours
Optional
Task budget hours.
|
Update a task
Update the details of a task.
PUT /projects/:project_id/tasks/:task_id
Request Example
$ curl https://books.zoho.com/api/v3/projects/:project_id/tasks/:task_id?organization_id=10234695 -H "Authorization: Zoho-authtoken ba4604e8e433g9c892e360d53463oec5" -H "Content-Type: application/json;charset=UTF-8" -d '{ "task_name": "Painting", "description": "", "rate": 3, "budget_hours": "" }
Response Example
HTTP/1.1 200 OK Content-Type:application/json;charset=UTF-8 { "code": 0, "message": "The task information has been updated.", "tasks": { "task": [ { "project_id": "90300000072369", "task_id": "90300000072369", "currency_id": 982000000000190, "customer_id": "903000000000099", "task_name": "Painting", "project_name": "Furniture Manufacturing", "customer_name": "Sujin Kumar", "billed_hours": "12:06", "log_time": "13:06", "un_billed_hours": "01:00" } ] } }
ARGUMENTS
|
task_name
Required
The name of the task.
Max-length [100]
description
Optional
The description of the project.
rate
Optional
Hourly rate for a task.
budget_hours
Optional
Task budget hours.
|
List tasks
Get list of tasks added to a project.
GET /projects/:project_id/tasks
Request Example
$ curl https://books.zoho.com/api/v3/projects/:project_id/tasks?organization_id=10234695 -H "Authorization: Zoho-authtoken ba4604e8e433g9c892e360d53463oec5" -H "Content-Type: application/json;charset=UTF-8" -d '{ "sort_column": "created_time" }
Response Example
HTTP/1.1 200 OK Content-Type:application/json;charset=UTF-8 { "code": 0, "message": "success", "tasks": [ { "task": [ { "project_id": "90300000072369", "task_id": "90300000072369", "currency_id": 982000000000190, "customer_id": "903000000000099", "task_name": "Painting", "project_name": "Furniture Manufacturing", "customer_name": "Sujin Kumar", "billed_hours": "12:06", "log_time": "13:06", "un_billed_hours": "01:00" } ], "page_context": { "page": 1, "per_page": 200, "has_more_page": false, "report_name": "Tasks", "sort_column": "created_time", "sort_order": "D" } }, {...}, {...} ] }
ARGUMENTS
|
sort_column
Optional
Sort tasks: Allowed Values:
task_name, billes_hours, log_time and un_billes_hours. |
Get a task
Get the details of a task.
GET /projects/:project_id/tasks/:task_id
Request Example
$ curl https://books.zoho.com/api/v3/projects/:project_id/tasks/:task_id?organization_id=10234695 -H "Authorization: Zoho-authtoken ba4604e8e433g9c892e360d53463oec5" -H "Content-Type: application/json;charset=UTF-8" -d '{ "task_id": "90300000072369" }
Response Example
HTTP/1.1 200 OK Content-Type:application/json;charset=UTF-8 { "code": 0, "message": "success", "tasks": { "task": [ { "project_id": "90300000072369", "project_name": "Furniture Manufacturing", "task_id": "90300000072369", "task_name": "Painting", "description": "", "rate": 3, "status": "active", "is_billable": true } ] } }
ARGUMENTS
|
task_id
Optional
Unique ID of the task generated by the server.
|
Delete Task
Delete a task added to a project.
DELETE /projects/:project_id/tasks/:task_id
Request Example
$ curl https://books.zoho.com/api/v3/projects/:project_id/tasks/:task_id?organization_id=10234695 -H "Authorization: Zoho-authtoken ba4604e8e433g9c892e360d53463oec5" -H "Content-Type: application/json;charset=UTF-8" -d '{ "task_id": "90300000072369" }
Response Example
HTTP/1.1 200 OK Content-Type:application/json;charset=UTF-8 { "code": 0, "message": "The task has been deleted successfully.", "tasks": {...} }
ARGUMENTS
|
task_id
Optional
Unique ID of the task generated by the server.
|
Time-Entries
Time entries are various entries of time made by users in a project, based on the time they spent on a project, in a task.
Example
{ "project_id": "460000000044019", "task_id": "460000000044009", "user_id": "460000000024003", "log_date": "2013-09-17" }
Attribute
|
project_id
string
Search time entries by project_id.
task_id
string
ID of the task.
user_id
string
Search time entries by user_id.
log_date
string
Date on which the user spent on the task.
Date-Format [HH:mm] |
Log time entries
Logging time entries.
POST /projects/timeentries
Request Example
$ curl https://books.zoho.com/api/v3/projects/timeentries?organization_id=10234695 -H "Authorization: Zoho-authtoken ba4604e8e433g9c892e360d53463oec5" -H "Content-Type: application/json;charset=UTF-8" -d '{ "project_id": "Network Distribution", "task_id": "460000000044001", "user_id": "460000000024003", "log_date": "2013-09-17", "log_time": " ", "begin_time": "10:00", "end_time": "15:00", "is_billable": true, "notes": " ", "start_timer": " " }
Response Example
HTTP/1.1 201 Created Content-Type:application/json;charset=UTF-8 { "code": 0, "message": "Your timesheet entry has been added.", "projects": { "time_entry": { "time_entry_id": "460000000044021", "project_id": "460000000044019", "project_name": "REAL TIME TRAFFIC FLUX", "customer_id": "460000000044001", "customer_name": "SAF Instruments Inc", "task_id": "460000000044009", "task_name": "Distribution Analysis", "user_id": "460000000024003", "user_name": "John David", "is_current_user": true, "log_date": "2013-09-17", "begin_time": "03:00", "end_time": "04:00", "log_time": "05:00", "is_billable": true, "billed_status": "unbilled", "invoice_id": "", "notes": " ", "timer_started_at": " ", "timer_started_at_utc_time": "", "timer_duration_in_minutes": " ", "timer_duration_in_seconds": "", "created_time": "2013-09-18T18:05:27+0530", "timesheet_custom_fields": "" } } }
ARGUMENTS
|
project_id
Required
ID of the project.
task_id
Required
ID of the task.
user_id
Required
ID of the user.
log_date
Required
Date on which the user spent on the task.
Date-Format [HH:mm]
log_time
Optional
Time the user spent on this task. Either send this attribute or begin and end time attributes.
Time-Format [HH:mm]
begin_time
Optional
Time the user started working on this task.
Time-Format [HH:mm]
end_time
Optional
Time the user stopped working on this task.
Time-Format [HH:mm]
is_billable
Optional
Whether it is billable or not.
notes
Optional
Description of the work done.
Max-length [500]
start_timer
Optional
Start timer.
|
Update time entry
Update logged time entry
PUT /projects/timeentries/:time_entry_id
Request Example
$ curl https://books.zoho.com/api/v3/projects/timeentries/:time_entry_id?organization_id=10234695 -H "Authorization: Zoho-authtoken ba4604e8e433g9c892e360d53463oec5" -H "Content-Type: application/json;charset=UTF-8" -d '{ "project_id": "Network Distribution", "task_id": "460000000044001", "user_id": "460000000024003", "log_date": "2013-09-17", "log_time": " ", "begin_time": "10:00", "end_time": "15:00", "is_billable": true, "notes": " ", "start_timer": " " }
Response Example
HTTP/1.1 200 OK Content-Type:application/json;charset=UTF-8 { "code": 0, "message": "The timesheet's information has been updated.", "projects": { "time_entry": { "time_entry_id": "460000000044021", "project_id": "460000000044019", "project_name": "REAL TIME TRAFFIC FLUX", "customer_id": "460000000044001", "customer_name": "SAF Instruments Inc", "task_id": "460000000044009", "task_name": "Distribution Analysis", "user_id": "460000000024003", "user_name": "John David", "is_current_user": true, "log_date": "2013-09-17", "begin_time": "03:00", "end_time": "04:00", "log_time": "05:00", "is_billable": true, "billed_status": "unbilled", "invoice_id": "", "notes": " ", "timer_started_at": " ", "timer_started_at_utc_time": "", "timer_duration_in_minutes": " ", "timer_duration_in_seconds": "", "created_time": "2013-09-18T18:05:27+0530", "timesheet_custom_fields": "" } } }
ARGUMENTS
|
project_id
Required
ID of the project.
task_id
Required
ID of the task.
user_id
Required
ID of the user.
log_date
Required
Date on which the user spent on the task.
Date-Format [HH:mm]
log_time
Optional
Time the user spent on this task. Either send this attribute or begin and end time attributes.
Time-Format [HH:mm]
begin_time
Optional
Time the user started working on this task.
Time-Format [HH:mm]
end_time
Optional
Time the user stopped working on this task.
Time-Format [HH:mm]
is_billable
Optional
Whether it is billable or not.
notes
Optional
Description of the work done.
Max-length [500]
start_timer
Optional
Start timer.
|
List time entries.
List all time entries with pagination.
GET /projects/timeentries
Request Example
$ curl https://books.zoho.com/api/v3/projects/timeentries?organization_id=10234695 -H "Authorization: Zoho-authtoken ba4604e8e433g9c892e360d53463oec5" -H "Content-Type: application/json;charset=UTF-8"
Response Example
HTTP/1.1 200 OK Content-Type:application/json;charset=UTF-8 { "code": 0, "message": "success", "time_entries": [ { "time_entry_id": "460000000044021", "project_id": "460000000044019", "project_name": "REAL TIME TRAFFIC FLUX", "customer_id": "460000000044001", "customer_name": "SAF Instruments Inc", "task_id": "460000000044009", "task_name": "Distribution Analysis", "user_id": "460000000024003", "is_current_user": true, "user_name": "John David", "log_date": "2013-09-17", "begin_time": "03:00", "end_time": "04:00", "log_time": "05:00", "is_billable": true, "billed_status": "unbilled", "invoice_id": "", "notes": " ", "timer_started_at": " ", "timer_duration_in_minutes": " ", "created_time": "2013-09-18T18:05:27+0530" } ], "page_context": [ { "page": 10, "per_page": 450, "report_name": "Projects", "has_more_page": false, "sort_order": "D", "sort_column": "customer_name" } ] }
Query Params
|
from_date
Optional
Date from which the time entries logged to be fetched
to_date
Optional
Date up to which the time entries logged to be fetched
filter_by
Optional
Filter time entries by date and status. Allowed Values:
Date.All, Date.Today, Date.ThisWeek, Date.ThisMonth, Date.ThisQuarter, Date.ThisYear, Date.PreviousDay, Date.PreviousWeek, Date.PreviousMonth, Date.PreviousQuarter, Date.PreviousYear, Date.CustomDate, Status.Unbilled and Status.Invoiced
project_id
Optional
Search time entries by project_id.
user_id
Optional
Search time entries by user_id.
sort_column
Optional
Sort time entries. Allowed Values:
project_name, task_name, user_name, log_date, timer_started_at and customer_name |
Get a time entry
Get details of a time entry.
GET /projects/timeentries/:time_entry_id
Request Example
$ curl https://books.zoho.com/api/v3/projects/timeentries/:time_entry_id?organization_id=10234695 -H "Authorization: Zoho-authtoken ba4604e8e433g9c892e360d53463oec5" -H "Content-Type: application/json;charset=UTF-8"
Response Example
HTTP/1.1 200 OK Content-Type:application/json;charset=UTF-8 { "code": 0, "message": "success", "time_entry": { "time_entry_id": "460000000044021", "project_id": "460000000044019", "project_name": "REAL TIME TRAFFIC FLUX", "customer_id": "460000000044001", "customer_name": "SAF Instruments Inc", "task_id": "460000000044009", "task_name": "Distribution Analysis", "user_id": "460000000024003", "user_name": "John David", "is_current_user": true, "log_date": "2013-09-17", "begin_time": "03:00", "end_time": "04:00", "log_time": "05:00", "is_billable": true, "billed_status": "unbilled", "invoice_id": "", "notes": " ", "timer_started_at": " ", "timer_started_at_utc_time": "", "timer_duration_in_minutes": " ", "timer_duration_in_seconds": "", "created_time": "2013-09-18T18:05:27+0530", "timesheet_custom_fields": "" } }
Delete time entry
Deleting a logged time entry.
DELETE /projects/timeentries/:time_entry_id
Request Example
$ curl https://books.zoho.com/api/v3/projects/timeentries/:time_entry_id?organization_id=10234695 -H "Authorization: Zoho-authtoken ba4604e8e433g9c892e360d53463oec5" -H "Content-Type: application/json;charset=UTF-8"
Response Example
HTTP/1.1 200 OK Content-Type:application/json;charset=UTF-8 { "code": 0, "message": "The time entry has been deleted." }
Delete time entries
Deleting time entries
Delete /projects/timeentries
Request Example
$ curl https://books.zoho.com/api/v3/projects/timeentries?organization_id=10234695 -H "Authorization: Zoho-authtoken ba4604e8e433g9c892e360d53463oec5" -H "Content-Type: application/json;charset=UTF-8" -d '{ "time_entry_ids": " " }
Response Example
HTTP/1.1 200 OK Content-Type:application/json;charset=UTF-8 { "code": 0, "message": "The selected timesheet entries have been deleted" }
ARGUMENTS
|
time_entry_ids
Required
ID of the time entries to be deleted.
|
Start timer
Start tracking time spent.
POST /projects/timeentries/:time_entry_id/timer/start
Request Example
$ curl https://books.zoho.com/api/v3/projects/timeentries/:time_entry_id/timer/start?organization_id=10234695 -H "Authorization: Zoho-authtoken ba4604e8e433g9c892e360d53463oec5" -H "Content-Type: application/json;charset=UTF-8"
Response Example
HTTP/1.1 200 OK Content-Type:application/json;charset=UTF-8 { "code": 0, "message": "The timer has been started.", "time_entry": { "time_entry_id": "460000000044021", "project_id": "460000000044019", "project_name": "REAL TIME TRAFFIC FLUX", "customer_id": "460000000044001", "customer_name": "SAF Instruments Inc", "task_id": "460000000044009", "task_name": "Distribution Analysis", "user_id": "460000000024003", "user_name": "John David", "is_current_user": true, "log_date": "2013-09-17", "begin_time": "03:00", "end_time": "04:00", "log_time": "05:00", "is_billable": true, "billed_status": "unbilled", "invoice_id": "", "notes": " ", "timer_started_at": " ", "timer_started_at_utc_time": "", "timer_duration_in_minutes": " ", "timer_duration_in_seconds": "", "created_time": "2013-09-18T18:05:27+0530", "timesheet_custom_fields": "" } }
Stop timer
Stop tracking time, say taking a break or leaving
POST /projects/timeentries/timer/stop
Request Example
$ curl https://books.zoho.com/api/v3/projects/timeentries/timer/stop?organization_id=10234695 -H "Authorization: Zoho-authtoken ba4604e8e433g9c892e360d53463oec5" -H "Content-Type: application/json;charset=UTF-8"
Response Example
HTTP/1.1 200 OK Content-Type:application/json;charset=UTF-8 { "code": 0, "message": "Timer has been stopped successfully.", "time_entry": { "time_entry_id": "460000000044021", "project_id": "460000000044019", "project_name": "REAL TIME TRAFFIC FLUX", "customer_id": "460000000044001", "customer_name": "SAF Instruments Inc", "task_id": "460000000044009", "task_name": "Distribution Analysis", "user_id": "460000000024003", "user_name": "John David", "is_current_user": true, "log_date": "2013-09-17", "begin_time": "03:00", "end_time": "04:00", "log_time": "05:00", "is_billable": true, "billed_status": "unbilled", "invoice_id": "", "notes": " ", "timer_started_at": " ", "timer_started_at_utc_time": "", "timer_duration_in_minutes": " ", "timer_duration_in_seconds": "", "created_time": "2013-09-18T18:05:27+0530", "timesheet_custom_fields": "" } }
Get timer
Get current running timer.
GET /projects/timeentries/runningtimer/me
Request Example
$ curl https://books.zoho.com/api/v3/projects/timeentries/runningtimer/me?organization_id=10234695 -H "Authorization: Zoho-authtoken ba4604e8e433g9c892e360d53463oec5" -H "Content-Type: application/json;charset=UTF-8"
Response Example
HTTP/1.1 200 OK Content-Type:application/json;charset=UTF-8 { "code": 0, "message": "success", "time_entry": { "time_entry_id": "460000000044021", "project_id": "460000000044019", "project_name": "REAL TIME TRAFFIC FLUX", "customer_id": "460000000044001", "customer_name": "SAF Instruments Inc", "task_id": "460000000044009", "task_name": "Distribution Analysis", "user_id": "460000000024003", "user_name": "John David", "is_current_user": true, "log_date": "2013-09-17", "begin_time": "03:00", "end_time": "04:00", "log_time": "05:00", "is_billable": true, "billed_status": "unbilled", "invoice_id": "", "notes": " ", "timer_started_at": " ", "timer_started_at_utc_time": "", "timer_duration_in_minutes": " ", "timer_duration_in_seconds": "", "created_time": "2013-09-18T18:05:27+0530", "timesheet_custom_fields": "" } }
Users
Users are various individuals/entities that are a part of an organisation. Each user will have a different role to play, like admin, staff etc., .
Example
{ "name": "Sujin Kumar", "email": "johndavid@zilliuminc.com" }
Attribute
|
name
string
name of the user
email
string
email address of the user
|
Create a user
Create a user for your organization.
POST /users
Request Example
$ curl https://books.zoho.com/api/v3/users?organization_id=10234695 -H "Authorization: Zoho-authtoken ba4604e8e433g9c892e360d53463oec5" -H "Content-Type: application/json;charset=UTF-8" -d '{ "name": "Sujin Kumar", "email": "johndavid@zilliuminc.com", "user_role": "admin" }
Response Example
HTTP/1.1 200 OK Content-Type:application/json;charset=UTF-8 { "code": 0, "message": "Your invitation has been sent.", "users": {...} }
ARGUMENTS
|
name
Required
name of the user
email
Required
email address of the user
user_role
Optional
Role to be assigned. Allowed Values:
staff, admin and timesheetstaff. |
Update a user
Update the details of a user.
PUT /users/:user_id
Request Example
$ curl https://books.zoho.com/api/v3/users/:user_id?organization_id=10234695 -H "Authorization: Zoho-authtoken ba4604e8e433g9c892e360d53463oec5" -H "Content-Type: application/json;charset=UTF-8" -d '{ "name": "Sujin Kumar", "email": "johndavid@zilliuminc.com", "user_role": "admin", "rate": 0, "budget_hours": 0 }
Response Example
HTTP/1.1 200 OK Content-Type:application/json;charset=UTF-8 { "code": 0, "message": "The user information has been updated.", "users": {...} }
ARGUMENTS
|
name
Required
name of the user
email
Required
email address of the user
user_role
Optional
Role to be assigned. Allowed Values:
staff, admin and timesheetstaff.
rate
Optional
Hourly rate for a task.
budget_hours
Optional
Task budget hours
|
List Users
Get the list of all users in the organization.
GET /users
Request Example
$ curl https://books.zoho.com/api/v3/users?organization_id=10234695 -H "Authorization: Zoho-authtoken ba4604e8e433g9c892e360d53463oec5" -H "Content-Type: application/json;charset=UTF-8"
Response Example
HTTP/1.1 200 OK Content-Type:application/json;charset=UTF-8 { "code": 0, "message": "success", "users": [ { "users": [ { "user_id": "982000000554041", "role_id": "982000000006005", "name": "Sujin Kumar", "email": "johndavid@zilliuminc.com", "user_role": "admin", "status": "active", "is_current_user": true, "photo_url": "https://contacts.zoho.com/file?ID=d27344a22bad8bb83a03722b4aa5bc6967c3135f24307fe40db8572782432fd6aae0110f8bb9c4c79e8e0f0cca5904aecfacbf079f13b48c295bacc89ae91fca&fs=thumb", "is_customer_segmented": false, "is_vendor_segmented": false, "user_type": "zoho" } ], "page_context": { "page": 1, "per_page": 10, "has_more_page": false, "report_name": "Users", "sort_column": "name", "sort_order": "A" } }, {...}, {...} ] }
Query Params
|
filter_by
Optional
Allowed Values:
Status.All, Status.Active, Status.Inactive, Status.Invited and Status.Deleted
sort_column
Optional
Sort users. Allowed Values:
name, email, user_role and status |
Get a user
Get the details of a user.
GET /users/:user_id
Request Example
$ curl https://books.zoho.com/api/v3/users/:user_id?organization_id=10234695 -H "Authorization: Zoho-authtoken ba4604e8e433g9c892e360d53463oec5" -H "Content-Type: application/json;charset=UTF-8"
Response Example
HTTP/1.1 200 OK Content-Type:application/json;charset=UTF-8 { "code": 0, "message": "success", "user": { "user": { "user_id": "982000000554041", "name": "Sujin Kumar", "email_ids": [ { "email": "johndavid@zilliuminc.com", "is_selected": true } ], "status": "active", "user_role": "admin", "user_type": "zoho", "role_id": "982000000006005", "photo_url": "https://contacts.zoho.com/file?ID=d27344a22bad8bb83a03722b4aa5bc6967c3135f24307fe40db8572782432fd6aae0110f8bb9c4c79e8e0f0cca5904aecfacbf079f13b48c295bacc89ae91fca&fs=thumb", "is_claimant": true, "created_time": "2016-06-05T02:30:08-0700", "custom_fields": "" } } }
Get current user
Get the details of the current user.
GET /users/me
Request Example
$ curl https://books.zoho.com/api/v3/users/me?organization_id=10234695 -H "Authorization: Zoho-authtoken ba4604e8e433g9c892e360d53463oec5" -H "Content-Type: application/json;charset=UTF-8"
Response Example
HTTP/1.1 200 OK Content-Type:application/json;charset=UTF-8 { "code": 0, "message": "success", "user": { "user": { "user_id": "982000000554041", "name": "Sujin Kumar", "email_ids": [ { "email": "johndavid@zilliuminc.com", "is_selected": true } ], "status": "active", "user_role": "admin", "user_type": "zoho", "role_id": "982000000006005", "photo_url": "https://contacts.zoho.com/file?ID=d27344a22bad8bb83a03722b4aa5bc6967c3135f24307fe40db8572782432fd6aae0110f8bb9c4c79e8e0f0cca5904aecfacbf079f13b48c295bacc89ae91fca&fs=thumb", "is_claimant": true, "created_time": "2016-06-05T02:30:08-0700", "custom_fields": "" } } }
Delete a user
Delete a user associated to the organization.
DELETE /users/:user_id
Request Example
$ curl https://books.zoho.com/api/v3/users/:user_id?organization_id=10234695 -H "Authorization: Zoho-authtoken ba4604e8e433g9c892e360d53463oec5" -H "Content-Type: application/json;charset=UTF-8"
Response Example
HTTP/1.1 200 OK Content-Type:application/json;charset=UTF-8 { "code": 0, "message": "The user has been removed from your organization.", "users": {...} }
Invite a user
Send invitation email to a user.
POST /users/:user_id/invite
Request Example
$ curl https://books.zoho.com/api/v3/users/:user_id/invite?organization_id=10234695 -H "Authorization: Zoho-authtoken ba4604e8e433g9c892e360d53463oec5" -H "Content-Type: application/json;charset=UTF-8"
Response Example
HTTP/1.1 200 OK Content-Type:application/json;charset=UTF-8 { "code": 0, "message": "Your invitation has been sent.", "users": {...} }
Mark user as active
Mark an inactive user as active.
POST /users/:user_id/active
Request Example
$ curl https://books.zoho.com/api/v3/users/:user_id/active?organization_id=10234695 -H "Authorization: Zoho-authtoken ba4604e8e433g9c892e360d53463oec5" -H "Content-Type: application/json;charset=UTF-8"
Response Example
HTTP/1.1 200 OK Content-Type:application/json;charset=UTF-8 { "code": 0, "message": "The user has been marked as active.", "users": {...} }
Mark user as inactive
Mark an active user as inactive.
POST /users/:user_id/inactive
Request Example
$ curl https://books.zoho.com/api/v3/users/:user_id/inactive?organization_id=10234695 -H "Authorization: Zoho-authtoken ba4604e8e433g9c892e360d53463oec5" -H "Content-Type: application/json;charset=UTF-8"
Response Example
HTTP/1.1 200 OK Content-Type:application/json;charset=UTF-8 { "code": 0, "message": "The user has been marked as inactive.", "users": {...} }
Items
Items are the products or services that you sell to your customers.
Example
{ "item_id": 45667789900, "name": "Hard Drive", "description": "500GB", "unit": "100GB", "status": "active", "product_type": "goods", "sku": "s12345" }
Attribute
|
item_id
string
ID of the item.
name
string
Name of the item. Max-length [100]
description
string
Description for the item. Max-length [2000]
unit
string
If there is a measurement unit for the items you are adding.
status
string
Status of the item. It can be
active or inactive
product_type
string
Specify the type of an item. Allowed values:
goods or service or digital_service.
sku
string
SKU value of item,should be unique throughout the product
|
Create an Item
Create a new item.
POST /items
Request Example
$ curl https://books.zoho.com/api/v3/items?organization_id=10234695 -H "Authorization: Zoho-authtoken ba4604e8e433g9c892e360d53463oec5" -H "Content-Type: application/json;charset=UTF-8" -d '{ "name": "Hard Drive", "rate": 120, "description": "500GB", "tax_id": 982000000037049, "tax_percentage": "70%", "sku": "s12345", "product_type": "goods", "account_id": " ", "avatax_tax_code": 982000000037049, "avatax_use_code": 982000000037049, "item_type": " ", "purchase_description": " ", "purchase_rate": " ", "purchase_account_id": " ", "inventory_account_id": " ", "vendor_id": " ", "reorder_level": " ", "initial_stock": " ", "initial_stock_rate": " ", "item_tax_preferences": [ { "tax_id": 982000000037049, "tax_specification": "intra" } ] }
Response Example
HTTP/1.1 201 Created Content-Type:application/json;charset=UTF-8 { "code": 0, "message": "The item has been added.", "item": { "item": { "item_id": 45667789900, "name": "Hard Drive", "status": "active", "description": "500GB", "rate": 120, "unit": "100GB", "tax_id": 982000000037049, "tax_name": "Sales Tax", "tax_percentage": "70%", "tax_type": "tax", "sku": "s12345", "product_type": "goods", "item_tax_preferences": [ { "tax_id": 982000000037049, "tax_specification": "intra" } ], "warehouses": [ { "warehouse_id": "", "warehouse_name": "", "status": "active", "is_primary": false, "warehouse_stock_on_hand": "", "warehouse_available_stock": "", "warehouse_actual_available_stock": "" } ] } } }
ARGUMENTS
|
name
Required
Name of the item. Max-length [100]
rate
Required
Price of the item.
description
Optional
Description for the item. Max-length [2000]
tax_id
Not applicable for the US and India Edition
Optional
ID of the tax to be associated to the item.
tax_percentage
Optional
Percent of the tax.
sku
Optional
SKU value of item,should be unique throughout the product
product_type
Optional
Specify the type of an item. Allowed values:
goods or service or digital_service.
hsn_or_sac
India Edition Only
Optional
HSN Code
is_taxable
India Edition and US Edition only
Optional
Boolean to track the taxability of the item.
tax_exemption_id
India Edition and US Edition only
Optional
ID of the tax exemption. Mandatory, if
is_taxable is false.
account_id
Optional
ID of the account to which the item has to be associated with.
avatax_tax_code
Avalara integration only
Optional
A tax code is a unique label used to group Items (products, services, or charges) together. Max-length [25]
avatax_use_code
Avalara integration only
Optional
Used to group like customers for
exemption purposes. It is a custom value that links customers to a tax
rule. Select from Avalara [standard codes][1] or enter a custom code.
Max-length [25]
item_type
Optional
Type of the item. Allowed values:
sales,purchases,sales_and_purchases and inventory. Default value will be sales.
purchase_description
Optional
Purchase description for the item.
purchase_rate
Optional
Purchase price of the item.
purchase_account_id
Optional
ID of the COGS account to which the
item has to be associated with. Mandatory, if item_type is purchase /
sales and purchase / inventory.
inventory_account_id
Optional
ID of the stock account to which the item has to be associated with. Mandatory, if item_type is inventory.
vendor_id
Optional
Preferred vendor ID.
reorder_level
Optional
Reorder level of the item.
initial_stock
Optional
Opening stock of the item.
initial_stock_rate
Optional
Unit price of the opening stock.
item_tax_preferences
India Edition only
Optional
tax_id
India Edition only
Optional
ID of the tax to be associated to the item.
tax_specification
India Edition only
Optional
Set whether the tax type is intra/interstate
|
Update an item
Update the details of an item.
PUT /items/{item_id}
Request Example
$ curl https://books.zoho.com/api/v3/items/{item_id}?organization_id=10234695 -H "Authorization: Zoho-authtoken ba4604e8e433g9c892e360d53463oec5" -H "Content-Type: application/json;charset=UTF-8" -d '{ "name": "Hard Drive", "rate": 120, "description": "500GB", "tax_id": 982000000037049, "tax_percentage": "70%", "sku": "s12345", "product_type": "goods", "account_id": " ", "avatax_tax_code": 982000000037049, "avatax_use_code": 982000000037049, "item_type": " ", "purchase_description": " ", "purchase_rate": " ", "purchase_account_id": " ", "inventory_account_id": " ", "vendor_id": " ", "reorder_level": " ", "initial_stock": " ", "initial_stock_rate": " ", "item_tax_preferences": [ { "tax_id": 982000000037049, "tax_specification": "intra" } ] }
Response Example
HTTP/1.1 200 OK Content-Type:application/json;charset=UTF-8 { "code": 0, "message": "Item details have been saved.", "item": { "item": { "item_id": 45667789900, "name": "Hard Drive", "status": "active", "description": "500GB", "rate": 120, "unit": "100GB", "tax_id": 982000000037049, "tax_name": "Sales Tax", "tax_percentage": "70%", "tax_type": "tax", "sku": "s12345", "product_type": "goods", "item_tax_preferences": [ { "tax_id": 982000000037049, "tax_specification": "intra" } ], "warehouses": [ { "warehouse_id": "", "warehouse_name": "", "status": "active", "is_primary": false, "warehouse_stock_on_hand": "", "warehouse_available_stock": "", "warehouse_actual_available_stock": "" } ] } } }
ARGUMENTS
|
name
Required
Name of the item. Max-length [100]
rate
Required
Price of the item.
description
Optional
Description for the item. Max-length [2000]
tax_id
Not applicable for the US and India Edition
Optional
ID of the tax to be associated to the item.
tax_percentage
Optional
Percent of the tax.
hsn_or_sac
India Edition Only
Optional
HSN Code
sku
Optional
SKU value of item,should be unique throughout the product
product_type
Optional
Specify the type of an item. Allowed values:
goods or service or digital_service.
is_taxable
India Edition and US Edition only
Optional
Boolean to track the taxability of the item.
tax_exemption_id
India Edition and US Edition only
Optional
ID of the tax exemption. Mandatory, if
is_taxable is false.
account_id
Optional
ID of the account to which the item has to be associated with.
avatax_tax_code
Avalara integration only
Optional
A tax code is a unique label used to group Items (products, services, or charges) together. Max-length [25]
avatax_use_code
Avalara integration only
Optional
Used to group like customers for
exemption purposes. It is a custom value that links customers to a tax
rule. Select from Avalara [standard codes][1] or enter a custom code.
Max-length [25]
item_type
Optional
Type of the item. Allowed values:
sales,purchases,sales_and_purchases and inventory. Default value will be sales.
purchase_description
Optional
Purchase description for the item.
purchase_rate
Optional
Purchase price of the item.
purchase_account_id
Optional
ID of the COGS account to which the
item has to be associated with. Mandatory, if item_type is purchase /
sales and purchase / inventory.
inventory_account_id
Optional
ID of the stock account to which the item has to be associated with. Mandatory, if item_type is inventory.
vendor_id
Optional
Preferred vendor ID.
reorder_level
Optional
Reorder level of the item.
initial_stock
Optional
Opening stock of the item.
initial_stock_rate
Optional
Unit price of the opening stock.
item_tax_preferences
India Edition only
Optional
tax_id
India Edition only
Optional
ID of the tax to be associated to the item.
tax_specification
India Edition only
Optional
Set whether the tax type is intra/interstate
|
Get an item
Details of an existing item.
GET /items/{item_id}
Request Example
$ curl https://books.zoho.com/api/v3/items/{item_id}?organization_id=10234695 -H "Authorization: Zoho-authtoken ba4604e8e433g9c892e360d53463oec5" -H "Content-Type: application/json;charset=UTF-8"
Response Example
HTTP/1.1 200 OK Content-Type:application/json;charset=UTF-8 { "code": 0, "message": "success", "product": { "item": { "item_id": 45667789900, "name": "Hard Drive", "status": "active", "description": "500GB", "rate": 120, "unit": "100GB", "tax_id": 982000000037049, "tax_name": "Sales Tax", "tax_percentage": "70%", "tax_type": "tax", "sku": "s12345", "product_type": "goods", "item_tax_preferences": [ { "tax_id": 982000000037049, "tax_specification": "intra" } ], "warehouses": [ { "warehouse_id": "", "warehouse_name": "", "status": "active", "is_primary": false, "warehouse_stock_on_hand": "", "warehouse_available_stock": "", "warehouse_actual_available_stock": "" } ] } } }
List items
Get the list of all active items with pagination.
GET /items
Request Example
$ curl https://books.zoho.com/api/v3/items?organization_id=10234695 -H "Authorization: Zoho-authtoken ba4604e8e433g9c892e360d53463oec5" -H "Content-Type: application/json;charset=UTF-8"
Response Example
HTTP/1.1 200 OK Content-Type:application/json;charset=UTF-8 { "code": 0, "message": "success", "items": [ { "items": [ { "item_id": 45667789900, "name": "Hard Drive", "status": "active", "description": "500GB", "rate": 120, "unit": "100GB", "tax_id": 982000000037049, "tax_name": "Sales Tax", "tax_percentage": "70%", "tax_type": "tax", "sku": "s12345", "product_type": "goods" } ], "page_context": { "page": 1, "per_page": 200, "has_more_page": false, "report_name": "Items", "sort_order": "A" } }, {...}, {...} ] }
Query Params
|
name
Optional
Search items by name. Max-length [100]. Variants:
name_startswith and name_contains
description
Optional
Search items by description. Max-length [100]. Variants:
description_startswith and description_contains
rate
Optional
Search items by rate. Variants:
rate_less_than, rate_less_equals, rate_greater_than and rate_greater_equals
tax_id
Optional
Search items by tax id.
tax_name
Optional
is_taxable
India Edition and US Edition only
Optional
Boolean to track the taxability of the item.
tax_exemption_id
India Edition and US Edition only
Optional
ID of the tax exemption. Mandatory, if
is_taxable is false.
account_id
Optional
ID of the account to which the item has to be associated with.
filter_by
Optional
Filter items by status. Allowed Values:
Status.All, Status.Active and Status.Inactive
search_text
Optional
Search items by name or description. Max-length [100]
sort_column
Optional
Sort items. Allowed Values:
name, rate and tax_name |
Delete an item
Delete the item created.items that are part of transaction cannot be deleted.
DELETE /items/{item_id}
Request Example
$ curl https://books.zoho.com/api/v3/items/{item_id}?organization_id=10234695 -H "Authorization: Zoho-authtoken ba4604e8e433g9c892e360d53463oec5" -H "Content-Type: application/json;charset=UTF-8"
Response Example
HTTP/1.1 200 OK Content-Type:application/json;charset=UTF-8 { "code": 0, "message": "The item has been deleted." }
Mark as active
Mark an inactive item as active.
POST /items/{item_id}/active
Request Example
$ curl https://books.zoho.com/api/v3/items/{item_id}/active?organization_id=10234695 -H "Authorization: Zoho-authtoken ba4604e8e433g9c892e360d53463oec5" -H "Content-Type: application/json;charset=UTF-8"
Response Example
HTTP/1.1 200 OK Content-Type:application/json;charset=UTF-8 { "code": 0, "message": "The item has been marked as active." }
Mark as inactive
Mark an active item as inactive.
POST /items/{item_id}/inactive
Request Example
$ curl https://books.zoho.com/api/v3/items/{item_id}/inactive?organization_id=10234695 -H "Authorization: Zoho-authtoken ba4604e8e433g9c892e360d53463oec5" -H "Content-Type: application/json;charset=UTF-8"
Response Example
HTTP/1.1 200 OK Content-Type:application/json;charset=UTF-8 { "code": 0, "message": "The item has been marked as inactive." }
Currency
In case your organization sells products or provides services to customer from different countries, you can add those currencies and exchange rates you deal with, to your Zoho Books account.
Example
{ "currency_id": "982000000004012", "currency_code": "AUD", "currency_name": "AUD- Australian Dollar", "currency_symbol": "$", "price_precision": 2, "currency_format": "1,234,567.89", "is_base_currency": false, "exchange_rate": 1, "effective_date": "2013-09-04" }
Attribute
|
currency_id
string
A unique ID for the currency.
currency_code
string
A unique standard code for the currency. Max-len [100]
currency_name
sring
The name for the currency.
currency_symbol
string
A unique symbol for the currency. Max-len [4]
price_precision
integer
The precision for the price
currency_format
string
The format for the currency to be displayed. Max-len [100]
is_base_currency
boolean
Is it the base currency of the organization.
exchange_rate
double
Exchange rate for the currency.
effective_date
string
Date which the exchange rate is applicable for the currency.
|
Create a Currency
Create a currency for transaction.
POST /settings/currencies
Request Example
$ curl https://books.zoho.com/api/v3/settings/currencies?organization_id=10234695 -H "Authorization: Zoho-authtoken ba4604e8e433g9c892e360d53463oec5" -H "Content-Type: application/json;charset=UTF-8" -d '{ "currency_code": "AUD", "currency_symbol": "$", "price_precision": 2, "currency_format": "1,234,567.89" }
Response Example
HTTP/1.1 201 Created Content-Type:application/json;charset=UTF-8 { "code": 0, "message": "The currency has been added.", "currency": { "currency": { "currency_id": "982000000004012", "currency_code": "AUD", "currency_name": "AUD- Australian Dollar", "currency_symbol": "$", "price_precision": 2, "currency_format": "1,234,567.89", "is_base_currency": false } } }
ARGUMENTS
|
currency_code
Required
A unique standard code for the currency. Max-len [100]
currency_symbol
Optional
A unique symbol for the currency. Max-len [4]
price_precision
Optional
The precision for the price
currency_format
Required
The format for the currency to be displayed. Max-len [100]
|
Update a Currency
Update the details of a currency.
PUT /settings/currencies/:currency_id
Request Example
$ curl https://books.zoho.com/api/v3/settings/currencies/:currency_id?organization_id=10234695 -H "Authorization: Zoho-authtoken ba4604e8e433g9c892e360d53463oec5" -H "Content-Type: application/json;charset=UTF-8" -d '{ "currency_code": "AUD", "currency_symbol": "$", "price_precision": 2, "currency_format": "1,234,567.89" }
Response Example
HTTP/1.1 200 OK Content-Type:application/json;charset=UTF-8 { "code": 0, "message": "Currency information has been saved.", "currency": { "currency": { "currency_id": "982000000004012", "currency_code": "AUD", "currency_name": "AUD- Australian Dollar", "currency_symbol": "$", "price_precision": 2, "currency_format": "1,234,567.89", "is_base_currency": false } } }
ARGUMENTS
|
currency_code
Required
A unique standard code for the currency. Max-len [100]
currency_symbol
Optional
A unique symbol for the currency. Max-len [4]
price_precision
Optional
The precision for the price
currency_format
Required
The format for the currency to be displayed. Max-len [100]
|
List Currencies
Get list of currencies configured.
GET /settings/currencies
Request Example
$ curl https://books.zoho.com/api/v3/settings/currencies?organization_id=10234695 -H "Authorization: Zoho-authtoken ba4604e8e433g9c892e360d53463oec5" -H "Content-Type: application/json;charset=UTF-8"
Response Example
HTTP/1.1 200 OK Content-Type:application/json;charset=UTF-8 { "code": 0, "message": "success", "currencies": [ { "currency_id": "982000000004012", "currency_code": "AUD", "currency_name": "AUD- Australian Dollar", "currency_symbol": "$", "price_precision": 2, "currency_format": "1,234,567.89", "is_base_currency": false, "exchange_rate": 1, "effective_date": "2013-09-04" }, {...}, {...} ] }
Query Params
|
filter_by
Optional
Filter currencies excluding base currency. Allowed Values:
Currencies.ExcludeBaseCurrency |
Get a Currency
Get the details of a currency.
GET /settings/currencies/:currency_id
Request Example
$ curl https://books.zoho.com/api/v3/settings/currencies/:currency_id?organization_id=10234695 -H "Authorization: Zoho-authtoken ba4604e8e433g9c892e360d53463oec5" -H "Content-Type: application/json;charset=UTF-8"
Response Example
HTTP/1.1 200 OK Content-Type:application/json;charset=UTF-8 { "code": 0, "message": "success", "currency": { "currency": { "currency_id": "982000000004012", "currency_code": "AUD", "currency_name": "AUD- Australian Dollar", "currency_symbol": "$", "price_precision": 2, "currency_format": "1,234,567.89", "is_base_currency": false } } }
Delete a currency
Delete a currency. Currency that is associated to transactions cannot be deleted.
DELETE /settings/currencies/:currency_id
Request Example
$ curl https://books.zoho.com/api/v3/settings/currencies/:currency_id?organization_id=10234695 -H "Authorization: Zoho-authtoken ba4604e8e433g9c892e360d53463oec5" -H "Content-Type: application/json;charset=UTF-8"
Response Example
HTTP/1.1 200 OK Content-Type:application/json;charset=UTF-8 { "code": 0, "message": "The currency has been deleted." }
List exchange rates
List of exchange rates configured for the currency.
GET /settings/currencies/{currency_id}/exchangerates
Request Example
$ curl https://books.zoho.com/api/v3/settings/currencies/{currency_id}/exchangerates?organization_id=10234695 -H "Authorization: Zoho-authtoken ba4604e8e433g9c892e360d53463oec5" -H "Content-Type: application/json;charset=UTF-8"
Response Example
HTTP/1.1 200 OK Content-Type:application/json;charset=UTF-8 { "code": 0, "message": "success", "exchange_rates": [ { "exchange_rate_id": "460000000038035", "currency_id": "982000000004012", "currency_code": "AUD", "effective_date": "2013-09-04", "rate": 1.23 }, {...}, {...} ] }
Query Params
|
from_date
Optional
Returns the exchange rate details from
the given date or from previous closest match in the absence of the
exchange rate on the given date.
is_current_date
Optional
To return the exchange rate only if available for current date.
sort_column
Optional
Sorts the exchange rate according to this column. Allowed Values :
effective_date |
Get an exchange rate.
Get the details of an exchange rate that has been asscoiated to the currency.
GET /settings/currencies/{currency_id}/exchangerates/{exchange_rate_id}
Request Example
$ curl https://books.zoho.com/api/v3/settings/currencies/{currency_id}/exchangerates/{exchange_rate_id}?organization_id=10234695 -H "Authorization: Zoho-authtoken ba4604e8e433g9c892e360d53463oec5" -H "Content-Type: application/json;charset=UTF-8"
Response Example
HTTP/1.1 200 OK Content-Type:application/json;charset=UTF-8 { "code": 0, "message": "success", "exchange_rate": 1 }
Create an exchange rate
Create an exchange rate for the specified currency.
POST /settings/currencies/{currency_id}/exchangerates
Request Example
$ curl https://books.zoho.com/api/v3/settings/currencies/{currency_id}/exchangerates?organization_id=10234695 -H "Authorization: Zoho-authtoken ba4604e8e433g9c892e360d53463oec5" -H "Content-Type: application/json;charset=UTF-8" -d '{ "effective_date": "2013-09-04", "rate": 1.23 }
Response Example
HTTP/1.1 201 Created Content-Type:application/json;charset=UTF-8 { "code": 0, "message": "The exchange rate has been added.", "exchange_rate": 1 }
ARGUMENTS
|
effective_date
Optional
Date which the exchange rate is applicable for the currency.
rate
Optional
Rate of exchange for the currency with respect to base currency.
|
Update an exchange rate
Update the details of exchange rate for a currency.
PUT /settings/currencies/{currency_id}/exchangerates/{exchange_rate_id}
Request Example
$ curl https://books.zoho.com/api/v3/settings/currencies/{currency_id}/exchangerates/{exchange_rate_id}?organization_id=10234695 -H "Authorization: Zoho-authtoken ba4604e8e433g9c892e360d53463oec5" -H "Content-Type: application/json;charset=UTF-8" -d '{ "effective_date": "2013-09-04", "rate": 1.23 }
Response Example
HTTP/1.1 200 OK Content-Type:application/json;charset=UTF-8 { "code": 0, "message": "The exchange rate has been updated." }
ARGUMENTS
|
effective_date
Optional
Date which the exchange rate is applicable for the currency.
rate
Optional
Rate of exchange for the currency with respect to base currency.
|
Delete an exchage rate
Delete an exchange rate for the specified currency.
DELETE /settings/currencies/{currency_id}/exchangerates/{exchange_rate_id}
Request Example
$ curl https://books.zoho.com/api/v3/settings/currencies/{currency_id}/exchangerates/{exchange_rate_id}?organization_id=10234695 -H "Authorization: Zoho-authtoken ba4604e8e433g9c892e360d53463oec5" -H "Content-Type: application/json;charset=UTF-8"
Response Example
HTTP/1.1 200 OK Content-Type:application/json;charset=UTF-8 { "code": 0, "message": "Exchange rate successfully deleted" }
Taxes
Your business’ financials are affected by regulatory taxes and each organization has different country specific taxes to adhere to.
Example
{ "tax_id": "982000000566009", "tax_name": "Sales Group", "tax_percentage": 10.5, "tax_type": "tax", "tax_group_id": "982000000566009", "tax_group_name": "Sales Group", "tax_group_percentage": 10.5 }
Attribute
|
tax_id
string
ID of the Tax
tax_name
string
Name of the Tax
tax_percentage
double
Number of Percentage Taxable.
tax_type
string
Type to determine whether it is a simple or compound tax.
Allowed Values: tax and compound_tax
tax_group_id
string
the id of the tax group
tax_group_name
string
Name of the tax group to be created.
tax_group_percentage
double
Number of percentage taxable.
|
Create a tax
Create a tax which can be associated with an item.
POST /settings/taxes
Request Example
$ curl https://books.zoho.com/api/v3/settings/taxes?organization_id=10234695 -H "Authorization: Zoho-authtoken ba4604e8e433g9c892e360d53463oec5" -H "Content-Type: application/json;charset=UTF-8" -d '{ "tax_name": "Sales Group", "tax_percentage": 10.5, "tax_type": "tax", "tax_authority_name": "Illinois Department of Revenue", "tax_authority_id": "460000000066001", "country_code": "UK", "is_value_added": false, "update_recurring_invoice": false, "update_recurring_expense": false, "update_draft_invoice": false, "update_recurring_bills": false, "update_draft_so": false, "update_subscription": false, "update_project": false, "is_editable": true }
Response Example
HTTP/1.1 201 Created Content-Type:application/json;charset=UTF-8 { "code": 0, "message": "The tax has been added.", "taxes": { "tax": [ { "tax_id": "982000000566009", "tax_name": "Sales Group", "tax_percentage": 10.5, "tax_type": "tax", "tax_authority_id": "460000000066001", "tax_authority_name": "Illinois Department of Revenue", "is_value_added": false, "country_code": "UK" } ] } }
ARGUMENTS
|
tax_name
Optional
Name of the Tax
tax_percentage
Optional
Number of Percentage Taxable.
tax_type
Optional
Type to determine whether it is a simple or compound tax.
Allowed Values: tax and compound_tax
tax_specific_type
India Edition Only
Optional
Type of Tax For Indian Edition. Allowed Values :
igst ,cgst ,sgst ,nil, cess
tax_authority_name
Optional
Name of the Tax Authority
tax_authority_id
US Edition only
Optional
ID of the tax authority. Tax authority
depends on the location of the customer. For example, if the customer
is located in NY, then the tax authority is NY tax authority.
country_code
UK, EU and Global Edition only
Optional
Two letter country code for the EU country to which the tax belongs.
purchase_tax_expense_account_id
AU and CA Edition Only
Optional
Account ID in which Purchase Tax will be Computed
is_value_added
Optional
Check if Tax is Value Added
update_recurring_invoice
Optional
Check if recurring invoice should be updated
update_recurring_expense
Optional
Check if recurring expenses should be updated
update_draft_invoice
Optional
Check if Draft Invoices should be updated
update_recurring_bills
Optional
Check if Recurring Bills should be updated
update_draft_so
Optional
Check if Draft Sales Orders should be updated
update_subscription
Optional
Check if Subscriptions should be updated
update_project
Optional
Check if Projects should be updated
is_editable
Optional
Check if tax is editable
|
Update a tax
Update the details of a simple or compound tax.
PUT /settings/taxes/{tax_id
Request Example
$ curl https://books.zoho.com/api/v3/settings/taxes/{tax_id?organization_id=10234695 -H "Authorization: Zoho-authtoken ba4604e8e433g9c892e360d53463oec5" -H "Content-Type: application/json;charset=UTF-8" -d '{ "tax_id": "982000000566009", "tax_name": "Sales Group", "tax_percentage": 10.5, "tax_type": "tax", "tax_authority_name": "Illinois Department of Revenue", "tax_authority_id": "460000000066001", "country_code": "UK", "is_value_added": false, "update_recurring_invoice": false, "update_recurring_expense": false, "update_draft_invoice": false, "update_recurring_bills": false, "update_draft_so": false, "update_subscription": false, "update_project": false, "is_editable": true }
Response Example
HTTP/1.1 200 OK Content-Type:application/json;charset=UTF-8 { "code": 0, "message": "Tax information has been saved.", "taxes": { "tax": [ { "tax_id": "982000000566009", "tax_name": "Sales Group", "tax_percentage": 10.5, "tax_type": "tax", "tax_authority_id": "460000000066001", "tax_authority_name": "Illinois Department of Revenue", "is_value_added": false, "country_code": "UK" } ] } }
ARGUMENTS
|
tax_id
Optional
ID of the Tax
tax_name
Optional
Name of the Tax
tax_percentage
Optional
Number of Percentage Taxable.
tax_type
Optional
Type to determine whether it is a simple or compound tax.
Allowed Values: tax and compound_tax
tax_specific_type
India Edition Only
Optional
Type of Tax For Indian Edition. Allowed Values :
igst ,cgst ,sgst ,nil, cess
tax_authority_name
Optional
Name of the Tax Authority
tax_authority_id
US Edition only
Optional
ID of the tax authority. Tax authority
depends on the location of the customer. For example, if the customer
is located in NY, then the tax authority is NY tax authority.
country_code
UK, EU and Global Edition only
Optional
Two letter country code for the EU country to which the tax belongs.
purchase_tax_expense_account_id
AU and CA Edition Only
Optional
Account ID in which Purchase Tax will be Computed
is_value_added
Optional
Check if Tax is Value Added
update_recurring_invoice
Optional
Check if recurring invoice should be updated
update_recurring_expense
Optional
Check if recurring expenses should be updated
update_draft_invoice
Optional
Check if Draft Invoices should be updated
update_recurring_bills
Optional
Check if Recurring Bills should be updated
update_draft_so
Optional
Check if Draft Sales Orders should be updated
update_subscription
Optional
Check if Subscriptions should be updated
update_project
Optional
Check if Projects should be updated
is_editable
Optional
Check if tax is editable
|
List taxes
List of simple and compound taxes with pagination.
GET /settings/taxes
Request Example
$ curl https://books.zoho.com/api/v3/settings/taxes?organization_id=10234695 -H "Authorization: Zoho-authtoken ba4604e8e433g9c892e360d53463oec5" -H "Content-Type: application/json;charset=UTF-8"
Response Example
HTTP/1.1 200 OK Content-Type:application/json;charset=UTF-8 { "code": 0, "message": "success", "taxes": [ { "taxes": [ { "tax_id": "982000000566009", "tax_name": "Sales Group", "tax_percentage": 10.5, "tax_type": "tax", "tax_authority_id": "460000000066001", "tax_authority_name": "Illinois Department of Revenue", "is_value_added": false, "is_default_tax": true, "is_editable": true } ], "page_context": { "page": 1, "per_page": 200, "has_more_page": false, "report_name": "Taxes", "applied_filter": "Status.All", "sort_column": "created_time", "sort_order": "D" } }, {...}, {...} ] }
Get a tax
Get the details of a simple or compound tax.
GET /settings/taxes/{tax_id}
Request Example
$ curl https://books.zoho.com/api/v3/settings/taxes/{tax_id}?organization_id=10234695 -H "Authorization: Zoho-authtoken ba4604e8e433g9c892e360d53463oec5" -H "Content-Type: application/json;charset=UTF-8"
Response Example
HTTP/1.1 200 OK Content-Type:application/json;charset=UTF-8 { "code": 0, "message": "success", "taxes": { "tax": [ { "tax_id": "982000000566009", "tax_name": "Sales Group", "tax_percentage": 10.5, "tax_type": "tax", "tax_authority_id": "460000000066001", "tax_authority_name": "Illinois Department of Revenue", "is_value_added": false, "country_code": "UK" } ] } }
Delete a tax
Delete a simple or compound tax.
DELETE /settings/taxes/{tax_id}
Request Example
$ curl https://books.zoho.com/api/v3/settings/taxes/{tax_id}?organization_id=10234695 -H "Authorization: Zoho-authtoken ba4604e8e433g9c892e360d53463oec5" -H "Content-Type: application/json;charset=UTF-8"
Response Example
HTTP/1.1 200 OK Content-Type:application/json;charset=UTF-8 { "code": 0, "message": "The record has been deleted." }
Get a tax group
Get the details of a tax group.
GET /settings/taxgroups/{tax_group_id}
Request Example
$ curl https://books.zoho.com/api/v3/settings/taxgroups/{tax_group_id}?organization_id=10234695 -H "Authorization: Zoho-authtoken ba4604e8e433g9c892e360d53463oec5" -H "Content-Type: application/json;charset=UTF-8"
Response Example
HTTP/1.1 200 OK Content-Type:application/json;charset=UTF-8 { "code": 0, "message": "success", "tax_group": { "tax_group_id": "982000000566009", "tax_group_name": "Sales Group", "tax_group_percentage": 10.5, "taxes": [ { "tax_id": "982000000566009", "tax_name": "Sales Group", "tax_percentage": 10.5, "tax_type": "tax", "tax_authority_id": "460000000066001", "tax_authority_name": "Illinois Department of Revenue" } ] } }
Create a tax group
Create a tax group associating multiple taxes..
POST /settings/taxgroups
Request Example
$ curl https://books.zoho.com/api/v3/settings/taxgroups?organization_id=10234695 -H "Authorization: Zoho-authtoken ba4604e8e433g9c892e360d53463oec5" -H "Content-Type: application/json;charset=UTF-8" -d '{ "tax_group_name": "Sales Group", "taxes": "982000000566009" }
Response Example
HTTP/1.1 201 Created Content-Type:application/json;charset=UTF-8 { "code": 0, "message": "success", "taxe group": { "tax_group": { "tax_group_id": "982000000566009", "tax_group_name": "Sales Group", "tax_group_percentage": 10.5, "taxes": [ { "tax_id": "982000000566009", "tax_name": "Sales Group", "tax_percentage": 10.5, "tax_type": "tax", "tax_authority_id": "460000000066001", "tax_authority_name": "Illinois Department of Revenue" } ] } } }
ARGUMENTS
|
tax_group_name
Optional
Name of the tax group to be created.
taxes
Optional
Comma Seperated list of tax IDs that are to be associated to the tax group.
|
Update a tax group
Update the details of the tax group.
PUT /settings/taxgroups/{tax_group_id}
Request Example
$ curl https://books.zoho.com/api/v3/settings/taxgroups/{tax_group_id}?organization_id=10234695 -H "Authorization: Zoho-authtoken ba4604e8e433g9c892e360d53463oec5" -H "Content-Type: application/json;charset=UTF-8" -d '{ "tax_group_name": "Sales Group", "taxes": "982000000566009" }
Response Example
HTTP/1.1 200 OK Content-Type:application/json;charset=UTF-8 { "code": 0, "message": "success", "taxes": { "tax_group": { "tax_group_id": "982000000566009", "tax_group_name": "Sales Group", "tax_group_percentage": 10.5, "taxes": [ { "tax_id": "982000000566009", "tax_name": "Sales Group", "tax_percentage": 10.5, "tax_type": "tax", "tax_authority_id": "460000000066001", "tax_authority_name": "Illinois Department of Revenue" } ] } } }
ARGUMENTS
|
tax_group_name
Optional
Name of the tax group to be created.
taxes
Optional
Comma Seperated list of tax IDs that are to be associated to the tax group.
|
Delete a tax group
Delete a tax group. Tax group that is associated to transactions cannot be deleted.
DELETE /settings/taxgroups/:tax_group_id
Request Example
$ curl https://books.zoho.com/api/v3/settings/taxgroups/:tax_group_id?organization_id=10234695 -H "Authorization: Zoho-authtoken ba4604e8e433g9c892e360d53463oec5" -H "Content-Type: application/json;charset=UTF-8"
Response Example
HTTP/1.1 200 OK Content-Type:application/json;charset=UTF-8 { "code": 0, "message": "The tax group has been deleted." }
Create a tax authority [US and CA Edition only]
Create a tax authority.
POST /settings/taxauthorities
Request Example
$ curl https://books.zoho.com/api/v3/settings/taxauthorities?organization_id=10234695 -H "Authorization: Zoho-authtoken ba4604e8e433g9c892e360d53463oec5" -H "Content-Type: application/json;charset=UTF-8" -d '{ "tax_authority_name": "Illinois Department of Revenue", "description": "The New York State Department of Taxation and Finance" }
Response Example
HTTP/1.1 201 Created Content-Type:application/json;charset=UTF-8 { "code": 0, "message": "Tax Authority has been added.", "tax_authority": { "tax_authority_id": "460000000066001", "tax_authority_name": "Illinois Department of Revenue", "description": "The New York State Department of Taxation and Finance" } }
ARGUMENTS
|
tax_authority_name
Required
Name of the Tax Authority
description
Optional
Description.
registration_number
CA Edition Only
Optional
Registration Number of the Tax Authority
registration_number_label
CA Edition Only
Optional
|
Update a tax authority [US and CA Edition only]
Update the details of a tax authority.
PUT /settings/taxauthorities/{tax_authority_id}
Request Example
$ curl https://books.zoho.com/api/v3/settings/taxauthorities/{tax_authority_id}?organization_id=10234695 -H "Authorization: Zoho-authtoken ba4604e8e433g9c892e360d53463oec5" -H "Content-Type: application/json;charset=UTF-8" -d '{ "tax_authority_name": "Illinois Department of Revenue", "description": "The New York State Department of Taxation and Finance" }
Response Example
HTTP/1.1 200 OK Content-Type:application/json;charset=UTF-8 { "code": 0, "message": "Tax Authority information has been updated.", "tax_authority": { "tax_authority_id": "460000000066001", "tax_authority_name": "Illinois Department of Revenue", "description": "The New York State Department of Taxation and Finance" } }
ARGUMENTS
|
tax_authority_name
Optional
Name of the Tax Authority
description
Optional
Description.
registration_number
CA Edition Only
Optional
Registration Number of the Tax Authority
registration_number_label
CA Edition Only
Optional
|
Get a tax authority [US and CA Edition only]
Get the details of a tax authority.
GET /settings/taxauthorities/{tax_authority_id}
Request Example
$ curl https://books.zoho.com/api/v3/settings/taxauthorities/{tax_authority_id}?organization_id=10234695 -H "Authorization: Zoho-authtoken ba4604e8e433g9c892e360d53463oec5" -H "Content-Type: application/json;charset=UTF-8"
Response Example
HTTP/1.1 200 OK Content-Type:application/json;charset=UTF-8 { "code": 0, "message": "success", "tax_authority": { "tax_authority_id": "460000000066001", "tax_authority_name": "Illinois Department of Revenue", "description": "The New York State Department of Taxation and Finance" } }
List tax authorities [US Edition only]
List of tax authorities
GET /settings/taxauthorities
Request Example
$ curl https://books.zoho.com/api/v3/settings/taxauthorities?organization_id=10234695 -H "Authorization: Zoho-authtoken ba4604e8e433g9c892e360d53463oec5" -H "Content-Type: application/json;charset=UTF-8"
Response Example
HTTP/1.1 200 OK Content-Type:application/json;charset=UTF-8 { "code": 0, "message": "success", "tax_authorities": [ { "tax_authority_id": "460000000066001", "tax_authority_name": "Illinois Department of Revenue", "description": "The New York State Department of Taxation and Finance" }, {...}, {...} ] }
Delete a tax authority [US and CA Edition only]
Delete a tax authority.
DELETE /settings/taxauthorities/{tax_authority_id}
Request Example
$ curl https://books.zoho.com/api/v3/settings/taxauthorities/{tax_authority_id}?organization_id=10234695 -H "Authorization: Zoho-authtoken ba4604e8e433g9c892e360d53463oec5" -H "Content-Type: application/json;charset=UTF-8"
Response Example
HTTP/1.1 200 OK Content-Type:application/json;charset=UTF-8 { "code": 0, "message": "Tax authority has been deleted." }
Create a tax exemption [US Edition only]
Create a tax exemption.
POST /settings/taxexemptions
Request Example
$ curl https://books.zoho.com/api/v3/settings/taxexemptions?organization_id=10234695 -H "Authorization: Zoho-authtoken ba4604e8e433g9c892e360d53463oec5" -H "Content-Type: application/json;charset=UTF-8" -d '{ "tax_exemption_code": "RESELLER", "description": "Tax exempted because the contact is a reseller.", "type": "customer" }
Response Example
HTTP/1.1 200 OK Content-Type:application/json;charset=UTF-8 { "code": 0, "message": "Tax Exemption has been added.", "tax_exemption": { "tax_exemption_id": "460000000076002", "tax_exemption_code": "RESELLER", "description": "Tax exempted because the contact is a reseller.", "type": "customer" } }
ARGUMENTS
|
tax_exemption_code
India Edition only
Required
Code of the Tax Exemption
description
Optional
Description
type
Required
Type of the tax exemption, can be
customer or item. |
Update a tax exemption [US Edition only]
Update the details of a tax exemption.
PUT /settings/taxexemptions/{tax_exemption_id}
Request Example
$ curl https://books.zoho.com/api/v3/settings/taxexemptions/{tax_exemption_id}?organization_id=10234695 -H "Authorization: Zoho-authtoken ba4604e8e433g9c892e360d53463oec5" -H "Content-Type: application/json;charset=UTF-8" -d '{ "tax_exemption_code": "RESELLER", "description": "Tax exempted because the contact is a reseller.", "type": "customer" }
Response Example
HTTP/1.1 200 OK Content-Type:application/json;charset=UTF-8 { "code": 0, "message": "Tax Exemption has been updated.", "tax_exemption": { "tax_exemption_id": "460000000076002", "tax_exemption_code": "RESELLER", "description": "Tax exempted because the contact is a reseller.", "type": "customer" } }
ARGUMENTS
|
tax_exemption_code
India Edition only
Required
Code of the Tax Exemption
description
Optional
Description
type
Required
Type of the tax exemption, can be
customer or item. |
Get a tax exemption [US Edition only]
Get the details of a tax exemption.
GET /settings/taxexemption/{tax_exemption_id}
Request Example
$ curl https://books.zoho.com/api/v3/settings/taxexemption/{tax_exemption_id}?organization_id=10234695 -H "Authorization: Zoho-authtoken ba4604e8e433g9c892e360d53463oec5" -H "Content-Type: application/json;charset=UTF-8"
Response Example
HTTP/1.1 200 OK Content-Type:application/json;charset=UTF-8 { "code": 0, "message": "success", "tax_exemption": { "tax_exemption_id": "460000000076002", "tax_exemption_code": "RESELLER", "description": "Tax exempted because the contact is a reseller.", "type": "customer" } }
List tax exemptions [US Edition only]
List of tax exemptions.
GET /settings/taxexemptions
Request Example
$ curl https://books.zoho.com/api/v3/settings/taxexemptions?organization_id=10234695 -H "Authorization: Zoho-authtoken ba4604e8e433g9c892e360d53463oec5" -H "Content-Type: application/json;charset=UTF-8"
Response Example
HTTP/1.1 200 OK Content-Type:application/json;charset=UTF-8 { "code": 0, "message": "success", "tax_exemptions": [ { "tax_exemption_id": "460000000076002", "tax_exemption_code": "RESELLER", "description": "Tax exempted because the contact is a reseller.", "type": "customer" }, {...}, {...} ] }
Delete a tax exemption [US Edition only]
Delete a tax exemption.
DELETE /settings/taxexemptions/{tax_exemption_id}
Request Example
$ curl https://books.zoho.com/api/v3/settings/taxexemptions/{tax_exemption_id}?organization_id=10234695 -H "Authorization: Zoho-authtoken ba4604e8e433g9c892e360d53463oec5" -H "Content-Type: application/json;charset=UTF-8"
Response Example
HTTP/1.1 200 OK Content-Type:application/json;charset=UTF-8 { "code": 0, "message": "Tax exemption has been deleted successfully." }
Opening-Balance
While migrating from existing accounting software to Zoho Books, you need to ensure that the transition is flawless, that all prevailing data such as journal entries, records, expense and income statements etc, has been recorded and continuity in financial statements is maintained. To ensure this, an opening balance needs to be calculated.
Example
{ "opening_balance": { "opening_balance_id": "460000000050041", "date": "2013-10-01", "price_precision": 2, "accounts": [ { "acount_split_id": "460000000050045", "account_id": "460000000000358", "account_name": "Undeposited Funds", "debit_or_credit": "debit", "exchange_rate": 1, "currency_id": "460000000000097", "currency_code": "USD", "bcy_amount": 2000, "amount": 2000 } ], "total": 10000 } }
Attribute
|
opening_balance
object
opening_balance_id
string
ID of opening balance.
date
string
Date on which the opening balance needs to be recorded. [yyyy-MM-dd]
price_precision
integer
Price Precision of the Values
accounts
list
acount_split_id
string
ID of split account that you want to update.
account_id
string
ID of account for which you need to record opening balance.
account_name
string
debit_or_credit
string
Debit or Credit for which the amount needs to be recorded. Allowed Values:
debit and credit.
exchange_rate
double
Exchange rate for the foreign currencies if involved.
currency_id
string
ID of account currency.
currency_code
string
bcy_amount
double
Amount in Base Currency of the Organisation
amount
double
total
integer
Total Amount from the Opening Balance
|
Create opening balance
Creates opening balance with the given information.
POST /settings/openingbalances
Request Example
$ curl https://books.zoho.com/api/v3/settings/openingbalances?organization_id=10234695 -H "Authorization: Zoho-authtoken ba4604e8e433g9c892e360d53463oec5" -H "Content-Type: application/json;charset=UTF-8" -d '{ "date": "2013-10-01", "accounts": [ { "acount_split_id": "460000000050045", "account_id": "460000000000358", "debit_or_credit": "debit", "exchange_rate": 1, "currency_id": "460000000000097", "amount": 2000 } ] }
Response Example
HTTP/1.1 200 OK Content-Type:application/json;charset=UTF-8 { "code": 0, "message": "The opening balances are saved!", "opening_balance": { "opening_balance_id": "460000000050041", "date": "2013-10-01", "price_precision": 2, "accounts": [ { "acount_split_id": "460000000050045", "account_id": "460000000000358", "account_name": "Undeposited Funds", "debit_or_credit": "debit", "exchange_rate": 1, "currency_id": "460000000000097", "currency_code": "USD", "bcy_amount": 2000, "amount": 2000 } ], "total": 10000 } }
ARGUMENTS
|
date
Required
Date on which the opening balance needs to be recorded. [yyyy-MM-dd]
accounts
Optional
acount_split_id
Optional
ID of split account that you want to update.
account_id
Optional
ID of account for which you need to record opening balance.
debit_or_credit
Required
Debit or Credit for which the amount needs to be recorded. Allowed Values:
debit and credit.
exchange_rate
Optional
Exchange rate for the foreign currencies if involved.
currency_id
Optional
ID of account currency.
amount
Optional
|
Update opening balance
Updates the existing opening balance information
PUT /settings/openingbalances
Request Example
$ curl https://books.zoho.com/api/v3/settings/openingbalances?organization_id=10234695 -H "Authorization: Zoho-authtoken ba4604e8e433g9c892e360d53463oec5" -H "Content-Type: application/json;charset=UTF-8" -d '{ "date": "2013-10-01", "accounts": [ { "acount_split_id": "460000000050045", "account_id": "460000000000358", "account_name": "Undeposited Funds", "debit_or_credit": "debit", "exchange_rate": 1, "currency_id": "460000000000097", "currency_code": "USD", "bcy_amount": 2000, "amount": 2000 } ], "opening_balance_id": "460000000050041" }
Response Example
HTTP/1.1 200 OK Content-Type:application/json;charset=UTF-8 { "code": 0, "message": "The opening balances are saved!", "opening_balance": { "opening_balance_id": "460000000050041", "date": "2013-10-01", "price_precision": 2, "accounts": [ { "acount_split_id": "460000000050045", "account_id": "460000000000358", "account_name": "Undeposited Funds", "debit_or_credit": "debit", "exchange_rate": 1, "currency_id": "460000000000097", "currency_code": "USD", "bcy_amount": 2000, "amount": 2000 } ], "total": 10000 } }
ARGUMENTS
|
date
Optional
Date on which the opening balance needs to be recorded. [yyyy-MM-dd]
accounts
Optional
acount_split_id
Optional
ID of split account that you want to update.
account_id
Optional
ID of account for which you need to record opening balance.
account_name
Optional
debit_or_credit
Required
Debit or Credit for which the amount needs to be recorded. Allowed Values:
debit and credit.
exchange_rate
Optional
Exchange rate for the foreign currencies if involved.
currency_id
Optional
ID of account currency.
currency_code
Optional
bcy_amount
Optional
Amount in Base Currency of the Organisation
amount
Optional
opening_balance_id
Required
ID of opening balance.
|
Get opening balance
Get opening balance.
GET /settings/openingbalances
Request Example
$ curl https://books.zoho.com/api/v3/settings/openingbalances?organization_id=10234695 -H "Authorization: Zoho-authtoken ba4604e8e433g9c892e360d53463oec5" -H "Content-Type: application/json;charset=UTF-8"
Response Example
HTTP/1.1 200 OK Content-Type:application/json;charset=UTF-8 { "code": 0, "message": "success", "opening_balance": { "opening_balance_id": "460000000050041", "date": "2013-10-01", "price_precision": 2, "accounts": [ { "acount_split_id": "460000000050045", "account_id": "460000000000358", "account_name": "Undeposited Funds", "debit_or_credit": "debit", "exchange_rate": 1, "currency_id": "460000000000097", "currency_code": "USD", "bcy_amount": 2000, "amount": 2000 } ], "total": 10000 } }
Delete opening balance
Delete the entered opening balance
DELETE /settings/openingbalances
Request Example
$ curl https://books.zoho.com/api/v3/settings/openingbalances?organization_id=10234695 -H "Authorization: Zoho-authtoken ba4604e8e433g9c892e360d53463oec5" -H "Content-Type: application/json;charset=UTF-8"
Response Example
HTTP/1.1 200 OK Content-Type:application/json;charset=UTF-8 { "code": 0, "message": "The entered opening balance has been deleted." }