API Documentation
Introduction

Curl Request

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 is available in 3 domains. Click on the corresponding domain to access its API Guide:

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 Access token has to be sent as Header in the API.The JSON String has to be sent as form-data.

Server to server calls are only possible.

Getting Started

Example

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

To use our API you must satisfy these prerequistes

  1. A valid Zoho username and password.
  2. An OAuth Token(access token).

OAuth

Zoho REST APIs uses the OAuth 2.0 protocol to authorize and authenticate calls. It provides secure access to protect resources thereby reducing the hassle of asking for a username and password everytime a user logs in. Follow the steps listed here, to access Zoho’s APIs using OAuth 2.0

Step 1: Registering New Client

You will have to first register your application with Zoho's Developer console in order get your Client ID and Client Secret.

To register your application, go to https://accounts.zoho.com/developerconsole and click on Add Client ID. Provide the required details to register your application.

On successful registration, you will be provided with a set of OAuth 2.0 credentials such as a Client ID and Client Secret that are known to both Zoho and your application. Do not share this credentials anywhere.

Step 2: Generating Grant Token

There are 2 methods to generate a grant token.

Method 1

Redirect to the following authorization URL with the given params

https://accounts.zoho.com/oauth/v2/auth

Request Example

https://accounts.zoho.com/oauth/v2/auth?scope=ZohoInvoice.invoices.CREATE,ZohoInvoice.invoices.READ,ZohoInvoice.invoices.UPDATE,ZohoInvoice.invoices.DELETE&client_id=1000.0SRSZSY37WMZ69405H3TMYI2239V&state=testing&response_type=code&redirect_uri=http://www.zoho.com/invoice&access_type=offline
Parameter Description
scope * SCOPE for which the token to be generated. Multiple scopes can be given which has to be separated by commas. Ex : ZohoInvoice.invoices.CREATE,ZohoInvoice.invoices.READ,ZohoInvoice.invoices.UPDATE,ZohoInvoice.invoices.DELETE
client_id * Client ID obtained during Client Registration
state An opaque string that is round-tripped in the protocol; ie., whatever value given to this will be passed back to you.
response_type * code
redirect_uri * One of the redirect URI given in above step. This param should be same redirect url mentioned while registering the Client
access_type The allowed values are offline and online. The online access_type gives your application only the access_token which is valid for one hour. The offline access_type will give the application an access_token as well as a refresh_token. By default it is taken as online
prompt Prompts for user consent each time your app tries to access user credentials. Ex: Consent [This Parameter is mandatory to get refresh_token]

Note: Fields with * are mandatory

On this request, you will be shown with a "user consent page".

Upon clicking “Accept”, Zoho will redirect to the given redirect_uri with code and state param. This code value is mandatory to get the access token in the next step and this code is valid for 60 seconds.

On clicking “Deny”, the server returns an error

Method 2

Follow the below steps to generate grant token from the Client ID:

  1. Go to https://accounts.zoho.com/developerconsole
  2. Click the Overflow icon and select Self Client from the options.
  3. Enter the scope and set the expiry time.
  4. Self Client

  5. Click View Code to generate the code.

Code

This code value is mandatory to get the access token in the next step. This code will be valid for the set expiry time.

Step 3: Generate Access and Refresh Token

After getting code from the above step, make a POST request for the following URL with given params, to generate the access_token.

https://accounts.zoho.com/oauth/v2/token

Request Example

https://accounts.zoho.com/oauth/v2/token?code=1000.dd7e47321d48b8a7e312e3d6eb1a9bb8.b6c07ac766ec11da98bf6a261e24dca4&client_id=1000.0SRSZSY37WMZ69405H3TMYI2239V&client_secret=fb0196010f2b70df8db2a173ca2cf59388798abf&redirect_uri=http://www.zoho.com/invoice&grant_type=authorization_code
Parameter Description
code* code which is obtained in the above step
client_id* Client ID obtained during Client Registration
client_secret* Secret key obtained during Client Registration
redirect_uri* This param should be same redirect url mentioned while adding Client
grant_type* authorization_code

Note: Fields with * are mandatory

In the response, you will get both access_token and refresh_token.

1. The access_token will expire after a particular period (as given in expires_in param in the response).

2. The refresh_token is permanent and will be used to regenerate new access_token, if the current access token is expired.

Note: 1.Each time a re-consent page is accepted, a new refresh token is generated. The maximum limit is 20 refresh tokens per user. If this limit is crossed, the first refresh token is automatically deleted to accommodate the latest one. This is done irrespective of whether the first refresh token is in use or not.

2.Step 1, 2 and 3 are one time processes that you need to follow when you are accessing Zoho's API for the first time. From the next time, you can jump to step 4 and use the refresh_token to generate a new access_token.

Step 4: Generate Access Token From Refresh Token

Access Tokens have limited validity. In most general cases the access tokens expire in one hour. Until then, the access token has unlimited usage. Once it expires, your app will have to use the refresh token to request for a new access token. Redirect to the following POST URL with the given params to get a new access token

https://accounts.zoho.com/oauth/v2/token

Request Example

https://accounts.zoho.com/oauth/v2/token?refresh_token=1000.8ecd474019e31d52d2f94aad6c5cb7.4638677ebc14f2f2ee0b6dfb6cebdc&client_id=1000.0SRSZSY37WMZ69405H3TMYI2239V&client_secret=fb0196010f2b70df8db2a173ca2cf59388798abf&redirect_uri=http://www.zoho.com/invoice&grant_type=refresh_token
Parameter Description
refresh_token REFRESH TOKEN which is obtained in the above step
client_id Client ID obtained during Client Registration
client_secret Secret key obtained during Client Registration
redirect_uri This param should be same redirect url mentioned while registering Client
grant_type refresh_token

Step 5: Revoking a Refresh Token

To revoke a refresh token, call the following POST URL with the given params

https://accounts.zoho.com/oauth/v2/token/revoke

Request Example

https://accounts.zoho.com/oauth/v2/token/revoke?token=1000.8ecd474019e31d522f94aad6c5cb7.4638677ebc14f2f2ee0b6dfb6cebdc
Parameter Description
token REFRESH TOKEN which is to be revoked

Step 6: Calling An API

Access Token can be passed only in header and cannot be passed in the request param.

List of scopes available in Zoho Invoice :

Scope Description
contacts To access contacts related APIs
Availabe types: ZohoInvoice.contacts.Create, ZohoInvoice.contacts.UPDATE, ZohoInvoice.contacts.READ, ZohoInvoice.contacts.DELETE
settings To access items, expense categories, users, taxes, currencies related APIs
Availabe types: ZohoInvoice.settings.Create, ZohoInvoice.settings.UPDATE, ZohoInvoice.settings.READ, ZohoInvoice.settings.DELETE
estimates To access estimates related APIs
Availabe types: ZohoInvoice.estimates.Create, ZohoInvoice.estimates.UPDATE, ZohoInvoice.estimates.READ, ZohoInvoice.estimates.DELETE
invoices To access invoices related APIs
Availabe types: ZohoInvoice.invoices.Create, ZohoInvoice.invoices.UPDATE, ZohoInvoice.invoices.READ, ZohoInvoice.invoices.DELETE
customerpayments To access customer payments related APIs
Availabe types: ZohoInvoice.customerpayments.Create, ZohoInvoice.customerpayments.UPDATE, ZohoInvoice.customerpayments.READ, ZohoInvoice.customerpayments.DELETE
creditnotes To access credit notes related APIs
Availabe types: ZohoInvoice.creditnotes.Create, ZohoInvoice.creditnotes.UPDATE, ZohoInvoice.creditnotes.READ, ZohoInvoice.creditnotes.DELETE
projects To access projects related APIs
Availabe types: ZohoInvoice.projects.Create, ZohoInvoice.projects.UPDATE, ZohoInvoice.projects.READ, ZohoInvoice.projects.DELETE
expenses To access expenses related APIs
Availabe types: ZohoInvoice.expenses.Create, ZohoInvoice.expenses.UPDATE, ZohoInvoice.expenses.READ, ZohoInvoice.expenses.DELETE

Convert Authtokens to OAuth in Existing Deluge Scripts

If your Deluge script uses Authtokens to invoke any Zoho APIs, you will need to change this script from Authtoken to OAuth-based authentication. This can be done with ease using Deluge's Connections. Learn how to set up and create new Connections.

Once you've created a Connection, simply remove the Authtoken details from your existing script and replace it with Connections instead. Here's how:

Existing Deluge script:

Example 1: An InvokeURL task with Authtoken-based authentication

  invoiceID = invoice.get("invoice_id");
  invoicedate = invoice.get("date").toDate();
  organizationID = organization.get("organization_id");
  authtoken = "XXXXXXXXXXXXXXX";
  invDetails = invokeurl
  [
  	url :"https://invoice.zoho.com/api/v3/invoices/" + invoiceID + "?organization_id=" + organizationID + "&authtoken="+ authtoken
  	type :GET
  ];

Example 2: A GetURL/PostURL task with Authtoken-based authentication

  invoiceID = invoice.get("invoice_id");
  invoicedate = invoice.get("date").toDate();
  organizationID = organization.get("organization_id");
  authtoken = "XXXXXXXXXXXXX";
  result = getUrl("https://invoice.zoho.com/api/v3/invoices/" + invoiceID + "?organization_id=" + organizationID + "&authtoken=" + authtoken);

Revised Deluge script with OAuth-based authentication:

  invoiceID = invoice.get("invoice_id");
  invoicedate = invoice.get("date").toDate();
  organizationID = organization.get("organization_id");
  invDetails = invokeurl
  [
    url :"https://invoice.zoho.com/api/v3/invoices/" + invoiceID + "?organization_id=" + organizationID
    type :GET
  connection : "invoiceconnection"
  ];

Here, invoiceconnection is the name of the Connection in Deluge, and you will have to replace it with your own Connection's name.

Once these changes have been made, your Deluge script will start using OAuth 2.0 for authentication with Zoho APIs.



Adding Connection Details to Integration Tasks

To ensure that the integration tasks in your Deluge scripts use OAuth 2.0, you must add Connection details to them.

Note: You need not make these changes to integration tasks which were created before November 2020, as Deluge will take care of this automatically.

  invoiceID = invoice.get("invoice_id");
  organizationID = organization.get("organization_id");
  invDetails = zoho.invoice.getRecordsByID("invoices", organizationID, invoiceID,"invoiceconnection");
  info invDetails;

The example on the right is of an existing integration task, to which we've added Connection details.

Here, invoiceconnection is the name of the Connection.

Organization ID

Request Example

$ curl https://invoice.zoho.com/api/v3/organizations

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?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?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?organization_id=10234695 -H 'Accept: application/pdf'
OR
$ curl https://invoice.zoho.com/api/v3/invoices/7000000079426?accept=pdf \ '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?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.

Possible error codes:
Error CodeMessage
1000The item name already exist
2006Item does not exist
2049Items which are a part of other transactions cannot be deleted. Instead, mark them as inactive
2076Product type cannot be changed for Items having transactions

Example

{ "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", "hsn_or_sac": "string", "item_tax_preferences": [ { "tax_id": 982000000037049, "tax_specification": "intra" } ] }

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]
status
string
Status of the item. It can be active or inactive. It tells whether the Item is available for transactions.
description
string
Description for the item. Maximum characters to be used for describing the item [2000]
rate
double
Per unit price of an item.
unit
string
Quantifying the amount of an item, using a measurement unit.
tax_id
string
ID of the tax to be associated to the item.
tax_name
string
Name of te Tax Included
tax_percentage
string
Percent of the tax.
tax_type
string
Type of the tax.
sku
string
SKU or the Stock Keeping Unit value of an item, should be unique throughout the product
product_type
string
Specify the type of an item. It can be either goods or service
hsn_or_sac
India Edition Only
string
HSN Code
item_tax_preferences
array
tax_id
string
ID of the tax to be associated to the item.
tax_specification
India Edition only
string
Set whether the tax type is intra/interstate

Create an Item

Create a new item.
oauthscope : ZohoInvoice.settings.CREATE

POST /items

Request Example

$ curl https://invoice.zoho.com/api/v3/items -X POST -H "X-com-zoho-invoice-organizationid: 10234695" -H "Content-Type: application/json;charset=UTF-8" -H "Authorization: Zoho-oauthtoken 1000.41d9f2cfbd1b7a8f9e314b7aff7bc2d1.8fcc9810810a216793f385b9dd6e125f" -d '{ "name": "Hard Drive", "rate": 120, "description": "500GB", "tax_id": 982000000037049, "sku": "s12345", "product_type": "goods", "is_taxable": true, "tax_exemption_id": "string", "hsn_or_sac": "string", "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", "hsn_or_sac": "string", "item_tax_preferences": [ { "tax_id": 982000000037049, "tax_specification": "intra" } ] } }

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

List items

Get the list of all active items with pagination.
oauthscope : ZohoInvoice.settings.READ

GET /items

Request Example

$ curl https://invoice.zoho.com/api/v3/items -H "X-com-zoho-invoice-organizationid: 10234695" -H "Authorization: Zoho-oauthtoken 1000.41d9f2cfbd1b7a8f9e314b7aff7bc2d1.8fcc9810810a216793f385b9dd6e125f"

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 Parameters

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

Update an item

Update the details of an existing item.
oauthscope : ZohoInvoice.settings.UPDATE

PUT /items/{item_id}

Request Example

$ curl https://invoice.zoho.com/api/v3/items/{item_id} -X PUT -H "X-com-zoho-invoice-organizationid: 10234695" -H "Content-Type: application/json;charset=UTF-8" -H "Authorization: Zoho-oauthtoken 1000.41d9f2cfbd1b7a8f9e314b7aff7bc2d1.8fcc9810810a216793f385b9dd6e125f" -d '{ "name": "Hard Drive", "rate": 120, "description": "500GB", "tax_id": 982000000037049, "sku": "s12345", "product_type": "goods", "is_taxable": true, "tax_exemption_id": "string", "hsn_or_sac": "string", "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", "hsn_or_sac": "string", "item_tax_preferences": [ { "tax_id": 982000000037049, "tax_specification": "intra" } ] } }

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.
oauthscope : ZohoInvoice.settings.READ

GET /items/{item_id}

Request Example

$ curl https://invoice.zoho.com/api/v3/items/{item_id} -H "X-com-zoho-invoice-organizationid: 10234695" -H "Authorization: Zoho-oauthtoken 1000.41d9f2cfbd1b7a8f9e314b7aff7bc2d1.8fcc9810810a216793f385b9dd6e125f"

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", "hsn_or_sac": "string", "item_tax_preferences": [ { "tax_id": 982000000037049, "tax_specification": "intra" } ] } }

Delete an item

Delete an existing item. Items that are part of a transaction cannot be deleted.
oauthscope : ZohoInvoice.settings.DELETE

DELETE /items/{item_id}

Request Example

$ curl https://invoice.zoho.com/api/v3/items/{item_id} -X DELETE -H "X-com-zoho-invoice-organizationid: 10234695" -H "Authorization: Zoho-oauthtoken 1000.41d9f2cfbd1b7a8f9e314b7aff7bc2d1.8fcc9810810a216793f385b9dd6e125f"

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.
oauthscope : ZohoInvoice.settings.CREATE

POST /items/{item_id}/active

Request Example

$ curl https://invoice.zoho.com/api/v3/items/{item_id}/active -X POST -H "X-com-zoho-invoice-organizationid: 10234695" -H "Authorization: Zoho-oauthtoken 1000.41d9f2cfbd1b7a8f9e314b7aff7bc2d1.8fcc9810810a216793f385b9dd6e125f"

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.
oauthscope : ZohoInvoice.settings.CREATE

POST /items/{item_id}/inactive

Request Example

$ curl https://invoice.zoho.com/api/v3/items/{item_id}/inactive -X POST -H "X-com-zoho-invoice-organizationid: 10234695" -H "Authorization: Zoho-oauthtoken 1000.41d9f2cfbd1b7a8f9e314b7aff7bc2d1.8fcc9810810a216793f385b9dd6e125f"

Response Example

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

Price Lists

Price list is a list containing a set of different prices for the items you sell.

Example

{ "pricebook_id": 1152891000000265000, "name": "Price List Per Item", "description": "checktest", "currency_id": 982000000004012, "currency_code": "INR", "pricebook_items": [ { "item_id": 982000000030049, "pricebook_rate": 120 } ], "status": "active", "is_default": false, "pricebook_type": "per_item", "is_increase": false, "rounding_type": "no_rounding", "sales_or_purchase_type": "sales" }

Attribute

pricebook_id
string
Unique ID generated by the server for a price list.
name
string
Name of the price list. Maximum length of the name [100]
description
string
Description for the price list. Maximum characters to be used for describing the price list [2000]
currency_id
string
A unique ID for the currency.
currency_code
string
A unique code for the currency. Maximum length [100]
pricebook_items
array
Items of a price book. It is mandatory for the price list type "per_item".
item_id
string
ID of the item for which the price list is created.
pricebook_rate
double
The rate of the item for your price list.
status
string
Status of the price list. It can be active or inactive. It tells whether the Item is available for transactions.
is_default
boolean
Is default.
pricebook_type
string
Type of the Pricebook. Allowed Values fixed_percentage, per_item
is_increase
boolean
Markup or Markdown the item rates by a percentage. Allowed Values true, false
rounding_type
string
Type of the Rounding type. Allowed Values no_rounding, round_to_dollar_minus_01, round_to_half_dollar, round_to_half_dollar_minus_01 and round_to_dollar
sales_or_purchase_type
string
Sales Type.

Create a Price List

Create a new Price List.
oauthscope : ZohoInvoice.settings.CREATE

POST /pricebooks

Request Example

$ curl https://invoice.zoho.com/api/v3/pricebooks -X POST -H "X-com-zoho-invoice-organizationid: 10234695" -H "Content-Type: application/json;charset=UTF-8" -H "Authorization: Zoho-oauthtoken 1000.41d9f2cfbd1b7a8f9e314b7aff7bc2d1.8fcc9810810a216793f385b9dd6e125f" -d '{ "name": "Price List Per Item", "pricebook_items": [ { "item_id": 982000000030049, "pricebook_rate": 120 } ], "currency_id": 982000000004012, "pricebook_type": "per_item", "is_increase": false, "rounding_type": "no_rounding" }'

Response Example

  
HTTP/1.1 201 Created Content-Type:application/json;charset=UTF-8 { "code": 0, "message": "Price list has been created.", "pricebook": { "pricebook_id": 1152891000000265000, "name": "Price List Per Item", "description": "checktest", "currency_id": 982000000004012, "currency_code": "INR", "pricebook_items": [ { "item_id": 982000000030049, "pricebook_rate": 120 } ], "status": "active", "is_default": false, "pricebook_type": "per_item", "is_increase": false, "rounding_type": "no_rounding", "sales_or_purchase_type": "sales" } }

Arguments

name
Required
Name of the price list. Maximum length of the name [100]
pricebook_items
Optional
Items of a price book. It is mandatory for the price list type "per_item".
item_id
Optional
ID of the item for which the price list is created.
pricebook_rate
Optional
The rate of the item for your price list.
currency_id
Optional
A unique ID for the currency.
pricebook_type
Required
Type of the Pricebook. Allowed Values fixed_percentage, per_item
is_increase
Required
Markup or Markdown the item rates by a percentage. Allowed Values true, false
rounding_type
Required
Type of the Rounding type. Allowed Values no_rounding, round_to_dollar_minus_01, round_to_half_dollar, round_to_half_dollar_minus_01 and round_to_dollar

List of all the Price Lists

Get the list of all the Price Lists with pagination.
oauthscope : ZohoInvoice.settings.READ

GET /pricebooks

Request Example

$ curl https://invoice.zoho.com/api/v3/pricebooks -H "X-com-zoho-invoice-organizationid: 10234695" -H "Authorization: Zoho-oauthtoken 1000.41d9f2cfbd1b7a8f9e314b7aff7bc2d1.8fcc9810810a216793f385b9dd6e125f"

Response Example

  
HTTP/1.1 200 OK Content-Type:application/json;charset=UTF-8 { "code": 0, "message": "success", "pricebooks": [ { "pricebook_id": 1152891000000265000, "name": "Price List Per Item", "description": "checktest", "currency_id": 982000000004012, "currency_code": "INR", "pricebook_items": [ { "item_id": 982000000030049, "pricebook_rate": 120 } ], "status": "active", "is_default": false, "pricebook_type": "per_item", "is_increase": false, "rounding_type": "no_rounding", "sales_or_purchase_type": "sales" }, {...}, {...} ] }

Update a Price List

Update an existing Price List.
oauthscope : ZohoInvoice.settings.UPDATE

PUT /pricebooks/{pricebook_id}

Request Example

$ curl https://invoice.zoho.com/api/v3/pricebooks/{pricebook_id} -X PUT -H "X-com-zoho-invoice-organizationid: 10234695" -H "Content-Type: application/json;charset=UTF-8" -H "Authorization: Zoho-oauthtoken 1000.41d9f2cfbd1b7a8f9e314b7aff7bc2d1.8fcc9810810a216793f385b9dd6e125f" -d '{ "name": "Price List Per Item", "currency_id": 982000000004012, "pricebook_type": "per_item", "is_increase": false, "rounding_type": "no_rounding", "pricebook_items": [ { "item_id": 982000000030049, "pricebook_rate": 120 } ] }'

Response Example

  
HTTP/1.1 200 OK Content-Type:application/json;charset=UTF-8 { "code": 0, "message": "Price list has been updated.", "pricebook": { "pricebook_id": 1152891000000265000, "name": "Price List Per Item", "description": "checktest", "currency_id": 982000000004012, "currency_code": "INR", "pricebook_items": [ { "item_id": 982000000030049, "pricebook_rate": 120 } ], "status": "active", "is_default": false, "pricebook_type": "per_item", "is_increase": false, "rounding_type": "no_rounding", "sales_or_purchase_type": "sales" } }

Arguments

name
Required
Name of the price list. Maximum length of the name [100]
currency_id
Optional
A unique ID for the currency.
pricebook_type
Required
Type of the Pricebook. Allowed Values fixed_percentage, per_item
is_increase
Required
Markup or Markdown the item rates by a percentage. Allowed Values true, false
rounding_type
Required
Type of the Rounding type. Allowed Values no_rounding, round_to_dollar_minus_01, round_to_half_dollar, round_to_half_dollar_minus_01 and round_to_dollar
pricebook_items
Optional
Items of a price book. It is mandatory for the price list type "per_item".
item_id
Optional
ID of the item for which the price list is created.
pricebook_rate
Optional
The rate of the item for your price list.

Retrieve a Price list

Fetch the details of an existing Price List.
oauthscope : ZohoInvoice.settings.READ

GET /pricebooks/{pricebook_id}

Request Example

$ curl https://invoice.zoho.com/api/v3/pricebooks/{pricebook_id} -H "X-com-zoho-invoice-organizationid: 10234695" -H "Authorization: Zoho-oauthtoken 1000.41d9f2cfbd1b7a8f9e314b7aff7bc2d1.8fcc9810810a216793f385b9dd6e125f"

