API Documentation
Introduction

Introduction

API Root Endpoint

https://invoice.zoho.com/api/v3

The Zoho Invoice API allows you to perform all the operations that you do with our web client.

Zoho Invoice 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 which 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.

The Organization ID and the Authtoken has to be sent as Query Params in the API.The JSON String has to be sent as form-data.

Getting Started

Example

    
$ curl https://invoice.zoho.com/api/v3/organizations?authtoken=ba4604e8e433g9c892e360d53463oec5&organization_id=10234695

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 Invoice 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=ZohoInvoice/invoiceapi

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=ZohoInvoice/invoiceapi&EMAIL_ID=[ZohoID/EmailID]&PASSWORD=[Password]

Below are the mandatory case sensitive fields to be passed in the URL.

Parameter Description
SCOPE ZohoInvoice/invoiceapi
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://invoice.zoho.com/api/v3/organizations?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 Invoice, 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 Invoice 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 Invoice 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://invoice.zoho.com/api/v3/contacts?authtoken=ba4604e8e433g9c892e360d53463oec5&organization_id=10234695
To get the details of a contact referred to by a specified contact_id
$ curl https://invoice.zoho.com/api/v3/contacts/903000000000099?authtoken=ba4604e8e433g9c892e360d53463oec5&organization_id=10234695

Zoho Invoice 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 invoice API follows the below format.
{ "code" : 0, "message" : "success", "invoice" : { "invoice_id" : "..." } }

Request Example

$ curl https://invoice.zoho.com/api/v3/invoices/7000000079426?authtoken=ba4604e8e433g9c892e360d53463oec5&organization_id=10234695 -H 'Accept: application/pdf'
OR
$ curl https://invoice.zoho.com/api/v3/invoices/7000000079426?accept=pdf \ '&authtoken=ba4604e8e433g9c892e360d53463oec5' \ '&organization_id=10234695'

Responses will be in the JSON format.

Node Name Description
code Zoho Invoice 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://invoice.zoho.com/api/v3/invoices/700000007942?authtoken=ba4604e8e433g9c892e360d53463oec5&organization_id=10234695

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 Invoice 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 Invoice server encountered an error which prevents it from fulfilling the request. Although this rarely happens, we recommend you to contact us at support@zohoinvoice.com if you receive this error.

Pagination

Example

$ curl https://invoice.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 Invoice 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: invoice.zoho.com

    organization_id: organization ID

    authtoken: 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

Items

A product is the item offered for sale. It can be a commodity. Based on the type of your business, you can offer one or more goods.

Example

{ "item_id": 903000000045027, "name": "Hard Drive", "description": "500GB", "unit": "100GB", "status": "active", "product_type": "goods", "sku": "s12345" }

Attribute

item_id
string
Unique ID generated by the server for an item.
name
string
Name of the item. Maximum length of the name [100]
description
string
Description for the item. Maximum characters to be used for describing the item [2000]
unit
string
Quantifying the amount of an item, using a measurement unit.
status
string
Status of the item. It can be active or inactive. It tells whether the Item is available for transactions.
product_type
string
Specify the type of an item. It can be either goods or service
sku
string
SKU or the Stock Keeping Unit value of an item, should be unique throughout the product

Create an Item

Create a new item.

POST /items

Request Example

  
$ curl https://invoice.zoho.com/api/v3/items?authtoken=ba4604e8e433g9c892e360d53463oec5&organization_id=10234695 -H "Authorization: Zoho-authtoken ba4604e8e433g9c892e360d53463oec5" -H "Content-Type: application/json;charset=UTF-8" -d JSONString='{ "name": "Hard Drive", "rate": 120, "description": "500GB", "tax_id": 982000000037049, "sku": "s12345", "product_type": "goods", "item_tax_preferences": [ { "tax_id": 982000000037049, "tax_specification": "intra" } ] }'

Response Example

  
HTTP/1.1 201 Created Content-Type:application/json;charset=UTF-8 { "code": 0, "message": "The item has been added.", "item": { "item_id": 903000000045027, "name": "Hard Drive", "status": "active", "description": "500GB", "rate": 120, "unit": "100GB", "tax_id": 982000000037049, "tax_name": "Sales Tax", "tax_percentage": "70%", "tax_type": "Service Tax", "sku": "s12345", "product_type": "goods", "item_tax_preferences": [ { "tax_id": 982000000037049, "tax_specification": "intra" } ], "warehouses": [ { "warehouse_id": "", "warehouse_name": "", "status": "active", "is_primary": false, "warehouse_stock_on_hand": "", "warehouse_available_stock": "", "warehouse_actual_available_stock": "" } ] } }

ARGUMENTS

name
Required
Name of the item. Maximum length of the name [100]
rate
Required
Per unit price of an item.
description
Optional
Description for the item. Maximum characters to be used for describing the item [2000]
tax_id
Optional
ID of the tax to be associated to the item.
sku
Optional
SKU or the Stock Keeping Unit value of an item, should be unique throughout the product
product_type
Optional
Specify the type of an item. It can be either goods or service
is_taxable
(India, US and CA Edition only)
Optional
Boolean to track the taxability of the item.
tax_exemption_id
(India, US and CA Edition only)
Optional
ID of the tax exemption applied. Mandatory, if is_taxable is false.
hsn_or_sac
India Edition Only
Optional
HSN Code
item_tax_preferences
Optional
tax_id
Optional
ID of the tax to be associated to the item.
tax_specification
India Edition only
Optional
Set whether the tax type is intra/interstate

Update an item

Update the details of an existing item.

PUT /items/{item_id}

Request Example

  
$ curl https://invoice.zoho.com/api/v3/items/{item_id}?authtoken=ba4604e8e433g9c892e360d53463oec5&organization_id=10234695 -H "Authorization: Zoho-authtoken ba4604e8e433g9c892e360d53463oec5" -H "Content-Type: application/json;charset=UTF-8" -d JSONString='{ "name": "Hard Drive", "rate": 120, "description": "500GB", "tax_id": 982000000037049, "sku": "s12345", "product_type": "goods", "item_tax_preferences": [ { "tax_id": 982000000037049, "tax_specification": "intra" } ] }'

Response Example

  
HTTP/1.1 200 OK Content-Type:application/json;charset=UTF-8 { "code": 0, "message": "Item details have been saved.", "item": { "item_id": 903000000045027, "name": "Hard Drive", "status": "active", "description": "500GB", "rate": 120, "unit": "100GB", "tax_id": 982000000037049, "tax_name": "Sales Tax", "tax_percentage": "70%", "tax_type": "Service Tax", "sku": "s12345", "product_type": "goods", "item_tax_preferences": [ { "tax_id": 982000000037049, "tax_specification": "intra" } ], "warehouses": [ { "warehouse_id": "", "warehouse_name": "", "status": "active", "is_primary": false, "warehouse_stock_on_hand": "", "warehouse_available_stock": "", "warehouse_actual_available_stock": "" } ] } }

ARGUMENTS

name
Required
Name of the item. Maximum length of the name [100]
rate
Required
Per unit price of an item.
description
Optional
Description for the item. Maximum characters to be used for describing the item [2000]
tax_id
Optional
ID of the tax to be associated to the item.
sku
Optional
SKU or the Stock Keeping Unit value of an item, should be unique throughout the product
product_type
Optional
Specify the type of an item. It can be either goods or service
is_taxable
(India, US and CA Edition only)
Optional
Boolean to track the taxability of the item.
tax_exemption_id
(India, US and CA Edition only)
Optional
ID of the tax exemption applied. Mandatory, if is_taxable is false.
hsn_or_sac
India Edition Only
Optional
HSN Code
item_tax_preferences
Optional
tax_id
Optional
ID of the tax to be associated to the item.
tax_specification
India Edition only
Optional
Set whether the tax type is intra/interstate

Retrieve an item

Fetch details of an existing item.

GET /items/{item_id}

Request Example

  
$ curl https://invoice.zoho.com/api/v3/items/{item_id}?authtoken=ba4604e8e433g9c892e360d53463oec5&organization_id=10234695 -H "Authorization: Zoho-authtoken ba4604e8e433g9c892e360d53463oec5" -H "Content-Type: application/json;charset=UTF-8"

Response Example

  
HTTP/1.1 200 OK Content-Type:application/json;charset=UTF-8 { "code": 0, "message": "success", "item": { "item_id": 903000000045027, "name": "Hard Drive", "status": "active", "description": "500GB", "rate": 120, "unit": "100GB", "tax_id": 982000000037049, "tax_name": "Sales Tax", "tax_percentage": "70%", "tax_type": "Service Tax", "sku": "s12345", "product_type": "goods", "item_tax_preferences": [ { "tax_id": 982000000037049, "tax_specification": "intra" } ], "warehouses": [ { "warehouse_id": "", "warehouse_name": "", "status": "active", "is_primary": false, "warehouse_stock_on_hand": "", "warehouse_available_stock": "", "warehouse_actual_available_stock": "" } ] } }

List items

Get the list of all active items with pagination.

GET /items

Request Example

  
$ curl https://invoice.zoho.com/api/v3/items?authtoken=ba4604e8e433g9c892e360d53463oec5&organization_id=10234695 -H "Authorization: Zoho-authtoken ba4604e8e433g9c892e360d53463oec5" -H "Content-Type: application/json;charset=UTF-8"

Response Example

  
HTTP/1.1 200 OK Content-Type:application/json;charset=UTF-8 { "code": 0, "message": "success", "items": [ { "item_id": 903000000045027, "name": "Hard Drive", "status": "active", "description": "500GB", "rate": 120, "unit": "100GB", "tax_id": 982000000037049, "tax_name": "Sales Tax", "tax_percentage": "70%", "tax_type": "Service Tax", "sku": "s12345", "product_type": "goods" }, {...}, {...} ] }

Query Params

name
Optional
Search items by name. Maximum length [100]. Variants: name_startswith and name_contains
description
Optional
Search items by description. Maximum length [100]. Variants: description_startswith and description_contains
rate
Optional
Search items by rate. Variants: rate_less_than, rate_less_equals, rate_greater_than and rate_greater_equals
tax_id
Optional
Search items by tax id.
filter_by
Optional
Filter items by status. Allowed Values: Status.All, Status.Active and Status.Inactive
search_text
Optional
Search items by name or description. Maximum length [100]
sort_column
Optional
Sort items. Allowed Values: name, rate and tax_name

Delete an item

Delete an existing item. Items that are part of a transaction cannot be deleted.

DELETE /items/{item_id}

Request Example

  
$ curl https://invoice.zoho.com/api/v3/items/{item_id}?authtoken=ba4604e8e433g9c892e360d53463oec5&organization_id=10234695 -H "Authorization: Zoho-authtoken ba4604e8e433g9c892e360d53463oec5" -H "Content-Type: application/json;charset=UTF-8"

Response Example

  
HTTP/1.1 200 OK Content-Type:application/json;charset=UTF-8 { "code": 0, "message": "The item has been deleted." }

Mark as active

Mark an inactive item as active.

POST /items/{item_id}/active

Request Example

  
$ curl https://invoice.zoho.com/api/v3/items/{item_id}/active?authtoken=ba4604e8e433g9c892e360d53463oec5&organization_id=10234695 -H "Authorization: Zoho-authtoken ba4604e8e433g9c892e360d53463oec5" -H "Content-Type: application/json;charset=UTF-8"

Response Example

  
HTTP/1.1 200 OK Content-Type:application/json;charset=UTF-8 { "code": 0, "message": "The item has been marked Active." }

Mark as inactive

Mark an active item as inactive.

POST /items/{item_id}/inactive

Request Example

  
$ curl https://invoice.zoho.com/api/v3/items/{item_id}/inactive?authtoken=ba4604e8e433g9c892e360d53463oec5&organization_id=10234695 -H "Authorization: Zoho-authtoken ba4604e8e433g9c892e360d53463oec5" -H "Content-Type: application/json;charset=UTF-8"

Response Example

  
HTTP/1.1 200 OK Content-Type:application/json;charset=UTF-8 { "code": 0, "message": "The item has been marked Inactive." }

Contacts

A contact is either a customer or vendor. A contact can be an individual or a business in general.

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", "language_code": "en", "billing_address": { "street": "Harrington Bay Street", "street2": "Suite 310", "state_code": "CA", "city": "Pleasanton", "state": "CA", "zip": 94588, "country": "U.S.A" }, "shipping_address": { "street": "Harrington Bay Street", "street2": "Suite 310", "state_code": "CA", "city": "Pleasanton", "state": "CA", "zip": 94588, "country": "U.S.A" }, "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
Name of the contact. This can be the name of an organisation or the name of an individual. Maximum length [200]
company_name
string
Name of the conact's company. Maximum length [200]
first_name
string
First name of the contact. Maximum length [100]
last_name
string
Last name of the contact. Maximum length [100]
email
string
The Email ID of the contact person.
phone
string
Phone number of the contact person.
facebook
string
Facebook profile account of the contact. Maximum length [100]
twitter
string
Twitter account of the contact. Maximum length [100]
language_code
string
language of a contact. allowed values de,en,es,fr,it,ja,nl,pt,sv,zh
billing_address
object
Billing address of the contact.
street
string
Street of the customer’s billing address.
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.
shipping_address
object
Customer's shipping address to which the goods must be delivered.
street
string
Street of the customer’s billing address.
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.
contact_persons
list
Person/Individual who represents a company
salutation
string
Salutation for the contact
first_name
string
First name of the contact. Maximum length [100]
last_name
string
Last name of the contact. Maximum length [100]
email
string
The Email ID of the contact person.
phone
string
Phone number of the contact person.
mobile
string
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://invoice.zoho.com/api/v3/contacts?authtoken=ba4604e8e433g9c892e360d53463oec5&organization_id=10234695 -H "Authorization: Zoho-authtoken ba4604e8e433g9c892e360d53463oec5" -H "Content-Type: application/json;charset=UTF-8" -d JSONString='{ "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": { "street": "Harrington Bay Street", "street2": "Suite 310", "state_code": "CA", "city": "Pleasanton", "state": "CA", "zip": 94588, "country": "U.S.A" }, "shipping_address": { "street": "Harrington Bay Street", "street2": "Suite 310", "state_code": "CA", "city": "Pleasanton", "state": "CA", "zip": 94588, "country": "U.S.A" }, "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" }, "language_code": "en", "notes": "Payment option : Through check", "place_of_contact": "TN", "gst_no": "22AAAAA0000A1Z5", "gst_treatment": "business_gst", "tax_exemption_id": 11149000000061054, "tax_authority_id": 11149000000061052, "tax_id": 11149000000061058, "is_taxable": true, "facebook": "zoho", "twitter": "zoho" }'

Response Example

  
HTTP/1.1 201 Created Content-Type:application/json;charset=UTF-8 { "code": 0, "message": "The contact has been created", "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": "$", "language_code": "en", "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": { "street": "Harrington Bay Street", "street2": "Suite 310", "state_code": "CA", "city": "Pleasanton", "state": "CA", "zip": 94588, "country": "U.S.A" }, "shipping_address": { "street": "Harrington Bay Street", "street2": "Suite 310", "state_code": "CA", "city": "Pleasanton", "state": "CA", "zip": 94588, "country": "U.S.A" }, "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-10-07T12:06:10+0530", "last_modified_time": "2013-11-08T18:24:51+0530" } }

ARGUMENTS

contact_name
Required
Name of the contact. This can be the name of an organisation or the name of an individual. Maximum length [200]
company_name
Optional
Name of the conact's company. Maximum 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 or Additional of the contact which we can create to add more information.
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.
street
Optional
Street of the customer’s billing address.
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.
shipping_address
Optional
Customer's shipping address to which the goods must be delivered.
street
Optional
Street of the customer’s billing address.
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.
contact_persons
Optional
Person/Individual who represents a company
salutation
Optional
Salutation for the contact
first_name
Optional
First name of the contact. Maximum length [100]
last_name
Optional
Last name of the contact. Maximum length [100]
email
Optional
The Email ID of the contact person.
phone
Optional
Phone number of the contact person.
mobile
Optional
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
ID of the Invoice template used
invoice_template_name
Optional
Name of the invoice template used
estimate_template_id
Optional
ID of the estimate template used
estimate_template_name
Optional
Name of the estimate template used
creditnote_template_id
Optional
ID of teh credit note template used
creditnote_template_name
Optional
Name of the credit note template used
invoice_email_template_id
Optional
ID of the invoice email tempalte used
invoice_email_template_name
Optional
Name of the Invoice email template used
estimate_email_template_id
Optional
ID of the estimate email template used
estimate_email_template_name
Optional
Name of the estimate email template used
creditnote_email_template_id
Optional
ID of the credit note email template
creditnote_email_template_name
Optional
Name of the credit note email template
language_code
Optional
language of a contact. allowed values de,en,es,fr,it,ja,nl,pt,sv,zh
notes
Optional
Commennts about the payment made by the contact.
vat_reg_no
UK Edition $ 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 $ 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.
tax_exemption_code
US, Canada, Australia and India editions only
Optional
Enter tax exemption code
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
Inida, US and CA edition only
Optional
ID of the tax exemption.
tax_authority_id
US and CA 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, US and CA 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
India, US and CA edition only
Optional
Boolean to track the taxability of the customer.
facebook
Optional
Facebook profile account of the contact. Maximum length [100]
twitter
Optional
Twitter account of the contact. Maximum length [100]

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://invoice.zoho.com/api/v3/contacts/{contact_id}?authtoken=ba4604e8e433g9c892e360d53463oec5&organization_id=10234695 -H "Authorization: Zoho-authtoken ba4604e8e433g9c892e360d53463oec5" -H "Content-Type: application/json;charset=UTF-8" -d JSONString='{ "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": { "street": "Harrington Bay Street", "street2": "Suite 310", "state_code": "CA", "city": "Pleasanton", "state": "CA", "zip": 94588, "country": "U.S.A" }, "shipping_address": { "street": "Harrington Bay Street", "street2": "Suite 310", "state_code": "CA", "city": "Pleasanton", "state": "CA", "zip": 94588, "country": "U.S.A" }, "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" }, "language_code": "en", "notes": "Payment option : Through check", "place_of_contact": "TN", "gst_no": "22AAAAA0000A1Z5", "gst_treatment": "business_gst", "tax_exemption_id": 11149000000061054, "tax_authority_id": 11149000000061052, "tax_id": 11149000000061058, "is_taxable": true, "facebook": "zoho", "twitter": "zoho" }'

Response Example

  
HTTP/1.1 200 OK Content-Type:application/json;charset=UTF-8 { "code": 0, "message": "Contact has been updated successfully", "contact": { "contact_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": "$", "language_code": "en", "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": { "street": "Harrington Bay Street", "street2": "Suite 310", "state_code": "CA", "city": "Pleasanton", "state": "CA", "zip": 94588, "country": "U.S.A" }, "shipping_address": { "street": "Harrington Bay Street", "street2": "Suite 310", "state_code": "CA", "city": "Pleasanton", "state": "CA", "zip": 94588, "country": "U.S.A" }, "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-10-07T12:06:10+0530", "last_modified_time": "2013-11-08T18:24:51+0530" } }

ARGUMENTS

contact_name
Required
Name of the contact. This can be the name of an organisation or the name of an individual. Maximum length [200]
company_name
Optional
Name of the conact's company. Maximum 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 or Additional of the contact which we can create to add more information.
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.
street
Optional
Street of the customer’s billing address.
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.
shipping_address
Optional
Customer's shipping address to which the goods must be delivered.
street
Optional
Street of the customer’s billing address.
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.
contact_persons
Optional
Person/Individual who represents a company
salutation
Optional
Salutation for the contact
first_name
Optional
First name of the contact. Maximum length [100]
last_name
Optional
Last name of the contact. Maximum length [100]
email
Optional
The Email ID of the contact person.
phone
Optional
Phone number of the contact person.
mobile
Optional
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
ID of the Invoice template used
invoice_template_name
Optional
Name of the invoice template used
estimate_template_id
Optional
ID of the estimate template used
estimate_template_name
Optional
Name of the estimate template used
creditnote_template_id
Optional
ID of teh credit note template used
creditnote_template_name
Optional
Name of the credit note template used
invoice_email_template_id
Optional
ID of the invoice email tempalte used
invoice_email_template_name
Optional
Name of the Invoice email template used
estimate_email_template_id
Optional
ID of the estimate email template used
estimate_email_template_name
Optional
Name of the estimate email template used
creditnote_email_template_id
Optional
ID of the credit note email template
creditnote_email_template_name
Optional
Name of the credit note email template
language_code
Optional
language of a contact. allowed values de,en,es,fr,it,ja,nl,pt,sv,zh
notes
Optional
Commennts about the payment made by the contact.
vat_reg_no
UK Edition $ 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 $ 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.
tax_exemption_code
US, Canada, Australia and India editions only
Optional
Enter tax exemption code
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
Inida, US and CA edition only
Optional
ID of the tax exemption.
tax_authority_id
US and CA 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, US and CA 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
India, US and CA edition only
Optional
Boolean to track the taxability of the customer.
facebook
Optional
Facebook profile account of the contact. Maximum length [100]
twitter
Optional
Twitter account of the contact. Maximum length [100]

List contacts

List all contacts with pagination.

GET /contacts

Request Example

  
$ curl https://invoice.zoho.com/api/v3/contacts?authtoken=ba4604e8e433g9c892e360d53463oec5&organization_id=10234695 -H "Authorization: Zoho-authtoken ba4604e8e433g9c892e360d53463oec5" -H "Content-Type: application/json;charset=UTF-8"

Response Example

  
HTTP/1.1 200 OK Content-Type:application/json;charset=UTF-8 { "code": 0, "message": "success", "contacts": [ { "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-10-07T12:06:10+0530", "last_modified_time": "2013-11-08T18:24:51+0530" }, {...}, {...} ] }

Query Params

contact_name
Optional
Search contacts by contact name. Maximum length [100] Variants: contact_name_startswith and contact_name_contains. Maximum length [100]
company_name
Optional
Search contacts by company name. Maximum length [100] Variants: company_name_startswith and company_name_contains
first_name
Optional
Search contacts by first name of the contact person. Maximum length [100] Variants: first_name_startswith and first_name_contains
last_name
Optional
Search contacts by last name of the contact person. Maximum length [100] Variants: last_name_startswith and last_name_contains
address
Optional
Search contacts by any of the address fields. Maximum length [100] Variants: address_startswith and address_contains
email
Optional
Search contacts by email id of the contact person. Maximum length [100] Variants: address_startswith and address_contains
phone
Optional
Search contacts by phone number of the contact person. Maximum 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. Maximum 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 a contact

Get details of a contact.

GET /contacts/{contacts_id}

Request Example

  
$ curl https://invoice.zoho.com/api/v3/contacts/{contacts_id}?authtoken=ba4604e8e433g9c892e360d53463oec5&organization_id=10234695 -H "Authorization: Zoho-authtoken ba4604e8e433g9c892e360d53463oec5" -H "Content-Type: application/json;charset=UTF-8"

Response Example

  
HTTP/1.1 200 OK Content-Type:application/json;charset=UTF-8 { "code": 0, "message": "success", "contact": { "contact_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": { "street": "Harrington Bay Street", "street2": "Suite 310", "state_code": "CA", "city": "Pleasanton", "state": "CA", "zip": 94588, "country": "U.S.A" }, "shipping_address": { "street": "Harrington Bay Street", "street2": "Suite 310", "state_code": "CA", "city": "Pleasanton", "state": "CA", "zip": 94588, "country": "U.S.A" }, "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-10-07T12:06:10+0530", "last_modified_time": "2013-11-08T18:24:51+0530" } }

Delete a contact

Delete an existing contact.

DELETE /contacts/{contact_id}

Request Example

  
$ curl https://invoice.zoho.com/api/v3/contacts/{contact_id}?authtoken=ba4604e8e433g9c892e360d53463oec5&organization_id=10234695 -H "Authorization: Zoho-authtoken ba4604e8e433g9c892e360d53463oec5" -H "Content-Type: application/json;charset=UTF-8"

Response Example

  
HTTP/1.1 200 OK Content-Type:application/json;charset=UTF-8 { "code": 0, "message": "The contact has been deleted." }

Mark as active

Mark a contact as active.

POST /contact/{contact_id}/active

Request Example

  
$ curl https://invoice.zoho.com/api/v3/contact/{contact_id}/active?authtoken=ba4604e8e433g9c892e360d53463oec5&organization_id=10234695 -H "Authorization: Zoho-authtoken ba4604e8e433g9c892e360d53463oec5" -H "Content-Type: application/json;charset=UTF-8"

Response Example

  
HTTP/1.1 200 OK Content-Type:application/json;charset=UTF-8 { "code": 0, "message": "The contact has been marked as active." }

Mark as Inactive

Mark a contact as inactive.

POST /contacts/{contact_id}/inactive

Request Example

  
$ curl https://invoice.zoho.com/api/v3/contacts/{contact_id}/inactive?authtoken=ba4604e8e433g9c892e360d53463oec5&organization_id=10234695 -H "Authorization: Zoho-authtoken ba4604e8e433g9c892e360d53463oec5" -H "Content-Type: application/json;charset=UTF-8"

Response Example

  
HTTP/1.1 200 OK Content-Type:application/json;charset=UTF-8 { "code": 0, "message": "The contact has been marked as inactive." }

Enable portal access

Enable portal access for a contact

POST /contacts/{contact_id}/portal/enable

Request Example

  
$ curl https://invoice.zoho.com/api/v3/contacts/{contact_id}/portal/enable?authtoken=ba4604e8e433g9c892e360d53463oec5&organization_id=10234695 -H "Authorization: Zoho-authtoken ba4604e8e433g9c892e360d53463oec5" -H "Content-Type: application/json;charset=UTF-8" -d JSONString='{ "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
Person/Individual who represents a company
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://invoice.zoho.com/api/v3/contacts/{contact_id}/paymentreminder/enable?authtoken=ba4604e8e433g9c892e360d53463oec5&organization_id=10234695 -H "Authorization: Zoho-authtoken ba4604e8e433g9c892e360d53463oec5" -H "Content-Type: application/json;charset=UTF-8"

Response Example

  
HTTP/1.1 200 OK Content-Type:application/json;charset=UTF-8 { "code": 0, "message": "All reminders associated with this contact have been enabled." }

Disable payment reminders

Disable automated payment reminders for a contact.

POST /contacts/{contact_id}/paymentreminder/disable

Request Example

  
$ curl https://invoice.zoho.com/api/v3/contacts/{contact_id}/paymentreminder/disable?authtoken=ba4604e8e433g9c892e360d53463oec5&organization_id=10234695 -H "Authorization: Zoho-authtoken ba4604e8e433g9c892e360d53463oec5" -H "Content-Type: application/json;charset=UTF-8"

Response Example

  
HTTP/1.1 200 OK Content-Type:application/json;charset=UTF-8 { "code": 0, "message": "All reminders associated with this contact have been stopped." }

Email statement

Email statement to the contact. If JSONString is not inputted, mail will be sent with the default mail content.

POST /contacts/{contact_id}/statements/email

Request Example

  
$ curl https://invoice.zoho.com/api/v3/contacts/{contact_id}/statements/email?authtoken=ba4604e8e433g9c892e360d53463oec5&organization_id=10234695 -H "Authorization: Zoho-authtoken ba4604e8e433g9c892e360d53463oec5" -H "Content-Type: application/json;charset=UTF-8" -d JSONString='{ "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 addresses of the recipients.
cc_mail_ids
Optional
Array of email addresses of the recipients to be CC'd.
subject
Required
Subject of an email that has to be sent. Maximum length to be allowed [1000]
body
Required
Body/content of the email to be sent. Maximum 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 mail content of a contacts billing statement.

GET /contacts/{contact_id}/statements/email

Request Example

  
$ curl https://invoice.zoho.com/api/v3/contacts/{contact_id}/statements/email?authtoken=ba4604e8e433g9c892e360d53463oec5&organization_id=10234695 -H "Authorization: Zoho-authtoken ba4604e8e433g9c892e360d53463oec5" -H "Content-Type: application/json;charset=UTF-8"

