API Documentation
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

  1. A valid Zoho username and password.
  2. 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:

  1. Through a URL in your browser.
  2. 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/nb/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

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.

Manage Organizations

Now you’ll be able to find Organization IDs for each of your organizations.

Organization ID

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
2xxSuccess
4xxBad request sent to server
5xxServer 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.

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:

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.

  1. Download the sample environment file.
  2. Replace the values for domain_url, organization_id, authtoken .

    domain_url: books.zoho.com

    Organization.Organization_ID: organization ID

    User.Auth_Token: authtoken

  3. In the Postman app, click the settings icon (cog icon) on the top-right and go to
    Manage Environment
  4. Click the Import button and 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", "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.
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 -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, "currency_id": 460000000000097, "website": "www.bowmanfurniture.com", "custom_fields": [ { "value": "GBGD078", "index": 1 } ], "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", "is_primary_contact": true } ], "default_templates": { "invoice_template_id": 460000000052069, "invoice_template_name": "Custom Classic", "estimate_template_id": 460000000000179, "estimate_template_name": "Service - Professional", "creditnote_template_id": 460000000000211, "creditnote_template_name": "Fixed Cost - Professional", "invoice_email_template_id": 460000000052071, "invoice_email_template_name": "Custom Invoice Notification", "estimate_email_template_id": 460000000052073, "estimate_email_template_name": "Custom Estimate Notification", "creditnote_email_template_id": 460000000052075, "creditnote_email_template_name": "Custom Credit Note Notification" }, "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", "email": "willsmith@bowmanfurniture.com", "is_primary_contact": true, "invoice_template_id": 460000000052069, "estimate_template_id": 460000000000179, "creditnote_template_id": 460000000000211, "invoice_email_template_id": 460000000052071, "estimate_email_template_id": 460000000052073, "creditnote_email_template_id": 460000000052075 }

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": [ { "value": "GBGD078", "index": 1, "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", "is_primary_contact": true } ], "default_templates": { "invoice_template_id": 460000000052069, "invoice_template_name": "Custom Classic", "estimate_template_id": 460000000000179, "estimate_template_name": "Service - Professional", "creditnote_template_id": 460000000000211, "creditnote_template_name": "Fixed Cost - Professional", "invoice_email_template_id": 460000000052071, "invoice_email_template_name": "Custom Invoice Notification", "estimate_email_template_id": 460000000052073, "estimate_email_template_name": "Custom Estimate Notification", "creditnote_email_template_id": 460000000052075, "creditnote_email_template_name": "Custom Credit Note Notification" }, "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.
currency_id
Optional
Currency ID of the customer's currency.
website
Optional
Website of the contact.
custom_fields
Optional
Custom fields of the contact.
value
Optional
Value of the custom field.
index
Optional
Index of the custom field. It can hold any value from 1 to 10.
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.
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.
invoice_template_name
Optional
estimate_template_id
Optional
Default estimate template id used for this contact while creating estimate.
estimate_template_name
Optional
creditnote_template_id
Optional
Default credit note template id used for this contact while creating credit note.
creditnote_template_name
Optional
invoice_email_template_id
Optional
Default invoice email template id used for this contact while sending invoices.
invoice_email_template_name
Optional
estimate_email_template_id
Optional
Default estimate email template id used for this contact while sending estimates.
estimate_email_template_name
Optional
creditnote_email_template_id
Optional
Default credit note email template id used for this contact while sending credit notes.
creditnote_email_template_name
Optional
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]
email
Optional
Email address of the contact person.
is_primary_contact
Optional
To mark contact person as primary for contact. Allowed value is true only.
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.
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.
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.

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} -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, "currency_id": 460000000000097, "website": "www.bowmanfurniture.com", "custom_fields": [ { "value": "GBGD078", "index": 1, "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", "is_primary_contact": true } ], "default_templates": { "invoice_template_id": 460000000052069, "invoice_template_name": "Custom Classic", "estimate_template_id": 460000000000179, "estimate_template_name": "Service - Professional", "creditnote_template_id": 460000000000211, "creditnote_template_name": "Fixed Cost - Professional", "invoice_email_template_id": 460000000052071, "invoice_email_template_name": "Custom Invoice Notification", "estimate_email_template_id": 460000000052073, "estimate_email_template_name": "Custom Estimate Notification", "creditnote_email_template_id": 460000000052075, "creditnote_email_template_name": "Custom Credit Note Notification" }, "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", "email": "willsmith@bowmanfurniture.com", "is_primary_contact": true, "invoice_template_id": 460000000052069, "estimate_template_id": 460000000000179, "creditnote_template_id": 460000000000211, "invoice_email_template_id": 460000000052071, "estimate_email_template_id": 460000000052073, "creditnote_email_template_id": 460000000052075 }

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": [ { "value": "GBGD078", "index": 1, "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", "is_primary_contact": true } ], "default_templates": { "invoice_template_id": 460000000052069, "invoice_template_name": "Custom Classic", "estimate_template_id": 460000000000179, "estimate_template_name": "Service - Professional", "creditnote_template_id": 460000000000211, "creditnote_template_name": "Fixed Cost - Professional", "invoice_email_template_id": 460000000052071, "invoice_email_template_name": "Custom Invoice Notification", "estimate_email_template_id": 460000000052073, "estimate_email_template_name": "Custom Estimate Notification", "creditnote_email_template_id": 460000000052075, "creditnote_email_template_name": "Custom Credit Note Notification" }, "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.
currency_id
Optional
Currency ID of the customer's currency.
website
Optional
Website of the contact.
custom_fields
Optional
Custom fields of the contact.
value
Optional
Value of the custom field.
index
Optional
Index of the custom field. It can hold any value from 1 to 10.
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.
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.
invoice_template_name
Optional
estimate_template_id
Optional
Default estimate template id used for this contact while creating estimate.
estimate_template_name
Optional
creditnote_template_id
Optional
Default credit note template id used for this contact while creating credit note.
creditnote_template_name
Optional
invoice_email_template_id
Optional
Default invoice email template id used for this contact while sending invoices.
invoice_email_template_name
Optional
estimate_email_template_id
Optional
Default estimate email template id used for this contact while sending estimates.
estimate_email_template_name
Optional
creditnote_email_template_id
Optional
Default credit note email template id used for this contact while sending credit notes.
creditnote_email_template_name
Optional
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]
email
Optional
Email address of the contact person.
is_primary_contact
Optional
To mark contact person as primary for contact. Allowed value is true only.
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.
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.
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.