Response Example

  
HTTP/1.1 200 OK Content-Type:application/json;charset=UTF-8 { "code": 0, "message": "success", "pricebook": { "pricebook_id": 1152891000000265000, "name": "Price List Per Item", "description": "checktest", "currency_id": 982000000004012, "currency_code": "INR", "pricebook_items": [ { "item_id": 982000000030049, "pricebook_rate": 120 } ], "status": "active", "is_default": false, "pricebook_type": "per_item", "is_increase": false, "rounding_type": "no_rounding", "sales_or_purchase_type": "sales" } }

Delete a Price List

Delete a Price List.
oauthscope : ZohoInvoice.settings.DELETE

DELETE /pricebooks/{pricebook_id}

Request Example

$ curl https://invoice.zoho.com/api/v3/pricebooks/{pricebook_id} -X DELETE -H "X-com-zoho-invoice-organizationid: 10234695" -H "Authorization: Zoho-oauthtoken 1000.41d9f2cfbd1b7a8f9e314b7aff7bc2d1.8fcc9810810a216793f385b9dd6e125f"

Response Example

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

Contacts

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

Possible error codes:
Error CodeMessage
1002Contact does not exist
3000This contact cannot be deleted since you have recorded transactions for it
3013Enter a valid Contact Name
3062The contact already exists.Please specify a different name
9004This currency does not exist. Please choose a valid currency
31006Portal is disabled for your organization. Please contact support@zohoinvoice.com to enable it

Example

{ "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, "tax_authority_name": "string", "tax_exemption_code": "string", "place_of_contact": "TN", "gst_no": "22AAAAA0000A1Z5", "vat_treatment": "string", "gst_treatment": "business_gst", "is_linked_with_zohocrm": false, "website": "www.zylker.org", "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": { "attention": "Mr.John", "address": "4900 Hopyard Rd, Suite 310", "street2": "Suite 310", "state_code": "CA", "city": "Pleasanton", "state": "CA", "zip": 94588, "country": "U.S.A", "fax": 1234, "phone": "1234" }, "shipping_address": { "attention": "Mr.John", "address": "4900 Hopyard Rd, Suite 310", "street2": "Suite 310", "state_code": "CA", "city": "Pleasanton", "state": "CA", "zip": 94588, "country": "U.S.A", "fax": 1234, "phone": "1234" }, "facebook": "zoho", "twitter": "zoho", "contact_persons": [ { "salutation": "Mr", "first_name": "Will", "last_name": "Smith", "email": "test@zylker.org", "phone": "1234", "mobile": "1234", "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" }

Attribute

contact_id
string
Contact ID of the contact
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]
has_transaction
boolean
Boolean to check if the customer has a history of transaction
contact_type
string
Type of the contact. Whether he is a customer or vendor
is_taxable
India, US and CA edition only
boolean
Boolean to track the taxability of the customer.
tax_id
India, US and CA edition only
string
ID of the tax or tax group that can be collected from the contact. Tax can be given only if is_taxable is true.
tax_name
India edition only
string
Enter tax name
tax_percentage
double
Enter tax percentage.
tax_authority_id
US and CA edition only
string
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
Inida, US and CA edition only
string
ID of the tax exemption.
tax_authority_name
string
Enter tax authority name.
tax_exemption_code
US, Canada, Australia and India editions only
string
Enter tax exemption code
place_of_contact
India Edition only.
string
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.
string
15 digit GST identification number of the customer/vendor.
vat_treatment
UK edition only
string
VAT treatment of the contact.Allowed Values:
uk (A business that is located in the UK.),
eu_vat_registered (A business that is reg for VAT and trade goods between Northern Ireland and EU. This node is available only for organizations enabled for NI protocal in VAT Settings.) and
overseas (A business that is located outside UK. Pre Brexit, this was split as eu_vat_registered, eu_vat_not_registered and non_eu ).
gst_treatment
India Edition only.
string
Choose whether the contact is GST registered/unregistered/consumer/overseas. Allowed values are business_gst , business_none , overseas , consumer .
is_linked_with_zohocrm
boolean
To check if the customer account is linked to the crm
website
string
Website of the contact.
primary_contact_id
string
Primary contact ID for a contact. This can be a contact person's ID as well.
payment_terms
integer
Net payment term for the customer.
payment_terms_label
string
Label for the paymet due details.
currency_id
string
Currency ID of the customer's currency.
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.
currency_symbol
string
Symbol of the currency of the contact_type
language_code
string
language of a contact. allowed values de,en,es,fr,it,ja,nl,pt,sv,zh
outstanding_receivable_amount
integer
Outsatnding amount with the contact, which is due for receipt
outstanding_receivable_amount_bcy
integer
outstanding receivable in base currency
unused_credits_receivable_amount
integer
Our Unused credits with the vendor which is receivable
unused_credits_receivable_amount_bcy
integer
receivable unused credits in base currency
status
string
The status of the contact.
payment_reminder_enabled
boolean
To check if a payment reminder service is enabled for the contact
custom_fields
array
Custom fields or Additional of the contact which we can create to add more information.
value
string
Value of the custom field.
index
integer
Index of the custom field. It can hold any value from 1 to 10.
label
string
Label of the custom field.
billing_address
object
Billing address of the contact.
attention
string
address
string
Billing address of the contact. Maximum length allowed [500]
street2
string
state_code
string
city
string
City of the customer’s billing address.
state
string
State of the customer’s billing address.
zip
string
Zip code of the customer’s billing address.
country
string
Country of the customer’s billing address.
fax
string
Customer's fax number.
phone
string
Phone number of the contact person.
shipping_address
object
Customer's shipping address to which the goods must be delivered.
attention
string
address
string
Billing address of the contact. Maximum length allowed [500]
street2
string
state_code
string
city
string
City of the customer’s billing address.
state
string
State of the customer’s billing address.
zip
string
Zip code of the customer’s billing address.
country
string
Country of the customer’s billing address.
fax
string
Customer's fax number.
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]
contact_persons
array
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.
default_templates
object
invoice_template_id
string
ID of the Invoice template used
invoice_template_name
string
Name of the invoice template used
estimate_template_id
string
ID of the estimate template used
estimate_template_name
string
Name of the estimate template used
creditnote_template_id
string
ID of teh credit note template used
creditnote_template_name
string
Name of the credit note template used
invoice_email_template_id
string
ID of the invoice email tempalte used
invoice_email_template_name
string
Name of the Invoice email template used
estimate_email_template_id
string
ID of the estimate email template used
estimate_email_template_name
string
Name of the estimate email template used
creditnote_email_template_id
string
ID of the credit note email template
creditnote_email_template_name
string
Name of the credit note email template
notes
string
Commennts about the payment made by the contact.
created_time
string
Time at which the contact was created.
last_modified_time
string
Time at which the contact was last modified

Create a Contact

Create a contact with given information.
oauthscope : ZohoInvoice.contacts.CREATE

POST /contacts

Request Example

$ curl https://invoice.zoho.com/api/v3/contacts -X POST -H "X-com-zoho-invoice-organizationid: 10234695" -H "Content-Type: application/json;charset=UTF-8" -H "Authorization: Zoho-oauthtoken 1000.41d9f2cfbd1b7a8f9e314b7aff7bc2d1.8fcc9810810a216793f385b9dd6e125f" -d '{ "contact_name": "Bowman and Co", "company_name": "Bowman and Co", "payment_terms": 15, "currency_id": 460000000000097, "website": "www.zylker.org", "custom_fields": [ { "value": "GBGD078", "index": 1 } ], "billing_address": { "attention": "Mr.John", "address": "4900 Hopyard Rd, Suite 310", "street2": "Suite 310", "state_code": "CA", "city": "Pleasanton", "state": "CA", "zip": 94588, "country": "U.S.A", "fax": 1234, "phone": "1234" }, "shipping_address": { "attention": "Mr.John", "address": "4900 Hopyard Rd, Suite 310", "street2": "Suite 310", "state_code": "CA", "city": "Pleasanton", "state": "CA", "zip": 94588, "country": "U.S.A", "fax": 1234, "phone": "1234" }, "contact_persons": [ { "salutation": "Mr", "first_name": "Will", "last_name": "Smith", "email": "test@zylker.org", "phone": "1234", "mobile": "1234", "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", "vat_reg_no": "string", "country_code": "string", "vat_treatment": "string", "place_of_contact": "TN", "gst_no": "22AAAAA0000A1Z5", "gst_treatment": "business_gst", "tax_authority_name": "string", "tax_exemption_code": "string", "avatax_exempt_no": "string", "avatax_use_code": "string", "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, "tax_authority_name": "string", "tax_exemption_code": "string", "place_of_contact": "TN", "gst_no": "22AAAAA0000A1Z5", "vat_treatment": "string", "gst_treatment": "business_gst", "is_linked_with_zohocrm": false, "website": "www.zylker.org", "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": { "attention": "Mr.John", "address": "4900 Hopyard Rd, Suite 310", "street2": "Suite 310", "state_code": "CA", "city": "Pleasanton", "state": "CA", "zip": 94588, "country": "U.S.A", "fax": 1234, "phone": "1234" }, "shipping_address": { "attention": "Mr.John", "address": "4900 Hopyard Rd, Suite 310", "street2": "Suite 310", "state_code": "CA", "city": "Pleasanton", "state": "CA", "zip": 94588, "country": "U.S.A", "fax": 1234, "phone": "1234" }, "facebook": "zoho", "twitter": "zoho", "contact_persons": [ { "salutation": "Mr", "first_name": "Will", "last_name": "Smith", "email": "test@zylker.org", "phone": "1234", "mobile": "1234", "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 fields for the contact.
value
Optional
Value of the custom field.
index
Optional
Index of the custom field. It can hold any value from 1 to 10.
billing_address
Optional
Billing address of the contact.
attention
Optional
address
Optional
Billing address of the contact. Maximum length allowed [500]
street2
Optional
state_code
Optional
city
Optional
City of the customer’s billing address.
state
Optional
State of the customer’s billing address.
zip
Optional
Zip code of the customer’s billing address.
country
Optional
Country of the customer’s billing address.
fax
Optional
Customer's fax number.
phone
Optional
Phone number of the contact person.
shipping_address
Optional
Customer's shipping address to which the goods must be delivered.
attention
Optional
address
Optional
Billing address of the contact. Maximum length allowed [500]
street2
Optional
state_code
Optional
city
Optional
City of the customer’s billing address.
state
Optional
State of the customer’s billing address.
zip
Optional
Zip code of the customer’s billing address.
country
Optional
Country of the customer’s billing address.
fax
Optional
Customer's fax number.
phone
Optional
Phone number of the contact person.
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 length should be between 2 and 12 characters.
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
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 (A business that is located in the UK.),
eu_vat_registered (A business that is reg for VAT and trade goods between Northern Ireland and EU. This node is available only for organizations enabled for NI protocal in VAT Settings.) and
overseas (A business that is located outside UK. Pre Brexit, this was split as eu_vat_registered, eu_vat_not_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.
oauthscope : ZohoInvoice.contacts.READ

GET /contacts

Request Example

$ curl https://invoice.zoho.com/api/v3/contacts -H "X-com-zoho-invoice-organizationid: 10234695" -H "Authorization: Zoho-oauthtoken 1000.41d9f2cfbd1b7a8f9e314b7aff7bc2d1.8fcc9810810a216793f385b9dd6e125f"

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": "test@zylker.org", "phone": "1234", "mobile": "1234", "created_time": "2013-10-07T12:06:10+0530", "last_modified_time": "2013-11-08T18:24:51+0530" }, {...}, {...} ] }

Query Parameters

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

Update a Contact

Update an existing contact. To delete a contact person remove it from the contact_persons list.
oauthscope : ZohoInvoice.contacts.UPDATE

PUT /contacts/{contact_id}

Request Example

$ curl https://invoice.zoho.com/api/v3/contacts/{contact_id} -X PUT -H "X-com-zoho-invoice-organizationid: 10234695" -H "Content-Type: application/json;charset=UTF-8" -H "Authorization: Zoho-oauthtoken 1000.41d9f2cfbd1b7a8f9e314b7aff7bc2d1.8fcc9810810a216793f385b9dd6e125f" -d '{ "contact_name": "Bowman and Co", "company_name": "Bowman and Co", "payment_terms": 15, "currency_id": 460000000000097, "website": "www.zylker.org", "custom_fields": [ { "value": "GBGD078", "index": 1, "label": "VAT ID" } ], "billing_address": { "attention": "Mr.John", "address": "4900 Hopyard Rd, Suite 310", "street2": "Suite 310", "state_code": "CA", "city": "Pleasanton", "state": "CA", "zip": 94588, "country": "U.S.A", "fax": 1234, "phone": "1234" }, "shipping_address": { "attention": "Mr.John", "address": "4900 Hopyard Rd, Suite 310", "street2": "Suite 310", "state_code": "CA", "city": "Pleasanton", "state": "CA", "zip": 94588, "country": "U.S.A", "fax": 1234, "phone": "1234" }, "contact_persons": [ { "salutation": "Mr", "first_name": "Will", "last_name": "Smith", "email": "test@zylker.org", "phone": "1234", "mobile": "1234", "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", "vat_reg_no": "string", "country_code": "string", "vat_treatment": "string", "place_of_contact": "TN", "gst_no": "22AAAAA0000A1Z5", "gst_treatment": "business_gst", "tax_authority_name": "string", "tax_exemption_code": "string", "avatax_exempt_no": "string", "avatax_use_code": "string", "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, "tax_authority_name": "string", "tax_exemption_code": "string", "place_of_contact": "TN", "gst_no": "22AAAAA0000A1Z5", "vat_treatment": "string", "gst_treatment": "business_gst", "is_linked_with_zohocrm": false, "website": "www.zylker.org", "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": { "attention": "Mr.John", "address": "4900 Hopyard Rd, Suite 310", "street2": "Suite 310", "state_code": "CA", "city": "Pleasanton", "state": "CA", "zip": 94588, "country": "U.S.A", "fax": 1234, "phone": "1234" }, "shipping_address": { "attention": "Mr.John", "address": "4900 Hopyard Rd, Suite 310", "street2": "Suite 310", "state_code": "CA", "city": "Pleasanton", "state": "CA", "zip": 94588, "country": "U.S.A", "fax": 1234, "phone": "1234" }, "facebook": "zoho", "twitter": "zoho", "contact_persons": [ { "salutation": "Mr", "first_name": "Will", "last_name": "Smith", "email": "test@zylker.org", "phone": "1234", "mobile": "1234", "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.
attention
Optional
address
Optional
Billing address of the contact. Maximum length allowed [500]
street2
Optional
state_code
Optional
city
Optional
City of the customer’s billing address.
state
Optional
State of the customer’s billing address.
zip
Optional
Zip code of the customer’s billing address.
country
Optional
Country of the customer’s billing address.
fax
Optional
Customer's fax number.
phone
Optional
Phone number of the contact person.
shipping_address
Optional
Customer's shipping address to which the goods must be delivered.
attention
Optional
address
Optional
Billing address of the contact. Maximum length allowed [500]
street2
Optional
state_code
Optional
city
Optional
City of the customer’s billing address.
state
Optional
State of the customer’s billing address.
zip
Optional
Zip code of the customer’s billing address.
country
Optional
Country of the customer’s billing address.
fax
Optional
Customer's fax number.
phone
Optional
Phone number of the contact person.
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 length should be between 2 and 12 characters.
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
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 (A business that is located in the UK.),
eu_vat_registered (A business that is reg for VAT and trade goods between Northern Ireland and EU. This node is available only for organizations enabled for NI protocal in VAT Settings.) and
overseas (A business that is located outside UK. Pre Brexit, this was split as eu_vat_registered, eu_vat_not_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]

Delete a Contact

Delete an existing Contact.
oauthscope : ZohoInvoice.contacts.DELETE

DELETE /contacts/{contact_id}

Request Example

$ curl https://invoice.zoho.com/api/v3/contacts/{contact_id} -X DELETE -H "X-com-zoho-invoice-organizationid: 10234695" -H "Authorization: Zoho-oauthtoken 1000.41d9f2cfbd1b7a8f9e314b7aff7bc2d1.8fcc9810810a216793f385b9dd6e125f"

Response Example

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

Get a Contact

Get details of a Contact.
oauthscope : ZohoInvoice.contacts.READ

GET /contacts/{contacts_id}

Request Example

$ curl https://invoice.zoho.com/api/v3/contacts/{contacts_id} -H "X-com-zoho-invoice-organizationid: 10234695" -H "Authorization: Zoho-oauthtoken 1000.41d9f2cfbd1b7a8f9e314b7aff7bc2d1.8fcc9810810a216793f385b9dd6e125f"

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, "tax_authority_name": "string", "tax_exemption_code": "string", "place_of_contact": "TN", "gst_no": "22AAAAA0000A1Z5", "vat_treatment": "string", "gst_treatment": "business_gst", "is_linked_with_zohocrm": false, "website": "www.zylker.org", "primary_contact_id": 460000000026051, "payment_terms": 15, "payment_terms_label": "Net 15", "currency_id": 460000000000097, "currency_code": "USD", "currency_symbol": "$", "outstanding_receivable_amount": 250, "outstanding_receivable_amount_bcy": 250, "unused_credits_receivable_amount": 1369.66, "unused_credits_receivable_amount_bcy": 1369.66, "status": "active", "facebook": "zoho", "twitter": "zoho", "payment_reminder_enabled": true, "custom_fields": [ { "value": "GBGD078", "index": 1, "label": "VAT ID" } ], "billing_address": { "attention": "Mr.John", "address": "4900 Hopyard Rd, Suite 310", "street2": "Suite 310", "state_code": "CA", "city": "Pleasanton", "state": "CA", "zip": 94588, "country": "U.S.A", "fax": 1234, "phone": "1234" }, "shipping_address": { "attention": "Mr.John", "address": "4900 Hopyard Rd, Suite 310", "street2": "Suite 310", "state_code": "CA", "city": "Pleasanton", "state": "CA", "zip": 94588, "country": "U.S.A", "fax": 1234, "phone": "1234" }, "contact_persons": [ { "salutation": "Mr", "first_name": "Will", "last_name": "Smith", "email": "test@zylker.org", "phone": "1234", "mobile": "1234", "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" } }

Mark as Active

Mark a contact as active.
oauthscope : ZohoInvoice.contacts.CREATE

POST /contact/{contact_id}/active

Request Example

$ curl https://invoice.zoho.com/api/v3/contact/{contact_id}/active -X POST -H "X-com-zoho-invoice-organizationid: 10234695" -H "Authorization: Zoho-oauthtoken 1000.41d9f2cfbd1b7a8f9e314b7aff7bc2d1.8fcc9810810a216793f385b9dd6e125f"

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.
oauthscope : ZohoInvoice.contacts.CREATE

POST /contacts/{contact_id}/inactive

Request Example

$ curl https://invoice.zoho.com/api/v3/contacts/{contact_id}/inactive -X POST -H "X-com-zoho-invoice-organizationid: 10234695" -H "Authorization: Zoho-oauthtoken 1000.41d9f2cfbd1b7a8f9e314b7aff7bc2d1.8fcc9810810a216793f385b9dd6e125f"

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.
oauthscope : ZohoInvoice.contacts.CREATE

POST /contacts/{contact_id}/portal/enable

Request Example

$ curl https://invoice.zoho.com/api/v3/contacts/{contact_id}/portal/enable -X POST -H "X-com-zoho-invoice-organizationid: 10234695" -H "Content-Type: application/json;charset=UTF-8" -H "Authorization: Zoho-oauthtoken 1000.41d9f2cfbd1b7a8f9e314b7aff7bc2d1.8fcc9810810a216793f385b9dd6e125f" -d '{ "contact_persons": [ { "contact_person_id": 460000000026051 } ] }'

Response Example

  
HTTP/1.1 200 OK Content-Type:application/json;charset=UTF-8 { "code": 0, "message": "Client Portal preferences have been updated" }

Arguments

contact_persons
Required
Person/Individual who represents a company
contact_person_id
Optional
The ID of the contact person

View All Client Reviews

View the list of all client reviews for a particular contact.
oauthscope : ZohoInvoice.contacts.READ

GET /clientreviews

Request Example

$ curl https://invoice.zoho.com/api/v3/clientreviews -H "X-com-zoho-invoice-organizationid: 10234695" -H "Authorization: Zoho-oauthtoken 1000.41d9f2cfbd1b7a8f9e314b7aff7bc2d1.8fcc9810810a216793f385b9dd6e125f"

Response Example

  
HTTP/1.1 200 OK Content-Type:application/json;charset=UTF-8 { "code": 0, "message": "success", "reviews": [ { "comment_id": 460000000053131, "commented_by": "David Sujin", "contact_id": 460000000026049, "date": "2013-11-19", "description": "", "rating": 4 }, {...}, {...} ] }

Query Parameters

contact_id
Optional
Unique ID of a particular contact.

Details of a Particular Client Review

View the details of a particular client review.
oauthscope : ZohoInvoice.contacts.READ

GET /clientreviews/{comment_id}

Request Example

$ curl https://invoice.zoho.com/api/v3/clientreviews/{comment_id} -H "X-com-zoho-invoice-organizationid: 10234695" -H "Authorization: Zoho-oauthtoken 1000.41d9f2cfbd1b7a8f9e314b7aff7bc2d1.8fcc9810810a216793f385b9dd6e125f"

Response Example

  
HTTP/1.1 200 OK Content-Type:application/json;charset=UTF-8 { "code": 0, "message": "success", "reviews": [ { "comment_id": 460000000053131, "commented_by": "David Sujin", "contact_id": 460000000026049, "date": "2013-11-19", "description": "", "is_client_review_or_comment": true, "rating": 4 }, {...}, {...} ] }

Query Parameters

contact_id
Optional
Unique ID of a particular contact.

Reply a Client Review

Send a reply to a client's review.
oauthscope : ZohoInvoice.contacts.CREATE

POST /clientreviews/{comment_id}/comment

Request Example

$ curl https://invoice.zoho.com/api/v3/clientreviews/{comment_id}/comment -X POST -H "X-com-zoho-invoice-organizationid: 10234695" -H "Content-Type: application/json;charset=UTF-8" -H "Authorization: Zoho-oauthtoken 1000.41d9f2cfbd1b7a8f9e314b7aff7bc2d1.8fcc9810810a216793f385b9dd6e125f" -d '{ "description": "Thank you for your feedback" }'

Response Example

  
HTTP/1.1 200 OK Content-Type:application/json;charset=UTF-8 { "code": 0, "message": "Comment has been updated.", "reviews": [ { "comment_id": 460000000053131, "commented_by": "David Sujin", "contact_id": 460000000026049, "date": "2013-11-19", "description": "", "is_client_review_or_comment": true, "rating": 4 }, {...}, {...} ] }

Arguments

description
Optional
A short note on the purpose/reason for the credit note

Query Parameters

contact_id
Optional
Unique ID of a particular contact.

Enable Payment Reminders

Enable automated payment reminders for a contact.
oauthscope : ZohoInvoice.contacts.CREATE

POST /contacts/{contact_id}/paymentreminder/enable

Request Example

$ curl https://invoice.zoho.com/api/v3/contacts/{contact_id}/paymentreminder/enable -X POST -H "X-com-zoho-invoice-organizationid: 10234695" -H "Authorization: Zoho-oauthtoken 1000.41d9f2cfbd1b7a8f9e314b7aff7bc2d1.8fcc9810810a216793f385b9dd6e125f"

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.
oauthscope : ZohoInvoice.contacts.CREATE

POST /contacts/{contact_id}/paymentreminder/disable

Request Example

$ curl https://invoice.zoho.com/api/v3/contacts/{contact_id}/paymentreminder/disable -X POST -H "X-com-zoho-invoice-organizationid: 10234695" -H "Authorization: Zoho-oauthtoken 1000.41d9f2cfbd1b7a8f9e314b7aff7bc2d1.8fcc9810810a216793f385b9dd6e125f"

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.
oauthscope : ZohoInvoice.contacts.CREATE

POST /contacts/{contact_id}/statements/email

Request Example

$ curl https://invoice.zoho.com/api/v3/contacts/{contact_id}/statements/email -X POST -H "X-com-zoho-invoice-organizationid: 10234695" -H "Content-Type: application/json;charset=UTF-8" -H "Authorization: Zoho-oauthtoken 1000.41d9f2cfbd1b7a8f9e314b7aff7bc2d1.8fcc9810810a216793f385b9dd6e125f" -d '{ "send_from_org_email_id": true, "to_mail_ids": [ "test@zylker.org" ], "cc_mail_ids": [ "test@zylker.org" ], "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 Parameters

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.
oauthscope : ZohoInvoice.contacts.READ

GET /contacts/{contact_id}/statements/email

Request Example

$ curl https://invoice.zoho.com/api/v3/contacts/{contact_id}/statements/email -H "X-com-zoho-invoice-organizationid: 10234695" -H "Authorization: Zoho-oauthtoken 1000.41d9f2cfbd1b7a8f9e314b7aff7bc2d1.8fcc9810810a216793f385b9dd6e125f"

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": "1234", "email": "test@zylker.org", "contact_person_id": 460000000026051, "last_name": "Smith", "salutation": "Mr", "mobile": "1234" } ], "file_name": "statement_BowmanandCo.pdf", "from_emails": [ { "user_name": "John Smith", "selected": true, "email": "test@zylker.org" } ], "contact_id": 460000000026049 }

Query Parameters

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.
oauthscope : ZohoInvoice.contacts.CREATE

POST /contacts/{contact_id}/email

Request Example

$ curl https://invoice.zoho.com/api/v3/contacts/{contact_id}/email -X POST -H "X-com-zoho-invoice-organizationid: 10234695" -H "Content-Type: application/json;charset=UTF-8" -H "Authorization: Zoho-oauthtoken 1000.41d9f2cfbd1b7a8f9e314b7aff7bc2d1.8fcc9810810a216793f385b9dd6e125f" -d '{ "to_mail_ids": [ "test@zylker.org" ], "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", "attachments": "string" }'

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 Parameters

send_customer_statement
Optional
Send customer statement pdf with email.

List Comments

List recent activities of a contact.
oauthscope : ZohoInvoice.contacts.READ

GET /contacts/{contact_id}/comments

Request Example

$ curl https://invoice.zoho.com/api/v3/contacts/{contact_id}/comments -H "X-com-zoho-invoice-organizationid: 10234695" -H "Authorization: Zoho-oauthtoken 1000.41d9f2cfbd1b7a8f9e314b7aff7bc2d1.8fcc9810810a216793f385b9dd6e125f"

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

Add Additional Address

Add an additional address for a contact using the arguments below.
oauthscope : ZohoInvoice.contacts.CREATE

POST /contacts/{:contact_id}/address

Request Example

$ curl https://invoice.zoho.com/api/v3/contacts/{:contact_id}/address -X POST -H "X-com-zoho-invoice-organizationid: 10234695" -H "Content-Type: application/json;charset=UTF-8" -H "Authorization: Zoho-oauthtoken 1000.41d9f2cfbd1b7a8f9e314b7aff7bc2d1.8fcc9810810a216793f385b9dd6e125f" -d '{ "attention": "Mr.John", "address": "4900 Hopyard Rd, Suite 310", "street2": "Suite 310", "city": "Pleasanton", "state": "CA", "zip": 94588, "country": "U.S.A", "fax": 1234, "phone": 1234 }'

Response Example

  
HTTP/1.1 200 OK Content-Type:application/json;charset=UTF-8 { "code": 0, "message": "The address has been created.", "address_info": { "address_id": 1053791000000186000, "attention": "Mr.John", "address": "4900 Hopyard Rd, Suite 310", "street2": "Suite 310", "city": "Pleasanton", "state": "CA", "zip": 94588, "country": "U.S.A", "fax": 1234, "phone": "1234" } }

Arguments

attention
Optional
address
Optional
Billing address of the contact. Maximum length allowed [500]
street2
Optional
city
Optional
City of the customer’s billing address.
state
Optional
State of the customer’s billing address.
zip
Optional
Zip code of the customer’s billing address.
country
Optional
Country of the customer’s billing address.
fax
Optional
Customer's fax number.
phone
Optional
phone number of the contact person.

Get Contact Addresses

Get addresses of a contact including its Shipping Address, Billing Address and other additional addresses.
oauthscope : ZohoInvoice.contacts.READ

GET /contacts/{:contact_id}/address

Request Example

$ curl https://invoice.zoho.com/api/v3/contacts/{:contact_id}/address -H "X-com-zoho-invoice-organizationid: 10234695" -H "Authorization: Zoho-oauthtoken 1000.41d9f2cfbd1b7a8f9e314b7aff7bc2d1.8fcc9810810a216793f385b9dd6e125f"

Response Example

  
HTTP/1.1 200 OK Content-Type:application/json;charset=UTF-8 { "code": 0, "message": "success", "addresses": [ { "address_id": 1053791000000186000, "attention": "Mr.John", "address": "4900 Hopyard Rd, Suite 310", "street2": "Suite 310", "city": "Pleasanton", "state": "CA", "zip": 94588, "country": "U.S.A", "fax": 1234, "phone": "1234" }, {...}, {...} ] }

Edit Additional Address

Edit the additional address of a contact using the arguments below.
oauthscope : ZohoInvoice.contacts.UPDATE

PUT /contacts/{:contact_id}/address/{:address_id}

Request Example

$ curl https://invoice.zoho.com/api/v3/contacts/{:contact_id}/address/{:address_id} -X PUT -H "X-com-zoho-invoice-organizationid: 10234695" -H "Content-Type: application/json;charset=UTF-8" -H "Authorization: Zoho-oauthtoken 1000.41d9f2cfbd1b7a8f9e314b7aff7bc2d1.8fcc9810810a216793f385b9dd6e125f" -d '{ "attention": "Mr.John", "address": "4900 Hopyard Rd, Suite 310", "street2": "Suite 310", "city": "Pleasanton", "state": "CA", "zip": 94588, "country": "U.S.A", "fax": 1234, "phone": 1234 }'

Response Example

  
HTTP/1.1 200 OK Content-Type:application/json;charset=UTF-8 { "code": 0, "message": "The address has been updated.", "address_info": { "address_id": 1053791000000186000, "attention": "Mr.John", "address": "4900 Hopyard Rd, Suite 310", "street2": "Suite 310", "city": "Pleasanton", "state": "CA", "zip": 94588, "country": "U.S.A", "fax": 1234, "phone": "1234" } }

Arguments

attention
Optional
address
Optional
Billing address of the contact. Maximum length allowed [500]
street2
Optional
city
Optional
City of the customer’s billing address.
state
Optional
State of the customer’s billing address.
zip
Optional
Zip code of the customer’s billing address.
country
Optional
Country of the customer’s billing address.
fax
Optional
Customer's fax number.
phone
Optional
phone number of the contact person.

Delete Additional Address

Delete the additional address of a contact.
oauthscope : ZohoInvoice.contacts.DELETE

DELETE /contacts/{:contact_id}/address/{:address_id}

Request Example

$ curl https://invoice.zoho.com/api/v3/contacts/{:contact_id}/address/{:address_id} -X DELETE -H "X-com-zoho-invoice-organizationid: 10234695" -H "Authorization: Zoho-oauthtoken 1000.41d9f2cfbd1b7a8f9e314b7aff7bc2d1.8fcc9810810a216793f385b9dd6e125f"

Response Example

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

List Refunds

List the refund history of a contact.
oauthscope : ZohoInvoice.contacts.READ

GET /contacts/{contact_id}/refunds

Request Example

$ curl https://invoice.zoho.com/api/v3/contacts/{contact_id}/refunds -H "X-com-zoho-invoice-organizationid: 10234695" -H "Authorization: Zoho-oauthtoken 1000.41d9f2cfbd1b7a8f9e314b7aff7bc2d1.8fcc9810810a216793f385b9dd6e125f"

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, "contact_person_id": 460000000026051, "salutation": "Mr", "first_name": "Will", "last_name": "Smith", "email": "test@zylker.org", "phone": 1234, "mobile": 1234, "is_primary_contact": true, "skype": "zoho", "designation": "Sales Engineer", "department": "Sales", "is_added_in_portal": true } ]