Response Example

  
HTTP/1.1 200 OK Content-Type:application/json;charset=UTF-8 { "code": 0, "message": "success", "body": "Dear Customer, <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://invoice.zoho.com/api/v3/contacts/{contact_id}/email?authtoken=ba4604e8e433g9c892e360d53463oec5&organization_id=10234695 -H "Authorization: Zoho-authtoken ba4604e8e433g9c892e360d53463oec5" -H "Content-Type: application/json;charset=UTF-8" -d JSONString='{ "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 addresses of the recipients.
subject
Required
Subject of an email has to be sent. Maximum length [1000]
body
Required
Body/content of the email to be sent. Maximum 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://invoice.zoho.com/api/v3/contacts/{contact_id}/comments?authtoken=ba4604e8e433g9c892e360d53463oec5&organization_id=10234695 -H "Authorization: Zoho-authtoken ba4604e8e433g9c892e360d53463oec5" -H "Content-Type: application/json;charset=UTF-8"

Response Example

  
HTTP/1.1 200 OK Content-Type:application/json;charset=UTF-8 { "code": 0, "message": "success", "contact_comments": [ { "comment_id": 460000000053131, "contact_id": 460000000026049, "contact_name": "Bowman and Co", "description": "", "commented_by_id": 460000000024003, "commented_by": "David Sujin", "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" }, {...}, {...} ] }

List Refunds

List the refund history of a contact.

GET /contacts/{contact_id}/refunds

Request Example

  
$ curl https://invoice.zoho.com/api/v3/contacts/{contact_id}/refunds?authtoken=ba4604e8e433g9c892e360d53463oec5&organization_id=10234695 -H "Authorization: Zoho-authtoken ba4604e8e433g9c892e360d53463oec5" -H "Content-Type: application/json;charset=UTF-8"

Response Example

  
HTTP/1.1 200 OK Content-Type:application/json;charset=UTF-8 { "code": 0, "message": "success", "creditnote_refunds": [ { "creditnote_refund_id": 982000000567158, "creditnote_id": 982000000567134, "date": "2013-11-19", "refund_mode": "cash", "reference_number": 782364, "creditnote_number": "CN-00001", "customer_name": "Bowman & Co", "description": "", "amount_bcy": 57.15, "amount_fcy": 57.15 } ] }

Contact Persons

A contact person is an individual who acts as a representative of an organisation for communication purpose. For example, a Manager can be a contact person for an organisation.

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
ID of the contact person
first_name
string
First Name of the contact. Maximum length allowed [100]
last_name
string
Last Name of the contact. Maximum length allowed [100]
email
string
Email ID of the contact person. Maximum length allowed [100]
skype
string
skype address of the contact person. Maximum length [50]
designation
string
designation of the contact person in the organisation. Maximum length [50]
department
string
department to which the contact person belongs. Maximum length [50]

Create a contact person

Create a contact person for contact.

POST /contacts/contactpersons

Request Example

  
$ curl https://invoice.zoho.com/api/v3/contacts/contactpersons?authtoken=ba4604e8e433g9c892e360d53463oec5&organization_id=10234695 -H "Authorization: Zoho-authtoken ba4604e8e433g9c892e360d53463oec5" -H "Content-Type: application/json;charset=UTF-8" -d JSONString='{ "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": "success", "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
ID of the contact person
salutation
Optional
Salutation for the contact. Maximum length allowed [25]
first_name
Required
First Name of the contact. Maximum length allowed [100]
last_name
Optional
Last Name of the contact. Maximum length allowed [100]
email
Optional
Email ID of the contact person. Maximum length allowed [100]
phone
Optional
Phone number of the contact person. Maximum length [50]
mobile
Optional
Mobile/Cell number of the contact person. Maximum length [50]
skype
Optional
skype address of the contact person. Maximum length [50]
designation
Optional
designation of the contact person in the organisation. Maximum length [50]
department
Optional
department to which the contact person belongs. Maximum length [50]
enable_portal
Optional
option to enable or disable portal access the contact person. allowed values true,false

Update a contact person

Update details of an existing contact person.

PUT /contacts/contactpersons/{contact_person_id}

Request Example

  
$ curl https://invoice.zoho.com/api/v3/contacts/contactpersons/{contact_person_id}?authtoken=ba4604e8e433g9c892e360d53463oec5&organization_id=10234695 -H "Authorization: Zoho-authtoken ba4604e8e433g9c892e360d53463oec5" -H "Content-Type: application/json;charset=UTF-8" -d JSONString='{ "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": "success", "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
ID of the contact person
salutation
Optional
Salutation for the contact. Maximum length allowed [25]
first_name
Required
First Name of the contact. Maximum length allowed [100]
last_name
Optional
Last Name of the contact. Maximum length allowed [100]
email
Optional
Email ID of the contact person. Maximum length allowed [100]
phone
Optional
Phone number of the contact person. Maximum length [50]
mobile
Optional
Mobile/Cell number of the contact person. Maximum length [50]
skype
Optional
skype address of the contact person. Maximum length [50]
designation
Optional
designation of the contact person in the organisation. Maximum length [50]
department
Optional
department to which the contact person belongs. Maximum length [50]
enable_portal
Optional
option to enable or disable portal access the contact person. allowed values true,false

List contact persons

List all contacts with pagination.

GET /contacts/{contact_id}/contactpersons

Request Example

  
$ curl https://invoice.zoho.com/api/v3/contacts/{contact_id}/contactpersons?authtoken=ba4604e8e433g9c892e360d53463oec5&organization_id=10234695 -H "Authorization: Zoho-authtoken ba4604e8e433g9c892e360d53463oec5" -H "Content-Type: application/json;charset=UTF-8"

Response Example

  
HTTP/1.1 200 OK Content-Type:application/json;charset=UTF-8 { "code": 0, "message": "success", "contact_persons": [ { "contact_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 }, {...}, {...} ] }

Get a contact person

Get the details of a contact person.

GET /contacts/{contact_id}/contactpersons/{contact_person_id}

Request Example

  
$ curl https://invoice.zoho.com/api/v3/contacts/{contact_id}/contactpersons/{contact_person_id}?authtoken=ba4604e8e433g9c892e360d53463oec5&organization_id=10234695 -H "Authorization: Zoho-authtoken ba4604e8e433g9c892e360d53463oec5" -H "Content-Type: application/json;charset=UTF-8"

Response Example

  
HTTP/1.1 200 OK Content-Type:application/json;charset=UTF-8 { "code": 0, "message": "success", "contact_person": { "contact_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://invoice.zoho.com/api/v3/contacts/contactpersons/{contact_person_id}?authtoken=ba4604e8e433g9c892e360d53463oec5&organization_id=10234695 -H "Authorization: Zoho-authtoken ba4604e8e433g9c892e360d53463oec5" -H "Content-Type: application/json;charset=UTF-8"

Response Example

  
HTTP/1.1 200 OK Content-Type:application/json;charset=UTF-8 { "code": 0, "message": "The contact person has been deleted." }

Mark as primary contact person

Mark a contact person as primary for contact.

POST /contacts/contactpersons/{contact_person_id}/primary

Request Example

  
$ curl https://invoice.zoho.com/api/v3/contacts/contactpersons/{contact_person_id}/primary?authtoken=ba4604e8e433g9c892e360d53463oec5&organization_id=10234695 -H "Authorization: Zoho-authtoken ba4604e8e433g9c892e360d53463oec5" -H "Content-Type: application/json;charset=UTF-8"

Response Example

  
HTTP/1.1 200 OK Content-Type:application/json;charset=UTF-8 { "code": 0, "message": "This contact person has been marked as your primary contact person." }

Estimates

An estimate is a quote or an approximation, of the prices, which a seller projects to a buyer. There can be different estimates to different buyers.

Example

{ "estimate_id": 982000000567011, "customer_name": "Bowman & Co", "customer_id": 982000000567001, "line_items": [ { "item_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 } ], "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" }

Attribute

estimate_id
string
The unique id of a particular estimate
customer_name
string
Name of the Customer to whom the estimate is sent.
customer_id
string
Customer ID on the estimate.
list
Line items of an estimate.
item_id
string
Unique ID of the item.
name
string
The name of the line item
item_order
integer
The order of the line item_order
bcy_rate
double
base currency rate
rate
double
Rate of the line item.
quantity
float
The quantity of line item
unit
string
Unit of measuring the line item e.g. kgs, Nos.
discount_amount
float
The discount amount on the line item
discount
double
Discount applied to the invoice. 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 to the estimate
tax_name
string
The name of the tax
tax_type
string
The type of the tax
tax_percentage
float
The percentage of tax levied
item_total
float
The total amount of the line items
status
string
Status of the estimate. Allowed Valuesdraft, sent, invoiced , accepted, declined and expired
estimate_number
string
Estimate Serial number.
reference_number
string
Transaction reference number.
date
string
Date on the estimate.
currency_id
string
The Unique 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
estimate total value.
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

Create an Estimate

Create an estimate for your customer.

POST /estimates

Request Example

  
$ curl https://invoice.zoho.com/api/v3/estimates?authtoken=ba4604e8e433g9c892e360d53463oec5&organization_id=10234695 -H "Authorization: Zoho-authtoken ba4604e8e433g9c892e360d53463oec5" -H "Content-Type: application/json;charset=UTF-8" -d JSONString='{ "customer_id": 982000000567001, "contact_persons": [ "982000000567003", "982000000567019" ], "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": " ", "name": "Hard Drive", "description": "500GB, USB 2.0 interface 1400 rpm, protective hard case.", "item_order": 1, "rate": 120, "product_type": "goods", "hsn_or_sac": 80540, "quantity": 1, "unit": " ", "discount_amount": 0, "discount": 0, "tax_id": 982000000557028, "tax_exemption_id": 11149000000061054, "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 }'

Response Example

  
HTTP/1.1 201 Created Content-Type:application/json;charset=UTF-8 { "code": 0, "message": "The estimate has been created", "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", "contact_persons": [ "982000000567003", "982000000567019" ], "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": " ", "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, "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": "2013-12-18T04:46:45-0500", "salesperson_id": 982000000567003, "salesperson_name": "Will smith" } }

ARGUMENTS

customer_id
Required
Customer ID on the estimate.
contact_persons
Optional
Array of contact person(s) for whom estimate has to be sent.
template_id
Optional
ID of the template used for 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
Estimate Serial number.
reference_number
Optional
Transaction reference number.
date
Optional
Date on the estimate.
expiry_date
Optional
The date of expiration of the estimates
exchange_rate
Optional
Foreign 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 edition
Optional
Used to specify whether the line item rates are inclusive or exclusive of tax.
custom_body
Optional
Custom content of the email
custom_subject
Optional
Subjet for the email to be sent
salesperson_name
Optional
Name of the sales person.
custom_fields
Optional
Custom fields for an estimate.
index
Optional
An index for the custom field.
value
Optional
Value for the custom field
Required
Line items of an estimate.
item_id
Optional
Unique ID of the item.
name
Optional
The name of the line item
item_order
Optional
The order of the line item_order
rate
Optional
Rate 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
quantity
Optional
The quantity of line item
unit
Optional
Unit of measuring 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
Optional
ID of the tax or tax group applied to the estimate
tax_exemption_id
India, US and CA edition only
Optional
ID of the tax exemption.
avatax_tax_code
Avalara integration only
Optional
A tax code is a unique label used to group Items (products, services, or charges) together. Maximum length [25]
avatax_use_code
Avalara integration only
Optional
Used to group like customers for exemption purposes. It is a custom value that links customers to a tax rule. Select from Avalara [standard codes][1] or enter a custom code.
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
Enlist the terms & conditions for estimate
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 value.
tax_id
Optional
ID of the tax or tax group applied to the estimate
tax_exemption_id
India, US and CA edition only
Optional
ID of the tax exemption.
tax_authority_id
US and CA 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_tax_code
Avalara integration only
Optional
A tax code is a unique label used to group Items (products, services, or charges) together. Maximum length [25]
avatax_exempt_no
Avalara integration only
Optional
Exemption certificate number of the customer.
vat_treatment
Optional
Enter vat treatment

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 to be entered manually.

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://invoice.zoho.com/api/v3/estimates/{estimate_id}?authtoken=ba4604e8e433g9c892e360d53463oec5&organization_id=10234695 -H "Authorization: Zoho-authtoken ba4604e8e433g9c892e360d53463oec5" -H "Content-Type: application/json;charset=UTF-8" -d JSONString='{ "customer_id": 982000000567001, "contact_persons": [ "982000000567003", "982000000567019" ], "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": " ", "name": "Hard Drive", "description": "500GB, USB 2.0 interface 1400 rpm, protective hard case.", "item_order": 1, "rate": 120, "quantity": 1, "product_type": "goods", "hsn_or_sac": 80540, "unit": " ", "discount_amount": 0, "discount": 0, "tax_id": 982000000557028, "tax_exemption_id": 11149000000061054, "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 }'

Response Example

  
HTTP/1.1 200 OK Content-Type:application/json;charset=UTF-8 { "code": 0, "message": "Estimate information has been updated.", "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", "contact_persons": [ "982000000567003", "982000000567019" ], "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": " ", "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, "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": "2013-12-18T04:46:45-0500", "salesperson_id": 982000000567003, "salesperson_name": "Will smith" } }

ARGUMENTS

customer_id
Required
Customer ID on the estimate.
contact_persons
Optional
Array of contact person(s) for whom estimate has to be sent.
template_id
Optional
ID of the template used for 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
Estimate Serial number.
reference_number
Optional
Transaction reference number.
date
Optional
Date on the estimate.
expiry_date
Optional
The date of expiration of the estimates
exchange_rate
Optional
Foreign 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 edition
Optional
Used to specify whether the line item rates are inclusive or exclusive of tax.
custom_body
Optional
Custom content of the email
custom_subject
Optional
Subjet for the email to be sent
salesperson_name
Optional
Name of the sales person.
custom_fields
Required
Custom fields for an estimate.
index
Optional
An index for the custom field.
value
Optional
Value for the custom field
Optional
Line items of an estimate.
item_id
Optional
Unique ID of the item.
name
Optional
The name of the line item
item_order
Optional
The order of the line item_order
rate
Optional
Rate of the line item.
quantity
Optional
The quantity of line item
product_type
Optional
Enter goods/services
hsn_or_sac
India Edition only
Optional
Add HSN/SAC code for your goods/services
unit
Optional
Unit of measuring 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
Optional
ID of the tax or tax group applied to the estimate
tax_exemption_id
India, US and CA edition only
Optional
ID of the tax exemption.
avatax_tax_code
Avalara integration only
Optional
A tax code is a unique label used to group Items (products, services, or charges) together. Maximum length [25]
avatax_use_code
Avalara integration only
Optional
Used to group like customers for exemption purposes. It is a custom value that links customers to a tax rule. Select from Avalara [standard codes][1] or enter a custom code.
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
Enlist the terms & conditions for estimate
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 value.
tax_id
Optional
ID of the tax or tax group applied to the estimate
tax_exemption_id
India, US and CA edition only
Optional
ID of the tax exemption.
tax_authority_id
US and CA 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_tax_code
Avalara integration only
Optional
A tax code is a unique label used to group Items (products, services, or charges) together. Maximum length [25]
avatax_exempt_no
Avalara integration only
Optional
Exemption certificate number of the customer.
vat_treatment
Optional
Enter vat treatment

Query Params

ignore_auto_number_generation
Optional
Ignore auto estimate number generation for this estimate. This mandates the estimate number to be entered manually.

Get an estimate

Get the details of an estimate.

GET /estimates/{estimate_id}

Request Example

  
$ curl https://invoice.zoho.com/api/v3/estimates/{estimate_id}?authtoken=ba4604e8e433g9c892e360d53463oec5&organization_id=10234695 -H "Authorization: Zoho-authtoken ba4604e8e433g9c892e360d53463oec5" -H "Content-Type: application/json;charset=UTF-8"

Response Example

  
HTTP/1.1 200 OK Content-Type:application/json;charset=UTF-8 { "code": 0, "message": "success", "estimate": { "estimate_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", "contact_persons": [ "982000000567003", "982000000567019" ], "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": " ", "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, "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": "2013-12-18T04: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://invoice.zoho.com/api/v3/estimates?authtoken=ba4604e8e433g9c892e360d53463oec5&organization_id=10234695 -H "Authorization: Zoho-authtoken ba4604e8e433g9c892e360d53463oec5" -H "Content-Type: application/json;charset=UTF-8" -d JSONString='{ "estimate_number": "EST-00002", "reference_number": "QRT-12346", "customer_name": "Bowman & Co", "total": 40.6, "customer_id": 982000000567001, "item_id": " ", "item_name": " ", "item_description": " ", "custom_field": " ", "expiry_date": "2013-11-30", "date": "2013-11-18", "status": "draft", "filter_by": " ", "search_text": " ", "sort_column": "created_time" }'

Response Example

  
HTTP/1.1 200 OK Content-Type:application/json;charset=UTF-8 { "code": 0, "message": "success", "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": "2013-12-18T04: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" }, {...}, {...} ] }

ARGUMENTS

estimate_number
Optional
Search estimates by Serial 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
Name of the Customer to whom the estimate is sent.Variants customer_name_startswith and customer_name_contains
total
Optional
estimate total value. Variants total_less_than, total_less_equals, total_greater_than and total_greater_equals
customer_id
Optional
Customer ID on the estimate.
item_id
Optional
Unique ID of the item.
item_name
Optional
item name for which estimate is made . Variants item_name_startswith and item_name_contains
item_description
Optional
Description of items on estimate. Variantsitem_description_startswith and item_description_contains
custom_field
Optional
Additional fields in the estimate. Variantscustom_field_startswith and custom_field_contains
expiry_date
Optional
The date of expiration of the estimates
date
Optional
Date on the estimate.
status
Optional
Status of the estimate. 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://invoice.zoho.com/api/v3/estimates/{estimate_id}?authtoken=ba4604e8e433g9c892e360d53463oec5&organization_id=10234695 -H "Authorization: Zoho-authtoken ba4604e8e433g9c892e360d53463oec5" -H "Content-Type: application/json;charset=UTF-8"

Response Example

  
HTTP/1.1 200 OK Content-Type:application/json;charset=UTF-8 { "code": 0, "message": "The estimate has been deleted." }

Mark an estimate as sent

Mark a draft estimate as sent.

POST /estimates/{estimate_id}/status/sent

Request Example

  
$ curl https://invoice.zoho.com/api/v3/estimates/{estimate_id}/status/sent?authtoken=ba4604e8e433g9c892e360d53463oec5&organization_id=10234695 -H "Authorization: Zoho-authtoken ba4604e8e433g9c892e360d53463oec5" -H "Content-Type: application/json;charset=UTF-8"

Response Example

  
HTTP/1.1 200 OK Content-Type:application/json;charset=UTF-8 { "code": 0, "message": "Estimate status has been changed to Sent" }

Mark an estimate as accepted

Mark a sent estimate as accepted if the customer has accepted it.

POST /estimates/{estimate_id}/status/accepted

Request Example

  
$ curl https://invoice.zoho.com/api/v3/estimates/{estimate_id}/status/accepted?authtoken=ba4604e8e433g9c892e360d53463oec5&organization_id=10234695 -H "Authorization: Zoho-authtoken ba4604e8e433g9c892e360d53463oec5" -H "Content-Type: application/json;charset=UTF-8"

Response Example

  
HTTP/1.1 200 OK Content-Type:application/json;charset=UTF-8 { "code": 0, "message": "Estimate status has been changed to Accepted." }

Mark an estimate as declined

Mark a sent estimate as declined if the customer has rejected it.

POST /estimates/{estimate_id}/status/declined

Request Example

  
$ curl https://invoice.zoho.com/api/v3/estimates/{estimate_id}/status/declined?authtoken=ba4604e8e433g9c892e360d53463oec5&organization_id=10234695 -H "Authorization: Zoho-authtoken ba4604e8e433g9c892e360d53463oec5" -H "Content-Type: application/json;charset=UTF-8"

Response Example

  
HTTP/1.1 200 OK Content-Type:application/json;charset=UTF-8 { "code": 0, "message": "Estimate status has been changed to Declined." }

Email an estimate

Email an estimate to the customer. Input json string is not mandatory. If input json string is empty, mail will be send with default mail content.

POST /estimates/{estimate_id}/email

Request Example

  
$ curl https://invoice.zoho.com/api/v3/estimates/{estimate_id}/email?authtoken=ba4604e8e433g9c892e360d53463oec5&organization_id=10234695 -H "Authorization: Zoho-authtoken ba4604e8e433g9c892e360d53463oec5" -H "Content-Type: application/json;charset=UTF-8" -d JSONString='{ "send_from_org_email_id": false, "to_mail_ids": [ "willsmith@bowmanfurniture.com" ], "cc_mail_ids": [ "peterparker@bowmanfurniture.com" ], "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 addresses of the recipients.
cc_mail_ids
Optional
Array of email addresses of the recipients to be CC'd.
subject
Optional
Subject of an email has to be sent.
body
Optional
Body/content 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://invoice.zoho.com/api/v3/estimates/email?authtoken=ba4604e8e433g9c892e360d53463oec5&organization_id=10234695 -H "Authorization: Zoho-authtoken ba4604e8e433g9c892e360d53463oec5" -H "Content-Type: application/json;charset=UTF-8"

Response Example

  
HTTP/1.1 200 OK Content-Type:application/json;charset=UTF-8 { "code": 0, "message": "Mission accomplished! We've sent all the estimates." }

Query Params

estimate_ids
Required
Comma separated estimate ids which are to be emailed.

Get estimate email content

Get the email content of an estimate.

GET /estimates/{estimate_id}/email

Request Example

  
$ curl https://invoice.zoho.com/api/v3/estimates/{estimate_id}/email?authtoken=ba4604e8e433g9c892e360d53463oec5&organization_id=10234695 -H "Authorization: Zoho-authtoken ba4604e8e433g9c892e360d53463oec5" -H "Content-Type: application/json;charset=UTF-8"

Response Example

  
HTTP/1.1 200 OK Content-Type:application/json;charset=UTF-8 { "code": 0, "message": "success", "body": "Dear Customer, Thanks for your business enquiry. The estimate EST-000002 is attached with this email. We can get started if you send us your consent. For any assistance you can reach us via email or phone. Looking forward to hearing back from you. Here's an overview of the estimate for your reference. Estimate Overview: Estimate : EST-000002 Date : 03 Oct 2013 Amount : $36.47 Regards<br>\\nZillium Inc<br>\\n\"\"", "error_list": [ {...} ], "subject": "Statement of transactions with Zillium Inc", "emailtemplates": [ { "selected": true, "name": "Hard Drive", "email_template_id": 982000000000079 } ], "to_contacts": [ { "first_name": "David", "selected": true, "phone": "+1-925-921-9201", "last_name": "Sujin", "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://invoice.zoho.com/api/v3/estimates/pdf?authtoken=ba4604e8e433g9c892e360d53463oec5&organization_id=10234695 -H "Authorization: Zoho-authtoken ba4604e8e433g9c892e360d53463oec5" -H "Content-Type: application/json;charset=UTF-8"

Response Example

  
HTTP/1.1 200 OK Content-Type:application/json;charset=UTF-8 { "code": 0, "message": "success" }

Query Params

estimate_ids
Required
Comma separated estimate ids which are to be emailed.

Bulk print estimates

Export estimates as pdf and print them. Maximum of 25 estimates can be printed.

GET /estimates/print

Request Example

  
$ curl https://invoice.zoho.com/api/v3/estimates/print?authtoken=ba4604e8e433g9c892e360d53463oec5&organization_id=10234695 -H "Authorization: Zoho-authtoken ba4604e8e433g9c892e360d53463oec5" -H "Content-Type: application/json;charset=UTF-8"

Response Example

  
HTTP/1.1 200 OK Content-Type:application/json;charset=UTF-8 { "code": 0, "message": "success" }

Query Params

estimate_ids
Required
Comma separated estimate ids which are to be emailed.

Update billing address

Updates the billing address for this estimate alone.

PUT /estimates/{estimate_id}/address/billing

Request Example

  
$ curl https://invoice.zoho.com/api/v3/estimates/{estimate_id}/address/billing?authtoken=ba4604e8e433g9c892e360d53463oec5&organization_id=10234695 -H "Authorization: Zoho-authtoken ba4604e8e433g9c892e360d53463oec5" -H "Content-Type: application/json;charset=UTF-8" -d JSONString='{ "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 of the receiver
city
Optional
City of the Billing address of the contact
state
Optional
State of the Billing address of the contact
zip
Optional
ZIP code of the billing address
country
Optional
Country of the billing address
fax
Optional
FAX number of the contact

Update shipping address

Updates the shipping address for an existing estimate alone.

PUT /estimates/{estimate_id}/address/shipping

Request Example

  
$ curl https://invoice.zoho.com/api/v3/estimates/{estimate_id}/address/shipping?authtoken=ba4604e8e433g9c892e360d53463oec5&organization_id=10234695 -H "Authorization: Zoho-authtoken ba4604e8e433g9c892e360d53463oec5" -H "Content-Type: application/json;charset=UTF-8" -d JSONString='{ "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 templates

Get all estimate pdf templates.

GET /estimates/templates

Request Example

  
$ curl https://invoice.zoho.com/api/v3/estimates/templates?authtoken=ba4604e8e433g9c892e360d53463oec5&organization_id=10234695 -H "Authorization: Zoho-authtoken ba4604e8e433g9c892e360d53463oec5" -H "Content-Type: application/json;charset=UTF-8"

Response Example

  
HTTP/1.1 200 OK Content-Type:application/json;charset=UTF-8 { "code": 0, "message": "success", "templates": { "template_name": "Service - Classic", "template_id": 982000000000143, "template_type": "classic" } }

Update estimate template

Update the pdf template associated with the estimate.

PUT /estimates/{estimate_id}/templates/{template_id}

Request Example

  
$ curl https://invoice.zoho.com/api/v3/estimates/{estimate_id}/templates/{template_id}?authtoken=ba4604e8e433g9c892e360d53463oec5&organization_id=10234695 -H "Authorization: Zoho-authtoken ba4604e8e433g9c892e360d53463oec5" -H "Content-Type: application/json;charset=UTF-8"

Response Example

  
HTTP/1.1 200 OK Content-Type:application/json;charset=UTF-8 { "code": 0, "message": "Estimate information has been updated." }

List estimate comments & history

Get the complete history and comments of an estimate.

GET /estimates/{estimate_id}/comments

Request Example

  
$ curl https://invoice.zoho.com/api/v3/estimates/{estimate_id}/comments?authtoken=ba4604e8e433g9c892e360d53463oec5&organization_id=10234695 -H "Authorization: Zoho-authtoken ba4604e8e433g9c892e360d53463oec5" -H "Content-Type: application/json;charset=UTF-8"

Response Example

  
HTTP/1.1 200 OK Content-Type:application/json;charset=UTF-8 { "code": 0, "message": "success", "comments": [ { "comment_id": 982000000567019, "estimate_id": 982000000567011, "description": "Estimate created", "commented_by_id": 982000000554041, "commented_by": "David Sujin", "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://invoice.zoho.com/api/v3/estimates/{estimate_id}/comments?authtoken=ba4604e8e433g9c892e360d53463oec5&organization_id=10234695 -H "Authorization: Zoho-authtoken ba4604e8e433g9c892e360d53463oec5" -H "Content-Type: application/json;charset=UTF-8" -d JSONString='{ "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
A short note on the estimate
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://invoice.zoho.com/api/v3/estimates/{estimate_id}/comments/{comment_id}?authtoken=ba4604e8e433g9c892e360d53463oec5&organization_id=10234695 -H "Authorization: Zoho-authtoken ba4604e8e433g9c892e360d53463oec5" -H "Content-Type: application/json;charset=UTF-8" -d JSONString='{ "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": "David Sujin", "date": "2013-11-18", "date_description": "yesterday", "time": "2:02 AM", "comment_type": "system" } }

ARGUMENTS

description
Optional
A short note on the estimate
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://invoice.zoho.com/api/v3/estimates/{estimate_id}/comments/{comment_id}?authtoken=ba4604e8e433g9c892e360d53463oec5&organization_id=10234695 -H "Authorization: Zoho-authtoken ba4604e8e433g9c892e360d53463oec5" -H "Content-Type: application/json;charset=UTF-8"

Response Example

  
HTTP/1.1 200 OK Content-Type:application/json;charset=UTF-8 { "code": 0, "message": "The comment has been deleted." }

Invoices

An invoice is a statement of items sold by a seller. It includes all the details of sale including units of goods, price of goods sold, shipping details, etc.

Example

{ "invoice_number": "INV-00003", "line_items": [ { "item_id": 982000000030049, "project_id": " ", "time_entry_ids": [ {} ], "expense_id": " ", "name": "Hard Drive", "description": "500GB, USB 2.0 interface 1400 rpm, protective hard case.", "item_order": 1, "bcy_rate": 120, "rate": 120, "quantity": 1, "unit": " ", "discount_amount": 0, "discount": 0, "tax_id": 982000000557028, "tax_name": "VAT", "tax_type": "tax", "tax_percentage": 12.5, "item_total": 120 } ], "recurring_invoice_id": " ", "custom_field": " ", "search_text": " ", "sort_column": "created_time", "invoice_id": 982000000567114, "customer_name": "Bowman & Co", "customer_id": 982000000567001, "status": "draft", "reference_number": " ", "date": "2013-11-17", "due_date": "2013-12-03", "due_days": "Due in 14 day(s)", "currency_id": 982000000000190, "currency_code": "USD", "total": 40.6, "balance": 40.6, "created_time": "2013-11-17T02:17:40-0800", "is_emailed": false, "reminders_sent": 1, "payment_expected_date": " ", "last_payment_date": " " }

Attribute

invoice_number
string
An unique number given to the invoice. Maximum length [100]
list
Line items of an invoice.
item_id
string
Unique item id.
project_id
string
Unique ID of the projet associated to an invoice
time_entry_ids
list
Unique ID's of all the time entries associated to the linked project
expense_id
string
Unique ID of the expenses associated
expense_receipt_name
string
Name of the expense receipt associated
name
string
The name of the line item. Maximum length [100]
item_order
integer
The order of the line item_order
bcy_rate
double
base currency rate
rate
double
Rate of the line item.
quantity
float
The quantity of line item
unit
string
Unit of the line item e.g. kgs, Nos. Maximum length [100]
discount_amount
float
The discount amount on the line item
discount
float
Discount applied to the invoice. It can be either in % or in amount. e.g. 12.5% or 190. Maximum length [100]
tax_id
string
ID of the tax or tax group applied to the estimate
tax_name
string
The name of the tax
tax_type
string
The type of the tax
tax_percentage
float
The percentage of tax levied
item_total
float
The total amount of the line items
recurring_invoice_id
string
ID of the recurring invoice from which the invoice is created.
email
string
contact's email id. Maximum length [100]
custom_field
string
custom fields for invoice.
search_text
string
Search invoices by invoice number or purchase order or customer name. Maximum length [100]
sort_column
string
Sort invoices.Allowed Values: customer_name, invoice_number, date, due_date, total, balance and created_time
invoice_id
string
The ID of the invoice
customer_name
string
The name of the customer. Maximum length [100]
customer_id
string
ID of the customer the invoice has to be created.
status
string
Status of the invoice. Allowed Values: sent, draft, overdue, paid, void, unpaid, partially_paid and viewed
invoice_number
string
An unique number given to the invoice. Maximum length [100]
reference_number
string
The reference number of the invoice
date
string
invoice date. Date format yyyy-mm-dd
due_date
string
due date of the invoices. Date format yyyy-mm-dd
due_days
string
Specifies the number of day in which the invoice would become overdue
currency_id
string
The currenct id of the currency
currency_code
string
The currency code in which the invoice is created.
total
string
The total amount to be paid
balance
string
The unpaid amount
created_time
string
The time of creation of the invoices
is_emailed
boolean
Boolean check to see if the mail has been sent
reminders_sent
integer
The number of reminders sent
payment_expected_date
string
The expected date of payment
last_payment_date
string
The last payment date of the invoice

Create an invoice

Create an invoice for your customer.

POST /invoices

Request Example

  
$ curl https://invoice.zoho.com/api/v3/invoices?authtoken=ba4604e8e433g9c892e360d53463oec5&organization_id=10234695 -H "Authorization: Zoho-authtoken ba4604e8e433g9c892e360d53463oec5" -H "Content-Type: application/json;charset=UTF-8" -d JSONString='{ "customer_id": 982000000567001, "contact_persons": [ "982000000870911", "982000000870915" ], "invoice_number": "INV-00003", "reference_number": " ", "place_of_supply": "TN", "gst_treatment": "business_gst", "gst_no": "22AAAAA0000A1Z5", "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": [ {} ], "expense_id": " ", "name": "Hard Drive", "product_type": "goods", "hsn_or_sac": 80540, "warehouse_id": "", "description": "500GB, USB 2.0 interface 1400 rpm, protective hard case.", "item_order": 1, "rate": 120, "quantity": 1, "unit": " ", "discount": 0, "tax_id": 982000000557028, "tax_exemption_id": 11149000000061054, "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 }'

Response Example

  
HTTP/1.1 201 Created Content-Type:application/json;charset=UTF-8 { "code": 0, "message": "The invoice has been created.", "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-17T02:17:40-0800", "last_modified_time": "2013-12-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
The IDs of the contact person associated with the contact.
invoice_number
Optional
An unique number given to the invoice. Maximum length [100]
reference_number
Optional
The reference number of the 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.
template_id
Optional
ID of the pdf template associated with the invoice.
date
Required
invoice date. Date format yyyy-mm-dd
payment_terms
Optional
Payment terms in days e.g. 15, 30, 60. Invoice due date will be calculated based on this. Maximum length [100]
payment_terms_label
Optional
Used to override the default payment terms label. Default value for 15 days is "Net 15 Days". Maximum length [100]
due_date
Optional
due date of the invoices. Date format yyyy-mm-dd
discount
Optional
Discount applied to the invoice. It can be either in % or in amount. e.g. 12.5% or 190. Maximum length [100]
is_discount_before_tax
Optional
Check if discount is exclusive of tax
discount_type
Optional
Type of discount
is_inclusive_tax
Optional
To check if discount is inclusive 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. Maximum length [200]
custom_fields
Optional
Custom fields for an invoice.
project_id
Optional
Unique ID of the projet associated to an invoice
Required
Line items of an invoice.
item_id
Optional
Unique item id.
project_id
Optional
Unique ID of the projet associated to an invoice
time_entry_ids
Optional
Unique ID's of all the time entries associated to the linked project
expense_id
Optional
Unique ID of the expenses associated
name
Optional
The name of the line item. Maximum length [100]
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
item_order
Optional
The order of the line item_order
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. Maximum length [100]
discount
Optional
Discount applied to the invoice. It can be either in % or in amount. e.g. 12.5% or 190. Maximum length [100]
tax_id
Optional
ID of the tax or tax group applied to the estimate
tax_exemption_id
India, US and CA 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. Maximum length [25]
avatax_exempt_no
Avalara integration only
Optional
Exemption certificate number of the customer. Maximum length [25]
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
Customized email content
custom_subject
Optional
Customized Subject line
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. Maximum length [100]
adjustment
Optional
Adjustments made to the invoice.
adjustment_description
Optional
Customize the adjustment description. E.g. Rounding off.
reason
Optional
Description of the attachment
tax_authority_id
US and CA 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, US and CA 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. Maximum 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. Maximum length [25]
avatax_exempt_no
Avalara integration only
Optional
Exemption certificate number of the customer. Maximum length [25]
vat_treatment
Optional
Enter vat treatment

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://invoice.zoho.com/api/v3/invoices/{invoice_id}?authtoken=ba4604e8e433g9c892e360d53463oec5&organization_id=10234695 -H "Authorization: Zoho-authtoken ba4604e8e433g9c892e360d53463oec5" -H "Content-Type: application/json;charset=UTF-8" -d JSONString='{ "customer_id": 982000000567001, "contact_persons": [ "982000000870911", "982000000870915" ], "invoice_number": "INV-00003", "reference_number": " ", "place_of_supply": "TN", "gst_treatment": "business_gst", "gst_no": "22AAAAA0000A1Z5", "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": [ {} ], "expense_id": " ", "name": "Hard Drive", "product_type": "goods", "hsn_or_sac": 80540, "warehouse_id": "", "description": "500GB, USB 2.0 interface 1400 rpm, protective hard case.", "item_order": 1, "rate": 120, "quantity": 1, "unit": " ", "discount": 0, "tax_id": 982000000557028, "tax_exemption_id": 11149000000061054, "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 }'

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", "date": "2013-11-17", "status": "draft", "is_pre_gst": true, "place_of_supply": "TN", "gst_no": "22AAAAA0000A1Z5", "gst_treatment": "business_gst", "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": " ", "warehouses": [ { "warehouse_id": "", "warehouse_name": "", "warehouse_stock_on_hand": "" } ], "item_type": "goods", "product_type": "goods", "time_entry_ids": [ {...} ], "expense_id": " ", "name": "Hard Drive", "description": "500GB, USB 2.0 interface 1400 rpm, protective hard case.", "item_order": 1, "bcy_rate": 120, "rate": 120, "quantity": 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-17T02:17:40-0800", "last_modified_time": "2013-12-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
The IDs of the contact person associated with the contact.
invoice_number
Optional
An unique number given to the invoice. Maximum length [100]
reference_number
Optional
The reference number of the 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.
template_id
Optional
ID of the pdf template associated with the invoice.
date
Optional
invoice date. Date format yyyy-mm-dd
payment_terms
Optional
Payment terms in days e.g. 15, 30, 60. Invoice due date will be calculated based on this. Maximum length [100]
payment_terms_label
Optional
Used to override the default payment terms label. Default value for 15 days is "Net 15 Days". Maximum length [100]
due_date
Optional
due date of the invoices. Date format yyyy-mm-dd
discount
Optional
Discount applied to the invoice. It can be either in % or in amount. e.g. 12.5% or 190. Maximum length [100]
is_discount_before_tax
Optional
Check if discount is exclusive of tax
discount_type
Optional
Type of discount
is_inclusive_tax
Optional
To check if discount is inclusive 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. Maximum length [200]
custom_fields
Optional
Custom fields for an invoice.
project_id
Optional
Unique ID of the projet associated to an invoice
Required
Line items of an invoice.
item_id
Optional
Unique item id.
project_id
Optional
Unique ID of the projet associated to an invoice
time_entry_ids
Optional
Unique ID's of all the time entries associated to the linked project
expense_id
Optional
Unique ID of the expenses associated
name
Optional
The name of the line item. Maximum length [100]
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
item_order
Optional
The order of the line item_order
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. Maximum length [100]
discount
Optional
Discount applied to the invoice. It can be either in % or in amount. e.g. 12.5% or 190. Maximum length [100]
tax_id
Optional
ID of the tax or tax group applied to the estimate
tax_exemption_id
India, US and CA 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. Maximum length [25]
avatax_exempt_no
Avalara integration only
Optional
Exemption certificate number of the customer. Maximum length [25]
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
Customized email content
custom_subject
Optional
Customized Subject line
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. Maximum length [100]
adjustment
Optional
Adjustments made to the invoice.
adjustment_description
Optional
Customize the adjustment description. E.g. Rounding off.
reason
Optional
Description of the attachment
tax_authority_id
US and CA 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, US and CA 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. Maximum 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. Maximum length [25]
avatax_exempt_no
Avalara integration only
Optional
Exemption certificate number of the customer. Maximum length [25]
vat_treatment
Optional
Enter vat treatment

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://invoice.zoho.com/api/v3/invoices/{invoice_id}?authtoken=ba4604e8e433g9c892e360d53463oec5&organization_id=10234695 -H "Authorization: Zoho-authtoken ba4604e8e433g9c892e360d53463oec5" -H "Content-Type: application/json;charset=UTF-8"

Response Example

  
HTTP/1.1 200 OK Content-Type:application/json;charset=UTF-8 { "code": 0, "message": "success", "invoice": { "invoice_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": " ", "warehouses": [ { "warehouse_id": "", "warehouse_name": "", "warehouse_stock_on_hand": "" } ], "item_type": "goods", "product_type": "goods", "time_entry_ids": [ {...} ], "expense_id": " ", "name": "Hard Drive", "description": "500GB, USB 2.0 interface 1400 rpm, protective hard case.", "item_order": 1, "bcy_rate": 120, "rate": 120, "quantity": 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-17T02:17:40-0800", "last_modified_time": "2013-12-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://invoice.zoho.com/api/v3/invoices?authtoken=ba4604e8e433g9c892e360d53463oec5&organization_id=10234695 -H "Authorization: Zoho-authtoken ba4604e8e433g9c892e360d53463oec5" -H "Content-Type: application/json;charset=UTF-8"

Response Example

  
HTTP/1.1 200 OK Content-Type:application/json;charset=UTF-8 { "code": 0, "message": "success", "invoices": [ { "invoice_id": 982000000567114, "ach_payment_initiated": false, "customer_name": "Bowman & Co", "customer_id": 982000000567001, "status": "draft", "invoice_number": "INV-00003", "reference_number": " ", "date": "2013-11-17", "due_date": "2013-12-03", "due_days": "Due in 14 day(s)", "currency_id": 982000000000190, "schedule_time": "", "currency_code": "USD", "is_viewed_by_client": false, "has_attachment": false, "client_viewed_time": "", "total": 40.6, "balance": 40.6, "created_time": "2013-11-17T02:17:40-0800", "last_modified_time": "2013-12-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 }, {...}, {...} ] }

Query Params

invoice_number
Optional
An unique number given to the invoice. Maximum length [100]
item_name
Optional
item name.Variants: item_name_startswith and item_name_contains. Maximum length [100]
item_id
Optional
Unique item id.
item_description
Optional
Search invoices by item description.Variants: item_description_startswith and item_description_contains. Maximum length [100]
reference_number
Optional
The reference number of the invoice
customer_name
Optional
The name of the customer. Maximum length [100]
recurring_invoice_id
Optional
ID of the recurring invoice from which the invoice is created.
email
Optional
contact's email id. Maximum length [100]
total
Optional
The total amount to be paid
balance
Optional
The unpaid amount
custom_field
Optional
custom fields for invoice. Variants: custom_field_startswith and custom_field_contains
date
Optional
invoice date. Date format yyyy-mm-dd. Variants: due_date_start, due_date_end, due_date_before and due_date_after.
due_date
Optional
due date of the invoices. Date format 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. Maximum 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://invoice.zoho.com/api/v3/invoices/{invoice_id}?authtoken=ba4604e8e433g9c892e360d53463oec5&organization_id=10234695 -H "Authorization: Zoho-authtoken ba4604e8e433g9c892e360d53463oec5" -H "Content-Type: application/json;charset=UTF-8"

Response Example

  
HTTP/1.1 200 OK Content-Type:application/json;charset=UTF-8 { "code": 0, "message": "The invoice has been deleted." }

Mark an invoice as sent

Mark a draft invoice as sent.

POST /invoices/{invoice_id}/status/sent

Request Example

  
$ curl https://invoice.zoho.com/api/v3/invoices/{invoice_id}/status/sent?authtoken=ba4604e8e433g9c892e360d53463oec5&organization_id=10234695 -H "Authorization: Zoho-authtoken ba4604e8e433g9c892e360d53463oec5" -H "Content-Type: application/json;charset=UTF-8"

Response Example

  
HTTP/1.1 200 OK Content-Type:application/json;charset=UTF-8 { "code": 0, "message": "Invoice status has been changed to Sent." }

Void an invoice

Mark an invoice status as void. Upon voiding, the payments and credits associated with the invoices will be unassociated and will be under customer credits.

POST /invoices/{invoice_id}/status/void

Request Example

  
$ curl https://invoice.zoho.com/api/v3/invoices/{invoice_id}/status/void?authtoken=ba4604e8e433g9c892e360d53463oec5&organization_id=10234695 -H "Authorization: Zoho-authtoken ba4604e8e433g9c892e360d53463oec5" -H "Content-Type: application/json;charset=UTF-8"

Response Example

  
HTTP/1.1 200 OK Content-Type:application/json;charset=UTF-8 { "code": 0, "message": "Invoice status has been changed to Void." }

Mark as draft

Mark a voided invoice as draft.

POST /invoices/{invoice_id}/status/draft

Request Example

  
$ curl https://invoice.zoho.com/api/v3/invoices/{invoice_id}/status/draft?authtoken=ba4604e8e433g9c892e360d53463oec5&organization_id=10234695 -H "Authorization: Zoho-authtoken ba4604e8e433g9c892e360d53463oec5" -H "Content-Type: application/json;charset=UTF-8"

Response Example

  
HTTP/1.1 200 OK Content-Type:application/json;charset=UTF-8 { "code": 0, "message": "Status of invoice changed from void to draft" }

Email an invoice

Email an invoice to the customer. Input json string is not mandatory. If input json string is empty, mail will be send with default mail content.

POST /invoices/{invoice_id}/email

Request Example

  
$ curl https://invoice.zoho.com/api/v3/invoices/{invoice_id}/email?authtoken=ba4604e8e433g9c892e360d53463oec5&organization_id=10234695 -H "Authorization: Zoho-authtoken ba4604e8e433g9c892e360d53463oec5" -H "Content-Type: application/json;charset=UTF-8" -d JSONString='{ "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 addresses of the recipients.
cc_mail_ids
Optional
Array of email addresses of the recipients to be CC'd.
subject
Optional
The subject of the mail
body
Optional
The body/content 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://invoice.zoho.com/api/v3/invoices/email?authtoken=ba4604e8e433g9c892e360d53463oec5&organization_id=10234695 -H "Authorization: Zoho-authtoken ba4604e8e433g9c892e360d53463oec5" -H "Content-Type: application/json;charset=UTF-8"

Response Example

  
HTTP/1.1 200 OK Content-Type:application/json;charset=UTF-8 { "code": 0, "message": "Mission accomplished! We've sent all the invoices." }

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://invoice.zoho.com/api/v3/invoices/{invoice_id}/email?authtoken=ba4604e8e433g9c892e360d53463oec5&organization_id=10234695 -H "Authorization: Zoho-authtoken ba4604e8e433g9c892e360d53463oec5" -H "Content-Type: application/json;charset=UTF-8"

Response Example

  
HTTP/1.1 200 OK Content-Type:application/json;charset=UTF-8 { "code": 0, "message": "success", "data": { "bcc_mails": [ {...} ], "gateways_configured": true, "gateways_associated": true, "bcc_mails_str": "", "body": "Dear Customer, <br><br><br><br>Thanks for your business. <br><br><br><br>The invoice INV-00001 is attached with this email. You can choose the easy way out and <a href= https://invoice.zoho.com/SecurePayment?CInvoiceID=b9800228e011ae86abe71227bdacb3c68e1af685f647dcaed747812e0b9314635e55ac6223925675b371fcbd2d5ae3dc >pay online for this invoice.</a> <br><br>Here's an overview of the invoice for your reference. <br><br><br><br>Invoice Overview: <br><br>Invoice : INV-00001 <br><br>Date : 05 Aug 2013 <br><br>Amount : $541.82 <br><br><br><br>It was great working with you. Looking forward to working with you again.<br><br><br>\\nRegards<br>\\nZillium Inc<br>\\n\",", "documents": "", "customer_name": "Bowman & Co", "attach_pdf": true, "entity_id": "2000000007037", "cc_mails_list": [ { "user_name": "David Sujin" } ], "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": "David", "selected": true, "phone": "+1-925-921-9201", "last_name": "Sujin", "salutation": "Mr", "contact_person_id": 982000000567003, "mobile": "+1-4054439562" } ], "attachment_name": " ", "file_name": "INV-00001.pdf", "from_emails": [ { "user_name": "David Sujin", "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://invoice.zoho.com/api/v3/invoices/{invoice_id}/paymentreminder?authtoken=ba4604e8e433g9c892e360d53463oec5&organization_id=10234695 -H "Authorization: Zoho-authtoken ba4604e8e433g9c892e360d53463oec5" -H "Content-Type: application/json;charset=UTF-8" -d JSONString='{ "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://invoice.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 addresses of the recipients.
cc_mail_ids
Required
Array of email addresses of the recipients to be CC'd.
subject
Optional
The subject of the mail
body
Optional
content of the email
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://invoice.zoho.com/api/v3/invoices/paymentreminder?authtoken=ba4604e8e433g9c892e360d53463oec5&organization_id=10234695 -H "Authorization: Zoho-authtoken ba4604e8e433g9c892e360d53463oec5" -H "Content-Type: application/json;charset=UTF-8"

Response Example

  
HTTP/1.1 201 Created Content-Type:application/json;charset=UTF-8 { "code": 0, "message": "success", "info": { "email_success_info": { "message": "The reminders were successfully sent", "sent_count": 2 }, "email_errors_info": [ { "message": "The reminders were successfully sent", "ids": [ {...} ] } ], "code": 4083 } }

Query Params

invoice_ids
Required
Array of invoice ids for which the reminder has to be sent.

Get payment reminder mail content

Get the mail content of the payment reminder.

GET /invoices/{invoice_id}/paymentreminder

Request Example

  
$ curl https://invoice.zoho.com/api/v3/invoices/{invoice_id}/paymentreminder?authtoken=ba4604e8e433g9c892e360d53463oec5&organization_id=10234695 -H "Authorization: Zoho-authtoken ba4604e8e433g9c892e360d53463oec5" -H "Content-Type: application/json;charset=UTF-8"

Response Example

  
HTTP/1.1 200 OK Content-Type:application/json;charset=UTF-8 { "code": 0, "message": "success", "data": { "bcc_mails": [ {...} ], "gateways_configured": true, "gateways_associated": true, "bcc_mails_str": "", "body": "<br>Dear Mr. Sujin,&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://invoice.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": "David Sujin" } ], "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": "David", "selected": true, "phone": "+1-925-921-9201", "last_name": "Sujin", "salutation": "Mr", "contact_person_id": 982000000567003, "mobile": "+1-4054439562" } ], "attachment_name": " ", "file_name": "INV-00001.pdf", "from_emails": [ { "user_name": "David Sujin", "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://invoice.zoho.com/api/v3/invoices/pdf?authtoken=ba4604e8e433g9c892e360d53463oec5&organization_id=10234695 -H "Authorization: Zoho-authtoken ba4604e8e433g9c892e360d53463oec5" -H "Content-Type: application/json;charset=UTF-8"

Response Example

  
HTTP/1.1 200 OK Content-Type:application/json;charset=UTF-8 { "code": 0, "message": "success" }

Query Params

invoice_ids
Required
Comma separated invoice ids which are to be export as pdf.

Bulk print invoices

Export invoices as pdf and print them. Maximum of 25 invoices can be printed.

GET /invoices/print

Request Example

  
$ curl https://invoice.zoho.com/api/v3/invoices/print?authtoken=ba4604e8e433g9c892e360d53463oec5&organization_id=10234695 -H "Authorization: Zoho-authtoken ba4604e8e433g9c892e360d53463oec5" -H "Content-Type: application/json;charset=UTF-8"

Response Example

  
HTTP/1.1 200 OK Content-Type:application/json;charset=UTF-8 { "code": 0, "message": "success" }

Query Params

invoice_ids
Required
Export invoices as pdf and print them. Maximum of 25 invoices can be printed.

Disable payment reminder

Disable automated payment reminders for an invoice.

POST /invoices/{invoice_id}/paymentreminder/disable

Request Example

  
$ curl https://invoice.zoho.com/api/v3/invoices/{invoice_id}/paymentreminder/disable?authtoken=ba4604e8e433g9c892e360d53463oec5&organization_id=10234695 -H "Authorization: Zoho-authtoken ba4604e8e433g9c892e360d53463oec5" -H "Content-Type: application/json;charset=UTF-8"

Response Example

  
HTTP/1.1 200 OK Content-Type:application/json;charset=UTF-8 { "code": 0, "message": "Reminders stopped." }

Enable payment reminder

Enable automated payment reminders for an invoice.

POST /invoices/{invoice_id}/paymentreminder/enable

Request Example

  
$ curl https://invoice.zoho.com/api/v3/invoices/{invoice_id}/paymentreminder/enable?authtoken=ba4604e8e433g9c892e360d53463oec5&organization_id=10234695 -H "Authorization: Zoho-authtoken ba4604e8e433g9c892e360d53463oec5" -H "Content-Type: application/json;charset=UTF-8"

Response Example

  
HTTP/1.1 200 OK Content-Type:application/json;charset=UTF-8 { "code": 0, "message": "Reminders enabled." }

Write off invoice

Write off the invoice balance amount of an invoice.

POST /invoices/{invoice_id}/writeoff

Request Example

  
$ curl https://invoice.zoho.com/api/v3/invoices/{invoice_id}/writeoff?authtoken=ba4604e8e433g9c892e360d53463oec5&organization_id=10234695 -H "Authorization: Zoho-authtoken ba4604e8e433g9c892e360d53463oec5" -H "Content-Type: application/json;charset=UTF-8"

Response Example

  
HTTP/1.1 200 OK Content-Type:application/json;charset=UTF-8 { "code": 0, "message": "Invoice has been written off" }

Cancel write off

Cancel the write off amount of an invoice.

POST /invoices/{invoice_id}/writeoff/cancel

Request Example

  
$ curl https://invoice.zoho.com/api/v3/invoices/{invoice_id}/writeoff/cancel?authtoken=ba4604e8e433g9c892e360d53463oec5&organization_id=10234695 -H "Authorization: Zoho-authtoken ba4604e8e433g9c892e360d53463oec5" -H "Content-Type: application/json;charset=UTF-8"

Response Example

  
HTTP/1.1 200 OK Content-Type:application/json;charset=UTF-8 { "code": 0, "message": "The write off done for this invoice has been cancelled." }

Update billing address

Updates the billing address for this invoice alone.

PUT /invoices/{invoice_id}/address/billing

Request Example

  
$ curl https://invoice.zoho.com/api/v3/invoices/{invoice_id}/address/billing?authtoken=ba4604e8e433g9c892e360d53463oec5&organization_id=10234695 -H "Authorization: Zoho-authtoken ba4604e8e433g9c892e360d53463oec5" -H "Content-Type: application/json;charset=UTF-8" -d JSONString='{ "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 of the customer
city
Optional
City of the customer's billing address
state
Optional
State of the customer's billing address
zip
Optional
ZIP code of the contact's billing address
country
Optional
Country of the contact's billing address
fax
Optional
FAX number of the customer

Update shipping address

Updates the shipping address for this invoice alone.

PUT /invoices/{invoice_id}/address/shipping

Request Example

  
$ curl https://invoice.zoho.com/api/v3/invoices/{invoice_id}/address/shipping?authtoken=ba4604e8e433g9c892e360d53463oec5&organization_id=10234695 -H "Authorization: Zoho-authtoken ba4604e8e433g9c892e360d53463oec5" -H "Content-Type: application/json;charset=UTF-8" -d JSONString='{ "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
Shipping address of the customer
city
Optional
City of the contact's shipping address
state
Optional
State of the Contact's shipping address
zip
Optional
ZIP code of the contact's shipping address
country
Optional
Contact's country for the given shipping address
fax
Optional
FAX number of the contact

List invoice templates

Get all invoice pdf templates.

Get /invoices/templates

Request Example

  
$ curl https://invoice.zoho.com/api/v3/invoices/templates?authtoken=ba4604e8e433g9c892e360d53463oec5&organization_id=10234695 -H "Authorization: Zoho-authtoken ba4604e8e433g9c892e360d53463oec5" -H "Content-Type: application/json;charset=UTF-8"

Response Example

  
HTTP/1.1 200 OK Content-Type:application/json;charset=UTF-8 { "code": 0, "message": "success", "templates": [ { "template_name": "Service - Classic", "template_id": 982000000000143, "template_type": "classic" }, {...}, {...} ] }

Update invoice template

Update the pdf template associated with the invoice.

PUT /invoices/{invoice_id}/templates/{template_id}

Request Example

  
$ curl https://invoice.zoho.com/api/v3/invoices/{invoice_id}/templates/{template_id}?authtoken=ba4604e8e433g9c892e360d53463oec5&organization_id=10234695 -H "Authorization: Zoho-authtoken ba4604e8e433g9c892e360d53463oec5" -H "Content-Type: application/json;charset=UTF-8"

Response Example

  
HTTP/1.1 200 OK Content-Type:application/json;charset=UTF-8 { "code": 0, "message": "Invoice information has been updated." }

List invoice payments

Get the list of payments made for an invoice.

GET /invoices/{invoice_id}/payments

Request Example

  
$ curl https://invoice.zoho.com/api/v3/invoices/{invoice_id}/payments?authtoken=ba4604e8e433g9c892e360d53463oec5&organization_id=10234695 -H "Authorization: Zoho-authtoken ba4604e8e433g9c892e360d53463oec5" -H "Content-Type: application/json;charset=UTF-8"

Response Example

  
HTTP/1.1 200 OK Content-Type:application/json;charset=UTF-8 { "code": 0, "message": "success", "payments": [ { "payment_id": 982000000567190, "payment_number": 7, "invoice_id": 982000000567114, "invoice_payment_id": 982000000567192, "payment_mode": "cash", "description": "500GB, USB 2.0 interface 1400 rpm, protective hard case.", "date": "2013-11-17", "reference_number": " ", "exchange_rate": 1, "amount": 10.57, "tax_amount_withheld": 0, "online_transaction_id": "", "is_single_invoice_payment": true }, {...}, {...} ] }

List credits applied

Get the list of credits applied for an invoice.

GET /invoices/{invoice_id}/creditsapplied

Request Example

  
$ curl https://invoice.zoho.com/api/v3/invoices/{invoice_id}/creditsapplied?authtoken=ba4604e8e433g9c892e360d53463oec5&organization_id=10234695 -H "Authorization: Zoho-authtoken ba4604e8e433g9c892e360d53463oec5" -H "Content-Type: application/json;charset=UTF-8"

Response Example

  
HTTP/1.1 200 OK Content-Type:application/json;charset=UTF-8 { "code": 0, "message": "success", "credits": [ { "creditnote_id": 982000000567134, "creditnotes_invoice_id": "982000000567172", "creditnotes_number": "CN-00001", "credited_date": "2013-11-18", "amount_applied": 12.2 }, {...}, {...} ] }

Apply credits

Apply the customer credits either from credit notes or excess customer payments to an invoice. Multiple credits can be applied at once.

POST /invoices/{invoice_id}/credits

Request Example

  
$ curl https://invoice.zoho.com/api/v3/invoices/{invoice_id}/credits?authtoken=ba4604e8e433g9c892e360d53463oec5&organization_id=10234695 -H "Authorization: Zoho-authtoken ba4604e8e433g9c892e360d53463oec5" -H "Content-Type: application/json;charset=UTF-8" -d JSONString='{ "invoice_payments": [ { "payment_id": 982000000567190, "amount_applied": 12.2 } ], "apply_creditnotes": [ { "creditnote_id": 982000000567134, "amount_applied": 12.2 } ] }'

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
Invoice payment list
payment_id
Optional
The ID of the payment
amount_applied
Optional
The amount applied to a creditnote
apply_creditnotes
Optional
Apply existing credit note of a customer against the invoice
creditnote_id
Optional
The ID of creditnote
amount_applied
Optional
The amount applied to a creditnote

Delete a payment

Delete a payment made to an invoice.

DELETE /invoices/{invoice_id}/payments/{invoice_payment_id}

Request Example

  
$ curl https://invoice.zoho.com/api/v3/invoices/{invoice_id}/payments/{invoice_payment_id}?authtoken=ba4604e8e433g9c892e360d53463oec5&organization_id=10234695 -H "Authorization: Zoho-authtoken ba4604e8e433g9c892e360d53463oec5" -H "Content-Type: application/json;charset=UTF-8"

Response Example

  
HTTP/1.1 200 OK Content-Type:application/json;charset=UTF-8 { "code": 0, "message": "The payment has been deleted." }

Delete applied credit

Delete a particular credit applied to an invoice.

DELETE /invoices/{invoice_id}/creditsapplied/{creditnotes_invoice_id}

Request Example

  
$ curl https://invoice.zoho.com/api/v3/invoices/{invoice_id}/creditsapplied/{creditnotes_invoice_id}?authtoken=ba4604e8e433g9c892e360d53463oec5&organization_id=10234695 -H "Authorization: Zoho-authtoken ba4604e8e433g9c892e360d53463oec5" -H "Content-Type: application/json;charset=UTF-8"

Response Example

  
HTTP/1.1 200 OK Content-Type:application/json;charset=UTF-8 { "code": 0, "message": "Credits applied to an invoice have been deleted." }

Get an invoice attachment

Returns the file attached to the invoice.

GET /invoices/{invoice_id}/attachment

Request Example

  
$ curl https://invoice.zoho.com/api/v3/invoices/{invoice_id}/attachment?authtoken=ba4604e8e433g9c892e360d53463oec5&organization_id=10234695 -H "Authorization: Zoho-authtoken ba4604e8e433g9c892e360d53463oec5" -H "Content-Type: application/json;charset=UTF-8"

Response Example

  
HTTP/1.1 200 OK Content-Type:application/json;charset=UTF-8 { "code": 0, "message": "success" }

Query Params

preview
Optional
Get the thumbnail of the attachment.

Add attachment to an invoice

Attach a file to an invoice.

POST /invoices/{invoice_id}/attachment

Request Example

  
$ curl https://invoice.zoho.com/api/v3 /invoices/{invoice_id}/attachment?authtoken=ba4604e8e433g9c892e360d53463oec5&organization_id=10234695 -H "Authorization: Zoho-authtoken ba4604e8e433g9c892e360d53463oec5" -H "Content-Type: application/json;charset=UTF-8"

Response Example

  
HTTP/1.1 200 OK Content-Type:application/json;charset=UTF-8 { "code": 0, "message": "Your file has been successfully attached to the invoice." }

Query Params

can_send_in_mail
Optional
True to send the attachment with the invoice when emailed.
attachment
Optional
The file to be attached.Allowed Extensions: gif, png, jpeg, jpg, bmp and pdf

Update attachment preference

Set whether you want to send the attached file while emailing the invoice.

PUT /invoices/{invoice_id}/attachment

Request Example

  
$ curl https://invoice.zoho.com/api/v3 /invoices/{invoice_id}/attachment?authtoken=ba4604e8e433g9c892e360d53463oec5&organization_id=10234695 -H "Authorization: Zoho-authtoken ba4604e8e433g9c892e360d53463oec5" -H "Content-Type: application/json;charset=UTF-8"

Response Example

  
HTTP/1.1 200 OK Content-Type:application/json;charset=UTF-8 { "code": 0, "message": "Invoice information has been updated." }

Query Params

can_send_in_mail
Required
Boolean to send the attachment with the invoice when emailed.

Delete an attachment

Delete the file attached to the invoice.

DELETE /invoices/{invoice_id}/attachment

Request Example

  
$ curl https://invoice.zoho.com/api/v3/invoices/{invoice_id}/attachment?authtoken=ba4604e8e433g9c892e360d53463oec5&organization_id=10234695 -H "Authorization: Zoho-authtoken ba4604e8e433g9c892e360d53463oec5" -H "Content-Type: application/json;charset=UTF-8"

Response Example

  
HTTP/1.1 200 OK Content-Type:application/json;charset=UTF-8 { "code": 0, "message": "Your file is no longer attached to the invoice." }

Delete the expense receipt

Delete the expense receipts attached to an invoice which is raised from an expense.

DELETE /invoices/expenses/{expense_id}/receipt

Request Example

  
$ curl https://invoice.zoho.com/api/v3 /invoices/expenses/{expense_id}/receipt?authtoken=ba4604e8e433g9c892e360d53463oec5&organization_id=10234695 -H "Authorization: Zoho-authtoken ba4604e8e433g9c892e360d53463oec5" -H "Content-Type: application/json;charset=UTF-8"

Response Example

  
HTTP/1.1 200 OK Content-Type:application/json;charset=UTF-8 { "code": 0, "message": "The attached expense receipt has been deleted." }

List invoice comments & history

Get the complete history and comments of an invoice.

GET /invoices/{invoice_id}/comments

Request Example

  
$ curl https://invoice.zoho.com/api/v3 /invoices/{invoice_id}/comments?authtoken=ba4604e8e433g9c892e360d53463oec5&organization_id=10234695 -H "Authorization: Zoho-authtoken ba4604e8e433g9c892e360d53463oec5" -H "Content-Type: application/json;charset=UTF-8"

Response Example

  
HTTP/1.1 200 OK Content-Type:application/json;charset=UTF-8 { "code": 0, "message": "success", "comments": [ { "comment_id": 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://invoice.zoho.com/api/v3/invoices/{invoice_id}/comments?authtoken=ba4604e8e433g9c892e360d53463oec5&organization_id=10234695 -H "Authorization: Zoho-authtoken ba4604e8e433g9c892e360d53463oec5" -H "Content-Type: application/json;charset=UTF-8"

Response Example

  
HTTP/1.1 200 OK Content-Type:application/json;charset=UTF-8 { "code": 0, "message": "Comments added." }

Query Params

description
Optional
A short note added
payment_expected_date
Optional
Expected date pf 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://invoice.zoho.com/api/v3/invoices/{invoice_id}/comments/{comment_id}?authtoken=ba4604e8e433g9c892e360d53463oec5&organization_id=10234695 -H "Authorization: Zoho-authtoken ba4604e8e433g9c892e360d53463oec5" -H "Content-Type: application/json;charset=UTF-8"

Response Example

  
HTTP/1.1 200 OK Content-Type:application/json;charset=UTF-8 { "code": 0, "message": "success", "comment_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://invoice.zoho.com/api/v3/invoices/{invoice_id}/comments/{comment_id}?authtoken=ba4604e8e433g9c892e360d53463oec5&organization_id=10234695 -H "Authorization: Zoho-authtoken ba4604e8e433g9c892e360d53463oec5" -H "Content-Type: application/json;charset=UTF-8"

Response Example

  
HTTP/1.1 200 OK Content-Type:application/json;charset=UTF-8 { "code": 0, "message": "The comment has been deleted." }

Recurring Invoices

Recurring Invoices are created in order to send invoice in a predefined time interval.

Example

{ "recurring_invoice_id": "90300000072369", "recurrence_name": "MonthlyInvoice", "line_items": [ { "item_id": "90300000081501", "name": "Hard Drive", "description": "10 GB Space, 300 GB Transfer 100 Email Accounts 10 MySQL Databases", "rate": 100, "quantity": 1, "discount": 10, "tax_id": "903000000000356", "item_total": 100 } ], "customer_name": "David Sujin", "customer_id": "903000000000099", "date": "2016-06-05", "start_date": "2016-06-12", "end_date": "2017-10-12", "last_sent_date": "2016-07-12", "next_invoice_date": "2016-08-17", "recurrence_frequency": "weeks", "repeat_every": 2, "status": "active", "email": "benjamin.george@bowmanfurniture.com", "item_id": "90300000081501", "description": "10 GB Space, 300 GB Transfer 100 Email Accounts 10 MySQL Databases", "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-09T02:30:08-0700", "contact_persons": [ "903000006532" ], "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": "10 GB Space, 300 GB Transfer 100 Email Accounts 10 MySQL Databases", "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. Maximum length [100]
list
Line items of an invoice.
item_id
string
Unique string generated for the item for which invoice is to be sent.
name
string
The name of the line item. Maximum length [100]
rate
double
The amount of the item
quantity
required
Quantity of the item included.
discount
string
The discount given for an item.
tax_id
string
Unique to denote the tax associate to the recurring invoice.
item_total
double
Total rate raised by this item. This would be the multiplicative product of item price and quantity.
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. Maximum 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
Items which are charged on a recurring basis
item_id
string
Unique string generated for the item for which invoice is to be sent.
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://invoice.zoho.com/api/v3/recurringinvoices?authtoken=ba4604e8e433g9c892e360d53463oec5&organization_id=10234695 -H "Authorization: Zoho-authtoken ba4604e8e433g9c892e360d53463oec5" -H "Content-Type: application/json;charset=UTF-8" -d JSONString='{ "recurrence_name": "MonthlyInvoice", "reference_number": "12314", "customer_id": "903000000000099", "contact_persons": [ "903000006532" ], "start_date": "2016-06-12", "end_date": "2017-10-12", "place_of_supply": "TN", "gst_treatment": "business_gst", "gst_no": "22AAAAA0000A1Z5", "recurrence_frequency": "weeks", "repeat_every": 2, "line_items": [ { "item_id": "90300000081501", "name": "Hard Drive", "description": "10 GB Space, 300 GB Transfer 100 Email Accounts 10 MySQL Databases", "rate": 100, "quantity": 1, "discount": 10, "tax_id": "903000000000356", "tax_exemption_id": "903000006345", "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 201 Created Content-Type:application/json;charset=UTF-8 { "code": 0, "message": "The recurring invoice has been created.", "recurring_invoice": { "recurring_invoice_id": "90300000072369", "recurrence_name": "MonthlyInvoice", "reference_number": "12314", "is_pre_gst": false, "gst_no": "22AAAAA0000A1Z5", "gst_treatment": "business_gst", "place_of_supply": "TN", "customer_name": "David Sujin", "customer_id": "903000000000099", "currency_id": "982000000000190", "currency_code": "USD", "start_date": "2016-06-12", "end_date": "2017-10-12", "last_sent_date": "2016-07-12", "next_invoice_date": "2016-08-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. Maximum 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.
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.
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.
item_id
Optional
Unique string generated for the item for which invoice is to be sent.
name
Optional
The name of the line item. Maximum length [100]
rate
Optional
The amount of the item
quantity
Optional
Quantity of the item included.
discount
Optional
The discount given for an item.
tax_id
Optional
Unique to denote the tax associate to the recurring invoice.
tax_exemption_id
India, US and CA edition Only
Optional
Unique ID of the tax exemption.
avatax_tax_code
Avalara integration only
Optional
A tax code is a unique label used to group Items (products, services, or charges) together. Maximum length [25]
avatax_use_code
Avalara integration only
Optional
Used to group like customers for exemption purposes. It is a custom value that links customers to a tax rule. Select from Avalara [standard codes][1] or enter a custom code. Maximum 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 and CA 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
India, US and CA edition 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. Maximum length [25]
avatax_exempt_no
Avalara integration only
Optional
Exemption certificate number of the customer. Maximum length [25]

Update Recurring Invoice

Update the recurring invoice.

PUT /recurringinvoices/{recurring_invoice_id}

Request Example

  
$ curl https://invoice.zoho.com/api/v3/recurringinvoices/{recurring_invoice_id}?authtoken=ba4604e8e433g9c892e360d53463oec5&organization_id=10234695 -H "Authorization: Zoho-authtoken ba4604e8e433g9c892e360d53463oec5" -H "Content-Type: application/json;charset=UTF-8" -d JSONString='{ "recurrence_name": "MonthlyInvoice", "reference_number": "12314", "customer_id": "903000000000099", "contact_persons": [ "903000006532" ], "start_date": "2016-06-12", "end_date": "2017-10-12", "place_of_supply": "TN", "gst_treatment": "business_gst", "gst_no": "22AAAAA0000A1Z5", "recurrence_frequency": "weeks", "repeat_every": 2, "line_items": [ { "item_id": "90300000081501", "name": "Hard Drive", "description": "10 GB Space, 300 GB Transfer 100 Email Accounts 10 MySQL Databases", "rate": 100, "quantity": 1, "discount": 10, "tax_id": "903000000000356", "tax_exemption_id": "903000006345", "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", "is_pre_gst": false, "gst_no": "22AAAAA0000A1Z5", "gst_treatment": "business_gst", "place_of_supply": "TN", "customer_name": "David Sujin", "customer_id": "903000000000099", "currency_id": "982000000000190", "currency_code": "USD", "start_date": "2016-06-12", "end_date": "2017-10-12", "last_sent_date": "2016-07-12", "next_invoice_date": "2016-08-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. Maximum 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.
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.
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.
item_id
Optional
Unique string generated for the item for which invoice is to be sent.
name
Optional
The name of the line item. Maximum length [100]
rate
Optional
The amount of the item
quantity
Optional
Quantity of the item included.
discount
Optional
The discount given for an item.
tax_id
Optional
Unique to denote the tax associate to the recurring invoice.
tax_exemption_id
India, US and CA edition Only
Optional
Unique ID of the tax exemption.
avatax_tax_code
Avalara integration only
Optional
A tax code is a unique label used to group Items (products, services, or charges) together. Maximum length [25]
avatax_use_code
Avalara integration only
Optional
Used to group like customers for exemption purposes. It is a custom value that links customers to a tax rule. Select from Avalara [standard codes][1] or enter a custom code. Maximum 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 and CA 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
India, US and CA edition 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. Maximum length [25]
avatax_exempt_no
Avalara integration only
Optional
Exemption certificate number of the customer. Maximum length [25]

Get a Recurring Invoice

Get the details of a recurring invoice.

GET /recurringinvoices/{recurring_invoice_id}

Request Example

  
$ curl https://invoice.zoho.com/api/v3/recurringinvoices/{recurring_invoice_id}?authtoken=ba4604e8e433g9c892e360d53463oec5&organization_id=10234695 -H "Authorization: Zoho-authtoken ba4604e8e433g9c892e360d53463oec5" -H "Content-Type: application/json;charset=UTF-8"

Response Example

  
HTTP/1.1 200 OK Content-Type:application/json;charset=UTF-8 { "code": 0, "message": "Details of a recurring invoice is displayed successfully.", "recurring_invoice": { "recurring_invoice_id": "90300000072369", "recurrence_name": "MonthlyInvoice", "reference_number": "12314", "customer_name": "David Sujin", "customer_id": "903000000000099", "is_pre_gst": false, "gst_no": "22AAAAA0000A1Z5", "gst_treatment": "business_gst", "place_of_supply": "TN", "company_name": "ABC Studios", "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-10-12", "last_sent_date": "2016-07-12", "next_invoice_date": "2016-08-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" } } }

List Recurring Invoice

List the details of all recurring invoice.

GET /recurringinvoices

Request Example

  
$ curl https://invoice.zoho.com/api/v3/recurringinvoices?authtoken=ba4604e8e433g9c892e360d53463oec5&organization_id=10234695 -H "Authorization: Zoho-authtoken ba4604e8e433g9c892e360d53463oec5" -H "Content-Type: application/json;charset=UTF-8"

Response Example

  
HTTP/1.1 200 OK Content-Type:application/json;charset=UTF-8 { "code": 0, "message": "Details of a recurring invoice is displayed successfully.", "recurring_invoices": [ { "recurring_invoice_id": "90300000072369", "recurrence_name": "MonthlyInvoice", "customer_name": "David Sujin", "customer_id": "903000000000099", "currency_id": "982000000000190", "currency_code": "USD", "start_date": "2016-06-12", "end_date": "2017-10-12", "last_sent_date": "2016-07-12", "next_invoice_date": "2016-08-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" } }, {...}, {...} ] }

Query Params

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.Maximum length [100]
sort_column
Optional
Sort based on column value

Delete a Recurring Invoice

Delete an existing recurring invoice.

DELETE /recurringinvoices/{recurring_invoice_id}

Request Example

  
$ curl https://invoice.zoho.com/api/v3/recurringinvoices/{recurring_invoice_id}?authtoken=ba4604e8e433g9c892e360d53463oec5&organization_id=10234695 -H "Authorization: Zoho-authtoken ba4604e8e433g9c892e360d53463oec5" -H "Content-Type: application/json;charset=UTF-8" -d JSONString='{ "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." }

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://invoice.zoho.com/api/v3/recurringinvoices/{recurring_invoice_id}/status/stop?authtoken=ba4604e8e433g9c892e360d53463oec5&organization_id=10234695 -H "Authorization: Zoho-authtoken ba4604e8e433g9c892e360d53463oec5" -H "Content-Type: application/json;charset=UTF-8" -d JSONString='{ "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." }

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://invoice.zoho.com/api/v3/recurringinvoices/{recurring_invoice_id}/status/resume?authtoken=ba4604e8e433g9c892e360d53463oec5&organization_id=10234695 -H "Authorization: Zoho-authtoken ba4604e8e433g9c892e360d53463oec5" -H "Content-Type: application/json;charset=UTF-8" -d JSONString='{ "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." }

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://invoice.zoho.com/api/v3/recurringinvoices/{recurring_invoice_id}/templates/{template_id}?authtoken=ba4604e8e433g9c892e360d53463oec5&organization_id=10234695 -H "Authorization: Zoho-authtoken ba4604e8e433g9c892e360d53463oec5" -H "Content-Type: application/json;charset=UTF-8" -d JSONString='{ "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." }

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://invoice.zoho.com/api/v3/recurringinvoices/{recurring_invoice_id}/comments?authtoken=ba4604e8e433g9c892e360d53463oec5&organization_id=10234695 -H "Authorization: Zoho-authtoken ba4604e8e433g9c892e360d53463oec5" -H "Content-Type: application/json;charset=UTF-8" -d JSONString='{ "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.", "comments": [ { "comment_id": "982000000567019", "recurring_invoice_id": "90300000072369", "comment_description": "Recurring Invoice created", "commented_by_id": "982000000554041", "commented_by": "David Sujin", "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.

Customer Payments

A payment object describes details regarding a particular customer payment. There can be multiple payments for a single invoice. Multiple invoices can be paid in a single payment as well.

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. Maximum length allowed [2000]
payment_mode
string
Mode through which payment is made. This can be check, cash, creditcard, banktransfer, bankremittance, autotransaction or others. Maximum length [100]
amount
double
Amount paid in the respective payment.
amount_refunded
double
Amount that is refunded. 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. Date 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. Maximum length of the reference number [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. Maximum 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. Date 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://invoice.zoho.com/api/v3/customerpayments?authtoken=ba4604e8e433g9c892e360d53463oec5&organization_id=10234695 -H "Authorization: Zoho-authtoken ba4604e8e433g9c892e360d53463oec5" -H "Content-Type: application/json;charset=UTF-8" -d JSONString='{ "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 } ] }'

Response Example

  
HTTP/1.1 201 Created Content-Type:application/json;charset=UTF-8 { "code": 0, "message": "The payment has been created.", "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. Maximum length [100]
amount
Required
Amount paid in the respective payment.
date
Required
Date on which payment is made. Date 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. Maximum length of the reference number [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
Required
Invoice ID of the required invoice.
amount_applied
Required
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.

Update a payment

Update an existing payment information.

PUT /customerpayments/{payment_id}

Request Example

  
$ curl https://invoice.zoho.com/api/v3/customerpayments/{payment_id}?authtoken=ba4604e8e433g9c892e360d53463oec5&organization_id=10234695 -H "Authorization: Zoho-authtoken ba4604e8e433g9c892e360d53463oec5" -H "Content-Type: application/json;charset=UTF-8" -d JSONString='{ "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 } ] }'

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_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. Maximum length [100]
amount
Required
Amount paid in the respective payment.
date
Required
Date on which payment is made. Date 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. Maximum length of the reference number [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
Required
Invoice ID of the required invoice.
amount_applied
Required
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.

Retrieve a payment

Details of an existing payment.

GET /customerpayments/{payment_id}

Request Example

  
$ curl https://invoice.zoho.com/api/v3/customerpayments/{payment_id}?authtoken=ba4604e8e433g9c892e360d53463oec5&organization_id=10234695 -H "Authorization: Zoho-authtoken ba4604e8e433g9c892e360d53463oec5" -H "Content-Type: application/json;charset=UTF-8"

Response Example

  
HTTP/1.1 200 OK Content-Type:application/json;charset=UTF-8 { "code": 0, "message": "success", "payment": { "payment_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", "online_transaction_id": "", "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://invoice.zoho.com/api/v3/customerpayments?authtoken=ba4604e8e433g9c892e360d53463oec5&organization_id=10234695 -H "Authorization: Zoho-authtoken ba4604e8e433g9c892e360d53463oec5" -H "Content-Type: application/json;charset=UTF-8"

Response Example

  
HTTP/1.1 200 OK Content-Type:application/json;charset=UTF-8 { "code": 0, "message": "success", "customerpayments": [ { "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. Maximum length [100]
reference_number
Optional
Search payments by reference number. Variants: reference_number_startswith and reference_number_contains. Maximum length [100]
date
Optional
Date on which payment is made. Date 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
Sort based on selected column
search_text
Optional
Search payments by reference number or customer name or payment description. Maximum length [100]

Delete a payment

Delete an existing payment.

DELETE /customerpayments/{payment_id}

Request Example

  
$ curl https://invoice.zoho.com/api/v3/customerpayments/{payment_id}?authtoken=ba4604e8e433g9c892e360d53463oec5&organization_id=10234695 -H "Authorization: Zoho-authtoken ba4604e8e433g9c892e360d53463oec5" -H "Content-Type: application/json;charset=UTF-8"

Response Example

  
HTTP/1.1 200 OK Content-Type:application/json;charset=UTF-8 { "code": 0, "message": "The payment has been deleted." }

List refunds of a customer payment

List all the refunds pertaining to an existing customer payment.

GET /customerpayments/{customer_payment_id}/refunds

Request Example

  
$ curl https://invoice.zoho.com/api/v3/customerpayments/{customer_payment_id}/refunds?authtoken=ba4604e8e433g9c892e360d53463oec5&organization_id=10234695 -H "Authorization: Zoho-authtoken ba4604e8e433g9c892e360d53463oec5" -H "Content-Type: application/json;charset=UTF-8"

Response Example

  
HTTP/1.1 200 OK Content-Type:application/json;charset=UTF-8 { "code": 0, "message": "The list of refunds of the customer is displayed successfully.", "payment_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 }, {...}, {...} ] }

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://invoice.zoho.com/api/v3/customerpayments/{customer_payment_id}/refunds/{refund_id}?authtoken=ba4604e8e433g9c892e360d53463oec5&organization_id=10234695 -H "Authorization: Zoho-authtoken ba4604e8e433g9c892e360d53463oec5" -H "Content-Type: application/json;charset=UTF-8"

Response Example

  
HTTP/1.1 200 OK Content-Type:application/json;charset=UTF-8 { "code": 0, "message": "The details of the refund are displayed successfully.", "payment_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://invoice.zoho.com/api/v3/customerpayments/{customer_payment_id}/refunds?authtoken=ba4604e8e433g9c892e360d53463oec5&organization_id=10234695 -H "Authorization: Zoho-authtoken ba4604e8e433g9c892e360d53463oec5" -H "Content-Type: application/json;charset=UTF-8" -d JSONString='{ "date": "2016-06-05", "refund_mode": "cash", "reference_number": "INV-384", "amount": 450, "exchange_rate": 1, "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_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. Date Format [yyyy-mm-dd]
refund_mode
Optional
The method of refund. Maximum length [50]
reference_number
Optional
Reference number generated for the payment. A string of your choice can also be used as the reference number. Maximum length of the reference number [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.

Update a refund

Update the refunded transaction.

PUT /customerpayments/{customer_payment_id}/refunds/{refund_id}

Request Example

  
$ curl https://invoice.zoho.com/api/v3/customerpayments/{customer_payment_id}/refunds/{refund_id}?authtoken=ba4604e8e433g9c892e360d53463oec5&organization_id=10234695 -H "Authorization: Zoho-authtoken ba4604e8e433g9c892e360d53463oec5" -H "Content-Type: application/json;charset=UTF-8" -d JSONString='{ "date": "2016-06-05", "refund_mode": "cash", "reference_number": "INV-384", "amount": 450, "exchange_rate": 1, "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 has been saved.", "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. Date Format [yyyy-mm-dd]
refund_mode
Optional
The method of refund. Maximum length [50]
reference_number
Optional
Reference number generated for the payment. A string of your choice can also be used as the reference number. Maximum length of the reference number [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.

Delete a Refund

Delete refund pertaining to an existing customer payment.

DELETE /customerpayments/{customer_payment_id}/refunds/{refund_id}

Request Example

  
$ curl https://invoice.zoho.com/api/v3/customerpayments/{customer_payment_id}/refunds/{refund_id}?authtoken=ba4604e8e433g9c892e360d53463oec5&organization_id=10234695 -H "Authorization: Zoho-authtoken ba4604e8e433g9c892e360d53463oec5" -H "Content-Type: application/json;charset=UTF-8"

Response Example

  
HTTP/1.1 200 OK Content-Type:application/json;charset=UTF-8 { "code": 0, "message": "The refund has been deleted." }

Retainer Invoices

A retainer invoice is an advanced payment from a customer before we record any transaction with him.

Example

{ "retainerinvoice_id": 982000000567114, "customer_name": "Bowman & Co", "line_items": [ { "line_item_id": 982000000567021, "description": "500GB, USB 2.0 interface 1400 rpm, protective hard case.", "item_order": 1, "rate": 120, "bcy_rate": 120, "tax_id": 982000000557028, "tax_name": "VAT", "tax_type": "tax", "tax_percentage": 12.5, "item_total": 120 } ], "retainerinvoice_number": "RET-00003", "customer_id": 982000000567001, "status": "draft", "reference_number": " ", "project_or_estimate_name": "new project", "date": "2013-11-17", "currency_id": 982000000000190, "currency_code": "USD", "is_viewed_by_client": true, "client_viewed_time": true, "total": 40.6, "balance": 40.6, "created_time": "2013-11-17T02:31:51-0800", "last_modified_time": "2013-12-18T02:31:51-0800", "is_emailed": false, "last_payment_date": " ", "has_attachment": true }

Attribute

retainerinvoice_id
string
The id of the retainerinvoice
customer_name
string
The name of the customer. Maximum length [100]
list
Line items of an invoice.
line_item_id
string
The line item ID
item_order
integer
The order of the line item_order
rate
double
Rate of the line item.
bcy_rate
double
base currency rate
tax_id
string
ID of the tax or tax group applied to the estimate
tax_name
string
The name of the tax
tax_type
string
The type of the tax
tax_percentage
float
The percentage of tax levied
item_total
float
The total amount of the line items
retainerinvoice_number
string
number of the retainer invoice.
customer_id
string
ID of the customer the retainer invoice has to be created.
status
string
retainer invoice status.Allowed Values: sent, draft, overdue, paid, void, unpaid, partially_paid and viewed
reference_number
string
The reference number of the retainer invoice. Maximum length [100]
project_or_estimate_name
string
date
string
The date of creation of the retainer invoice.
currency_id
string
The currenct id of the currency
currency_code
string
The currency code in which the retainer invoice is created.
is_viewed_by_client
boolean
Boolean is retainer invoice viewed by client in client portal.
client_viewed_time
boolean
client viewed time for retainer invoice in client portal.
total
string
The total amount to be paid
balance
string
The unpaid amount
created_time
string
The time of creation of the retainer invoice
last_modified_time
string
The time of last modification of the retainer invoice
is_emailed
string
Boolean check to if the email was sent
last_payment_date
string
The last payment date of the retainer invoice
has_attachment
boolean
Boolean retainer invoice has attachment

Create a retainer invoice

Create a retainer invoice for your customer.

POST /retainerinvoices

Request Example

  
$ curl https://invoice.zoho.com/api/v3/retainerinvoices?authtoken=ba4604e8e433g9c892e360d53463oec5&organization_id=10234695 -H "Authorization: Zoho-authtoken ba4604e8e433g9c892e360d53463oec5" -H "Content-Type: application/json;charset=UTF-8" -d JSONString='{ "customer_id": 982000000567001, "reference_number": " ", "date": "2013-11-17", "contact_persons": [ "982000000567003", "982000000567003" ], "custom_fields": [ { "index": 1, "show_on_pdf": false, "value": "The value of the custom field", "label": "Delivery Date" } ], "notes": "Looking forward for your business.", "terms": "Terms & Conditions apply", "line_items": [ { "description": "500GB, USB 2.0 interface 1400 rpm, protective hard case.", "item_order": 1, "rate": 120 } ], "payment_options": { "payment_gateways": [ { "gateway_name": "paypal" } ] }, "template_id": 982000000000143, "place_of_supply": "TN" }'

Response Example

  
HTTP/1.1 200 OK Content-Type:application/json;charset=UTF-8 { "code": 0, "message": "The retainer invoice has been created.", "retainerinvoices": { "retainerinvoice_id": 982000000567114, "retainerinvoice_number": "RET-00003", "date": "2013-11-17", "status": "draft", "is_pre_gst": false, "place_of_supply": "TN", "project_id": 982000000567154, "last_payment_date": " ", "reference_number": " ", "customer_id": 982000000567001, "customer_name": "Bowman & Co", "contact_persons": [ "982000000567003", "982000000567003" ], "currency_id": 982000000000190, "currency_code": "USD", "currency_symbol": "USD", "exchange_rate": 1, "is_viewed_by_client": true, "client_viewed_time": true, "is_inclusive_tax": false, "line_items": [ { "line_item_id": 982000000567021, "description": "500GB, USB 2.0 interface 1400 rpm, protective hard case.", "item_order": 1, "rate": 120, "bcy_rate": 120, "tax_id": 982000000557028, "tax_name": "VAT", "tax_type": "tax", "tax_percentage": 12.5, "item_total": 120 } ], "sub_total": 153, "total": 40.6, "taxes": [ { "tax_name": "VAT", "tax_amount": 19.13 } ], "payment_made": 26.91, "payment_drawn": 26.91, "balance": 40.6, "allow_partial_payments": true, "price_precision": 2, "payment_options": { "payment_gateways": [ { "gateway_name": "paypal" } ] }, "is_emailed": false, "documents": [ {...} ], "billing_address": { "address": "Suite 125, McMillan Avenue", "street2": "McMillan Avenue", "city": "San Francisco", "state": "CA", "zip": 94134, "country": "U.S.A", "fax": "+86-10-82637827" }, "shipping_address": { "address": "Suite 125, McMillan Avenue", "street2": "McMillan Avenue", "city": "San Francisco", "state": "CA", "zip": 94134, "country": "U.S.A", "fax": "+86-10-82637827" }, "notes": "Looking forward for your business.", "terms": "Terms & Conditions apply", "custom_fields": [ { "index": 1, "show_on_pdf": false, "value": "The value of the custom field", "label": "Delivery Date" } ], "template_id": 982000000000143, "template_name": "Service - Classic", "page_width": "8.27in", "page_height": "11.69in", "orientation": "portrait", "template_type": "classic", "created_time": "2013-11-17T02:31:51-0800", "last_modified_time": "2013-12-18T02:31:51-0800", "created_by_id": 14909000000072000, "attachment_name": "new file", "can_send_in_mail": true, "invoice_url": "https://invoice.zoho.com/SecurePayment?CInvoiceID=23d84d0cf64f9a72ea0c66fded25a08c8bafd0ab508aff05323a9f80e2cd03fdc5dd568d3d6407bbda969d3e870d740b6fce549a9438c4ea" } }

ARGUMENTS

customer_id
Required
ID of the customer the retainer invoice has to be created.
reference_number
Optional
The reference number of the retainer invoice. Maximum length [100]
date
Optional
The date of creation of the retainer invoice.
contact_persons
Optional
The conatct persons associated with the contact.
custom_fields
Optional
Custom fields for a reatiner invoice.
index
Optional
The index of the custom field
show_on_pdf
Optional
Boolean value to check if the custom field is to be dispplayed on the pdf.
value
Optional
label
Optional
The label of the custom field.
notes
Optional
The notes added below expressing gratitude or for conveying some information.
terms
Optional
The terms added below expressing gratitude or for conveying some information.
Required
Line items of an invoice.
item_order
Optional
The order of the line item_order
rate
Optional
Rate of the line item.
payment_options
Optional
Payment options for the retainer invoice, online payment gateways and bank accounts. Will be displayed in the pdf.
payment_gateways
Optional
Online payment gateways through which payment can be made.
gateway_name
Optional
Name of the payment gateway associated with the retainer invoice. E.g. paypal, stripe.Allowed Values: paypal, authorize_net, payflow_pro, stripe, 2checkout and braintree
template_id
Optional
ID of the pdf template associated with the retainer invoice.
place_of_supply
India Edition only.
Optional
Place where the goods/services are supplied to. (If not given, place of contact given for the contact will be taken)

Query Params

ignore_auto_number_generation
Optional
Ignore auto invoice number generation for this invoice. This mandates the invoice number. Allowed values true and false

Update a retainer invoice

Update an existing invoice.

PUT /retainerinvoices/{retainerinvoice_id}

Request Example

  
$ curl https://invoice.zoho.com/api/v3/retainerinvoices/{retainerinvoice_id}?authtoken=ba4604e8e433g9c892e360d53463oec5&organization_id=10234695 -H "Authorization: Zoho-authtoken ba4604e8e433g9c892e360d53463oec5" -H "Content-Type: application/json;charset=UTF-8" -d JSONString='{ "customer_id": 982000000567001, "reference_number": " ", "date": "2013-11-17", "contact_persons": [ "982000000567003", "982000000567003" ], "custom_fields": [ { "index": 1, "show_on_pdf": false, "value": "The value of the custom field", "label": "Delivery Date" } ], "notes": "Looking forward for your business.", "terms": "Terms & Conditions apply", "line_items": [ { "description": "500GB, USB 2.0 interface 1400 rpm, protective hard case.", "item_order": 1, "rate": 120 } ], "payment_options": { "payment_gateways": [ { "gateway_name": "paypal" } ] }, "template_id": 982000000000143, "place_of_supply": "TN" }'

Response Example

  
HTTP/1.1 200 OK Content-Type:application/json;charset=UTF-8 { "code": 0, "message": "Retainer Invoice information has been updated.", "retainerinvoices": { "retainerinvoice_id": 982000000567114, "retainerinvoice_number": "RET-00003", "date": "2013-11-17", "status": "draft", "is_pre_gst": false, "place_of_supply": "TN", "project_id": 982000000567154, "last_payment_date": " ", "reference_number": " ", "customer_id": 982000000567001, "customer_name": "Bowman & Co", "contact_persons": [ "982000000567003", "982000000567003" ], "currency_id": 982000000000190, "currency_code": "USD", "currency_symbol": "USD", "exchange_rate": 1, "is_viewed_by_client": true, "client_viewed_time": true, "is_inclusive_tax": false, "line_items": [ { "line_item_id": 982000000567021, "description": "500GB, USB 2.0 interface 1400 rpm, protective hard case.", "item_order": 1, "rate": 120, "bcy_rate": 120, "tax_id": 982000000557028, "tax_name": "VAT", "tax_type": "tax", "tax_percentage": 12.5, "item_total": 120 } ], "sub_total": 153, "total": 40.6, "taxes": [ { "tax_name": "VAT", "tax_amount": 19.13 } ], "payment_made": 26.91, "payment_drawn": 26.91, "balance": 40.6, "allow_partial_payments": true, "price_precision": 2, "payment_options": { "payment_gateways": [ { "gateway_name": "paypal" } ] }, "is_emailed": false, "documents": [ {...} ], "billing_address": { "address": "Suite 125, McMillan Avenue", "street2": "McMillan Avenue", "city": "San Francisco", "state": "CA", "zip": 94134, "country": "U.S.A", "fax": "+86-10-82637827" }, "shipping_address": { "address": "Suite 125, McMillan Avenue", "street2": "McMillan Avenue", "city": "San Francisco", "state": "CA", "zip": 94134, "country": "U.S.A", "fax": "+86-10-82637827" }, "notes": "Looking forward for your business.", "terms": "Terms & Conditions apply", "custom_fields": [ { "index": 1, "show_on_pdf": false, "value": "The value of the custom field", "label": "Delivery Date" } ], "template_id": 982000000000143, "template_name": "Service - Classic", "page_width": "8.27in", "page_height": "11.69in", "orientation": "portrait", "template_type": "classic", "created_time": "2013-11-17T02:31:51-0800", "last_modified_time": "2013-12-18T02:31:51-0800", "created_by_id": 14909000000072000, "attachment_name": "new file", "can_send_in_mail": true, "invoice_url": "https://invoice.zoho.com/SecurePayment?CInvoiceID=23d84d0cf64f9a72ea0c66fded25a08c8bafd0ab508aff05323a9f80e2cd03fdc5dd568d3d6407bbda969d3e870d740b6fce549a9438c4ea" } }

ARGUMENTS

customer_id
Required
ID of the customer the retainer invoice has to be created.
reference_number
Optional
The reference number of the retainer invoice. Maximum length [100]
date
Optional
The date of creation of the retainer invoice.
contact_persons
Optional
The conatct persons associated with the contact.
custom_fields
Optional
Custom fields for a reatiner invoice.
index
Optional
The index of the custom field
show_on_pdf
Optional
Boolean value to check if the custom field is to be dispplayed on the pdf.
value
Optional
label
Optional
The label of the custom field.
notes
Optional
The notes added below expressing gratitude or for conveying some information.
terms
Optional
The terms added below expressing gratitude or for conveying some information.
Required
Line items of an invoice.
item_order
Optional
The order of the line item_order
rate
Optional
Rate of the line item.
payment_options
Optional
Payment options for the retainer invoice, online payment gateways and bank accounts. Will be displayed in the pdf.
payment_gateways
Optional
Online payment gateways through which payment can be made.
gateway_name
Optional
Name of the payment gateway associated with the retainer invoice. E.g. paypal, stripe.Allowed Values: paypal, authorize_net, payflow_pro, stripe, 2checkout and braintree
template_id
Optional
ID of the pdf template associated with the retainer invoice.
place_of_supply
India Edition only.
Optional
Place where the goods/services are supplied to. (If not given, place of contact given for the contact will be taken)

List Retainer invoices

List all retainer invoices with pagination.

GET /retainerinvoices

Request Example

  
$ curl https://invoice.zoho.com/api/v3/retainerinvoices?authtoken=ba4604e8e433g9c892e360d53463oec5&organization_id=10234695 -H "Authorization: Zoho-authtoken ba4604e8e433g9c892e360d53463oec5" -H "Content-Type: application/json;charset=UTF-8"

Response Example

  
HTTP/1.1 200 OK Content-Type:application/json;charset=UTF-8 { "code": 0, "message": "success", "retainerinvoices": [ { "retainerinvoice_id": 982000000567114, "customer_name": "Bowman & Co", "retainerinvoice_number": "RET-00003", "customer_id": 982000000567001, "status": "draft", "reference_number": " ", "project_or_estimate_name": "new project", "date": "2013-11-17", "currency_id": 982000000000190, "currency_code": "USD", "is_viewed_by_client": true, "client_viewed_time": true, "total": 40.6, "balance": 40.6, "created_time": "2013-11-17T02:31:51-0800", "last_modified_time": "2013-12-18T02:31:51-0800", "is_emailed": false, "last_payment_date": " ", "has_attachment": true }, {...}, {...} ] }

Query Params

print
Optional
Print the exported pdf.
sort_column
Optional
Sort retainer invoices.Allowed Values: customer_name, retainer invoice_number, date, due_date, total, balance and created_time
filter_by
Optional
Filter invoices by any status or payment expected date.Allowed Values: Status.All, Status.Sent, Status.Draft, Status.OverDue, Status.Paid, Status.Void, Status.Unpaid, Status.PartiallyPaid, Status.Viewed and Date.PaymentExpectedDate
sort_order
Optional
The order for sorting
page
Optional
Number of pages

Get a retainer invoice

Get the details of a retainer invoice.

GET /retainerinvoices/{retainerinvoice_id}

Request Example

  
$ curl https://invoice.zoho.com/api/v3/retainerinvoices/{retainerinvoice_id}?authtoken=ba4604e8e433g9c892e360d53463oec5&organization_id=10234695 -H "Authorization: Zoho-authtoken ba4604e8e433g9c892e360d53463oec5" -H "Content-Type: application/json;charset=UTF-8"

Response Example

  
HTTP/1.1 200 OK Content-Type:application/json;charset=UTF-8 { "code": 0, "message": "success", "retainerinvoice": { "retainerinvoice_id": 982000000567114, "retainerinvoice_number": "RET-00003", "date": "2013-11-17", "status": "draft", "is_pre_gst": false, "place_of_supply": "TN", "project_id": 982000000567154, "last_payment_date": " ", "reference_number": " ", "customer_id": 982000000567001, "customer_name": "Bowman & Co", "contact_persons": [ "982000000567003", "982000000567003" ], "currency_id": 982000000000190, "currency_code": "USD", "currency_symbol": "USD", "exchange_rate": 1, "is_viewed_by_client": true, "client_viewed_time": true, "is_inclusive_tax": false, "line_items": { "line_item_id": 982000000567021, "description": "500GB, USB 2.0 interface 1400 rpm, protective hard case.", "item_order": 1, "rate": 120, "bcy_rate": 120, "tax_id": 982000000557028, "tax_name": "VAT", "tax_type": "tax", "tax_percentage": 12.5, "item_total": 120 }, "sub_total": 153, "total": 40.6, "taxes": [ { "tax_name": "VAT", "tax_amount": 19.13 } ], "payment_made": 26.91, "payment_drawn": 26.91, "balance": 40.6, "allow_partial_payments": true, "price_precision": 2, "payment_options": { "payment_gateways": [ { "gateway_name": "paypal" } ] }, "is_emailed": false, "documents": [ {...} ], "billing_address": { "address": "Suite 125, McMillan Avenue", "street2": "McMillan Avenue", "city": "San Francisco", "state": "CA", "zip": 94134, "country": "U.S.A", "fax": "+86-10-82637827" }, "shipping_address": { "address": "Suite 125, McMillan Avenue", "street2": "McMillan Avenue", "city": "San Francisco", "state": "CA", "zip": 94134, "country": "U.S.A", "fax": "+86-10-82637827" }, "notes": "Looking forward for your business.", "terms": "Terms & Conditions apply", "custom_fields": [ { "index": 1, "show_on_pdf": false, "value": "The value of the custom field", "label": "Delivery Date" } ], "template_id": 982000000000143, "template_name": "Service - Classic", "page_width": "8.27in", "page_height": "11.69in", "orientation": "portrait", "template_type": "classic", "created_time": "2013-11-17T02:31:51-0800", "last_modified_time": "2013-12-18T02:31:51-0800", "created_by_id": 14909000000072000, "attachment_name": "new file", "can_send_in_mail": true, "invoice_url": "https://invoice.zoho.com/SecurePayment?CInvoiceID=23d84d0cf64f9a72ea0c66fded25a08c8bafd0ab508aff05323a9f80e2cd03fdc5dd568d3d6407bbda969d3e870d740b6fce549a9438c4ea" } }

Delete a retainer invoice

Delete an existing retainer invoice. Invoices which have payment or credits note applied cannot be deleted.

DELETE /retainerinvoices/{retainerinvoice_id}

Request Example

  
$ curl https://invoice.zoho.com/api/v3/retainerinvoices/{retainerinvoice_id}?authtoken=ba4604e8e433g9c892e360d53463oec5&organization_id=10234695 -H "Authorization: Zoho-authtoken ba4604e8e433g9c892e360d53463oec5" -H "Content-Type: application/json;charset=UTF-8"

Response Example

  
HTTP/1.1 200 OK Content-Type:application/json;charset=UTF-8 { "code": 0, "message": "The retainer invoice has been deleted." }

Mark a retainer invoice as sent

Mark a draft retainer invoice as sent.

POST /retainerinvoices/{retainerinvoice_id}/status/sent

Request Example

  
$ curl https://invoice.zoho.com/api/v3/retainerinvoices/{retainerinvoice_id}/status/sent?authtoken=ba4604e8e433g9c892e360d53463oec5&organization_id=10234695 -H "Authorization: Zoho-authtoken ba4604e8e433g9c892e360d53463oec5" -H "Content-Type: application/json;charset=UTF-8"

Response Example

  
HTTP/1.1 200 OK Content-Type:application/json;charset=UTF-8 { "code": 0, "message": "Retainer Invoice status has been changed to Sent." }

Update retainer invoice template

Update the pdf template associated with the retainer invoice.

PUT /retainerinvoices/{retainerinvoice_id}/templates/{template_id}

Request Example

  
$ curl https://invoice.zoho.com/api/v3/retainerinvoices/{retainerinvoice_id}/templates/{template_id}?authtoken=ba4604e8e433g9c892e360d53463oec5&organization_id=10234695 -H "Authorization: Zoho-authtoken ba4604e8e433g9c892e360d53463oec5" -H "Content-Type: application/json;charset=UTF-8"

Response Example

  
HTTP/1.1 200 OK Content-Type:application/json;charset=UTF-8 { "code": 0, "message": "Retainer Invoice information has been updated." }

Void a retainer invoice

Mark an invoice status as void. Upon voiding, the payments and credits associated with the retainer invoices will be unassociated and will be under customer credits.

POST /retainerinvoices/{retainerinvoice_id}/status/void

Request Example

  
$ curl https://invoice.zoho.com/api/v3/retainerinvoices/{retainerinvoice_id}/status/void?authtoken=ba4604e8e433g9c892e360d53463oec5&organization_id=10234695 -H "Authorization: Zoho-authtoken ba4604e8e433g9c892e360d53463oec5" -H "Content-Type: application/json;charset=UTF-8"

Response Example

  
HTTP/1.1 200 OK Content-Type:application/json;charset=UTF-8 { "code": 0, "message": "Retainer Invoice status has been changed to 'Void'." }

Mark as draft

Mark a voided retainer invoice as draft.

POST /retainerinvoices/{reatinerinvoice_id}/status/draft

Request Example

  
$ curl https://invoice.zoho.com/api/v3/retainerinvoices/{reatinerinvoice_id}/status/draft?authtoken=ba4604e8e433g9c892e360d53463oec5&organization_id=10234695 -H "Authorization: Zoho-authtoken ba4604e8e433g9c892e360d53463oec5" -H "Content-Type: application/json;charset=UTF-8"

Response Example

  
HTTP/1.1 200 OK Content-Type:application/json;charset=UTF-8 { "code": 0, "message": "Status of retainer invoice changed from void to draft." }

Email a retainer invoice

Email a retainer invoice to the customer. Input json string is not mandatory. If input json string is empty, mail will be send with default mail content.

POST /retainerinvoices/{retainerinvoice_id}/email

Request Example

  
$ curl https://invoice.zoho.com/api/v3/retainerinvoices/{retainerinvoice_id}/email?authtoken=ba4604e8e433g9c892e360d53463oec5&organization_id=10234695 -H "Authorization: Zoho-authtoken ba4604e8e433g9c892e360d53463oec5" -H "Content-Type: application/json;charset=UTF-8" -d JSONString='{ "send_from_org_email_id": false, "to_mail_ids": [ "willsmith@bowmanfurniture.com" ], "cc_mail_ids": [ "peterparker@bowmanfurniture.com" ], "subject": "Retainer Invoice from Zillium Inc (Retainer Invoice#: RET-00001)", "body": "Dear Customer, <br><br><br><br>Thanks for your business. <br><br><br><br>The retainer invoice RET-00001 is attached with this email. You can choose the easy way out and <a href= https://invoice.zoho.com/SecurePayment?CInvoiceID=b9800228e011ae86abe71227bdacb3c68e1af685f647dcaed747812e0b9314635e55ac6223925675b371fcbd2d5ae3dc >pay online for this invoice.</a> <br><br>Here's an overview of the invoice for your reference. <br><br><br><br>Invoice Overview: <br><br>Invoice : INV-00001 <br><br>Date : 05 Aug 2013 <br><br>Amount : $541.82 <br><br><br><br>It was great working with you. Looking forward to working with you again.<br><br><br>\\nRegards<br>\\nZillium Inc<br>\\n\"," }'

Response Example

  
HTTP/1.1 200 OK Content-Type:application/json;charset=UTF-8 { "code": 0, "message": "Your retainer invoice has been sent." }

ARGUMENTS

send_from_org_email_id
Optional
Boolean to trigger the email from the organization's email address
to_mail_ids
Required
Array of email address of the recipients.
cc_mail_ids
Optional
Array of email address of the recipients to be CC'd.
subject
Optional
The subject of the mail
body
Optional
The body of the mail

Query Params

send_customer_statement
Optional
Send customer statement pdf a with email.
send_attachment
Optional
Send the retainer invoice attachment a with the email.
attachments
Optional
Files to be attached to the email

Get retainer invoice email content

Get the email content of a retainer invoice.

GET /retainerinvoices/{retainerinvoice_id}/email

Request Example

  
$ curl https://invoice.zoho.com/api/v3/retainerinvoices/{retainerinvoice_id}/email?authtoken=ba4604e8e433g9c892e360d53463oec5&organization_id=10234695 -H "Authorization: Zoho-authtoken ba4604e8e433g9c892e360d53463oec5" -H "Content-Type: application/json;charset=UTF-8" -d JSONString='{}'

Response Example

  
HTTP/1.1 200 OK Content-Type:application/json;charset=UTF-8 { "code": 0, "message": "success", "gateways_configured": true, "deprecated_placeholders_used": [ {...} ], "body": "Dear Customer, <br><br><br><br>Thanks for your business. <br><br><br><br>The retainer invoice RET-00001 is attached with this email. You can choose the easy way out and <a href= https://invoice.zoho.com/SecurePayment?CInvoiceID=b9800228e011ae86abe71227bdacb3c68e1af685f647dcaed747812e0b9314635e55ac6223925675b371fcbd2d5ae3dc >pay online for this invoice.</a> <br><br>Here's an overview of the invoice for your reference. <br><br><br><br>Invoice Overview: <br><br>Invoice : INV-00001 <br><br>Date : 05 Aug 2013 <br><br>Amount : $541.82 <br><br><br><br>It was great working with you. Looking forward to working with you again.<br><br><br>\\nRegards<br>\\nZillium Inc<br>\\n\",", "error_list": [ {...} ], "subject": "Retainer Invoice from Zillium Inc (Retainer Invoice#: RET-00001)", "to_contacts": [ { "first_name": "Will", "selected": false, "phone": "+1-925-921-9201", "email": "willsmith@bowmanfurniture.com", "last_name": "Smith", "salutation": "Mr", "contact_person_id": 982000000567003, "mobile": "+1-4054439562" } ], "attachment_name": "new file", "file_name": "RET-00001.pdf", "from_emails": [ { "user_name": [ {...} ], "selected": false, "email": "willsmith@bowmanfurniture.com" } ], "customer_id": 982000000567001 }

ARGUMENTS

email_template_id
Optional
Get the email content based on a specific email template. If this param is not inputted, then the content will be based on the email template associated with the customer. If no template is associated with the customer, then default template will be used.

Update billing address

Updates the billing address for this retainer invoice alone.

PUT /retainerinvoices/{retainerinvoice_id}/address/billing

Request Example

  
$ curl https://invoice.zoho.com/api/v3/retainerinvoices/{retainerinvoice_id}/address/billing?authtoken=ba4604e8e433g9c892e360d53463oec5&organization_id=10234695 -H "Authorization: Zoho-authtoken ba4604e8e433g9c892e360d53463oec5" -H "Content-Type: application/json;charset=UTF-8" -d JSONString='{ "address": "B-1104, 11F, \nHorizon International Tower, \nNo. 6, ZhiChun Road, HaiDian District", "city": "Beijing", "state": "Beijing", "zip": 1000881, "fax": "+86-10-82637827" }'

Response Example

  
HTTP/1.1 200 OK Content-Type:application/json;charset=UTF-8 { "code": 0, "message": "Billing address updated" }

ARGUMENTS

address
Optional
address of the customer
city
Optional
city of the customer
state
Optional
state of the customer
zip
Optional
zip of the customer
country
Optional
country of the customer
fax
Optional
fax of the customer

List retainer invoice templates

Get all retainer invoice pdf templates.

Get /retainerinvoices/templates

Request Example

  
$ curl https://invoice.zoho.com/api/v3/retainerinvoices/templates?authtoken=ba4604e8e433g9c892e360d53463oec5&organization_id=10234695 -H "Authorization: Zoho-authtoken ba4604e8e433g9c892e360d53463oec5" -H "Content-Type: application/json;charset=UTF-8"

Response Example

  
HTTP/1.1 200 OK Content-Type:application/json;charset=UTF-8 { "code": 0, "message": "success", "templates": [ { "template_name": "Service - Classic", "template_id": 982000000000143, "template_type": "classic" }, {...}, {...} ] }

List retainer payments

Get the list of payments made for a retainer invoices.

GET /customerpayments/{retainerinvoice_id}

Request Example

  
$ curl https://invoice.zoho.com/api/v3/customerpayments/{retainerinvoice_id}?authtoken=ba4604e8e433g9c892e360d53463oec5&organization_id=10234695 -H "Authorization: Zoho-authtoken ba4604e8e433g9c892e360d53463oec5" -H "Content-Type: application/json;charset=UTF-8"

Response Example

  
HTTP/1.1 200 OK Content-Type:application/json;charset=UTF-8 { "code": 0, "message": "success", "payments": [ { "payment_id": "982000000567190", "documents": [ {...} ], "customer_id": 982000000567001, "customer_name": "Bowman & Co", "retainerinvoice_id": 982000000567114, "payment_mode": "cash", "date": "2013-11-17", "currency_id": 982000000000190, "currency_code": "USD", "exchange_rate": 1, "amount": 100, "unused_amount": 100, "bank_charges": 20, "is_client_review_settings_enabled": true, "tax_amount_withheld": 10, "discount_amount": 10, "description": "500GB, USB 2.0 interface 1400 rpm, protective hard case.", "reference_number": " ", "online_transaction_id": "7843653940324085", "invoices": [ {...} ], "retainerinvoice": { "retainerinvoice_id": 982000000567114, "retainerinvoice_number": "RET-00003", "retainerinvoice_total": 3478, "retainerinvoice_balance": 3478, "retainerinvoice_date": "2016-12-20" }, "payment_refunds": [ {...} ], "last_four_digits": "", "html_string": "", "template_id": 982000000000143, "template_name": "Service - Classic", "page_width": "8.27in", "page_height": "11.69in", "orientation": "portrait", "template_type": "classic", "attachment_name": "new file", "can_send_in_mail": true, "is_payment_drawn_details_required": true, "custom_fields": [ { "index": 1, "show_on_pdf": false, "value": "The value of the custom field", "label": "Delivery Date" } ] }, {...}, {...} ] }

Delete a retainer payment

Delete a payment made to a retainer invoice.

DELETE /customerpayments/{retainer_payment_id}

Request Example

  
$ curl https://invoice.zoho.com/api/v3/customerpayments/{retainer_payment_id}?authtoken=ba4604e8e433g9c892e360d53463oec5&organization_id=10234695 -H "Authorization: Zoho-authtoken ba4604e8e433g9c892e360d53463oec5" -H "Content-Type: application/json;charset=UTF-8"

Response Example

  
HTTP/1.1 200 OK Content-Type:application/json;charset=UTF-8 { "code": 0, "message": "The payment has been deleted." }

Get a retainer invoice attachment

Returns the file attached to the retainer invoice.

GET /retainerinvoices/{retainerinvoice_id}/attachment

Request Example

  
$ curl https://invoice.zoho.com/api/v3/retainerinvoices/{retainerinvoice_id}/attachment?authtoken=ba4604e8e433g9c892e360d53463oec5&organization_id=10234695 -H "Authorization: Zoho-authtoken ba4604e8e433g9c892e360d53463oec5" -H "Content-Type: application/json;charset=UTF-8" -d JSONString='{}'

Response Example

  
HTTP/1.1 200 OK Content-Type:application/json;charset=UTF-8 { "code": 0, "message": "success" }

ARGUMENTS

preview
Optional
Get the thumbnail of the attachment.

Add attachment to a retainer invoice

Attach a file to an invoice.

POST /retainerinvoices/{retainerinvoice_id}/attachment

Request Example

  
$ curl https://invoice.zoho.com/api/v3/retainerinvoices/{retainerinvoice_id}/attachment?authtoken=ba4604e8e433g9c892e360d53463oec5&organization_id=10234695 -H "Authorization: Zoho-authtoken ba4604e8e433g9c892e360d53463oec5" -H "Content-Type: application/json;charset=UTF-8" -d JSONString='{ "can_send_in_mail": true }'

Response Example

  
HTTP/1.1 200 OK Content-Type:application/json;charset=UTF-8 { "code": 0, "message": "Your file has been attached." }

ARGUMENTS

can_send_in_mail
Optional
Check if attachment can be sent via mail
attachment
Optional
The file to be attached. It has to be sent in multipart/formdata

Delete an attachment

Delete the file attached to the retainer invoice.

DELETE /retainerinvoices/{retainerinvoice_id}/documents/{document_id}

Request Example

  
$ curl https://invoice.zoho.com/api/v3/retainerinvoices/{retainerinvoice_id}/documents/{document_id}?authtoken=ba4604e8e433g9c892e360d53463oec5&organization_id=10234695 -H "Authorization: Zoho-authtoken ba4604e8e433g9c892e360d53463oec5" -H "Content-Type: application/json;charset=UTF-8"

Response Example

  
HTTP/1.1 200 OK Content-Type:application/json;charset=UTF-8 { "code": 0, "message": "Your file is no longer attached to the invoice." }

List retainer invoice comments & history

Get the complete history and comments of a retainer invoice.

GET /retainerinvoices/{retainernvoice_id}/comments

Request Example

  
$ curl https://invoice.zoho.com/api/v3 /retainerinvoices/{retainernvoice_id}/comments?authtoken=ba4604e8e433g9c892e360d53463oec5&organization_id=10234695 -H "Authorization: Zoho-authtoken ba4604e8e433g9c892e360d53463oec5" -H "Content-Type: application/json;charset=UTF-8"

Response Example

  
HTTP/1.1 200 OK Content-Type:application/json;charset=UTF-8 { "code": 0, "message": "success", "comments": [ { "comment_id": 982000000567019, "retainerinvoice_id": 982000000567114, "description": "500GB, USB 2.0 interface 1400 rpm, protective hard case.", "commented_by_id": 982000000554041, "commented_by": "John David", "comment_type": "system", "operation_type": "Added", "date": "2013-11-17", "date_description": "yesterday", "time": "2:38 AM", "transaction_id": "982000000567204", "transaction_type": "retainer_payment" }, {...}, {...} ] }

Add comment

Add a comment for a retainer invoice.

POST /retainerinvoices/{retainerinvoice_id}/comments

Request Example

  
$ curl https://invoice.zoho.com/api/v3/retainerinvoices/{retainerinvoice_id}/comments?authtoken=ba4604e8e433g9c892e360d53463oec5&organization_id=10234695 -H "Authorization: Zoho-authtoken ba4604e8e433g9c892e360d53463oec5" -H "Content-Type: application/json;charset=UTF-8" -d JSONString='{ "description": "comment added", "payment_expected_date": " ", "show_comment_to_clients": true }'

Response Example

  
HTTP/1.1 200 OK Content-Type:application/json;charset=UTF-8 { "code": 0, "message": "Comments added." }

ARGUMENTS

description
Optional
The description of the line items. Maximum length [2000]
payment_expected_date
Optional
Actual date when payment is expected to be cedited
show_comment_to_clients
Optional
Boolean to check if the comment to be shown to the clients

Delete a comment

Delete a retainer invoice comment.

DELETE /retainerinvoices/{retainerinvoice_id}/comments/{comment_id}

Request Example

  
$ curl https://invoice.zoho.com/api/v3/retainerinvoices/{retainerinvoice_id}/comments/{comment_id}?authtoken=ba4604e8e433g9c892e360d53463oec5&organization_id=10234695 -H "Authorization: Zoho-authtoken ba4604e8e433g9c892e360d53463oec5" -H "Content-Type: application/json;charset=UTF-8"

Response Example

  
HTTP/1.1 200 OK Content-Type:application/json;charset=UTF-8 { "code": 0, "message": "The comment has been deleted." }

Update comment

Update an existing comment of a retainer invoice.

PUT /retainerinvoices/{retainerinvoice_id}/comments/{comment_id}

Request Example

  
$ curl https://invoice.zoho.com/api/v3/retainerinvoices/{retainerinvoice_id}/comments/{comment_id}?authtoken=ba4604e8e433g9c892e360d53463oec5&organization_id=10234695 -H "Authorization: Zoho-authtoken ba4604e8e433g9c892e360d53463oec5" -H "Content-Type: application/json;charset=UTF-8" -d JSONString='{ "description": "comment updated", "show_comment_to_clients": true }'

Response Example

  
HTTP/1.1 200 OK Content-Type:application/json;charset=UTF-8 { "code": 0, "message": "The comment has been deleted.", "comment_id": 982000000567019, "retainerinvoice_id": 982000000567114, "description": "500GB, USB 2.0 interface 1400 rpm, protective hard case.", "commented_by_id": 982000000554041, "commented_by": "John David", "date": "2013-11-17", "date_description": "yesterday", "time": "2:38 AM", "comment_type": "system" }

ARGUMENTS

description
Optional
The description of the line items. Maximum length [2000]
show_comment_to_clients
Optional
Boolean to check if the comment to be shown to the clients

Credit Notes

A credit note is a promisory note issued to a person, when we owe him money. 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": [ { "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", "item_name": "kit", "description": "500GB, USB 2.0 interface 1400 rpm, protective hard case.", "name": "Hard Drive", "type": 1, "quantity": 1, "tax_id": "903000000000356", "rate": 100, "item_total": 100, "product_type": "goods", "hsn_or_sac": 80540 } ], "invoices": [ { "invoice_id": "90300000079426", "invoice_number": "INV-384", "amount": 450 } ], "currency_code": "USD", "currency_symbol": "$", "created_time": "2016-06-05T02:30:08-0700", "updated_time": "2016-07-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. Maximum 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. Date 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. Maximum Length of the name [100]
custom_fields
list
additional fields for credit note
value
string
Value of the custom field.
label
string
Label of the custom field.
data_type
string
Data type of the custom field.
reference_number
string
Reference number generated for the payment. A string of your choice can also be used as the reference number. Maximum Length [100]
email
string
Email address of the customer.
total
double
Total credits raised in this credit note.
balance
double
The unapplied/existing credits.
list
Items present in a credit note
item_id
string
Unique string generated for the item to which a refund is to be made.
item_name
string
Search credit notes by item name. Maximum length [100]
name
string
Name of the credit note item.
quantity
required
Quantity of the item included.
tax_id
string
Unique to denote the tax associate dto the creditnote
rate
double
The rate of the item included.
item_total
double
Total credits raised by this item. This would be the multiplicative product of item price and quantity.
product_type
string
Enter goods/services
hsn_or_sac
India Edition only
string
Add HSN/SAC code for your goods/services
list
List of invoices used for a credit redemption
invoice_id
string
Invoice ID of the required invoice.
invoice_number
string
Invoice number of the required invoice.
amount
double
Amount of the invoice.
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 used
template_name
string
Name of the default template of the creditnote used

Create a credit note

Details of an existing creditnote.

POST /creditnotes

Request Example

  
$ curl https://invoice.zoho.com/api/v3/creditnotes?authtoken=ba4604e8e433g9c892e360d53463oec5&organization_id=10234695 -H "Authorization: Zoho-authtoken ba4604e8e433g9c892e360d53463oec5" -H "Content-Type: application/json;charset=UTF-8" -d JSONString='{ "customer_id": "903000000000099", "contact_persons": [ "903000006532" ], "date": "2016-06-05", "exchange_rate": "5.5", "line_items": [ { "item_id": "90300000081501", "description": "500GB, USB 2.0 interface 1400 rpm, protective hard case.", "name": "Hard Drive", "type": 1, "quantity": 1, "tax_id": "903000000000356", "tax_exemption_id": "903000006345", "rate": 100, "item_total": 100, "product_type": "goods", "hsn_or_sac": 80540 } ], "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": [ { "value": 129890, "label": "label", "data_type": "text" } ], "notes": "Offer for the referral", "terms": "Can be added for refund only if purchased again", "template_id": "90300000001336", "tax_authority_id": "903000006345", "tax_exemption_id": "903000006345" }'

Response Example

  
HTTP/1.1 201 Created Content-Type:application/json;charset=UTF-8 { "code": 0, "message": "The credit note has been created.", "creditnote": { "creditnote_id": "90300000072369", "creditnote_number": "CN-29", "date": "2016-06-05", "status": "open", "customer_id": "903000000000099", "product_type": "goods", "warehouse_id": 90300000072378, "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": "500GB, USB 2.0 interface 1400 rpm, protective hard case.", "name": "Hard Drive", "type": 1, "quantity": 1, "tax_id": "903000000000356", "rate": 100, "item_total": 100, "product_type": "goods", "hsn_or_sac": 80540 } ], "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", "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" }, "created_time": "2016-06-05T02:30:08-0700", "updated_time": "2016-07-05T02:30:08-0700", "template_id": "90300000001336", "template_name": "Standard Template", "notes": "Offer for the referral", "terms": "Can be added for refund only if purchased again" } }

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. Date Format [yyyy-mm-dd]
exchange_rate
Optional
Exchange rate for the currency associated with the customer.
Required
Items present in a credit note
item_id
Optional
Unique string generated for the item to which a refund is to be made.
name
Optional
Name of the credit note item.
quantity
Optional
Quantity of the item included.
tax_id
Optional
Unique to denote the tax associate dto the creditnote
tax_exemption_id
India, US and CA edition only
Optional
Unique ID of the tax exemption.
avatax_tax_code
Avalara integration only
Optional
A tax code is a unique label used to group Items (products, services, or charges) together. Maximum length [25]
avatax_use_code
Avalara integration only
Optional
Used to group like customers for exemption purposes. It is a custom value that links customers to a tax rule. Select from Avalara [standard codes][1] or enter a custom code. Maximum length [25]
rate
Optional
The rate of the item included.
item_total
Optional
Total credits raised by this item. This would be the multiplicative product of item price and quantity.
product_type
Optional
Enter goods/services
hsn_or_sac
India Edition only
Optional
Add HSN/SAC code for your goods/services
creditnote_number
Required
Unique number generated (starts with CN) which will be displayed in the interface and credit notes. Maximum 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. Maximum Length [100]
custom_fields
Optional
additional fields for credit note
value
Optional
Value of the custom field.
label
Optional
Label of the custom field.
data_type
Optional
Data type of the custom field.
notes
Optional
A short note for the credit note. Maximum length [5000]
terms
Optional
Terms & condition to be displayed in the credit note. Maximum length [10000]
template_id
Optional
Unique ID of the creditnote template used
tax_authority_id
US and CA 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
India, US and CA edition 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. Maximum 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. Maximum length [25]
avatax_exempt_no
Avalara integration only
Optional
Exemption certificate number of the customer. Maximum length [25]
vat_treatment
Optional
Enter vat treatment

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

Update Details of an existing creditnote.

PUT /creditnotes/{creditnote_id}

Request Example

  
$ curl https://invoice.zoho.com/api/v3/creditnotes/{creditnote_id}?authtoken=ba4604e8e433g9c892e360d53463oec5&organization_id=10234695 -H "Authorization: Zoho-authtoken ba4604e8e433g9c892e360d53463oec5" -H "Content-Type: application/json;charset=UTF-8" -d JSONString='{ "customer_id": "903000000000099", "contact_persons": [ "903000006532" ], "date": "2016-06-05", "exchange_rate": "5.5", "line_items": [ { "item_id": "90300000081501", "description": "500GB, USB 2.0 interface 1400 rpm, protective hard case.", "name": "Hard Drive", "type": 1, "quantity": 1, "tax_id": "903000000000356", "tax_exemption_id": "903000006345", "rate": 100, "item_total": 100, "product_type": "goods", "hsn_or_sac": 80540 } ], "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": [ { "value": 129890, "label": "label", "data_type": "text" } ], "notes": "Offer for the referral", "terms": "Can be added for refund only if purchased again", "template_id": "90300000001336", "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": "The credit note has been updated.", "creditnote": { "creditnote_id": "90300000072369", "creditnote_number": "CN-29", "date": "2016-06-05", "status": "open", "customer_id": "903000000000099", "product_type": "goods", "warehouse_id": 90300000072378, "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": "500GB, USB 2.0 interface 1400 rpm, protective hard case.", "name": "Hard Drive", "type": 1, "quantity": 1, "tax_id": "903000000000356", "rate": 100, "item_total": 100, "product_type": "goods", "hsn_or_sac": 80540 } ], "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", "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" }, "created_time": "2016-06-05T02:30:08-0700", "updated_time": "2016-07-05T02:30:08-0700", "template_id": "90300000001336", "template_name": "Standard Template", "notes": "Offer for the referral", "terms": "Can be added for refund only if purchased again" } }

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. Date Format [yyyy-mm-dd]
exchange_rate
Optional
Exchange rate for the currency associated with the customer.
Required
Items present in a credit note
item_id
Optional
Unique string generated for the item to which a refund is to be made.
name
Optional
Name of the credit note item.
quantity
Optional
Quantity of the item included.
tax_id
Optional
Unique to denote the tax associate dto the creditnote
tax_exemption_id
India, US and CA edition only
Optional
Unique ID of the tax exemption.
avatax_tax_code
Avalara integration only
Optional
A tax code is a unique label used to group Items (products, services, or charges) together. Maximum length [25]
avatax_use_code
Avalara integration only
Optional
Used to group like customers for exemption purposes. It is a custom value that links customers to a tax rule. Select from Avalara [standard codes][1] or enter a custom code. Maximum length [25]
rate
Optional
The rate of the item included.
item_total
Optional
Total credits raised by this item. This would be the multiplicative product of item price and quantity.
product_type
Optional
Enter goods/services
hsn_or_sac
India Edition only
Optional
Add HSN/SAC code for your goods/services
creditnote_number
Required
Unique number generated (starts with CN) which will be displayed in the interface and credit notes. Maximum 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. Maximum Length [100]
custom_fields
Optional
additional fields for credit note
value
Optional
Value of the custom field.
label
Optional
Label of the custom field.
data_type
Optional
Data type of the custom field.
notes
Optional
A short note for the credit note. Maximum length [5000]
terms
Optional
Terms & condition to be displayed in the credit note. Maximum length [10000]
template_id
Optional
Unique ID of the creditnote template used
tax_authority_id
US and CA 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
India, US and CA edition 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. Maximum 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. Maximum length [25]
avatax_exempt_no
Avalara integration only
Optional
Exemption certificate number of the customer. Maximum length [25]
vat_treatment
Optional
Enter vat treatment

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://invoice.zoho.com/api/v3/creditnotes/{creditnote_id}?authtoken=ba4604e8e433g9c892e360d53463oec5&organization_id=10234695 -H "Authorization: Zoho-authtoken ba4604e8e433g9c892e360d53463oec5" -H "Content-Type: application/json;charset=UTF-8"

Response Example

  
HTTP/1.1 200 OK Content-Type:application/json;charset=UTF-8 { "code": 0, "message": "success", "creditnote": { "creditnote_id": "90300000072369", "creditnote_number": "CN-29", "date": "2016-06-05", "status": "open", "customer_id": "903000000000099", "product_type": "goods", "warehouse_id": 90300000072378, "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": "500GB, USB 2.0 interface 1400 rpm, protective hard case.", "name": "Hard Drive", "type": 1, "quantity": 1, "tax_id": "903000000000356", "rate": 100, "item_total": 100, "product_type": "goods", "hsn_or_sac": 80540 } ], "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-07-05T02:30:08-0700", "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" }, "template_id": "90300000001336", "template_name": "Standard Template", "notes": "Offer for the referral", "terms": "Can be added for refund only if purchased again" } }

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 Credit Notes

List all the Credit Notes .

GET /creditnotes

Request Example

  
$ curl https://invoice.zoho.com/api/v3/creditnotes?authtoken=ba4604e8e433g9c892e360d53463oec5&organization_id=10234695 -H "Authorization: Zoho-authtoken ba4604e8e433g9c892e360d53463oec5" -H "Content-Type: application/json;charset=UTF-8"

Response Example

  
HTTP/1.1 200 OK Content-Type:application/json;charset=UTF-8 { "code": 0, "message": "success", "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. Maximum Length [100]
date
Optional
The date on which credit note is raised. Date 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. Maximum Length [100]
customer_name
Optional
Name of the customer to whom the credit note is raised. Maximum Length of the name [100]
item_name
Optional
Search credit notes by item name. Maximum length [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. Maximum length [100]
item_id
Optional
Unique string generated for the item to which a refund is to be made.
filter_by
Optional
Filter credit notes by status. 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. Maximum 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://invoice.zoho.com/api/v3/creditnotes/{creditnote_id}/email?authtoken=ba4604e8e433g9c892e360d53463oec5&organization_id=10234695 -H "Authorization: Zoho-authtoken ba4604e8e433g9c892e360d53463oec5" -H "Content-Type: application/json;charset=UTF-8" -d JSONString='{ "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. Maximum length [1000]
body
Required
The body/content of the email. Maximum 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

To mark a credit note as invalid/nullify it content.

POST /creditnotes/{creditnote_id}/void

Request Example

  
$ curl https://invoice.zoho.com/api/v3/creditnotes/{creditnote_id}/void?authtoken=ba4604e8e433g9c892e360d53463oec5&organization_id=10234695 -H "Authorization: Zoho-authtoken ba4604e8e433g9c892e360d53463oec5" -H "Content-Type: application/json;charset=UTF-8"

Response Example

  
HTTP/1.1 200 OK Content-Type:application/json;charset=UTF-8 { "code": 0, "message": "The credit note has been marked as void." }

Open a voided credit note

Convert a voided credit note to open

POST /creditnotes/{creditnote_id}/converttoopen

Request Example

  
$ curl https://invoice.zoho.com/api/v3/creditnotes/{creditnote_id}/converttoopen?authtoken=ba4604e8e433g9c892e360d53463oec5&organization_id=10234695 -H "Authorization: Zoho-authtoken ba4604e8e433g9c892e360d53463oec5" -H "Content-Type: application/json;charset=UTF-8"

Response Example

  
HTTP/1.1 200 OK Content-Type:application/json;charset=UTF-8 { "code": 0, "message": "Status of the credit note has been changed to open." }

Delete a credit note

Delete an existing credit note

DELETE /creditnotes/{creditnote_id}

Request Example

  
$ curl https://invoice.zoho.com/api/v3/creditnotes/{creditnote_id}?authtoken=ba4604e8e433g9c892e360d53463oec5&organization_id=10234695 -H "Authorization: Zoho-authtoken ba4604e8e433g9c892e360d53463oec5" -H "Content-Type: application/json;charset=UTF-8"

Response Example

  
HTTP/1.1 200 OK Content-Type:application/json;charset=UTF-8 { "code": 0, "message": "The credit note has been deleted." }

Email history

Get email history of a credit code.

GETE /creditnotes/{creditnote_id}/emailhistory

Request Example

  
$ curl https://invoice.zoho.com/api/v3/creditnotes/{creditnote_id}/emailhistory?authtoken=ba4604e8e433g9c892e360d53463oec5&organization_id=10234695 -H "Authorization: Zoho-authtoken ba4604e8e433g9c892e360d53463oec5" -H "Content-Type: application/json;charset=UTF-8"

Response Example

  
HTTP/1.1 200 OK Content-Type:application/json;charset=UTF-8 { "code": 0, "message": "success", "email_history": [ { "mailhistory_id": 982000000570005, "from": "gator@zillum.com", "to_mail_ids": [ "benjamin.george@bowmanfurniture.com", "paul@bowmanfurniture.com" ], "subject": "Credit note for subscription.", "date": "2016-06-05" } ] }

Update billing address

Updates the billing address for an existing credit note alone.

PUT /creditnotes/{creditnote_id}/address/billing

Request Example

  
$ curl https://invoice.zoho.com/api/v3/creditnotes/{creditnote_id}/address/billing?authtoken=ba4604e8e433g9c892e360d53463oec5&organization_id=10234695 -H "Authorization: Zoho-authtoken ba4604e8e433g9c892e360d53463oec5" -H "Content-Type: application/json;charset=UTF-8" -d JSONString='{ "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 of the contact
city
Optional
City of the contact
state
Optional
State of the contact's address
zip
Optional
ZIP code of a contacts billing address
country
Optional
Country of a contact's billing address
fax
Optional
FAX number of a contact

Update Shipping address

Updates the shipping address for an existing credit note alone.

PUT /creditnotes/{creditnote_id}/address/shipping

Request Example

  
$ curl https://invoice.zoho.com/api/v3/creditnotes/{creditnote_id}/address/shipping?authtoken=ba4604e8e433g9c892e360d53463oec5&organization_id=10234695 -H "Authorization: Zoho-authtoken ba4604e8e433g9c892e360d53463oec5" -H "Content-Type: application/json;charset=UTF-8" -d JSONString='{ "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 field
city
Optional
City of a contacts billing address
state
Optional
State of a contct's billing address
zip
Optional
ZIP code of a billing address
country
Optional
Country of a contacts billing address
fax
Optional
Customer's fax number.

List credit note templates

Get all credit note pdf templates.

GET /creditnotes/templates

Request Example

  
$ curl https://invoice.zoho.com/api/v3/creditnotes/templates?authtoken=ba4604e8e433g9c892e360d53463oec5&organization_id=10234695 -H "Authorization: Zoho-authtoken ba4604e8e433g9c892e360d53463oec5" -H "Content-Type: application/json;charset=UTF-8"

Response Example

  
HTTP/1.1 200 OK Content-Type:application/json;charset=UTF-8 { "code": 0, "message": "success", "templates": [ { "template_name": "Standard Template", "template_id": "90300000001336", "template_type": "professional" }, {...}, {...} ] }

Update a credit note template

Update the pdf template associated with the credit note.

PUT /creditnotes/{creditnote_id}/templates/{template_id}

Request Example

  
$ curl https://invoice.zoho.com/api/v3/creditnotes/{creditnote_id}/templates/{template_id}?authtoken=ba4604e8e433g9c892e360d53463oec5&organization_id=10234695 -H "Authorization: Zoho-authtoken ba4604e8e433g9c892e360d53463oec5" -H "Content-Type: application/json;charset=UTF-8"

Response Example

  
HTTP/1.1 200 OK Content-Type:application/json;charset=UTF-8 { "code": 0, "message": "The credit note has been updated." }

List invoices credited

List invoices to which the credit note is applied.

GET /creditnotes/{creditnote_id}/invoices

Request Example

  
$ curl https://invoice.zoho.com/api/v3/creditnotes/{creditnote_id}/invoices?authtoken=ba4604e8e433g9c892e360d53463oec5&organization_id=10234695 -H "Authorization: Zoho-authtoken ba4604e8e433g9c892e360d53463oec5" -H "Content-Type: application/json;charset=UTF-8"

Response Example

  
HTTP/1.1 200 OK Content-Type:application/json;charset=UTF-8 { "code": 0, "message": "success", "invoices_credited": [ { "creditnote_id": "90300000072369", "invoice_id": "90300000079426", "creditnote_invoice_id": "982000000567172", "date": "2016-06-05", "invoice_number": "INV-384", "creditnote_number": "CN-29", "credited_amount": 12.02 }, {...}, {...} ] }

Credit to an invoice

Apply credit note to existing invoices.

POST /creditnotes/{creditnote_id}/invoices

Request Example

  
$ curl https://invoice.zoho.com/api/v3/creditnotes/{creditnote_id}/invoices?authtoken=ba4604e8e433g9c892e360d53463oec5&organization_id=10234695 -H "Authorization: Zoho-authtoken ba4604e8e433g9c892e360d53463oec5" -H "Content-Type: application/json;charset=UTF-8" -d JSONString='{ "invoices": [ { "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 used for a credit redemption
invoice_id
Optional
Invoice ID of the required invoice.
amount_applied
Optional
The total amount applied for redemption from 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://invoice.zoho.com/api/v3/creditnotes/{creditnote_id}/invoices/{creditnote_invoice_id}?authtoken=ba4604e8e433g9c892e360d53463oec5&organization_id=10234695 -H "Authorization: Zoho-authtoken ba4604e8e433g9c892e360d53463oec5" -H "Content-Type: application/json;charset=UTF-8"

Response Example

  
HTTP/1.1 200 OK Content-Type:application/json;charset=UTF-8 { "code": 0, "message": "Credits applied to an invoice have been deleted." }

List credit note comments & history

Get history and comments of a credit note.

GET /creditnotes/{creditnote_id}/comments

Request Example

  
$ curl https://invoice.zoho.com/api/v3/creditnotes/{creditnote_id}/comments?authtoken=ba4604e8e433g9c892e360d53463oec5&organization_id=10234695 -H "Authorization: Zoho-authtoken ba4604e8e433g9c892e360d53463oec5" -H "Content-Type: application/json;charset=UTF-8"

Response Example

  
HTTP/1.1 200 OK Content-Type:application/json;charset=UTF-8 { "code": 0, "message": "Comments of the credit note are displayed successfully.", "comments": [ { "comment_id": "982000000570001", "creditnote_id": "90300000072369", "description": "Credits applied to invoice INV-00004", "commented_by_id": "982000000554041", "commented_by": "David Sujin", "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://invoice.zoho.com/api/v3/creditnotes/{creditnote_id}/comments?authtoken=ba4604e8e433g9c892e360d53463oec5&organization_id=10234695 -H "Authorization: Zoho-authtoken ba4604e8e433g9c892e360d53463oec5" -H "Content-Type: application/json;charset=UTF-8" -d JSONString='{ "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 short note on the credit applied

Delete a Comment

Delete a credit note comment.

DELETE /creditnotes/{creditnote_id}/comments/{comment_id}

Request Example

  
$ curl https://invoice.zoho.com/api/v3/creditnotes/{creditnote_id}/comments/{comment_id}?authtoken=ba4604e8e433g9c892e360d53463oec5&organization_id=10234695 -H "Authorization: Zoho-authtoken ba4604e8e433g9c892e360d53463oec5" -H "Content-Type: application/json;charset=UTF-8"

Response Example

  
HTTP/1.1 200 OK Content-Type:application/json;charset=UTF-8 { "code": 0, "message": "The comment has been deleted." }

List credit note refunds

List all refunds with pagination.

GET /creditnotes/refunds

Request Example

  
$ curl https://invoice.zoho.com/api/v3/creditnotes/refunds?authtoken=ba4604e8e433g9c892e360d53463oec5&organization_id=10234695 -H "Authorization: Zoho-authtoken ba4604e8e433g9c892e360d53463oec5" -H "Content-Type: application/json;charset=UTF-8"

Response Example

  
HTTP/1.1 200 OK Content-Type:application/json;charset=UTF-8 { "code": 0, "message": "The list of credit note refunds are displayed successfully.", "creditnote_refunds": [ { "creditnote_refund_id": "982000000567158", "creditnote_id": "90300000072369", "date": "2016-06-05", "refund_mode": "cash", "reference_number": "INV-384", "creditnote_number": "CN-29", "customer_name": "Bowman Furniture", "description": "Offer", "amount_bcy": 10, "amount_fcy": 10 }, {...}, {...} ] }

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://invoice.zoho.com/api/v3/creditnotes/{creditnote_id}/refunds?authtoken=ba4604e8e433g9c892e360d53463oec5&organization_id=10234695 -H "Authorization: Zoho-authtoken ba4604e8e433g9c892e360d53463oec5" -H "Content-Type: application/json;charset=UTF-8"

Response Example

  
HTTP/1.1 200 OK Content-Type:application/json;charset=UTF-8 { "code": 0, "message": "The refunds of the existing credit note are displayed successfully.", "creditnote_refunds": [ { "creditnote_refund_id": "982000000567158", "creditnote_id": "90300000072369", "date": "2016-06-05", "refund_mode": "cash", "reference_number": "INV-384", "creditnote_number": "CN-29", "customer_name": "Bowman Furniture", "description": "Offer", "amount_bcy": 10, "amount_fcy": 10 }, {...}, {...} ] }

Get credit note refund

Get refund of a particular credit note.

GET /creditnotes/{creditnote_id}/refunds/{creditnote_refund_id}

Request Example

  
$ curl https://invoice.zoho.com/api/v3/creditnotes/{creditnote_id}/refunds/{creditnote_refund_id}?authtoken=ba4604e8e433g9c892e360d53463oec5&organization_id=10234695 -H "Authorization: Zoho-authtoken ba4604e8e433g9c892e360d53463oec5" -H "Content-Type: application/json;charset=UTF-8"

Response Example

  
HTTP/1.1 200 OK Content-Type:application/json;charset=UTF-8 { "code": 0, "message": "The refund of the credit note is displayed successfully.", "creditnote_refund": { "creditnote_refund_id": "982000000567158", "creditnote_id": "90300000072369", "date": "2016-06-05", "refund_mode": "cash", "reference_number": "INV-384", "amount": 450, "customer_name": "Bowman Furniture", "description": "500GB, USB 2.0 interface 1400 rpm, protective hard case." } }

Refund credit note

Refund credit note amount.

POST /creditnotes/{creditnote_id}/refunds

Request Example

  
$ curl https://invoice.zoho.com/api/v3/creditnotes/{creditnote_id}/refunds?authtoken=ba4604e8e433g9c892e360d53463oec5&organization_id=10234695 -H "Authorization: Zoho-authtoken ba4604e8e433g9c892e360d53463oec5" -H "Content-Type: application/json;charset=UTF-8" -d JSONString='{ "date": "2016-06-05", "refund_mode": "cash", "reference_number": "INV-384", "amount": 450, "exchange_rate": "5.5", "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": "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": "500GB, USB 2.0 interface 1400 rpm, protective hard case." } }

ARGUMENTS

date
Optional
The date on which credit note is raised. Date 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. Maximum Length [100]
amount
Optional
Amount of the invoice.
exchange_rate
Optional
Exchange rate for the currency associated with the customer.
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://invoice.zoho.com/api/v3/creditnotes/{creditnote_id}/refunds/{creditnote_refund_id}?authtoken=ba4604e8e433g9c892e360d53463oec5&organization_id=10234695 -H "Authorization: Zoho-authtoken ba4604e8e433g9c892e360d53463oec5" -H "Content-Type: application/json;charset=UTF-8" -d JSONString='{ "date": "2016-06-05", "refund_mode": "cash", "reference_number": "INV-384", "amount": 450, "exchange_rate": "5.5", "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": "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": "500GB, USB 2.0 interface 1400 rpm, protective hard case." } }

ARGUMENTS

date
Optional
The date on which credit note is raised. Date 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. Maximum Length [100]
amount
Optional
Amount of the invoice.
exchange_rate
Optional
Exchange rate for the currency associated with the customer.
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://invoice.zoho.com/api/v3/creditnotes/{creditnote_id}/refunds/{creditnote_refund_id}?authtoken=ba4604e8e433g9c892e360d53463oec5&organization_id=10234695 -H "Authorization: Zoho-authtoken ba4604e8e433g9c892e360d53463oec5" -H "Content-Type: application/json;charset=UTF-8"

Response Example

  
HTTP/1.1 200 OK Content-Type:application/json;charset=UTF-8 { "code": 0, "message": "The refund has been successfully deleted." }

Expenses

An expense represents the money that you spend, with the ultimate target of generating revenue for your organization

Example

{ "description": "Marketing", "reference_number": "#562SD23R4", "date": "2013-11-18", "status": "unbilled", "amount": 112.5, "customer_name": "Bowman & Co", "is_billable": true }

Attribute

description
String
Description of the expense. Maximum length [100]
reference_number
String
Reference number of the expense. Maximum length [100]
date
String
Date of the expense
status
String
Expense status
amount
double
Amount of the Expense.
customer_name
String
Name of the Customer for whom expense is raised. Maximum length [100]
is_billable
boolean
Check if an expense is billable

Create an Expense

Create billable or non-billable expense

POST /expenses

Request Example

  
$ curl https://invoice.zoho.com/api/v3/expenses?authtoken=ba4604e8e433g9c892e360d53463oec5&organization_id=10234695 -H "Authorization: Zoho-authtoken ba4604e8e433g9c892e360d53463oec5" -H "Content-Type: application/json;charset=UTF-8" -d JSONString='{ "account_id": 982000000561057, "date": "2013-11-18", "amount": 112.5, "tax_id": 982000000566007, "is_inclusive_tax": false, "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_billable": true, "reference_number": "#562SD23R4", "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": " " }'

Response Example

  
HTTP/1.1 200 OK Content-Type:application/json;charset=UTF-8 { "code": 0, "message": "The expense has been recorded.", "expense": { "expense_id": 982000000030049, "transaction_id": " ", "transaction_type": "expense", "expense_item_id": 982000000567220, "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 } } ], "account_id": 982000000561057, "account_name": "Rent", "date": "2013-11-18", "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": "#562SD23R4", "description": "Marketing", "is_billable": true, "is_personal": false, "customer_id": 982000000567001, "customer_name": "Bowman & Co", "expense_receipt_name": " ", "expense_receipt_type": " ", "last_modified_time": "2013-12-18T02:17:40-0800", "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
Tax ID applied
is_inclusive_tax
Optional
Check if amount is inclusive of tax
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
ID of the items in the expense
account_id
Optional
ID of the expense account.
description
Optional
Description of the expense. Maximum length [100]
amount
Required
Amount of the Expense.
tax_id
Optional
Tax ID applied
item_order
Optional
Order of the items
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: 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_billable
Optional
Check if an expense is billable
reference_number
Required
Reference number of the expense. Maximum length [100]
description
Optional
Description of the expense. Maximum length [100]
customer_id
Optional
ID of the expense account.
currency_id
Optional
Unique ID of the currency
exchange_rate
Optional
Foreign currency exchange rate
project_id
Optional
ID of the project associated with the customer.
mileage_type
Optional
Milage expense type
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: 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
Milage expense type
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

Query Params

receipt
Optional
Expense receipt file to attach. Allowed Extensions: gif, png, jpeg, jpg, bmp and pdf

Update an Expense

Update an existing Expense

PUT /expenses/{expense_id}

Request Example

  
$ curl https://invoice.zoho.com/api/v3/expenses/{expense_id}?authtoken=ba4604e8e433g9c892e360d53463oec5&organization_id=10234695 -H "Authorization: Zoho-authtoken ba4604e8e433g9c892e360d53463oec5" -H "Content-Type: application/json;charset=UTF-8" -d JSONString='{ "account_id": 982000000561057, "date": "2013-11-18", "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": "#562SD23R4", "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": " " }'

Response Example

  
HTTP/1.1 200 OK Content-Type:application/json;charset=UTF-8 { "code": 0, "message": "Expense information has been updated.", "expense": { "expense_id": 982000000030049, "transaction_id": " ", "transaction_type": "expense", "expense_item_id": 982000000567220, "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 } } ], "account_id": 982000000561057, "account_name": "Rent", "date": "2013-11-18", "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": "#562SD23R4", "description": "Marketing", "is_billable": true, "is_personal": false, "customer_id": 982000000567001, "customer_name": "Bowman & Co", "expense_receipt_name": " ", "expense_receipt_type": " ", "last_modified_time": "2013-12-18T02:17:40-0800", "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
Total expense value
tax_id
Optional
Tax ID applied
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
ID of the items in the expense
account_id
Optional
ID of the expense account.
description
Optional
Description of the expense. Maximum length [100]
amount
Required
Total expense value
tax_id
Optional
Tax ID applied
item_order
Optional
Order of the items
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: 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
Check if amount is inclusive of tax
is_billable
Optional
Check if an expense is billable
reference_number
Required
Reference number of the expense. Maximum length [100]
description
Optional
Description of the expense. Maximum length [100]
customer_id
Optional
ID of the expense account.
currency_id
Optional
Unique ID of the currency
exchange_rate
Optional
Foreign currency exchange rate
project_id
Optional
ID of the project associated with the customer.
mileage_type
Optional
Milage expense type
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: 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
Milage expense type
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

Query Params

receipt
Optional
Expense receipt file to attach. Allowed Extensions: gif, png, jpeg, jpg, bmp and pdf
delete_receipt
Optional
A historic receipt

List Expenses

List all the Expenses with pagination.

GET /expenses

Request Example

  
$ curl https://invoice.zoho.com/api/v3/expenses?authtoken=ba4604e8e433g9c892e360d53463oec5&organization_id=10234695 -H "Authorization: Zoho-authtoken ba4604e8e433g9c892e360d53463oec5" -H "Content-Type: application/json;charset=UTF-8"

Response Example

  
HTTP/1.1 200 OK Content-Type:application/json;charset=UTF-8 { "code": 0, "message": "success", "expenses": [ { "expense_id": 982000000030049, "date": "2013-11-18", "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": "#562SD23R4", "customer_id": 982000000567001, "customer_name": "Bowman & Co", "status": "unbilled", "created_time": "2013-11-18T02:17:40-0800", "last_modified_time": "2013-12-18T02:17:40-0800", "expense_receipt_name": " ", "mileage_rate": " ", "mileage_unit": " ", "expense_type": "non-mileage", "start_reading": " ", "end_reading": " " }, {...}, {...} ] }

Query Params

description
Optional
Search expenses by description.Variants description_startswith and description_contains. Maximum length [100]
reference_number
Optional
Search expenses by reference number. Variants reference_number_startswith and reference_number_contains. Maximum length [100]
date
Optional
Search expenses by expense date. Variants date_start, date_end, date_before and date_after. Date Format [yyyy-mm-dd]
status
Optional
Search expenses by expense status. Allowed Values unbilled, invoiced, reimbursed, non-billable and billable
amount
Optional
Search expenses by amount. Variants: amount_less_than, amount_less_equals, amount_greater_than and amount_greater_than
account_name
Optional
Search expenses by expense account name. Variants account_name_startswith and account_name_contains. Maximum length [100]
customer_name
Optional
Search expenses by customer name. Variants: customer_name_startswith and customer_name_contains. Maximum length [100]
search_text
Optional
Search expenses by account name or description or customer name or vendor name. Maximum length [100]
sort_column
Optional
Sort expenses.Allowed Values date, account_name, total, bcy_total, reference_number, customer_name and created_time
filter_by
Optional
Filter expenses by expense status. Allowed Values Status.All, Status.Billable, Status.Nonbillable, Status.Reimbursed, Status.InvoicedStatus.Unbilled

Get an Expense

Get the details of the Expense

GET /expenses/{expense_id}

Request Example

  
$ curl https://invoice.zoho.com/api/v3/expenses/{expense_id}?authtoken=ba4604e8e433g9c892e360d53463oec5&organization_id=10234695 -H "Authorization: Zoho-authtoken ba4604e8e433g9c892e360d53463oec5" -H "Content-Type: application/json;charset=UTF-8"

Response Example

  
HTTP/1.1 200 OK Content-Type:application/json;charset=UTF-8 { "code": 0, "message": "success", "expense": { "expense_id": 982000000030049, "transaction_id": " ", "transaction_type": "expense", "expense_item_id": 982000000567220, "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 } } ], "account_id": 982000000561057, "account_name": "Rent", "date": "2013-11-18", "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": "#562SD23R4", "description": "Marketing", "is_billable": true, "is_personal": false, "customer_id": 982000000567001, "customer_name": "Bowman & Co", "expense_receipt_name": " ", "expense_receipt_type": " ", "last_modified_time": "2013-12-18T02:17:40-0800", "status": "unbilled", "invoice_id": " ", "invoice_number": " ", "project_id": 982000000567226, "project_name": " ", "mileage_rate": " ", "mileage_type": "non_mileage", "expense_type": "non-mileage", "start_reading": " ", "end_reading": " ", "line_item": { "line_item_id": 10763000000140068, "account_id": 982000000561057, "account_name": "Rent", "description": "Marketing", "tax_amount": 11.85, "tax_id": 982000000566007, "tax_name": "SalesTax", "tax_type": "tax", "tax_percentage": 10.5, "item_total": 100, "item_order": 1, "amount": 112.5, "hsn_or_sac": 80540, "reverse_charge_tax_id": 982000000561063, "reverse_charge_tax_name": "intra", "reverse_charge_tax_percentage": 10, "reverse_charge_tax_amount": 12 } } }

Delete an Expense

Delete an existing expense.

DELETE /expenses/{expense_id}

Request Example

  
$ curl https://invoice.zoho.com/api/v3/expenses/{expense_id}?authtoken=ba4604e8e433g9c892e360d53463oec5&organization_id=10234695 -H "Authorization: Zoho-authtoken ba4604e8e433g9c892e360d53463oec5" -H "Content-Type: application/json;charset=UTF-8"

Response Example

  
HTTP/1.1 200 OK Content-Type:application/json;charset=UTF-8 { "code": 0, "message": "The expense has been deleted." }

List expense History & Comments

Get history and comments of an expense

GET /expense/{expense_id}/comments

Request Example

  
$ curl https://invoice.zoho.com/api/v3/expense/{expense_id}/comments?authtoken=ba4604e8e433g9c892e360d53463oec5&organization_id=10234695 -H "Authorization: Zoho-authtoken ba4604e8e433g9c892e360d53463oec5" -H "Content-Type: application/json;charset=UTF-8"

Response Example

  
HTTP/1.1 200 OK Content-Type:application/json;charset=UTF-8 { "code": 0, "message": "success", "comments": [ { "comment_id": 982000000567272, "expense_id": 982000000030049, "description": "Marketing", "commented_by_id": 982000000554041, "commented_by": "John David", "date_description": "16 hours ago", "time": "4.22AM", "operation_type": "Added", "transaction_id": " ", "transaction_type": "expense" }, {...}, {...} ] }

List claimants

List claimants with pagination

GET /claimants

Request Example

  
$ curl https://invoice.zoho.com/api/v3/claimants?authtoken=ba4604e8e433g9c892e360d53463oec5&organization_id=10234695 -H "Authorization: Zoho-authtoken ba4604e8e433g9c892e360d53463oec5" -H "Content-Type: application/json;charset=UTF-8"

Response Example

  
HTTP/1.1 200 OK Content-Type:application/json;charset=UTF-8 { "code": 0, "message": "success", "claimants": [ { "claimant_id": " ", "name": "John David", "email": "johnsmith@zilliuminc.com" }, {...}, {...} ] }

Get a claimant

Get the details of the claimant

GET /claimants/{claimant_id}

Request Example

  
$ curl https://invoice.zoho.com/api/v3/claimants/{claimant_id}?authtoken=ba4604e8e433g9c892e360d53463oec5&organization_id=10234695 -H "Authorization: Zoho-authtoken ba4604e8e433g9c892e360d53463oec5" -H "Content-Type: application/json;charset=UTF-8"

Response Example

  
HTTP/1.1 200 OK Content-Type:application/json;charset=UTF-8 { "code": 0, "message": "success", "claimant": { "claimant_id": " ", "name": "John David", "email": "johnsmith@zilliuminc.com" } }

Create a claimant

Create a claimant for an expense

POST /claimants

Request Example

  
$ curl https://invoice.zoho.com/api/v3/claimants?authtoken=ba4604e8e433g9c892e360d53463oec5&organization_id=10234695 -H "Authorization: Zoho-authtoken ba4604e8e433g9c892e360d53463oec5" -H "Content-Type: application/json;charset=UTF-8" -d JSONString='{ "name": "John David", "email": "johnsmith@zilliuminc.com" }'

Response Example

  
HTTP/1.1 201 Created Content-Type:application/json;charset=UTF-8 { "code": 0, "message": "success", "claimant": { "claimant_id": " ", "name": "John David", "email": "johnsmith@zilliuminc.com" } }

ARGUMENTS

name
Required
Name of the contact
email
Required
Email address of the contact

Delete a claimant

Delete an existing claimant

DELETE /claimant/{claimant_id}

Request Example

  
$ curl https://invoice.zoho.com/api/v3/claimant/{claimant_id}?authtoken=ba4604e8e433g9c892e360d53463oec5&organization_id=10234695 -H "Authorization: Zoho-authtoken ba4604e8e433g9c892e360d53463oec5" -H "Content-Type: application/json;charset=UTF-8"

Response Example

  
HTTP/1.1 200 OK Content-Type:application/json;charset=UTF-8 { "code": 0, "message": "Claimant has been deleted." }

Recurring Expenses

Recurring expenses are those expenses that repeat itself after a fixed interval of time

Example

{ "recurrence_name": "Monthly Rental", "status": "active", "account_id": 982000000561057, "account_name": "Rent", "amount": 112.5, "customer_name": "Bowman & Co", "is_billable": true }

Attribute

recurrence_name
String
Name of the Recurring Expense. Maximum length [100]
status
String
Status of the recurring expense
account_id
String
Unique ID of an account
account_name
String
For which Account the Expense is raised. Maximum length [100]
amount
double
Recurring Expense amount.
customer_name
String
Name of the Custome for which expense is raised. Maximum length [100]
is_billable
boolean
To check if the expense is billable

Create a recurring expense

Create a new recurring expense

POST /recurringexpenses

Request Example

  
$ curl https://invoice.zoho.com/api/v3/recurringexpenses?authtoken=ba4604e8e433g9c892e360d53463oec5&organization_id=10234695 -H "Authorization: Zoho-authtoken ba4604e8e433g9c892e360d53463oec5" -H "Content-Type: application/json;charset=UTF-8" -d JSONString='{ "account_id": 982000000561057, "recurrence_name": "Monthly Rental", "start_date": "2016-11-19T00:00:00.000Z", "gst_no": "22AAAAA0000A1Z5", "source_of_supply": "AP", "destination_of_supply": "TN", "reverse_charge_tax_id": 982000000567254, "line_items": [ { "line_item_id": 10763000000140068, "account_id": 982000000561057, "description": " ", "amount": 112.5, "tax_id": 982000000566007, "item_order": 1, "product_type": "goods", "acquisition_vat_id": " ", "reverse_charge_vat_id": " ", "reverse_charge_tax_id": 982000000567254, "tax_exemption_id": 982000000567267 } ], "end_date": " ", "recurrence_frequency": "months", "repeat_every": 1, "amount": 112.5, "vat_treatment": "eu_vat_not_registered", "product_type": "goods", "acquisition_vat_id": " ", "reverse_charge_vat_id": " ", "tax_id": 982000000566007, "is_inclusive_tax": false, "is_billable": true, "customer_id": 982000000567001, "project_id": " ", "currency_id": 982000000567001, "exchange_rate": 1 }'

Response Example

  
HTTP/1.1 200 OK Content-Type:application/json;charset=UTF-8 { "code": 0, "message": "The recurring expense has been created", "recurring_expense": { "account_id": 982000000561057, "recurrence_name": "Monthly Rental", "start_date": "2016-11-19T00:00:00.000Z", "end_date": " ", "is_pre_gst": false, "source_of_supply": "AP", "destination_of_supply": "TN", "gst_no": "22AAAAA0000A1Z5", "gst_treatment": "business_gst", "destination_of_supply_state": "AP", "hsn_or_sac": 80540, "vat_treatment": "eu_vat_not_registered", "reverse_charge_tax_id": 982000000567254, "reverse_charge_tax_name": "inter", "reverse_charge_tax_percentage": 10, "reverse_charge_tax_amount": 10, "is_reverse_charge_applied": false, "acquisition_vat_total": 0, "reverse_charge_vat_total": 10, "acquisition_vat_summary": [ { "tax_name": "SalesTax", "tax_amount": 11.85 } ], "reverse_charge_vat_summary": [ { "tax_name": "SalesTax", "tax_amount": 11.85 } ], "recurrence_frequency": "months", "repeat_every": 1, "amount": 112.5, "total": 128.25, "sub_total": 90, "bcy_total": 100, "product_type": "goods", "acquisition_vat_id": " ", "reverse_charge_vat_id": " ", "tax_id": 982000000566007, "tax_name": "SalesTax", "tax_percentage": 10.5, "created_time": "2013-11-18T02:17:40-0800", "last_modified_time": "2013-12-18T02:17:40-0800", "is_inclusive_tax": false, "is_billable": true, "customer_id": 982000000567001, "currency_id": 982000000567001, "exchange_rate": 1, "project_id": " ", "project_name": " ", "line_item": { "line_item_id": 10763000000140068, "account_id": 982000000561057, "account_name": "Rent", "description": " ", "tax_amount": 11.85, "tax_id": 982000000566007, "tax_name": "SalesTax", "tax_type": "tax", "tax_percentage": 10.5, "item_total": 100, "item_order": 1, "hsn_or_sac": 80540, "reverse_charge_tax_id": 982000000567254, "reverse_charge_tax_name": "inter", "reverse_charge_tax_percentage": 10, "reverse_charge_tax_amount": 10 } } }

ARGUMENTS

account_id
Required
Unique ID of an account
recurrence_name
Required
Name of the Recurring Expense. Maximum length [100]
start_date
Required
Start date of the recurring expense. Expenses will not be generated for dates prior to the current date. Format [yyyy-mm-dd].
gst_no
India Edition only.
Optional
15 digit GST identification number of the vendor.
source_of_supply
India Edition only.
Optional
Place from where the goods/services are supplied. (If not given, place of contact given for the contact will be taken)
destination_of_supply
India Edition only.
Optional
Place where the goods/services are supplied to. (If not given, organisation's home state will be taken)
reverse_charge_tax_id
India Edition only.
Optional
Enter reverse charge tax ID
Optional
line_item_id
Optional
Unique ID of Item listed
account_id
Required
Unique ID of an account
description
Optional
Search recurring expenses by description. Maximum length [100]
amount
Required
Recurring Expense amount.
tax_id
Optional
Unique ID for the tax
item_order
Optional
Order of items
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: goods and service.
acquisition_vat_id
UK Edition only
Optional
This is the ID of the tax applied in case this is an EU - goods expense and acquisition VAT needs to be reported.
reverse_charge_vat_id
India Edition and UK Edition only
Optional
This is the ID of the tax applied in case this is a non UK - service expense and reverse charge VAT needs to be reported.
reverse_charge_tax_id
India Edition only.
Optional
Enter reverse charge tax ID
tax_exemption_code
India Edition only.
Optional
Enter the code for tax exemption
tax_exemption_id
India Edition only.
Optional
Enter ID of the tax exemption
end_date
Optional
Date on which recurring expense has to expire. Can be left as empty to run forever. Format [yyyy-mm-dd].
recurrence_frequency
Required
Frequency of the recurrance
repeat_every
Required
The cycle of recurrance
amount
Required
Recurring Expense amount.
vat_treatment
UK Edition only
Optional
VAT treatment for the expense. VAT treatment denotes the location of the vendor, if the vendor resides in UK then the VAT treatment is uk. If the vendor is in an EU country & if he is VAT registered then his VAT treatment is eu_vat_registered, if he resides in EU & if he is not VAT registered then his VAT treatment is eu_vat_not_registered and if he resides outside the EU then his VAT treatment is non_eu.
product_type
UK Edition only
Optional
Type of the expense. This denotes whether the expense is to be treated as a goods or service purchase. Allowed Values: goods and service.
acquisition_vat_id
UK Edition only
Optional
This is the ID of the tax applied in case this is an EU - goods expense and acquisition VAT needs to be reported.
reverse_charge_vat_id
India Edition and UK Edition only
Optional
This is the ID of the tax applied in case this is a non UK - service expense and reverse charge VAT needs to be reported.
tax_id
Optional
Unique ID for the tax
is_inclusive_tax
Optional
To check if the total is inclusive of tax
is_billable
Optional
To check if the expense is billable
customer_id
Optional
Search expenses by customer id.
project_id
Optional
Unique ID of the tax applied
currency_id
Optional
Unique ID of the currency used
exchange_rate
Optional
Foreign exchange rate

Update a recurring expense

Update an existing recurring expense

POST /recurringexpenses/{recurring_expense_id}

Request Example

  
$ curl https://invoice.zoho.com/api/v3/recurringexpenses/{recurring_expense_id}?authtoken=ba4604e8e433g9c892e360d53463oec5&organization_id=10234695 -H "Authorization: Zoho-authtoken ba4604e8e433g9c892e360d53463oec5" -H "Content-Type: application/json;charset=UTF-8" -d JSONString='{ "account_id": 982000000561057, "recurrence_name": "Monthly Rental", "start_date": "2016-11-19T00:00:00.000Z", "gst_no": "22AAAAA0000A1Z5", "source_of_supply": "AP", "destination_of_supply": "TN", "reverse_charge_tax_id": 982000000567254, "line_items": [ { "line_item_id": 10763000000140068, "account_id": 982000000561057, "description": " ", "amount": 112.5, "tax_id": 982000000566007, "item_order": 1, "product_type": "goods", "acquisition_vat_id": " ", "reverse_charge_vat_id": " ", "reverse_charge_tax_id": 982000000567254, "tax_exemption_id": 982000000567267 } ], "end_date": " ", "recurrence_frequency": "months", "repeat_every": 1, "amount": 112.5, "vat_treatment": "eu_vat_not_registered", "product_type": "goods", "acquisition_vat_id": " ", "reverse_charge_vat_id": " ", "tax_id": 982000000566007, "is_inclusive_tax": false, "is_billable": true, "customer_id": 982000000567001, "project_id": " ", "currency_id": 982000000567001, "exchange_rate": 1 }'

Response Example

  
HTTP/1.1 200 OK Content-Type:application/json;charset=UTF-8 { "code": 0, "message": "Recurring expense information has been updated", "recurring_expense": { "account_id": 982000000561057, "recurrence_name": "Monthly Rental", "start_date": "2016-11-19T00:00:00.000Z", "end_date": " ", "is_pre_gst": false, "source_of_supply": "AP", "destination_of_supply": "TN", "gst_no": "22AAAAA0000A1Z5", "gst_treatment": "business_gst", "destination_of_supply_state": "AP", "hsn_or_sac": 80540, "vat_treatment": "eu_vat_not_registered", "reverse_charge_tax_id": 982000000567254, "reverse_charge_tax_name": "inter", "reverse_charge_tax_percentage": 10, "reverse_charge_tax_amount": 10, "is_reverse_charge_applied": false, "acquisition_vat_total": 0, "reverse_charge_vat_total": 10, "acquisition_vat_summary": [ { "tax_name": "SalesTax", "tax_amount": 11.85 } ], "reverse_charge_vat_summary": [ { "tax_name": "SalesTax", "tax_amount": 11.85 } ], "recurrence_frequency": "months", "repeat_every": 1, "amount": 120.5, "total": 128.25, "sub_total": 90, "bcy_total": 100, "product_type": "goods", "acquisition_vat_id": " ", "reverse_charge_vat_id": " ", "tax_id": 982000000566007, "tax_name": "SalesTax", "tax_percentage": 10.5, "created_time": "2013-11-18T02:17:40-0800", "last_modified_time": "2013-12-18T02:17:40-0800", "is_inclusive_tax": false, "is_billable": true, "customer_id": 982000000567001, "currency_id": 982000000567001, "exchange_rate": 1, "project_id": " ", "project_name": " ", "line_item": { "line_item_id": 10763000000140068, "account_id": 982000000561057, "account_name": "Rent", "description": " ", "tax_amount": 11.85, "tax_id": 982000000566007, "tax_name": "SalesTax", "tax_type": "tax", "tax_percentage": 10.5, "item_total": 100, "item_order": 1, "hsn_or_sac": 80540, "reverse_charge_tax_id": 982000000567254, "reverse_charge_tax_name": "inter", "reverse_charge_tax_percentage": 10, "reverse_charge_tax_amount": 10 } } }

ARGUMENTS

account_id
Required
Unique ID of an account
recurrence_name
Required
Name of the Recurring Expense. Maximum length [100]
start_date
Required
Start date of the recurring expense. Expenses will not be generated for dates prior to the current date. Format [yyyy-mm-dd].
gst_no
India Edition only.
Optional
15 digit GST identification number of the vendor.
source_of_supply
India Edition only.
Optional
Place from where the goods/services are supplied. (If not given, place of contact given for the contact will be taken)
destination_of_supply
India Edition only.
Optional
Place where the goods/services are supplied to. (If not given, organisation's home state will be taken)
reverse_charge_tax_id
India Edition only.
Optional
Enter reverse charge tax ID
Optional
line_item_id
Optional
Unique ID of Item listed
account_id
Required
Unique ID of an account
description
Optional
Search recurring expenses by description. Maximum length [100]
amount
Required
Recurring Expense amount.
tax_id
Optional
Unique ID for the tax
item_order
Optional
Order of items
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: goods and service.
acquisition_vat_id
UK Edition only
Optional
This is the ID of the tax applied in case this is an EU - goods expense and acquisition VAT needs to be reported.
reverse_charge_vat_id
India Edition and UK Edition only
Optional
This is the ID of the tax applied in case this is a non UK - service expense and reverse charge VAT needs to be reported.
reverse_charge_tax_id
India Edition only.
Optional
Enter reverse charge tax ID
tax_exemption_code
India Edition only.
Optional
Enter the code for tax exemption
tax_exemption_id
India Edition only.
Optional
Enter ID of the tax exemption
end_date
Optional
Date on which recurring expense has to expire. Can be left as empty to run forever. Format [yyyy-mm-dd].
recurrence_frequency
Required
Frequency of the recurrance
repeat_every
Required
The cycle of recurrance
amount
Required
Recurring Expense amount.
vat_treatment
UK Edition only
Optional
VAT treatment for the expense. VAT treatment denotes the location of the vendor, if the vendor resides in UK then the VAT treatment is uk. If the vendor is in an EU country & if he is VAT registered then his VAT treatment is eu_vat_registered, if he resides in EU & if he is not VAT registered then his VAT treatment is eu_vat_not_registered and if he resides outside the EU then his VAT treatment is non_eu.
product_type
UK Edition only
Optional
Type of the expense. This denotes whether the expense is to be treated as a goods or service purchase. Allowed Values: goods and service.
acquisition_vat_id
UK Edition only
Optional
This is the ID of the tax applied in case this is an EU - goods expense and acquisition VAT needs to be reported.
reverse_charge_vat_id
India Edition and UK Edition only
Optional
This is the ID of the tax applied in case this is a non UK - service expense and reverse charge VAT needs to be reported.
tax_id
Optional
Unique ID for the tax
is_inclusive_tax
Optional
To check if the total is inclusive of tax
is_billable
Optional
To check if the expense is billable
customer_id
Optional
Search expenses by customer id.
project_id
Optional
Unique ID of the tax applied
currency_id
Optional
Unique ID of the currency used
exchange_rate
Optional
Foreign exchange rate

List recurring expenses

List all the Expenses with pagination.

GET /recurringexpenses

Request Example

  
$ curl https://invoice.zoho.com/api/v3/recurringexpenses?authtoken=ba4604e8e433g9c892e360d53463oec5&organization_id=10234695 -H "Authorization: Zoho-authtoken ba4604e8e433g9c892e360d53463oec5" -H "Content-Type: application/json;charset=UTF-8"

Response Example

  
HTTP/1.1 200 OK Content-Type:application/json;charset=UTF-8 { "code": 0, "message": "success", "recurring_expenses": [ { "recurring_expense_id": 982000000567240, "recurrence_name": "Monthly Rental", "recurrence_frequency": "months", "repeat_every": 1, "last_created_date": "2013-11-18T00:00:00.000Z", "next_expense_date": "2013-12-18T00:00:00.000Z", "account_name": "Rent", "description": " ", "currency_id": 982000000567001, "currency_code": "USD", "total": 128.25, "is_billable": true, "customer_name": "Bowman & Co", "status": "active", "created_time": "2013-11-18T02:17:40-0800", "last_modified_time": "2013-12-18T02:17:40-0800" }, {...}, {...} ] }

Query Params

recurrence_name
Optional
Search recurring expenses by recurring expense name. Variants: recurrence_name_startswith and recurrence_name_contains. Maximum length [100]
last_created_date
Optional
Search recurring expenses by date on when last expense was generated. Variants: last_created_date_start, last_created_date_end, last_created_date_before and last_created_date_after . Format [yyyy-mm-dd]
next_expense_date
Optional
Search recurring expenses by date on which next expense will be generated. Variants: next_expense_date_start, next_expense_date_end, next_expense_date_before and next_expense_date_after . Format [yyyy-mm-dd]
status
Optional
Search expenses by expense status. Allowed Values active, stopped and expired
account_id
Optional
Unique ID of an account
account_name
Optional
Search expenses by expense account name. Variants account_name_startswith and account_name_contains . Maximum length [100]
amount
Optional
Search expenses by amount. Variants: amount_less_than, amount_less_equals, amount_greater_than and amount_greater_than
customer_name
Optional
Search expenses by customer name. Variants: customer_name_startswith and customer_name_contains . Maximum length [100]
customer_id
Optional
Search expenses by customer id.
paid_through_account_id
Optional
Search expenses by paid through account id.
filter_by
Optional
Filter expenses by expense status. Allowed Values Status.All, Status.Active, Status.Expired and Status.Stopped
search_text
Optional
Search expenses by account name or description or customer name or vendor name. Maximum length [100] .
sort_column
Optional
Sort expenses.Allowed Values next_expense_date, account_name, total, last_created_date, recurrence_name, customer_name and created_time

Get a recurring expense

Get the details of the recurring expense

GET /recurringexpenses/{recurring_expense_id}

Request Example

  
$ curl https://invoice.zoho.com/api/v3/recurringexpenses/{recurring_expense_id}?authtoken=ba4604e8e433g9c892e360d53463oec5&organization_id=10234695 -H "Authorization: Zoho-authtoken ba4604e8e433g9c892e360d53463oec5" -H "Content-Type: application/json;charset=UTF-8"

Response Example

  
HTTP/1.1 200 OK Content-Type:application/json;charset=UTF-8 { "code": 0, "message": "success", "recurring_expense": { "recurring_expense_id": 982000000567240, "recurrence_name": "Monthly Rental", "start_date": "2016-11-19T00:00:00.000Z", "end_date": " ", "is_pre_gst": false, "source_of_supply": "AP", "destination_of_supply": "TN", "gst_no": "22AAAAA0000A1Z5", "gst_treatment": "business_gst", "destination_of_supply_state": "AP", "hsn_or_sac": 80540, "vat_treatment": "eu_vat_not_registered", "reverse_charge_tax_id": 982000000567254, "reverse_charge_tax_name": "inter", "reverse_charge_tax_percentage": 10, "reverse_charge_tax_amount": 10, "is_reverse_charge_applied": false, "acquisition_vat_total": 0, "reverse_charge_vat_total": 10, "acquisition_vat_summary": [ { "tax_name": "SalesTax", "tax_amount": 11.85 } ], "reverse_charge_vat_summary": [ { "tax_name": "SalesTax", "tax_amount": 11.85 } ], "recurrence_frequency": "months", "repeat_every": 1, "last_created_date": "2013-11-18T00:00:00.000Z", "next_expense_date": "2013-12-18T00:00:00.000Z", "account_id": 982000000561057, "account_name": "Rent", "currency_id": 982000000567001, "currency_code": "USD", "exchange_rate": 1, "tax_id": 982000000566007, "tax_name": "SalesTax", "tax_percentage": 10.5, "tax_amount": 11.85, "sub_total": 90, "total": 128.25, "bcy_total": 100, "amount": 112.5, "description": " ", "is_inclusive_tax": false, "is_billable": true, "customer_id": 982000000567001, "customer_name": "Bowman & Co", "status": "active", "created_time": "2013-11-18T02:17:40-0800", "last_modified_time": "2013-12-18T02:17:40-0800", "project_id": " ", "project_name": " ", "line_item": { "line_item_id": 10763000000140068, "account_id": 982000000561057, "account_name": "Rent", "description": " ", "tax_amount": 11.85, "tax_id": 982000000566007, "tax_name": "SalesTax", "tax_type": "tax", "tax_percentage": 10.5, "item_total": 100, "item_order": 1, "hsn_or_sac": 80540, "reverse_charge_tax_id": 982000000567254, "reverse_charge_tax_name": "inter", "reverse_charge_tax_percentage": 10, "reverse_charge_tax_amount": 10 } } }

Delete a recurring expense

Deleting an existing recurring expense

DELETE /recurringexpenses/{recurring_expense_id}

Request Example

  
$ curl https://invoice.zoho.com/api/v3 /recurringexpenses/{recurring_expense_id}?authtoken=ba4604e8e433g9c892e360d53463oec5&organization_id=10234695 -H "Authorization: Zoho-authtoken ba4604e8e433g9c892e360d53463oec5" -H "Content-Type: application/json;charset=UTF-8"

Response Example

  
HTTP/1.1 200 OK Content-Type:application/json;charset=UTF-8 { "code": 0, "message": "The recurring expense has been deleted." }

Stop a recurring expense

Stop an active recurring expense

POST /recurringexpenses/{recurring_expense_id}/status/stop

Request Example

  
$ curl https://invoice.zoho.com/api/v3/recurringexpenses/{recurring_expense_id}/status/stop?authtoken=ba4604e8e433g9c892e360d53463oec5&organization_id=10234695 -H "Authorization: Zoho-authtoken ba4604e8e433g9c892e360d53463oec5" -H "Content-Type: application/json;charset=UTF-8"

Response Example

  
HTTP/1.1 200 OK Content-Type:application/json;charset=UTF-8 { "code": 0, "message": "The recurring expense has been stopped." }

Resume a recurring Expense

Resume a stopped recurring expense.

POST /recurringexpenses/{recurring_expense_id}/status/resume

Request Example

  
$ curl https://invoice.zoho.com/api/v3/recurringexpenses/{recurring_expense_id}/status/resume?authtoken=ba4604e8e433g9c892e360d53463oec5&organization_id=10234695 -H "Authorization: Zoho-authtoken ba4604e8e433g9c892e360d53463oec5" -H "Content-Type: application/json;charset=UTF-8"

Response Example

  
HTTP/1.1 200 OK Content-Type:application/json;charset=UTF-8 { "code": 0, "message": "The recurring expense has been activated." }

List child expenses created

List child expenses created from recurring expense.

GET /recurringexpenses/{recurring_expense_id}/expenses

Request Example

  
$ curl https://invoice.zoho.com/api/v3/recurringexpenses/{recurring_expense_id}/expenses?authtoken=ba4604e8e433g9c892e360d53463oec5&organization_id=10234695 -H "Authorization: Zoho-authtoken ba4604e8e433g9c892e360d53463oec5" -H "Content-Type: application/json;charset=UTF-8"

Response Example

  
HTTP/1.1 200 OK Content-Type:application/json;charset=UTF-8 { "code": 0, "message": "success", "expensehistory": [ { "expense_id": 982000000567250, "date": "2013-11-18", "account_name": "Rent", "customer_name": "Bowman & Co", "total": 128.25, "status": "active", "vendor_name": " ", "paid_through_account_name": "Undeposited Funds" }, {...}, {...} ] }

Query Params

sort_column
Optional
Sort expenses.Allowed Values next_expense_date, account_name, total, last_created_date, recurrence_name, customer_name and created_time

List recurring expense history

Get history and comments of a recurring expense.

GET /recurringexpenses/{recurring_expense_id}/comments

Request Example

  
$ curl https://invoice.zoho.com/api/v3/recurringexpenses/{recurring_expense_id}/comments?authtoken=ba4604e8e433g9c892e360d53463oec5&organization_id=10234695 -H "Authorization: Zoho-authtoken ba4604e8e433g9c892e360d53463oec5" -H "Content-Type: application/json;charset=UTF-8"

Response Example

  
HTTP/1.1 200 OK Content-Type:application/json;charset=UTF-8 { "code": 0, "message": "success", "comments": [ { "comment_id": 982000000567272, "recurring_expense_id": 982000000567240, "description": " ", "commented_by_id": 982000000554041, "commented_by": "John David", "date": "2013-11-18", "time": "2.41 AM", "operation_type": "Added", "transaction_id": " ", "transaction_type": "expense" }, {...}, {...} ] }

Projects

A project is a series of tasks performed over a period of time, to achieve certain targets. There can be many number of people working on a single project and a project may consist of single or multiple tasks. A project is billed and charged upon a customer whom the project was taken up for.

Example

{ "project_name": "REAL TIME TRAFFIC FLUX", "customer_id": "460000000044001", "billing_type": "fixed_cost_for_project", "user_id": "460000000024003" }

Attribute

project_name
string
Name of the project. Maximum length [100]
customer_id
string
Unique ID of the customer.
billing_type
string
The way you bill your customer. Allowed Values: fixed_cost_for_project, based_on_project_hours, based_on_staff_hours and based_on_task_hours
user_id
string
ID of the user to be added to the project.

Create a project

Get the details of a project.

POST /projects

Request Example

  
$ curl https://invoice.zoho.com/api/v3/projects?authtoken=ba4604e8e433g9c892e360d53463oec5&organization_id=10234695 -H "Authorization: Zoho-authtoken ba4604e8e433g9c892e360d53463oec5" -H "Content-Type: application/json;charset=UTF-8" -d JSONString='{ "project_name": "Network Distribution", "customer_id": "460000000044001", "description": "Distribution for the system of intermediaries between the producer of goods and/or services and the final user", "billing_type": "based_on_task_hours", "rate": " ", "budget_type": " ", "budget_hours": " ", "budget_amount": " ", "user_id": "INV-00003", "tasks": [ { "task_name": "Distribution Analysis", "description": "Distribution for the system of intermediaries between the producer of goods and/or services and the final user", "rate": " ", "budget_hours": " " } ], "users": [ { "user_id": "INV-00003", "is_current_user": true, "user_name": "John David", "email": "johndavid@zilliuminc.com", "user_role": "admin", "status": "active", "rate": " ", "budget_hours": " ", "total_hours": "12:26", "billed_hours": "12:27", "un_billed_hours": "00:00" } ] }'

Response Example

  
HTTP/1.1 201 Created Content-Type:application/json;charset=UTF-8 { "code": 0, "message": "The project has been created.", "project": { "project_id": "460000000044019", "project_name": "REAL TIME TRAFFIC FLUX", "customer_id": "460000000044001", "customer_name": "SAF Instruments Inc", "currency_code": "USD", "description": "A simple algorithm is to be tested with vehicle detection application.", "status": "active", "billing_type": "fixed_cost_for_project", "rate": 5000, "budget_type": " ", "total_hours": "12:26", "total_amount": 500, "billed_hours": "12:27", "billed_amount": 500, "un_billed_hours": "00:00", "un_billed_amount": 0, "billable_hours": "12:26", "billable_amount": 500, "non_billable_hours": "0.00", "non_billable_amount": 0, "is_recurrence_associated": false, "recurring_invoices": [ {...} ], "created_time": "2013-11-18T18:05:27+0530", "show_in_dashboard": true, "tasks": [ { "task_id": "460000000044009", "task_name": "Distribution Analysis", "description": "A simple algorithm is to be tested with vehicle detection application.", "rate": 5000, "budget_hours": "0", "total_hours": "12:26", "billed_hours": "12:27", "un_billed_hours": "00:00", "non_billable_hours": "0.00", "status": "active", "is_billable": true, "task_custom_fields": "" } ], "users": [ { "user_id": "460000000024003", "is_current_user": true, "user_name": "John David", "email": "johndavid@zilliuminc.com", "user_role": "admin", "status": "active", "rate": 5000, "budget_hours": "0", "total_hours": "12:26", "billed_hours": "12:27", "un_billed_hours": "00:00" } ] } }

ARGUMENTS

project_name
Required
Name of the project. Maximum length [100]
customer_id
Required
ID of the customer.
description
Optional
Project description. Maximu length [500]
billing_type
Required
The way you bill your customer. Allowed Values: fixed_cost_for_project, based_on_project_hours, based_on_staff_hours and based_on_task_hours
rate
Optional
Hourly rate for a task.
budget_type
Optional
The way you budget. Allowed Values: total_project_cost, total_project_hours, hours_per_task and hours_per_staff
budget_hours
Optional
Task budget hours
budget_amount
Optional
Give value, if you are estimating total project cost.
user_id
Required
ID of the user to be added to the project.
rate
Optional
Hourly rate for a task.
budget_hours
Optional
Task budget hours
Optional
Tasks comprising a project
task_name
Required
Name of the task performed in a project
description
Optional
Project description. Maximu length [500]
rate
Optional
Hourly rate for a task.
budget_hours
Optional
Task budget hours
Optional
Users of a project
user_id
Required
ID of the user to be added to the project.
is_current_user
Optional
user_name
Optional
Name of the user. Maximum length [200]
email
Optional
Email of the user. Maximum length [100]
user_role
Optional
Role to be assigned. Allowed Values: staff, admin and timesheetstaff
status
Optional
Project Status
rate
Optional
Hourly rate for a task.
budget_hours
Optional
Task budget hours
total_hours
Optional
Total hours spent on project
billed_hours
Optional
Total duration/hours of a project that is billed
un_billed_hours
Optional
Hours of the project that cannot be billed

Update a project

Update details of a project.

PUT /projects/{project_id}

Request Example

  
$ curl https://invoice.zoho.com/api/v3/projects/{project_id}?authtoken=ba4604e8e433g9c892e360d53463oec5&organization_id=10234695 -H "Authorization: Zoho-authtoken ba4604e8e433g9c892e360d53463oec5" -H "Content-Type: application/json;charset=UTF-8" -d JSONString='{ "project_name": "Network Distribution", "customer_id": "460000000044001", "description": "Distribution for the system of intermediaries between the producer of goods and/or services and the final user", "billing_type": "based_on_task_hours", "rate": " ", "budget_type": " ", "budget_hours": " ", "budget_amount": " ", "user_id": "INV-00003", "tasks": [ { "task_name": "Distribution Analysis", "description": "Distribution for the system of intermediaries between the producer of goods and/or services and the final user", "rate": " ", "budget_hours": " " } ], "users": [ { "user_id": "INV-00003", "is_current_user": true, "user_name": "John David", "email": "johndavid@zilliuminc.com", "user_role": "admin", "status": "active", "rate": " ", "budget_hours": " ", "total_hours": "12:26", "billed_hours": "12:27", "un_billed_hours": "00:00" } ] }'

Response Example

  
HTTP/1.1 200 OK Content-Type:application/json;charset=UTF-8 { "code": 0, "message": "The project information has been updated.", "project": { "project_id": "460000000044019", "project_name": "REAL TIME TRAFFIC FLUX", "customer_id": "460000000044001", "customer_name": "SAF Instruments Inc", "currency_code": "USD", "description": "A simple algorithm is to be tested with vehicle detection application.", "status": "active", "billing_type": "fixed_cost_for_project", "rate": 5000, "budget_type": " ", "total_hours": "12:26", "total_amount": 500, "billed_hours": "12:27", "billed_amount": 500, "un_billed_hours": "00:00", "un_billed_amount": 0, "billable_hours": "12:26", "billable_amount": 500, "non_billable_hours": "0.00", "non_billable_amount": 0, "is_recurrence_associated": false, "recurring_invoices": [ {...} ], "created_time": "2013-11-18T18:05:27+0530", "show_in_dashboard": true, "tasks": [ { "task_id": "460000000044009", "task_name": "Distribution Analysis", "description": "A simple algorithm is to be tested with vehicle detection application.", "rate": 5000, "budget_hours": "0", "total_hours": "12:26", "billed_hours": "12:27", "un_billed_hours": "00:00", "non_billable_hours": "0.00", "status": "active", "is_billable": true, "task_custom_fields": "" } ], "users": [ { "user_id": "460000000024003", "is_current_user": true, "user_name": "John David", "email": "johndavid@zilliuminc.com", "user_role": "admin", "status": "active", "rate": 5000, "budget_hours": "0", "total_hours": "12:26", "billed_hours": "12:27", "un_billed_hours": "00:00" } ] } }

ARGUMENTS

project_name
Required
Name of the project. Maximum length [100]
customer_id
Required
ID of the customer.
description
Optional
Project description. Maximum length [500]
billing_type
Required
The way you bill your customer. Allowed Values: fixed_cost_for_project, based_on_project_hours, based_on_staff_hours and based_on_task_hours
rate
Optional
Hourly rate for a task.
budget_type
Optional
The way you budget. Allowed Values: total_project_cost, total_project_hours, hours_per_task and hours_per_staff
budget_hours
Optional
Task budget hours
budget_amount
Optional
Give value, if you are estimating total project cost.
user_id
Required
ID of the user to be added to the project.
rate
Optional
Hourly rate for a task.
budget_hours
Optional
Task budget hours
Optional
Tasks comprising a project
task_name
Required
Name of the task performed in a project
description
Optional
Project description. Maximum length [500]
rate
Optional
Hourly rate for a task.
budget_hours
Optional
Task budget hours
Optional
Users of a project
user_id
Required
ID of the user to be added to the project.
is_current_user
Optional
user_name
Optional
Name of the user. Maximum length [200]
email
Optional
Email of the user. Maximum length [100]
user_role
Optional
Role to be assigned. Allowed Values: staff, admin and timesheetstaff
status
Optional
Project Status
rate
Optional
Hourly rate for a task.
budget_hours
Optional
Task budget hours
total_hours
Optional
Total hours spent on project
billed_hours
Optional
Total duration/hours of a project that is billed
un_billed_hours
Optional
Hours of the project that cannot be billed

List projects

List all projects with pagination.

GET /projects

Request Example

  
$ curl https://invoice.zoho.com/api/v3/projects?authtoken=ba4604e8e433g9c892e360d53463oec5&organization_id=10234695 -H "Authorization: Zoho-authtoken ba4604e8e433g9c892e360d53463oec5" -H "Content-Type: application/json;charset=UTF-8"

Response Example

  
HTTP/1.1 200 OK Content-Type:application/json;charset=UTF-8 { "code": 0, "message": "success", "projects": [ { "project_id": "460000000044019", "project_name": "REAL TIME TRAFFIC FLUX", "customer_id": "460000000044001", "customer_name": "SAF Instruments Inc", "description": "A simple algorithm is to be tested with vehicle detection application.", "status": "active", "billing_type": "fixed_cost_for_project", "rate": 5000, "created_time": "2013-11-18T18:05:27+0530", "has_attachment": false, "total_hours": "12:26", "billable_hours": "12:26" }, {...}, {...} ] }

Query Params

filter_by
Optional
Filter projects by any status. Allowed Values: Status.All, Status.Active and Status.Inactive
customer_id
Optional
Unique ID of the customer.
sort_column
Optional
Sort projects. Allowed Values: project_name, customer_name, rate and created_time

Get a project

Get the details of a project.

GET /projects/{project_id}

Request Example

  
$ curl https://invoice.zoho.com/api/v3/projects/{project_id}?authtoken=ba4604e8e433g9c892e360d53463oec5&organization_id=10234695 -H "Authorization: Zoho-authtoken ba4604e8e433g9c892e360d53463oec5" -H "Content-Type: application/json;charset=UTF-8"

Response Example

  
HTTP/1.1 200 OK Content-Type:application/json;charset=UTF-8 { "code": 0, "message": "success", "project": { "project_id": "460000000044019", "project_name": "REAL TIME TRAFFIC FLUX", "customer_id": "460000000044001", "customer_name": "SAF Instruments Inc", "currency_code": "USD", "description": "A simple algorithm is to be tested with vehicle detection application.", "status": "active", "billing_type": "fixed_cost_for_project", "rate": 5000, "budget_type": " ", "total_hours": "12:26", "total_amount": 500, "billed_hours": "12:27", "billed_amount": 500, "un_billed_hours": "00:00", "un_billed_amount": 0, "billable_hours": "12:26", "billable_amount": 500, "non_billable_hours": "0.00", "non_billable_amount": 0, "is_recurrence_associated": false, "recurring_invoices": [ {...} ], "created_time": "2013-11-18T18:05:27+0530", "show_in_dashboard": true, "tasks": [ { "task_id": "460000000044009", "task_name": "Distribution Analysis", "description": "A simple algorithm is to be tested with vehicle detection application.", "rate": 5000, "budget_hours": "0", "total_hours": "12:26", "billed_hours": "12:27", "un_billed_hours": "00:00", "non_billable_hours": "0.00", "status": "active", "is_billable": true, "task_custom_fields": "" } ] } }

Delete a project

Deleting a existing project.

DELETE /projects/{project_id}

Request Example

  
$ curl https://invoice.zoho.com/api/v3/projects/{project_id}?authtoken=ba4604e8e433g9c892e360d53463oec5&organization_id=10234695 -H "Authorization: Zoho-authtoken ba4604e8e433g9c892e360d53463oec5" -H "Content-Type: application/json;charset=UTF-8"

Response Example

  
HTTP/1.1 200 OK Content-Type:application/json;charset=UTF-8 { "code": 0, "message": "The project has been deleted." }

Activate a project

Mark project as active

POST /projects/{project_id}/active

Request Example

  
$ curl https://invoice.zoho.com/api/v3/projects/{project_id}/active?authtoken=ba4604e8e433g9c892e360d53463oec5&organization_id=10234695 -H "Authorization: Zoho-authtoken ba4604e8e433g9c892e360d53463oec5" -H "Content-Type: application/json;charset=UTF-8"

Response Example

  
HTTP/1.1 200 OK Content-Type:application/json;charset=UTF-8 { "code": 0, "message": "The selected Projects have been marked as active." }

Deactivate a project

Marking a project as inactive.

POST /projects/{project_id}/inactive

Request Example

  
$ curl https://invoice.zoho.com/api/v3/projects/{project_id}/inactive?authtoken=ba4604e8e433g9c892e360d53463oec5&organization_id=10234695 -H "Authorization: Zoho-authtoken ba4604e8e433g9c892e360d53463oec5" -H "Content-Type: application/json;charset=UTF-8"

Response Example

  
HTTP/1.1 200 OK Content-Type:application/json;charset=UTF-8 { "code": 0, "message": "The selected projects have been marked as inactive." }

Clone a project

Cloning the settings of an existing project

POST /projects/{project_id}/clone

Request Example

  
$ curl https://invoice.zoho.com/api/v3/projects/{project_id}/clone?authtoken=ba4604e8e433g9c892e360d53463oec5&organization_id=10234695 -H "Authorization: Zoho-authtoken ba4604e8e433g9c892e360d53463oec5" -H "Content-Type: application/json;charset=UTF-8" -d JSONString='{ "project_name": "Network Distribution", "description": "Distribution for the system of intermediaries between the producer of goods and/or services and the final user" }'

Response Example

  
HTTP/1.1 200 OK Content-Type:application/json;charset=UTF-8 { "code": 0, "message": "Project has been cloned successfully.", "project": { "project_id": "460000000044019", "project_name": "REAL TIME TRAFFIC FLUX", "customer_id": "460000000044001", "customer_name": "SAF Instruments Inc", "currency_code": "USD", "description": "A simple algorithm is to be tested with vehicle detection application.", "status": "active", "billing_type": "fixed_cost_for_project", "rate": 5000, "budget_type": " ", "total_hours": "12:26", "total_amount": 500, "billed_hours": "12:27", "billed_amount": 500, "un_billed_hours": "00:00", "un_billed_amount": 0, "billable_hours": "12:26", "billable_amount": 500, "non_billable_hours": "0.00", "non_billable_amount": 0, "is_recurrence_associated": false, "recurring_invoices": [ {...} ], "created_time": "2013-11-18T18:05:27+0530", "show_in_dashboard": true, "tasks": [ { "task_id": "460000000044009", "task_name": "Distribution Analysis", "description": "A simple algorithm is to be tested with vehicle detection application.", "rate": 5000, "budget_hours": "0", "total_hours": "12:26", "billed_hours": "12:27", "un_billed_hours": "00:00", "non_billable_hours": "0.00", "status": "active", "is_billable": true, "task_custom_fields": "" } ], "users": [ { "user_id": "460000000024003", "is_current_user": true, "user_name": "John David", "email": "johndavid@zilliuminc.com", "user_role": "admin", "status": "active", "rate": 5000, "budget_hours": "0", "total_hours": "12:26", "billed_hours": "12:27", "un_billed_hours": "00:00" } ] } }

ARGUMENTS

project_name
Required
Name of the project. Maximum length [100]
description
Optional
Project description. Maximum length [500]

Assign users

Assign a users to a project

POST /projects/{project_id}/users

Request Example

  
$ curl https://invoice.zoho.com/api/v3/projects/{project_id}/users?authtoken=ba4604e8e433g9c892e360d53463oec5&organization_id=10234695 -H "Authorization: Zoho-authtoken ba4604e8e433g9c892e360d53463oec5" -H "Content-Type: application/json;charset=UTF-8" -d JSONString='{ "user_id": "INV-00003", "rate": 5000, "budget_hours": "0" }'

Response Example

  
HTTP/1.1 201 Created Content-Type:application/json;charset=UTF-8 { "code": 0, "message": "Users added.", "users": [ { "user_id": "460000000024003", "is_current_user": true, "user_name": "John David", "email": "johndavid@zilliuminc.com", "user_role": "admin", "status": "active", "rate": 5000, "budget_hours": "0" } ] }

ARGUMENTS

user_id
Required
ID of the user to be added to the project.
rate
Optional
Total project cost
budget_hours
Optional
Planned hours for completion of project

Invite user

Invite a user to the project

POST /projects/{project_id}/users/invite

Request Example

  
$ curl https://invoice.zoho.com/api/v3 /projects/{project_id}/users/invite?authtoken=ba4604e8e433g9c892e360d53463oec5&organization_id=10234695 -H "Authorization: Zoho-authtoken ba4604e8e433g9c892e360d53463oec5" -H "Content-Type: application/json;charset=UTF-8" -d JSONString='{ "user_name": "John David", "email": "johndavid@zilliuminc.com", "user_role": "admin", "rate": " ", "budget_hours": "0" }'

Response Example

  
HTTP/1.1 201 Created Content-Type:application/json;charset=UTF-8 { "code": 0, "message": "The staff has been added.", "users": [ { "user_id": "460000000024003", "user_name": "John David", "email": "johndavid@zilliuminc.com", "user_role": "admin", "is_current_user": true } ] }

ARGUMENTS

user_name
Required
Name of the user. Maximum length [200]
email
Required
Email of the user. Maximum length [100]
user_role
Optional
Role to be assigned. Allowed Values: staff, admin and timesheetstaff
rate
Optional
Hourly rate for a task.
budget_hours
Optional
Planned hours for completion of project

Update user

Update details of a user

PUT /projects/{project_id}/users/{user_id}

Request Example

  
$ curl https://invoice.zoho.com/api/v3/projects/{project_id}/users/{user_id}?authtoken=ba4604e8e433g9c892e360d53463oec5&organization_id=10234695 -H "Authorization: Zoho-authtoken ba4604e8e433g9c892e360d53463oec5" -H "Content-Type: application/json;charset=UTF-8" -d JSONString='{ "user_name": "John David", "user_role": "admin", "rate": 5000, "budget_hours": "0" }'

Response Example

  
HTTP/1.1 200 OK Content-Type:application/json;charset=UTF-8 { "code": 0, "message": "The staff information has been updated.", "users": [ { "user_id": "460000000024003", "user_name": "John David", "email": "johndavid@zilliuminc.com", "user_role": "admin", "is_current_user": true } ] }

ARGUMENTS

user_name
Optional
Name of the user. Maximum length [200]
user_role
Optional
Role to be assigned. Allowed Values: staff, admin and timesheetstaff
rate
Optional
Total project cost
budget_hours
Optional
Planned hours for completion of project

List Users

Get list of all users associated to a project.

GET /projects/{project_id}/users

Request Example

  
$ curl https://invoice.zoho.com/api/v3/projects/{project_id}/users?authtoken=ba4604e8e433g9c892e360d53463oec5&organization_id=10234695 -H "Authorization: Zoho-authtoken ba4604e8e433g9c892e360d53463oec5" -H "Content-Type: application/json;charset=UTF-8"

Response Example

  
HTTP/1.1 200 OK Content-Type:application/json;charset=UTF-8 { "code": 0, "message": "success", "users": [ { "user_id": "460000000024003", "is_current_user": true, "user_name": "John David", "email": "johndavid@zilliuminc.com", "user_role": "admin", "status": "active", "rate": 5000, "budget_hours": "0" }, {...}, {...} ] }

Get a User

Get details of a user in project

GET /projects/{project_id}/users/{user_id}

Request Example

  
$ curl https://invoice.zoho.com/api/v3/projects/{project_id}/users/{user_id}?authtoken=ba4604e8e433g9c892e360d53463oec5&organization_id=10234695 -H "Authorization: Zoho-authtoken ba4604e8e433g9c892e360d53463oec5" -H "Content-Type: application/json;charset=UTF-8"

Response Example

  
HTTP/1.1 200 OK Content-Type:application/json;charset=UTF-8 { "code": 0, "message": "success", "users": { "user_id": "460000000024003", "is_current_user": true, "user_name": "John David", "email": "johndavid@zilliuminc.com", "user_role": "admin" } }

Delete user

Remove user from a project

DELETE /projects/{project_id}/users/{user_id}

Request Example

  
$ curl https://invoice.zoho.com/api/v3/projects/{project_id}/users/{user_id}?authtoken=ba4604e8e433g9c892e360d53463oec5&organization_id=10234695 -H "Authorization: Zoho-authtoken ba4604e8e433g9c892e360d53463oec5" -H "Content-Type: application/json;charset=UTF-8"

Response Example

  
HTTP/1.1 200 OK Content-Type:application/json;charset=UTF-8 { "code": 0, "message": "The staff has been removed" }

Post comment

Post comment to a project

POST /projects/{project_id}/comments

Request Example

  
$ curl https://invoice.zoho.com/api/v3/projects/{project_id}/comments?authtoken=ba4604e8e433g9c892e360d53463oec5&organization_id=10234695 -H "Authorization: Zoho-authtoken ba4604e8e433g9c892e360d53463oec5" -H "Content-Type: application/json;charset=UTF-8" -d JSONString='{ "description": "Billing based on task hours" }'

Response Example

  
HTTP/1.1 201 Created Content-Type:application/json;charset=UTF-8 { "code": 0, "message": "Comments added.", "comments": [ { "project_id": "460000000044019", "comment_id": "460000000044027", "description": "A simple algorithm is to be tested with vehicle detection application.", "commented_by_id": "460000000024003", "commented_by": "John David", "date": "2013-11-18", "date_description": "19 days ago", "time": "6:52 PM" } ] }

ARGUMENTS

description
Required
Project description. Maximum length [500]

List comments

Get comments for a project.

GET /projects/{project_id}/comments

Request Example

  
$ curl https://invoice.zoho.com/api/v3/projects/{project_id}/comments?authtoken=ba4604e8e433g9c892e360d53463oec5&organization_id=10234695 -H "Authorization: Zoho-authtoken ba4604e8e433g9c892e360d53463oec5" -H "Content-Type: application/json;charset=UTF-8"

Response Example

  
HTTP/1.1 200 OK Content-Type:application/json;charset=UTF-8 { "code": 0, "message": "success", "comments": [ { "comment_id": "460000000044027", "project_id": "460000000044019", "description": "A simple algorithm is to be tested with vehicle detection application.", "commented_by_id": "460000000024003", "commented_by": "John David", "is_current_user": true, "date": "2013-11-18", "date_description": "19 days ago", "time": "6:52 PM" }, {...}, {...} ] }

Delete comment

Deleting a comment

DELETE /projects/{project_id}

Request Example

  
$ curl https://invoice.zoho.com/api/v3/projects/{project_id}?authtoken=ba4604e8e433g9c892e360d53463oec5&organization_id=10234695 -H "Authorization: Zoho-authtoken ba4604e8e433g9c892e360d53463oec5" -H "Content-Type: application/json;charset=UTF-8"

Response Example

  
HTTP/1.1 200 OK Content-Type:application/json;charset=UTF-8 { "code": 0, "message": "The comment has been deleted." }

List invoices

Lists invoices created for this project.

GET /projects/{project_id}/invoices

Request Example

  
$ curl https://invoice.zoho.com/api/v3/projects/{project_id}/invoices?authtoken=ba4604e8e433g9c892e360d53463oec5&organization_id=10234695 -H "Authorization: Zoho-authtoken ba4604e8e433g9c892e360d53463oec5" -H "Content-Type: application/json;charset=UTF-8"

Response Example

  
HTTP/1.1 200 OK Content-Type:application/json;charset=UTF-8 { "code": 0, "message": "success", "invoices": [ { "invoice_id": "460000000044001", "customer_name": "SAF Instruments Inc", "status": "active", "invoice_number": "INV-00004", "reference_number": " ", "date": "2013-11-18", "due_date": "2013-11-19", "total": "310.75", "balance": "48.75", "created_time": "2013-11-18T18:05:27+0530" }, {...}, {...} ] }

Query Params

sort_column
Optional
Sort invoices raised. Allowed Values: invoice_number, date, total, balance and created_time

Tasks

A project comprises of a single or multiple tasks that need to be completed. You need to add a task to the project before you log time.

Example

{ "project_id": "90300000072369", "task_id": "90300000072369", "customer_id": "903000000000099", "currency_id": 982000000000190, "task_name": "Painting", "project_name": "Furniture Manufacturing", "customer_name": "David Sujin", "billed_hours": "12:06", "log_time": "13:06", "un_billed_hours": "01:00", "description": "", "rate": 3, "budget_hours": "" }

Attribute

project_id
string
Unique ID of the project generated by the server.
task_id
string
Unique ID of the task generated by the server.
customer_id
string
Customer ID of the customer for whom the task is created.
currency_id
string
The currenct ID of the currency
task_name
string
The name of the task. Maximum length [100]
project_name
string
The name of the project
customer_name
string
Name of the customer to whom the task is created.
billed_hours
double
The total hours that are billed.
log_time
double
Total hours logged in the project.
un_billed_hours
double
Total hours that are unbilled.
description
string
The description of the project.
rate
integer
Hourly rate for a task.
budget_hours
integer
Task budget hours.

Add a task

Adding a new task to a project.

POST /projects/{project_id}/tasks

Request Example

  
$ curl https://invoice.zoho.com/api/v3/projects/{project_id}/tasks?authtoken=ba4604e8e433g9c892e360d53463oec5&organization_id=10234695 -H "Authorization: Zoho-authtoken ba4604e8e433g9c892e360d53463oec5" -H "Content-Type: application/json;charset=UTF-8" -d JSONString='{ "task_name": "Painting", "description": "", "rate": 3, "budget_hours": "" }'

Response Example

  
HTTP/1.1 201 Created Content-Type:application/json;charset=UTF-8 { "code": 0, "message": "The task has been added.", "task": { "project_id": "90300000072369", "task_id": "90300000072369", "currency_id": 982000000000190, "customer_id": "903000000000099", "task_name": "Painting", "project_name": "Furniture Manufacturing", "customer_name": "David Sujin", "billed_hours": "12:06", "log_time": "13:06", "un_billed_hours": "01:00" } }

ARGUMENTS

task_name
Required
The name of the task. Maximum length [100]
description
Optional
The description of the project.
rate
Optional
Hourly rate for a task.
budget_hours
Optional
Task budget hours.

Update a task

Update the details of an existing task.

PUT /projects/{project_id}/tasks/{task_id}

Request Example

  
$ curl https://invoice.zoho.com/api/v3/projects/{project_id}/tasks/{task_id}?authtoken=ba4604e8e433g9c892e360d53463oec5&organization_id=10234695 -H "Authorization: Zoho-authtoken ba4604e8e433g9c892e360d53463oec5" -H "Content-Type: application/json;charset=UTF-8" -d JSONString='{ "task_name": "Painting", "description": "", "rate": 3, "budget_hours": "" }'

Response Example

  
HTTP/1.1 200 OK Content-Type:application/json;charset=UTF-8 { "code": 0, "message": "The task information has been updated.", "task": { "project_id": "90300000072369", "task_id": "90300000072369", "currency_id": 982000000000190, "customer_id": "903000000000099", "task_name": "Painting", "project_name": "Furniture Manufacturing", "customer_name": "David Sujin", "billed_hours": "12:06", "log_time": "13:06", "un_billed_hours": "01:00" } }

ARGUMENTS

task_name
Required
The name of the task. Maximum length [100]
description
Optional
The description of the project.
rate
Optional
Hourly rate for a task.
budget_hours
Optional
Task budget hours.

List tasks

Get list of all the tasks added to a project.

GET /projects/{project_id}/tasks

Request Example

  
$ curl https://invoice.zoho.com/api/v3/projects/{project_id}/tasks?authtoken=ba4604e8e433g9c892e360d53463oec5&organization_id=10234695 -H "Authorization: Zoho-authtoken ba4604e8e433g9c892e360d53463oec5" -H "Content-Type: application/json;charset=UTF-8"

Response Example

  
HTTP/1.1 200 OK Content-Type:application/json;charset=UTF-8 { "code": 0, "message": "success", "tasks": [ { "project_id": "90300000072369", "task_id": "90300000072369", "currency_id": 982000000000190, "customer_id": "903000000000099", "task_name": "Painting", "project_name": "Furniture Manufacturing", "customer_name": "David Sujin", "billed_hours": "12:06", "log_time": "13:06", "un_billed_hours": "01:00" }, {...}, {...} ] }

Get a task

Get the details of a task.

GET /projects/{project_id}/tasks/{task_id}

Request Example

  
$ curl https://invoice.zoho.com/api/v3/projects/{project_id}/tasks/{task_id}?authtoken=ba4604e8e433g9c892e360d53463oec5&organization_id=10234695 -H "Authorization: Zoho-authtoken ba4604e8e433g9c892e360d53463oec5" -H "Content-Type: application/json;charset=UTF-8" -d JSONString='{ "task_id": "90300000072369" }'

Response Example

  
HTTP/1.1 200 OK Content-Type:application/json;charset=UTF-8 { "code": 0, "message": "success", "task": { "project_id": "90300000072369", "project_name": "Furniture Manufacturing", "task_id": "90300000072369", "task_name": "Painting", "description": "", "rate": 3, "status": "active", "is_billable": true } }

ARGUMENTS

task_id
Optional
Unique ID of the task generated by the server.

Delete a Task

Delete a task added to a project.

DELETE /projects/{project_id}/tasks/{task_id}

Request Example

  
$ curl https://invoice.zoho.com/api/v3/projects/{project_id}/tasks/{task_id}?authtoken=ba4604e8e433g9c892e360d53463oec5&organization_id=10234695 -H "Authorization: Zoho-authtoken ba4604e8e433g9c892e360d53463oec5" -H "Content-Type: application/json;charset=UTF-8" -d JSONString='{ "task_id": "90300000072369" }'

Response Example

  
HTTP/1.1 200 OK Content-Type:application/json;charset=UTF-8 { "code": 0, "message": "The task has been deleted successfully." }

ARGUMENTS

task_id
Optional
Unique ID of the task generated by the server.

Time Entries

Time entries are various entries of time made by users in a project, based on the time they spent on a project, in a task.

Example

{ "project_id": "460000000044019", "task_id": "460000000044009", "user_id": "460000000024003", "log_date": "2013-09-17" }

Attribute

project_id
string
Unique ID of the project
task_id
string
Unique ID of the task
user_id
string
Unique ID of the user of timesheet.
log_date
string
Date on which the user spent on the task. Date Format [yyyy-mm-dd]

Log time entries

Logging time entries.

POST /projects/timeentries

Request Example

  
$ curl https://invoice.zoho.com/api/v3/projects/timeentries?authtoken=ba4604e8e433g9c892e360d53463oec5&organization_id=10234695 -H "Authorization: Zoho-authtoken ba4604e8e433g9c892e360d53463oec5" -H "Content-Type: application/json;charset=UTF-8" -d JSONString='{ "project_id": "Network Distribution", "task_id": "460000000044001", "user_id": "460000000024003", "log_date": "2013-09-17", "log_time": " ", "begin_time": "10:00", "end_time": "15:00", "is_billable": true, "notes": " ", "start_timer": " " }'

Response Example

  
HTTP/1.1 201 Created Content-Type:application/json;charset=UTF-8 { "code": 0, "message": "Your timesheet entry has been added.", "time_entry": { "time_entry_id": "460000000044021", "project_id": "460000000044019", "project_name": "REAL TIME TRAFFIC FLUX", "customer_id": "460000000044001", "customer_name": "SAF Instruments Inc", "task_id": "460000000044009", "task_name": "Distribution Analysis", "user_id": "460000000024003", "user_name": "John David", "is_current_user": true, "log_date": "2013-09-17", "begin_time": "03:00", "end_time": "04:00", "log_time": "05:00", "is_billable": true, "billed_status": "unbilled", "invoice_id": "", "notes": " ", "timer_started_at": " ", "timer_started_at_utc_time": "", "timer_duration_in_minutes": " ", "timer_duration_in_seconds": "", "created_time": "2013-09-11T18:05:27+0530", "timesheet_custom_fields": "" } }

ARGUMENTS

project_id
Required
ID of the project.
task_id
Required
ID of the task.
user_id
Required
ID of the user.
log_date
Required
Date on which the user spent on the task. Date Format [yyyy-dd-mm]
log_time
Optional
Time the user spent on this task. Either send this attribute or begin and end time attributes. Time-Format [HH:mm]
begin_time
Optional
Time the user started working on this task. Time-Format [HH:mm]
end_time
Optional
Time the user stopped working on this task. Time-Format [HH:mm]
is_billable
Optional
Whether it is billable or not.
notes
Optional
Description of the work done. Maximum length [500]
start_timer
Optional
Start timer.

Update time entry

Update logged time entry

PUT /projects/timeentries/{time_entry_id}

Request Example

  
$ curl https://invoice.zoho.com/api/v3/projects/timeentries/{time_entry_id}?authtoken=ba4604e8e433g9c892e360d53463oec5&organization_id=10234695 -H "Authorization: Zoho-authtoken ba4604e8e433g9c892e360d53463oec5" -H "Content-Type: application/json;charset=UTF-8" -d JSONString='{ "project_id": "Network Distribution", "task_id": "460000000044001", "user_id": "460000000024003", "log_date": "2013-09-17", "log_time": " ", "begin_time": "10:00", "end_time": "15:00", "is_billable": true, "notes": " ", "start_timer": " " }'

Response Example

  
HTTP/1.1 200 OK Content-Type:application/json;charset=UTF-8 { "code": 0, "message": "The timesheet's information has been updated.", "time_entry": { "time_entry_id": "460000000044021", "project_id": "460000000044019", "project_name": "REAL TIME TRAFFIC FLUX", "customer_id": "460000000044001", "customer_name": "SAF Instruments Inc", "task_id": "460000000044009", "task_name": "Distribution Analysis", "user_id": "460000000024003", "user_name": "John David", "is_current_user": true, "log_date": "2013-09-17", "begin_time": "03:00", "end_time": "04:00", "log_time": "05:00", "is_billable": true, "billed_status": "unbilled", "invoice_id": "", "notes": " ", "timer_started_at": " ", "timer_started_at_utc_time": "", "timer_duration_in_minutes": " ", "timer_duration_in_seconds": "", "created_time": "2013-09-11T18:05:27+0530", "timesheet_custom_fields": "" } }

ARGUMENTS

project_id
Required
ID of the project.
task_id
Required
ID of the task.
user_id
Required
ID of the user.
log_date
Required
Date on which the user spent on the task. Date Format [yyyy-mm-dd]
log_time
Optional
Time the user spent on this task. Either send this attribute or begin and end time attributes. Time Format [HH:mm]
begin_time
Optional
Time the user started working on this task. Time Format [HH:mm]
end_time
Optional
Time the user stopped working on this task. Time Format [HH:mm]
is_billable
Optional
Whether it is billable or not.
notes
Optional
Description of the work done. Maximum length [500]
start_timer
Optional
Start timer.

List time entries.

List all time entries with pagination.

GET /projects/timeentries

Request Example

  
$ curl https://invoice.zoho.com/api/v3/projects/timeentries?authtoken=ba4604e8e433g9c892e360d53463oec5&organization_id=10234695 -H "Authorization: Zoho-authtoken ba4604e8e433g9c892e360d53463oec5" -H "Content-Type: application/json;charset=UTF-8"

Response Example

  
HTTP/1.1 200 OK Content-Type:application/json;charset=UTF-8 { "code": 0, "message": "success", "time_entries": [ { "time_entry_id": "460000000044021", "project_id": "460000000044019", "project_name": "REAL TIME TRAFFIC FLUX", "customer_id": "460000000044001", "customer_name": "SAF Instruments Inc", "task_id": "460000000044009", "task_name": "Distribution Analysis", "user_id": "460000000024003", "is_current_user": true, "user_name": "John David", "log_date": "2013-09-17", "begin_time": "03:00", "end_time": "04:00", "log_time": "05:00", "is_billable": true, "billed_status": "unbilled", "invoice_id": "", "notes": " ", "timer_started_at": " ", "timer_duration_in_minutes": " ", "created_time": "2013-09-11T18:05:27+0530" }, {...}, {...} ] }

Query Params

from_date
Optional
Date from which the time entries logged to be fetched
to_date
Optional
Date up to which the time entries logged to be fetched
filter_by
Optional
Filter time entries by date and status. Allowed Values: Date.All, Date.Today, Date.ThisWeek, Date.ThisMonth, Date.ThisQuarter, Date.ThisYear, Date.PreviousDay, Date.PreviousWeek, Date.PreviousMonth, Date.PreviousQuarter, Date.PreviousYear, Date.CustomDate, Status.Unbilled and Status.Invoiced
project_id
Optional
Unique ID of the project
user_id
Optional
Unique ID of the user of timesheet.
sort_column
Optional
Sort time entries. Allowed Values: project_name, task_name, user_name, log_date, timer_started_at and customer_name

Get a time entry

Get details of a time entry.

GET /projects/timeentries/{time_entry_id}

Request Example

  
$ curl https://invoice.zoho.com/api/v3/projects/timeentries/{time_entry_id}?authtoken=ba4604e8e433g9c892e360d53463oec5&organization_id=10234695 -H "Authorization: Zoho-authtoken ba4604e8e433g9c892e360d53463oec5" -H "Content-Type: application/json;charset=UTF-8"

Response Example

  
HTTP/1.1 200 OK Content-Type:application/json;charset=UTF-8 { "code": 0, "message": "success", "time_entry": { "time_entry_id": "460000000044021", "project_id": "460000000044019", "project_name": "REAL TIME TRAFFIC FLUX", "customer_id": "460000000044001", "customer_name": "SAF Instruments Inc", "task_id": "460000000044009", "task_name": "Distribution Analysis", "user_id": "460000000024003", "user_name": "John David", "is_current_user": true, "log_date": "2013-09-17", "begin_time": "03:00", "end_time": "04:00", "log_time": "05:00", "is_billable": true, "billed_status": "unbilled", "invoice_id": "", "notes": " ", "timer_started_at": " ", "timer_started_at_utc_time": "", "timer_duration_in_minutes": " ", "timer_duration_in_seconds": "", "created_time": "2013-09-11T18:05:27+0530", "timesheet_custom_fields": "" } }

Delete time entry

Deleting a logged time entry.

DELETE /projects/timeentries/{time_entry_id}

Request Example