List contacts

List all contacts with pagination.

GET /contacts

Request Example

  
$ curl https://books.zoho.com/api/v3/contacts -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} -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": [ { "value": "GBGD078", "index": 1, "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", "is_primary_contact": true } ], "default_templates": { "invoice_template_id": 460000000052069, "invoice_template_name": "Custom Classic", "estimate_template_id": 460000000000179, "estimate_template_name": "Service - Professional", "creditnote_template_id": 460000000000211, "creditnote_template_name": "Fixed Cost - Professional", "invoice_email_template_id": 460000000052071, "invoice_email_template_name": "Custom Invoice Notification", "estimate_email_template_id": 460000000052073, "estimate_email_template_name": "Custom Estimate Notification", "creditnote_email_template_id": 460000000052075, "creditnote_email_template_name": "Custom Credit Note Notification" }, "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} -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 -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 -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 -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 -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 -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 -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 -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 -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 -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 -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 -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 -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 -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} -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 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

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 -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_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 } ], "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} -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} -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 -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

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 Valuesdraft, sent, invoiced , accepted, declined and expired
estimate_number
string
Search estimates by estimate number.Variantsestimate_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 -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.Variantsestimate_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
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} -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.Variantsestimate_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
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} -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 -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.Variantsestimate_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.Variantsitem_description_startswith and item_description_contains
custom_field
Optional
Search estimates by custom field.Variantscustom_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 Valuesdraft, 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} -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 -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 -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 -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 -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 -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 -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 -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 -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 -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 -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 -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} -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 -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 -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} -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} -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