Attribute

contact_id
string
ID of the contact person
contact_person_id
string
The ID of the contact person
salutation
string
Salutation for the contact. Maximum length allowed [25]
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]
phone
string
Phone number of the contact person. Maximum length [50]
mobile
string
Mobile/Cell number of the contact person. Maximum length [50]
is_primary_contact
boolean
To mark contact person as primary for communication.
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]
is_added_in_portal
boolean
tells whether the contact person has portal access or not

Create a contact person

Create a contact person for contact.
oauthscope : ZohoInvoice.contacts.CREATE

POST /contacts/contactpersons

Request Example

$ curl https://invoice.zoho.com/api/v3/contacts/contactpersons -X POST -H "X-com-zoho-invoice-organizationid: 10234695" -H "Content-Type: application/json;charset=UTF-8" -H "Authorization: Zoho-oauthtoken 1000.41d9f2cfbd1b7a8f9e314b7aff7bc2d1.8fcc9810810a216793f385b9dd6e125f" -d '{ "contact_id": 460000000026049, "salutation": "Mr", "first_name": "Will", "last_name": "Smith", "email": "test@zylker.org", "phone": 1234, "mobile": 1234, "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": "test@zylker.org", "phone": 1234, "mobile": 1234, "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.
oauthscope : ZohoInvoice.contacts.UPDATE

PUT /contacts/contactpersons/{contact_person_id}

Request Example

$ curl https://invoice.zoho.com/api/v3/contacts/contactpersons/{contact_person_id} -X PUT -H "X-com-zoho-invoice-organizationid: 10234695" -H "Content-Type: application/json;charset=UTF-8" -H "Authorization: Zoho-oauthtoken 1000.41d9f2cfbd1b7a8f9e314b7aff7bc2d1.8fcc9810810a216793f385b9dd6e125f" -d '{ "contact_id": 460000000026049, "salutation": "Mr", "first_name": "Will", "last_name": "Smith", "email": "test@zylker.org", "phone": 1234, "mobile": 1234, "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": "test@zylker.org", "phone": 1234, "mobile": 1234, "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

Delete a contact person

Delete an existing contact person.
oauthscope : ZohoInvoice.contacts.DELETE

DELETE /contacts/contactpersons/{contact_person_id}

Request Example

$ curl https://invoice.zoho.com/api/v3/contacts/contactpersons/{contact_person_id} -X DELETE -H "X-com-zoho-invoice-organizationid: 10234695" -H "Authorization: Zoho-oauthtoken 1000.41d9f2cfbd1b7a8f9e314b7aff7bc2d1.8fcc9810810a216793f385b9dd6e125f"

Response Example

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

List contact persons

List all contacts with pagination.
oauthscope : ZohoInvoice.contacts.READ

GET /contacts/{contact_id}/contactpersons

Request Example

$ curl https://invoice.zoho.com/api/v3/contacts/{contact_id}/contactpersons -H "X-com-zoho-invoice-organizationid: 10234695" -H "Authorization: Zoho-oauthtoken 1000.41d9f2cfbd1b7a8f9e314b7aff7bc2d1.8fcc9810810a216793f385b9dd6e125f"

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": "test@zylker.org", "phone": 1234, "mobile": 1234, "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.
oauthscope : ZohoInvoice.contacts.READ

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

Request Example

$ curl https://invoice.zoho.com/api/v3/contacts/{contact_id}/contactpersons/{contact_person_id} -H "X-com-zoho-invoice-organizationid: 10234695" -H "Authorization: Zoho-oauthtoken 1000.41d9f2cfbd1b7a8f9e314b7aff7bc2d1.8fcc9810810a216793f385b9dd6e125f"

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": "test@zylker.org", "phone": 1234, "mobile": 1234, "is_primary_contact": true, "skype": "zoho", "designation": "Sales Engineer", "department": "Sales", "is_added_in_portal": true } }

Mark as primary contact person

Mark a contact person as primary for contact.
oauthscope : ZohoInvoice.contacts.CREATE

POST /contacts/contactpersons/{contact_person_id}/primary

Request Example

$ curl https://invoice.zoho.com/api/v3/contacts/contactpersons/{contact_person_id}/primary -X POST -H "X-com-zoho-invoice-organizationid: 10234695" -H "Authorization: Zoho-oauthtoken 1000.41d9f2cfbd1b7a8f9e314b7aff7bc2d1.8fcc9810810a216793f385b9dd6e125f"

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.

Possible error codes:
Error CodeMessage
1001Estimate Number already exist
1002Estimate does not exist
2007Estimate cannot be raised for items that have been deleted or marked as inactive
4041Estimate status cannot be changed to Draft
9526Please enter a valid retainer percentage. It should be greater than 0 and less than or equal to 100

Example

{ "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": 1234 }, "shipping_address": { "address": "4900 Hopyard Rd, Suite 310", "city": "Pleasanton", "state": "CA", "zip": 94588, "country": "U.S.A", "fax": 1234 }, "notes": "Looking forward for your business.", "terms": "Terms & Conditions apply", "custom_fields": [ { "customfield_id": 439910000000236000, "data_type": "number", "index": 1, "label": "Delivery Date", "show_on_pdf": false, "show_in_all_pdf": true, "value": "15 Dec 2013" } ], "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", "project": { "project_id": 90300000087378, "project_name": "Sample Project" } }

Attribute

estimate_id
string
The unique id of a particular estimate
estimate_number
string
Estimate Serial number.
date
string
Date on the estimate.
reference_number
string
Transaction reference number.
is_pre_gst
India Edition only
boolean
Applicable for transactions that fall before july 1, 2017
place_of_supply
India Edition only.
string
Place where the goods/services are supplied to. (If not given, place of contact given for the contact will be taken)
gst_no
India Edition only
string
15 digit GST identification number of the customer.
gst_treatment
India Edition only
string
Choose whether the contact is GST registered/unregistered/consumer/overseas. Allowed values are business_gst , business_none , overseas , consumer .
status
string
Status of the estimate. Allowed Valuesdraft, sent, invoiced , accepted, declined and expired
customer_id
string
Customer ID on the estimate.
customer_name
string
Name of the Customer to whom the estimate is sent.
contact_persons
array
Array of contact person(s) for whom estimate has to be sent.
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.
exchange_rate
double
Foreign Exchange rate of the currency.
expiry_date
string
The date of expiration of the estimates
discount
double
Discount applied to the invoice. It can be either in % or in amount. e.g. 12.5% or 190.
is_discount_before_tax
boolean
Used to specify how the discount has to applied. Either before or after the calculation of tax.
discount_type
string
How the discount is specified. Allowed values are entity_level or item_level.Allowed Values: entity_level and item_level
is_inclusive_tax
Not applicable for US edition
boolean
Used to specify whether the line item rates are inclusive or exclusive of tax.
array
Line items of an estimate.
item_id
string
Unique ID of the item.
name
string
The name of the line item
description
string
The description of the line items
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
shipping_charge
string
Shipping charges applied to the invoice.
adjustment
double
Adjustments made to the invoice.
adjustment_description
string
Customize the adjustment description. E.g. Rounding off value.
sub_total
float
The sub total of the all items
total
double
estimate total value.
tax_total
double
The total amount of the tax levied
price_precision
integer
The precision value on the price
array
List of the taxes levied
tax_name
string
The name of the tax
tax_amount
float
The amount of the tax levied
billing_address
object
The billing address of the customer
address
string
Billing address for the estimate
city
string
City of the customer’s billing address.
state
string
State of the customer’s billing address.
zip
string
Zip code of the customer’s billing address.
country
string
Country of the customer’s billing address.
fax
string
Customer's fax number.
shipping_address
object
The shipping address of the customer
address
string
Billing address for the estimate
city
string
City of the customer’s billing address.
state
string
State of the customer’s billing address.
zip
string
Zip code of the customer’s billing address.
country
string
Country of the customer’s billing address.
fax
string
Customer's fax number.
notes
string
The notes added below expressing gratitude or for conveying some information.
terms
string
Enlist the terms & conditions for estimate
custom_fields
array
Custom fields for an estimate.
customfield_id
long
Unique ID of the custom field
data_type
string
Data type of the custom field
index
integer
An index for the custom field.
label
string
Label for the estimate
show_on_pdf
boolean
Show exported file in PDF format
show_in_all_pdf
Enable/Disable show this custom field on all the pdf
value
string
Value for the custom field
template_id
string
ID of the template used for the estimate
template_name
string
Name of the template used
created_time
string
The time of creation of the estimates
last_modified_time
string
Last date of modification in estimate
salesperson_id
string
Unique ID of the sales person
salesperson_name
string
Name of the sales person.
object
project_id
string
ID of the project
project_name
string
Name of the project.

Create an Estimate

Create an estimate for your customer.
oauthscope : ZohoInvoice.estimates.CREATE

POST /estimates

Request Example

$ curl https://invoice.zoho.com/api/v3/estimates -X POST -H "X-com-zoho-invoice-organizationid: 10234695" -H "Content-Type: application/json;charset=UTF-8" -H "Authorization: Zoho-oauthtoken 1000.41d9f2cfbd1b7a8f9e314b7aff7bc2d1.8fcc9810810a216793f385b9dd6e125f" -d '{ "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": [ { "label": "Delivery Date", "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, "avatax_tax_code": "string", "avatax_use_code": "string", "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, "avatax_use_code": "string", "avatax_tax_code": "string", "avatax_exempt_no": "string", "vat_treatment": "string", "project_id": 90300000087378 }'

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": 1234 }, "shipping_address": { "address": "4900 Hopyard Rd, Suite 310", "city": "Pleasanton", "state": "CA", "zip": 94588, "country": "U.S.A", "fax": 1234 }, "notes": "Looking forward for your business.", "terms": "Terms & Conditions apply", "custom_fields": [ { "customfield_id": 439910000000236000, "data_type": "number", "index": 1, "label": "Delivery Date", "show_on_pdf": false, "show_in_all_pdf": true, "value": "15 Dec 2013" } ], "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", "project": { "project_id": 90300000087378, "project_name": "Sample Project" } } }

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.
label
Optional
Label for the estimate
value
Optional
Value for the custom field
Required
Line items of an estimate.
item_id
Required
Unique ID of the item.
name
Optional
The name of the line item
description
Optional
The description of the line items
item_order
Optional
The order of the line item_order
rate
Required
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
Required
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
UK edition only
Optional
(Optional) VAT treatment for the estimates. VAT treatment denotes the location of the customer, if the customer resides in UK then the VAT treatment is uk. If the customer is in an EU country & VAT registered, you are resides in Northen Ireland and selling Goods then his VAT treatment is eu_vat_registered, if he resides outside of the UK then his VAT treatment is overseas (For Pre Brexit, this can be split as eu_vat_registered, eu_vat_not_registered and non_eu).
project_id
Optional
ID of the project

Query Parameters

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.

List estimates

List all estimates with pagination.
oauthscope : ZohoInvoice.estimates.READ

GET /estimates

Request Example

$ curl https://invoice.zoho.com/api/v3/estimates -H "X-com-zoho-invoice-organizationid: 10234695" -H "Authorization: Zoho-oauthtoken 1000.41d9f2cfbd1b7a8f9e314b7aff7bc2d1.8fcc9810810a216793f385b9dd6e125f"

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

Update an Estimate

Update an existing estimate. To delete a line item just remove it from the line_items list.
oauthscope : ZohoInvoice.estimates.UPDATE

PUT /estimates/{estimate_id}

Request Example

$ curl https://invoice.zoho.com/api/v3/estimates/{estimate_id} -X PUT -H "X-com-zoho-invoice-organizationid: 10234695" -H "Content-Type: application/json;charset=UTF-8" -H "Authorization: Zoho-oauthtoken 1000.41d9f2cfbd1b7a8f9e314b7aff7bc2d1.8fcc9810810a216793f385b9dd6e125f" -d '{ "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": [ { "label": "Delivery Date", "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, "avatax_tax_code": "string", "avatax_use_code": "string", "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, "avatax_use_code": "string", "avatax_tax_code": "string", "avatax_exempt_no": "string", "vat_treatment": "string", "project_id": 90300000087378 }'

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": 1234 }, "shipping_address": { "address": "4900 Hopyard Rd, Suite 310", "city": "Pleasanton", "state": "CA", "zip": 94588, "country": "U.S.A", "fax": 1234 }, "notes": "Looking forward for your business.", "terms": "Terms & Conditions apply", "custom_fields": [ { "customfield_id": 439910000000236000, "data_type": "number", "index": 1, "label": "Delivery Date", "show_on_pdf": false, "show_in_all_pdf": true, "value": "15 Dec 2013" } ], "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", "project": { "project_id": 90300000087378, "project_name": "Sample Project" } } }

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.
label
Optional
Label for the estimate
value
Optional
Value for the custom field
Optional
Line items of an estimate.
item_id
Required
Unique ID of the item.
name
Optional
The name of the line item
description
Optional
The description of the line items
item_order
Optional
The order of the line item_order
rate
Required
Rate of the line item.
quantity
Required
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
UK edition only
Optional
(Optional) VAT treatment for the estimates. VAT treatment denotes the location of the customer, if the customer resides in UK then the VAT treatment is uk. If the customer is in an EU country & VAT registered, you are resides in Northen Ireland and selling Goods then his VAT treatment is eu_vat_registered, if he resides outside of the UK then his VAT treatment is overseas (For Pre Brexit, this can be split as eu_vat_registered, eu_vat_not_registered and non_eu).
project_id
Optional
ID of the project

Query Parameters

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.
oauthscope : ZohoInvoice.estimates.READ

GET /estimates/{estimate_id}

Request Example

$ curl https://invoice.zoho.com/api/v3/estimates/{estimate_id} -H "X-com-zoho-invoice-organizationid: 10234695" -H "Authorization: Zoho-oauthtoken 1000.41d9f2cfbd1b7a8f9e314b7aff7bc2d1.8fcc9810810a216793f385b9dd6e125f"

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": 1234 }, "shipping_address": { "address": "4900 Hopyard Rd, Suite 310", "city": "Pleasanton", "state": "CA", "zip": 94588, "country": "U.S.A", "fax": 1234 }, "custom_fields": [ { "customfield_id": 439910000000236000, "data_type": "number", "index": 1, "label": "Delivery Date", "show_on_pdf": false, "show_in_all_pdf": true, "value": "15 Dec 2013" } ], "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", "project": { "project_id": 90300000087378, "project_name": "Sample Project" } } }

Query Parameters

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

Delete an Estimate

Delete an existing estimate.
oauthscope : ZohoInvoice.estimates.DELETE

DELETE /estimates/{estimate_id}

Request Example

$ curl https://invoice.zoho.com/api/v3/estimates/{estimate_id} -X DELETE -H "X-com-zoho-invoice-organizationid: 10234695" -H "Authorization: Zoho-oauthtoken 1000.41d9f2cfbd1b7a8f9e314b7aff7bc2d1.8fcc9810810a216793f385b9dd6e125f"

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.
oauthscope : ZohoInvoice.estimates.CREATE

POST /estimates/{estimate_id}/status/sent

Request Example

$ curl https://invoice.zoho.com/api/v3/estimates/{estimate_id}/status/sent -X POST -H "X-com-zoho-invoice-organizationid: 10234695" -H "Authorization: Zoho-oauthtoken 1000.41d9f2cfbd1b7a8f9e314b7aff7bc2d1.8fcc9810810a216793f385b9dd6e125f"

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.
oauthscope : ZohoInvoice.estimates.CREATE

POST /estimates/{estimate_id}/status/accepted

Request Example

$ curl https://invoice.zoho.com/api/v3/estimates/{estimate_id}/status/accepted -X POST -H "X-com-zoho-invoice-organizationid: 10234695" -H "Authorization: Zoho-oauthtoken 1000.41d9f2cfbd1b7a8f9e314b7aff7bc2d1.8fcc9810810a216793f385b9dd6e125f"

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.
oauthscope : ZohoInvoice.estimates.CREATE

POST /estimates/{estimate_id}/status/declined

Request Example

$ curl https://invoice.zoho.com/api/v3/estimates/{estimate_id}/status/declined -X POST -H "X-com-zoho-invoice-organizationid: 10234695" -H "Authorization: Zoho-oauthtoken 1000.41d9f2cfbd1b7a8f9e314b7aff7bc2d1.8fcc9810810a216793f385b9dd6e125f"

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.
oauthscope : ZohoInvoice.estimates.CREATE

POST /estimates/{estimate_id}/email

Request Example

$ curl https://invoice.zoho.com/api/v3/estimates/{estimate_id}/email -X POST -H "X-com-zoho-invoice-organizationid: 10234695" -H "Content-Type: application/json;charset=UTF-8" -H "Authorization: Zoho-oauthtoken 1000.41d9f2cfbd1b7a8f9e314b7aff7bc2d1.8fcc9810810a216793f385b9dd6e125f" -d '{ "send_from_org_email_id": false, "to_mail_ids": [ "test@zylker.org" ], "cc_mail_ids": [ "test@zylker.org" ], "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 Parameters

attachments
Optional
Files to be attached to the email

Get estimate email content

Get the email content of an estimate.
oauthscope : ZohoInvoice.estimates.READ

GET /estimates/{estimate_id}/email

Request Example

$ curl https://invoice.zoho.com/api/v3/estimates/{estimate_id}/email -H "X-com-zoho-invoice-organizationid: 10234695" -H "Authorization: Zoho-oauthtoken 1000.41d9f2cfbd1b7a8f9e314b7aff7bc2d1.8fcc9810810a216793f385b9dd6e125f"

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": "Default", "email_template_id": 982000000000079 } ], "to_contacts": [ { "first_name": "David", "selected": true, "phone": "1234", "email": "string", "last_name": "Sujin", "salutation": ":Mr", "contact_person_id": "982000000567003", "mobile": "1234" } ], "file_name": "EST-00001.pdf", "from_emails": [ { "user_name": "John Smith", "selected": true, "email": "string" } ], "customer_id": 982000000567001 }

Query Parameters

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.

Email multiple estimates

Send estimates to your customers by email. Maximum of 10 estimates can be sent at once.
oauthscope : ZohoInvoice.estimates.CREATE

POST /estimates/email

Request Example

$ curl https://invoice.zoho.com/api/v3/estimates/email -X POST -H "X-com-zoho-invoice-organizationid: 10234695" -H "Authorization: Zoho-oauthtoken 1000.41d9f2cfbd1b7a8f9e314b7aff7bc2d1.8fcc9810810a216793f385b9dd6e125f"

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 Parameters

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

Bulk export estimates

Maximum of 25 estimates can be exported in a single pdf.
oauthscope : ZohoInvoice.estimates.READ

GET /estimates/pdf

Request Example

$ curl https://invoice.zoho.com/api/v3/estimates/pdf -H "X-com-zoho-invoice-organizationid: 10234695" -H "Authorization: Zoho-oauthtoken 1000.41d9f2cfbd1b7a8f9e314b7aff7bc2d1.8fcc9810810a216793f385b9dd6e125f"

Response Example

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

Query Parameters

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.
oauthscope : ZohoInvoice.estimates.READ

GET /estimates/print

Request Example

$ curl https://invoice.zoho.com/api/v3/estimates/print -H "X-com-zoho-invoice-organizationid: 10234695" -H "Authorization: Zoho-oauthtoken 1000.41d9f2cfbd1b7a8f9e314b7aff7bc2d1.8fcc9810810a216793f385b9dd6e125f"

Response Example

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

Query Parameters

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

Update billing address

Updates the billing address for this estimate alone.
oauthscope : ZohoInvoice.estimates.UPDATE

PUT /estimates/{estimate_id}/address/billing

Request Example

$ curl https://invoice.zoho.com/api/v3/estimates/{estimate_id}/address/billing -X PUT -H "X-com-zoho-invoice-organizationid: 10234695" -H "Content-Type: application/json;charset=UTF-8" -H "Authorization: Zoho-oauthtoken 1000.41d9f2cfbd1b7a8f9e314b7aff7bc2d1.8fcc9810810a216793f385b9dd6e125f" -d '{ "address": "B-1104, 11F, \nHorizon International Tower, \nNo. 6, ZhiChun Road, HaiDian District,", "city": "Beijing", "state": "Beijing", "zip": 1000881, "country": "China", "fax": "+86-10-82637827" }'

Response Example

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

Arguments

address
Optional
Billing Address 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.
oauthscope : ZohoInvoice.estimates.UPDATE

PUT /estimates/{estimate_id}/address/shipping

Request Example

$ curl https://invoice.zoho.com/api/v3/estimates/{estimate_id}/address/shipping -X PUT -H "X-com-zoho-invoice-organizationid: 10234695" -H "Content-Type: application/json;charset=UTF-8" -H "Authorization: Zoho-oauthtoken 1000.41d9f2cfbd1b7a8f9e314b7aff7bc2d1.8fcc9810810a216793f385b9dd6e125f" -d '{ "address": "4900 Hopyard Rd, Suite 310", "city": "Pleasanton", "state": "CA", "zip": 94588, "country": "U.S.A", "fax": 1234 }'

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.
oauthscope : ZohoInvoice.estimates.READ

GET /estimates/templates

Request Example

$ curl https://invoice.zoho.com/api/v3/estimates/templates -H "X-com-zoho-invoice-organizationid: 10234695" -H "Authorization: Zoho-oauthtoken 1000.41d9f2cfbd1b7a8f9e314b7aff7bc2d1.8fcc9810810a216793f385b9dd6e125f"

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.
oauthscope : ZohoInvoice.estimates.UPDATE

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

Request Example

$ curl https://invoice.zoho.com/api/v3/estimates/{estimate_id}/templates/{template_id} -X PUT -H "X-com-zoho-invoice-organizationid: 10234695" -H "Authorization: Zoho-oauthtoken 1000.41d9f2cfbd1b7a8f9e314b7aff7bc2d1.8fcc9810810a216793f385b9dd6e125f"

Response Example

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

Add Comments

Add a comment for an estimate.
oauthscope : ZohoInvoice.estimates.CREATE

POST /estimates/{estimate_id}/comments

Request Example

$ curl https://invoice.zoho.com/api/v3/estimates/{estimate_id}/comments -X POST -H "X-com-zoho-invoice-organizationid: 10234695" -H "Content-Type: application/json;charset=UTF-8" -H "Authorization: Zoho-oauthtoken 1000.41d9f2cfbd1b7a8f9e314b7aff7bc2d1.8fcc9810810a216793f385b9dd6e125f" -d '{ "description": "Estimate marked as sent", "show_comment_to_clients": true }'

Response Example

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

Arguments

description
Optional
A short note on the estimate
show_comment_to_clients
Optional
Boolean to show the comments to contacts in portal.

List estimate comments & history

Get the complete history and comments of an estimate.
oauthscope : ZohoInvoice.estimates.READ

GET /estimates/{estimate_id}/comments

Request Example

$ curl https://invoice.zoho.com/api/v3/estimates/{estimate_id}/comments -H "X-com-zoho-invoice-organizationid: 10234695" -H "Authorization: Zoho-oauthtoken 1000.41d9f2cfbd1b7a8f9e314b7aff7bc2d1.8fcc9810810a216793f385b9dd6e125f"

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

Update comment

Update an existing comment of an estimate.
oauthscope : ZohoInvoice.estimates.UPDATE

PUT /estimates/{estimate_id}/comments/{comment_id}

Request Example

$ curl https://invoice.zoho.com/api/v3/estimates/{estimate_id}/comments/{comment_id} -X PUT -H "X-com-zoho-invoice-organizationid: 10234695" -H "Content-Type: application/json;charset=UTF-8" -H "Authorization: Zoho-oauthtoken 1000.41d9f2cfbd1b7a8f9e314b7aff7bc2d1.8fcc9810810a216793f385b9dd6e125f" -d '{ "description": "Estimate created", "show_comment_to_clients": " " }'

Response Example

  
HTTP/1.1 200 OK Content-Type:application/json;charset=UTF-8 { "code": 0, "message": "Comment has been updated successfully.", "comment": { "comment_id": 982000000567019, "estimate_id": 982000000567011, "description": "500GB, USB 2.0 interface 1400 rpm, protective hard case.", "commented_by_id": 982000000554041, "commented_by": "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.
oauthscope : ZohoInvoice.estimates.DELETE

DELETE /estimates/{estimate_id}/comments/{comment_id}

Request Example

$ curl https://invoice.zoho.com/api/v3/estimates/{estimate_id}/comments/{comment_id} -X DELETE -H "X-com-zoho-invoice-organizationid: 10234695" -H "Authorization: Zoho-oauthtoken 1000.41d9f2cfbd1b7a8f9e314b7aff7bc2d1.8fcc9810810a216793f385b9dd6e125f"

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.

Possible error codes:
Error CodeMessage
1001Invoice Number already exist
1002Contact Person does not exist
3009The contact details of this invoice cannot be edited as the credits have been applied to it
3010The customer for this invoice cannot be changed because payments have been recorded for this invoice
4001Payments have been recorded for these invoices.Hence they cannot be deleted
12008This invoice has credits applied to it. Hence, it cannot be deleted

Example

{ "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", "vat_treatment": "string", "vat_reg_no": "string", "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": 90300000087378, "project_name": "Sample Project", "time_entry_ids": [], "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": { "payment_gateways": [ { "configured": true, "additional_field1": "standard", "gateway_name": "paypal" } ] }, "is_emailed": false, "reminders_sent": 1, "last_reminder_sent_date": " ", "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": [ { "customfield_id": 439910000000236000, "data_type": "number", "index": 1, "label": "Record Number", "show_on_pdf": true, "show_in_all_pdf": true, "value": 23 } ], "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/portal/zylkar/secure?CInvoiceID=23d84d0cf64f9a72ea0c66fded25a08c8bafd0ab508aff05323a9f80e2cd03fdc5dd568d3d6407bbda969d3e870d740b6fce549a9438c4ea" }

Attribute

invoice_id
string
The ID of the invoice
ach_payment_initiated
boolean
To check initiation of ACH Payment
invoice_number
string
An unique number given to the invoice. Maximum length [100]
is_pre_gst
India Edition only.
boolean
Applicable for transactions that fall before july 1, 2017
place_of_supply
India Edition only.
string
Place where the goods/services are supplied to. (If not given, place of contact given for the contact will be taken)
gst_no
India Edition only.
string
15 digit GST identification number of the customer.
gst_treatment
India Edition only.
string
Choose whether the contact is GST registered/unregistered/consumer/overseas. Allowed values are business_gst , business_none , overseas , consumer .
vat_treatment
UK edition only
string
(Optional) VAT treatment for the invoices. VAT treatment denotes the location of the customer, if the customer resides in UK then the VAT treatment is uk. If the customer is in an EU country & VAT registered, you are resides in Northen Ireland and selling Goods then his VAT treatment is eu_vat_registered, if he resides outside of the UK then his VAT treatment is overseas (For Pre Brexit, this can be split as eu_vat_registered, eu_vat_not_registered and non_eu).
vat_reg_no
string
Enter VAT registration number.
date
string
invoice date. Date format yyyy-mm-dd
status
string
Status of the invoice. Allowed Values: sent, draft, overdue, paid, void, unpaid, partially_paid and viewed
payment_terms
integer
Payment terms in days e.g. 15, 30, 60. Invoice due date will be calculated based on this. Maximum length [100]
payment_terms_label
string
Used to override the default payment terms label. Default value for 15 days is "Net 15 Days". Maximum length [100]
due_date
string
due date of the invoices. Date format yyyy-mm-dd
payment_expected_date
string
The expected date of payment
last_payment_date
string
The last payment date of the invoice
reference_number
string
The reference number of the invoice
customer_id
string
ID of the customer to whom the invoice is created.
customer_name
string
The name of the customer. Maximum length [100]
contact_persons
array
The IDs of the contact person associated with the contact.
currency_id
string
The currenct id of the currency
currency_code
string
The currency code in which the invoice is created.
exchange_rate
float
Exchange rate of the currency.
discount
float
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
boolean
Check if discount is exclusive of tax
discount_type
string
Type of discount
is_inclusive_tax
boolean
To check if discount is inclusive of tax
recurring_invoice_id
string
ID of the recurring invoice from which the invoice is created.
is_viewed_by_client
boolean
Check if invoice is viewed by client
has_attachment
boolean
To check if invoice has an attachment
client_viewed_time
string
Time when client viewed the statement
array
Items listed in invoice
line_item_id
string
The line item ID
item_id
string
Unique item id.
project_id
string
Unique ID of the projet associated to an invoice
project_name
string
Name of the project.
time_entry_ids
array
Unique ID's of all the time entries associated to the linked project
item_type
string
Enter goods/services
product_type
string
Enter goods/services
expense_id
string
Unique ID of the expenses associated
name
string
The name of the line item. Maximum length [100]
description
string
The description of the line items. Maximum length [2000]
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
shipping_charge
string
Shipping charges applied to the invoice. Maximum length [100]
adjustment
double
Adjustments made to the invoice.
adjustment_description
string
Customize the adjustment description. E.g. Rounding off.
sub_total
float
The sub total of the all items
tax_total
double
The total amount of the tax levied
total
string
The total amount to be paid
array
List of the taxes levied
tax_name
string
The name of the tax
tax_amount
float
The amount of the tax levied
payment_reminder_enabled
boolean
Boolean to check if reminders have been enabled
payment_made
float
The amount paid
credits_applied
float
The credits applied
tax_amount_withheld
float
The tax amount which has been withheld
balance
string
The unpaid amount
write_off_amount
float
The write off amount. i.e. the amount which is not expected to be returned. Like a bad debt
allow_partial_payments
boolean
Boolean to check if partial payments are allowed for the contact
price_precision
integer
The precision value on the price
payment_options
object
Payment options available for payment
payment_gateways
array
Payment gateways integrated and supported
configured
boolean
Boolean check to see if a payment gateway has been configured
additional_field1
string
Paypal payment method. Allowed Values: standard and adaptive
gateway_name
string
Name of the payment gateway associated with the invoice. E.g. paypal, stripe.Allowed Values: paypal, authorize_net, payflow_pro, stripe, 2checkout and braintree
is_emailed
boolean
Boolean check to see if the mail has been sent
reminders_sent
integer
The number of reminders sent
last_reminder_sent_date
string
The date the last email was sent
billing_address
object
Billing address of the contact
address
string
Billing address for the invoice
city
string
City of the customer’s billing address.
state
string
State of the customer’s billing address.
zip
string
Zip code of the customer’s billing address.
country
string
Country of the customer’s billing address.
fax
string
Customer's fax number.
shipping_address
object
Shipping address of the contact
address
string
Billing address for the invoice
city
string
City of the customer’s billing address.
state
string
State of the customer’s billing address.
zip
string
Zip code of the customer’s billing address.
country
string
Country of the customer’s billing address.
fax
string
Customer's fax number.
notes
string
The notes added below expressing gratitude or for conveying some information.
terms
string
The terms added below expressing gratitude or for conveying some information.
custom_fields
array
Custom fields for an invoice.
customfield_id
long
Unique ID of the custom field
data_type
string
Data type of the custom field
index
integer
The index of the custom field
label
string
Name of the custom field
show_on_pdf
boolean
Enable/Disable show this custom field on pdf for that invoice
show_in_all_pdf
Enable/Disable show this custom field on all the pdf
value
integer
Value of the custom field
template_id
string
ID of the pdf template associated with the invoice.
template_name
string
Name of the invoice template used
created_time
string
The time of creation of the invoices
last_modified_time
string
Date of last modification of the invoice
attachment_name
string
Name of the file attached
can_send_in_mail
boolean
To check if attachment can be sent in email
salesperson_id
string
ID of the salesperson linked to invoice
salesperson_name
string
Name of the salesperson. Maximum length [200]
invoice_url
string
Url of invoice as a link

Create an invoice

Create an invoice for your customer.
oauthscope : ZohoInvoice.invoices.CREATE

POST /invoices

Request Example

$ curl https://invoice.zoho.com/api/v3/invoices -X POST -H "X-com-zoho-invoice-organizationid: 10234695" -H "Content-Type: application/json;charset=UTF-8" -H "Authorization: Zoho-oauthtoken 1000.41d9f2cfbd1b7a8f9e314b7aff7bc2d1.8fcc9810810a216793f385b9dd6e125f" -d '{ "customer_id": 982000000567001, "contact_persons": [ "982000000870911", "982000000870915" ], "invoice_number": "INV-00003", "reference_number": " ", "place_of_supply": "TN", "vat_treatment": "string", "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": [ { "label": "Record Number", "value": 23 } ], "project_id": 90300000087378, "line_items": [ { "item_id": 982000000030049, "project_id": 90300000087378, "time_entry_ids": [], "expense_id": " ", "name": "Hard Drive", "product_type": "goods", "hsn_or_sac": 80540, "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, "avatax_use_code": "string", "avatax_exempt_no": "string", "tax_name": "VAT", "tax_type": "tax", "tax_percentage": 12.5, "item_total": 120 } ], "payment_options": { "payment_gateways": [ { "configured": true, "additional_field1": "standard", "gateway_name": "paypal" } ] }, "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, "avatax_use_code": "string", "avatax_tax_code": "string", "avatax_exempt_no": "string" }'

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", "vat_treatment": "string", "vat_reg_no": "string", "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": 90300000087378, "project_name": "Sample Project", "time_entry_ids": [], "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": { "payment_gateways": [ { "configured": true, "additional_field1": "standard", "gateway_name": "paypal" } ] }, "is_emailed": false, "reminders_sent": 1, "last_reminder_sent_date": " ", "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": [ { "customfield_id": 439910000000236000, "data_type": "number", "index": 1, "label": "Record Number", "show_on_pdf": true, "show_in_all_pdf": true, "value": 23 } ], "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/portal/zylkar/secure?CInvoiceID=23d84d0cf64f9a72ea0c66fded25a08c8bafd0ab508aff05323a9f80e2cd03fdc5dd568d3d6407bbda969d3e870d740b6fce549a9438c4ea" } }

Arguments

customer_id
Required
ID of the customer to whom the invoice is 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
UK edition only
Optional
(Optional) VAT treatment for the invoices. VAT treatment denotes the location of the customer, if the customer resides in UK then the VAT treatment is uk. If the customer is in an EU country & VAT registered, you are resides in Northen Ireland and selling Goods then his VAT treatment is eu_vat_registered, if he resides outside of the UK then his VAT treatment is overseas (For Pre Brexit, this can be split as eu_vat_registered, eu_vat_not_registered and non_eu).
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.
label
Optional
Name of the custom field
value
Optional
Value of the custom field
project_id
Optional
Unique ID of the projet associated to an invoice
Required
Line items of an invoice.
item_id
Required
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
description
Optional
The description of the line items. Maximum length [2000]
item_order
Optional
The order of the line item_order
rate
Required
Rate of the line item.
quantity
Required
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 available for payment
payment_gateways
Optional
Payment gateways integrated and supported
configured
Optional
Boolean check to see if a payment gateway has 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
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]

Query Parameters

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

List invoices

List all invoices with pagination.
oauthscope : ZohoInvoice.invoices.READ

GET /invoices

Request Example

$ curl https://invoice.zoho.com/api/v3/invoices -H "X-com-zoho-invoice-organizationid: 10234695" -H "Authorization: Zoho-oauthtoken 1000.41d9f2cfbd1b7a8f9e314b7aff7bc2d1.8fcc9810810a216793f385b9dd6e125f"

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": [ { "customfield_id": 439910000000236000, "data_type": "number", "index": 1, "label": "Record Number", "show_on_pdf": true, "show_in_all_pdf": true, "value": 23 } ], "documents": "", "salesperson_id": " ", "salesperson_name": " ", "shipping_charge": 0, "adjustment": 0, "write_off_amount": 0, "exchange_rate": 1 }, {...}, {...} ] }

Query Parameters

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 to whom the invoice is 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

Update an invoice

Update an existing invoice. To delete a line item just remove it from the line_items list.
oauthscope : ZohoInvoice.invoices.UPDATE

PUT /invoices/{invoice_id}

Request Example

$ curl https://invoice.zoho.com/api/v3/invoices/{invoice_id} -X PUT -H "X-com-zoho-invoice-organizationid: 10234695" -H "Content-Type: application/json;charset=UTF-8" -H "Authorization: Zoho-oauthtoken 1000.41d9f2cfbd1b7a8f9e314b7aff7bc2d1.8fcc9810810a216793f385b9dd6e125f" -d '{ "customer_id": 982000000567001, "contact_persons": [ "982000000870911", "982000000870915" ], "invoice_number": "INV-00003", "reference_number": " ", "place_of_supply": "TN", "vat_treatment": "string", "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": [ { "label": "Record Number", "value": 23 } ], "project_id": 90300000087378, "line_items": [ { "item_id": 982000000030049, "project_id": 90300000087378, "time_entry_ids": [], "expense_id": " ", "name": "Hard Drive", "product_type": "goods", "hsn_or_sac": 80540, "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, "avatax_use_code": "string", "avatax_exempt_no": "string", "tax_name": "VAT", "tax_type": "tax", "tax_percentage": 12.5, "item_total": 120 } ], "payment_options": { "payment_gateways": [ { "configured": true, "additional_field1": "standard", "gateway_name": "paypal" } ] }, "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, "avatax_use_code": "string", "avatax_tax_code": "string", "avatax_exempt_no": "string" }'

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", "vat_treatment": "string", "vat_reg_no": "string", "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": 90300000087378, "project_name": "Sample Project", "item_type": "goods", "product_type": "goods", "time_entry_ids": [], "expense_id": " ", "expense_receipt_name": "string", "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": { "payment_gateways": [ { "configured": true, "additional_field1": "standard", "gateway_name": "paypal" } ] }, "is_emailed": false, "reminders_sent": 1, "last_reminder_sent_date": " ", "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": [ { "customfield_id": 439910000000236000, "data_type": "number", "index": 1, "label": "Record Number", "show_on_pdf": true, "show_in_all_pdf": true, "value": 23 } ], "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/portal/zylkar/secure?CInvoiceID=23d84d0cf64f9a72ea0c66fded25a08c8bafd0ab508aff05323a9f80e2cd03fdc5dd568d3d6407bbda969d3e870d740b6fce549a9438c4ea" } }

Arguments

customer_id
Required
ID of the customer to whom the invoice is 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
UK edition only
Optional
(Optional) VAT treatment for the invoices. VAT treatment denotes the location of the customer, if the customer resides in UK then the VAT treatment is uk. If the customer is in an EU country & VAT registered, you are resides in Northen Ireland and selling Goods then his VAT treatment is eu_vat_registered, if he resides outside of the UK then his VAT treatment is overseas (For Pre Brexit, this can be split as eu_vat_registered, eu_vat_not_registered and non_eu).
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.
label
Optional
Name of the custom field
value
Optional
Value of the custom field
project_id
Optional
Unique ID of the projet associated to an invoice
Required
Line items of an invoice.
item_id
Required
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
description
Optional
The description of the line items. Maximum length [2000]
item_order
Optional
The order of the line item_order
rate
Required
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 available for payment
payment_gateways
Optional
Payment gateways integrated and supported
configured
Optional
Boolean check to see if a payment gateway has 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
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]