list
salesorder_id
string
ID of the Sales Order
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.
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
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
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 -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.
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.
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.
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} -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.
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.
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.
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 -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} -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} -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 -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 -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 -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,&nbsp;<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: &nbsp;<br><br> ----------------------------------------------------------------------------------------<br> <h2>Sales Order&nbsp;# :&nbsp;SO-00001</h2><br> ----------------------------------------------------------------------------------------<br> <b>&nbsp;Order Date &nbsp; &nbsp;&nbsp;&nbsp;: &nbsp;28 Jul 2014</b><br><b>&nbsp;Amount &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; : &nbsp;&nbsp;$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.
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 -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,&nbsp;<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: &nbsp;<br><br> ----------------------------------------------------------------------------------------<br> <h2>Sales Order&nbsp;# :&nbsp;SO-00001</h2><br> ----------------------------------------------------------------------------------------<br> <b>&nbsp;Order Date &nbsp; &nbsp;&nbsp;&nbsp;: &nbsp;28 Jul 2014</b><br><b>&nbsp;Amount &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; : &nbsp;&nbsp;$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 -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 -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 -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 -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 -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} -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 -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 -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 -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 -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 -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 -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} -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} -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
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 -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
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 -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
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 -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 -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 -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 -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 -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 -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 -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 -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

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 -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 -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,&nbsp;<br><br>You might have missed the payment date and the invoice is now overdue by&nbsp;1&nbsp;days.<br><br>----------------------------------------------------------------------------------------<br><h2>Invoice# : INV-000004 </h2>Dated : 23 Dec 2016<br>----------------------------------------------------------------------------------------<br><b>&nbsp;Due Date &nbsp; &nbsp; &nbsp; &nbsp; : &nbsp;&nbsp;23 Dec 2016</b><br><b>&nbsp;Amount &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; : &nbsp;&nbsp;$139.65</b><br>----------------------------------------------------------------------------------------<br><br><span>Not to worry at all !&nbsp;</span>View your invoice and take the easy way out by making an&nbsp;<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 -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 -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,&nbsp;<br><br>You might have missed the payment date and the invoice is now overdue by&nbsp;1&nbsp;days.<br><br>----------------------------------------------------------------------------------------<br><h2>Invoice# : INV-000004 </h2>Dated : 23 Dec 2016<br>----------------------------------------------------------------------------------------<br><b>&nbsp;Due Date &nbsp; &nbsp; &nbsp; &nbsp; : &nbsp;&nbsp;23 Dec 2016</b><br><b>&nbsp;Amount &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; : &nbsp;&nbsp;$139.65</b><br>----------------------------------------------------------------------------------------<br><br><span>Not to worry at all !&nbsp;</span>View your invoice and take the easy way out by making an&nbsp;<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 -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 -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 -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 -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 -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 -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 -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 -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 -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} -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 -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 -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 -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} -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} -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 -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 -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 -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 -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 -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 -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 -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 -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} -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 -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.
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
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
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} -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.
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 -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 -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 -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 -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 -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 -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 -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.
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
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 -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 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", "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" }, "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.
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.
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

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} -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.
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.
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} -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 -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 -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 -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 -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} -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 -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 -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 -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 -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 -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} -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 -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 -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

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 -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 -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 -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 -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 -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 -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 -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 -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 -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 -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.
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 -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.
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} -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.
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} -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 -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 PaymentMode.Others
sort_column
Optional
search_text
Optional
Search payments by reference number or customer name or payment description. Max-length [100]
customer_id
Optional
Customer ID of the customer involved in the payment.

Delete a payment

Delete an existing payment.

DELETE /customerpayments/{payment_id}

Request Example

  
$ curl https://books.zoho.com/api/v3/customerpayments/{payment_id} -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 -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 -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 -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 -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 -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 -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": " ", "claimant_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
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
claimant_id
UK Edition only
Optional
vehicle_type
UK Edition only
Optional
can_reclaim_vat_on_mileage
UK Edition only
Optional
fuel_type
UK Edition only
Optional
engine_capacity_range
UK Edition only
Optional
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} -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": " ", "claimant_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
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
claimant_id
UK Edition only
Optional
vehicle_type
UK Edition only
Optional
can_reclaim_vat_on_mileage
UK Edition only
Optional
fuel_type
UK Edition only
Optional
engine_capacity_range
UK Edition only
Optional
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 -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_startsw