Query Parameters

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.
oauthscope : ZohoInvoice.invoices.READ

GET /invoices/{invoice_id}

Request Example

$ curl https://invoice.zoho.com/api/v3/invoices/{invoice_id} -H "X-com-zoho-invoice-organizationid: 10234695" -H "Authorization: Zoho-oauthtoken 1000.41d9f2cfbd1b7a8f9e314b7aff7bc2d1.8fcc9810810a216793f385b9dd6e125f"

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", "vat_treatment": "string", "vat_reg_no": "string", "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": 90300000087378, "project_name": "Sample Project", "item_type": "goods", "product_type": "goods", "time_entry_ids": [], "expense_id": " ", "expense_receipt_name": "string", "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": { "payment_gateways": [ { "configured": true, "additional_field1": "standard", "gateway_name": "paypal" } ] }, "is_emailed": false, "reminders_sent": 1, "last_reminder_sent_date": " ", "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": [ { "customfield_id": 439910000000236000, "data_type": "number", "index": 1, "label": "Record Number", "show_on_pdf": true, "show_in_all_pdf": true, "value": 23 } ], "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/portal/zylkar/secure?CInvoiceID=23d84d0cf64f9a72ea0c66fded25a08c8bafd0ab508aff05323a9f80e2cd03fdc5dd568d3d6407bbda969d3e870d740b6fce549a9438c4ea" } }

Query Parameters

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

Delete an invoice

Delete an existing invoice. Invoices which have payment or credits note applied cannot be deleted.
oauthscope : ZohoInvoice.invoices.DELETE

DELETE /invoices/{invoice_id}

Request Example

$ curl https://invoice.zoho.com/api/v3/invoices/{invoice_id} -X DELETE -H "X-com-zoho-invoice-organizationid: 10234695" -H "Authorization: Zoho-oauthtoken 1000.41d9f2cfbd1b7a8f9e314b7aff7bc2d1.8fcc9810810a216793f385b9dd6e125f"

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.
oauthscope : ZohoInvoice.invoices.CREATE

POST /invoices/{invoice_id}/status/sent

Request Example

$ curl https://invoice.zoho.com/api/v3/invoices/{invoice_id}/status/sent -X POST -H "X-com-zoho-invoice-organizationid: 10234695" -H "Authorization: Zoho-oauthtoken 1000.41d9f2cfbd1b7a8f9e314b7aff7bc2d1.8fcc9810810a216793f385b9dd6e125f"

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.
oauthscope : ZohoInvoice.invoices.CREATE

POST /invoices/{invoice_id}/status/void

Request Example

$ curl https://invoice.zoho.com/api/v3/invoices/{invoice_id}/status/void -X POST -H "X-com-zoho-invoice-organizationid: 10234695" -H "Authorization: Zoho-oauthtoken 1000.41d9f2cfbd1b7a8f9e314b7aff7bc2d1.8fcc9810810a216793f385b9dd6e125f"

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.
oauthscope : ZohoInvoice.invoices.CREATE

POST /invoices/{invoice_id}/status/draft

Request Example

$ curl https://invoice.zoho.com/api/v3/invoices/{invoice_id}/status/draft -X POST -H "X-com-zoho-invoice-organizationid: 10234695" -H "Authorization: Zoho-oauthtoken 1000.41d9f2cfbd1b7a8f9e314b7aff7bc2d1.8fcc9810810a216793f385b9dd6e125f"

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.
oauthscope : ZohoInvoice.invoices.CREATE

POST /invoices/{invoice_id}/email

Request Example

$ curl https://invoice.zoho.com/api/v3/invoices/{invoice_id}/email -X POST -H "X-com-zoho-invoice-organizationid: 10234695" -H "Content-Type: application/json;charset=UTF-8" -H "Authorization: Zoho-oauthtoken 1000.41d9f2cfbd1b7a8f9e314b7aff7bc2d1.8fcc9810810a216793f385b9dd6e125f" -d '{ "send_from_org_email_id": false, "to_mail_ids": [ "willsmith@bowmanfurniture.com" ], "cc_mail_ids": [ "peterparker@bowmanfurniture.com" ], "subject": "Invoice from Zillium Inc (Invoice#: INV-00001)", "body": "Dear Customer, <br><br><br><br>Thanks for your business. <br><br><br><br>The invoice INV-00001 is attached with this email. You can choose the easy way out and <a href= https://invoice.zoho.com/portal/zylkar/secure?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 Parameters

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

Get invoice email content

Get the email content of an invoice.
oauthscope : ZohoInvoice.invoices.READ

GET /invoices/{invoice_id}/email

Request Example

$ curl https://invoice.zoho.com/api/v3/invoices/{invoice_id}/email -H "X-com-zoho-invoice-organizationid: 10234695" -H "Authorization: Zoho-oauthtoken 1000.41d9f2cfbd1b7a8f9e314b7aff7bc2d1.8fcc9810810a216793f385b9dd6e125f"

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/portal/zylkar/secure?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", "email": "string" } ], "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": "Default", "email_template_id": "982000000000067" } ], "emailtemplate_documents": "", "to_contacts": [ { "first_name": "David", "selected": true, "phone": "+1-925-921-9201", "email": "string", "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, "email": "string", "organization_contact_id": "2000000002266", "is_org_email_id": true } ], "customer_id": 982000000567001 } }

Query Parameters

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.

Email invoices

Send invoices to your customers by email. Maximum of 10 invoices can be sent at once.
oauthscope : ZohoInvoice.invoices.CREATE

POST /invoices/email

Request Example

$ curl https://invoice.zoho.com/api/v3/invoices/email -X POST -H "X-com-zoho-invoice-organizationid: 10234695" -H "Content-Type: application/json;charset=UTF-8" -H "Authorization: Zoho-oauthtoken 1000.41d9f2cfbd1b7a8f9e314b7aff7bc2d1.8fcc9810810a216793f385b9dd6e125f" -d '{ "contacts": [ { "contact_id": 460000000026049, "email": true, "snail_mail": false } ] }'

Response Example

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

Arguments

Required
Contacts to whom email or snail mail has to be sent.

Query Parameters

invoice_ids
Required
Comma separated invoice ids which are to be emailed.

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.
oauthscope : ZohoInvoice.invoices.CREATE

POST /invoices/{invoice_id}/paymentreminder

Request Example

$ curl https://invoice.zoho.com/api/v3/invoices/{invoice_id}/paymentreminder -X POST -H "X-com-zoho-invoice-organizationid: 10234695" -H "Content-Type: application/json;charset=UTF-8" -H "Authorization: Zoho-oauthtoken 1000.41d9f2cfbd1b7a8f9e314b7aff7bc2d1.8fcc9810810a216793f385b9dd6e125f" -d '{ "to_mail_ids": [ "willsmith@bowmanfurniture.com" ], "cc_mail_ids": [ "peterparker@bowmanfurniture.com" ], "subject": "Invoice from Zillium Inc (Invoice#: INV-00001)", "body": "<br>Dear Mr. Sujin,&nbsp;<br><br>You might have missed the payment date and the invoice is now overdue by&nbsp;1&nbsp;days.<br><br>----------------------------------------------------------------------------------------<br><h2>Invoice# : INV-000004 </h2>Dated : 23 Dec 2016<br>----------------------------------------------------------------------------------------<br><b>&nbsp;Due Date &nbsp; &nbsp; &nbsp; &nbsp; : &nbsp;&nbsp;23 Dec 2016</b><br><b>&nbsp;Amount &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; : &nbsp;&nbsp;$139.65</b><br>----------------------------------------------------------------------------------------<br><br><span>Not to worry at all !&nbsp;</span>View your invoice and take the easy way out by making an&nbsp;<a href=\"https://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 Parameters

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

Get payment reminder mail content

Get the mail content of the payment reminder.
oauthscope : ZohoInvoice.invoices.READ

GET /invoices/{invoice_id}/paymentreminder

Request Example

$ curl https://invoice.zoho.com/api/v3/invoices/{invoice_id}/paymentreminder -H "X-com-zoho-invoice-organizationid: 10234695" -H "Authorization: Zoho-oauthtoken 1000.41d9f2cfbd1b7a8f9e314b7aff7bc2d1.8fcc9810810a216793f385b9dd6e125f"

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", "email": "string" } ], "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": "Default", "email_template_id": "982000000000067" } ], "emailtemplate_documents": "", "to_contacts": [ { "first_name": "David", "selected": true, "phone": "+1-925-921-9201", "email": "string", "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, "email": "string", "organization_contact_id": "2000000002266", "is_org_email_id": true } ], "customer_id": 982000000567001 } }

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.
oauthscope : ZohoInvoice.invoices.CREATE

POST /invoices/paymentreminder

Request Example

$ curl https://invoice.zoho.com/api/v3/invoices/paymentreminder -X POST -H "X-com-zoho-invoice-organizationid: 10234695" -H "Authorization: Zoho-oauthtoken 1000.41d9f2cfbd1b7a8f9e314b7aff7bc2d1.8fcc9810810a216793f385b9dd6e125f"

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": "2000000007037" } ], "code": 4083 } }

Query Parameters

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

Bulk export Invoices

Maximum of 25 invoices can be exported in a single pdf.
oauthscope : ZohoInvoice.invoices.READ

GET /invoices/pdf

Request Example

$ curl https://invoice.zoho.com/api/v3/invoices/pdf -H "X-com-zoho-invoice-organizationid: 10234695" -H "Authorization: Zoho-oauthtoken 1000.41d9f2cfbd1b7a8f9e314b7aff7bc2d1.8fcc9810810a216793f385b9dd6e125f"

Response Example

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

Query Parameters

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.
oauthscope : ZohoInvoice.invoices.READ

GET /invoices/print

Request Example

$ curl https://invoice.zoho.com/api/v3/invoices/print -H "X-com-zoho-invoice-organizationid: 10234695" -H "Authorization: Zoho-oauthtoken 1000.41d9f2cfbd1b7a8f9e314b7aff7bc2d1.8fcc9810810a216793f385b9dd6e125f"

Response Example

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

Query Parameters

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.
oauthscope : ZohoInvoice.invoices.CREATE

POST /invoices/{invoice_id}/paymentreminder/disable

Request Example

$ curl https://invoice.zoho.com/api/v3/invoices/{invoice_id}/paymentreminder/disable -X POST -H "X-com-zoho-invoice-organizationid: 10234695" -H "Authorization: Zoho-oauthtoken 1000.41d9f2cfbd1b7a8f9e314b7aff7bc2d1.8fcc9810810a216793f385b9dd6e125f"

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.
oauthscope : ZohoInvoice.invoices.CREATE

POST /invoices/{invoice_id}/paymentreminder/enable

Request Example

$ curl https://invoice.zoho.com/api/v3/invoices/{invoice_id}/paymentreminder/enable -X POST -H "X-com-zoho-invoice-organizationid: 10234695" -H "Authorization: Zoho-oauthtoken 1000.41d9f2cfbd1b7a8f9e314b7aff7bc2d1.8fcc9810810a216793f385b9dd6e125f"

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.
oauthscope : ZohoInvoice.invoices.CREATE

POST /invoices/{invoice_id}/writeoff

Request Example

$ curl https://invoice.zoho.com/api/v3/invoices/{invoice_id}/writeoff -X POST -H "X-com-zoho-invoice-organizationid: 10234695" -H "Authorization: Zoho-oauthtoken 1000.41d9f2cfbd1b7a8f9e314b7aff7bc2d1.8fcc9810810a216793f385b9dd6e125f"

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.
oauthscope : ZohoInvoice.invoices.CREATE

POST /invoices/{invoice_id}/writeoff/cancel

Request Example

$ curl https://invoice.zoho.com/api/v3/invoices/{invoice_id}/writeoff/cancel -X POST -H "X-com-zoho-invoice-organizationid: 10234695" -H "Authorization: Zoho-oauthtoken 1000.41d9f2cfbd1b7a8f9e314b7aff7bc2d1.8fcc9810810a216793f385b9dd6e125f"

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.
oauthscope : ZohoInvoice.invoices.UPDATE

PUT /invoices/{invoice_id}/address/billing

Request Example

$ curl https://invoice.zoho.com/api/v3/invoices/{invoice_id}/address/billing -X PUT -H "X-com-zoho-invoice-organizationid: 10234695" -H "Content-Type: application/json;charset=UTF-8" -H "Authorization: Zoho-oauthtoken 1000.41d9f2cfbd1b7a8f9e314b7aff7bc2d1.8fcc9810810a216793f385b9dd6e125f" -d '{ "address": "B-1104, 11F, \nHorizon International Tower, \nNo. 6, ZhiChun Road, HaiDian District", "city": "Beijing", "state": "Beijing", "zip": 1000881, "country": "string", "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.
oauthscope : ZohoInvoice.invoices.UPDATE

PUT /invoices/{invoice_id}/address/shipping

Request Example

$ curl https://invoice.zoho.com/api/v3/invoices/{invoice_id}/address/shipping -X PUT -H "X-com-zoho-invoice-organizationid: 10234695" -H "Content-Type: application/json;charset=UTF-8" -H "Authorization: Zoho-oauthtoken 1000.41d9f2cfbd1b7a8f9e314b7aff7bc2d1.8fcc9810810a216793f385b9dd6e125f" -d '{ "address": "4900 Hopyard Rd, Suit 310", "city": "Pleasanton", "state": "CA", "zip": 945881, "country": "USA", "fax": "+1-925-924-9600" }'

Response Example

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

Arguments

address
Optional
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.
oauthscope : ZohoInvoice.invoices.READ

GET /invoices/templates

Request Example

$ curl https://invoice.zoho.com/api/v3/invoices/templates -H "X-com-zoho-invoice-organizationid: 10234695" -H "Authorization: Zoho-oauthtoken 1000.41d9f2cfbd1b7a8f9e314b7aff7bc2d1.8fcc9810810a216793f385b9dd6e125f"

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.
oauthscope : ZohoInvoice.invoices.UPDATE

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

Request Example

$ curl https://invoice.zoho.com/api/v3/invoices/{invoice_id}/templates/{template_id} -X PUT -H "X-com-zoho-invoice-organizationid: 10234695" -H "Authorization: Zoho-oauthtoken 1000.41d9f2cfbd1b7a8f9e314b7aff7bc2d1.8fcc9810810a216793f385b9dd6e125f"

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.
oauthscope : ZohoInvoice.invoices.READ

GET /invoices/{invoice_id}/payments

Request Example

$ curl https://invoice.zoho.com/api/v3/invoices/{invoice_id}/payments -H "X-com-zoho-invoice-organizationid: 10234695" -H "Authorization: Zoho-oauthtoken 1000.41d9f2cfbd1b7a8f9e314b7aff7bc2d1.8fcc9810810a216793f385b9dd6e125f"

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.
oauthscope : ZohoInvoice.invoices.READ

GET /invoices/{invoice_id}/creditsapplied

Request Example

$ curl https://invoice.zoho.com/api/v3/invoices/{invoice_id}/creditsapplied -H "X-com-zoho-invoice-organizationid: 10234695" -H "Authorization: Zoho-oauthtoken 1000.41d9f2cfbd1b7a8f9e314b7aff7bc2d1.8fcc9810810a216793f385b9dd6e125f"

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.
oauthscope : ZohoInvoice.invoices.CREATE

POST /invoices/{invoice_id}/credits

Request Example

$ curl https://invoice.zoho.com/api/v3/invoices/{invoice_id}/credits -X POST -H "X-com-zoho-invoice-organizationid: 10234695" -H "Content-Type: application/json;charset=UTF-8" -H "Authorization: Zoho-oauthtoken 1000.41d9f2cfbd1b7a8f9e314b7aff7bc2d1.8fcc9810810a216793f385b9dd6e125f" -d '{ "invoice_payments": [ { "payment_id": 460000000031003, "amount_applied": 15 } ], "apply_creditnotes": [ { "creditnote_id": 460000000029003, "amount_applied": 22.5 } ] }'

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
Payments applied to an invoice.
payment_id
Optional
ID of the payment from which credit has to be applied.
amount_applied
Optional
Amount applied to the invoice.
apply_creditnotes
Optional
Credits applied to invoice.
creditnote_id
Optional
ID of the credit note from which credit has to be applied.
amount_applied
Optional
Amount applied to the invoice.

Delete a payment

Delete a payment made to an invoice.
oauthscope : ZohoInvoice.invoices.DELETE

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

Request Example

$ curl https://invoice.zoho.com/api/v3/invoices/{invoice_id}/payments/{invoice_payment_id} -X DELETE -H "X-com-zoho-invoice-organizationid: 10234695" -H "Authorization: Zoho-oauthtoken 1000.41d9f2cfbd1b7a8f9e314b7aff7bc2d1.8fcc9810810a216793f385b9dd6e125f"

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.
oauthscope : ZohoInvoice.invoices.DELETE

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

Request Example

$ curl https://invoice.zoho.com/api/v3/invoices/{invoice_id}/creditsapplied/{creditnotes_invoice_id} -X DELETE -H "X-com-zoho-invoice-organizationid: 10234695" -H "Authorization: Zoho-oauthtoken 1000.41d9f2cfbd1b7a8f9e314b7aff7bc2d1.8fcc9810810a216793f385b9dd6e125f"

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

Add attachment to an invoice

Attach a file to an invoice.
oauthscope : ZohoInvoice.invoices.CREATE

POST /invoices/{invoice_id}/attachment

Request Example

$ curl https://invoice.zoho.com/api/v3/invoices/{invoice_id}/attachment -X POST -H "X-com-zoho-invoice-organizationid: 10234695" -H "Authorization: Zoho-oauthtoken 1000.41d9f2cfbd1b7a8f9e314b7aff7bc2d1.8fcc9810810a216793f385b9dd6e125f"

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 Parameters

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.
oauthscope : ZohoInvoice.invoices.UPDATE

PUT /invoices/{invoice_id}/attachment

Request Example

$ curl https://invoice.zoho.com/api/v3/invoices/{invoice_id}/attachment -X PUT -H "X-com-zoho-invoice-organizationid: 10234695" -H "Authorization: Zoho-oauthtoken 1000.41d9f2cfbd1b7a8f9e314b7aff7bc2d1.8fcc9810810a216793f385b9dd6e125f"

Response Example

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

Query Parameters

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

Get an invoice attachment

Returns the file attached to the invoice.
oauthscope : ZohoInvoice.invoices.READ

GET /invoices/{invoice_id}/attachment

Request Example

$ curl https://invoice.zoho.com/api/v3/invoices/{invoice_id}/attachment -H "X-com-zoho-invoice-organizationid: 10234695" -H "Authorization: Zoho-oauthtoken 1000.41d9f2cfbd1b7a8f9e314b7aff7bc2d1.8fcc9810810a216793f385b9dd6e125f"

Response Example

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

Query Parameters

preview
Optional
Get the thumbnail of the attachment.

Delete an attachment

Delete the file attached to the invoice.
oauthscope : ZohoInvoice.invoices.DELETE

DELETE /invoices/{invoice_id}/attachment

Request Example

$ curl https://invoice.zoho.com/api/v3/invoices/{invoice_id}/attachment -X DELETE -H "X-com-zoho-invoice-organizationid: 10234695" -H "Authorization: Zoho-oauthtoken 1000.41d9f2cfbd1b7a8f9e314b7aff7bc2d1.8fcc9810810a216793f385b9dd6e125f"

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.
oauthscope : ZohoInvoice.invoices.DELETE

DELETE /invoices/expenses/{expense_id}/receipt

Request Example

$ curl https://invoice.zoho.com/api/v3/invoices/expenses/{expense_id}/receipt -X DELETE -H "X-com-zoho-invoice-organizationid: 10234695" -H "Authorization: Zoho-oauthtoken 1000.41d9f2cfbd1b7a8f9e314b7aff7bc2d1.8fcc9810810a216793f385b9dd6e125f"

Response Example

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

Add comment

Add a comment for an invoice.
oauthscope : ZohoInvoice.invoices.CREATE

POST /invoices/{invoice_id}/comments

Request Example

$ curl https://invoice.zoho.com/api/v3/invoices/{invoice_id}/comments -X POST -H "X-com-zoho-invoice-organizationid: 10234695" -H "Authorization: Zoho-oauthtoken 1000.41d9f2cfbd1b7a8f9e314b7aff7bc2d1.8fcc9810810a216793f385b9dd6e125f"

Response Example

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

Query Parameters

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

List invoice comments & history

Get the complete history and comments of an invoice.
oauthscope : ZohoInvoice.invoices.READ

GET /invoices/{invoice_id}/comments

Request Example

$ curl https://invoice.zoho.com/api/v3/invoices/{invoice_id}/comments -H "X-com-zoho-invoice-organizationid: 10234695" -H "Authorization: Zoho-oauthtoken 1000.41d9f2cfbd1b7a8f9e314b7aff7bc2d1.8fcc9810810a216793f385b9dd6e125f"

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-18", "date_description": "yesterday", "time": "2:38 AM", "transaction_id": "982000000567204", "transaction_type": "invoice" }, {...}, {...} ] }

Update comment

Update an existing comment of an invoice.
oauthscope : ZohoInvoice.invoices.UPDATE

PUT /invoices/{invoice_id}/comments/{comment_id}

Request Example

$ curl https://invoice.zoho.com/api/v3/invoices/{invoice_id}/comments/{comment_id} -X PUT -H "X-com-zoho-invoice-organizationid: 10234695" -H "Authorization: Zoho-oauthtoken 1000.41d9f2cfbd1b7a8f9e314b7aff7bc2d1.8fcc9810810a216793f385b9dd6e125f"

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 Parameters

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.
oauthscope : ZohoInvoice.invoices.DELETE

DELETE /invoices/{invoice_id}/comments/{comment_id}

Request Example

$ curl https://invoice.zoho.com/api/v3/invoices/{invoice_id}/comments/{comment_id} -X DELETE -H "X-com-zoho-invoice-organizationid: 10234695" -H "Authorization: Zoho-oauthtoken 1000.41d9f2cfbd1b7a8f9e314b7aff7bc2d1.8fcc9810810a216793f385b9dd6e125f"

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.

Possible error codes:
Error CodeMessage
1002Recurring Invoice does not exist
4031Please enter a name for this Recurring Invoice

Example

{ "recurring_invoice_id": "90300000072369", "recurrence_name": "MonthlyInvoice", "reference_number": "12314", "is_pre_gst": false, "gst_no": "22AAAAA0000A1Z5", "gst_treatment": "business_gst", "vat_treatment": "overseas", "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", "project_id": 90300000087378, "project_name": "Sample Project" } ], "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": true, "avatax_exempt_no": "string", "avatax_use_code": "string" }

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]
reference_number
string
The Order number of the Recurring Invoice.
is_pre_gst
India Edition only.
string
Applicable for transactions that fall before july 1, 2017
gst_no
India Edition only.
string
15 digit GST identification number of the customer.
gst_treatment
India Edition only.
string
Choose whether the contact is GST registered/unregistered/consumer/overseas. Allowed values are business_gst , business_none , overseas , consumer .
vat_treatment
UK edition Only
string
(Optional) VAT treatment for the invoices. VAT treatment denotes the location of the customer, if the customer resides in UK then the VAT treatment is uk. If the customer is in an EU country & VAT registered, you are resides in Northen Ireland and selling Goods then his VAT treatment is eu_vat_registered, if he resides outside of the UK then his VAT treatment is overseas (For Pre Brexit, this can be split as eu_vat_registered, eu_vat_not_registered and non_eu).
place_of_supply
India Edition only.
string
Place where the goods/services are supplied to. (If not given, place of contact given for the contact will be taken)
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.
currency_id
string
The currenct id of the currency
currency_code
string
The currency code in which the invoice is created.
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.
array
Line items of an invoice.
line_item_id
string
The line item id
quantity
int32
Quantity of the item included.
name
string
The name of the line item. Maximum length [100]
item_total
double
Total rate raised by this item. This would be the multiplicative product of item price and quantity.
sku
string
Enter item's SKU information
product_type
string
Enter goods/services
project_id
string
ID of the project
project_name
string
Name of the project.
billing_address
object
The address to which the Item has to be billed.
address
string
Billing address for the invoice
street2
string
city
string
City of the customer’s billing address.
state
string
State of the customer’s billing address.
zip
string
Zip code of the customer’s billing address.
country
string
Country of the customer’s billing address.
fax
string
Customer's fax number.
shipping_address
object
The address to which the Item has to be shipped.
address
string
Shipping address for the invoice
city
string
City of the customer’s shipping address.
state
string
State of the customer’s shipping address.
zip
string
Zip code of the customer’s shipping address.
country
string
Country of the customer’s shipping address.
fax
string
Customer's fax number.
payment_gateways
array
configured
boolean
Boolean check to see if a payment gateway ahs been configured
additional_field1
string
Paypal payment method. Allowed Values: standard and adaptive
gateway_name
string
Name of the payment gateway associated with the invoice. E.g. paypal, stripe.Allowed Values: paypal, authorize_net, payflow_pro, stripe, 2checkout and braintree
payment_options
object
Boolean check to see if a payment gateway ahs been configured
configured
boolean
Boolean check to see if a payment gateway ahs been configured
additional_field1
string
Paypal payment method. Allowed Values: standard and adaptive
gateway_name
string
Name of the payment gateway associated with the invoice. E.g. paypal, stripe.Allowed Values: paypal, authorize_net, payflow_pro, stripe, 2checkout and braintree
avatax_exempt_no
Avalara integration only
string
Exemption certificate number of the customer. Maximum length [25]
avatax_use_code
Avalara integration only
string
Used to group like customers for exemption purposes. It is a custom value that links customers to a tax rule. Select from Avalara [standard codes][1] or enter a custom code. Maximum length [25]

Create a Recurring Invoice

Creating a new recurring invoice.
oauthscope : ZohoInvoice.invoices.CREATE

POST /recurringinvoices

Request Example

$ curl https://invoice.zoho.com/api/v3/recurringinvoices -X POST -H "X-com-zoho-invoice-organizationid: 10234695" -H "Content-Type: application/json;charset=UTF-8" -H "Authorization: Zoho-oauthtoken 1000.41d9f2cfbd1b7a8f9e314b7aff7bc2d1.8fcc9810810a216793f385b9dd6e125f" -d '{ "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", "vat_treatment": "overseas", "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", "avatax_tax_code": "string", "avatax_use_code": "string", "item_total": 100, "product_type": "goods", "hsn_or_sac": 80540, "project_id": 90300000087378 } ], "tax_id": "903000000000356", "email": "test@zylker.org", "payment_gateways": [ { "configured": true, "additional_field1": "standard", "gateway_name": "paypal" } ], "tax_authority_id": "903000006345", "tax_exemption_id": "903000006345", "avatax_use_code": "string", "avatax_exempt_no": "string" }'

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", "vat_treatment": "overseas", "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", "project_id": 90300000087378, "project_name": "Sample Project" } ], "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": true, "avatax_exempt_no": "string", "avatax_use_code": "string" } }

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
UK edition Only
Optional
(Optional) VAT treatment for the invoices. VAT treatment denotes the location of the customer, if the customer resides in UK then the VAT treatment is uk. If the customer is in an EU country & VAT registered, you are resides in Northen Ireland and selling Goods then his VAT treatment is eu_vat_registered, if he resides outside of the UK then his VAT treatment is overseas (For Pre Brexit, this can be split as eu_vat_registered, eu_vat_not_registered and non_eu).
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]
description
Optional
A small description about the item. Maximum length [2000]
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
project_id
Optional
ID of the project
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.
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]

List Recurring Invoice

List the details of all recurring invoice.
oauthscope : ZohoInvoice.invoices.READ

GET /recurringinvoices

Request Example

$ curl https://invoice.zoho.com/api/v3/recurringinvoices -H "X-com-zoho-invoice-organizationid: 10234695" -H "Authorization: Zoho-oauthtoken 1000.41d9f2cfbd1b7a8f9e314b7aff7bc2d1.8fcc9810810a216793f385b9dd6e125f"

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, "project_id": 90300000087378 } ], "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": true }, {...}, {...} ] }

Query Parameters

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

Update Recurring Invoice

Update the recurring invoice.
oauthscope : ZohoInvoice.invoices.UPDATE

PUT /recurringinvoices/{recurring_invoice_id}

Request Example

$ curl https://invoice.zoho.com/api/v3/recurringinvoices/{recurring_invoice_id} -X PUT -H "X-com-zoho-invoice-organizationid: 10234695" -H "Content-Type: application/json;charset=UTF-8" -H "Authorization: Zoho-oauthtoken 1000.41d9f2cfbd1b7a8f9e314b7aff7bc2d1.8fcc9810810a216793f385b9dd6e125f" -d '{ "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", "vat_treatment": "overseas", "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", "avatax_tax_code": "string", "avatax_use_code": "string", "item_total": 100, "product_type": "goods", "hsn_or_sac": 80540, "project_id": 90300000087378 } ], "tax_id": "903000000000356", "email": "test@zylker.org", "payment_gateways": [ { "configured": true, "additional_field1": "standard", "gateway_name": "paypal" } ], "tax_authority_id": "903000006345", "tax_exemption_id": "903000006345", "avatax_use_code": "string", "avatax_exempt_no": "string" }'

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", "vat_treatment": "overseas", "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", "project_id": 90300000087378, "project_name": "Sample Project" } ], "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": true, "avatax_exempt_no": "string", "avatax_use_code": "string" } }

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
UK edition Only
Optional
(Optional) VAT treatment for the invoices. VAT treatment denotes the location of the customer, if the customer resides in UK then the VAT treatment is uk. If the customer is in an EU country & VAT registered, you are resides in Northen Ireland and selling Goods then his VAT treatment is eu_vat_registered, if he resides outside of the UK then his VAT treatment is overseas (For Pre Brexit, this can be split as eu_vat_registered, eu_vat_not_registered and non_eu).
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]
description
Optional
A small description about the item. Maximum length [2000]
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
project_id
Optional
ID of the project
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.
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.
oauthscope : ZohoInvoice.invoices.READ

GET /recurringinvoices/{recurring_invoice_id}

Request Example

$ curl https://invoice.zoho.com/api/v3/recurringinvoices/{recurring_invoice_id} -H "X-com-zoho-invoice-organizationid: 10234695" -H "Authorization: Zoho-oauthtoken 1000.41d9f2cfbd1b7a8f9e314b7aff7bc2d1.8fcc9810810a216793f385b9dd6e125f"

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", "vat_treatment": "overseas", "place_of_supply": "TN", "company_name": "ABC Studios", "customer_email": "test@zylker.org", "customer_mobile_phone": 1234, "customer_phone": 1234, "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", "project_id": 90300000087378, "project_name": "Sample Project" } ], "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": true } }

Delete a Recurring Invoice

Delete an existing recurring invoice.
oauthscope : ZohoInvoice.invoices.DELETE

DELETE /recurringinvoices/{recurring_invoice_id}

Request Example

$ curl https://invoice.zoho.com/api/v3/recurringinvoices/{recurring_invoice_id} -X DELETE -H "X-com-zoho-invoice-organizationid: 10234695" -H "Authorization: Zoho-oauthtoken 1000.41d9f2cfbd1b7a8f9e314b7aff7bc2d1.8fcc9810810a216793f385b9dd6e125f"

Response Example

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

Stop a Recurring Invoice

Stop an active recurring invoice.
oauthscope : ZohoInvoice.invoices.CREATE

POST /recurringinvoices/{recurring_invoice_id}/status/stop

Request Example

$ curl https://invoice.zoho.com/api/v3/recurringinvoices/{recurring_invoice_id}/status/stop -X POST -H "X-com-zoho-invoice-organizationid: 10234695" -H "Content-Type: application/json;charset=UTF-8" -H "Authorization: Zoho-oauthtoken 1000.41d9f2cfbd1b7a8f9e314b7aff7bc2d1.8fcc9810810a216793f385b9dd6e125f" -d '{ "recurring_invoice_id": "90300000072369" }'

Response Example

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

Arguments

recurring_invoice_id
Optional
Unique ID of the recurring invoice generated by the server.

Resume a Recurring Invoice

Resume a stopped recurring invoice.
oauthscope : ZohoInvoice.invoices.CREATE

POST /recurringinvoices/{recurring_invoice_id}/status/resume

Request Example

$ curl https://invoice.zoho.com/api/v3/recurringinvoices/{recurring_invoice_id}/status/resume -X POST -H "X-com-zoho-invoice-organizationid: 10234695" -H "Content-Type: application/json;charset=UTF-8" -H "Authorization: Zoho-oauthtoken 1000.41d9f2cfbd1b7a8f9e314b7aff7bc2d1.8fcc9810810a216793f385b9dd6e125f" -d '{ "recurring_invoice_id": "90300000072369" }'

Response Example

  
HTTP/1.1 201 Created Content-Type:application/json;charset=UTF-8 { "code": 0, "message": "The recurring invoice has been resumed." }

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.
oauthscope : ZohoInvoice.invoices.UPDATE

PUT /recurringinvoices/{recurring_invoice_id}/templates/{template_id}

Request Example

$ curl https://invoice.zoho.com/api/v3/recurringinvoices/{recurring_invoice_id}/templates/{template_id} -X PUT -H "X-com-zoho-invoice-organizationid: 10234695" -H "Content-Type: application/json;charset=UTF-8" -H "Authorization: Zoho-oauthtoken 1000.41d9f2cfbd1b7a8f9e314b7aff7bc2d1.8fcc9810810a216793f385b9dd6e125f" -d '{ "recurring_invoice_id": "90300000072369", "template_id": "90300043563547" }'

Response Example

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

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.
oauthscope : ZohoInvoice.invoices.READ

GET /recurringinvoices/{recurring_invoice_id}/comments

Request Example

$ curl https://invoice.zoho.com/api/v3/recurringinvoices/{recurring_invoice_id}/comments -H "X-com-zoho-invoice-organizationid: 10234695" -H "Authorization: Zoho-oauthtoken 1000.41d9f2cfbd1b7a8f9e314b7aff7bc2d1.8fcc9810810a216793f385b9dd6e125f"

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

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.

Possible error codes:
Error CodeMessage
3004The Customer field can neither be blank nor incorrect. Please enter a correct Customer
9521Partial payment for retainer invoice is not allowed. Please record the full payment
9523Payment amount made to retainer invoice cannot be changed. You could instead delete it and add it back
24016The amount entered is more than the balance due for this invoice

Example

{ "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": "test@zylker.org", "invoices": [ { "invoice_id": "90300000079426", "invoice_payment_id": "27161000000203281", "invoice_number": "INV-384", "date": "2016-06-05", "invoice_amount": 450, "amount_applied": 450, "balance_amount": 0 } ], "currency_code": "USD", "currency_symbol": "$", "custom_fields": [ { "customfield_id": 439910000000236000, "data_type": "number", "index": 1, "label": "Record Number", "show_on_pdf": true, "show_in_all_pdf": true, "value": 23 } ] }

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.
bank_charges
double
Denotes any additional bank charges.
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.
array
Invoice related to a payment
invoice_id
string
Invoice ID of the required invoice.
invoice_payment_id
string
Payment ID of the invoice.
invoice_number
string
Unique ID (starts with INV) of an invoice.
date
Date on which the invoice was raised.
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.
custom_fields
array
Custom fields for a payment received.
customfield_id
long
Unique ID of the custom field
data_type
string
Data type of the custom field
index
integer
The index of the custom field
label
string
Name of the custom field
show_on_pdf
boolean
Enable/Disable show this custom field on pdf for that invoice
show_in_all_pdf
Enable/Disable show this custom field on all the pdf
value
integer
Value of the custom field

Create a payment

Create a new payment.
oauthscope : ZohoInvoice.customerpayments.CREATE

POST /customerpayments

Request Example

$ curl https://invoice.zoho.com/api/v3/customerpayments -X POST -H "X-com-zoho-invoice-organizationid: 10234695" -H "Content-Type: application/json;charset=UTF-8" -H "Authorization: Zoho-oauthtoken 1000.41d9f2cfbd1b7a8f9e314b7aff7bc2d1.8fcc9810810a216793f385b9dd6e125f" -d '{ "customer_id": "903000000000099", "payment_mode": "cash", "amount": 450, "date": "2016-06-05", "reference_number": "INV-384", "description": "Payment has been added to INV-384", "invoices": [ { "invoice_id": "90300000079426", "amount_applied": 450 } ], "exchange_rate": 1, "bank_charges": 10, "custom_fields": [ { "label": "Record Number", "value": 23 } ] }'

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": "test@zylker.org", "invoices": [ { "invoice_id": "90300000079426", "invoice_payment_id": "27161000000203281", "invoice_number": "INV-384", "date": "2016-06-05", "invoice_amount": 450, "amount_applied": 450, "balance_amount": 0 } ], "currency_code": "USD", "currency_symbol": "$", "custom_fields": [ { "customfield_id": 439910000000236000, "data_type": "number", "index": 1, "label": "Record Number", "show_on_pdf": true, "show_in_all_pdf": true, "value": 23 } ] } }

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
Custom fields for a payment received.
label
Optional
Name of the custom field
value
Optional
Value of the custom field

List Customer Payments

List all the payments made by your customer.
oauthscope : ZohoInvoice.customerpayments.READ

GET /customerpayments

Request Example

$ curl https://invoice.zoho.com/api/v3/customerpayments -H "X-com-zoho-invoice-organizationid: 10234695" -H "Authorization: Zoho-oauthtoken 1000.41d9f2cfbd1b7a8f9e314b7aff7bc2d1.8fcc9810810a216793f385b9dd6e125f"

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 Parameters

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]

Update a payment

Update an existing payment information.
oauthscope : ZohoInvoice.customerpayments.UPDATE

PUT /customerpayments/{payment_id}

Request Example

$ curl https://invoice.zoho.com/api/v3/customerpayments/{payment_id} -X PUT -H "X-com-zoho-invoice-organizationid: 10234695" -H "Content-Type: application/json;charset=UTF-8" -H "Authorization: Zoho-oauthtoken 1000.41d9f2cfbd1b7a8f9e314b7aff7bc2d1.8fcc9810810a216793f385b9dd6e125f" -d '{ "customer_id": "903000000000099", "payment_mode": "cash", "amount": 450, "date": "2016-06-05", "reference_number": "INV-384", "description": "Payment has been added to INV-384", "invoices": [ { "invoice_id": "90300000079426", "invoice_payment_id": "27161000000203281", "amount_applied": 450 } ], "exchange_rate": 1, "bank_charges": 10, "custom_fields": [ { "label": "Record Number", "value": 23 } ] }'

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": "test@zylker.org", "invoices": [ { "invoice_id": "90300000079426", "invoice_payment_id": "27161000000203281", "invoice_number": "INV-384", "date": "2016-06-05", "invoice_amount": 450, "amount_applied": 450, "balance_amount": 0 } ], "currency_code": "USD", "currency_symbol": "$", "custom_fields": [ { "customfield_id": 439910000000236000, "data_type": "number", "index": 1, "label": "Record Number", "show_on_pdf": true, "show_in_all_pdf": true, "value": 23 } ] } }

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
Invoice associated to a payment
invoice_id
Required
Invoice ID of the required invoice.
invoice_payment_id
Optional
Payment ID of the 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 to support payment information
label
Optional
Name of the custom field
value
Optional
Value of the custom field

Retrieve a payment

Details of an existing payment.
oauthscope : ZohoInvoice.customerpayments.READ

GET /customerpayments/{payment_id}

Request Example

$ curl https://invoice.zoho.com/api/v3/customerpayments/{payment_id} -H "X-com-zoho-invoice-organizationid: 10234695" -H "Authorization: Zoho-oauthtoken 1000.41d9f2cfbd1b7a8f9e314b7aff7bc2d1.8fcc9810810a216793f385b9dd6e125f"

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": "test@zylker.org", "invoices": [ { "invoice_id": "90300000079426", "invoice_payment_id": "27161000000203281", "invoice_number": "INV-384", "date": "2016-06-05", "invoice_amount": 450, "amount_applied": 450, "balance_amount": 0 } ], "currency_code": "USD", "currency_symbol": "$", "custom_fields": [ { "customfield_id": 439910000000236000, "data_type": "number", "index": 1, "label": "Record Number", "show_on_pdf": true, "show_in_all_pdf": true, "value": 23 } ] } }

Delete a payment

Delete an existing payment.
oauthscope : ZohoInvoice.customerpayments.DELETE

DELETE /customerpayments/{payment_id}

Request Example

$ curl https://invoice.zoho.com/api/v3/customerpayments/{payment_id} -X DELETE -H "X-com-zoho-invoice-organizationid: 10234695" -H "Authorization: Zoho-oauthtoken 1000.41d9f2cfbd1b7a8f9e314b7aff7bc2d1.8fcc9810810a216793f385b9dd6e125f"

Response Example

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

Refund an excess customer payment

Refund the excess amount paid by the customer.
oauthscope : ZohoInvoice.customerpayments.CREATE

POST /customerpayments/{customer_payment_id}/refunds

Request Example

$ curl https://invoice.zoho.com/api/v3/customerpayments/{customer_payment_id}/refunds -X POST -H "X-com-zoho-invoice-organizationid: 10234695" -H "Content-Type: application/json;charset=UTF-8" -H "Authorization: Zoho-oauthtoken 1000.41d9f2cfbd1b7a8f9e314b7aff7bc2d1.8fcc9810810a216793f385b9dd6e125f" -d '{ "date": "2016-06-05", "refund_mode": "cash", "reference_number": "INV-384", "amount": 450, "exchange_rate": 1, "description": "Payment has been added to INV-384" }'

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.

List refunds of a customer payment

List all the refunds pertaining to an existing customer payment.
oauthscope : ZohoInvoice.customerpayments.READ

GET /customerpayments/{customer_payment_id}/refunds

Request Example

$ curl https://invoice.zoho.com/api/v3/customerpayments/{customer_payment_id}/refunds -H "X-com-zoho-invoice-organizationid: 10234695" -H "Authorization: Zoho-oauthtoken 1000.41d9f2cfbd1b7a8f9e314b7aff7bc2d1.8fcc9810810a216793f385b9dd6e125f"

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 }, {...}, {...} ] }

Update a refund

Update the refunded transaction.
oauthscope : ZohoInvoice.customerpayments.UPDATE

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

Request Example

$ curl https://invoice.zoho.com/api/v3/customerpayments/{customer_payment_id}/refunds/{refund_id} -X PUT -H "X-com-zoho-invoice-organizationid: 10234695" -H "Content-Type: application/json;charset=UTF-8" -H "Authorization: Zoho-oauthtoken 1000.41d9f2cfbd1b7a8f9e314b7aff7bc2d1.8fcc9810810a216793f385b9dd6e125f" -d '{ "date": "2016-06-05", "refund_mode": "cash", "reference_number": "INV-384", "amount": 450, "exchange_rate": 1, "description": "Payment has been added to INV-384" }'

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.

Details of a refund

Obtain details of a particular refund of a customer payment.
oauthscope : ZohoInvoice.customerpayments.READ

GET /customerpayments/{customer_payment_id}/refunds/{refund_id}

Request Example

$ curl https://invoice.zoho.com/api/v3/customerpayments/{customer_payment_id}/refunds/{refund_id} -H "X-com-zoho-invoice-organizationid: 10234695" -H "Authorization: Zoho-oauthtoken 1000.41d9f2cfbd1b7a8f9e314b7aff7bc2d1.8fcc9810810a216793f385b9dd6e125f"

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

Delete a Refund

Delete refund pertaining to an existing customer payment.
oauthscope : ZohoInvoice.customerpayments.DELETE

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

Request Example

$ curl https://invoice.zoho.com/api/v3/customerpayments/{customer_payment_id}/refunds/{refund_id} -X DELETE -H "X-com-zoho-invoice-organizationid: 10234695" -H "Authorization: Zoho-oauthtoken 1000.41d9f2cfbd1b7a8f9e314b7aff7bc2d1.8fcc9810810a216793f385b9dd6e125f"

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.

Possible error codes:
Error CodeMessage
9520Retainer Invoices for which payments have been recorded cannot be deleted
9533Cannot modify Retainer Invoice amount, once the payment is recorded

Example

{ "retainerinvoice_id": 982000000567114, "retainerinvoice_number": "RET-00003", "date": "2013-11-17", "status": "draft", "is_pre_gst": false, "place_of_supply": "TN", "project_id": 982000000567154, "project_name": "string", "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": [ { "customfield_id": 439910000000236000, "data_type": "number", "index": 1, "label": "Record Number", "show_on_pdf": true, "show_in_all_pdf": true, "value": 23 } ], "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/portal/zylkar/secure?CInvoiceID=23d84d0cf64f9a72ea0c66fded25a08c8bafd0ab508aff05323a9f80e2cd03fdc5dd568d3d6407bbda969d3e870d740b6fce549a9438c4ea" }

Attribute

retainerinvoice_id
string
The id of the retainerinvoice
retainerinvoice_number
string
number of the retainer invoice.
date
string
The date of creation of the retainer invoice.
status
string
retainer invoice status.Allowed Values: sent, draft, overdue, paid, void, unpaid, partially_paid and viewed
is_pre_gst
string
Applicable for transactions that fall before july 1, 2017
place_of_supply
India Edition only.
string
Place where the goods/services are supplied to. (If not given, place of contact given for the contact will be taken)
project_id
string
ID of the project
project_name
string
Name of the project
last_payment_date
string
The last payment date of the retainer invoice
reference_number
string
The reference number of the retainer invoice. Maximum length [100]
customer_id
string
ID of the customer the retainer invoice has to be created.
customer_name
string
The name of the customer. Maximum length [100]
contact_persons
array
The conatct persons associated with the contact.
currency_id
string
The currenct id of the currency
currency_code
string
The currency code in which the retainer invoice is created.
currency_symbol
string
The currency symbol in which the retainer invoice is created.
exchange_rate
float
Exchange rate of the currency.
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.
is_inclusive_tax
boolean
To check if the total amount is inclusive of tax
array
Line items of a retainer invoice.
line_item_id
string
The line item ID
description
string
The description of the line items. Maximum length [2000]
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
sub_total
float
The sub total of the all items
total
string
The total amount to be paid
array
List of the taxes levied
tax_name
string
The name of the tax
tax_amount
float
The amount of the tax levied
payment_made
float
The amount paid
payment_drawn
float
The amount drawn
balance
string
The unpaid amount
allow_partial_payments
boolean
Boolean to check if partial payments are allowed for the contact
price_precision
integer
The precision value on the price
payment_options
object
Payment options for the retainer invoice, online payment gateways and bank accounts. Will be displayed in the pdf.
payment_gateways
array
Online payment gateways through which payment can be made.
gateway_name
string
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
is_emailed
string
Boolean check to if the email was sent
documents
array
documents attached to the retainer invoice
billing_address
object
Organisation's billing address
address
string
Organisation's Billing address
street2
string
city
string
City of Organisation's billing address
state
string
State where organisation's billing location is mentioned
zip
string
ZIP of organisation's billing address
country
string
Country of organisation's billing address
fax
string
FAX number of organisation's billing address
shipping_address
object
Organisation's shipping address
address
string
Organisation's Billing address
street2
string
city
string
City of Organisation's billing address
state
string
State where organisation's billing location is mentioned
zip
string
ZIP of organisation's billing address
country
string
Country of organisation's billing address
fax
string
FAX number of organisation's billing address
notes
string
The notes added below expressing gratitude or for conveying some information.
terms
string
The terms added below expressing gratitude or for conveying some information.
custom_fields
array
Custom fields for a retainer invoice.
customfield_id
long
Unique ID of the custom field
data_type
string
Data type of the custom field
index
integer
The index of the custom field
label
string
Name of the custom field
show_on_pdf
boolean
Enable/Disable show this custom field on pdf for that invoice
show_in_all_pdf
Enable/Disable show this custom field on all the pdf
value
integer
Value of the custom field
template_id
string
ID of the pdf template associated with the retainer invoice.
template_name
string
Name of template used by organisation
page_width
string
Width of page of contents
page_height
string
Height of page of contents
orientation
string
Page orientation
template_type
string
The type of template type
created_time
string
The time of creation of the retainer invoice
last_modified_time
string
The time of last modification of the retainer invoice
created_by_id
string
Filted by ID of comment
attachment_name
string
name of file attached
can_send_in_mail
boolean
Check if attachment can be sent via mail
invoice_url
string
Url link of invoice

Create a retainer invoice

Create a retainer invoice for your customer.
oauthscope : ZohoInvoice.invoices.CREATE

POST /retainerinvoices

Request Example

$ curl https://invoice.zoho.com/api/v3/retainerinvoices -X POST -H "X-com-zoho-invoice-organizationid: 10234695" -H "Content-Type: application/json;charset=UTF-8" -H "Authorization: Zoho-oauthtoken 1000.41d9f2cfbd1b7a8f9e314b7aff7bc2d1.8fcc9810810a216793f385b9dd6e125f" -d '{ "customer_id": 982000000567001, "reference_number": " ", "date": "2013-11-17", "contact_persons": [ "982000000567003", "982000000567003" ], "custom_fields": [ { "label": "Record Number", "value": 23 } ], "notes": "Looking forward for your business.", "terms": "Terms & Conditions apply", "line_items": [ { "description": "500GB, USB 2.0 interface 1400 rpm, protective hard case.", "item_order": 1, "rate": 120 } ], "payment_options": { "payment_gateways": [ { "gateway_name": "paypal" } ] }, "template_id": 982000000000143, "place_of_supply": "TN" }'

Response Example

  
HTTP/1.1 201 Created Content-Type:application/json;charset=UTF-8 { "code": 0, "message": "The retainer invoice has been created.", "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, "project_name": "string", "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": [ { "customfield_id": 439910000000236000, "data_type": "number", "index": 1, "label": "Record Number", "show_on_pdf": true, "show_in_all_pdf": true, "value": 23 } ], "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/portal/zylkar/secure?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 retainer invoice.
label
Optional
Name of the custom field
value
Optional
Value 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.
description
Optional
The description of the line items. Maximum length [2000]
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 Parameters

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

List Retainer invoices

List all retainer invoices with pagination.
oauthscope : ZohoInvoice.invoices.READ

GET /retainerinvoices

Request Example

$ curl https://invoice.zoho.com/api/v3/retainerinvoices -H "X-com-zoho-invoice-organizationid: 10234695" -H "Authorization: Zoho-oauthtoken 1000.41d9f2cfbd1b7a8f9e314b7aff7bc2d1.8fcc9810810a216793f385b9dd6e125f"

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 Parameters

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

Update a retainer invoice

Update an existing invoice.
oauthscope : ZohoInvoice.invoices.UPDATE

PUT /retainerinvoices/{retainerinvoice_id}

Request Example

$ curl https://invoice.zoho.com/api/v3/retainerinvoices/{retainerinvoice_id} -X PUT -H "X-com-zoho-invoice-organizationid: 10234695" -H "Content-Type: application/json;charset=UTF-8" -H "Authorization: Zoho-oauthtoken 1000.41d9f2cfbd1b7a8f9e314b7aff7bc2d1.8fcc9810810a216793f385b9dd6e125f" -d '{ "customer_id": 982000000567001, "reference_number": " ", "date": "2013-11-17", "contact_persons": [ "982000000567003", "982000000567003" ], "custom_fields": [ { "label": "Record Number", "value": 23 } ], "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", "project_id": 982000000567154 }'

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, "project_name": "string", "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": [ { "customfield_id": 439910000000236000, "data_type": "number", "index": 1, "label": "Record Number", "show_on_pdf": true, "show_in_all_pdf": true, "value": 23 } ], "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/portal/zylkar/secure?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 retainer invoice.
label
Optional
Name of the custom field
value
Optional
Value 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 a retainer invoice.
description
Optional
The description of the line items. Maximum length [2000]
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)
project_id
Optional
ID of the project

Get a retainer invoice

Get the details of a retainer invoice.
oauthscope : ZohoInvoice.invoices.READ

GET /retainerinvoices/{retainerinvoice_id}

Request Example

$ curl https://invoice.zoho.com/api/v3/retainerinvoices/{retainerinvoice_id} -H "X-com-zoho-invoice-organizationid: 10234695" -H "Authorization: Zoho-oauthtoken 1000.41d9f2cfbd1b7a8f9e314b7aff7bc2d1.8fcc9810810a216793f385b9dd6e125f"

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, "project_name": "string", "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": [ { "customfield_id": 439910000000236000, "data_type": "number", "index": 1, "label": "Record Number", "show_on_pdf": true, "show_in_all_pdf": true, "value": 23 } ], "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/portal/zylkar/secure?CInvoiceID=23d84d0cf64f9a72ea0c66fded25a08c8bafd0ab508aff05323a9f80e2cd03fdc5dd568d3d6407bbda969d3e870d740b6fce549a9438c4ea" } }

Delete a retainer invoice

Delete an existing retainer invoice. Invoices which have payment or credits note applied cannot be deleted.
oauthscope : ZohoInvoice.invoices.DELETE

DELETE /retainerinvoices/{retainerinvoice_id}

Request Example

$ curl https://invoice.zoho.com/api/v3/retainerinvoices/{retainerinvoice_id} -X DELETE -H "X-com-zoho-invoice-organizationid: 10234695" -H "Authorization: Zoho-oauthtoken 1000.41d9f2cfbd1b7a8f9e314b7aff7bc2d1.8fcc9810810a216793f385b9dd6e125f"

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.
oauthscope : ZohoInvoice.invoices.CREATE

POST /retainerinvoices/{retainerinvoice_id}/status/sent

Request Example

$ curl https://invoice.zoho.com/api/v3/retainerinvoices/{retainerinvoice_id}/status/sent -X POST -H "X-com-zoho-invoice-organizationid: 10234695" -H "Authorization: Zoho-oauthtoken 1000.41d9f2cfbd1b7a8f9e314b7aff7bc2d1.8fcc9810810a216793f385b9dd6e125f"

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.
oauthscope : ZohoInvoice.invoices.UPDATE

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

Request Example

$ curl https://invoice.zoho.com/api/v3/retainerinvoices/{retainerinvoice_id}/templates/{template_id} -X PUT -H "X-com-zoho-invoice-organizationid: 10234695" -H "Authorization: Zoho-oauthtoken 1000.41d9f2cfbd1b7a8f9e314b7aff7bc2d1.8fcc9810810a216793f385b9dd6e125f"

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.
oauthscope : ZohoInvoice.invoices.CREATE

POST /retainerinvoices/{retainerinvoice_id}/status/void

Request Example

$ curl https://invoice.zoho.com/api/v3/retainerinvoices/{retainerinvoice_id}/status/void -X POST -H "X-com-zoho-invoice-organizationid: 10234695" -H "Authorization: Zoho-oauthtoken 1000.41d9f2cfbd1b7a8f9e314b7aff7bc2d1.8fcc9810810a216793f385b9dd6e125f"

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.
oauthscope : ZohoInvoice.invoices.CREATE

POST /retainerinvoices/{reatinerinvoice_id}/status/draft

Request Example

$ curl https://invoice.zoho.com/api/v3/retainerinvoices/{reatinerinvoice_id}/status/draft -X POST -H "X-com-zoho-invoice-organizationid: 10234695" -H "Authorization: Zoho-oauthtoken 1000.41d9f2cfbd1b7a8f9e314b7aff7bc2d1.8fcc9810810a216793f385b9dd6e125f"

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.
oauthscope : ZohoInvoice.invoices.CREATE

POST /retainerinvoices/{retainerinvoice_id}/email

Request Example

$ curl https://invoice.zoho.com/api/v3/retainerinvoices/{retainerinvoice_id}/email -X POST -H "X-com-zoho-invoice-organizationid: 10234695" -H "Content-Type: application/json;charset=UTF-8" -H "Authorization: Zoho-oauthtoken 1000.41d9f2cfbd1b7a8f9e314b7aff7bc2d1.8fcc9810810a216793f385b9dd6e125f" -d '{ "send_from_org_email_id": false, "to_mail_ids": [ "test@zylker.org" ], "cc_mail_ids": [ "test@zylker.org" ], "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/portal/zylkar/secure?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 Parameters

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.
oauthscope : ZohoInvoice.invoices.READ

GET /retainerinvoices/{retainerinvoice_id}/email

Request Example

$ curl https://invoice.zoho.com/api/v3/retainerinvoices/{retainerinvoice_id}/email -H "X-com-zoho-invoice-organizationid: 10234695" -H "Authorization: Zoho-oauthtoken 1000.41d9f2cfbd1b7a8f9e314b7aff7bc2d1.8fcc9810810a216793f385b9dd6e125f"

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/portal/zylkar/secure?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": "1234", "email": "test@zylker.org", "last_name": "Smith", "salutation": "Mr", "contact_person_id": 982000000567003, "mobile": "1234" } ], "attachment_name": "new file", "email_template_id": "string", "file_name": "RET-00001.pdf", "from_emails": [ { "user_name": "John Smith", "selected": false, "email": "test@zylker.org" } ], "customer_id": 982000000567001 }

Update billing address

Updates the billing address for this retainer invoice alone.
oauthscope : ZohoInvoice.invoices.UPDATE

PUT /retainerinvoices/{retainerinvoice_id}/address/billing

Request Example

$ curl https://invoice.zoho.com/api/v3/retainerinvoices/{retainerinvoice_id}/address/billing -X PUT -H "X-com-zoho-invoice-organizationid: 10234695" -H "Content-Type: application/json;charset=UTF-8" -H "Authorization: Zoho-oauthtoken 1000.41d9f2cfbd1b7a8f9e314b7aff7bc2d1.8fcc9810810a216793f385b9dd6e125f" -d '{ "address": "B-1104, 11F, \nHorizon International Tower, \nNo. 6, ZhiChun Road, HaiDian District", "city": "Beijing", "state": "Beijing", "zip": 1000881, "country": "string", "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.
oauthscope : ZohoInvoice.invoices.READ

GET /retainerinvoices/templates

Request Example

$ curl https://invoice.zoho.com/api/v3/retainerinvoices/templates -H "X-com-zoho-invoice-organizationid: 10234695" -H "Authorization: Zoho-oauthtoken 1000.41d9f2cfbd1b7a8f9e314b7aff7bc2d1.8fcc9810810a216793f385b9dd6e125f"

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.
oauthscope : ZohoInvoice.invoices.READ

GET /customerpayments/{retainerinvoice_id}

Request Example

$ curl https://invoice.zoho.com/api/v3/customerpayments/{retainerinvoice_id} -H "X-com-zoho-invoice-organizationid: 10234695" -H "Authorization: Zoho-oauthtoken 1000.41d9f2cfbd1b7a8f9e314b7aff7bc2d1.8fcc9810810a216793f385b9dd6e125f"

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": [ { "customfield_id": 439910000000236000, "data_type": "number", "index": 1, "label": "Record Number", "show_on_pdf": true, "show_in_all_pdf": true, "value": 23 } ] }, {...}, {...} ] }

Delete a retainer payment

Delete a payment made to a retainer invoice.
oauthscope : ZohoInvoice.invoices.DELETE

DELETE /customerpayments/{retainer_payment_id}

Request Example

$ curl https://invoice.zoho.com/api/v3/customerpayments/{retainer_payment_id} -X DELETE -H "X-com-zoho-invoice-organizationid: 10234695" -H "Authorization: Zoho-oauthtoken 1000.41d9f2cfbd1b7a8f9e314b7aff7bc2d1.8fcc9810810a216793f385b9dd6e125f"

Response Example

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

Add attachment to a retainer invoice

Attach a file to an invoice.
oauthscope : ZohoInvoice.invoices.CREATE

POST /retainerinvoices/{retainerinvoice_id}/attachment

Request Example

$ curl https://invoice.zoho.com/api/v3/retainerinvoices/{retainerinvoice_id}/attachment -X POST -H "X-com-zoho-invoice-organizationid: 10234695" -H "Content-Type: application/json;charset=UTF-8" -H "Authorization: Zoho-oauthtoken 1000.41d9f2cfbd1b7a8f9e314b7aff7bc2d1.8fcc9810810a216793f385b9dd6e125f" -d '{ "can_send_in_mail": true, "attachment": "string" }'

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

Get a retainer invoice attachment

Returns the file attached to the retainer invoice.
oauthscope : ZohoInvoice.invoices.READ

GET /retainerinvoices/{retainerinvoice_id}/attachment

Request Example

$ curl https://invoice.zoho.com/api/v3/retainerinvoices/{retainerinvoice_id}/attachment -H "X-com-zoho-invoice-organizationid: 10234695" -H "Authorization: Zoho-oauthtoken 1000.41d9f2cfbd1b7a8f9e314b7aff7bc2d1.8fcc9810810a216793f385b9dd6e125f"

Response Example

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

Delete an attachment

Delete the file attached to the retainer invoice.
oauthscope : ZohoInvoice.invoices.DELETE

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

Request Example

$ curl https://invoice.zoho.com/api/v3/retainerinvoices/{retainerinvoice_id}/documents/{document_id} -X DELETE -H "X-com-zoho-invoice-organizationid: 10234695" -H "Authorization: Zoho-oauthtoken 1000.41d9f2cfbd1b7a8f9e314b7aff7bc2d1.8fcc9810810a216793f385b9dd6e125f"

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.
oauthscope : ZohoInvoice.invoices.READ

GET /retainerinvoices/{retainernvoice_id}/comments

Request Example

$ curl https://invoice.zoho.com/api/v3/retainerinvoices/{retainernvoice_id}/comments -H "X-com-zoho-invoice-organizationid: 10234695" -H "Authorization: Zoho-oauthtoken 1000.41d9f2cfbd1b7a8f9e314b7aff7bc2d1.8fcc9810810a216793f385b9dd6e125f"

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.
oauthscope : ZohoInvoice.invoices.CREATE

POST /retainerinvoices/{retainerinvoice_id}/comments

Request Example

$ curl https://invoice.zoho.com/api/v3/retainerinvoices/{retainerinvoice_id}/comments -X POST -H "X-com-zoho-invoice-organizationid: 10234695" -H "Content-Type: application/json;charset=UTF-8" -H "Authorization: Zoho-oauthtoken 1000.41d9f2cfbd1b7a8f9e314b7aff7bc2d1.8fcc9810810a216793f385b9dd6e125f" -d '{ "description": "comment added", "payment_expected_date": " ", "show_comment_to_clients": true }'

Response Example

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

Arguments

description
Optional
The description of the line items. 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

Update comment

Update an existing comment of a retainer invoice.
oauthscope : ZohoInvoice.invoices.UPDATE

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

Request Example

$ curl https://invoice.zoho.com/api/v3/retainerinvoices/{retainerinvoice_id}/comments/{comment_id} -X PUT -H "X-com-zoho-invoice-organizationid: 10234695" -H "Content-Type: application/json;charset=UTF-8" -H "Authorization: Zoho-oauthtoken 1000.41d9f2cfbd1b7a8f9e314b7aff7bc2d1.8fcc9810810a216793f385b9dd6e125f" -d '{ "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

Delete a comment

Delete a retainer invoice comment.
oauthscope : ZohoInvoice.invoices.DELETE

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

Request Example

$ curl https://invoice.zoho.com/api/v3/retainerinvoices/{retainerinvoice_id}/comments/{comment_id} -X DELETE -H "X-com-zoho-invoice-organizationid: 10234695" -H "Authorization: Zoho-oauthtoken 1000.41d9f2cfbd1b7a8f9e314b7aff7bc2d1.8fcc9810810a216793f385b9dd6e125f"

Response Example

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

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.

Possible error codes:
Error CodeMessage
1002Credit Note does not exists
12003Credit notes that are in closed status cannot be applied to invoices
12004Credit notes that are in void status cannot be applied to invoices
12005Credits cannot be applied to invoices in the draft status
12006Credits cannot be applied to invoices in the closed status
12007Credits cannot be applied to invoices in the void status
12018The specified Credit Note Number already exists

Example

{ "creditnote_id": "90300000072369", "creditnote_number": "CN-29", "date": "2016-06-05", "status": "open", "customer_id": "903000000000099", "product_type": "goods", "serial_numbers": "string", "customer_name": "Bowman Furniture", "custom_fields": [ { "customfield_id": 439910000000236000, "data_type": "text", "label": "label", "show_on_pdf": true, "show_in_all_pdf": true, "value": 129890 } ], "reference_number": "INV-384", "email": "test@zylker.org", "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, "project_id": 90300000087378, "project_name": "Sample Project" } ], "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" }

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]
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.
product_type
string
Enter goods/services
serial_numbers
string
Enter serial number
customer_name
string
Name of the customer to whom the credit note is raised. Maximum Length of the name [100]
custom_fields
array
Custom fields for a credit note.
customfield_id
long
Unique ID of the custom field
data_type
string
Data type of the custom field.
label
string
Label of the custom field.
show_on_pdf
boolean
Enable/Disable show this custom field on pdf for that invoice
show_in_all_pdf
Enable/Disable show this custom field on all the pdf
value
string
Value 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.
array
Items present in a credit note
item_id
string
Unique string generated for the item to which a refund is to be made.
description
string
A small description about the item.
name
string
Name of the credit note item.
type
integer
Type of the creditnote line item.
quantity
int32
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
project_id
string
ID of the project
project_name
string
Name of the project.
array
Invoices included for a credit note 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.
array
Taxes associated with the subscription.
tax_id
string
Unique to denote the tax associate dto the creditnote
tax_name
string
Unique name for tax.
tax_amount
string
Tax amount applied to the subscription.
currency_code
string
Customer's currency code. This currency code is used in credit notes.
currency_symbol
string
Customer's currency symbol.
billing_address
object
Address to which a customer is billed
address
string
Billing address for the invoice
city
string
City of the customer’s billing address.
state
string
State of the customer’s billing address.
zip
string
Zip code of the customer’s billing address.
country
string
Country of the customer’s billing address.
fax
string
Customer's fax number.
shipping_address
object
Address to which goods/any exchange must be shipped to contact
address
string
Billing address for the invoice
city
string
City of the customer’s billing address.
state
string
State of the customer’s billing address.
zip
string
Zip code of the customer’s billing address.
country
string
Country of the customer’s billing address.
fax
string
Customer's fax number.
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
notes
string
A short note for the credit note. Maximum length [5000]
terms
string
Terms & condition to be displayed in the credit note. Maximum length [10000]

Create a credit note

Details of an existing creditnote.
oauthscope : ZohoInvoice.creditnotes.CREATE

POST /creditnotes

Request Example

$ curl https://invoice.zoho.com/api/v3/creditnotes -X POST -H "X-com-zoho-invoice-organizationid: 10234695" -H "Content-Type: application/json;charset=UTF-8" -H "Authorization: Zoho-oauthtoken 1000.41d9f2cfbd1b7a8f9e314b7aff7bc2d1.8fcc9810810a216793f385b9dd6e125f" -d '{ "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", "avatax_tax_code": "string", "avatax_use_code": "string", "rate": 100, "item_total": 100, "product_type": "goods", "hsn_or_sac": 80540, "project_id": 90300000087378 } ], "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": [ { "label": "label", "value": 129890 } ], "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", "avatax_use_code": "string", "avatax_tax_code": "string", "avatax_exempt_no": "string", "vat_treatment": "overseas" }'

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", "serial_numbers": "string", "customer_name": "Bowman Furniture", "custom_fields": [ { "customfield_id": 439910000000236000, "data_type": "text", "label": "label", "show_on_pdf": true, "show_in_all_pdf": true, "value": 129890 } ], "reference_number": "INV-384", "email": "test@zylker.org", "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, "project_id": 90300000087378, "project_name": "Sample Project" } ], "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.
description
Optional
A small description about the item.
name
Optional
Name of the credit note item.
type
Optional
Type of the creditnote line 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
project_id
Optional
ID of the project
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
Custom fields for a credit note.
label
Optional
Label of the custom field.
value
Optional
Value 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
UK edition Only
Optional
(Optional) VAT treatment for the credit notes. VAT treatment denotes the location of the customer, if the customer resides in UK then the VAT treatment is uk. If the customer is in an EU country & VAT registered, you are resides in Northen Ireland and selling Goods then his VAT treatment is eu_vat_registered, if he resides outside of the UK then his VAT treatment is overseas (For Pre Brexit, this can be split as eu_vat_registered, eu_vat_not_registered and non_eu).

Query Parameters

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.

List Credit Notes

List all the Credit Notes.
oauthscope : ZohoInvoice.creditnotes.READ

GET /creditnotes

Request Example

$ curl https://invoice.zoho.com/api/v3/creditnotes -H "X-com-zoho-invoice-organizationid: 10234695" -H "Authorization: Zoho-oauthtoken 1000.41d9f2cfbd1b7a8f9e314b7aff7bc2d1.8fcc9810810a216793f385b9dd6e125f"

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 Parameters

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

Update a credit note

Update Details of an existing creditnote.
oauthscope : ZohoInvoice.creditnotes.UPDATE

PUT /creditnotes/{creditnote_id}

Request Example

$ curl https://invoice.zoho.com/api/v3/creditnotes/{creditnote_id} -X PUT -H "X-com-zoho-invoice-organizationid: 10234695" -H "Content-Type: application/json;charset=UTF-8" -H "Authorization: Zoho-oauthtoken 1000.41d9f2cfbd1b7a8f9e314b7aff7bc2d1.8fcc9810810a216793f385b9dd6e125f" -d '{ "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", "avatax_tax_code": "string", "avatax_use_code": "string", "rate": 100, "item_total": 100, "product_type": "goods", "hsn_or_sac": 80540, "project_id": 90300000087378 } ], "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": [ { "label": "label", "value": 129890 } ], "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", "avatax_use_code": "string", "avatax_tax_code": "string", "avatax_exempt_no": "string", "vat_treatment": "overseas" }'

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", "serial_numbers": "string", "customer_name": "Bowman Furniture", "custom_fields": [ { "customfield_id": 439910000000236000, "data_type": "text", "label": "label", "show_on_pdf": true, "show_in_all_pdf": true, "value": 129890 } ], "reference_number": "INV-384", "email": "test@zylker.org", "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, "project_id": 90300000087378, "project_name": "Sample Project" } ], "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.
description
Optional
A small description about the item.
name
Optional
Name of the credit note item.
type
Optional
Type of the creditnote line 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
project_id
Optional
ID of the project
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
Custom fields for a credit note.
label
Optional
Label of the custom field.
value
Optional
Value 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
UK edition Only
Optional
(Optional) VAT treatment for the credit notes. VAT treatment denotes the location of the customer, if the customer resides in UK then the VAT treatment is uk. If the customer is in an EU country & VAT registered, you are resides in Northen Ireland and selling Goods then his VAT treatment is eu_vat_registered, if he resides outside of the UK then his VAT treatment is overseas (For Pre Brexit, this can be split as eu_vat_registered, eu_vat_not_registered and non_eu).

Query Parameters

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.
oauthscope : ZohoInvoice.creditnotes.READ

GET /creditnotes/{creditnote_id}

Request Example

$ curl https://invoice.zoho.com/api/v3/creditnotes/{creditnote_id} -H "X-com-zoho-invoice-organizationid: 10234695" -H "Authorization: Zoho-oauthtoken 1000.41d9f2cfbd1b7a8f9e314b7aff7bc2d1.8fcc9810810a216793f385b9dd6e125f"

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", "serial_numbers": "string", "customer_name": "Bowman Furniture", "custom_fields": [ { "customfield_id": 439910000000236000, "data_type": "text", "label": "label", "show_on_pdf": true, "show_in_all_pdf": true, "value": 129890 } ], "reference_number": "INV-384", "email": "test@zylker.org", "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, "project_id": 90300000087378, "project_name": "Sample Project" } ], "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 Parameters

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

Delete a credit note

Delete an existing credit note.
oauthscope : ZohoInvoice.creditnotes.DELETE

DELETE /creditnotes/{creditnote_id}

Request Example

$ curl https://invoice.zoho.com/api/v3/creditnotes/{creditnote_id} -X DELETE -H "X-com-zoho-invoice-organizationid: 10234695" -H "Authorization: Zoho-oauthtoken 1000.41d9f2cfbd1b7a8f9e314b7aff7bc2d1.8fcc9810810a216793f385b9dd6e125f"

Response Example

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

Email a credit note

Email a credit note.
oauthscope : ZohoInvoice.creditnotes.CREATE

POST /creditnotes/{creditnote_id}/email

Request Example

$ curl https://invoice.zoho.com/api/v3/creditnotes/{creditnote_id}/email -X POST -H "X-com-zoho-invoice-organizationid: 10234695" -H "Content-Type: application/json;charset=UTF-8" -H "Authorization: Zoho-oauthtoken 1000.41d9f2cfbd1b7a8f9e314b7aff7bc2d1.8fcc9810810a216793f385b9dd6e125f" -d '{ "to_mail_ids": [ "test@zylker.org", "test1@zylker.org" ], "cc_mail_ids": [ "test@zylker.org" ], "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 Parameters

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.
oauthscope : ZohoInvoice.creditnotes.CREATE

POST /creditnotes/{creditnote_id}/void

Request Example

$ curl https://invoice.zoho.com/api/v3/creditnotes/{creditnote_id}/void -X POST -H "X-com-zoho-invoice-organizationid: 10234695" -H "Authorization: Zoho-oauthtoken 1000.41d9f2cfbd1b7a8f9e314b7aff7bc2d1.8fcc9810810a216793f385b9dd6e125f"

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.
oauthscope : ZohoInvoice.creditnotes.CREATE

POST /creditnotes/{creditnote_id}/converttoopen

Request Example

$ curl https://invoice.zoho.com/api/v3/creditnotes/{creditnote_id}/converttoopen -X POST -H "X-com-zoho-invoice-organizationid: 10234695" -H "Authorization: Zoho-oauthtoken 1000.41d9f2cfbd1b7a8f9e314b7aff7bc2d1.8fcc9810810a216793f385b9dd6e125f"

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

Email history

Get email history of a credit code.
oauthscope : ZohoInvoice.creditnotes.READ

GET /creditnotes/{creditnote_id}/emailhistory

Request Example

$ curl https://invoice.zoho.com/api/v3/creditnotes/{creditnote_id}/emailhistory -H "X-com-zoho-invoice-organizationid: 10234695" -H "Authorization: Zoho-oauthtoken 1000.41d9f2cfbd1b7a8f9e314b7aff7bc2d1.8fcc9810810a216793f385b9dd6e125f"

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": [ "test@zylker.org", "test1@zylker.org" ], "subject": "Credit note for subscription.", "date": "2016-06-05" }, {...}, {...} ] }

Update billing address

Updates the billing address for an existing credit note alone.
oauthscope : ZohoInvoice.creditnotes.UPDATE

PUT /creditnotes/{creditnote_id}/address/billing

Request Example

$ curl https://invoice.zoho.com/api/v3/creditnotes/{creditnote_id}/address/billing -X PUT -H "X-com-zoho-invoice-organizationid: 10234695" -H "Content-Type: application/json;charset=UTF-8" -H "Authorization: Zoho-oauthtoken 1000.41d9f2cfbd1b7a8f9e314b7aff7bc2d1.8fcc9810810a216793f385b9dd6e125f" -d '{ "address": "4900 Hopyard Rd, Suite 310", "city": "Pleasanton", "state": "CA", "zip": 94588, "country": "USA", "fax": "+1-925-924-9600" }'

Response Example

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

Arguments

address
Optional
Billing address 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.
oauthscope : ZohoInvoice.creditnotes.UPDATE

PUT /creditnotes/{creditnote_id}/address/shipping

Request Example

$ curl https://invoice.zoho.com/api/v3/creditnotes/{creditnote_id}/address/shipping -X PUT -H "X-com-zoho-invoice-organizationid: 10234695" -H "Content-Type: application/json;charset=UTF-8" -H "Authorization: Zoho-oauthtoken 1000.41d9f2cfbd1b7a8f9e314b7aff7bc2d1.8fcc9810810a216793f385b9dd6e125f" -d '{ "address": "Suite 125, McMillan Avenue", "city": "San Francisco", "state": "CA", "zip": 94134, "country": "USA", "fax": "+1-925-924-9600" }'

Response Example

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

Arguments

address
Optional
Billing Address 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.
oauthscope : ZohoInvoice.creditnotes.READ

GET /creditnotes/templates

Request Example

$ curl https://invoice.zoho.com/api/v3/creditnotes/templates -H "X-com-zoho-invoice-organizationid: 10234695" -H "Authorization: Zoho-oauthtoken 1000.41d9f2cfbd1b7a8f9e314b7aff7bc2d1.8fcc9810810a216793f385b9dd6e125f"

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.
oauthscope : ZohoInvoice.creditnotes.UPDATE

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

Request Example

$ curl https://invoice.zoho.com/api/v3/creditnotes/{creditnote_id}/templates/{template_id} -X PUT -H "X-com-zoho-invoice-organizationid: 10234695" -H "Authorization: Zoho-oauthtoken 1000.41d9f2cfbd1b7a8f9e314b7aff7bc2d1.8fcc9810810a216793f385b9dd6e125f"

Response Example

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

Credit to an invoice

Apply credit note to existing invoices.
oauthscope : ZohoInvoice.creditnotes.CREATE

POST /creditnotes/{creditnote_id}/invoices

Request Example

$ curl https://invoice.zoho.com/api/v3/creditnotes/{creditnote_id}/invoices -X POST -H "X-com-zoho-invoice-organizationid: 10234695" -H "Content-Type: application/json;charset=UTF-8" -H "Authorization: Zoho-oauthtoken 1000.41d9f2cfbd1b7a8f9e314b7aff7bc2d1.8fcc9810810a216793f385b9dd6e125f" -d '{ "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.

List invoices credited

List invoices to which the credit note is applied.
oauthscope : ZohoInvoice.creditnotes.READ

GET /creditnotes/{creditnote_id}/invoices

Request Example

$ curl https://invoice.zoho.com/api/v3/creditnotes/{creditnote_id}/invoices -H "X-com-zoho-invoice-organizationid: 10234695" -H "Authorization: Zoho-oauthtoken 1000.41d9f2cfbd1b7a8f9e314b7aff7bc2d1.8fcc9810810a216793f385b9dd6e125f"

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 }, {...}, {...} ] }

Delete invoices credited

Delete the credits applied to an invoice.
oauthscope : ZohoInvoice.creditnotes.DELETE

DELETE /creditnotes/{creditnote_id}/invoices/{creditnote_invoice_id}

Request Example

$ curl https://invoice.zoho.com/api/v3/creditnotes/{creditnote_id}/invoices/{creditnote_invoice_id} -X DELETE -H "X-com-zoho-invoice-organizationid: 10234695" -H "Authorization: Zoho-oauthtoken 1000.41d9f2cfbd1b7a8f9e314b7aff7bc2d1.8fcc9810810a216793f385b9dd6e125f"

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

Add a comment

Add a comment to an existing credit note.
oauthscope : ZohoInvoice.creditnotes.CREATE

POST /creditnotes/{creditnote_id}/comments

Request Example

$ curl https://invoice.zoho.com/api/v3/creditnotes/{creditnote_id}/comments -X POST -H "X-com-zoho-invoice-organizationid: 10234695" -H "Content-Type: application/json;charset=UTF-8" -H "Authorization: Zoho-oauthtoken 1000.41d9f2cfbd1b7a8f9e314b7aff7bc2d1.8fcc9810810a216793f385b9dd6e125f" -d '{ "description": "Credits applied to invoice INV-00004" }'

Response Example

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

Arguments

description
Optional
A short note on the credit applied

List credit note comments & history

Get history and comments of a credit note.
oauthscope : ZohoInvoice.creditnotes.READ

GET /creditnotes/{creditnote_id}/comments

Request Example

$ curl https://invoice.zoho.com/api/v3/creditnotes/{creditnote_id}/comments -H "X-com-zoho-invoice-organizationid: 10234695" -H "Authorization: Zoho-oauthtoken 1000.41d9f2cfbd1b7a8f9e314b7aff7bc2d1.8fcc9810810a216793f385b9dd6e125f"

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

Delete a Comment

Delete a credit note comment.
oauthscope : ZohoInvoice.creditnotes.DELETE

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

Request Example

$ curl https://invoice.zoho.com/api/v3/creditnotes/{creditnote_id}/comments/{comment_id} -X DELETE -H "X-com-zoho-invoice-organizationid: 10234695" -H "Authorization: Zoho-oauthtoken 1000.41d9f2cfbd1b7a8f9e314b7aff7bc2d1.8fcc9810810a216793f385b9dd6e125f"

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.
oauthscope : ZohoInvoice.creditnotes.READ

GET /creditnotes/refunds

Request Example

$ curl https://invoice.zoho.com/api/v3/creditnotes/refunds -H "X-com-zoho-invoice-organizationid: 10234695" -H "Authorization: Zoho-oauthtoken 1000.41d9f2cfbd1b7a8f9e314b7aff7bc2d1.8fcc9810810a216793f385b9dd6e125f"

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 Parameters

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

Refund credit note

Refund credit note amount.
oauthscope : ZohoInvoice.creditnotes.CREATE

POST /creditnotes/{creditnote_id}/refunds

Request Example

$ curl https://invoice.zoho.com/api/v3/creditnotes/{creditnote_id}/refunds -X POST -H "X-com-zoho-invoice-organizationid: 10234695" -H "Content-Type: application/json;charset=UTF-8" -H "Authorization: Zoho-oauthtoken 1000.41d9f2cfbd1b7a8f9e314b7aff7bc2d1.8fcc9810810a216793f385b9dd6e125f" -d '{ "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.

List refunds of a credit note

List all refunds of an existing credit note.
oauthscope : ZohoInvoice.creditnotes.READ

GET /creditnotes/{creditnote_id}/refunds

Request Example

$ curl https://invoice.zoho.com/api/v3/creditnotes/{creditnote_id}/refunds -H "X-com-zoho-invoice-organizationid: 10234695" -H "Authorization: Zoho-oauthtoken 1000.41d9f2cfbd1b7a8f9e314b7aff7bc2d1.8fcc9810810a216793f385b9dd6e125f"

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 }, {...}, {...} ] }

Update credit note refund

Update the refunded transaction.
oauthscope : ZohoInvoice.creditnotes.UPDATE

PUT /creditnotes/{creditnote_id}/refunds/{creditnote_refund_id}

Request Example

$ curl https://invoice.zoho.com/api/v3/creditnotes/{creditnote_id}/refunds/{creditnote_refund_id} -X PUT -H "X-com-zoho-invoice-organizationid: 10234695" -H "Content-Type: application/json;charset=UTF-8" -H "Authorization: Zoho-oauthtoken 1000.41d9f2cfbd1b7a8f9e314b7aff7bc2d1.8fcc9810810a216793f385b9dd6e125f" -d '{ "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.

Get credit note refund

Get refund of a particular credit note.
oauthscope : ZohoInvoice.creditnotes.READ

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

Request Example

$ curl https://invoice.zoho.com/api/v3/creditnotes/{creditnote_id}/refunds/{creditnote_refund_id} -H "X-com-zoho-invoice-organizationid: 10234695" -H "Authorization: Zoho-oauthtoken 1000.41d9f2cfbd1b7a8f9e314b7aff7bc2d1.8fcc9810810a216793f385b9dd6e125f"

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

Delete credit note refund

Delete a credit note refund.
oauthscope : ZohoInvoice.creditnotes.DELETE

DELETE /creditnotes/{creditnote_id}/refunds/{creditnote_refund_id}

Request Example

$ curl https://invoice.zoho.com/api/v3/creditnotes/{creditnote_id}/refunds/{creditnote_refund_id} -X DELETE -H "X-com-zoho-invoice-organizationid: 10234695" -H "Authorization: Zoho-oauthtoken 1000.41d9f2cfbd1b7a8f9e314b7aff7bc2d1.8fcc9810810a216793f385b9dd6e125f"

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.

Possible error codes:
Error CodeMessage
1002Expense does not exists
5001Expenses that were converted to an invoice cannot be deleted
5015Enter a valid expense amount
5019Contact cannot be changed for an invoiced expense
5032You cannot make this expense non-billable as it has been already invoiced

Example

{ "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", "vat_reg_no": "string", "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": " " }

Attribute

expense_id
string
Unique ID of the expense
transaction_id
string
Unique ID of the transaction
transaction_type
string
Type of the transaction
expense_item_id
string
ID of the expense item/component.
gst_no
India Edition only
string
15 digit GST identification number of the vendor.
gst_treatment
India Edition only.
string
Choose whether the contact is GST registered/unregistered/consumer/overseas. Allowed values are business_gst , business_none , overseas , consumer .
destination_of_supply
India Edition only
string
Place where the goods/services are supplied to. (If not given, organisation's home state will be taken)
destination_of_supply_state
India Edition only.
string
State to where goods/services are supplied
hsn_or_sac
India Edition only
string
Add HSN/SAC code for your goods/services
source_of_supply
India Edition only
string
Place from where the goods/services are supplied. (If not given, place of contact given for the contact will be taken)
paid_through_account_name
string
Enter the name of the paid through account.
vat_reg_no
string
Enter VAT registration number.
reverse_charge_tax_id
string
ID of the reverse charge tax
reverse_charge_tax_name
India Edition only.
string
Enter name of the reverse charge tax
reverse_charge_tax_percentage
India Edition only.
double
Enter percentage of the reverse charge tax
reverse_charge_tax_amount
India Edition only.
integer
Enter amount of the reverse charge tax
tax_amount
double
total expense amount
is_itemized_expense
boolean
is_pre_gst
India Edition only.
string
Applicable for transactions that fall before july 1, 2017
trip_id
string
Enter trip ID
trip_number
string
Enter trip number
reverse_charge_vat_total
India Edition only.
double
Enter total of the reverse charge vat tax.
acquisition_vat_total
double
Enter acquisition vat total.
acquisition_vat_summary
array
tax_name
string
Name of the tax levied
tax_amount
double
total expense amount
reverse_charge_vat_summary
array
tax_name
string
Name of the tax levied
tax_amount
double
total expense amount
account_id
string
ID of the expense account.
account_name
string
Name of the expense account in which that expense is recorded
date
string
Date of the expense
tax_id
string
Tax ID applied
tax_name
string
Name of the tax levied
tax_percentage
double
Percentage of tax charged
currency_id
string
Unique ID of the currency
currency_code
string
Code of the currency
exchange_rate
double
Foreign currency exchange rate
sub_total
double
Sub-total of the expense amount
total
double
Total value of expense
bcy_total
double
Total value of expense in Base currency
amount
double
Total expense value
is_inclusive_tax
boolean
Check if amount is inclusive of tax
reference_number
string
Reference number of the expense. Maximum length [100]
description
string
Description of the expense. Maximum length [100]
is_billable
boolean
Check if an expense is billable
is_personal
boolean
Check if the expense os personal
customer_id
string
ID of the expense account.
customer_name
string
Name of the Customer for whom expense is raised. Maximum length [100]
expense_receipt_name
string
Name of the expense receipt
expense_receipt_type
string
Type of the expense receipt
last_modified_time
string
Date of last modification to the expense
status
string
Expense status
invoice_id
string
ID of the invoice associated
invoice_number
string
Serial Number of the invoice attached
project_id
string
ID of the project associated with the customer.
project_name
string
Name of the project in question
mileage_rate
double
Mileage rate for a particular mileage expense.
mileage_type
string
Milage expense type
expense_type
string
Type of the expense
start_reading
double
Start reading of odometer when creating a mileage expense where mileage_type is odometer.
end_reading
double
End reading of odometer when creating a mileage expense where mileage_type is odometer.

Create an Expense

Create billable or non-billable expense.
oauthscope : ZohoInvoice.expenses.CREATE

POST /expenses

Request Example

$ curl https://invoice.zoho.com/api/v3/expenses -X POST -H "X-com-zoho-invoice-organizationid: 10234695" -H "Content-Type: application/json;charset=UTF-8" -H "Authorization: Zoho-oauthtoken 1000.41d9f2cfbd1b7a8f9e314b7aff7bc2d1.8fcc9810810a216793f385b9dd6e125f" -d '{ "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_code": "string", "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": "overseas", "product_type": "goods", "acquisition_vat_id": " ", "reverse_charge_vat_id": " ", "start_reading": " ", "end_reading": " ", "distance": " ", "mileage_unit": " ", "mileage_rate": " ", "employee_id": " ", "vehicle_type": " ", "can_reclaim_vat_on_mileage": " ", "fuel_type": " ", "engine_capacity_range": " " }'