Introduction
Introduction
API Root Endpoint
https://inventory.zoho.com/api/v1
The Zoho Inventory API allows you to perform all the operations that you do with our web client.
Zoho Inventory 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.
Getting Started
Example
$ curl https://inventory.zoho.com/api/v1/organizations?organization_id=10234695 -H 'Authorization: Zoho-oauthtoken 1000.41d9f2cfbd1b7a8f9e314b7aff7bc2d1.8fcc9810810a216793f385b9dd6e125f'
To use our API you must satisfy these prerequistes
- A valid Zoho username and password.
- An Authentication Token - authtoken in short!
Multiple Data Centers
Zoho Inventory is hosted at multiple data centers, and therefore available on different domains.
There are 4 different domains for Zoho Inventory's APIs, and you will have to use the one that is applicable to you.
| Data Center | Domain | Base API URI |
|---|---|---|
| United States | .com | https://inventory.zoho.com/ |
| Europe | .eu | https://inventory.zoho.eu/ |
| India | .in | https://inventory.zoho.in/ |
| Australia | .com.au | https://inventory.zoho.com.au/ |
The APIs on this page are for organizations in Zoho Inventory that are hosted on the .com domain. If your organization is on a different domain, then you must replace .com with the appropriate domain for API endpoints on this page before using them.
Note: To find out which domain you're accessing Zoho Inventory from, visit the Zoho Inventory web app and check its URL. If the URL contains inventory.zoho.com, then you're accessing it from the .com domain. If the URL contains inventory.zoho.in, you're accessing it from the .in domain. Similarly, you could be accessing Zoho Inventory from the .eu or .com.au domain.
For example, here's how you would modify the domain in an API endpoint for the .eu domain:
API endpoint for the .com domain, as available on this page:
https://inventory.zoho.com/api/v1/items
API endpoint after replacing the .com domain with .eu:
https://inventory.zoho.eu/api/v1/items
OAuth
Zoho REST APIs uses the OAuth 2.0 protocol to authorize and authenticate calls (The above approach of authentication via Authtoken will be deprecated soon). 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
Note:The API URLs in this section should be modified, based on your domain.
| Data Center | Domain | Base API URI |
|---|---|---|
| United States | .com | https://accounts.zoho.com/ |
| Europe | .eu | https://accounts.zoho.eu/ |
| India | .in | https://accounts.zoho.in/ |
| Australia | .com.au | https://accounts.zoho.com.au/ |
You can read more about this here.
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
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=ZohoInventory.invoices.CREATE,ZohoInventory.invoices.READ,ZohoInventory.invoices.UPDATE,ZohoInventory.invoices.DELETE&client_id=1000.0SRSZSY37WMZ69405H3TMYI2239V&state=testing&response_type=code&redirect_uri=http://www.zoho.com/books&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 : ZohoInventory.FullAccess.all |
| 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 |
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
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/books&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* | Client secret obtained during Client Registration |
| redirect_uri* | This param should be same redirect url mentioned while adding Client |
| grant_type* | authorization_code |
| scope | SCOPE for which token to be generated. Ex : ZohoInventory.FullAccess.all. Multiple scopes has to be separated by commas. |
| state | An opaque string that is round-tripped in the protocol; that is to say, value will be passed back to you. |
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: 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.
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/books&grant_type=authorization_code
| Parameter | Description |
|---|---|
| refresh_token | REFRESH TOKEN which is obtained in the above step |
| client_id | Client ID obtained during Client Registration |
| client_secret | Client secret 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?refresh_token=1000.8ecd474019e31d522f94aad6c5cb7.4638677ebc14f2f2ee0b6dfb6cebdc
| Parameter | Description |
|---|---|
| refresh_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.
- Header name should be
Authorization - Header value should be
Zoho-oauthtoken {access_token}
List of scopes available in Zoho Inventory :
| Scope | Description |
|---|---|
| contacts | To access contacts related APIs Availabe types: ZohoInventory.contacts.CREATE, ZohoInventory.contacts.UPDATE, ZohoInventory.contacts.READ, ZohoInventory.contacts.DELETE |
| items | To access item related APIs Availabe types: ZohoInventory.items.CREATE, ZohoInventory.items.UPDATE, ZohoInventory.items.READ, ZohoInventory.items.DELETE |
| composite items | To access item related APIs Availabe types: ZohoInventory.compositeitems.CREATE, ZohoInventory.compositeitems.UPDATE, ZohoInventory.compositeitems.READ, ZohoInventory.compositeitems.DELETE |
| settings | To access users, taxes, currencies related APIs Availabe types: ZohoInventory.settings.CREATE, ZohoInventory.settings.UPDATE, ZohoInventory.settings.READ, ZohoInventory.settings.DELETE |
| invoices | To access invoices related APIs Availabe types: ZohoInventory.invoices.CREATE, ZohoInventory.invoices.UPDATE, ZohoInventory.invoices.READ, ZohoInventory.invoices.DELETE |
| customerpayments | To access customer payments related APIs Availabe types: ZohoInventory.customerpayments.CREATE, ZohoInventory.customerpayments.UPDATE, ZohoInventory.customerpayments.READ, ZohoInventory.customerpayments.DELETE |
| creditnotes | To access credit notes related APIs Availabe types: ZohoInventory.creditnotes.CREATE, ZohoInventory.creditnotes.UPDATE, ZohoInventory.creditnotes.READ, ZohoInventory.creditnotes.DELETE |
| salesorder | To access salesorder related APIs Availabe types: ZohoInventory.salesorders.CREATE, ZohoInventory.salesorders.UPDATE, ZohoInventory.salesorders.READ, ZohoInventory.salesorders.DELETE |
| packages | To access Package related APIs Availabe types: ZohoInventory.packages.CREATE, ZohoInventory.packages.UPDATE, ZohoInventory.packages.READ, ZohoInventory.packages.DELETE |
| shipmentorders | To access Shipment order related APIs Availabe types: ZohoInventory.shipmentorders.CREATE, ZohoInventory.shipmentorders.UPDATE, ZohoInventory.shipmentorders.READ, ZohoInventory.shipmentorders.DELETE |
| purchaseorder | To access purchaseorder related APIs Availabe types: ZohoInventory.purchaseorders.CREATE, ZohoInventory.purchaseorders.UPDATE, ZohoInventory.purchaseorders.READ, ZohoInventory.purchaseorders.DELETE |
| purchase receives | To access purchase receive related APIs Availabe types: ZohoInventory.purchasereceives.CREATE, ZohoInventory.purchasereceives.READ, ZohoInventory.purchasereceives.DELETE |
| bills | To access bills related APIs Availabe types: ZohoInventory.bills.CREATE, ZohoInventory.bills.UPDATE, ZohoInventory.bills.READ, ZohoInventory.bills.DELETE |
| inventory adjustments | To access inventory adjustments related APIs Availabe types: ZohoInventory.inventoryadjustments.CREATE, ZohoInventory.inventoryadjustments.READ, ZohoInventory.inventoryadjustments.DELETE |
| transfer orders | To access transfer order related APIs Availabe types: ZohoInventory.transferorders.CREATE, ZohoInventory.purchasereceives.READ, ZohoInventory.transferorders.DELETE |
| warehouses | To access warehouse related APIs Availabe types: ZohoInventory.warehouses.CREATE, ZohoInventory.warehouses.UPDATE, ZohoInventory.warehouses.READ, ZohoInventory.warehouses.DELETE |
Organization ID
Request Example
$ curl https://inventory.zoho.com/api/v1/organizations?authtoken=ba4604e8e433g9c892e360d53463oec5
Response Example
HTTP/1.1 200 OK Content-Type:application/json;charset=UTF-8 { "code": 0, "message": "success", "organizations": [ { "organization_id": "10234695", "name": "Zillum", "contact_name": "John Smith", "email": "johnsmith@zillum.com", "is_default_org": false, "language_code": "en", "fiscal_year_start_month": 0, "account_created_date": "2016-02-18", "time_zone": "PST", "is_org_active": true, "currency_id": "460000000000097", "currency_code": "USD", "currency_symbol": "$", "currency_format": "###,##0.00", "price_precision": 2 }, {...}, {...} ]
In Zoho Inventory, 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 Inventory 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 Inventory admin console. Click the drop down with organization’s name as the label and click Manage Organizations.
Now you’ll be able to find Organization IDs for each of your organizations.
HTTP Methods
Using GET method, you can get the list of resources or details of a particular instance of a resource.
To get a list of contacts
$ curl https://inventory.zoho.com/api/v1/contacts?authtoken=ba4604e8e433g9c892e360d53463oec5&organization_id=10234695
To get the details of a contact referred to by a specified contact_id
$ curl https://inventory.zoho.com/api/v1/contacts/903000000000099?authtoken=ba4604e8e433g9c892e360d53463oec5&organization_id=10234695
Zoho Inventory 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://inventory.zoho.com/api/v1/invoices/7000000079426?authtoken=ba4604e8e433g9c892e360d53463oec5&organization_id=10234695 -H 'Accept: application/pdf'
OR
$ curl https://inventory.zoho.com/api/v1/invoices/7000000079426?accept=pdf \ '&authtoken=ba4604e8e433g9c892e360d53463oec5' \ '&organization_id=10234695'
Responses will be in the JSON format.
| Node Name | Description |
|---|---|
| code | Zoho Inventory 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://inventory.zoho.com/api/v1/invoices/700000007942?authtoken=ba4604e8e433g9c892e360d53463oec5&organization_id=10234695
Response Example
HTTP/1.1 404 Not Found Content-Type: application/json;charset=UTF-8 { "code": 1002, "message": "Invoice does not exist." }
Zoho Inventory 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 | 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. |
| 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. |
| 429 | Too many requests Too many requests within a certain time frame. To know more about api call limits, click here. |
| 500 | Server errorZoho Inventory server encountered an error which prevents it from fulfilling the request. Although this rarely happens, we recommend you to contact us at support@zoho-inventory.com if you receive this error. |
Pagination
Example
$ curl https://inventory.zoho.com/api/v1/contacts?page=2&per_page=25 { "code": 0, "message": "success", "contacts": [ {...}, {...} ], "page_context": { "page": 2, "per_page": 25, "has_more_page": false } }
Zoho Inventory provides APIs to retrieve lists of contacts, plans and other resources - paginated to 200 items by default. The pagination information will be included in the list API response under the node name page_context.
- By default first page will be listed. For navigating through pages, use the
pageparameter. - The
per_pageparameter can be used to set the number of records that you want to receive in response.
API Call Limit
API calls are limited to provide better quality of service and availability to all the users. You can send a maximum of 1000 API requests per day per organization during the free plan. However, if the organization is on a paid plan you can send up to 5000 API requests per day per organization.
Organizations
An Organisation represents a company or an institution running a business.
Example
{}
Attribute
|
|
Create an organization
Create an organization. oauthscope : ZohoInventory.settings.CREATE
POST /organizations
Request Example
$ curl https://inventory.zoho.com/api/v1/organizations?organization_id=10234695 -X POST -H "Authorization: Zoho-oauthtoken 1000.41d9f2cfbd1b7a8f9e314b7aff7bc2d1.8fcc9810810a216793f385b9dd6e125f" -H "Content-Type: application/x-www-form-urlencoded;charset=UTF-8" -F 'JSONString="{ "name": "Zillium Inc", "fiscal_year_start_month": "january", "currency_code": "USD", "time_zone": "PST", "date_format": "dd MMM yyyy", "field_separator": " ", "language_code": "en", "industry_type": "Services", "industry_size": " ", "portal_name": "zilluminc", "org_address": " ", "remit_to_address": " ", "address": [ { "street_address1": " ", "street_address2": " ", "city": " ", "state": " ", "country": "U.S.A", "zip": "U.S.A" } ] }"'
Response Example
HTTP/1.1 201 Created Content-Type:application/json;charset=UTF-8 { "code": 0, "message": "success", "organization": { "organization_id": "10229182", "name": "Zillium Inc", "is_logo_uploaded": " ", "is_default_org": false, "user_role": " ", "account_created_date": "2012-02-15", "time_zone": "PST", "language_code": "en", "date_format": "dd MMM yyyy", "field_separator": " ", "fiscal_year_start_month": 0, "tax_group_enabled": true, "user_status": " ", "contact_name": "John Smith", "industry_type": "Services", "address": [ { "street_address1": " ", "street_address2": " ", "city": " ", "state": " ", "country": "U.S.A", "zip": "U.S.A" } ] } }
ARGUMENTS
|
name
Required
Name of the project.
fiscal_year_start_month
Optional
Fiscal or financial starting year of your business. Allowed Values:
january, february, march, april, may, june, july, august, september, october, november and december
currency_code
Required
Standard code for currency.
time_zone
Required
Time zone in with the organization is located geographically.
date_format
Optional
Format for representing the date.
field_separator
Optional
Field separator for components in date.
language_code
Optional
language code for organization.For instance
en represents english.
industry_type
Optional
Business type
industry_size
Optional
The size of the industry. The possibe values could be "small scale", "medium scale", "large scale"
fiscal_year_start_month
Optional
Fiscal or financial starting year of your business. Allowed Values:
january, february, march, april, may, june, july, august, september, october, november and december
portal_name
Required
Poratal name for the organisation. Length of the portal name should be greater than 4 and less than 31. Allowed chars [a-z][A-Z][0-9]
org_address
Optional
Billing address of the organisation
remit_to_address
Optional
Shipping address of the organisation
address
Optional
Billing address of the organisation
street_address1
Optional
Street name of the Billing address of the Organisation
street_address2
Optional
Continyed billing address of the organisation
city
Optional
City of the organisation
state
Optional
State where the organisation is located
country
Optional
Country of the Organisation
zip
Optional
ZIP/Postal code of the organisation's location
|
Update an organization
Update the details of an organization. oauthscope : ZohoInventory.settings.UPDATE
PUT /organizations/:organization_id
Request Example
$ curl https://inventory.zoho.com/api/v1/organizations/:organization_id?organization_id=10234695 -X PUT -H "Authorization: Zoho-oauthtoken 1000.41d9f2cfbd1b7a8f9e314b7aff7bc2d1.8fcc9810810a216793f385b9dd6e125f" -H "Content-Type: application/x-www-form-urlencoded;charset=UTF-8" -F 'JSONString="{ "name": "Zillium Inc", "fiscal_year_start_month": "january", "is_logo_uploaded": true, "time_zone": "PST", "date_format": "dd MMM yyyy", "field_separator": " ", "language_code": "en", "org_address": " ", "remit_to_address": " ", "address": [ { "street_address1": " ", "street_address2": " ", "city": " ", "state": " ", "country": "U.S.A", "zip": "U.S.A" } ], "contact_name": "John Smith", "phone": " ", "fax": " ", "website": " ", "email": "johndavid@zilliuminc.com", "currency_id": "982000000000190", "companyid_label": " ", "companyid_value": " ", "taxid_label": " ", "taxid_value": " ", "custom_fields": [ { "index": 1, "value": " ", "label": " " } ] }"'
Response Example
HTTP/1.1 200 OK Content-Type:application/json;charset=UTF-8 { "code": 0, "message": "success", "organization": { "organization_id": "10229182", "name": "Zillium Inc", "is_default_org": false, "account_created_date": "2012-02-15", "time_zone": "PST", "language_code": "en", "date_format": "dd MMM yyyy", "field_separator": " ", "fiscal_year_start_month": 0, "contact_name": "John Smith", "industry_type": "Services", "industry_size": " ", "company_id_label": "Company ID", "company_id_value": " ", "tax_id_label": "Tax ID", "tax_id_value": " ", "currency_id": "982000000000190", "currency_code": "USD", "currency_symbol": "$", "currency_format": "###,##0.00", "price_precision": 2, "org_address": " ", "remit_to_address": " ", "phone": " ", "fax": " ", "website": " ", "email": "johndavid@zilliuminc.com", "is_org_active": true, "address": [ { "street_address1": " ", "street_address2": " ", "city": " ", "state": " ", "country": "U.S.A", "zip": "U.S.A" } ], "custom_fields": [ { "index": 1, "value": " ", "label": " " } ] } }
ARGUMENTS
|
name
Optional
Name of the project.
fiscal_year_start_month
Optional
Fiscal or financial starting year of your business. Allowed Values:
january, february, march, april, may, june, july, august, september, october, november and december
is_logo_uploaded
Optional
To determine whether logo is uploaded.
time_zone
Optional
Time zone in with the organization is located geographically.
date_format
Optional
Format for representing the date.
field_separator
Optional
Field separator for components in date.
language_code
Optional
language code for organization.For instance
en represents english.
org_address
Optional
Billing address of the organisation
remit_to_address
Optional
Shipping address of the organisation
address
Optional
Billing address of the organisation
street_address1
Optional
Street name of the Billing address of the Organisation
street_address2
Optional
Continyed billing address of the organisation
city
Optional
City of the organisation
state
Optional
State where the organisation is located
country
Optional
Country of the Organisation
zip
Optional
ZIP/Postal code of the organisation's location
contact_name
Optional
Name of the contact person of the organisation
phone
Optional
Contact number of the organisation
fax
Optional
FAX number of the organisation
website
Optional
Organisation's website
email
Optional
email ID of the contact person of the organisation
currency_id
Optional
ID of the organisation curreency
companyid_label
Optional
Label " Company ID "
companyid_value
Optional
value in field "company ID"
taxid_label
Optional
Label "tax ID"
taxid_value
Optional
Value in "tax ID"
custom_fields
Optional
Additional fields to describe an organisation
index
Optional
Index used to list
value
Optional
Value of the list
label
Optional
Label of each column
|
List organizations
Get the list of organizations. oauthscope : ZohoInventory.settings.READ
GET /organizations
Request Example
$ curl https://inventory.zoho.com/api/v1/organizations?organization_id=10234695 -H "Authorization: Zoho-oauthtoken 1000.41d9f2cfbd1b7a8f9e314b7aff7bc2d1.8fcc9810810a216793f385b9dd6e125f" -H "Content-Type: application/x-www-form-urlencoded;charset=UTF-8"
Response Example
HTTP/1.1 200 OK Content-Type:application/json;charset=UTF-8 { "code": 0, "message": "success", "organizations": [ { "organization_id": "10229182", "name": "Zillium Inc", "contact_name": "John Smith", "email": "johndavid@zilliuminc.com", "is_default_org": false, "plan_type": 130, "tax_group_enabled": true, "zi_migration_status": 0, "plan_name": "PROFESSIONAL", "plan_period": "Monthly", "language_code": "en", "fiscal_year_start_month": 0, "account_created_date": "2012-02-15", "account_created_date_formatted": "15 Feb 2012", "time_zone": "PST", "is_org_active": true, "currency_id": "982000000000190", "currency_code": "USD", "currency_symbol": "$", "currency_format": "###,##0.00", "price_precision": 2 }, {...}, {...} ] }
Get an organization
Get the details of an organization. oauthscope : ZohoInventory.settings.READ
GET /organizations/:organization_id
Request Example
$ curl https://inventory.zoho.com/api/v1/organizations/:organization_id?organization_id=10234695 -H "Authorization: Zoho-oauthtoken 1000.41d9f2cfbd1b7a8f9e314b7aff7bc2d1.8fcc9810810a216793f385b9dd6e125f" -H "Content-Type: application/x-www-form-urlencoded;charset=UTF-8"
Response Example
HTTP/1.1 200 OK Content-Type:application/json;charset=UTF-8 { "code": 0, "message": "success", "organization": { "organization_id": "10229182", "name": "Zillium Inc", "is_default_org": false, "account_created_date": "2012-02-15", "time_zone": "PST", "language_code": "en", "date_format": "dd MMM yyyy", "field_separator": " ", "fiscal_year_start_month": 0, "contact_name": "John Smith", "industry_type": "Services", "industry_size": " ", "company_id_label": "Company ID", "company_id_value": " ", "tax_id_label": "Tax ID", "tax_id_value": " ", "currency_id": "982000000000190", "currency_code": "USD", "currency_symbol": "$", "currency_format": "###,##0.00", "price_precision": 2, "org_address": " ", "remit_to_address": " ", "phone": " ", "fax": " ", "website": " ", "email": "johndavid@zilliuminc.com", "is_org_active": true, "address": [ { "street_address1": " ", "street_address2": " ", "city": " ", "state": " ", "country": "U.S.A", "zip": "U.S.A" } ], "custom_fields": [ { "index": 1, "value": " ", "label": " " } ] } }
Contacts
A contact is either a customer or vendor. A contact can be an individual or a business in general.
Example
{ "contact_name": "Bowman and Co", "company_name": "Bowman and Co", "first_name": "Will", "last_name": "Smith", "email": "willsmith@bowmanfurniture.com", "phone": "+1-925-921-9201", "facebook": "zoho", "twitter": "zoho", "language_code": "en", "billing_address": { "attention": "Mr.John", "address": "4900 Hopyard Rd", "street2": "Suit 310", "city": "Pleasanton", "state": "CA", "zip": 94588, "country": "U.S.A" }, "shipping_address": { "attention": "Mr.John", "address": "4900 Hopyard Rd", "street2": "Suit 310", "city": "Pleasanton", "state": "CA", "zip": 94588, "country": "U.S.A" }, "contact_persons": [ { "salutation": "Mr", "first_name": "Will", "last_name": "Smith", "email": "willsmith@bowmanfurniture.com", "phone": "+1-925-921-9201", "mobile": "+1-4054439562", "is_primary_contact": true } ], "place_of_contact": "TN", "gst_no": "22AAAAA0000A1Z5", "gst_treatment": "business_gst" }
Attribute
|
contact_name
string
Name of the contact. This can be the name of an organisation or the name of an individual. Maximum length [200]
company_name
string
Name of the conact's company. Maximum length [200]
first_name
string
First name of the contact. Maximum length [100]
last_name
string
Last name of the contact. Maximum length [100]
email
string
Search contacts by email id of the contact person. Variants:
address_startswith and address_contains
phone
string
Search contacts by phone number of the contact person. Variants:
phone_startswith and phone_contains
facebook
string
Facebook profile account of the contact. Maximum length [100]
twitter
string
Twitter account of the contact. MAximum length [100]
language_code
string
language of a contact. allowed values
de,en,es,fr,it,ja,nl,pt,sv,zh
billing_address
object
Billing address of the contact.
attention
string
Intended recipient at given address
address
string
Street address of the contact. Maximum length allowed [500]
street2
string
Additional Street address of the contact. Maximum length allowed [255]
city
string
City of the customer’s billing address.
state
string
State of the customer’s billing address.
zip
string
Zip code of the customer’s billing address.
country
string
Country of the customer’s billing address.
shipping_address
object
Customer's shipping address to which the goods must be delivered.
attention
string
Intended recipient at given address
address
string
Street address of the contact. Maximum length allowed [500]
street2
string
Additional Street address of the contact. Maximum length allowed [255]
city
string
City of the customer’s billing address.
state
string
State of the customer’s billing address.
zip
string
Zip code of the customer’s billing address.
country
string
Country of the customer’s billing address.
contact_persons
list
Person/Individual who represents a company
salutation
string
Salutation for the contact
first_name
string
First name of the contact. Maximum length [100]
last_name
string
Last name of the contact. Maximum length [100]
email
string
Search contacts by email id of the contact person. Variants:
address_startswith and address_contains
phone
string
Search contacts by phone number of the contact person. Variants:
phone_startswith and phone_contains
mobile
string
Search contacts by mobile number of the contact person.
is_primary_contact
boolean
To mark contact person as primary for contact. Allowed value is true only.
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.
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 .
tax_authority_name
string
Name of the Tax Authority
tax_exemption_code
US, Canada, Australia and India editions only
string
Enter tax exemption code
|
Create a Contact
Create a contact with given information. oauthscope : ZohoBooks.contacts.CREATE
POST /contacts
Request Example
$ curl https://inventory.zoho.com/api/v1/contacts?organization_id=10234695 -X POST -H "Authorization: Zoho-oauthtoken 1000.41d9f2cfbd1b7a8f9e314b7aff7bc2d1.8fcc9810810a216793f385b9dd6e125f" -H "Content-Type: application/x-www-form-urlencoded;charset=UTF-8" -F 'JSONString="{ "contact_name": "Bowman and Co", "company_name": "Bowman and Co", "payment_terms": 15, "currency_id": 460000000000097, "website": "www.bowmanfurniture.com", "contact_type": "customer", "custom_fields": [ { "value": "GBGD078", "index": 1 } ], "billing_address": { "attention": "Mr.John", "address": "4900 Hopyard Rd", "street2": "Suit 310", "city": "Pleasanton", "state": "CA", "zip": 94588, "country": "U.S.A" }, "shipping_address": { "attention": "Mr.John", "address": "4900 Hopyard Rd", "street2": "Suit 310", "city": "Pleasanton", "state": "CA", "zip": 94588, "country": "U.S.A" }, "contact_persons": [ { "salutation": "Mr", "first_name": "Will", "last_name": "Smith", "email": "willsmith@bowmanfurniture.com", "phone": "+1-925-921-9201", "mobile": "+1-4054439562", "is_primary_contact": true } ], "default_templates": { "invoice_template_id": 460000000052069, "invoice_template_name": "Custom Classic", "estimate_template_id": 460000000000179, "estimate_template_name": "Service - Professional", "creditnote_template_id": 460000000000211, "creditnote_template_name": "Fixed Cost - Professional", "invoice_email_template_id": 460000000052071, "invoice_email_template_name": "Custom Invoice Notification", "estimate_email_template_id": 460000000052073, "estimate_email_template_name": "Custom Estimate Notification", "creditnote_email_template_id": 460000000052075, "creditnote_email_template_name": "Custom Credit Note Notification" }, "language_code": "en", "notes": "Payment option : Through check", "tax_exemption_id": 11149000000061054, "tax_authority_id": 11149000000061052, "tax_id": 11149000000061058, "is_taxable": true, "facebook": "zoho", "twitter": "zoho", "place_of_contact": "TN", "gst_no": "22AAAAA0000A1Z5", "gst_treatment": "business_gst" }"'
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_linked_with_zohocrm": false, "website": "www.bowmanfurniture.com", "primary_contact_id": 460000000026051, "payment_terms": 15, "payment_terms_label": "Net 15", "currency_id": 460000000000097, "currency_code": "USD", "currency_symbol": "$", "language_code": "en", "outstanding_receivable_amount": 250, "outstanding_receivable_amount_bcy": 250, "unused_credits_receivable_amount": 1369.66, "unused_credits_receivable_amount_bcy": 1369.66, "status": "active", "payment_reminder_enabled": true, "custom_fields": [ { "value": "GBGD078", "index": 1, "label": "VAT ID" } ], "billing_address": { "attention": "Mr.John", "address": "4900 Hopyard Rd", "street2": "Suit 310", "city": "Pleasanton", "state": "CA", "zip": 94588, "country": "U.S.A" }, "shipping_address": { "attention": "Mr.John", "address": "4900 Hopyard Rd", "street2": "Suit 310", "city": "Pleasanton", "state": "CA", "zip": 94588, "country": "U.S.A" }, "facebook": "zoho", "twitter": "zoho", "contact_persons": [ { "salutation": "Mr", "first_name": "Will", "last_name": "Smith", "email": "willsmith@bowmanfurniture.com", "phone": "+1-925-921-9201", "mobile": "+1-4054439562", "is_primary_contact": true } ], "default_templates": { "invoice_template_id": 460000000052069, "invoice_template_name": "Custom Classic", "estimate_template_id": 460000000000179, "estimate_template_name": "Service - Professional", "creditnote_template_id": 460000000000211, "creditnote_template_name": "Fixed Cost - Professional", "invoice_email_template_id": 460000000052071, "invoice_email_template_name": "Custom Invoice Notification", "estimate_email_template_id": 460000000052073, "estimate_email_template_name": "Custom Estimate Notification", "creditnote_email_template_id": 460000000052075, "creditnote_email_template_name": "Custom Credit Note Notification" }, "notes": "Payment option : Through check", "created_time": "2013-08-05", "last_modified_time": "2013-10-07", "is_taxable": true, "tax_id": 11149000000061058, "tax_name": "CGST", "tax_percentage": 12, "tax_authority_id": 11149000000061052, "tax_exemption_id": 11149000000061054, "place_of_contact": "TN", "gst_no": "22AAAAA0000A1Z5", "gst_treatment": "business_gst" } }
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.
contact_type
Optional
Type of the contact. Allowed values are
customer and vendor
custom_fields
Optional
Custom fields or Additional of the contact which we can create to add more information.
value
Optional
Value of the custom field.
index
Optional
Index of the custom field. It can hold any value from 1 to 10.
billing_address
Optional
Billing address of the contact.
attention
Optional
Intended recipient at given address
address
Optional
Street address of the contact. Maximum length allowed [500]
street2
Optional
Additional Street address of the contact. Maximum length allowed [255]
city
Optional
City of the customer’s billing address.
state
Optional
State of the customer’s billing address.
zip
Optional
Zip code of the customer’s billing address.
country
Optional
Country of the customer’s billing address.
shipping_address
Optional
Customer's shipping address to which the goods must be delivered.
attention
Optional
Intended recipient at given address
address
Optional
Street address of the contact. Maximum length allowed [500]
street2
Optional
Additional Street address of the contact. Maximum length allowed [255]
city
Optional
City of the customer’s billing address.
state
Optional
State of the customer’s billing address.
zip
Optional
Zip code of the customer’s billing address.
country
Optional
Country of the customer’s billing address.
contact_persons
Optional
Person/Individual who represents a company
salutation
Optional
Salutation for the contact
first_name
Optional
First name of the contact. Maximum length [100]
last_name
Optional
Last name of the contact. Maximum length [100]
email
Optional
Search contacts by email id of the contact person. Variants:
address_startswith and address_contains
phone
Optional
Search contacts by phone number of the contact person. Variants:
phone_startswith and phone_contains
mobile
Optional
Search contacts by mobile number of the contact person.
is_primary_contact
Optional
To mark contact person as primary for contact. Allowed value is true only.
default_templates
Optional
invoice_template_id
Optional
ID of the Invoice template used
invoice_template_name
Optional
Name of the invoice template used
estimate_template_id
Optional
ID of the estimate template used
estimate_template_name
Optional
Name of the estimate template used
creditnote_template_id
Optional
ID of teh credit note template used
creditnote_template_name
Optional
Name of the credit note template used
invoice_email_template_id
Optional
ID of the invoice email tempalte used
invoice_email_template_name
Optional
Name of the Invoice email template used
estimate_email_template_id
Optional
ID of the estimate email template used
estimate_email_template_name
Optional
Name of the estimate email template used
creditnote_email_template_id
Optional
ID of the credit note email template
creditnote_email_template_name
Optional
Name of the credit note email template
language_code
Optional
language of a contact. allowed values
de,en,es,fr,it,ja,nl,pt,sv,zh
notes
Optional
Commennts about the payment made by the contact.
vat_reg_no
UK Edition $ Avalara integration only
Optional
For UK Edition: VAT Registration number of a contact with VAT treatment as
eu_vat_registered. Length should be between 2 and 12 characters.(This node is only available for EU VAT registered contacts.)For Avalara: If you are doing sales in the European Union (EU) then provide VAT Registration Number of your customers here. This is used to calculate VAT for B2B sales, from Avalara.
country_code
UK Edition $ Avalara integration only
Optional
For UK Edition: Two letter country code of a contact with VAT treatment as
eu_vat_registered.(This node is only available for EU VAT registered contacts.)For Avalara: Two letter country code for the customer country, if your customer is not in US. Refer [AvaTax Codes for Countries and States][2].
vat_treatment
UK edition only
Optional
VAT treatment of the contact.Allowed Values:
uk, eu_vat_not_registered, eu_vat_registered and non_eu.
avatax_exempt_no
Avalara integration only
Optional
Exemption certificate number of the customer.
avatax_use_code
Avalara integration only
Optional
Used to group like customers for exemption purposes. It is a custom value that links customers to a tax rule. Select from Avalara [standard codes][1] or enter a custom code.
tax_exemption_id
US, Canada, Australia and India editions only
Optional
ID of the tax exemption.
tax_authority_id
US edition only
Optional
ID of the tax authority. Tax authority depends on the location of the customer. For example, if the customer is located in NY, then the tax authority is NY tax authority.
tax_id
US and Indian editions only
Optional
ID of the tax or tax group that can be collected from the contact. Tax can be given only if
is_taxable is true.
is_taxable
US, Canada, Australia, and India Editions only.
Optional
Boolean to track the taxability of the customer.
facebook
Optional
Facebook profile account of the contact. Maximum length [100]
twitter
Optional
Twitter account of the contact. MAximum length [100]
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
Name of the Tax Authority
tax_exemption_code
US, Canada, Australia and India editions only
Optional
Enter tax exemption code
|
Update a contact
Update an existing contact. To delete a contact person remove it from the contact_persons list. oauthscope : ZohoBooks.contacts.UPDATE
PUT /contacts/{contact_id}
Request Example
$ curl https://inventory.zoho.com/api/v1/contacts/{contact_id}?organization_id=10234695 -X PUT -H "Authorization: Zoho-oauthtoken 1000.41d9f2cfbd1b7a8f9e314b7aff7bc2d1.8fcc9810810a216793f385b9dd6e125f" -H "Content-Type: application/x-www-form-urlencoded;charset=UTF-8" -F 'JSONString="{ "contact_name": "Bowman and Co", "company_name": "Bowman and Co", "payment_terms": 15, "currency_id": 460000000000097, "contact_type": "customer", "website": "www.bowmanfurniture.com", "custom_fields": [ { "value": "GBGD078", "index": 1, "label": "VAT ID" } ], "billing_address": { "attention": "Mr.John", "address": "4900 Hopyard Rd", "street2": "Suit 310", "city": "Pleasanton", "state": "CA", "zip": 94588, "country": "U.S.A" }, "shipping_address": { "attention": "Mr.John", "address": "4900 Hopyard Rd", "street2": "Suit 310", "city": "Pleasanton", "state": "CA", "zip": 94588, "country": "U.S.A" }, "contact_persons": [ { "salutation": "Mr", "first_name": "Will", "last_name": "Smith", "email": "willsmith@bowmanfurniture.com", "phone": "+1-925-921-9201", "mobile": "+1-4054439562", "is_primary_contact": true } ], "default_templates": { "invoice_template_id": 460000000052069, "invoice_template_name": "Custom Classic", "estimate_template_id": 460000000000179, "estimate_template_name": "Service - Professional", "creditnote_template_id": 460000000000211, "creditnote_template_name": "Fixed Cost - Professional", "invoice_email_template_id": 460000000052071, "invoice_email_template_name": "Custom Invoice Notification", "estimate_email_template_id": 460000000052073, "estimate_email_template_name": "Custom Estimate Notification", "creditnote_email_template_id": 460000000052075, "creditnote_email_template_name": "Custom Credit Note Notification" }, "language_code": "en", "notes": "Payment option : Through check", "tax_exemption_id": 11149000000061054, "tax_authority_id": 11149000000061052, "tax_id": 11149000000061058, "is_taxable": true, "facebook": "zoho", "twitter": "zoho", "place_of_contact": "TN", "gst_no": "22AAAAA0000A1Z5", "gst_treatment": "business_gst" }"'
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_linked_with_zohocrm": false, "website": "www.bowmanfurniture.com", "primary_contact_id": 460000000026051, "payment_terms": 15, "payment_terms_label": "Net 15", "currency_id": 460000000000097, "currency_code": "USD", "currency_symbol": "$", "language_code": "en", "outstanding_receivable_amount": 250, "outstanding_receivable_amount_bcy": 250, "unused_credits_receivable_amount": 1369.66, "unused_credits_receivable_amount_bcy": 1369.66, "status": "active", "payment_reminder_enabled": true, "custom_fields": [ { "value": "GBGD078", "index": 1, "label": "VAT ID" } ], "billing_address": { "attention": "Mr.John", "address": "4900 Hopyard Rd", "street2": "Suit 310", "city": "Pleasanton", "state": "CA", "zip": 94588, "country": "U.S.A" }, "shipping_address": { "attention": "Mr.John", "address": "4900 Hopyard Rd", "street2": "Suit 310", "city": "Pleasanton", "state": "CA", "zip": 94588, "country": "U.S.A" }, "facebook": "zoho", "twitter": "zoho", "contact_persons": [ { "salutation": "Mr", "first_name": "Will", "last_name": "Smith", "email": "willsmith@bowmanfurniture.com", "phone": "+1-925-921-9201", "mobile": "+1-4054439562", "is_primary_contact": true } ], "default_templates": { "invoice_template_id": 460000000052069, "invoice_template_name": "Custom Classic", "estimate_template_id": 460000000000179, "estimate_template_name": "Service - Professional", "creditnote_template_id": 460000000000211, "creditnote_template_name": "Fixed Cost - Professional", "invoice_email_template_id": 460000000052071, "invoice_email_template_name": "Custom Invoice Notification", "estimate_email_template_id": 460000000052073, "estimate_email_template_name": "Custom Estimate Notification", "creditnote_email_template_id": 460000000052075, "creditnote_email_template_name": "Custom Credit Note Notification" }, "notes": "Payment option : Through check", "created_time": "2013-08-05", "last_modified_time": "2013-10-07", "is_taxable": true, "tax_id": 11149000000061058, "tax_name": "CGST", "tax_percentage": 12, "tax_authority_id": 11149000000061052, "tax_exemption_id": 11149000000061054, "place_of_contact": "TN", "gst_no": "22AAAAA0000A1Z5", "gst_treatment": "business_gst" } }
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.
contact_type
Optional
Type of the contact. Allowed values are
customer and vendor
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
Intended recipient at given address
address
Optional
Street address of the contact. Maximum length allowed [500]
street2
Optional
Additional Street address of the contact. Maximum length allowed [255]
city
Optional
City of the customer’s billing address.
state
Optional
State of the customer’s billing address.
zip
Optional
Zip code of the customer’s billing address.
country
Optional
Country of the customer’s billing address.
shipping_address
Optional
Customer's shipping address to which the goods must be delivered.
attention
Optional
Intended recipient at given address
address
Optional
Street address of the contact. Maximum length allowed [500]
street2
Optional
Additional Street address of the contact. Maximum length allowed [255]
city
Optional
City of the customer’s billing address.
state
Optional
State of the customer’s billing address.
zip
Optional
Zip code of the customer’s billing address.
country
Optional
Country of the customer’s billing address.
contact_persons
Optional
Person/Individual who represents a company
salutation
Optional
Salutation for the contact
first_name
Optional
First name of the contact. Maximum length [100]
last_name
Optional
Last name of the contact. Maximum length [100]
email
Optional
Search contacts by email id of the contact person. Variants:
address_startswith and address_contains
phone
Optional
Search contacts by phone number of the contact person. Variants:
phone_startswith and phone_contains
mobile
Optional
Search contacts by mobile number of the contact person.
is_primary_contact
Optional
To mark contact person as primary for contact. Allowed value is true only.
default_templates
Optional
invoice_template_id
Optional
ID of the Invoice template used
invoice_template_name
Optional
Name of the invoice template used
estimate_template_id
Optional
ID of the estimate template used
estimate_template_name
Optional
Name of the estimate template used
creditnote_template_id
Optional
ID of teh credit note template used
creditnote_template_name
Optional
Name of the credit note template used
invoice_email_template_id
Optional
ID of the invoice email tempalte used
invoice_email_template_name
Optional
Name of the Invoice email template used
estimate_email_template_id
Optional
ID of the estimate email template used
estimate_email_template_name
Optional
Name of the estimate email template used
creditnote_email_template_id
Optional
ID of the credit note email template
creditnote_email_template_name
Optional
Name of the credit note email template
language_code
Optional
language of a contact. allowed values
de,en,es,fr,it,ja,nl,pt,sv,zh
notes
Optional
Commennts about the payment made by the contact.
vat_reg_no
UK Edition $ Avalara integration only
Optional
For UK Edition: VAT Registration number of a contact with VAT treatment as
eu_vat_registered. Length should be between 2 and 12 characters.(This node is only available for EU VAT registered contacts.)For Avalara: If you are doing sales in the European Union (EU) then provide VAT Registration Number of your customers here. This is used to calculate VAT for B2B sales, from Avalara.
country_code
UK Edition $ Avalara integration only
Optional
For UK Edition: Two letter country code of a contact with VAT treatment as
eu_vat_registered.(This node is only available for EU VAT registered contacts.)For Avalara: Two letter country code for the customer country, if your customer is not in US. Refer [AvaTax Codes for Countries and States][2].
vat_treatment
UK edition only
Optional
VAT treatment of the contact.Allowed Values:
uk, eu_vat_not_registered, eu_vat_registered and non_eu.
avatax_exempt_no
Avalara integration only
Optional
Exemption certificate number of the customer.
avatax_use_code
Avalara integration only
Optional
Used to group like customers for exemption purposes. It is a custom value that links customers to a tax rule. Select from Avalara [standard codes][1] or enter a custom code.
tax_exemption_id
US, Canada, Australia and India editions only
Optional
ID of the tax exemption.
tax_authority_id
US edition only
Optional
ID of the tax authority. Tax authority depends on the location of the customer. For example, if the customer is located in NY, then the tax authority is NY tax authority.
tax_id
US and Indian editions only
Optional
ID of the tax or tax group that can be collected from the contact. Tax can be given only if
is_taxable is true.
is_taxable
US, Canada, Australia, and India Editions only.
Optional
Boolean to track the taxability of the customer.
facebook
Optional
Facebook profile account of the contact. Maximum length [100]
twitter
Optional
Twitter account of the contact. MAximum length [100]
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
Name of the Tax Authority
tax_exemption_code
US, Canada, Australia and India editions only
Optional
Enter tax exemption code
|
List contacts
List all contacts with pagination. oauthscope : ZohoBooks.contacts.READ
GET /contacts
Request Example
$ curl https://inventory.zoho.com/api/v1/contacts?organization_id=10234695 -H "Authorization: Zoho-oauthtoken 1000.41d9f2cfbd1b7a8f9e314b7aff7bc2d1.8fcc9810810a216793f385b9dd6e125f" -H "Content-Type: application/x-www-form-urlencoded;charset=UTF-8"
Response Example
HTTP/1.1 200 OK Content-Type:application/json;charset=UTF-8 { "code": 0, "message": "success", "contacts": [ { "contact_id": 460000000026049, "contact_name": "Bowman and Co", "company_name": "Bowman and Co", "contact_type": "customer", "status": "active", "payment_terms": 15, "payment_terms_label": "Net 15", "currency_id": 460000000000097, "currency_code": "USD", "outstanding_receivable_amount": 250, "unused_credits_receivable_amount": 1369.66, "first_name": "Will", "last_name": "Smith", "email": "willsmith@bowmanfurniture.com", "phone": "+1-925-921-9201", "mobile": "+1-4054439562", "created_time": "2013-08-05", "last_modified_time": "2013-10-07" }, {...}, {...} ] }
Query Params
|
contact_name
Optional
Search contacts by contact name. Maximum length [100] Variants:
contact_name_startswith and contact_name_contains. Maximum length [100]
company_name
Optional
Search contacts by company name. Maximum length [100] Variants:
company_name_startswith and company_name_contains
first_name
Optional
Search contacts by first name of the contact person. Maximum length [100] Variants:
first_name_startswith and first_name_contains
last_name
Optional
Search contacts by last name of the contact person. Maximum length [100] Variants:
last_name_startswith and last_name_contains
address
Optional
Search contacts by any of the address fields. Maximum length [100] Variants:
address_startswith and address_contains
email
Optional
Search contacts by email of the contact person. Maximum length [100] Variants:
email_startswith and email_contains
phone
Optional
Search contacts by phone number of the contact person. Maximum length [100] Variants:
phone_startswith and phone_contains
filter_by
Optional
Filter contacts by status. Allowed Values:
Status.All, Status.Active, Status.Inactive, Status.Duplicate and Status.Crm
search_text
Optional
Search contacts by contact name or notes. Maximum length [100]
sort_column
Optional
Sort contacts. Allowed Values:
contact_name, first_name, last_name, email, outstanding_receivable_amount, created_time and last_modified_time |
Get contact
Get details of a contact. oauthscope : ZohoBooks.contacts.READ
GET /contacts/{:contacts_id}
Request Example
$ curl https://inventory.zoho.com/api/v1/contacts/{:contacts_id}?organization_id=10234695 -H "Authorization: Zoho-oauthtoken 1000.41d9f2cfbd1b7a8f9e314b7aff7bc2d1.8fcc9810810a216793f385b9dd6e125f" -H "Content-Type: application/x-www-form-urlencoded;charset=UTF-8"
Response Example
HTTP/1.1 200 OK Content-Type:application/json;charset=UTF-8 { "code": 0, "message": "success", "contact": { "contact_id": 460000000026049, "contact_name": "Bowman and Co", "company_name": "Bowman and Co", "has_transaction": true, "contact_type": "customer", "is_linked_with_zohocrm": false, "website": "www.bowmanfurniture.com", "primary_contact_id": 460000000026051, "payment_terms": 15, "payment_terms_label": "Net 15", "currency_id": 460000000000097, "currency_code": "USD", "currency_symbol": "$", "outstanding_receivable_amount": 250, "outstanding_receivable_amount_bcy": 250, "unused_credits_receivable_amount": 1369.66, "unused_credits_receivable_amount_bcy": 1369.66, "status": "active", "facebook": "zoho", "twitter": "zoho", "payment_reminder_enabled": true, "custom_fields": [ { "value": "GBGD078", "index": 1, "label": "VAT ID" } ], "billing_address": { "attention": "Mr.John", "address": "4900 Hopyard Rd", "street2": "Suit 310", "city": "Pleasanton", "state": "CA", "zip": 94588, "country": "U.S.A" }, "shipping_address": { "attention": "Mr.John", "address": "4900 Hopyard Rd", "street2": "Suit 310", "city": "Pleasanton", "state": "CA", "zip": 94588, "country": "U.S.A" }, "contact_persons": [ { "salutation": "Mr", "first_name": "Will", "last_name": "Smith", "email": "willsmith@bowmanfurniture.com", "phone": "+1-925-921-9201", "mobile": "+1-4054439562", "is_primary_contact": true } ], "default_templates": { "invoice_template_id": 460000000052069, "invoice_template_name": "Custom Classic", "estimate_template_id": 460000000000179, "estimate_template_name": "Service - Professional", "creditnote_template_id": 460000000000211, "creditnote_template_name": "Fixed Cost - Professional", "invoice_email_template_id": 460000000052071, "invoice_email_template_name": "Custom Invoice Notification", "estimate_email_template_id": 460000000052073, "estimate_email_template_name": "Custom Estimate Notification", "creditnote_email_template_id": 460000000052075, "creditnote_email_template_name": "Custom Credit Note Notification" }, "notes": "Payment option : Through check", "created_time": "2013-08-05", "last_modified_time": "2013-10-07", "is_taxable": true, "tax_id": 11149000000061058, "tax_name": "CGST", "tax_percentage": 12, "tax_authority_id": 11149000000061052, "tax_exemption_id": 11149000000061054, "place_of_contact": "TN", "gst_no": "22AAAAA0000A1Z5", "gst_treatment": "business_gst" } }
Delete a contact
Delete an existing contact. oauthscope : ZohoBooks.contacts.DELETE
DELETE /contacts/{:contact_id}
Request Example
$ curl https://inventory.zoho.com/api/v1/contacts/{:contact_id}?organization_id=10234695 -X DELETE -H "Authorization: Zoho-oauthtoken 1000.41d9f2cfbd1b7a8f9e314b7aff7bc2d1.8fcc9810810a216793f385b9dd6e125f" -H "Content-Type: application/x-www-form-urlencoded;charset=UTF-8"
Response Example
HTTP/1.1 200 OK Content-Type:application/json;charset=UTF-8 { "code": 0, "message": "The contact has been deleted." }
Mark as active
Mark a contact as active. oauthscope : ZohoBooks.contacts.CREATE
POST /contact/{:contact_id}/active
Request Example
$ curl https://inventory.zoho.com/api/v1/contact/{:contact_id}/active?organization_id=10234695 -X POST -H "Authorization: Zoho-oauthtoken 1000.41d9f2cfbd1b7a8f9e314b7aff7bc2d1.8fcc9810810a216793f385b9dd6e125f" -H "Content-Type: application/x-www-form-urlencoded;charset=UTF-8"
Response Example
HTTP/1.1 200 OK Content-Type:application/json;charset=UTF-8 { "code": 0, "message": "The contact has been marked as active." }
Mark as Inactive
Mark a contact as inactive. oauthscope : ZohoBooks.contacts.CREATE
POST /contacts/{:contact_id}/inactive
Request Example
$ curl https://inventory.zoho.com/api/v1/contacts/{:contact_id}/inactive?organization_id=10234695 -X POST -H "Authorization: Zoho-oauthtoken 1000.41d9f2cfbd1b7a8f9e314b7aff7bc2d1.8fcc9810810a216793f385b9dd6e125f" -H "Content-Type: application/x-www-form-urlencoded;charset=UTF-8"
Response Example
HTTP/1.1 200 OK Content-Type:application/json;charset=UTF-8 { "code": 0, "message": "The contact has been marked as inactive." }
Email statement
Email statement to the contact. If JSONString is not inputted, mail will be sent with the default mail content. oauthscope : ZohoInventory.contacts.CREATE
POST /contacts/{:contact_id}/statements/email
Request Example
$ curl https://inventory.zoho.com/api/v1/contacts/{:contact_id}/statements/email?organization_id=10234695 -X POST -H "Authorization: Zoho-oauthtoken 1000.41d9f2cfbd1b7a8f9e314b7aff7bc2d1.8fcc9810810a216793f385b9dd6e125f" -H "Content-Type: application/x-www-form-urlencoded;charset=UTF-8" -F 'JSONString="{ "send_from_org_email_id": true, "to_mail_ids": [ "willsmith@bowmanfurniture.com" ], "cc_mail_ids": [ "peterparker@bowmanfurniture.com" ], "subject": "Statement of transactions with Zillium Inc", "body": "Dear Customer, <br/>We have attached with this email a list of all your transactions with us for the period 01 Sep 2013 to 30 Sep 2013. You can write to us or call us if you need any assistance or clarifications. <br/>Thanks for your business.<br/>Regards<br/>Zillium Inc" }"'
Response Example
HTTP/1.1 200 OK Content-Type:application/json;charset=UTF-8 { "code": 0, "message": "Statement has been sent to the customer." }
ARGUMENTS
|
send_from_org_email_id
Optional
Boolean to trigger the email from the organization's email address
to_mail_ids
Required
Array of email addresses of the recipients.
cc_mail_ids
Optional
Array of email addresses of the recipients to be CC'd.
subject
Required
Subject of an email that has to be sent. Maximum length to be allowed [1000]
body
Required
Body/content of the email to be sent. Maximum length [5000]
|
Query Params
|
start_date
Optional
If start_date and end_date are not given, current month's statement will be sent to contact. Date format [yyyy-mm-dd]
end_date
Optional
End date for the statement. Date format [yyyy-mm-dd]
multipart_or_formdata
Optional
Files to be attached along with the statement.
|
Get Statement mail content
Get the mail content of a contacts billing statement. oauthscope : ZohoInventory.contacts.READ
GET /contacts/{:contact_id}/statements/email
Request Example
$ curl https://inventory.zoho.com/api/v1/contacts/{:contact_id}/statements/email?organization_id=10234695 -H "Authorization: Zoho-oauthtoken 1000.41d9f2cfbd1b7a8f9e314b7aff7bc2d1.8fcc9810810a216793f385b9dd6e125f" -H "Content-Type: application/x-www-form-urlencoded;charset=UTF-8"
Response Example
HTTP/1.1 200 OK Content-Type:application/json;charset=UTF-8 { "code": 0, "message": "success", "body": "Dear Customer, <br/>We have attached with this email a list of all your transactions with us for the period 01 Sep 2013 to 30 Sep 2013. You can write to us or call us if you need any assistance or clarifications. <br/>Thanks for your business.<br/>Regards<br/>Zillium Inc", "subject": "Statement of transactions with Zillium Inc", "to_contacts": [ { "first_name": "Will", "selected": true, "phone": "+1-925-921-9201", "email": "willsmith@bowmanfurniture.com", "contact_person_id": 460000000026051, "last_name": "Smith", "salutation": "Mr", "mobile": "+1-4054439562" } ], "file_name": "statement_BowmanandCo.pdf", "from_emails": [ { "user_name": "John Smith", "selected": true, "email": "willsmith@bowmanfurniture.com" } ], "contact_id": 460000000026049 }
Query Params
|
start_date
Optional
If start_date and end_date are not given, current month's statement will be sent to contact. Date format [yyyy-mm-dd]
end_date
Optional
End date for the statement. Date format [yyyy-mm-dd]
|
Email contact
Send email to contact. oauthscope : ZohoInventory.contacts.CREATE
POST /contacts/{:contact_id}/email
Request Example
$ curl https://inventory.zoho.com/api/v1/contacts/{:contact_id}/email?organization_id=10234695 -X POST -H "Authorization: Zoho-oauthtoken 1000.41d9f2cfbd1b7a8f9e314b7aff7bc2d1.8fcc9810810a216793f385b9dd6e125f" -H "Content-Type: application/x-www-form-urlencoded;charset=UTF-8" -F 'JSONString="{ "to_mail_ids": [ "willsmith@bowmanfurniture.com" ], "subject": "Welcome to Zillium Inc .", "body": "Dear Customer, <br/>We have attached with this email a list of all your transactions with us for the period 01 Sep 2013 to 30 Sep 2013. You can write to us or call us if you need any assistance or clarifications. <br/>Thanks for your business.<br/>Regards<br/>Zillium Inc" }"'
Response Example
HTTP/1.1 200 OK Content-Type:application/json;charset=UTF-8 { "code": 0, "message": "Email has been sent." }
ARGUMENTS
|
to_mail_ids
Required
Array of email addresses of the recipients.
subject
Required
Subject of an email has to be sent. Maximum length [1000]
body
Required
Body/content of the email to be sent. Maximum length [5000]
attachments
Optional
Files to be attached to the email. It has to be sent in multipart/formdata
|
Query Params
|
send_customer_statement
Optional
Send customer statement pdf with email.
|
List Comments
List recent activities of a contact. oauthscope : ZohoInventory.contacts.READ
GET /contacts/{:contact_id}/comments
Request Example
$ curl https://inventory.zoho.com/api/v1/contacts/{:contact_id}/comments?organization_id=10234695 -H "Authorization: Zoho-oauthtoken 1000.41d9f2cfbd1b7a8f9e314b7aff7bc2d1.8fcc9810810a216793f385b9dd6e125f" -H "Content-Type: application/x-www-form-urlencoded;charset=UTF-8"
Response Example
HTTP/1.1 200 OK Content-Type:application/json;charset=UTF-8 { "code": 0, "message": "success", "contact_comments": [ { "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" } ] }, {...}, {...} ] }
Contact Persons
A contact person is an individual who acts as a representative of an organisation for communication purpose. For example, a Manager can be a contact person for an organisation.
Example
{ "contact_id": 460000000026049, "first_name": "Will", "last_name": "Smith", "email": "willsmith@bowmanfurniture.com", "skype": "zoho", "designation": "Sales Engineer", "department": "Sales" }
Attribute
|
contact_id
string
ID of the contact person
first_name
string
First Name of the contact. Maximum length allowed [100]
last_name
string
Last Name of the contact. Maximum length allowed [100]
email
string
Email ID of the contact person. Maximum length allowed [100]
skype
string
skype address of the contact person. Maximum length [50]
designation
string
designation of the contact person in the organisation. Maximum length [50]
department
string
department to which the contact person belongs. Maximum length [50]
|
Create a contact person
Create a contact person for contact. oauthscope : ZohoBooks.contacts.CREATE
POST /contacts/contactpersons
Request Example
$ curl https://inventory.zoho.com/api/v1/contacts/contactpersons?organization_id=10234695 -X POST -H "Authorization: Zoho-oauthtoken 1000.41d9f2cfbd1b7a8f9e314b7aff7bc2d1.8fcc9810810a216793f385b9dd6e125f" -H "Content-Type: application/x-www-form-urlencoded;charset=UTF-8" -F 'JSONString="{ "contact_id": 460000000026049, "salutation": "Mr", "first_name": "Will", "last_name": "Smith", "email": "willsmith@bowmanfurniture.com", "phone": "+1-925-921-9201", "mobile": "+1-4054439562", "skype": "zoho", "designation": "Sales Engineer", "department": "Sales", "enable_portal": true }"'
Response Example
HTTP/1.1 201 Created Content-Type:application/json;charset=UTF-8 { "code": 0, "message": "The contact person has been Created", "contact_person": [ { "contact_id": 460000000026049, "contact_person_id": 460000000026051, "salutation": "Mr", "first_name": "Will", "last_name": "Smith", "email": "willsmith@bowmanfurniture.com", "phone": "+1-925-921-9201", "mobile": "+1-4054439562", "is_primary_contact": true, "skype": "zoho", "designation": "Sales Engineer", "department": "Sales", "is_added_in_portal": true } ] }
ARGUMENTS
|
contact_id
Optional
ID of the contact person
salutation
Optional
Salutation for the contact. Maximum length allowed [25]
first_name
Required
First Name of the contact. Maximum length allowed [100]
last_name
Optional
Last Name of the contact. Maximum length allowed [100]
email
Optional
Email ID of the contact person. Maximum length allowed [100]
phone
Optional
Phone number of the contact person. Maximum length [50]
mobile
Optional
Mobile/Cell number of the contact person. Maximum length [50]
skype
Optional
skype address of the contact person. Maximum length [50]
designation
Optional
designation of the contact person in the organisation. Maximum length [50]
department
Optional
department to which the contact person belongs. Maximum length [50]
enable_portal
Optional
option to enable or disable portal access the contact person. allowed values
true,false |
Update a contact person
Update details of an existing contact person. oauthscope : ZohoBooks.contacts.UPDATE
PUT /contacts/contactpersons/{:contact_person_id}
Request Example
$ curl https://inventory.zoho.com/api/v1/contacts/contactpersons/{:contact_person_id}?organization_id=10234695 -X PUT -H "Authorization: Zoho-oauthtoken 1000.41d9f2cfbd1b7a8f9e314b7aff7bc2d1.8fcc9810810a216793f385b9dd6e125f" -H "Content-Type: application/x-www-form-urlencoded;charset=UTF-8" -F 'JSONString="{ "contact_id": 460000000026049, "salutation": "Mr", "first_name": "Will", "last_name": "Smith", "email": "willsmith@bowmanfurniture.com", "phone": "+1-925-921-9201", "mobile": "+1-4054439562", "skype": "zoho", "designation": "Sales Engineer", "department": "Sales", "enable_portal": true }"'
Response Example
HTTP/1.1 200 OK Content-Type:application/json;charset=UTF-8 { "code": 0, "message": "The contactperson details has been updated.", "contact_person": [ { "contact_id": 460000000026049, "contact_person_id": 460000000026051, "salutation": "Mr", "first_name": "Will", "last_name": "Smith", "email": "willsmith@bowmanfurniture.com", "phone": "+1-925-921-9201", "mobile": "+1-4054439562", "is_primary_contact": true, "skype": "zoho", "designation": "Sales Engineer", "department": "Sales", "is_added_in_portal": true } ] }
ARGUMENTS
|
contact_id
Required
ID of the contact person
salutation
Optional
Salutation for the contact. Maximum length allowed [25]
first_name
Required
First Name of the contact. Maximum length allowed [100]
last_name
Optional
Last Name of the contact. Maximum length allowed [100]
email
Optional
Email ID of the contact person. Maximum length allowed [100]
phone
Optional
Phone number of the contact person. Maximum length [50]
mobile
Optional
Mobile/Cell number of the contact person. Maximum length [50]
skype
Optional
skype address of the contact person. Maximum length [50]
designation
Optional
designation of the contact person in the organisation. Maximum length [50]
department
Optional
department to which the contact person belongs. Maximum length [50]
enable_portal
Optional
option to enable or disable portal access the contact person. allowed values
true,false |
List contact persons
List all contacts with pagination. oauthscope : ZohoBooks.contacts.READ
GET /contacts/{:contact_id}/contactpersons
Request Example
$ curl https://inventory.zoho.com/api/v1/contacts/{:contact_id}/contactpersons?organization_id=10234695 -H "Authorization: Zoho-oauthtoken 1000.41d9f2cfbd1b7a8f9e314b7aff7bc2d1.8fcc9810810a216793f385b9dd6e125f" -H "Content-Type: application/x-www-form-urlencoded;charset=UTF-8"
Response Example
HTTP/1.1 200 OK Content-Type:application/json;charset=UTF-8 { "code": 0, "message": "success", "contact_persons": [ { "contact_id": 460000000026049, "contact_person_id": 460000000026051, "salutation": "Mr", "first_name": "Will", "last_name": "Smith", "email": "willsmith@bowmanfurniture.com", "phone": "+1-925-921-9201", "mobile": "+1-4054439562", "is_primary_contact": true, "skype": "zoho", "designation": "Sales Engineer", "department": "Sales", "is_added_in_portal": true }, {...}, {...} ] }
Get a contact person
Get the details of a contact person. oauthscope : ZohoBooks.contacts.READ
GET /contacts/{:contact_id}/contactpersons/{:contact_person_id}
Request Example
$ curl https://inventory.zoho.com/api/v1/contacts/{:contact_id}/contactpersons/{:contact_person_id}?organization_id=10234695 -H "Authorization: Zoho-oauthtoken 1000.41d9f2cfbd1b7a8f9e314b7aff7bc2d1.8fcc9810810a216793f385b9dd6e125f" -H "Content-Type: application/x-www-form-urlencoded;charset=UTF-8"
Response Example
HTTP/1.1 200 OK Content-Type:application/json;charset=UTF-8 { "code": 0, "message": "success", "contact_person": { "contact_id": 460000000026049, "contact_person_id": 460000000026051, "salutation": "Mr", "first_name": "Will", "last_name": "Smith", "email": "willsmith@bowmanfurniture.com", "phone": "+1-925-921-9201", "mobile": "+1-4054439562", "is_primary_contact": true, "skype": "zoho", "designation": "Sales Engineer", "department": "Sales", "is_added_in_portal": true } }
Delete a contact person
Delete an existing contact person. oauthscope : ZohoBooks.contacts.DELETE
DELETE /contacts/contactpersons/{:contact_person_id}
Request Example
$ curl https://inventory.zoho.com/api/v1/contacts/contactpersons/{:contact_person_id}?organization_id=10234695 -X DELETE -H "Authorization: Zoho-oauthtoken 1000.41d9f2cfbd1b7a8f9e314b7aff7bc2d1.8fcc9810810a216793f385b9dd6e125f" -H "Content-Type: application/x-www-form-urlencoded;charset=UTF-8"
Response Example
HTTP/1.1 200 OK Content-Type:application/json;charset=UTF-8 { "code": 0, "message": "The contact person has been deleted." }
Mark as primary contact person
Mark a contact person as primary for contact. oauthscope : ZohoBooks.contacts.CREATE
POST /contacts/contactpersons/{:contact_person_id}/primary
Request Example
$ curl https://inventory.zoho.com/api/v1/contacts/contactpersons/{:contact_person_id}/primary?organization_id=10234695 -X POST -H "Authorization: Zoho-oauthtoken 1000.41d9f2cfbd1b7a8f9e314b7aff7bc2d1.8fcc9810810a216793f385b9dd6e125f" -H "Content-Type: application/x-www-form-urlencoded;charset=UTF-8"
Response Example
HTTP/1.1 200 OK Content-Type:application/json;charset=UTF-8 { "code": 0, "message": "This contact person has been marked as your primary contact person." }
Item Groups
Item Group are the products that you sell or services that you render to various clients and can be purchased from various vendors in a business. Create and manage the item groups your business deals with and also create price lists for specific item and clients.
Example
{ "group_id": 4815000000044220, "group_name": "Bags", "brand": "Brand", "manufacturer": "Bagstore", "unit": "qty", "description": "description", "is_taxable": true, "tax_id": 4815000000044043, "tax_name": "Sales", "tax_percentage": 12, "tax_type": "Service Tax", "attribute_id1": 4815000000044112, "attribute_name1": "Small", "status": "active", "image_id": 2077500000000002000, "image_name": "bag_s.jpg", "image_type": "jpg", "items": [ { "item_id": 4815000000044208, "name": "Bags-small", "status": "active", "rate": 6, "purchase_rate": 6, "reorder_level": 5, "initial_stock": 50, "initial_stock_rate": 500, "vendor_id": 4815000000044080, "vendor_name": "Molly", "stock_on_hand": 50, "sku": "SK1234", "upc": 111111111111, "ean": 111111111112, "isbn": 111111111113, "part_number": 111111111114, "attribute_option_id1": 4815000000044214, "attribute_option_name1": "Small", "image_id": 2077500000000002000, "image_name": "bag_s.jpg", "image_type": "jpg" } ], "attributes": [ { "id": 4815000000044112, "name": "Bags-small", "options": [ { "id": 4815000000044112, "name": "Bags-small" } ] } ] }
Attribute
|
group_id
long
Unique ID generated by the server. This is used an a unique identifier.
group_name
string
Name of the Item Group.
brand
string
Brand of the Item Group.
manufacturer
string
Manufacturer of Item Group.
unit
string
Unit of measurement of the Item Group.
description
string
Description of the Item Group.
is_taxable
boolean
Boolean to track the taxability of the item.
tax_id
long
Unique ID generated by the server for the tax associated with the item. This is used a unique identifier.
tax_name
string
Name of the tax applied on the Item Group.
tax_percentage
double
Percentage of the Tax
tax_type
string
Type of the Tax.
attribute_id1
long
Unique ID used by the server. This is used as an identifier.
attribute_name1
string
Name of the attribute present in the Item Group.
status
string
Status of the Item Group.
source
string
The source of the Item Group.
image_id
string
Unique ID generated by the server for the Item image. This is used as an identifier.
image_name
string
Name of the Item image.
image_type
string
Type of the image i.e., its file format.
items
list
The items present in the Item Group.
item_id
long
Unique ID generated by the server for the Item. This is used as an identifier.
name
string
Name of the Item.
status
string
Status of the Item Group.
rate
double
Sales price of the Item.
purchase_rate
double
Purchase price of the Item.
reorder_level
double
Reorder level of the item.
initial_stock
double
The opening stock of the item.
initial_stock_rate
double
The opening stock value of the item.
vendor_id
long
Unique ID generated by the server for the Vendor. This is used as an identifier.
vendor_name
string
Name of the preferred Vendor for purchasing this item.
stock_on_hand
double
Stock available for a particular item.
sku
string
The Stock Keeeping Unit (SKU) of an item. This is unique for every item in the Inventory.
upc
long
The 12 digit Unique Product Code (UPC) of the item.
ean
long
Unique EAN value for the Item.
isbn
string
Unique ISBN value for the Item.
part_number
string
Part Number of the Item.
attribute_option_id1
long
Unique ID generated by the server for the attribute's options. This is used as an identifier.
attribute_option_name1
long
Name of the attribute's option.
image_id
string
Unique ID generated by the server for the Item image. This is used as an identifier.
image_name
string
Name of the Item image.
image_type
string
Type of the image i.e., its file format.
attributes
list
All the attributes present in the Item Group. Each attribute will have its own option.
id
long
Unique ID generated by the server for the attribute. This is used as an identifier.
name
string
Name of the Item.
options
list
The options present for each attribute.
|
Create an Item Group
A new Item Group can a be created. While creating items, user can attach image for product group by passing form-data parameter image i.e., -F image=bag_s.jpg. oauthscope : ZohoInventory.items.CREATE
POST /itemgroups
Request Example
$ curl https://inventory.zoho.com/api/v1/itemgroups?organization_id=10234695 -X POST -H "Authorization: Zoho-oauthtoken 1000.41d9f2cfbd1b7a8f9e314b7aff7bc2d1.8fcc9810810a216793f385b9dd6e125f" -H "Content-Type: application/x-www-form-urlencoded;charset=UTF-8" -F 'JSONString="{ "group_name": "Bags", "brand": "Brand", "manufacturer": "Bagstore", "unit": "qty", "description": "description", "tax_id": 4815000000044043, "attribute_name1": "Small", "items": [ { "name": "Bags-small", "rate": 6, "purchase_rate": 6, "reorder_level": 5, "initial_stock": 50, "initial_stock_rate": 500, "vendor_id": 4815000000044080, "sku": "SK1234", "upc": 111111111111, "ean": 111111111112, "isbn": 111111111113, "part_number": 111111111114, "attribute_option_name1": "Small" } ], "attributes": [ { "id": 4815000000044112, "name": "Bags-small", "options": [ { "id": 4815000000044112, "name": "Bags-small" } ] } ] }"'
Response Example
HTTP/1.1 201 Created Content-Type:application/json;charset=UTF-8 { "code": 0, "message": "The Item Group has been created.", "group_id": 4815000000044220, "group_name": "Bags", "documents": [ {...} ], "brand": "Brand", "manufacturer": "Bagstore", "unit": "qty", "description": "description", "is_taxable": true, "tax_id": 4815000000044043, "tax_name": "Sales", "tax_percentage": 12, "tax_type": "Service Tax", "attribute_id1": 4815000000044112, "attribute_name1": "Small", "status": "active", "image_id": 2077500000000002000, "image_name": "bag_s.jpg", "image_type": "jpg", "items": { "item_id": 4815000000044208, "name": "Bags-small", "status": "active", "rate": 6, "purchase_rate": 6, "reorder_level": 5, "initial_stock": 50, "initial_stock_rate": 500, "vendor_id": 4815000000044080, "vendor_name": "Molly", "stock_on_hand": 50, "sku": "SK1234", "upc": 111111111111, "ean": 111111111112, "isbn": 111111111113, "part_number": 111111111114, "attribute_option_id1": 4815000000044214, "attribute_option_name1": "Small", "image_id": 2077500000000002000, "image_name": "bag_s.jpg", "image_type": "jpg", "actual_available_stock": 2, "available_stock": 2 }, "attributes": { "id": 4815000000044112, "name": "Bags-small", "options": { "id": 4815000000044112, "name": "Bags-small" } } }
ARGUMENTS
|
group_name
Required
Name of the Item Group.
brand
Optional
Brand of the Item Group.
manufacturer
Optional
Manufacturer of Item Group.
unit
Required
Unit of measurement of the Item Group.
description
Optional
Description of the Item Group.
tax_id
Optional
Unique ID generated by the server for the tax associated with the item. This is used a unique identifier.
attribute_name1
Optional
Name of the attribute present in the Item Group.
items
Optional
The items present in the Item Group.
name
Required
Name of the Item.
rate
Required
Sales price of the Item.
purchase_rate
Required
Purchase price of the Item.
reorder_level
Optional
Reorder level of the item.
initial_stock
Optional
The opening stock of the item.
initial_stock_rate
Optional
The opening stock value of the item.
vendor_id
Optional
Unique ID generated by the server for the Vendor. This is used as an identifier.
sku
Optional
The Stock Keeeping Unit (SKU) of an item. This is unique for every item in the Inventory.
upc
Optional
The 12 digit Unique Product Code (UPC) of the item.
ean
Optional
Unique EAN value for the Item.
isbn
Optional
Unique ISBN value for the Item.
part_number
Optional
Part Number of the Item.
attribute_option_name1
Optional
Name of the attribute's option.
attributes
Optional
All the attributes present in the Item Group. Each attribute will have its own option.
id
Optional
Unique ID generated by the server for the attribute. This is used as an identifier.
name
Required
Name of the Item.
options
Optional
The options present for each attribute.
|
Retrieve an Item Group
Fetches the details for an existing Item Group. oauthscope : ZohoInventory.items.READ
GET /itemgroups/{itemgroup_id}
Request Example
$ curl https://inventory.zoho.com/api/v1/itemgroups/{itemgroup_id}?organization_id=10234695 -H "Authorization: Zoho-oauthtoken 1000.41d9f2cfbd1b7a8f9e314b7aff7bc2d1.8fcc9810810a216793f385b9dd6e125f" -H "Content-Type: application/x-www-form-urlencoded;charset=UTF-8"
Response Example
HTTP/1.1 200 OK Content-Type:application/json;charset=UTF-8 { "code": 0, "message": "success", "group_id": 4815000000044220, "group_name": "Bags", "brand": "Brand", "manufacturer": "Bagstore", "unit": "qty", "description": "description", "is_taxable": true, "tax_id": 4815000000044043, "tax_name": "Sales", "tax_percentage": 12, "tax_type": "Service Tax", "attribute_id1": 4815000000044112, "attribute_name1": "Small", "status": "active", "image_id": 2077500000000002000, "image_name": "bag_s.jpg", "image_type": "jpg", "items": { "item_id": 4815000000044208, "name": "Bags-small", "status": "active", "rate": 6, "purchase_rate": 6, "reorder_level": 5, "initial_stock": 50, "initial_stock_rate": 500, "vendor_id": 4815000000044080, "vendor_name": "Molly", "stock_on_hand": 50, "sku": "SK1234", "upc": 111111111111, "ean": 111111111112, "isbn": 111111111113, "part_number": 111111111114, "attribute_option_id1": 4815000000044214, "attribute_option_name1": "Small", "image_id": 2077500000000002000, "image_name": "bag_s.jpg", "image_type": "jpg" }, "attributes": { "id": 4815000000044112, "name": "Bags-small", "options": { "id": 4815000000044112, "name": "Bags-small" } }, "options": { "id": 4815000000044112, "name": "Bags-small" } }
Update an Item Group
Updates the details of an existing Item Group. oauthscope : ZohoInventory.items.UPDATE
PUT /itemgroups/{itemgroup_id}
Request Example
$ curl https://inventory.zoho.com/api/v1/itemgroups/{itemgroup_id}?organization_id=10234695 -X PUT -H "Authorization: Zoho-oauthtoken 1000.41d9f2cfbd1b7a8f9e314b7aff7bc2d1.8fcc9810810a216793f385b9dd6e125f" -H "Content-Type: application/x-www-form-urlencoded;charset=UTF-8" -F 'JSONString="{ "group_name": "Bags", "brand": "Brand", "manufacturer": "Bagstore", "unit": "qty", "description": "description", "tax_id": 4815000000044043, "attribute_name1": "Small" }"'
Response Example
HTTP/1.1 200 OK Content-Type:application/json;charset=UTF-8 { "code": 0, "message": "The Item Group details have been updated.", "group_id": 4815000000044220, "group_name": "Bags", "brand": "Brand", "manufacturer": "Bagstore", "unit": "qty", "description": "description", "is_taxable": true, "tax_id": 4815000000044043, "tax_name": "Sales", "tax_percentage": 12, "tax_type": "Service Tax", "attribute_id1": 4815000000044112, "attribute_name1": "Small", "status": "active", "image_id": 2077500000000002000, "image_name": "bag_s.jpg", "image_type": "jpg" }
ARGUMENTS
|
group_name
Required
Name of the Item Group.
brand
Optional
Brand of the Item Group.
manufacturer
Optional
Manufacturer of Item Group.
unit
Required
Unit of measurement of the Item Group.
description
Optional
Description of the Item Group.
tax_id
Optional
Unique ID generated by the server for the tax associated with the item. This is used a unique identifier.
attribute_name1
Optional
Name of the attribute present in the Item Group.
|
Delete an Item Group
Deletes an existing Item Group from Zoho Inventory. oauthscope : ZohoInventory.items.DELETE
DELETE /itemgroups/{itemgroup_id}
Request Example
$ curl https://inventory.zoho.com/api/v1/itemgroups/{itemgroup_id}?organization_id=10234695 -X DELETE -H "Authorization: Zoho-oauthtoken 1000.41d9f2cfbd1b7a8f9e314b7aff7bc2d1.8fcc9810810a216793f385b9dd6e125f" -H "Content-Type: application/x-www-form-urlencoded;charset=UTF-8"
Response Example
HTTP/1.1 200 OK Content-Type:application/json;charset=UTF-8 { "code": 0, "message": "Whooooosh! The item group and all its items have been deleted." }
List all Item Groups
Lists all the Item Groups that are present in the Zoho Inventory organization. oauthscope : ZohoInventory.items.READ
GET /itemgroups
Request Example
$ curl https://inventory.zoho.com/api/v1/itemgroups?organization_id=10234695 -H "Authorization: Zoho-oauthtoken 1000.41d9f2cfbd1b7a8f9e314b7aff7bc2d1.8fcc9810810a216793f385b9dd6e125f" -H "Content-Type: application/x-www-form-urlencoded;charset=UTF-8"
Response Example
HTTP/1.1 200 OK Content-Type:application/json;charset=UTF-8 { "code": 0, "message": "success", "itemgroups": [ { "group_id": 4815000000044220, "group_name": "Bags", "product_type": "goods", "brand": "Brand", "manufacturer": "Bagstore", "unit": "qty", "description": "description", "is_taxable": true, "tax_id": 4815000000044043, "tax_name": "Sales", "tax_percentage": 12, "tax_type": "Service Tax", "tax_exemption_id": null, "attribute_id1": 4815000000044112, "attribute_name1": "Small", "status": "active", "image_id": 2077500000000002000, "image_name": "bag_s.jpg", "image_type": "jpg", "items": { "item_id": 4815000000044208, "name": "Bags-small", "status": "active", "rate": 6, "purchase_rate": 6, "reorder_level": 5, "initial_stock": 50, "initial_stock_rate": 500, "vendor_id": 4815000000044080, "vendor_name": "Molly", "stock_on_hand": 50, "sku": "SK1234", "upc": 111111111111, "ean": 111111111112, "isbn": 111111111113, "part_number": 111111111114, "attribute_option_id1": 4815000000044214, "attribute_option_name1": "Small", "image_id": 2077500000000002000, "image_name": "bag_s.jpg", "image_type": "jpg", "available_stock": 2, "actual_available_stock": 2 }, "created_time": "2013-01-24", "last_modified_time": "2013-01-24" }, {...}, {...} ] }
Mark as Active
Marks an Item group as Active. oauthscope : ZohoInventory.items.CREATE
POST /itemgroups/{itemgroup_id}/active
Request Example
$ curl https://inventory.zoho.com/api/v1/itemgroups/{itemgroup_id}/active?organization_id=10234695 -X POST -H "Authorization: Zoho-oauthtoken 1000.41d9f2cfbd1b7a8f9e314b7aff7bc2d1.8fcc9810810a216793f385b9dd6e125f" -H "Content-Type: application/x-www-form-urlencoded;charset=UTF-8"
Response Example
HTTP/1.1 200 OK Content-Type:application/json;charset=UTF-8 { "code": 0, "message": "Back to business! The item group and all its items have been marked as active." }
Mark as Inactive.
Marks as Item Group as Inactive. oauthscope : ZohoInventory.items.CREATE
POST /itemgroups/{itemgroup_id}/inactive
Request Example
$ curl https://inventory.zoho.com/api/v1/itemgroups/{itemgroup_id}/inactive?organization_id=10234695 -X POST -H "Authorization: Zoho-oauthtoken 1000.41d9f2cfbd1b7a8f9e314b7aff7bc2d1.8fcc9810810a216793f385b9dd6e125f" -H "Content-Type: application/x-www-form-urlencoded;charset=UTF-8"
Response Example
HTTP/1.1 200 OK Content-Type:application/json;charset=UTF-8 { "code": 0, "message": "The item group and all its items have been marked as inactive." }
Items
An item is the product that is offered for sale. Nature of the product could be physical or digital. Based on the type of your business, you can offer one or more goods/services. Your product can be either fixed priced or a subscription service. Each of this may fall under a separate pricing category or have add ons associated to them.
Example
{ "group_id": 4815000000044220, "group_name": "Bags", "unit": "qty", "item_type": "inventory", "product_type": "goods", "is_taxable": true, "tax_id": 4815000000044043, "description": "description", "tax_name": "Sales", "tax_percentage": 12, "tax_type": "Service Tax", "purchase_account_id": 4815000000035003, "purchase_account_name": "Cost of Goods Sold", "account_id": 4815000000000388, "account_name": "Sales", "inventory_account_id": 4815000000035001, "attribute_id1": 4815000000044112, "attribute_name1": "Small", "status": "active", "item_id": 4815000000044208, "name": "Bags-small", "rate": 6, "pricebook_rate": 6, "purchase_rate": 6, "reorder_level": 5, "initial_stock": 50, "initial_stock_rate": 500, "vendor_id": 4815000000044080, "vendor_name": "Molly", "stock_on_hand": 50, "sku": "SK123", "upc": 111111111111, "ean": 111111111112, "isbn": 111111111113, "part_number": 111111111114, "attribute_option_id1": 4815000000044214, "attribute_option_name1": "Small", "image_id": 2077500000000002000, "image_name": "bag_s.jpg", "purchase_description": "Purchase description", "image_type": "jpg", "item_tax_preferences": [ { "tax_id": 4815000000044043, "tax_specification": "intra" } ], "hsn_or_sac": 85423100 }
Attribute
|
group_id
string
Unique ID generated by the server for the group to which the item belongs, if any. This is used as an identifier.
group_name
string
Name of product group
unit
string
Unit of measurement for the item.
item_type
string
Item type can be
inventory, sales, purchases or sales_and_purchases. If item is associated with a group, then type should be inventory.
product_type
string
Type of the product. It can be
goods or service
is_taxable
boolean
Boolean to track the taxability of the item.
tax_id
long
Unique ID generated by the server for the tax associated with the item. This is used a unique identifier.
description
string
Description of the Item.
tax_name
string
Name of the tax applied on the Item Group.
tax_percentage
double
Percentage of the Tax
tax_type
string
Type of the Tax.
purchase_account_id
long
Unique ID generated by the server for the Purchase account.
purchase_account_name
string
Name of the Purchase Account
account_id
long
Unique ID generated by the server for the Sales account.
account_name
string
Name of the Sales Account.
inventory_account_id
long
Uniquq ID generated by the server for the Inventory account.
attribute_id1
long
Unique ID used by the server. This is used as an identifier.
attribute_name1
string
Name of the attribute present in the Item Group.
status
string
Status of the Item Group.
source
string
The source of the Item Group.
item_id
long
Unique ID generated by the server for the Item. This is used as an identifier.
name
string
Name of the Item.
rate
double
Sales price of the Item.
pricebook_rate
double
Pricelist rate applied on the item.
purchase_rate
double
Purchase price of the Item.
reorder_level
double
Reorder level of the item.
initial_stock
double
The opening stock of the item.
initial_stock_rate
double
The opening stock value of the item.
vendor_id
long
Unique ID generated by the server for the Vendor. This is used as an identifier.
vendor_name
string
Name of the preferred Vendor for purchasing this item.
stock_on_hand
double
Stock available for a particular item.
sku
string
The Stock Keeeping Unit (SKU) of an item. This is unique for every item in the Inventory.
upc
long
The 12 digit Unique Product Code (UPC) of the item.
ean
long
Unique EAN value for the Item.
isbn
string
Unique ISBN value for the Item.
part_number
string
Part Number of the Item.
attribute_option_id1
long
Unique ID generated by the server for the attribute's options. This is used as an identifier.
attribute_option_name1
long
Name of the attribute's option.
image_id
long
Unique ID generated by the server for the item image. This is used as an identifier.
image_name
string
Image name of the Item.
purchase_description
string
The description for the purchase information. This will be displayed to the vendor in your purchase order.
image_type
string
Type of the image i.e., its file format.
item_tax_preferences
India Edition only
list
tax_id
long
Unique ID generated by the server for the tax associated with the item. This is used a unique identifier.
tax_specification
India Edition only
string
Type of tax. It can be
intra or inter
hsn_or_sac
India Edition Only
string
HSN Code of the item
|
Create an item
Creates a new item in Zoho Inventory. oauthscope : ZohoInventory.items.CREATE
POST /items
Request Example
$ curl https://inventory.zoho.com/api/v1/items?organization_id=10234695 -X POST -H "Authorization: Zoho-oauthtoken 1000.41d9f2cfbd1b7a8f9e314b7aff7bc2d1.8fcc9810810a216793f385b9dd6e125f" -H "Content-Type: application/x-www-form-urlencoded;charset=UTF-8" -F 'JSONString="{ "group_id": 4815000000044220, "group_name": "Bags", "unit": "qty", "item_type": "inventory", "product_type": "goods", "is_taxable": true, "tax_id": 4815000000044043, "description": "description", "purchase_account_id": 4815000000035003, "inventory_account_id": 4815000000035001, "attribute_name1": "Small", "name": "Bags-small", "rate": 6, "purchase_rate": 6, "reorder_level": 5, "initial_stock": 50, "initial_stock_rate": 500, "vendor_id": 4815000000044080, "vendor_name": "Molly", "sku": "SK123", "upc": 111111111111, "ean": 111111111112, "isbn": 111111111113, "part_number": 111111111114, "attribute_option_name1": "Small", "purchase_description": "Purchase description", "item_tax_preferences": [ { "tax_id": 4815000000044043, "tax_specification": "intra" } ], "hsn_or_sac": 85423100 }"'
Response Example
HTTP/1.1 200 OK Content-Type:application/json;charset=UTF-8 { "code": 0, "message": "The item has been added.", "item": { "group_id": 4815000000044220, "group_name": "Bags", "item_id": 4815000000044208, "name": "Bags-small", "unit": "qty", "item_type": "inventory", "product_type": "goods", "is_taxable": true, "tax_id": 4815000000044043, "description": "description", "tax_name": "Sales", "tax_percentage": 12, "tax_type": "Service Tax", "purchase_account_id": 4815000000035003, "purchase_account_name": "Cost of Goods Sold", "account_name": "Sales", "inventory_account_id": 4815000000035001, "attribute_id1": 4815000000044112, "attribute_name1": "Small", "status": "active", "rate": 6, "pricebook_rate": 6, "purchase_rate": 6, "reorder_level": 5, "initial_stock": 50, "initial_stock_rate": 500, "vendor_id": 4815000000044080, "vendor_name": "Molly", "stock_on_hand": 50, "available_stock": 2, "actual_available_stock": 2, "sku": "SK123", "upc": 111111111111, "ean": 111111111112, "isbn": 111111111113, "part_number": 111111111114, "attribute_option_id1": 4815000000044214, "attribute_option_name1": "Small", "image_id": 2077500000000002000, "image_name": "bag_s.jpg", "purchase_description": "Purchase description", "image_type": "jpg", "item_tax_preferences": [ { "tax_id": 4815000000044043, "tax_specification": "intra" } ], "hsn_or_sac": 85423100 } }
ARGUMENTS
|
group_id
Optional
Unique ID generated by the server for the group to which the item belongs, if any. This is used as an identifier.
group_name
Optional
Name of product group
unit
Optional
Unit of measurement for the item.
documents
Optional
List of all the documents associated with the item
item_type
Optional
Item type can be
inventory, sales, purchases or sales_and_purchases. If item is associated with a group, then type should be inventory.
product_type
Optional
Type of the product. It can be
goods or service
is_taxable
Optional
Boolean to track the taxability of the item.
tax_id
Optional
Unique ID generated by the server for the tax associated with the item. This is used a unique identifier.
description
Optional
Description of the Item.
purchase_account_id
Optional
Unique ID generated by the server for the Purchase account.
inventory_account_id
Optional
Uniquq ID generated by the server for the Inventory account.
attribute_name1
Optional
Name of the attribute present in the Item Group.
name
Required
Name of the Item.
rate
Optional
Sales price of the Item.
purchase_rate
Optional
Purchase price of the Item.
reorder_level
Optional
Reorder level of the item.
initial_stock
Optional
The opening stock of the item.
initial_stock_rate
Optional
The opening stock value of the item.
vendor_id
Optional
Unique ID generated by the server for the Vendor. This is used as an identifier.
vendor_name
Optional
Name of the preferred Vendor for purchasing this item.
sku
Optional
The Stock Keeeping Unit (SKU) of an item. This is unique for every item in the Inventory.
upc
Optional
The 12 digit Unique Product Code (UPC) of the item.
ean
Optional
Unique EAN value for the Item.
isbn
Optional
Unique ISBN value for the Item.
part_number
Optional
Part Number of the Item.
attribute_option_name1
Optional
Name of the attribute's option.
purchase_description
Optional
The description for the purchase information. This will be displayed to the vendor in your purchase order.
item_tax_preferences
India Edition only
Optional
tax_id
Optional
Unique ID generated by the server for the tax associated with the item. This is used a unique identifier.
tax_specification
India Edition only
Optional
Type of tax. It can be
intra or inter
hsn_or_sac
India Edition Only
Optional
HSN Code of the item
|
Retrieve an item
Fetches the details for an existing item. oauthscope : ZohoInventory.items.READ
GET /items/{item_id}
Request Example
$ curl https://inventory.zoho.com/api/v1/items/{item_id}?organization_id=10234695 -H "Authorization: Zoho-oauthtoken 1000.41d9f2cfbd1b7a8f9e314b7aff7bc2d1.8fcc9810810a216793f385b9dd6e125f" -H "Content-Type: application/x-www-form-urlencoded;charset=UTF-8"
Response Example
HTTP/1.1 200 OK Content-Type:application/json;charset=UTF-8 { "code": 0, "message": "success", "item": { "group_id": 4815000000044220, "group_name": "Bags", "item_id": 4815000000044208, "name": "Bags-small", "unit": "qty", "item_type": "inventory", "product_type": "goods", "is_taxable": true, "tax_id": 4815000000044043, "description": "description", "tax_name": "Sales", "tax_percentage": 12, "tax_type": "Service Tax", "purchase_account_id": 4815000000035003, "purchase_account_name": "Cost of Goods Sold", "account_name": "Sales", "inventory_account_id": 4815000000035001, "attribute_id1": 4815000000044112, "attribute_name1": "Small", "status": "active", "rate": 6, "pricebook_rate": 6, "purchase_rate": 6, "reorder_level": 5, "initial_stock": 50, "initial_stock_rate": 500, "vendor_id": 4815000000044080, "vendor_name": "Molly", "stock_on_hand": 50, "available_stock": 2, "actual_available_stock": 2, "sku": "SK123", "upc": 111111111111, "ean": 111111111112, "isbn": 111111111113, "part_number": 111111111114, "attribute_option_id1": 4815000000044214, "attribute_option_name1": "Small", "image_id": 2077500000000002000, "image_name": "bag_s.jpg", "purchase_description": "Purchase description", "image_type": "jpg", "item_tax_preferences": [ { "tax_id": 4815000000044043, "tax_specification": "intra" } ], "hsn_or_sac": 85423100 } }
Update an item
Update the details of an item. oauthscope : ZohoInventory.items.UPDATE
PUT /items/{item_id}
Request Example
$ curl https://inventory.zoho.com/api/v1/items/{item_id}?organization_id=10234695 -X PUT -H "Authorization: Zoho-oauthtoken 1000.41d9f2cfbd1b7a8f9e314b7aff7bc2d1.8fcc9810810a216793f385b9dd6e125f" -H "Content-Type: application/x-www-form-urlencoded;charset=UTF-8" -F 'JSONString="{ "group_id": 4815000000044220, "group_name": "Bags", "unit": "qty", "item_type": "inventory", "product_type": "goods", "is_taxable": true, "tax_id": 4815000000044043, "description": "description", "tax_name": "Sales", "tax_percentage": 12, "tax_type": "Service Tax", "purchase_account_id": 4815000000035003, "purchase_account_name": "Cost of Goods Sold", "account_name": "Sales", "inventory_account_id": 4815000000035001, "attribute_id1": 4815000000044112, "attribute_name1": "Small", "status": "active", "name": "Bags-small", "rate": 6, "pricebook_rate": 6, "purchase_rate": 6, "reorder_level": 5, "initial_stock": 50, "initial_stock_rate": 500, "vendor_id": 4815000000044080, "vendor_name": "Molly", "stock_on_hand": 50, "sku": "SK123", "upc": 111111111111, "ean": 111111111112, "isbn": 111111111113, "part_number": 111111111114, "attribute_option_id1": 4815000000044214, "attribute_option_name1": "Small", "image_id": 2077500000000002000, "image_name": "bag_s.jpg", "purchase_description": "Purchase description", "image_type": "jpg", "item_tax_preferences": [ { "tax_id": 4815000000044043, "tax_specification": "intra" } ], "hsn_or_sac": 85423100 }"'
Response Example
HTTP/1.1 200 OK Content-Type:application/json;charset=UTF-8 { "code": 0, "message": "Item details have been updated", "item": { "group_id": 4815000000044220, "group_name": "Bags", "item_id": 4815000000044208, "name": "Bags-small", "unit": "qty", "item_type": "inventory", "product_type": "goods", "is_taxable": true, "tax_id": 4815000000044043, "description": "description", "tax_name": "Sales", "tax_percentage": 12, "tax_type": "Service Tax", "purchase_account_id": 4815000000035003, "purchase_account_name": "Cost of Goods Sold", "account_name": "Sales", "inventory_account_id": 4815000000035001, "attribute_id1": 4815000000044112, "attribute_name1": "Small", "status": "active", "rate": 6, "pricebook_rate": 6, "purchase_rate": 6, "reorder_level": 5, "initial_stock": 50, "initial_stock_rate": 500, "vendor_id": 4815000000044080, "vendor_name": "Molly", "stock_on_hand": 50, "available_stock": 2, "actual_available_stock": 2, "sku": "SK123", "upc": 111111111111, "ean": 111111111112, "isbn": 111111111113, "part_number": 111111111114, "attribute_option_id1": 4815000000044214, "attribute_option_name1": "Small", "image_id": 2077500000000002000, "image_name": "bag_s.jpg", "purchase_description": "Purchase description", "image_type": "jpg", "item_tax_preferences": [ { "tax_id": 4815000000044043, "tax_specification": "intra" } ], "hsn_or_sac": 85423100 } }
ARGUMENTS
|
group_id
Optional
Unique ID generated by the server for the group to which the item belongs, if any. This is used as an identifier.
group_name
Optional
Name of product group
unit
Optional
Unit of measurement for the item.
item_type
Optional
Item type can be
inventory, sales, purchases or sales_and_purchases. If item is associated with a group, then type should be inventory.
product_type
Optional
Type of the product. It can be
goods or service
is_taxable
Optional
Boolean to track the taxability of the item.
tax_id
Optional
Unique ID generated by the server for the tax associated with the item. This is used a unique identifier.
description
Optional
Description of the Item.
tax_name
Optional
Name of the tax applied on the Item Group.
tax_percentage
Optional
Percentage of the Tax
tax_type
Optional
Type of the Tax.
purchase_account_id
Optional
Unique ID generated by the server for the Purchase account.
purchase_account_name
Optional
Name of the Purchase Account
account_name
Optional
Name of the Sales Account.
inventory_account_id
Optional
Uniquq ID generated by the server for the Inventory account.
attribute_id1
Optional
Unique ID used by the server. This is used as an identifier.
attribute_name1
Optional
Name of the attribute present in the Item Group.
status
Optional
Status of the Item Group.
source
Optional
The source of the Item Group.
name
Required
Name of the Item.
rate
Optional
Sales price of the Item.
pricebook_rate
Optional
Pricelist rate applied on the item.
purchase_rate
Optional
Purchase price of the Item.
reorder_level
Optional
Reorder level of the item.
initial_stock
Optional
The opening stock of the item.
initial_stock_rate
Optional
The opening stock value of the item.
vendor_id
Optional
Unique ID generated by the server for the Vendor. This is used as an identifier.
vendor_name
Optional
Name of the preferred Vendor for purchasing this item.
stock_on_hand
Optional
Stock available for a particular item.
sku
Optional
The Stock Keeeping Unit (SKU) of an item. This is unique for every item in the Inventory.
upc
Optional
The 12 digit Unique Product Code (UPC) of the item.
ean
Optional
Unique EAN value for the Item.
isbn
Optional
Unique ISBN value for the Item.
part_number
Optional
Part Number of the Item.
attribute_option_id1
Optional
Unique ID generated by the server for the attribute's options. This is used as an identifier.
attribute_option_name1
Optional
Name of the attribute's option.
image_id
Optional
Unique ID generated by the server for the item image. This is used as an identifier.
image_name
Optional
Image name of the Item.
purchase_description
Optional
The description for the purchase information. This will be displayed to the vendor in your purchase order.
image_type
Optional
Type of the image i.e., its file format.
item_tax_preferences
India Edition only
Optional
tax_id
Optional
Unique ID generated by the server for the tax associated with the item. This is used a unique identifier.
tax_specification
India Edition only
Optional
Type of tax. It can be
intra or inter
hsn_or_sac
India Edition Only
Optional
HSN Code of the item
|
Delete an item
Deletes an existing item from Zoho Inventory. oauthscope : ZohoInventory.items.DELETE
DELETE /items/{item_id}
Request Example
$ curl https://inventory.zoho.com/api/v1/items/{item_id}?organization_id=10234695 -X DELETE -H "Authorization: Zoho-oauthtoken 1000.41d9f2cfbd1b7a8f9e314b7aff7bc2d1.8fcc9810810a216793f385b9dd6e125f" -H "Content-Type: application/x-www-form-urlencoded;charset=UTF-8"
Response Example
HTTP/1.1 200 OK Content-Type:application/json;charset=UTF-8 { "code": 0, "message": "The item has been deleted." }
Delete an item image
Deletes the image associated for an item in Zoho Inventory. oauthscope : ZohoInventory.items.DELETE
DELETE /items/{item_id}/image
Request Example
$ curl https://inventory.zoho.com/api/v1/items/{item_id}/image?organization_id=10234695 -X DELETE -H "Authorization: Zoho-oauthtoken 1000.41d9f2cfbd1b7a8f9e314b7aff7bc2d1.8fcc9810810a216793f385b9dd6e125f" -H "Content-Type: application/x-www-form-urlencoded;charset=UTF-8"
Response Example
HTTP/1.1 200 OK Content-Type:application/json;charset=UTF-8 { "code": 0, "message": "The item image has been deleted." }
List all the items
Lists all the items present in Zoho Inventory. oauthscope : ZohoInventory.items.READ
GET /items
Request Example
$ curl https://inventory.zoho.com/api/v1/items?organization_id=10234695 -H "Authorization: Zoho-oauthtoken 1000.41d9f2cfbd1b7a8f9e314b7aff7bc2d1.8fcc9810810a216793f385b9dd6e125f" -H "Content-Type: application/x-www-form-urlencoded;charset=UTF-8"
Response Example
HTTP/1.1 200 OK Content-Type:application/json;charset=UTF-8 { "code": 0, "message": "success", "items": [ { "group_id": 4815000000044220, "group_name": "Bags", "item_id": 4815000000044208, "name": "Bags-small", "status": "active", "is_linked_with_zohocrm": false, "item_type": "inventory", "description": "description", "rate": 6, "is_taxable": true, "tax_id": 4815000000044043, "tax_name": "Sales", "tax_percentage": 12, "purchase_description": "Purchase description", "purchase_rate": 6, "is_combo_product": false, "product_type": "goods", "attribute_id1": 4815000000044112, "attribute_name1": "Small", "reorder_level": 5, "stock_on_hand": 50, "available_stock": 2, "actual_available_stock": 2, "sku": "SK123", "upc": 111111111111, "ean": 111111111112, "isbn": 111111111113, "part_number": 111111111114, "attribute_option_id1": 4815000000044214, "attribute_option_name1": "Small", "image_name": "bag_s.jpg", "image_type": "jpg", "created_time": "2013-01-24", "last_modified_time": "2013-01-24", "hsn_or_sac": 85423100 }, {...}, {...} ] }
Mark as active
Changes the status of an item to active. oauthscope : ZohoInventory.items.CREATE
POST /items/{item_id}/active
Request Example
$ curl https://inventory.zoho.com/api/v1/items/{item_id}/active?organization_id=10234695 -X POST -H "Authorization: Zoho-oauthtoken 1000.41d9f2cfbd1b7a8f9e314b7aff7bc2d1.8fcc9810810a216793f385b9dd6e125f" -H "Content-Type: application/x-www-form-urlencoded;charset=UTF-8"
Response Example
HTTP/1.1 200 OK Content-Type:application/json;charset=UTF-8 { "code": 0, "message": "The item has been marked as Active." }
Mark as inactive
Mark an item as inactive. oauthscope : ZohoInventory.items.CREATE
POST /items/{item_id}/inactive
Request Example
$ curl https://inventory.zoho.com/api/v1/items/{item_id}/inactive?organization_id=10234695 -X POST -H "Authorization: Zoho-oauthtoken 1000.41d9f2cfbd1b7a8f9e314b7aff7bc2d1.8fcc9810810a216793f385b9dd6e125f" -H "Content-Type: application/x-www-form-urlencoded;charset=UTF-8"
Response Example
HTTP/1.1 200 OK Content-Type:application/json;charset=UTF-8 { "code": 0, "message": "The item has been marked as Inactive." }
Composite Items
A form or version of an composite item that differs in some respect from other forms of the same or from a standard. You can create your composite items by associating multiple items and their respective quantities.
Example
{ "name": "Combo of Apple IPhone and Smartwatch", "sku": "SKUIS", "unit": "units", "description": "Just a sample description", "purchase_description": "Composite item purchase description", "composite_item_id": 504366000000053250, "rate": 85000, "pricebook_rate": 85000, "initial_stock": 2, "initial_stock_rate": 30000, "upc": 746325287436, "ean": 5789414385764, "isbn": 368302334, "part_number": "JHFKE7GK7", "status": "active", "is_combo_product": true, "item_type": "inventory", "is_taxable": true, "reorder_level": 1, "vendor_id": 504366000000053250, "line_item_id": 504366000000053250, "quantity": 1, "item_id": 4815000000044208, "tax_id": 504366000000053100, "tax_name": "VAT", "tax_percentage": 13, "tax_type": "tax", "custom_fields": [ { "custom_field_id": 504366000000053400, "value": "GBGD078", "index": 1, "label": "VAT ID" } ], "available_stock": 2, "actual_available_stock": 2, "stock_on_hand": 2, "mapped_items": [ { "line_item_id": 504366000000053250, "item_id": 4815000000044208, "name": "Combo of Apple IPhone and Smartwatch", "rate": 85000, "purchase_rate": 30000, "sku": "SKUIS", "image_id": 8408722000000019000, "image_name": "img1.jpg", "purchase_description": "Composite item purchase description", "image_type": "jpg", "unit": "units", "is_combo_product": true, "description": "Just a sample description", "quantity": 1, "stock_on_hand": 2, "available_stock": 2, "actual_available_stock": 2 } ], "item_tax_preferences": [ { "tax_id": 504366000000053100, "tax_specification": "intra" } ], "hsn_or_sac": 85423100, "is_completed": true }
Attribute
|
name
string
Name of the composite item
sku
string
Stock Keeping Unit value of the item. It should be unique throughout the product
unit
string
Unit of Item
description
string
Sample Description.
purchase_description
string
Purchase description of the item
composite_item_id
long
Unique ID generated for the composite item by the server. This is used as identifier
rate
double
Selling price of the item
pricebook_rate
double
Price list applied on the item's selling price.
initial_stock
double
Initial stock of item
initial_stock_rate
double
Average purchase price of initial stock. This is required for FIFO cost lot tracking and inventory valuation
upc
long
Unique Product Code, 12 digit unique code of the item
ean
long
European Article Number, 13 digit barcode number of the item
isbn
long
International Standard Book Number, 13 digit unique commercial book identifier barcode of the item
part_number
string
MPN - Manufacturing Part Number, unambiguously identifies a part design
status
string
Status of the Item
is_combo_product
boolean
Defines whether the item is composite or not
true for composite items
item_type
string
Type of item
Always inventory
is_taxable
boolean
To check if the item is taxable or not
true if the item is taxable, else false
reorder_level
double
Reorder point of the item
vendor_id
long
Unique ID generated by the server for preferred vendor to buy this composite item
line_item_id
long
Unique ID generated by the server for mapping the associated item with composite item
quantity
double
Quantity of item associated with the composite item
item_id
long
Unique ID generated by the server for the Item. This is used as an identifier.
tax_id
long
Unique ID generated by the server for the tax .
tax_name
string
Name of the tax applied on selling this item
tax_percentage
double
Percentage at which the item is taxed
tax_type
string
Type of tax. It can either Tax or Group Tax
custom_fields
list
Custom fields are used to add more information about the item
custom_field_id
long
Unique ID generated by the server for the custom field.
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.
available_stock
decimal
Stock based on Shipments and Receives
actual_available_stock
decimal
Stock based on Shipments and Receives minus ordered stock
stock_on_hand
decimal
Stock based on Invoices and Bills
asset_value
decimal
value of the composite items based on purchase rate
mapped_items
list
Items that are associated with the composite item
line_item_id
long
Unique ID generated by the server for mapping the associated item with composite item
item_id
long
Unique ID generated by the server for the Item. This is used as an identifier.
name
string
Name of the composite item
rate
double
Selling price of the item
purchase_rate
double
Buying price of the item
sku
string
Stock Keeping Unit value of the item. It should be unique throughout the product
image_id
long
Unique identifier generated by the server for item image
image_name
string
Name of the image
purchase_description
string
Purchase description of the item
image_type
string
Type of the image
Only images with gif,png,jpeg,jpg,bmp extensions are allowed
unit
string
Unit of Item
is_combo_product
boolean
Defines whether the item is composite or not
true for composite items
description
string
Sample Description.
quantity
double
Quantity of item associated with the composite item
stock_on_hand
decimal
Stock based on Invoices and Bills
available_stock
decimal
Stock based on Shipments and Receives
actual_available_stock
decimal
Stock based on Shipments and Receives minus ordered stock
item_tax_preferences
India Edition only
list
tax_id
long
Unique ID generated by the server for the tax .
tax_specification
India Edition only
string
Type of tax. It can be
intra or inter
hsn_or_sac
India Edition Only
string
HSN Code of the item
is_completed
boolean
Denotes the status of the bundle. Currently, this has to be true since we didnt support any other status as of now.
|
Creating a Composite Item
A new composite item can be created after creating items that we want to associcate with composite item. User can attach image for composite item by calling Different API 'https://inventory.zoho.com/api/v1/compositeitems/{composite_item_id}/image', passing form-data parameter image i.e. -F image=bag_s.jpg oauthscope : ZohoInventory.compositeitems.CREATE
POST /compositeitems
Request Example
$ curl https://inventory.zoho.com/api/v1/compositeitems?organization_id=10234695 -X POST -H "Authorization: Zoho-oauthtoken 1000.41d9f2cfbd1b7a8f9e314b7aff7bc2d1.8fcc9810810a216793f385b9dd6e125f" -H "Content-Type: application/x-www-form-urlencoded;charset=UTF-8" -F 'JSONString="{ "name": "Combo of Apple IPhone and Smartwatch", "mapped_items": [ { "quantity": 1, "item_id": 4815000000044208, "line_item_id": 504366000000053250 } ], "description": "Just a sample description", "is_combo_product": true, "vendor_id": 504366000000053250, "purchase_rate": 30000, "purchase_description": "Composite item purchase description", "initial_stock": 2, "initial_stock_rate": 30000, "tax_id": 504366000000053100, "sku": "SKUIS", "isbn": 368302334, "ean": 5789414385764, "part_number": "JHFKE7GK7", "reorder_level": 1, "unit": "units", "upc": 746325287436, "item_type": "inventory", "rate": 85000, "custom_fields": [ { "custom_field_id": 504366000000053400, "value": "GBGD078" } ], "account_id": 504366000000000400, "purchase_account_id": 504366000000034000, "inventory_account_id": 504366000000034000, "item_tax_preferences": [ { "tax_id": 504366000000053100, "tax_specification": "intra" } ], "hsn_or_sac": 85423100 }"'
Response Example
HTTP/1.1 201 Created Content-Type:application/json;charset=UTF-8 { "code": 0, "message": "The item has been added.", "composite_item": { "composite_item_id": 504366000000053250, "name": "Combo of Apple IPhone and Smartwatch", "unit": "units", "tax_id": 504366000000053100, "description": "Just a sample description", "tax_name": "VAT", "tax_percentage": 13, "tax_type": "tax", "purchase_account_id": 504366000000034000, "purchase_account_name": "Cost of Goods Sold", "account_id": 504366000000000400, "account_name": "sales", "inventory_account_id": 504366000000034000, "inventory_account_name": "Inventory Asset", "status": "active", "source": "user", "is_combo_product": true, "item_type": "inventory", "rate": 85000, "pricebook_rate": 85000, "purchase_rate": 30000, "reorder_level": 1, "initial_stock": 2, "initial_stock_rate": 30000, "vendor_id": 504366000000053250, "vendor_name": "Mr. vendor combo", "stock_on_hand": 2, "available_stock": 2, "actual_available_stock": 2, "sku": "SKUIS", "upc": 746325287436, "ean": 5789414385764, "isbn": 368302334, "part_number": "JHFKE7GK7", "image_id": 8408722000000019000, "image_name": "img1.jpg", "purchase_description": "Composite item purchase description", "custom_fields": [ { "custom_field_id": 504366000000053400, "value": "GBGD078", "index": 1, "label": "VAT ID" } ], "mapped_items": [ { "line_item_id": 504366000000053250, "item_id": 4815000000044208, "name": "Combo of Apple IPhone and Smartwatch", "rate": 85000, "purchase_rate": 30000, "sku": "SKUIS", "image_id": 8408722000000019000, "image_name": "img1.jpg", "purchase_description": "Composite item purchase description", "image_type": "jpg", "unit": "units", "is_combo_product": true, "description": "Just a sample description", "quantity": 1, "stock_on_hand": 2, "available_stock": 2, "actual_available_stock": 2 } ], "item_tax_preferences": [ { "tax_id": 504366000000053100, "tax_specification": "intra" } ], "hsn_or_sac": 85423100 } }
ARGUMENTS
|
name
Required
Name of the composite item
mapped_items
Required
Items that are associated with the composite item
quantity
Optional
Quantity of item associated with the composite item
item_id
Required
Unique ID generated by the server for the Item. This is used as an identifier.
line_item_id
Optional
Unique ID generated by the server for mapping the associated item with composite item
description
Optional
Sample Description.
is_combo_product
Optional
Defines whether the item is composite or not
true for composite items
vendor_id
Optional
Unique ID generated by the server for preferred vendor to buy this composite item
purchase_rate
Optional
Buying price of the item
purchase_description
Optional
Purchase description of the item
initial_stock
Optional
Initial stock of item
initial_stock_rate
Optional
Average purchase price of initial stock. This is required for FIFO cost lot tracking and inventory valuation
tax_id
Optional
Unique ID generated by the server for the tax .
sku
Required
Stock Keeping Unit value of the item. It should be unique throughout the product
isbn
Optional
International Standard Book Number, 13 digit unique commercial book identifier barcode of the item
ean
Optional
European Article Number, 13 digit barcode number of the item
part_number
Optional
MPN - Manufacturing Part Number, unambiguously identifies a part design
reorder_level
Optional
Reorder point of the item
unit
Optional
Unit of Item
upc
Optional
Unique Product Code, 12 digit unique code of the item
item_type
Required
Type of item
Always inventory
rate
Required
Selling price of the item
custom_fields
Optional
Custom fields are used to add more information about the item
custom_field_id
Optional
Unique ID generated by the server for the custom field.
value
Optional
Value of the custom field.
account_id
Optional
Unique ID generated by the server for the type of sale of this item
purchase_account_id
Optional
Unique ID generated by the server for the type of purchase
inventory_account_id
Optional
Unique ID generated by the server for the type of inventory for this item
item_tax_preferences
India Edition only
Optional
tax_id
Optional
Unique ID generated by the server for the tax .
tax_specification
India Edition only
Optional
Type of tax. It can be
intra or inter
hsn_or_sac
India Edition Only
Optional
HSN Code of the item
|
Retrieving a Composite Item
Retrieving details of an existing compostie item. oauthscope : ZohoInventory.compositeitems.READ
GET /compositeitems/{:composite_item_id}
Request Example
$ curl https://inventory.zoho.com/api/v1/compositeitems/{:composite_item_id}?organization_id=10234695 -H "Authorization: Zoho-oauthtoken 1000.41d9f2cfbd1b7a8f9e314b7aff7bc2d1.8fcc9810810a216793f385b9dd6e125f" -H "Content-Type: application/x-www-form-urlencoded;charset=UTF-8"
Response Example
HTTP/1.1 200 OK Content-Type:application/json;charset=UTF-8 { "code": 0, "message": "success", "composite_item_id": 504366000000053250, "name": "Combo of Apple IPhone and Smartwatch", "status": "active", "source": "user", "unit": "units", "tax_id": 504366000000053100, "description": "Just a sample description", "tax_name": "VAT", "tax_percentage": 13, "tax_type": "tax", "purchase_account_id": 504366000000034000, "purchase_account_name": "Cost of Goods Sold", "account_id": 504366000000000400, "account_name": "sales", "inventory_account_id": 504366000000034000, "inventory_account_name": "Inventory Asset", "is_combo_product": true, "item_type": "inventory", "rate": 85000, "pricebook_rate": 85000, "purchase_rate": 30000, "reorder_level": 1, "initial_stock": 2, "initial_stock_rate": 30000, "vendor_id": 504366000000053250, "vendor_name": "Mr. vendor combo", "stock_on_hand": 2, "available_stock": 2, "actual_available_stock": 2, "sku": "SKUIS", "upc": 746325287436, "ean": 5789414385764, "isbn": 368302334, "part_number": "JHFKE7GK7", "image_id": 8408722000000019000, "image_name": "img1.jpg", "purchase_description": "Composite item purchase description", "custom_fields": [ { "custom_field_id": 504366000000053400, "value": "GBGD078", "index": 1, "label": "VAT ID" } ], "mapped_items": [ { "line_item_id": 504366000000053250, "item_id": 4815000000044208, "name": "Combo of Apple IPhone and Smartwatch", "rate": 85000, "purchase_rate": 30000, "sku": "SKUIS", "image_id": 8408722000000019000, "image_name": "img1.jpg", "purchase_description": "Composite item purchase description", "image_type": "jpg", "unit": "units", "is_combo_product": true, "description": "Just a sample description", "quantity": 1, "stock_on_hand": 2, "available_stock": 2, "actual_available_stock": 2 } ], "item_tax_preferences": [ { "tax_id": 504366000000053100, "tax_specification": "intra" } ], "hsn_or_sac": 85423100 }
Updating a composite item
Updating details of an existing composite item. oauthscope : ZohoInventory.compositeitems.UPDATE
PUT /compositeitems/{:composite_item_id}
Request Example
$ curl https://inventory.zoho.com/api/v1/compositeitems/{:composite_item_id}?organization_id=10234695 -X PUT -H "Authorization: Zoho-oauthtoken 1000.41d9f2cfbd1b7a8f9e314b7aff7bc2d1.8fcc9810810a216793f385b9dd6e125f" -H "Content-Type: application/x-www-form-urlencoded;charset=UTF-8" -F 'JSONString="{ "composite_item_id": 504366000000053250, "name": "Combo of Apple IPhone and Smartwatch", "unit": "units", "tax_id": 504366000000053100, "description": "Just a sample description", "tax_name": "VAT", "tax_percentage": 13, "tax_type": "tax", "purchase_account_id": 504366000000034000, "purchase_account_name": "Cost of Goods Sold", "account_id": 504366000000000400, "account_name": "sales", "inventory_account_id": 504366000000034000, "inventory_account_name": "Inventory Asset", "status": "active", "source": "user", "is_combo_product": true, "item_type": "inventory", "rate": 85000, "pricebook_rate": 85000, "purchase_rate": 30000, "reorder_level": 1, "initial_stock": 2, "initial_stock_rate": 30000, "vendor_id": 504366000000053250, "vendor_name": "Mr. vendor combo", "stock_on_hand": 2, "available_stock": 2, "actual_available_stock": 2, "sku": "SKUIS", "upc": 746325287436, "ean": 5789414385764, "isbn": 368302334, "part_number": "JHFKE7GK7", "image_id": 8408722000000019000, "image_name": "img1.jpg", "purchase_description": "Composite item purchase description", "custom_fields": [ { "custom_field_id": 504366000000053400, "value": "GBGD078", "index": 1, "label": "VAT ID" } ], "mapped_items": [ { "line_item_id": 504366000000053250, "item_id": 4815000000044208, "name": "Combo of Apple IPhone and Smartwatch", "rate": 85000, "purchase_rate": 30000, "sku": "SKUIS", "image_id": 8408722000000019000, "image_name": "img1.jpg", "purchase_description": "Composite item purchase description", "image_type": "jpg", "unit": "units", "is_combo_product": true, "description": "Just a sample description", "quantity": 1, "stock_on_hand": 2, "available_stock": 2, "actual_available_stock": 2 } ], "item_tax_preferences": [ { "tax_id": 504366000000053100, "tax_specification": "intra" } ], "hsn_or_sac": 85423100 }"'
Response Example
HTTP/1.1 200 OK Content-Type:application/json;charset=UTF-8 { "code": 0, "message": "Item details have been saved.", "composite_item": { "composite_item_id": 504366000000053250, "name": "Combo of Apple IPhone and Smartwatch", "unit": "units", "tax_id": 504366000000053100, "description": "Just a sample description", "tax_name": "VAT", "tax_percentage": 13, "tax_type": "tax", "purchase_account_id": 504366000000034000, "purchase_account_name": "Cost of Goods Sold", "account_id": 504366000000000400, "account_name": "sales", "inventory_account_id": 504366000000034000, "inventory_account_name": "Inventory Asset", "status": "active", "source": "user", "is_combo_product": true, "item_type": "inventory", "rate": 85000, "pricebook_rate": 85000, "purchase_rate": 30000, "reorder_level": 1, "initial_stock": 2, "initial_stock_rate": 30000, "vendor_id": 504366000000053250, "vendor_name": "Mr. vendor combo", "stock_on_hand": 2, "available_stock": 2, "actual_available_stock": 2, "sku": "SKUIS", "upc": 746325287436, "ean": 5789414385764, "isbn": 368302334, "part_number": "JHFKE7GK7", "image_id": 8408722000000019000, "image_name": "img1.jpg", "purchase_description": "Composite item purchase description", "custom_fields": [ { "custom_field_id": 504366000000053400, "value": "GBGD078", "index": 1, "label": "VAT ID" } ], "mapped_items": [ { "line_item_id": 504366000000053250, "item_id": 4815000000044208, "name": "Combo of Apple IPhone and Smartwatch", "rate": 85000, "purchase_rate": 30000, "sku": "SKUIS", "image_id": 8408722000000019000, "image_name": "img1.jpg", "purchase_description": "Composite item purchase description", "image_type": "jpg", "unit": "units", "is_combo_product": true, "description": "Just a sample description", "quantity": 1, "stock_on_hand": 2, "available_stock": 2, "actual_available_stock": 2 } ], "item_tax_preferences": [ { "tax_id": 504366000000053100, "tax_specification": "intra" } ], "hsn_or_sac": 85423100 } }
ARGUMENTS
|
composite_item_id
Optional
Unique ID generated for the composite item by the server. This is used as identifier
name
Required
Name of the composite item
unit
Optional
Unit of Item
tax_id
Optional
Unique ID generated by the server for the tax .
description
Optional
Sample Description.
tax_name
Optional
Name of the tax applied on selling this item
tax_percentage
Optional
Percentage at which the item is taxed
tax_type
Optional
Type of tax. It can either Tax or Group Tax
purchase_account_id
Optional
Unique ID generated by the server for the type of purchase
purchase_account_name
Optional
Type of purchase under which the composite item was bought
account_id
Optional
Unique ID generated by the server for the type of sale of this item
account_name
Optional
Type of sale under which the composite item is sold
inventory_account_id
Optional
Unique ID generated by the server for the type of inventory for this item
inventory_account_name
Optional
Name of inventory type
status
Optional
Status of the Item
source
Optional
source
is_combo_product
Optional
Defines whether the item is composite or not
true for composite items
item_type
Required
Type of item
Always inventory
rate
Required
Selling price of the item
pricebook_rate
Optional
Price list applied on the item's selling price.
purchase_rate
Optional
Buying price of the item
reorder_level
Optional
Reorder point of the item
initial_stock
Optional
Initial stock of item
initial_stock_rate
Optional
Average purchase price of initial stock. This is required for FIFO cost lot tracking and inventory valuation
vendor_id
Optional
Unique ID generated by the server for preferred vendor to buy this composite item
vendor_name
Optional
Name of the preferred vendor
stock_on_hand
Optional
Stock based on Invoices and Bills
asset_value
Optional
value of the composite items based on purchase rate
available_stock
Optional
Stock based on Shipments and Receives
actual_available_stock
Optional
Stock based on Shipments and Receives minus ordered stock
sku
Required
Stock Keeping Unit value of the item. It should be unique throughout the product
upc
Optional
Unique Product Code, 12 digit unique code of the item
ean
Optional
European Article Number, 13 digit barcode number of the item
isbn
Optional
International Standard Book Number, 13 digit unique commercial book identifier barcode of the item
part_number
Optional
MPN - Manufacturing Part Number, unambiguously identifies a part design
image_id
Optional
Unique identifier generated by the server for item image
image_name
Optional
Name of the image
purchase_description
Optional
Purchase description of the item
custom_fields
Optional
Custom fields are used to add more information about the item
custom_field_id
Optional
Unique ID generated by the server for the custom field.
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.
mapped_items
Required
Items that are associated with the composite item
line_item_id
Optional
Unique ID generated by the server for mapping the associated item with composite item
item_id
Optional
Unique ID generated by the server for the Item. This is used as an identifier.
name
Required
Name of the composite item
rate
Required
Selling price of the item
purchase_rate
Optional
Buying price of the item
sku
Required
Stock Keeping Unit value of the item. It should be unique throughout the product
image_id
Optional
Unique identifier generated by the server for item image
image_name
Optional
Name of the image
purchase_description
Optional
Purchase description of the item
image_type
Optional
Type of the image
Only images with gif,png,jpeg,jpg,bmp extensions are allowed
unit
Optional
Unit of Item
is_combo_product
Optional
Defines whether the item is composite or not
true for composite items
description
Optional
Sample Description.
quantity
Optional
Quantity of item associated with the composite item
stock_on_hand
Optional
Stock based on Invoices and Bills
available_stock
Optional
Stock based on Shipments and Receives
actual_available_stock
Optional
Stock based on Shipments and Receives minus ordered stock
item_tax_preferences
India Edition only
Optional
tax_id
Optional
Unique ID generated by the server for the tax .
tax_specification
India Edition only
Optional
Type of tax. It can be
intra or inter
hsn_or_sac
India Edition Only
Optional
HSN Code of the item
|
Deleting a Composite Item
Deleting an existing Composite Item. oauthscope : ZohoInventory.compositeitems.DELETE
DELETE /compositeitems/{:composite_item_id}
Request Example
$ curl https://inventory.zoho.com/api/v1/compositeitems/{:composite_item_id}?organization_id=10234695 -X DELETE -H "Authorization: Zoho-oauthtoken 1000.41d9f2cfbd1b7a8f9e314b7aff7bc2d1.8fcc9810810a216793f385b9dd6e125f" -H "Content-Type: application/x-www-form-urlencoded;charset=UTF-8"
Response Example
HTTP/1.1 200 OK Content-Type:application/json;charset=UTF-8 { "code": 0, "message": "The item has been deleted." }
Mark as Active
Changing status of an existing composite item to active. oauthscope : ZohoInventory.compositeitems.CREATE
POST /compositeitems/{composite_item_id}/active
Request Example
$ curl https://inventory.zoho.com/api/v1/compositeitems/{composite_item_id}/active?organization_id=10234695 -X POST -H "Authorization: Zoho-oauthtoken 1000.41d9f2cfbd1b7a8f9e314b7aff7bc2d1.8fcc9810810a216793f385b9dd6e125f" -H "Content-Type: application/x-www-form-urlencoded;charset=UTF-8"
Response Example
HTTP/1.1 200 OK Content-Type:application/json;charset=UTF-8 { "code": 0, "message": "Re-activation complete! The item is back in business!" }
Mark as Inactive
Changing status of an existing composite item to inactive. oauthscope : ZohoInventory.compositeitems.CREATE
POST /compositeitems/{:composite_item_id}/inactive
Request Example
$ curl https://inventory.zoho.com/api/v1/compositeitems/{:composite_item_id}/inactive?organization_id=10234695 -X POST -H "Authorization: Zoho-oauthtoken 1000.41d9f2cfbd1b7a8f9e314b7aff7bc2d1.8fcc9810810a216793f385b9dd6e125f" -H "Content-Type: application/x-www-form-urlencoded;charset=UTF-8"
Response Example
HTTP/1.1 200 OK Content-Type:application/json;charset=UTF-8 { "code": 0, "message": "The item has been marked as inactive." }
List All Composite Items
List of all composite items. oauthscope : ZohoInventory.compositeitems.READ
GET /compositeitems
Request Example
$ curl https://inventory.zoho.com/api/v1/compositeitems?organization_id=10234695 -H "Authorization: Zoho-oauthtoken 1000.41d9f2cfbd1b7a8f9e314b7aff7bc2d1.8fcc9810810a216793f385b9dd6e125f" -H "Content-Type: application/x-www-form-urlencoded;charset=UTF-8"
Response Example
HTTP/1.1 200 OK Content-Type:application/json;charset=UTF-8 { "code": 0, "message": "success", "composite_items": [ { "composite_item_id": 504366000000053250, "name": "Combo of Apple IPhone and Smartwatch", "status": "active", "source": "user", "description": "Just a sample description", "rate": 85000, "tax_id": 504366000000053100, "tax_name": "VAT", "tax_percentage": 13, "purchase_description": "Composite item purchase description", "purchase_rate": 30000, "is_combo_product": true, "item_type": "inventory", "product_type": "goods", "is_taxable": true, "stock_on_hand": 2, "available_stock": 2, "actual_available_stock": 2, "sku": "SKUIS", "upc": 746325287436, "ean": 5789414385764, "isbn": 368302334, "part_number": "JHFKE7GK7", "reorder_level": 1, "image_id": 8408722000000019000, "image_name": "img1.jpg", "created_time": "2013-08-05" }, {...}, {...} ] }
Query Params
|
page
Optional
Page Number
per_page
Optional
Items to be displayed per page
sort_column
Optional
column to be used for sorting. Allowed values:
name,sku,rate,tax_name,purchase_rate,created_time,last_modified_time,reorder_level
sort_order
Optional
order used for sorting
filter_by
Optional
Filter items by status. Allowed values:
Status.All,Status.Active,Inactive,Lowstock
usestate
Optional
Whether current filter needs to be saved
response_option
Optional
response format number
|
Create Bundle
Bundling is the technique of putting together different components in desired quantities to produce a single commodity. These components could be goods, services and other non-inventory items of your choice.
POST /bundles
Request Example
$ curl https://inventory.zoho.com/api/v1/bundles?organization_id=10234695 -X POST -H "Authorization: Zoho-oauthtoken 1000.41d9f2cfbd1b7a8f9e314b7aff7bc2d1.8fcc9810810a216793f385b9dd6e125f" -H "Content-Type: application/x-www-form-urlencoded;charset=UTF-8" -F 'JSONString="{ "reference_number": "REF-B-00005", "date": "2017-01-05", "description": "Just a sample description", "composite_item_id": 504366000000053250, "composite_item_name": "Combo of Apple IPhone and Smartwatch", "composite_item_sku": "SKUIS", "quantity_to_bundle": 1, "line_items": [ { "item_id": 4815000000044208, "name": "Combo of Apple IPhone and Smartwatch", "quantity_consumed": 1, "unit": "units", "account_id": 504366000000000400, "account_name": "sales", "warehouse_id": 4815000000000390, "warehouse_name": "MyWarehouse", "rate": 85000 } ], "is_completed": true }"'
Response Example
HTTP/1.1 201 Created Content-Type:application/json;charset=UTF-8 { "code": 0, "message": "Bundle has been created.", "bundle_id": 504366000000053250, "reference_number": "REF-B-00005", "date": "2017-01-05", "description": "Just a sample description", "composite_item_id": 504366000000053250, "composite_item_name": "Combo of Apple IPhone and Smartwatch", "composite_item_sku": "SKUIS", "quantity_to_bundle": 1, "line_items": [ { "item_id": 4815000000044208, "line_item_id": 504366000000053250, "name": "Combo of Apple IPhone and Smartwatch", "description": "Just a sample description", "quantity_consumed": 1, "unit": "units", "account_id": 504366000000000400, "account_name": "sales", "warehouse_id": 4815000000000390, "warehouse_name": "MyWarehouse", "rate": 85000 } ] }
ARGUMENTS
|
reference_number
Required
Reference number for the Bundle.
date
Required
The date on which bundling is done
description
Optional
Sample Description.
composite_item_id
Required
Unique ID generated for the composite item by the server. This is used as identifier
composite_item_name
Required
Name of the composite item
composite_item_sku
Optional
Stock Keeping Unit value of the composite item. It should be unique throughout the product
quantity_to_bundle
Required
Quantity of bundles to be bundled.
line_items
Required
A bundle can contain multiple line items. Each line item contains
item_id,name,description,quantity_consumed,unit,account_id,warehouse_id.
item_id
Required
Unique ID generated by the server for the Item. This is used as an identifier.
name
Required
Name of the composite item
description
Optional
Sample Description.
quantity_consumed
Required
Quantity of item to be bundled.
unit
Optional
Unit of Item
account_id
Required
Unique ID generated by the server for the type of sale of this item
account_name
Optional
Type of sale under which the composite item is sold
warehouse_id
Required
Unique ID generated by the server for the Warehouse.
warehouse_name
Optional
Name of the Warehouse.
rate
Optional
Selling price of the item
is_completed
Required
Denotes the status of the bundle. Currently, this has to be true since we didnt support any other status as of now.
|
Bundling History
List of all bundles of a given composite item.
GET /bundles
Request Example
$ curl https://inventory.zoho.com/api/v1/bundles?organization_id=10234695 -H "Authorization: Zoho-oauthtoken 1000.41d9f2cfbd1b7a8f9e314b7aff7bc2d1.8fcc9810810a216793f385b9dd6e125f" -H "Content-Type: application/x-www-form-urlencoded;charset=UTF-8"
Response Example
HTTP/1.1 200 OK Content-Type:application/json;charset=UTF-8 { "code": 0, "message": "success", "bundles": [ { "bundle_id": 504366000000053250, "reference_number": "REF-B-00005", "date": "2017-01-05", "description": "Just a sample description", "composite_item_id": 504366000000053250, "composite_item_name": "Combo of Apple IPhone and Smartwatch", "composite_item_sku": "SKUIS", "quantity_to_bundle": 1, "line_items": [ { "item_id": 4815000000044208, "line_item_id": 504366000000053250, "name": "Combo of Apple IPhone and Smartwatch", "description": "Just a sample description", "quantity_consumed": 1, "unit": "units", "account_id": 504366000000000400, "account_name": "sales", "warehouse_id": 4815000000000390, "warehouse_name": "MyWarehouse", "rate": 85000 } ] }, {...}, {...} ] }
Query Params
|
composite_item_id
Required
Unique ID generated for the composite item by the server. This is used as identifier
|
Retrieve Bundle
Fetches the details for an existing bundle.
GET /bundles/{bundle_id}
Request Example
$ curl https://inventory.zoho.com/api/v1/bundles/{bundle_id}?organization_id=10234695 -H "Authorization: Zoho-oauthtoken 1000.41d9f2cfbd1b7a8f9e314b7aff7bc2d1.8fcc9810810a216793f385b9dd6e125f" -H "Content-Type: application/x-www-form-urlencoded;charset=UTF-8"
Response Example
HTTP/1.1 200 OK Content-Type:application/json;charset=UTF-8 { "code": 0, "message": "success", "bundle": { "bundle_id": 504366000000053250, "reference_number": "REF-B-00005", "date": "2017-01-05", "description": "Just a sample description", "composite_item_id": 504366000000053250, "composite_item_name": "Combo of Apple IPhone and Smartwatch", "composite_item_sku": "SKUIS", "quantity_to_bundle": 1, "line_items": [ { "item_id": 4815000000044208, "line_item_id": 504366000000053250, "name": "Combo of Apple IPhone and Smartwatch", "description": "Just a sample description", "quantity_consumed": 1, "unit": "units", "account_id": 504366000000000400, "account_name": "sales", "warehouse_id": 4815000000000390, "warehouse_name": "MyWarehouse", "rate": 85000 } ], "is_completed": true } }
Delete Bundle
Deletes an existing bundle from Zoho Inventory.
DELETE /bundles/{bundle_id}
Request Example
$ curl https://inventory.zoho.com/api/v1/bundles/{bundle_id}?organization_id=10234695 -X DELETE -H "Authorization: Zoho-oauthtoken 1000.41d9f2cfbd1b7a8f9e314b7aff7bc2d1.8fcc9810810a216793f385b9dd6e125f" -H "Content-Type: application/x-www-form-urlencoded;charset=UTF-8"
Response Example
HTTP/1.1 200 OK Content-Type:application/json;charset=UTF-8 { "code": 0, "message": "The bundle has been deleted." }
Item Adjustments
Item Adjustments are used to synchronize the inventory/stock to account for things that occur outside the normal business like theft, damaged goods, data entry error etc.
Example
{ "inventory_adjustment_id": 4815000000044100, "date": "2015-05-28", "reason": "Damaged goods", "reason_id": 4815000000044110, "description": "Just a sample description.", "reference_number": "REF-IA-00001", "adjustment_type": "quantity", "line_items": [ { "item_id": 4815000000044100, "line_item_id": 4815000000044897, "name": "Laptop-white/15inch/dell", "description": "Just a sample description.", "quantity_adjusted": 10, "item_total": 244, "unit": "qty", "is_combo_product": false, "adjustment_account_id": 4815000000000388, "adjustment_account_name": "Cost of Goods Sold", "warehouse_id": 4815000000000390, "warehouse_name": "MyWarehouse" } ], "total": 350 }
Attribute
|
inventory_adjustment_id
long
Unique ID generated by the server for the item adjustment. This is used as an identifier.
date
string
The date for the Item Adjustment.
reason
string
The reason for the Item Adjustment.
reason_id
long
Unique ID generated by the server for the reason. This is used as an identifier.
description
string
Sample Description.
reference_number
string
Reference number of the Item Adjustment.
adjustment_type
enum
The adjustment type should be either quantity or value.Allowed values are
quantity and value only.
line_items
list
An item adjustment can contain multiple line items. Each line item contains
item_id,name,description,quantity_adjusted,unit,adjustment_account_id,warehouse_id.
item_id
long
Unique ID generated by the server for the item. This is used as an identifier.
line_item_id
long
Unique ID generated by the server for each line item. This is used as an identifier.
name
string
Name of the line item.
description
string
Sample Description.
quantity_adjusted
double
The adjusted quantity of the line item.It depends on adjustment_type and should be given only when adjustment_type is given as quantity.
item_total
double
Total of line item.
unit
string
Unit of line item.
is_combo_product
boolean
adjustment_account_id
long
Unique ID generated by the server for the Adjustment account.
adjustment_account_name
string
Name of the Adjustment Account.
warehouse_id
long
Unique ID generated by the server for the Warehouse.
warehouse_name
string
Name of the Warehouse.
total
double
Total value of the Item Adjustment.
|
Create an item adjustment
Creates a new item adjustment in Zoho Inventory. oauthscope : ZohoInventory.inventoryadjustments.CREATE
POST /inventoryadjustments
Request Example
$ curl https://inventory.zoho.com/api/v1/inventoryadjustments?organization_id=10234695 -X POST -H "Authorization: Zoho-oauthtoken 1000.41d9f2cfbd1b7a8f9e314b7aff7bc2d1.8fcc9810810a216793f385b9dd6e125f" -H "Content-Type: application/x-www-form-urlencoded;charset=UTF-8" -F 'JSONString="{ "date": "2015-05-28", "reason": "Damaged goods", "description": "Just a sample description.", "reference_number": "REF-IA-00001", "adjustment_type": "quantity", "line_items": [ { "item_id": 4815000000044100, "name": "Laptop-white/15inch/dell", "quantity_adjusted": 10, "item_total": 244, "unit": "qty", "is_combo_product": false, "adjustment_account_id": 4815000000000388, "adjustment_account_name": "Cost of Goods Sold", "warehouse_id": 4815000000000390, "warehouse_name": "MyWarehouse" } ] }"'
Response Example
HTTP/1.1 200 OK Content-Type:application/json;charset=UTF-8 { "code": 0, "message": "Inventory Adjustment has been added", "inventory_adjustment": { "inventory_adjustment_id": 4815000000044100, "date": "2015-05-28", "reason": "Damaged goods", "reason_id": 4815000000044110, "description": "Just a sample description.", "reference_number": "REF-IA-00001", "adjustment_type": "quantity", "line_items": [ { "item_id": 4815000000044100, "line_item_id": 4815000000044897, "name": "Laptop-white/15inch/dell", "description": "Just a sample description.", "quantity_adjusted": 10, "item_total": 244, "unit": "qty", "is_combo_product": false, "adjustment_account_id": 4815000000000388, "adjustment_account_name": "Cost of Goods Sold", "warehouse_id": 4815000000000390, "warehouse_name": "MyWarehouse" } ], "total": 350 } }
ARGUMENTS
|
date
Required
The date for the Item Adjustment.
reason
Required
The reason for the Item Adjustment.
description
Optional
Sample Description.
reference_number
Optional
Reference number of the Item Adjustment.
adjustment_type
Required
The adjustment type should be either quantity or value.Allowed values are
quantity and value only.
line_items
Required
An item adjustment can contain multiple line items. Each line item contains
item_id,name,description,quantity_adjusted,unit,adjustment_account_id,warehouse_id.
item_id
Required
Unique ID generated by the server for the item. This is used as an identifier.
name
Optional
Name of the line item.
description
Optional
Sample Description.
quantity_adjusted
Required
The adjusted quantity of the line item.It depends on adjustment_type and should be given only when adjustment_type is given as quantity.
item_total
Optional
Total of line item.
unit
Optional
Unit of line item.
is_combo_product
Optional
adjustment_account_id
Optional
Unique ID generated by the server for the Adjustment account.
adjustment_account_name
Optional
Name of the Adjustment Account.
warehouse_id
Optional
Unique ID generated by the server for the Warehouse.
warehouse_name
Optional
Name of the Warehouse.
|
Retrieve an item adjustment
Fetches the details for an existing item adjustment. oauthscope : ZohoInventory.inventoryadjustments.READ
GET /inventoryadjustments/{inventory_adjustment_id}
Request Example
$ curl https://inventory.zoho.com/api/v1/inventoryadjustments/{inventory_adjustment_id}?organization_id=10234695 -H "Authorization: Zoho-oauthtoken 1000.41d9f2cfbd1b7a8f9e314b7aff7bc2d1.8fcc9810810a216793f385b9dd6e125f" -H "Content-Type: application/x-www-form-urlencoded;charset=UTF-8"
Response Example
HTTP/1.1 200 OK Content-Type:application/json;charset=UTF-8 { "code": 0, "message": "success", "inventory_adjustment": { "inventory_adjustment_id": 4815000000044100, "date": "2015-05-28", "reason": "Damaged goods", "reason_id": 4815000000044110, "description": "Just a sample description.", "reference_number": "REF-IA-00001", "adjustment_type": "quantity", "line_items": [ { "item_id": 4815000000044100, "line_item_id": 4815000000044897, "name": "Laptop-white/15inch/dell", "description": "Just a sample description.", "quantity_adjusted": 10, "item_total": 244, "unit": "qty", "is_combo_product": false, "adjustment_account_id": 4815000000000388, "adjustment_account_name": "Cost of Goods Sold", "warehouse_id": 4815000000000390, "warehouse_name": "MyWarehouse" } ], "total": 350 } }
Delete an item adjustment
Deletes an existing item adjustment from Zoho Inventory. oauthscope : ZohoInventory.inventoryadjustments.DELETE
DELETE /inventoryadjustments/{inventory_adjustment_id}
Request Example
$ curl https://inventory.zoho.com/api/v1/inventoryadjustments/{inventory_adjustment_id}?organization_id=10234695 -X DELETE -H "Authorization: Zoho-oauthtoken 1000.41d9f2cfbd1b7a8f9e314b7aff7bc2d1.8fcc9810810a216793f385b9dd6e125f" -H "Content-Type: application/x-www-form-urlencoded;charset=UTF-8"
Response Example
HTTP/1.1 200 OK Content-Type:application/json;charset=UTF-8 { "code": 0, "message": "Inventory Adjustment(s) has been deleted" }
List all the item adjustments
Lists all the item adjustments present in Zoho Inventory. oauthscope : ZohoInventory.inventoryadjustments.READ
GET /inventoryadjustments
Request Example
$ curl https://inventory.zoho.com/api/v1/inventoryadjustments?organization_id=10234695 -H "Authorization: Zoho-oauthtoken 1000.41d9f2cfbd1b7a8f9e314b7aff7bc2d1.8fcc9810810a216793f385b9dd6e125f" -H "Content-Type: application/x-www-form-urlencoded;charset=UTF-8"
Response Example
HTTP/1.1 200 OK Content-Type:application/json;charset=UTF-8 { "code": 0, "message": "success", "inventory_adjustments": [ { "inventory_adjustment_id": 4815000000044100, "date": "2015-05-28", "reason": "Damaged goods", "reason_id": 4815000000044110, "description": "Just a sample description.", "reference_number": "REF-IA-00001", "adjustment_type": "quantity", "total": 350 }, {...}, {...} ] }
Transfer Orders
Transfer Orders allow you transfer stock from one warehouse to another, thereby greatly reducing the hassle of manually updating the stock levels.
Example
{ "transfer_order_id": 4815000000044895, "transfer_order_number": "TO-00001", "date": "2018-03-23", "from_warehouse_id": 4815000000035003, "to_warehouse_id": 4815000000035003, "line_items": [ { "item_id": 4815000000044100, "line_item_id": 4815000000044897, "name": "Laptop-white/15inch/dell", "description": "Just a sample description.", "quantity_transfer": 2, "unit": "qty" } ], "is_intransit_order": false }
Attribute
|
transfer_order_id
long
Unique ID generated by the server for the Transfer Order. This is used as identifier.
transfer_order_number
string
The Transfer Order number. This is unique for each transfer order.
date
string
The date for the Transfer Order.
from_warehouse_id
long
Unique ID generated by the server for the Warehouse.This is used a unique identifier.This is a source warehouse.
to_warehouse_id
long
Unique ID generated by the server for the Warehouse.This is used a unique identifier.This is a destination warehouse.
line_items
list
A transfer can contain multiple line items. Each line item contains
item_id,name,description,quantity_transfer,unit.
item_id
long
Unique ID generated by the server for the item. This is used as an identifier.
line_item_id
long
Unique ID generated by the server for each line item. This is used as an identifier.
name
string
Name of the line item.
description
string
Description of the line item.
quantity_transfer
double
Quantity of the line item to be transferred.
unit
string
Unit of line item.
is_intransit_order
boolean
It states whether the transfer order is in transit or transferred.The default value is false.
|
Create a transfer order
Creates a new transfer order in Zoho Inventory. oauthscope : ZohoInventory.transferorders.CREATE
POST /transferorders
Request Example
$ curl https://inventory.zoho.com/api/v1/transferorders?organization_id=10234695 -X POST -H "Authorization: Zoho-oauthtoken 1000.41d9f2cfbd1b7a8f9e314b7aff7bc2d1.8fcc9810810a216793f385b9dd6e125f" -H "Content-Type: application/x-www-form-urlencoded;charset=UTF-8" -F 'JSONString="{ "transfer_order_number": "TO-00001", "date": "2018-03-23", "from_warehouse_id": 4815000000035003, "to_warehouse_id": 4815000000035003, "line_items": [ { "item_id": 4815000000044100, "name": "Laptop-white/15inch/dell", "quantity_transfer": 2, "unit": "qty" } ], "is_intransit_order": false }"'
Response Example
HTTP/1.1 200 OK Content-Type:application/json;charset=UTF-8 { "code": 0, "message": "Transfer Order added successfully.", "transfer_order": { "transfer_order_id": 4815000000044895, "transfer_order_number": "TO-00001", "date": "2018-03-23", "from_warehouse_id": 4815000000035003, "to_warehouse_id": 4815000000035003, "line_items": [ { "item_id": 4815000000044100, "line_item_id": 4815000000044897, "name": "Laptop-white/15inch/dell", "description": "Just a sample description.", "quantity_transfer": 2, "unit": "qty" } ], "is_intransit_order": false } }
ARGUMENTS
|
transfer_order_number
Required
The Transfer Order number. This is unique for each transfer order.
date
Required
The date for the Transfer Order.
from_warehouse_id
Required
Unique ID generated by the server for the Warehouse.This is used a unique identifier.This is a source warehouse.
to_warehouse_id
Required
Unique ID generated by the server for the Warehouse.This is used a unique identifier.This is a destination warehouse.
line_items
Required
A transfer can contain multiple line items. Each line item contains
item_id,name,description,quantity_transfer,unit.
item_id
Required
Unique ID generated by the server for the item. This is used as an identifier.
name
Required
Name of the line item.
description
Optional
Description of the line item.
quantity_transfer
Required
Quantity of the line item to be transferred.
unit
Optional
Unit of line item.
is_intransit_order
Optional
It states whether the transfer order is in transit or transferred.The default value is false.
|
Retrieve a transfer order
Fetches the details for an existing transfer order. oauthscope : ZohoInventory.transferorders.READ
GET /transferorders/{transfer_order_id}
Request Example
$ curl https://inventory.zoho.com/api/v1/transferorders/{transfer_order_id}?organization_id=10234695 -H "Authorization: Zoho-oauthtoken 1000.41d9f2cfbd1b7a8f9e314b7aff7bc2d1.8fcc9810810a216793f385b9dd6e125f" -H "Content-Type: application/x-www-form-urlencoded;charset=UTF-8"
Response Example
HTTP/1.1 200 OK Content-Type:application/json;charset=UTF-8 { "code": 0, "message": "success", "transfer_order": { "transfer_order_id": 4815000000044895, "transfer_order_number": "TO-00001", "date": "2018-03-23", "from_warehouse_id": 4815000000035003, "to_warehouse_id": 4815000000035003, "line_items": [ { "item_id": 4815000000044100, "line_item_id": 4815000000044897, "name": "Laptop-white/15inch/dell", "description": "Just a sample description.", "quantity_transfer": 2, "unit": "qty" } ], "is_intransit_order": false }, "warehouses": {...} }
Delete a transfer order
Deletes an existing transfer order from Zoho Inventory. oauthscope : ZohoInventory.transferorders.DELETE
DELETE /transferorders/{transfer_order_id}
Request Example
$ curl https://inventory.zoho.com/api/v1/transferorders/{transfer_order_id}?organization_id=10234695 -X DELETE -H "Authorization: Zoho-oauthtoken 1000.41d9f2cfbd1b7a8f9e314b7aff7bc2d1.8fcc9810810a216793f385b9dd6e125f" -H "Content-Type: application/x-www-form-urlencoded;charset=UTF-8"
Response Example
HTTP/1.1 200 OK Content-Type:application/json;charset=UTF-8 { "code": 0, "message": "Transfer Order(s) has been deleted." }
List all the transfer orders
Lists all the transfer orders present in Zoho Inventory. oauthscope : ZohoInventory.transferorders.READ
GET /transferorders
Request Example
$ curl https://inventory.zoho.com/api/v1/transferorders?organization_id=10234695 -H "Authorization: Zoho-oauthtoken 1000.41d9f2cfbd1b7a8f9e314b7aff7bc2d1.8fcc9810810a216793f385b9dd6e125f" -H "Content-Type: application/x-www-form-urlencoded;charset=UTF-8"
Response Example
HTTP/1.1 200 OK Content-Type:application/json;charset=UTF-8 { "code": 0, "message": "success", "transfer_orders": [ { "transfer_order_id": 4815000000044895, "transfer_order_number": "TO-00001", "date": "2018-03-23", "from_warehouse_id": 4815000000035003, "to_warehouse_id": 4815000000035003, "is_intransit_order": false }, {...}, {...} ] }
Mark as Received
Changes the status of a transfer order to Transferred. oauthscope : ZohoInventory.transferorders.CREATE
POST /transferorders/{transfer_order_id}/markastransferred
Request Example
$ curl https://inventory.zoho.com/api/v1/transferorders/{transfer_order_id}/markastransferred?organization_id=10234695 -X POST -H "Authorization: Zoho-oauthtoken 1000.41d9f2cfbd1b7a8f9e314b7aff7bc2d1.8fcc9810810a216793f385b9dd6e125f" -H "Content-Type: application/x-www-form-urlencoded;charset=UTF-8"
Response Example
HTTP/1.1 200 OK Content-Type:application/json;charset=UTF-8 { "code": 0, "message": "The status of the Transfer Order has been updated." }
Sales Orders
A sales order is a financial document that confirms an impending sale. It details the exact quantity, price and delivery details of the products or services being sold. Perform the simple operations mentioned below to create and manage your Sales Orders.
Example
{ "salesorder_id": 4815000000044895, "ignore_auto_number_generation": false, "salesorder_number": "SO-00003", "date": "2015-05-28", "status": "fulfilled", "shipment_date": "2015-06-02", "reference_number": "REF-S-00003", "customer_id": 4815000000044080, "customer_name": "Molly", "contact_persons": [ { "contact_person_id": 4815000000044080 } ], "currency_id": 4815000000000097, "currency_code": "USD", "currency_symbol": "$", "exchange_rate": 1, "discount_amount": 0, "discount": "20.00%", "is_discount_before_tax": true, "discount_type": "entity_level", "estimate_id": 4815000000045091, "delivery_method": "FedEx", "delivery_method_id": 4815000000044822, "line_items": [ { "item_id": 4815000000044100, "line_item_id": 4815000000044897, "name": "Laptop-white/15inch/dell", "description": "Just a sample description.", "item_order": 0, "bcy_rate": 122, "rate": 122, "quantity": 2, "quantity_invoiced": 2, "quantity_packed": 2, "quantity_shipped": 2, "unit": "qty", "tax_id": 4815000000044043, "tax_name": "Sales Tax", "tax_type": "tax", "tax_percentage": 12, "item_total": 244, "is_invoiced": true, "image_id": 2077500000000002000, "image_name": "dell.jpg", "image_type": "jpg", "warehouse_id": 130426000000664020, "hsn_or_sac": 80540 } ], "shipping_charge": 7, "adjustment": 0, "adjustment_description": "Just an example description.", "sub_total": 244, "tax_total": 29, "total": 350, "taxes": [ { "tax_name": "Sales Tax", "tax_amount": 29.28 } ], "price_precision": 2, "pricebook_id": 4815000000044054, "is_emailed": true, "packages": [ { "package_id": 4815000000044905, "package_number": "PK-00004", "status": "fulfilled", "detailed_status": "Delivered", "status_message": "Delivered", "shipment_id": 4815000000044917, "shipment_number": "SH-00004", "shipment_status": 3, "carrier": "FedEx", "service": "SMART_POST", "tracking_number": "TRK214124124", "shipment_date": "2015-06-02", "delivery_days": 12, "delivery_guarantee": true } ], "invoices": [ { "invoice_id": 4815000000045091, "invoice_number": "INV-001", "status": "fulfilled", "date": "2015-05-28", "due_date": "2015-06-13", "total": 350, "balance": 0 } ], "shipping_address": [ { "address": "No:432,Bayside,Queens", "city": "New York City", "state": "New York", "zip": 11364, "country": "U.S.A", "fax": "424-524242" } ], "billing_address": [ { "address": "No:432,Bayside,Queens", "city": "New York City", "state": "New York", "zip": 11364, "country": "U.S.A", "fax": "424-524242" } ], "notes": "Sample Note", "terms": "Terms and Conditions", "template_id": 4815000000017003, "template_name": "Standard", "template_type": "standard", "created_time": "2015-05-28T00:00:00.000Z", "last_modified_time": "2015-05-28T00:00:00.000Z", "attachment_name": "sample.pdf", "can_send_in_mail": true, "salesperson_id": 4815000000044762, "salesperson_name": "Lara", "documents": [ { "can_send_in_mail": true, "file_name": "sample.pdf", "file_type": "pdf", "file_size_formatted": "116.8 KB", "attachment_order": 1, "document_id": 16115000000096068, "file_size": 11957 } ], "is_pre_gst": false, "gst_no": "22AAAAA0000A1Z5", "gst_treatment": "business_gst", "place_of_supply": "TN" }
Attribute
|
salesorder_id
long
Unique ID generated by the server for the Sales Order. This is used as identifier.
ignore_auto_number_generation
boolean
Ignore auto sales order number generation for this sales order. This mandates the sales order number. Allowed values are
true , false .
salesorder_number
string
The Sales Order number. This is unique for each sales order.
date
string
The date for the Sales Order.
status
string
The current status of the Sales Order.
shipment_date
string
Shipment date of the Sales Order.
reference_number
string
Reference number of the Sales Order
customer_id
long
Unique ID generated for the customer. This is used as an identifier.
customer_name
string
Name of the customer.
contact_persons
list
List of contact persons details.
contact_person_id
long
Unique ID generated by the server for the contact person
currency_id
long
Unique ID generated by the server for the currency. This is used as an identifier.
currency_code
string
Currency code.
currency_symbol
string
The symbol for the selected currency.
exchange_rate
double
Exchange rate of the currency, with respect to the base currency.
discount_amount
double
Discount to be applied on the Sales Order.
discount
double
The percentage of Discount applied.
is_discount_before_tax
boolean
Used to check whether the discount is applied before tax or after tax.
discount_type
string
Type of discount. Allowed values are
entity_level,item_level. For entity_level type, discount is applied at entity level and the node discount resides outside the line_items node.For item_level type, discount is applied at item level and the node discount resides inside each line_item under the line_items node
estimate_id
long
Unique ID generated by the server from the Estimate created in Zoho Books. This is used as an identifier.
delivery_method
string
Delivery method of the shipment.
delivery_method_id
long
Unique ID generated by the server for the delivery method. This is used as an identifier.
line_items
list
A sales order can contain multiple line items. Each line item contains
item_id,name,description,rate,quantity,unit,tax_id,tax_name,tax_type,tax_percentage,item_total.
item_id
long
Unique ID generated by the server for the item. This is used as an identifier.
line_item_id
long
Unique ID generated by the server for each line item. This is used as an identifier.
name
string
Name of the line item.
description
string
Description of the line item.
item_order
int
The order of the line items, starts from
0 by default.
bcy_rate
double
Item rate in the organization's base currency.
rate
double
Rate / Selling Price of the line item.
quantity
double
Quantity of the line item.
quantity_invoiced
double
Quantity invoiced of the line item.
quantity_packed
double
Quantity packed of the line item.
quantity_shipped
double
Quantity shipped of the line item.
unit
string
Unit of line item.
tax_id
long
Unique ID generated by the server for the tax. This is used as an identifier.
tax_name
string
Name of the tax applied on the line item.
tax_type
string
Denotes the type of the tax. This can either be a single tax or a tax group.
tax_percentage
double
Percentage of the tax.
item_total
double
Total of line item.
is_invoiced
boolean
Checks whether the Sales Order has been invoiced or not.
image_id
double
Unique ID generated by the server for the item image. This is used an identifier.
image_name
string
Name of the image of the line item.
image_type
string
The type (file format) of the image.
warehouse_id
long
Unique ID generated by the server for the ware houses
hsn_or_sac
India Edition only
string
Add HSN/SAC code for your goods/services
shipping_charge
double
Shipping charges that can be applied to the Sales Order.
adjustment
double
Adjustment on the Sales Order's total.
adjustment_description
string
Description for the adjustment.
sub_total
double
Sub total of the Sales Order.
tax_total
double
Tax total of the Sales Order.
total
double
Total amount of the Sales Order.
taxes
list
Number of taxes applied on sales order. Each tax contains:
tax_name and tax_amount.
tax_name
string
Name of the tax applied on the line item.
tax_amount
double
Amount of the tax.
price_precision
integer
The precision level for the price's decimal point in a Sales Order.
pricebook_id
string
Unique ID generated by the server for the Pricebook. This is used as an identifier.
is_emailed
boolean
Checks whether the Sales Order has been emailed to the customer or not.
packages
list
These are the packages created for Sales Orders. Each package contains -
package_id,package_number,status,detailed_status,status_message,shipment_id,shipment_number,shipment_status,carrier,service,tracking_number,shipment_date,delivery_days and delivery_guarantee.
package_id
long
Unique ID generated by the server for the package. This is used as an identifier.
package_number
string
Package number of the Sales Order.
status
string
The current status of the Sales Order.
detailed_status
string
Detailed status.
status_message
string
Status message of package.
shipment_id
long
Unique ID generated by the server for the shipment. This is used as an identifier.
shipment_number
string
Shipment number of the package.
shipment_status
string
Shipment status of the package.
carrier
string
Name of the shipping carrier.
service
string
Name of the service provided by the carrier.
tracking_number
string
Tracking number of shipment.
shipment_date
string
Shipment date of the Sales Order.
delivery_days
string
The expected days to be taken for the delivery.
delivery_guarantee
boolean
Delivery guarantee of the shipment can be true or false.
invoices
list
Invoices created for the Sales Order. Each invoice contains -
invoice_id, invoice_number, status, date, due_date, total, balance.
invoice_id
long
Unique ID generated by the server for the invoice. This is used as an identifier.
invoice_number
string
The number of the Invoice.
status
string
The current status of the Sales Order.
date
string
The date for the Sales Order.
due_date
string
Due date for the Invoice.
total
double
Total amount of the Sales Order.
balance
double
Balance due for the invoice.
shipping_address
list
Customer's shipping address. It contains -
address, city, state, zip, country and fax.
address
string
Name of the street of the customer’s shipping address.
city
string
Name of the city of the customer’s shipping address.
state
string
Name of the state of the customer's shipping address.
zip
string
Zip code of the customer’s shipping address.
country
string
Name of the country of the customer’s shipping address.
fax
string
Fax number of the customer’s shipping address.
billing_address
list
Customer's billing address. It contains -
address, city, state, zip, country and fax.
address
string
Name of the street of the customer’s shipping address.
city
string
Name of the city of the customer’s shipping address.
state
string
Name of the state of the customer's shipping address.
zip
string
Zip code of the customer’s shipping address.
country
string
Name of the country of the customer’s shipping address.
fax
string
Fax number of the customer’s shipping address.
notes
string
Notes for the Sales Order.
terms
string
Terms for the Sales Order.
template_id
long
Unique ID generated by the server for the Template. This is used as an identifier.
template_name
string
Name of the template used for the Sales Order.
template_type
string
Type of the template.
created_time
string
Time at which the Sales Order was created.
last_modified_time
string
Time at which the sales order details were last modified.
attachment_name
string
Name of attached file with Sales Order.
can_send_in_mail
boolean
Checks whether the sales order can be sent as a mail or not.
salesperson_id
string
Unique ID generated by the server for the sales person. This is used as an identifier.
salesperson_name
string
Name of the Sales Person.
documents
list
Sales order can have files attached to them. Each attachment has the following attributes
can_send_in_mail, file_name, file_type, file_size_formatted, attachment_order, document_id, file_size.
can_send_in_mail
boolean
Checks whether the sales order can be sent as a mail or not.
file_name
string
This indicates the name of the file.
file_type
string
This indicates the type of the file.
file_size_formatted
string
This indicates the size of the formatted file.
attachment_order
int
This indicates the chronological number of the attachment.
document_id
long
Unique ID generated by the server for the document. This is used as an identifier.
file_size
long
this indicates the size of the attached file.
is_pre_gst
India Edition only.
boolean
Applicable for transactions that fall before july 1, 2017
gst_no
India Edition only.
string
15 digit GST identification number of the customer.
gst_treatment
India Edition only.
string
Choose whether the contact is GST registered/unregistered/consumer/overseas. Allowed values are
business_gst , business_none , overseas , consumer .
place_of_supply
India Edition only.
string
Place where the goods/services are supplied to. (If not given,
place of contact given for the contact will be taken) |
Create a Sales Order
Creates a new Sales Order in Zoho Inventory. Description about extra parameter ignore_auto_number_generation - Ignore auto sales order number generation for this sales order. This mandates the Sales Order number to be entered. Allowed Values true and false. oauthscope : ZohoInventory.salesorders.CREATE
POST /salesorders
Request Example
$ curl https://inventory.zoho.com/api/v1/salesorders?organization_id=10234695 -X POST -H "Authorization: Zoho-oauthtoken 1000.41d9f2cfbd1b7a8f9e314b7aff7bc2d1.8fcc9810810a216793f385b9dd6e125f" -H "Content-Type: application/x-www-form-urlencoded;charset=UTF-8" -F 'JSONString="{ "customer_id": 4815000000044080, "salesorder_number": "SO-00003", "date": "2015-05-28", "shipment_date": "2015-06-02", "custom_fields": [ {} ], "reference_number": "REF-S-00003", "line_items": [ { "item_id": 4815000000044100, "name": "Laptop-white/15inch/dell", "description": "Just a sample description.", "rate": 122, "quantity": 2, "unit": "qty", "tax_id": 4815000000044043, "tax_name": "Sales Tax", "tax_type": "tax", "tax_percentage": 12, "item_total": 244, "warehouse_id": 130426000000664020, "hsn_or_sac": 80540 } ], "notes": "Sample Note", "terms": "Terms and Conditions", "discount": "20.00%", "is_discount_before_tax": true, "discount_type": "entity_level", "shipping_charge": 7, "delivery_method": "FedEx", "adjustment": 0, "pricebook_id": 4815000000044054, "salesperson_id": 4815000000044762, "adjustment_description": "Just an example description.", "is_inclusive_tax": false, "exchange_rate": 1, "template_id": 4815000000017003, "documents": [ { "can_send_in_mail": true, "file_name": "sample.pdf", "file_type": "pdf", "file_size_formatted": "116.8 KB", "attachment_order": 1, "document_id": 16115000000096068, "file_size": 11957 } ], "billing_address_id": 4815000000017005, "shipping_address_id": 4815000000017005, "place_of_supply": "TN", "gst_treatment": "business_gst", "gst_no": "22AAAAA0000A1Z5" }"'
Response Example
HTTP/1.1 201 Created Content-Type:application/json;charset=UTF-8 { "code": 0, "message": "success", "sales_order": { "salesorder_id": 4815000000044895, "salesorder_number": "SO-00003", "date": "2015-05-28", "status": "fulfilled", "shipment_date": "2015-06-02", "reference_number": "REF-S-00003", "customer_id": 4815000000044080, "customer_name": "Molly", "contact_persons": [ { "contact_person_id": 4815000000044080 } ], "currency_id": 4815000000000097, "currency_code": "USD", "currency_symbol": "$", "exchange_rate": 1, "discount_amount": 0, "discount": "20.00%", "is_discount_before_tax": true, "discount_type": "entity_level", "estimate_id": 4815000000045091, "delivery_method": "FedEx", "delivery_method_id": 4815000000044822, "line_items": [ { "item_id": 4815000000044100, "line_item_id": 4815000000044897, "name": "Laptop-white/15inch/dell", "description": "Just a sample description.", "item_order": 0, "bcy_rate": 122, "rate": 122, "quantity": 2, "quantity_invoiced": 2, "quantity_packed": 2, "quantity_shipped": 2, "unit": "qty", "tax_id": 4815000000044043, "tax_name": "Sales Tax", "tax_type": "tax", "tax_percentage": 12, "item_total": 244, "is_invoiced": true, "image_id": 2077500000000002000, "image_name": "dell.jpg", "image_type": "jpg", "warehouse_id": 130426000000664020, "hsn_or_sac": 80540 } ], "shipping_charge": 7, "adjustment": 0, "adjustment_description": "Just an example description.", "sub_total": 244, "tax_total": 29, "total": 350, "taxes": [ { "tax_name": "Sales Tax", "tax_amount": 29.28 } ], "price_precision": 2, "pricebook_id": 4815000000044054, "shipping_address": [ { "address": "No:432,Bayside,Queens", "city": "New York City", "state": "New York", "zip": 11364, "country": "U.S.A", "fax": "424-524242" } ], "billing_address": [ { "address": "No:432,Bayside,Queens", "city": "New York City", "state": "New York", "zip": 11364, "country": "U.S.A", "fax": "424-524242" } ], "notes": "Sample Note", "terms": "Terms and Conditions", "template_id": 4815000000017003, "template_name": "Standard", "template_type": "standard", "created_time": "2015-05-28T00:00:00.000Z", "last_modified_time": "2015-05-28T00:00:00.000Z", "salesperson_id": 4815000000044762, "salesperson_name": "Lara", "documents": [ { "can_send_in_mail": true, "file_name": "sample.pdf", "file_type": "pdf", "file_size_formatted": "116.8 KB", "attachment_order": 1, "document_id": 16115000000096068, "file_size": 11957 } ], "is_pre_gst": false, "gst_no": "22AAAAA0000A1Z5", "gst_treatment": "business_gst", "place_of_supply": "TN" } }
ARGUMENTS
|
customer_id
Required
Unique ID generated for the customer. This is used as an identifier.
salesorder_number
Required
The Sales Order number. This is unique for each sales order.
date
Optional
The date for the Sales Order.
shipment_date
Optional
Shipment date of the Sales Order.
custom_fields
Optional
custom_field_id
Optional
index
Optional
Index of the custom field
label
Optional
Label of the Custom Field
value
Optional
Value of the Custom Field
reference_number
Optional
Reference number of the Sales Order
line_items
Required
A sales order can contain multiple line items. Each line item contains
item_id,name,description,rate,quantity,unit,tax_id,tax_name,tax_type,tax_percentage,item_total.
item_id
Optional
Unique ID generated by the server for the item. This is used as an identifier.
name
Optional
Name of the line item.
description
Optional
Description of the line item.
rate
Optional
Rate / Selling Price of the line item.
quantity
Optional
Quantity of the line item.
unit
Optional
Unit of line item.
tax_id
Optional
Unique ID generated by the server for the tax. This is used as an identifier.
tax_name
Optional
Name of the tax applied on the line item.
tax_type
Optional
Denotes the type of the tax. This can either be a single tax or a tax group.
tax_percentage
Optional
Percentage of the tax.
item_total
Optional
Total of line item.
warehouse_id
Optional
Unique ID generated by the server for the ware houses
hsn_or_sac
India Edition only
Optional
Add HSN/SAC code for your goods/services
notes
Optional
Notes for the Sales Order.
terms
Optional
Terms for the Sales Order.
discount
Optional
The percentage of Discount applied.
is_discount_before_tax
Optional
Used to check whether the discount is applied before tax or after tax.
discount_type
Optional
Type of discount. Allowed values are
entity_level,item_level. For entity_level type, discount is applied at entity level and the node discount resides outside the line_items node.For item_level type, discount is applied at item level and the node discount resides inside each line_item under the line_items node
shipping_charge
Optional
Shipping charges that can be applied to the Sales Order.
delivery_method
Optional
Delivery method of the shipment.
adjustment
Optional
Adjustment on the Sales Order's total.
pricebook_id
Optional
Unique ID generated by the server for the Pricebook. This is used as an identifier.
salesperson_id
Optional
Unique ID generated by the server for the sales person. This is used as an identifier.
adjustment_description
Optional
Description for the adjustment.
is_inclusive_tax
Optional
Used to specify whether the line item rates are inclusive or exclusive of tax.
exchange_rate
Optional
Exchange rate of the currency, with respect to the base currency.
template_id
Optional
Unique ID generated by the server for the Template. This is used as an identifier.
documents
Optional
Sales order can have files attached to them. Each attachment has the following attributes
can_send_in_mail, file_name, file_type, file_size_formatted, attachment_order, document_id, file_size.
can_send_in_mail
Optional
Checks whether the sales order can be sent as a mail or not.
file_name
Optional
This indicates the name of the file.
file_type
Optional
This indicates the type of the file.
file_size_formatted
Optional
This indicates the size of the formatted file.
attachment_order
Optional
This indicates the chronological number of the attachment.
document_id
Optional
Unique ID generated by the server for the document. This is used as an identifier.
file_size
Optional
this indicates the size of the attached file.
billing_address_id
Optional
Unique Id generated by the server for address in contacts page. To add a billing address to sales order, send the address_id using this node. Else, the default billing address for that contact is used
shipping_address_id
Optional
Unique Id generated by the server for address in contacts page. To add a shipping address to sales order, send the address_id using this node. Else, the default shipping address for that contact is used
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.
|
Query Params
|
ignore_auto_number_generation
Optional
Ignore auto sales order number generation for this sales order. This mandates the sales order number. Allowed values are
true , false . |
Retrieve a Sales Order
Retrieves the details for an existing Sales Order. oauthscope : ZohoInventory.salesorders.READ
GET /salesorders/{salesorder_id}
Request Example
$ curl https://inventory.zoho.com/api/v1/salesorders/{salesorder_id}?organization_id=10234695 -H "Authorization: Zoho-oauthtoken 1000.41d9f2cfbd1b7a8f9e314b7aff7bc2d1.8fcc9810810a216793f385b9dd6e125f" -H "Content-Type: application/x-www-form-urlencoded;charset=UTF-8"
Response Example
HTTP/1.1 200 OK Content-Type:application/json;charset=UTF-8 { "code": 0, "message": "success", "sales_order": { "salesorder_id": 4815000000044895, "documents": [ { "can_send_in_mail": true, "file_name": "sample.pdf", "file_type": "pdf", "file_size_formatted": "116.8 KB", "attachment_order": 1, "document_id": 16115000000096068, "file_size": 11957 } ], "salesorder_number": "SO-00003", "date": "2015-05-28", "status": "fulfilled", "shipment_date": "2015-06-02", "reference_number": "REF-S-00003", "customer_id": 4815000000044080, "customer_name": "Molly", "contact_persons": [ { "contact_person_id": 4815000000044080 } ], "currency_id": 4815000000000097, "currency_code": "USD", "currency_symbol": "$", "exchange_rate": 1, "discount_amount": 0, "discount": "20.00%", "is_discount_before_tax": true, "discount_type": "entity_level", "estimate_id": 4815000000045091, "delivery_method": "FedEx", "delivery_method_id": 4815000000044822, "is_inclusive_tax": false, "sales_channel": "direct_sales", "is_dropshipped": false, "is_backordered": false, "is_backorder_allowed": false, "line_items": [ { "item_id": 4815000000044100, "line_item_id": 4815000000044897, "name": "Laptop-white/15inch/dell", "description": "Just a sample description.", "item_order": 0, "bcy_rate": 122, "rate": 122, "quantity": 2, "quantity_invoiced": 2, "quantity_packed": 2, "quantity_shipped": 2, "unit": "qty", "tax_id": 4815000000044043, "tax_name": "Sales Tax", "tax_type": "tax", "tax_percentage": 12, "item_total": 244, "is_invoiced": true, "image_id": 2077500000000002000, "image_name": "dell.jpg", "image_type": "jpg", "warehouse_id": 130426000000664020, "hsn_or_sac": 80540 } ], "shipping_charge": 7, "adjustment": 0, "pricebook_id": 4815000000044054, "adjustment_description": "Just an example description.", "sub_total": 244, "tax_total": 29, "total": 350, "taxes": [ { "tax_name": "Sales Tax", "tax_amount": 29.28 } ], "price_precision": 2, "is_emailed": true, "has_unconfirmed_line_item": true, "packages": [ { "package_id": 4815000000044905, "package_number": "PK-00004", "status": "fulfilled", "detailed_status": "Delivered", "status_message": "Delivered", "shipment_id": 4815000000044917, "shipment_number": "SH-00004", "shipment_status": 3, "carrier": "FedEx", "service": "SMART_POST", "tracking_number": "TRK214124124", "shipment_date": "2015-06-02", "delivery_days": 12, "delivery_guarantee": true } ], "invoices": [ { "invoice_id": 4815000000045091, "invoice_number": "INV-001", "status": "fulfilled", "date": "2015-05-28", "due_date": "2015-06-13", "total": 350, "balance": 0 } ], "billing_address": [ { "address": "No:432,Bayside,Queens", "city": "New York City", "state": "New York", "zip": 11364, "country": "U.S.A", "fax": "424-524242" } ], "shipping_address": [ { "address": "No:432,Bayside,Queens", "city": "New York City", "state": "New York", "zip": 11364, "country": "U.S.A", "fax": "424-524242" } ], "notes": "Sample Note", "terms": "Terms and Conditions", "custom_fields": [ {...} ], "template_id": 4815000000017003, "template_name": "Standard", "template_type": "standard", "created_time": "2015-05-28T00:00:00.000Z", "last_modified_time": "2015-05-28T00:00:00.000Z", "attachment_name": "sample.pdf", "can_send_in_mail": true, "salesperson_id": 4815000000044762, "salesperson_name": "Lara", "is_pre_gst": false, "gst_no": "22AAAAA0000A1Z5", "gst_treatment": "business_gst", "place_of_supply": "TN" } }
Update a Sales Order
Updates a new Sales Order in Zoho Inventory. Description about extra parameter ignore_auto_number_generation - Ignore auto sales order number generation for this sales order. This mandates the Sales Order number to be entered. Allowed Values true and false. oauthscope : ZohoInventory.salesorders.UPDATE
PUT /salesorders/{salesorder_id}
Request Example
$ curl https://inventory.zoho.com/api/v1/salesorders/{salesorder_id}?organization_id=10234695 -X PUT -H "Authorization: Zoho-oauthtoken 1000.41d9f2cfbd1b7a8f9e314b7aff7bc2d1.8fcc9810810a216793f385b9dd6e125f" -H "Content-Type: application/x-www-form-urlencoded;charset=UTF-8" -F 'JSONString="{ "salesorder_number": "SO-00003", "date": "2015-05-28", "shipment_date": "2015-06-02", "custom_fields": [ {} ], "reference_number": "REF-S-00003", "customer_id": 4815000000044080, "contact_persons": [ { "contact_person_id": 4815000000044080 } ], "discount": "20.00%", "is_discount_before_tax": true, "discount_type": "entity_level", "delivery_method": "FedEx", "shipping_charge": 7, "adjustment": 0, "adjustment_description": "Just an example description.", "pricebook_id": 4815000000044054, "notes": "Sample Note", "salesperson_name": "Lara", "terms": "Terms and Conditions", "exchange_rate": 1, "line_items": [ { "line_item_id": 4815000000044897, "item_id": 4815000000044100, "name": "Laptop-white/15inch/dell", "description": "Just a sample description.", "rate": 122, "quantity": 2, "unit": "qty", "tax_id": 4815000000044043, "tax_name": "Sales Tax", "tax_type": "tax", "tax_percentage": 12, "item_total": 244, "warehouse_id": 130426000000664020, "hsn_or_sac": 80540 } ], "billing_address_id": 4815000000017005, "shipping_address_id": 4815000000017005, "place_of_supply": "TN", "gst_treatment": "business_gst", "gst_no": "22AAAAA0000A1Z5" }"'
Response Example
HTTP/1.1 200 OK Content-Type:application/json;charset=UTF-8 { "code": 0, "message": "Sales Order has been updated.", "sales_order": { "salesorder_id": 4815000000044895, "salesorder_number": "SO-00003", "date": "2015-05-28", "status": "fulfilled", "shipment_date": "2015-06-02", "reference_number": "REF-S-00003", "customer_id": 4815000000044080, "customer_name": "Molly", "contact_persons": [ { "contact_person_id": 4815000000044080 } ], "currency_id": 4815000000000097, "currency_code": "USD", "currency_symbol": "$", "exchange_rate": 1, "discount_amount": 0, "discount": "20.00%", "is_discount_before_tax": true, "discount_type": "entity_level", "estimate_id": 4815000000045091, "delivery_method": "FedEx", "delivery_method_id": 4815000000044822, "line_items": [ { "item_id": 4815000000044100, "line_item_id": 4815000000044897, "name": "Laptop-white/15inch/dell", "description": "Just a sample description.", "item_order": 0, "bcy_rate": 122, "rate": 122, "quantity": 2, "quantity_invoiced": 2, "quantity_packed": 2, "quantity_shipped": 2, "unit": "qty", "tax_id": 4815000000044043, "tax_name": "Sales Tax", "tax_type": "tax", "tax_percentage": 12, "item_total": 244, "is_invoiced": true, "image_id": 2077500000000002000, "image_name": "dell.jpg", "image_type": "jpg", "warehouse_id": 130426000000664020, "hsn_or_sac": 80540 } ], "shipping_charge": 7, "adjustment": 0, "adjustment_description": "Just an example description.", "sub_total": 244, "tax_total": 29, "total": 350, "taxes": [ { "tax_name": "Sales Tax", "tax_amount": 29.28 } ], "price_precision": 2, "pricebook_id": 4815000000044054, "packages": [ { "package_id": 4815000000044905, "package_number": "PK-00004", "status": "fulfilled", "detailed_status": "Delivered", "status_message": "Delivered", "shipment_id": 4815000000044917, "shipment_number": "SH-00004", "shipment_status": 3, "carrier": "FedEx", "service": "SMART_POST", "tracking_number": "TRK214124124", "shipment_date": "2015-06-02", "delivery_days": 12, "delivery_guarantee": true } ], "invoices": [ { "invoice_id": 4815000000045091, "invoice_number": "INV-001", "status": "fulfilled", "date": "2015-05-28", "due_date": "2015-06-13", "total": 350, "balance": 0 } ], "shipping_address": [ { "address": "No:432,Bayside,Queens", "city": "New York City", "state": "New York", "zip": 11364, "country": "U.S.A", "fax": "424-524242" } ], "billing_address": [ { "address": "No:432,Bayside,Queens", "city": "New York City", "state": "New York", "zip": 11364, "country": "U.S.A", "fax": "424-524242" } ], "notes": "Sample Note", "terms": "Terms and Conditions", "template_id": 4815000000017003, "template_name": "Standard", "template_type": "standard", "created_time": "2015-05-28T00:00:00.000Z", "last_modified_time": "2015-05-28T00:00:00.000Z", "attachment_name": "sample.pdf", "can_send_in_mail": true, "salesperson_id": 4815000000044762, "salesperson_name": "Lara", "is_pre_gst": false, "gst_no": "22AAAAA0000A1Z5", "gst_treatment": "business_gst", "place_of_supply": "TN" } }
ARGUMENTS
|
salesorder_number
Required
The Sales Order number. This is unique for each sales order.
date
Optional
The date for the Sales Order.
shipment_date
Optional
Shipment date of the Sales Order.
custom_fields
Optional
custom_field_id
Optional
index
Optional
Index of the custom field
label
Optional
Label of the Custom Field
value
Optional
Value of the Custom Field
reference_number
Optional
Reference number of the Sales Order
customer_id
Required
Unique ID generated for the customer. This is used as an identifier.
contact_persons
Optional
List of contact persons details.
contact_person_id
Optional
Unique ID generated by the server for the contact person
discount
Optional
The percentage of Discount applied.
is_discount_before_tax
Optional
Used to check whether the discount is applied before tax or after tax.
discount_type
Optional
Type of discount. Allowed values are
entity_level,item_level. For entity_level type, discount is applied at entity level and the node discount resides outside the line_items node.For item_level type, discount is applied at item level and the node discount resides inside each line_item under the line_items node
delivery_method
Optional
Delivery method of the shipment.
shipping_charge
Optional
Shipping charges that can be applied to the Sales Order.
adjustment
Optional
Adjustment on the Sales Order's total.
adjustment_description
Optional
Description for the adjustment.
pricebook_id
Optional
Unique ID generated by the server for the Pricebook. This is used as an identifier.
notes
Optional
Notes for the Sales Order.
salesperson_name
Optional
Name of the Sales Person.
terms
Optional
Terms for the Sales Order.
exchange_rate
Optional
Exchange rate of the currency, with respect to the base currency.
line_items
Required
A sales order can contain multiple line items. Each line item contains
item_id,name,description,rate,quantity,unit,tax_id,tax_name,tax_type,tax_percentage,item_total.
line_item_id
Optional
Unique ID generated by the server for each line item. This is used as an identifier.
item_id
Optional
Unique ID generated by the server for the item. This is used as an identifier.
name
Optional
Name of the line item.
description
Optional
Description of the line item.
rate
Optional
Rate / Selling Price of the line item.
quantity
Optional
Quantity of the line item.
unit
Optional
Unit of line item.
tax_id
Optional
Unique ID generated by the server for the tax. This is used as an identifier.
tax_name
Optional
Name of the tax applied on the line item.
tax_type
Optional
Denotes the type of the tax. This can either be a single tax or a tax group.
tax_percentage
Optional
Percentage of the tax.
item_total
Optional
Total of line item.
warehouse_id
Optional
Unique ID generated by the server for the ware houses
hsn_or_sac
India Edition only
Optional
Add HSN/SAC code for your goods/services
billing_address_id
Optional
Unique Id generated by the server for address in contacts page. To add a billing address to sales order, send the address_id using this node. Else, the default billing address for that contact is used
shipping_address_id
Optional
Unique Id generated by the server for address in contacts page. To add a shipping address to sales order, send the address_id using this node. Else, the default shipping address for that contact is used
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.
|
Query Params
|
ignore_auto_number_generation
Optional
Ignore auto sales order number generation for this sales order. This mandates the sales order number. Allowed values are
true , false . |
Delete a Sales Order
Deletes an existing Sales Order from Zoho Inventory. oauthscope : ZohoInventory.salesorders.DELETE
DELETE /salesorders/{salesorder_id}
Request Example
$ curl https://inventory.zoho.com/api/v1/salesorders/{salesorder_id}?organization_id=10234695 -X DELETE -H "Authorization: Zoho-oauthtoken 1000.41d9f2cfbd1b7a8f9e314b7aff7bc2d1.8fcc9810810a216793f385b9dd6e125f" -H "Content-Type: application/x-www-form-urlencoded;charset=UTF-8"
Response Example
HTTP/1.1 200 OK Content-Type:application/json;charset=UTF-8 { "code": 0, "message": "The Sales Order has been deleted." }
List all Sales Orders
Lists all the available Sales Orders in Zoho Inventory. oauthscope : ZohoInventory.salesorders.READ
GET /salesorders
Request Example
$ curl https://inventory.zoho.com/api/v1/salesorders?organization_id=10234695 -H "Authorization: Zoho-oauthtoken 1000.41d9f2cfbd1b7a8f9e314b7aff7bc2d1.8fcc9810810a216793f385b9dd6e125f" -H "Content-Type: application/x-www-form-urlencoded;charset=UTF-8"
Response Example
HTTP/1.1 200 OK Content-Type:application/json;charset=UTF-8 { "code": 0, "message": "success", "salesorders": [ { "salesorder_id": 4815000000044895, "customer_name": "Molly", "customer_id": 4815000000044080, "status": "fulfilled", "salesorder_number": "SO-00003", "reference_number": "REF-S-00003", "date": "2015-05-28", "shipment_date": "2015-06-02", "shipment_days": 2, "quantity": 2, "quantity_invoiced": 2, "quantity_packed": 2, "quantity_shipped": 2, "currency_code": "USD", "total": 350, "bcy_total": 33, "created_time": "2015-05-28T00:00:00.000Z", "last_modified_time": "2015-05-28T00:00:00.000Z", "is_emailed": true, "is_drop_shipment": false, "is_backorder": false, "sales_channel": "direct_sales", "custom_fields": [ {...} ] }, {...}, {...} ] }
Mark as Confirmed
Changes the status of a Sales Order to Confirmed. oauthscope : ZohoInventory.salesorders.CREATE
POST /salesorders/{salesorder_id}/status/confirmed
Request Example
$ curl https://inventory.zoho.com/api/v1/salesorders/{salesorder_id}/status/confirmed?organization_id=10234695 -X POST -H "Authorization: Zoho-oauthtoken 1000.41d9f2cfbd1b7a8f9e314b7aff7bc2d1.8fcc9810810a216793f385b9dd6e125f" -H "Content-Type: application/x-www-form-urlencoded;charset=UTF-8"
Response Example
HTTP/1.1 200 OK Content-Type:application/json;charset=UTF-8 { "code": 0, "message": "Sales order status has been changed to 'Confirmed'." }
Mark as Void
Changes the status of a Sales Order to Void. oauthscope : ZohoInventory.salesorders.CREATE
POST /salesorders/{salesorder_id}/status/void
Request Example
$ curl https://inventory.zoho.com/api/v1/salesorders/{salesorder_id}/status/void?organization_id=10234695 -X POST -H "Authorization: Zoho-oauthtoken 1000.41d9f2cfbd1b7a8f9e314b7aff7bc2d1.8fcc9810810a216793f385b9dd6e125f" -H "Content-Type: application/x-www-form-urlencoded;charset=UTF-8"
Response Example
HTTP/1.1 200 OK Content-Type:application/json;charset=UTF-8 { "code": 0, "message": "The status of the Sales Order has been changed to void." }
Packages
Zoho Inventory brings to you, the feature ‘Packages’ with which you can create and assign package slip numbers to the line items in your sales orders and keep track of your packages when they are shipped.
Example
{ "billing_address": { "address": "432, Bayside, Queens", "city": "New York City", "state": "New York", "country": "U.S.A", "zip": 11364, "phone": "+1 (999)999-9999", "fax": "416-765-9871" }, "carrier": "FedEx", "contact_persons": [ { "contact_person_id": 504366000000062000 } ], "created_time": "2017-01-11T00:00:00.000Z", "customer_id": 504366000000062000, "customer_name": "Peter James", "date": "2017-01-11", "delivery_days": 2, "delivery_guarantee": true, "delivery_method": "LocalCourier", "delivery_method_id": 14954000000086028, "detailed_status": "Reached a courier facility near Toronto", "email": "jamespeter@pete.com", "is_emailed": false, "last_modified_time": "2017-01-11T00:00:00.000Z", "line_items": [ { "description": "Mobile Sales description", "is_invoiced": false, "item_custom_fields": [ { "customfield_id": 504366000000053100, "data_type": "check_box", "index": 1, "is_active": null, "label": "VAT ID", "placeholder": "cf-504366000000053126", "show_in_all_pdf": null, "show_on_pdf": null, "value": "GBGD078" } ], "item_id": 504366000000053200, "item_order": null, "line_item_id": 504366000000062100, "name": "Apple Iphone", "quantity": 2, "so_line_item_id": 504366000000062000, "sku": "SKUM", "unit": "units" } ], "mobile": "+1 (999)999-9999", "notes": "notes", "package_id": 504366000000062100, "package_number": "PA-00001", "phone": "+1 (999)999-9999", "salesorder_id": 504366000000062000, "salesorder_number": "SO-00001", "service": "FEDEX_2_DAY", "shipment_id": 14954000000086344, "shipment_number": "SN-00001", "shipment_order": { "carrier": "FedEx", "delivery_days": 2, "delivery_guarantee": true, "delivery_method": "LocalCourier", "delivery_method_id": 14954000000086028, "detailed_status": "Reached a courier facility near Toronto", "notes": "notes", "service": "FEDEX_2_DAY", "shipment_id": 14954000000086344, "shipment_number": "SN-00001", "shipment_rate": 52, "shipping_date": "2017-01-13", "status": "shipped", "tracking_number": "794656855217" }, "shipping_address": { "address": "432, Bayside, Queens", "city": "New York City", "state": "New York", "country": "U.S.A", "zip": 11364, "phone": "+1 (999)999-9999", "fax": "416-765-9871" }, "shipping_date": "2017-01-13", "status": "shipped", "template_id": 14954000000072020, "template_name": "Standard Template", "template_type": "standard", "total_quantity": 1, "tracking_number": "794656855217" }
Attribute
|
billing_address
object
Customer billing address
address
string
Name of the street of the customer address
city
string
Name of the city of the customer address
state
string
Name of the state of the customer address
country
string
Name of the country of the customer address
zip
string
Zipcode of the customer address
phone
string
Phone number of the customer
fax
string
Fax number of the customer address
carrier
string
Carrier used for shipment of package
contact_persons
list
Array of contact persons for the customers
contact_person_id
long
Unique ID generated by the server for contact person
created_time
date
Time at which the package was created
customer_id
long
Unique ID generated by the for the customer
customer_name
string
Name of the customer
date
string
Date on which package is prepared
delivery_days
integer
Number of days taken by the courier for delivering in package
delivery_guarantee
boolean
guarantee assured by the courier.
For guaranteed on-time deliveries, it is true else it is false
delivery_method
string
Custom delivery option created for the manual shipment
delivery_method_id
long
Unique ID generated by the server for delivery method
detailed_status
string
Detailed shipment details received from the courier
email
string
Email of contact person
is_emailed
boolean
Package is emailed to the customer or not
last_modified_time
date
Time at which the package details were last modified.
line_items
list
Details of the items in this package
description
string
Description of the item in package
is_invoiced
boolean
Sales order item is invoiced to the customer or not
item_custom_fields
list
Custom field of the item in package
customfield_id
long
Unique ID generated by the server for the custom field
data_type
string
Data type of the custom field
index
integer
Index of the custom field. It can hold any value from 1 to 10.
is_active
label
string
Label of the custom field
placeholder
string
Placeholder for the custom field
show_in_all_pdf
show_on_pdf
value
string
Value of the custom field
item_id
long
Unique ID generated by the server of the item in package
item_order
line_item_id
long
Unique value generated by the server for an item of sales order in package
name
string
Name of the packaged item
quantity
decimal
Number of quantity of line items in sales order
so_line_item_id
long
Unique ID generated by the server for items in sales order
sku
string
Stock keeping unit of the item in package
unit
string
Unit of the item in package
mobile
string
Mobile number of the customer
notes
string
Notes for package
package_id
long
Unique ID generated by the server for the package
package_number
string
Name of the package
phone
string
Phone number of the customer
salesorder_id
long
Unique ID generated by the server for sales order
salesorder_number
string
Name of the sales order for which package is created
service
string
Type of service selected for shipment
shipment_id
long
Unique ID generated by the server for the shipment
shipment_number
string
shipment number for the package
shipment_order
object
Shipment details of the package
carrier
string
Carrier used for shipment of package
delivery_days
integer
Number of days taken by the courier for delivering in package
delivery_guarantee
boolean
guarantee assured by the courier.
For guaranteed on-time deliveries, it is true else it is false
delivery_method
string
Custom delivery option created for the manual shipment
delivery_method_id
long
Unique ID generated by the server for delivery method
detailed_status
string
Detailed shipment details received from the courier
notes
string
Notes for package
service
string
Type of service selected for shipment
shipment_id
long
Unique ID generated by the server for the shipment
shipment_number
string
shipment number for the package
shipment_rate
decimal
Costs involved for shipment
shipping_date
date
Date on which package is shipped
status
string
status of the shipment order
tracking_number
string
Tracking number of the shipment
shipping_address
object
Customer shipping address
address
string
Name of the street of the customer address
city
string
Name of the city of the customer address
state
string
Name of the state of the customer address
country
string
Name of the country of the customer address
zip
string
Zipcode of the customer address
phone
string
Phone number of the customer
fax
string
Fax number of the customer address
shipping_date
date
Date on which package is shipped
status
string
status of the shipment order
template_id
long
Unique ID generated by the server for the template used for package
template_name
string
Name of the template
template_type
string
Type of template
total_quantity
string
Total quantity in the package
tracking_number
string
Tracking number of the shipment
|
Creating a package
A new package can be created. To create package, URL parameter salesorder_id also needed. oauthscope : ZohoInventory.packages.CREATE
POST /packages
Request Example
$ curl https://inventory.zoho.com/api/v1/packages?organization_id=10234695 -X POST -H "Authorization: Zoho-oauthtoken 1000.41d9f2cfbd1b7a8f9e314b7aff7bc2d1.8fcc9810810a216793f385b9dd6e125f" -H "Content-Type: application/x-www-form-urlencoded;charset=UTF-8" -F 'JSONString="{ "package_number": "PA-00001", "date": "2017-01-11", "line_items": [ { "so_line_item_id": 504366000000062000, "quantity": 2 } ], "notes": "notes" }"'
Response Example
HTTP/1.1 201 Created Content-Type:application/json;charset=UTF-8 { "code": 0, "message": "Package created successfully. It's now time to ship!", "package": [ { "billing_address": { "address": "432, Bayside, Queens", "city": "New York City", "state": "New York", "country": "U.S.A", "zip": 11364, "phone": "+1 (999)999-9999", "fax": "416-765-9871" }, "contact_persons": [ { "contact_person_id": 504366000000062000 } ], "created_time": "2017-01-11T00:00:00.000Z", "customer_id": 504366000000062000, "customer_name": "Peter James", "date": "2017-01-11", "email": "jamespeter@pete.com", "is_emailed": false, "last_modified_time": "2017-01-11T00:00:00.000Z", "line_items": [ { "description": "Mobile Sales description", "is_invoiced": false, "item_custom_fields": [ { "customfield_id": 504366000000053100, "data_type": "check_box", "index": 1, "is_active": null, "label": "VAT ID", "placeholder": "cf-504366000000053126", "show_in_all_pdf": null, "show_on_pdf": null, "value": "GBGD078" } ], "item_id": 504366000000053200, "item_order": null, "line_item_id": 504366000000062100, "name": "Apple Iphone", "quantity": 2, "so_line_item_id": 504366000000062000, "sku": "SKUM", "unit": "units" } ], "mobile": "+1 (999)999-9999", "notes": "notes", "package_id": 504366000000062100, "package_number": "PA-00001", "phone": "+1 (999)999-9999", "salesorder_id": 504366000000062000, "salesorder_number": "SO-00001", "shipping_address": { "address": "432, Bayside, Queens", "city": "New York City", "state": "New York", "country": "U.S.A", "zip": 11364, "phone": "+1 (999)999-9999", "fax": "416-765-9871" }, "template_id": 14954000000072020, "template_name": "Standard Template", "template_type": "standard", "total_quantity": 1 } ] }
ARGUMENTS
|
package_number
Optional
Name of the package
date
Required
Date on which package is prepared
line_items
Required
Details of the items in this package
so_line_item_id
Optional
Unique ID generated by the server for items in sales order
quantity
Optional
Number of quantity of line items in sales order
notes
Optional
Notes for package
|
Query Params
|
salesorder_id
Required
Unique ID generated by the server for sales order
|
Retrieving a package
Retrieving details of existing package. oauthscope : ZohoInventory.packages.READ
GET /packages/{package_id}
Request Example
$ curl https://inventory.zoho.com/api/v1/packages/{package_id}?organization_id=10234695 -H "Authorization: Zoho-oauthtoken 1000.41d9f2cfbd1b7a8f9e314b7aff7bc2d1.8fcc9810810a216793f385b9dd6e125f" -H "Content-Type: application/x-www-form-urlencoded;charset=UTF-8"
Response Example
HTTP/1.1 200 OK Content-Type:application/json;charset=UTF-8 { "code": 0, "message": "success", "package": [ { "billing_address": { "address": "432, Bayside, Queens", "city": "New York City", "state": "New York", "country": "U.S.A", "zip": 11364, "phone": "+1 (999)999-9999", "fax": "416-765-9871" }, "contact_persons": [ { "contact_person_id": 504366000000062000 } ], "created_time": "2017-01-11T00:00:00.000Z", "customer_id": 504366000000062000, "customer_name": "Peter James", "date": "2017-01-11", "email": "jamespeter@pete.com", "is_emailed": false, "last_modified_time": "2017-01-11T00:00:00.000Z", "line_items": [ { "description": "Mobile Sales description", "is_invoiced": false, "item_custom_fields": [ { "customfield_id": 504366000000053100, "data_type": "check_box", "index": 1, "is_active": null, "label": "VAT ID", "placeholder": "cf-504366000000053126", "show_in_all_pdf": null, "show_on_pdf": null, "value": "GBGD078" } ], "item_id": 504366000000053200, "item_order": null, "line_item_id": 504366000000062100, "name": "Apple Iphone", "quantity": 2, "so_line_item_id": 504366000000062000, "sku": "SKUM", "unit": "units" } ], "mobile": "+1 (999)999-9999", "notes": "notes", "package_id": 504366000000062100, "package_number": "PA-00001", "phone": "+1 (999)999-9999", "salesorder_id": 504366000000062000, "salesorder_number": "SO-00001", "shipment_order": { "carrier": "FedEx", "delivery_days": 2, "delivery_guarantee": true, "delivery_method": "LocalCourier", "delivery_method_id": 14954000000086028, "detailed_status": "Reached a courier facility near Toronto", "notes": "notes", "service": "FEDEX_2_DAY", "shipment_id": 14954000000086344, "shipment_number": "SN-00001", "shipment_rate": 52, "shipping_date": "2017-01-13", "status": "shipped", "tracking_number": "794656855217" }, "shipping_address": { "address": "432, Bayside, Queens", "city": "New York City", "state": "New York", "country": "U.S.A", "zip": 11364, "phone": "+1 (999)999-9999", "fax": "416-765-9871" }, "template_id": 14954000000072020, "template_name": "Standard Template", "template_type": "standard", "total_quantity": 1 } ] }
Updating a package
Updating details of existing package. oauthscope : ZohoInventory.packages.UPDATE
PUT /packages/{package_id}
Request Example
$ curl https://inventory.zoho.com/api/v1/packages/{package_id}?organization_id=10234695 -X PUT -H "Authorization: Zoho-oauthtoken 1000.41d9f2cfbd1b7a8f9e314b7aff7bc2d1.8fcc9810810a216793f385b9dd6e125f" -H "Content-Type: application/x-www-form-urlencoded;charset=UTF-8" -F 'JSONString="{ "package_number": "PA-00001", "date": "2017-01-11", "line_items": [ { "line_item_id": 504366000000062100, "so_line_item_id": 504366000000062000, "quantity": 2 } ], "notes": "notes" }"'
Response Example
HTTP/1.1 200 OK Content-Type:application/json;charset=UTF-8 { "code": 0, "message": "Package Updated Successfully.", "package": [ { "billing_address": { "address": "432, Bayside, Queens", "city": "New York City", "state": "New York", "country": "U.S.A", "zip": 11364, "phone": "+1 (999)999-9999", "fax": "416-765-9871" }, "contact_persons": [ { "contact_person_id": 504366000000062000 } ], "created_time": "2017-01-11T00:00:00.000Z", "customer_id": 504366000000062000, "customer_name": "Peter James", "date": "2017-01-11", "email": "jamespeter@pete.com", "is_emailed": false, "last_modified_time": "2017-01-11T00:00:00.000Z", "line_items": [ { "description": "Mobile Sales description", "is_invoiced": false, "item_custom_fields": [ { "customfield_id": 504366000000053100, "data_type": "check_box", "index": 1, "is_active": null, "label": "VAT ID", "placeholder": "cf-504366000000053126", "show_in_all_pdf": null, "show_on_pdf": null, "value": "GBGD078" } ], "item_id": 504366000000053200, "item_order": null, "line_item_id": 504366000000062100, "name": "Apple Iphone", "quantity": 2, "so_line_item_id": 504366000000062000, "sku": "SKUM", "unit": "units" } ], "mobile": "+1 (999)999-9999", "notes": "notes", "package_id": 504366000000062100, "package_number": "PA-00001", "phone": "+1 (999)999-9999", "salesorder_id": 504366000000062000, "salesorder_number": "SO-00001", "shipping_address": { "address": "432, Bayside, Queens", "city": "New York City", "state": "New York", "country": "U.S.A", "zip": 11364, "phone": "+1 (999)999-9999", "fax": "416-765-9871" }, "template_id": 14954000000072020, "template_name": "Standard Template", "template_type": "standard", "total_quantity": 1 } ] }
ARGUMENTS
|
package_number
Optional
Name of the package
date
Required
Date on which package is prepared
line_items
Required
Details of the items in this package
line_item_id
Optional
Unique value generated by the server for an item of sales order in package
so_line_item_id
Optional
Unique ID generated by the server for items in sales order
quantity
Optional
Number of quantity of line items in sales order
notes
Optional
Notes for package
|
Deleting a package
Deleting an existing package. oauthscope : ZohoInventory.packages.DELETE
DELETE /packages/{package_id}
Request Example
$ curl https://inventory.zoho.com/api/v1/packages/{package_id}?organization_id=10234695 -X DELETE -H "Authorization: Zoho-oauthtoken 1000.41d9f2cfbd1b7a8f9e314b7aff7bc2d1.8fcc9810810a216793f385b9dd6e125f" -H "Content-Type: application/x-www-form-urlencoded;charset=UTF-8"
Response Example
HTTP/1.1 200 OK Content-Type:application/json;charset=UTF-8 { "code": 0, "message": "Whooooosh! Package Deleted Successfully." }
List all packages
List all existing packages. oauthscope : ZohoInventory.packages.READ
GET /packages
Request Example
$ curl https://inventory.zoho.com/api/v1/packages?organization_id=10234695 -H "Authorization: Zoho-oauthtoken 1000.41d9f2cfbd1b7a8f9e314b7aff7bc2d1.8fcc9810810a216793f385b9dd6e125f" -H "Content-Type: application/x-www-form-urlencoded;charset=UTF-8"
Response Example
HTTP/1.1 200 OK Content-Type:application/json;charset=UTF-8 { "code": 0, "message": "success", "package": [ { "created_time": "2017-01-11T00:00:00.000Z", "customer_id": 504366000000062000, "customer_name": "Peter James", "date": "2017-01-11", "email": "jamespeter@pete.com", "is_emailed": false, "last_modified_time": "2017-01-11T00:00:00.000Z", "mobile": "+1 (999)999-9999", "notes": "notes", "package_id": 504366000000062100, "package_number": "PA-00001", "phone": "+1 (999)999-9999", "salesorder_id": 504366000000062000, "salesorder_number": "SO-00001", "template_id": 14954000000072020, "template_name": "Standard Template", "template_type": "standard", "total_quantity": 1 } ] }
Query Params
|
sort_column
Optional
sorting column. it can have values as
tracking_number|salesorder_number|package_number|date|created_time|last_modified_time|customer_name|customer_id|shipment_date|quantity|delivery_method
search_text
Optional
search the packages by text
filter_by
Optional
filter the packages by status. Status can be
All|NotShipped|Shipped|Delivered For example: Status.All
packing_number_startswith
Optional
Used for searching package_id which starts with given number in advanced search option
packing_number_contains
Optional
Used for searching package_id which contains given number in advanced search option
salesorder_number_startswith
Optional
Used for searching salesorder_id which starts with given number in advanced search option
salesorder_number_contains
Optional
Used for searching salesorder_id which contains given number in advanced search option
date_start
Optional
Used for searching packages from specified date
Use the node as date_after if specified date is not to be considered
date_end
Optional
Used for searching packages till specified date
Use the node as date_before if specified date is not to be considered
shipment_date_start
Optional
Used for searching shipments from specified date
Use the node as shipment_date_after if specified date is not to be considered
shipment_date_end
Optional
Used for searching shipments till specified date
Use the node as shipment_date_before if specified date is not to be considered
customer_name_startswith
Optional
Used for searching salesorder_id which starts with given number in advanced search option
customer_name_contains
Optional
Used for searching salesorder_id which contains given number in advanced search option
delivery_method_startswith
Optional
Used for searching delivery_method which starts with given string in advanced search option
delivery_method_contains
Optional
Used for searching delivery_method which contains given string in advanced search option
status
Optional
status of the shipment order
customer_id
Optional
Unique ID generated by the for the customer
|
Bulk print packages
Print package slips. oauthscope : ZohoInventory.packages.READ
GET /packages/print
Request Example
$ curl https://inventory.zoho.com/api/v1/packages/print?organization_id=10234695 -H "Authorization: Zoho-oauthtoken 1000.41d9f2cfbd1b7a8f9e314b7aff7bc2d1.8fcc9810810a216793f385b9dd6e125f" -H "Content-Type: application/x-www-form-urlencoded;charset=UTF-8"
Response Example
HTTP/1.1 200 OK Content-Type:application/json;charset=UTF-8 { "code": 0, "message": "success" }
Query Params
|
package_ids
Required
Export packages as pdf and print them.
List of package ids separated by comma |
Shipment Orders
A document used by an organization to specify what items or packages are to be transferred from a storage location or warehouse to what person and to what new location is called a shipment order. It is typically sent along with a shipment of goods so that the person receiving them(your customer) can verify that the document correctly reflects the items that they actually received.
Example
{ "salesorder_id": 4815000000044895, "package_ids": [ 4815000000017005, 4815000000017006 ], "salesorder_number": "SO-00003", "shipment_id": 4815000000044917, "shipment_number": "SH-00004", "date": "2017-01-11", "status": "shipped", "detailed_status": "Reached a courier facility near Toronto.", "status_message": "Shipped", "carrier": "FedEx", "service": "FEDEX_2_DAY", "delivery_days": 2, "delivery_guarantee": true, "reference_number": "TKG424242", "customer_id": 504366000000062000, "customer_name": "Peter James", "contact_persons": [ { "contact_person_id": 4815000000044080 } ], "currency_id": 4815000000000097, "currency_code": "USD", "currency_symbol": "$", "exchange_rate": 1, "discount_amount": 0, "discount": "20.00%", "is_discount_before_tax": true, "discount_type": "entity_level", "estimate_id": 4815000000045091, "delivery_method": "FedEx", "delivery_method_id": 4815000000044822, "tracking_number": "TRK214124124", "line_items": [ { "item_id": 4815000000044100, "line_item_id": 4815000000044897, "name": "Laptop-white/15inch/dell", "description": "Just a sample description.", "item_order": 0, "bcy_rate": 122, "rate": 122, "unit": "qty", "tax_id": 4815000000044043, "tax_name": "Sales Tax", "tax_type": "tax", "tax_percentage": 12, "item_total": 244, "is_invoiced": true } ], "shipping_charge": 7, "sub_total": 244, "tax_total": 29, "total": 350, "taxes": [ { "tax_name": "Sales Tax", "tax_amount": 29.28 } ], "price_precision": 2, "is_emailed": true, "billing_address": [ { "address": "No:234,90 Church Street", "city": "New York City", "state": "New York", "zip": 10048, "country": "U.S.A", "fax": "324-524242" } ], "shipping_address": [ { "address": "No:234,90 Church Street", "city": "New York City", "state": "New York", "zip": 10048, "country": "U.S.A", "fax": "324-524242" } ], "template_id": 4815000000017003, "template_name": "Standard", "template_type": "standard", "notes": "notes", "created_time": "2015-05-28T00:00:00.000Z", "last_modified_time": "2015-05-28T00:00:00.000Z" }
Attribute
|
salesorder_id
long
Unique ID generated by the server for the Sales Order. This is used as identifier.
package_ids
array
Array of package_id(s) to be shipped
salesorder_number
string
The Sales Order number. This is unique for each sales order.
shipment_id
long
Unique ID generated by the server for the shipment. This is used as an identifier.
shipment_number
string
Shipment number of the package.
date
string
Date on which package is prepared
status
string
Status of the Shipment Order
detailed_status
string
Detailed shipment details received from the courier
status_message
string
Status message of the shipment.
carrier
string
Carrier used for shipment.
service
string
Type of service selected for shipment
delivery_days
integer
Number of days taken by the courier for delivering in package
delivery_guarantee
boolean
guarantee assured by the courier.
For guaranteed on-time deliveries, it is true else it is false
reference_number
string
Tracking number for the Shipment.
customer_id
long
Unique ID generated by the for the customer
customer_name
string
Name of the customer
contact_persons
list
Array of contact person IDs.
contact_person_id
long
Unique ID generated by the server for the contact person
currency_id
long
Unique ID generated by the server for the currency. This is used as an identifier.
currency_code
string
Currency code.
currency_symbol
string
The symbol for the selected currency.
exchange_rate
double
Exchange rate of the currency, with respect to the base currency.
discount_amount
double
Discount to be applied on the Sales Order.
discount
double
The percentage of Discount applied.
is_discount_before_tax
boolean
Used to check whether the discount is applied before tax or after tax.
discount_type
string
Type of discount
estimate_id
long
Unique ID generated by the server from the Estimate created in Zoho Books. This is used as an identifier.
delivery_method
string
Delivery method of the shipment.
delivery_method_id
long
Unique ID generated by the server for the delivery method. This is used as an identifier.
tracking_number
string
Tracking number of shipment.
line_items
list
List of items in a package. Each line item contains
line_item_id,item_id,name,description,item_order,bcy_rate,rate,quantity,unit,tax_id,tax_name,tax_type,tax_percentage,item_total,is_invoiced.
item_id
long
Unique ID generated by the server for the item. This is used as an identifier.
line_item_id
long
Unique ID generated by the server for each line item. This is used as an identifier.
name
string
Name of the line item.
description
string
Description of the line item.
item_order
int
The order of the line items, starts from
0 by default.
bcy_rate
double
Item rate in the organization's base currency.
rate
double
Rate / Selling Price of the line item.
unit
string
Unit of line item.
tax_id
long
Unique ID generated by the server for the tax. This is used as an identifier.
tax_name
string
Name of the tax applied on the line item.
tax_type
string
Denotes the type of the tax. This can either be a single tax or a tax group.
tax_percentage
double
Percentage of the tax.
item_total
double
Total of line item.
is_invoiced
boolean
Checks whether the Sales Order has been invoiced or not.
shipping_charge
double
Shipping charges that are applied to the Shipment.
sub_total
double
Sub total of the Sales Order.
tax_total
double
Tax total of the Sales Order.
total
double
Total amount of the Sales Order.
taxes
list
Number of taxes applied on sales order. Each tax contains:
tax_name and tax_amount.
tax_name
string
Name of the tax applied on the line item.
tax_amount
double
Amount of the tax.
price_precision
integer
The precision level for the price's decimal point in a Shipment.
is_emailed
boolean
Checks whether the Package has been emailed to the customer or not.
billing_address
list
Customer's billing address. It contains -
address, city, state, zip, country and fax.
address
string
Name of the street of the customer’s billing address.
city
string
Name of the city of the customer’s billing address.
state
string
Name of the state of the customer's billing address.
zip
string
Zip code of the customer’s billing address.
country
string
Name of the country of the customer’s billing address.
fax
string
Fax number of the customer’s billing address.
shipping_address
list
Customer's shipping address. It contains -
address, city, state, zip, country and fax.
address
string
Name of the street of the customer’s billing address.
city
string
Name of the city of the customer’s billing address.
state
string
Name of the state of the customer's billing address.
zip
string
Zip code of the customer’s billing address.
country
string
Name of the country of the customer’s billing address.
fax
string
Fax number of the customer’s billing address.
template_id
long
Unique ID generated by the server for the Template. This is used as an identifier.
template_name
string
Name of the template used for the Shipment.
template_type
string
Type of the template.
notes
string
Notes for package
created_time
string
Time at which the Shipment Details was created.
last_modified_time
string
Time at which the Shipment Details details were last modified.
|
Create a Shipment Order
A new shipment order can a be created. To create shipment, URL parameter's package_ids and salesorder_id are mandatory. oauthscope : ZohoInventory.shipmentorders.CREATE
POST /shipmentorders
Request Example
$ curl https://inventory.zoho.com/api/v1/shipmentorders?organization_id=10234695 -X POST -H "Authorization: Zoho-oauthtoken 1000.41d9f2cfbd1b7a8f9e314b7aff7bc2d1.8fcc9810810a216793f385b9dd6e125f" -H "Content-Type: application/x-www-form-urlencoded;charset=UTF-8" -F 'JSONString="{ "shipment_number": "SH-00004", "date": "2017-01-11", "reference_number": "TKG424242", "contact_persons": [ { "contact_person_id": 4815000000044080 } ], "delivery_method": "FedEx", "tracking_number": "TRK214124124", "shipping_charge": 7, "exchange_rate": 1, "template_id": 4815000000017003, "notes": "notes" }"'
Response Example
HTTP/1.1 201 Created Content-Type:application/json;charset=UTF-8 { "code": 0, "message": "Shipment created successfully.", "shipment_order": { "salesorder_id": 4815000000044895, "salesorder_number": "SO-00003", "shipment_id": 4815000000044917, "shipment_number": "SH-00004", "date": "2017-01-11", "status": "shipped", "detailed_status": "Reached a courier facility near Toronto.", "status_message": "Shipped", "carrier": "FedEx", "service": "FEDEX_2_DAY", "delivery_days": 2, "delivery_guarantee": true, "reference_number": "TKG424242", "customer_id": 504366000000062000, "customer_name": "Peter James", "contact_persons": [ { "contact_person_id": 4815000000044080 } ], "currency_id": 4815000000000097, "currency_code": "USD", "currency_symbol": "$", "exchange_rate": 1, "discount_amount": 0, "discount": "20.00%", "is_discount_before_tax": true, "discount_type": "entity_level", "estimate_id": 4815000000045091, "delivery_method": "FedEx", "delivery_method_id": 4815000000044822, "tracking_number": "TRK214124124", "line_items": [ { "item_id": 4815000000044100, "line_item_id": 4815000000044897, "name": "Laptop-white/15inch/dell", "description": "Just a sample description.", "item_order": 0, "bcy_rate": 122, "rate": 122, "unit": "qty", "tax_id": 4815000000044043, "tax_name": "Sales Tax", "tax_type": "tax", "tax_percentage": 12, "item_total": 244, "is_invoiced": true } ], "shipping_charge": 7, "sub_total": 244, "tax_total": 29, "total": 350, "taxes": [ { "tax_name": "Sales Tax", "tax_amount": 29.28 } ], "price_precision": 2, "is_emailed": true, "billing_address": [ { "address": "No:234,90 Church Street", "city": "New York City", "state": "New York", "zip": 10048, "country": "U.S.A", "fax": "324-524242" } ], "shipping_address": [ { "address": "No:234,90 Church Street", "city": "New York City", "state": "New York", "zip": 10048, "country": "U.S.A", "fax": "324-524242" } ], "template_id": 4815000000017003, "template_name": "Standard", "template_type": "standard", "notes": "notes", "created_time": "2015-05-28T00:00:00.000Z", "last_modified_time": "2015-05-28T00:00:00.000Z" } }
ARGUMENTS
|
shipment_number
Required
Shipment number of the package.
date
Required
Date on which package is prepared
reference_number
Optional
Tracking number for the Shipment.
contact_persons
Optional
Array of contact person IDs.
contact_person_id
Optional
Unique ID generated by the server for the contact person
delivery_method
Required
Delivery method of the shipment.
tracking_number
Required
Tracking number of shipment.
shipping_charge
Optional
Shipping charges that are applied to the Shipment.
exchange_rate
Optional
Exchange rate of the currency, with respect to the base currency.
template_id
Optional
Unique ID generated by the server for the Template. This is used as an identifier.
notes
Optional
Notes for package
|
Query Params
|
package_ids
Optional
Array of package_id(s) to be shipped
salesorder_id
Optional
Unique ID generated by the server for the Sales Order. This is used as identifier.
|
Retrieve a Shipment Order
Retrieves details for an existing Shipment Orders. oauthscope : ZohoInventory.shipmentorders.READ
GET /shipmentorders/{shipmentorder_id}
Request Example
$ curl https://inventory.zoho.com/api/v1/shipmentorders/{shipmentorder_id}?organization_id=10234695 -H "Authorization: Zoho-oauthtoken 1000.41d9f2cfbd1b7a8f9e314b7aff7bc2d1.8fcc9810810a216793f385b9dd6e125f" -H "Content-Type: application/x-www-form-urlencoded;charset=UTF-8"
Response Example
HTTP/1.1 200 OK Content-Type:application/json;charset=UTF-8 { "code": 0, "message": "success", "shipment_order": { "salesorder_id": 4815000000044895, "salesorder_number": "SO-00003", "shipment_id": 4815000000044917, "shipment_number": "SH-00004", "date": "2017-01-11", "status": "shipped", "detailed_status": "Reached a courier facility near Toronto.", "status_message": "Shipped", "carrier": "FedEx", "service": "FEDEX_2_DAY", "delivery_days": 2, "delivery_guarantee": true, "reference_number": "TKG424242", "customer_id": 504366000000062000, "customer_name": "Peter James", "contact_persons": [ { "contact_person_id": 4815000000044080 } ], "currency_id": 4815000000000097, "currency_code": "USD", "currency_symbol": "$", "exchange_rate": 1, "discount_amount": 0, "discount": "20.00%", "is_discount_before_tax": true, "discount_type": "entity_level", "estimate_id": 4815000000045091, "delivery_method": "FedEx", "delivery_method_id": 4815000000044822, "tracking_number": "TRK214124124", "line_items": [ { "item_id": 4815000000044100, "line_item_id": 4815000000044897, "name": "Laptop-white/15inch/dell", "description": "Just a sample description.", "item_order": 0, "bcy_rate": 122, "rate": 122, "unit": "qty", "tax_id": 4815000000044043, "tax_name": "Sales Tax", "tax_type": "tax", "tax_percentage": 12, "item_total": 244, "is_invoiced": true } ], "shipping_charge": 7, "sub_total": 244, "tax_total": 29, "total": 350, "taxes": [ { "tax_name": "Sales Tax", "tax_amount": 29.28 } ], "price_precision": 2, "is_emailed": true, "billing_address": [ { "address": "No:234,90 Church Street", "city": "New York City", "state": "New York", "zip": 10048, "country": "U.S.A", "fax": "324-524242" } ], "shipping_address": [ { "address": "No:234,90 Church Street", "city": "New York City", "state": "New York", "zip": 10048, "country": "U.S.A", "fax": "324-524242" } ], "template_id": 4815000000017003, "template_name": "Standard", "template_type": "standard", "notes": "notes", "created_time": "2015-05-28T00:00:00.000Z", "last_modified_time": "2015-05-28T00:00:00.000Z" } }
Delete a Shipment Order
Deletes an existing Shipment Order. oauthscope : ZohoInventory.shipmentorders.DELETE
DELETE /shipmentorders/{shipmentorder_id}
Request Example
$ curl https://inventory.zoho.com/api/v1/shipmentorders/{shipmentorder_id}?organization_id=10234695 -X DELETE -H "Authorization: Zoho-oauthtoken 1000.41d9f2cfbd1b7a8f9e314b7aff7bc2d1.8fcc9810810a216793f385b9dd6e125f" -H "Content-Type: application/x-www-form-urlencoded;charset=UTF-8"
Response Example
HTTP/1.1 200 OK Content-Type:application/json;charset=UTF-8 { "code": 0, "message": "The Shipment Order has been deleted." }
Mark as Delivered
Change the status of the Shipment to delivered. oauthscope : ZohoInventory.shipmentorders.CREATE
POST /shipmentorders/{shipmentorder_id}/status/delivered
Request Example
$ curl https://inventory.zoho.com/api/v1/shipmentorders/{shipmentorder_id}/status/delivered?organization_id=10234695 -X POST -H "Authorization: Zoho-oauthtoken 1000.41d9f2cfbd1b7a8f9e314b7aff7bc2d1.8fcc9810810a216793f385b9dd6e125f" -H "Content-Type: application/x-www-form-urlencoded;charset=UTF-8"
Response Example
HTTP/1.1 200 OK Content-Type:application/json;charset=UTF-8 { "code": 0, "message": "The Shipment Order has been marked as Delivered." }
Invoices
An invoice is a statement of items sold by a seller. It includes all the details of sale including units of goods, price of goods sold, shipping details, etc.
Example
{ "invoice_number": "INV-00003", "item_name": "Desktop Units", "item_id": 982000000030049, "recurring_invoice_id": " ", "custom_field": " ", "search_text": " ", "sort_column": "created_time", "invoice_id": 982000000567114, "customer_name": "Bowman & Co", "customer_id": 982000000567001, "status": "draft", "reference_number": " ", "date": "2013-11-17", "due_date": "2013-12-03", "due_days": "Due in 14 day(s)", "currency_id": 982000000000190, "currency_code": "USD", "total": 40.6, "balance": 40.6, "created_time": "2013-11-18", "is_emailed": false, "reminders_sent": 1, "payment_expected_date": " ", "last_payment_date": " ", "is_pre_gst": false, "gst_no": "22AAAAA0000A1Z5", "gst_treatment": "business_gst", "place_of_supply": "TN" }
Attribute
|
invoice_number
string
An unique number given to the invoice. Maximum length [100]
item_name
string
item name.Maximum length [100]
item_id
string
Unique item id.
recurring_invoice_id
string
ID of the recurring invoice from which the invoice is created.
email
contact's email id. Maximum length [100]
custom_field
string
custom fields for invoice.
search_text
string
Search invoices by invoice number or purchase order or customer name. Maximum length [100]
sort_column
string
Sort invoices.Allowed Values:
customer_name, invoice_number, date, due_date, total, balance and created_time
invoice_id
string
The ID of the invoice
customer_name
string
The name of the customer. Maximum length [100]
customer_id
string
ID of the customer the invoice has to be created.
status
string
Search invoices by invoice status.Allowed Values:
sent, draft, overdue, paid, void, unpaid, partially_paid and viewed
invoice_number
string
An unique number given to the invoice. Maximum length [100]
reference_number
string
The reference number of the invoice
date
string
invoice date. Default date format is yyyy-mm-dd.
due_date
string
due date of the invoices. Default date format is yyyy-mm-dd.
due_days
string
Specifies the number of day in which the invoice would become overdue
currency_id
string
The currenct id of the currency
currency_code
string
The currency code in which the invoice is created.
total
string
The total amount to be paid
balance
string
The unpaid amount
created_time
string
The time of creation of the invoices
is_emailed
boolean
Boolean check to see if the mail has been sent
reminders_sent
integer
The number of reminders sent
payment_expected_date
string
The expected date of payment
last_payment_date
string
The last payment date of the invoice
is_pre_gst
India Edition only.
boolean
Applicable for transactions that fall before july 1, 2017
gst_no
India Edition only.
string
15 digit GST identification number of the customer.
gst_treatment
India Edition only.
string
Choose whether the contact is GST registered/unregistered/consumer/overseas. Allowed values are
business_gst , business_none , overseas , consumer .
place_of_supply
India Edition only.
string
Place where the goods/services are supplied to. (If not given,
place of contact given for the contact will be taken) |
Create an invoice
Create an invoice for your customer. oauthscope : ZohoInventory.invoices.CREATE
POST /invoices
Request Example
$ curl https://inventory.zoho.com/api/v1/invoices?organization_id=10234695 -X POST -H "Authorization: Zoho-oauthtoken 1000.41d9f2cfbd1b7a8f9e314b7aff7bc2d1.8fcc9810810a216793f385b9dd6e125f" -H "Content-Type: application/x-www-form-urlencoded;charset=UTF-8" -F 'JSONString="{ "customer_id": 982000000567001, "contact_persons": [ { "contact_person_id": 982000000567003, "salutation": "Mr", "first_name": "David", "last_name": "Sujin", "phone": "+1-925-921-9201", "mobile": "+1-4054439562" } ], "invoice_number": "INV-00003", "reference_number": " ", "template_id": 982000000000143, "date": "2013-11-17", "payment_terms": 15, "payment_terms_label": "Net 15", "due_date": "2013-12-03", "discount": 0, "is_discount_before_tax": true, "discount_type": "item_level", "is_inclusive_tax": false, "exchange_rate": 1, "recurring_invoice_id": " ", "invoiced_estimate_id": " ", "salesperson_name": " ", "custom_fields": [ { "index": 1, "show_on_pdf": false, "value": "The value of the custom field", "label": "Delivery Date" } ], "project_id": " ", "line_items": [ { "line_item_id": 982000000567021, "item_id": 982000000030049, "project_id": " ", "time_entry_ids": " ", "expense_id": " ", "name": "Hard Drive", "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, "salesorder_item_id": 4815000000017009, "warehouse_id": 130426000000664020, "hsn_or_sac": 80540 } ], "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, "billing_address_id": 4815000000017005, "shipping_address_id": 4815000000017005, "gst_no": "22AAAAA0000A1Z5", "gst_treatment": "business_gst", "place_of_supply": "TN" }"'
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", "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": [ { "contact_person_id": 982000000567003, "salutation": "Mr", "first_name": "David", "last_name": "Sujin", "phone": "+1-925-921-9201", "mobile": "+1-4054439562" } ], "currency_id": 982000000000190, "currency_code": "USD", "exchange_rate": 1, "discount": 0, "is_discount_before_tax": true, "discount_type": "item_level", "is_inclusive_tax": false, "recurring_invoice_id": " ", "is_viewed_by_client": false, "has_attachment": false, "client_viewed_time": "", "line_items": [ { "line_item_id": 982000000567021, "item_id": 982000000030049, "project_id": " ", "time_entry_ids": " ", "expense_id": " ", "name": "Hard Drive", "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, "warehouse_id": 130426000000664020, "hsn_or_sac": 80540 } ], "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": {...}, "shipping_address": {...}, "notes": "Looking forward for your business.", "terms": "Terms & Conditions apply", "custom_fields": [ { "index": 1, "show_on_pdf": false, "value": "The value of the custom field", "label": "Delivery Date" } ], "template_id": 982000000000143, "template_name": "Service - Classic", "created_time": "2013-11-18", "last_modified_time": "2013-11-18", "attachment_name": " ", "can_send_in_mail": true, "salesperson_id": " ", "salesperson_name": " ", "invoice_url": "https://invoice.zoho.com/SecurePayment?CInvoiceID=23d84d0cf64f9a72ea0c66fded25a08c8bafd0ab508aff05323a9f80e2cd03fdc5dd568d3d6407bbda969d3e870d740b6fce549a9438c4ea", "is_pre_gst": false, "gst_no": "22AAAAA0000A1Z5", "gst_treatment": "business_gst", "place_of_supply": "TN" } }
ARGUMENTS
|
customer_id
Required
ID of the customer the invoice has to be created.
contact_persons
Optional
contact_person_id
Optional
Unique ID of the contact person
salutation
Optional
Salutation to the contact
first_name
Optional
First name of the contact
last_name
Optional
Last name of the contact
email
Optional
contact's email id. Maximum length [100]
phone
Optional
Phone number of the contact
mobile
Optional
Mobile number of the contact person
is_primary_contact
Optional
To mark contact person as primary for contact
invoice_number
Optional
An unique number given to the invoice. Maximum length [100]
reference_number
Optional
The reference number of the invoice
template_id
Optional
ID of the pdf template associated with the invoice.
date
Optional
invoice date. Default date format is 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. Default date format is 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. Allowed values are
entity_level,item_level. For entity_level type, discount is applied at entity level and the node discount resides outside the line_items node.For item_level type, discount is applied at item level and the node discount resides inside each line_item under the line_items node.
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
Additional fields added to the invoice
index
Optional
The index of the custom field
show_on_pdf
Optional
Boolean value to check if the custom field is to be dispplayed on the pdf.
value
Optional
Value of the custom field like VAT Id etc.
label
Optional
The label of the custom field.
project_id
Optional
Unique ID of the projet associated to an invoice
line_items
Required
Line items of an invoice.
line_item_id
Optional
The line item ID
item_id
Optional
Unique item id.
project_id
Optional
Unique ID of the projet associated to an invoice
time_entry_ids
Optional
Unique ID's of all the time entries associated to the linked project
expense_id
Optional
Unique ID of the expenses associated
expense_receipt_name
Optional
Name of the expense receipt associated
name
Optional
The name of the line item. Maximum length [100]
description
Optional
The description of the line items. Maximum length [2000]
item_order
Optional
The order of the line item_order
bcy_rate
Optional
base currency rate
rate
Optional
Rate of the line item.
quantity
Optional
The quantity of line item
unit
Optional
Unit of the line item e.g. kgs, Nos. Maximum length [100]
discount_amount
Optional
The discount amount on the line item
discount
Optional
Discount applied to the invoice. It can be either in % or in amount. e.g. 12.5% or 190. Maximum length [100]
tax_id
Optional
ID of the tax or tax group applied to the estimate
tax_name
Optional
The name of the tax
tax_type
Optional
The type of the tax
tax_percentage
Optional
The percentage of tax levied
item_total
Optional
The total amount of the line items
salesorder_item_id
Optional
Pass the unique ID(line_item_id) generated by the server for the line item in sales order for this node to associate this invoice with the sales order
warehouse_id
Optional
Unique ID generated by the server for the ware houses
hsn_or_sac
India Edition only
Optional
Add HSN/SAC code for your goods/services
payment_options
Optional
Payment options available for payment
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 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
US and India 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]
vat_treatment
UK edition only
Optional
VAT treatment for the invoice. VAT treatment denotes the location of the customer, if the customer resides in UK then the VAT treatment is
uk. If the customer is in a EU country & if he is VAT registered then his VAT treatment is eu_vat_registered, if he resides in EU & if he is not VAT registered then his VAT treatment is eu_vat_not_registered and if he resides outside the EU then his VAT treatment is non_eu .
billing_address_id
Optional
Unique Id generated by the server for address in contacts page. To add a billing address to invoice, send the address_id using this node. Else, the default billing address for that contact is used
shipping_address_id
Optional
Unique Id generated by the server for address in contacts page. To add a shipping address to invoice, send the address_id using this node. Else, the default shipping address for that contact is used
gst_no
India Edition only.
Optional
15 digit GST identification number of the customer.
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 .
place_of_supply
India Edition only.
Optional
Place where the goods/services are supplied to. (If not given,
place of contact given for the contact will be taken) |
Query Params
|
send
Optional
Send the invoice to the contact person(s) associated with the invoice. Allowed values
true and false.
ignore_auto_number_generation
Optional
Ignore auto invoice number generation for this invoice. This mandates the invoice number. Allowed values
true and false |
Update an invoice
Update an existing invoice. To delete a line item just remove it from the line_items list. oauthscope : ZohoInventory.invoices.UPDATE
PUT /invoices/{:invoice_id}
Request Example
$ curl https://inventory.zoho.com/api/v1/invoices/{:invoice_id}?organization_id=10234695 -X PUT -H "Authorization: Zoho-oauthtoken 1000.41d9f2cfbd1b7a8f9e314b7aff7bc2d1.8fcc9810810a216793f385b9dd6e125f" -H "Content-Type: application/x-www-form-urlencoded;charset=UTF-8" -F 'JSONString="{ "customer_id": 982000000567001, "contact_persons": [ { "contact_person_id": 982000000567003, "salutation": "Mr", "first_name": "David", "last_name": "Sujin", "phone": "+1-925-921-9201", "mobile": "+1-4054439562" } ], "invoice_number": "INV-00003", "reference_number": " ", "template_id": 982000000000143, "date": "2013-11-17", "payment_terms": 15, "payment_terms_label": "Net 15", "due_date": "2013-12-03", "discount": 0, "is_discount_before_tax": true, "discount_type": "item_level", "is_inclusive_tax": false, "exchange_rate": 1, "recurring_invoice_id": " ", "invoiced_estimate_id": " ", "salesperson_name": " ", "custom_fields": [ { "index": 1, "show_on_pdf": false, "value": "The value of the custom field", "label": "Delivery Date" } ], "project_id": " ", "line_items": [ { "line_item_id": 982000000567021, "item_id": 982000000030049, "project_id": " ", "time_entry_ids": " ", "expense_id": " ", "name": "Hard Drive", "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, "warehouse_id": 130426000000664020, "hsn_or_sac": 80540 } ], "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, "billing_address_id": 4815000000017005, "shipping_address_id": 4815000000017005, "gst_no": "22AAAAA0000A1Z5", "gst_treatment": "business_gst", "place_of_supply": "TN" }"'
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", "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": [ { "contact_person_id": 982000000567003, "salutation": "Mr", "first_name": "David", "last_name": "Sujin", "phone": "+1-925-921-9201", "mobile": "+1-4054439562" } ], "currency_id": 982000000000190, "currency_code": "USD", "exchange_rate": 1, "discount": 0, "is_discount_before_tax": true, "discount_type": "item_level", "is_inclusive_tax": false, "recurring_invoice_id": " ", "is_viewed_by_client": false, "has_attachment": false, "client_viewed_time": "", "line_items": [ { "line_item_id": 982000000567021, "item_id": 982000000030049, "project_id": " ", "time_entry_ids": " ", "expense_id": " ", "name": "Hard Drive", "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, "warehouse_id": 130426000000664020, "hsn_or_sac": 80540 } ], "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": {...}, "shipping_address": {...}, "notes": "Looking forward for your business.", "terms": "Terms & Conditions apply", "custom_fields": [ { "index": 1, "show_on_pdf": false, "value": "The value of the custom field", "label": "Delivery Date" } ], "template_id": 982000000000143, "template_name": "Service - Classic", "created_time": "2013-11-18", "last_modified_time": "2013-11-18", "attachment_name": " ", "can_send_in_mail": true, "salesperson_id": " ", "salesperson_name": " ", "invoice_url": "https://invoice.zoho.com/SecurePayment?CInvoiceID=23d84d0cf64f9a72ea0c66fded25a08c8bafd0ab508aff05323a9f80e2cd03fdc5dd568d3d6407bbda969d3e870d740b6fce549a9438c4ea", "is_pre_gst": false, "gst_no": "22AAAAA0000A1Z5", "gst_treatment": "business_gst", "place_of_supply": "TN" } }
ARGUMENTS
|
customer_id
Required
ID of the customer the invoice has to be created.
contact_persons
Optional
contact_person_id
Optional
Unique ID of the contact person
salutation
Optional
Salutation to the contact
first_name
Optional
First name of the contact
last_name
Optional
Last name of the contact
email
Optional
contact's email id. Maximum length [100]
phone
Optional
Phone number of the contact
mobile
Optional
Mobile number of the contact person
is_primary_contact
Optional
To mark contact person as primary for contact
invoice_number
Optional
An unique number given to the invoice. Maximum length [100]
reference_number
Optional
The reference number of the invoice
template_id
Optional
ID of the pdf template associated with the invoice.
date
Optional
invoice date. Default date format is 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. Default date format is 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. Allowed values are
entity_level,item_level. For entity_level type, discount is applied at entity level and the node discount resides outside the line_items node.For item_level type, discount is applied at item level and the node discount resides inside each line_item under the line_items node.
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
Additional fields added to the invoice
index
Optional
The index of the custom field
show_on_pdf
Optional
Boolean value to check if the custom field is to be dispplayed on the pdf.
value
Optional
Value of the custom field like VAT Id etc.
label
Optional
The label of the custom field.
project_id
Optional
Unique ID of the projet associated to an invoice
line_items
Required
Line items of an invoice.
line_item_id
Optional
The line item ID
item_id
Optional
Unique item id.
project_id
Optional
Unique ID of the projet associated to an invoice
time_entry_ids
Optional
Unique ID's of all the time entries associated to the linked project
expense_id
Optional
Unique ID of the expenses associated
expense_receipt_name
Optional
Name of the expense receipt associated
name
Optional
The name of the line item. Maximum length [100]
description
Optional
The description of the line items. Maximum length [2000]
item_order
Optional
The order of the line item_order
bcy_rate
Optional
base currency rate
rate
Optional
Rate of the line item.
quantity
Optional
The quantity of line item
unit
Optional
Unit of the line item e.g. kgs, Nos. Maximum length [100]
discount_amount
Optional
The discount amount on the line item
discount
Optional
Discount applied to the invoice. It can be either in % or in amount. e.g. 12.5% or 190. Maximum length [100]
tax_id
Optional
ID of the tax or tax group applied to the estimate
tax_name
Optional
The name of the tax
tax_type
Optional
The type of the tax
tax_percentage
Optional
The percentage of tax levied
item_total
Optional
The total amount of the line items
warehouse_id
Optional
Unique ID generated by the server for the ware houses
hsn_or_sac
India Edition only
Optional
Add HSN/SAC code for your goods/services
payment_options
Optional
Payment options available for payment
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 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
US and India 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]
vat_treatment
UK edition only
Optional
VAT treatment for the invoice. VAT treatment denotes the location of the customer, if the customer resides in UK then the VAT treatment is
uk. If the customer is in a EU country & if he is VAT registered then his VAT treatment is eu_vat_registered, if he resides in EU & if he is not VAT registered then his VAT treatment is eu_vat_not_registered and if he resides outside the EU then his VAT treatment is non_eu .
billing_address_id
Optional
Unique Id generated by the server for address in contacts page. To add a billing address to invoice, send the address_id using this node. Else, the default billing address for that contact is used
shipping_address_id
Optional
Unique Id generated by the server for address in contacts page. To add a shipping address to invoice, send the address_id using this node. Else, the default shipping address for that contact is used
gst_no
India Edition only.
Optional
15 digit GST identification number of the customer.
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 .
place_of_supply
India Edition only.
Optional
Place where the goods/services are supplied to. (If not given,
place of contact given for the contact will be taken) |
Query Params
|
ignore_auto_number_generation
Optional
Ignore auto invoice number generation for this invoice. This mandates the invoice number. Allowed values
true and false |
Get an invoice
Get the details of an invoice. oauthscope : ZohoInventory.invoices.READ
GET /invoices/{:invoice_id}
Request Example
$ curl https://inventory.zoho.com/api/v1/invoices/{:invoice_id}?organization_id=10234695 -H "Authorization: Zoho-oauthtoken 1000.41d9f2cfbd1b7a8f9e314b7aff7bc2d1.8fcc9810810a216793f385b9dd6e125f" -H "Content-Type: application/x-www-form-urlencoded;charset=UTF-8"
Response Example
HTTP/1.1 200 OK Content-Type:application/json;charset=UTF-8 { "code": 0, "message": "success", "invoice": { "invoice_id": 982000000567114, "ach_payment_initiated": false, "invoice_number": "INV-00003", "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": [ { "contact_person_id": 982000000567003, "salutation": "Mr", "first_name": "David", "last_name": "Sujin", "phone": "+1-925-921-9201", "mobile": "+1-4054439562" } ], "currency_id": 982000000000190, "currency_code": "USD", "exchange_rate": 1, "discount": 0, "is_discount_before_tax": true, "discount_type": "item_level", "is_inclusive_tax": false, "recurring_invoice_id": " ", "is_viewed_by_client": false, "has_attachment": false, "client_viewed_time": "", "line_items": [ { "line_item_id": 982000000567021, "item_id": 982000000030049, "project_id": " ", "time_entry_ids": " ", "expense_id": " ", "name": "Hard Drive", "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, "warehouse_id": 130426000000664020, "hsn_or_sac": 80540 } ], "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": {...}, "shipping_address": {...}, "notes": "Looking forward for your business.", "terms": "Terms & Conditions apply", "custom_fields": [ { "index": 1, "show_on_pdf": false, "value": "The value of the custom field", "label": "Delivery Date" } ], "template_id": 982000000000143, "template_name": "Service - Classic", "created_time": "2013-11-18", "last_modified_time": "2013-11-18", "attachment_name": " ", "can_send_in_mail": true, "salesperson_id": " ", "salesperson_name": " ", "invoice_url": "https://invoice.zoho.com/SecurePayment?CInvoiceID=23d84d0cf64f9a72ea0c66fded25a08c8bafd0ab508aff05323a9f80e2cd03fdc5dd568d3d6407bbda969d3e870d740b6fce549a9438c4ea", "is_pre_gst": false, "gst_no": "22AAAAA0000A1Z5", "gst_treatment": "business_gst", "place_of_supply": "TN" } }
Query Params
|
print
Optional
Print the exported pdf.
accept
Optional
Get the details of a particular invoice in formats such as json/ pdf/ html. Default format is json. Allowed values
json pdf and html |
List invoices
List all invoices with pagination. oauthscope : ZohoInventory.invoices.READ
GET /invoices
Request Example
$ curl https://inventory.zoho.com/api/v1/invoices?organization_id=10234695 -H "Authorization: Zoho-oauthtoken 1000.41d9f2cfbd1b7a8f9e314b7aff7bc2d1.8fcc9810810a216793f385b9dd6e125f" -H "Content-Type: application/x-www-form-urlencoded;charset=UTF-8"
Response Example
HTTP/1.1 200 OK Content-Type:application/json;charset=UTF-8 { "code": 0, "message": "success", "invoices": [ { "invoice_id": 982000000567114, "ach_payment_initiated": false, "customer_name": "Bowman & Co", "customer_id": 982000000567001, "status": "draft", "invoice_number": "INV-00003", "reference_number": " ", "date": "2013-11-17", "due_date": "2013-12-03", "due_days": "Due in 14 day(s)", "currency_id": 982000000000190, "schedule_time": "", "currency_code": "USD", "is_viewed_by_client": false, "has_attachment": false, "client_viewed_time": "", "total": 40.6, "balance": 40.6, "created_time": "2013-11-18", "last_modified_time": "2013-11-18", "is_emailed": false, "reminders_sent": 1, "last_reminder_sent_date": " ", "payment_expected_date": " ", "last_payment_date": " ", "custom_fields": [ { "index": 1, "show_on_pdf": false, "value": "The value of the custom field", "label": "Delivery Date" } ], "documents": "", "salesperson_id": " ", "salesperson_name": " ", "shipping_charge": 0, "adjustment": 0, "write_off_amount": 0, "exchange_rate": 1 }, {...}, {...} ] }
Query Params
|
invoice_number
Optional
An unique number given to the invoice. Maximum length [100]
item_name
Optional
item name.Variants:
item_name_startswith and item_name_contains. Maximum length [100]
item_id
Optional
Unique item id.
item_description
Optional
Search invoices by item description.Variants:
item_description_startswith and item_description_contains. Maximum length [100]
reference_number
Optional
The reference number of the invoice
customer_name
Optional
The name of the customer. Maximum length [100]
recurring_invoice_id
Optional
ID of the recurring invoice from which the invoice is created.
email
Optional
contact's email id. Maximum length [100]
total
Optional
The total amount to be paid
balance
Optional
The unpaid amount
custom_field
Optional
custom fields for invoice. Variants:
custom_field_startswith and custom_field_contains
date
Optional
invoice date. Default date format is 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. Default date format is yyyy-mm-dd.
Variants: due_date_start, due_date_end, due_date_before and due_date_after
status
Optional
Search invoices by invoice status.Allowed Values:
sent, draft, overdue, paid, void, unpaid, partially_paid and viewed
customer_id
Optional
ID of the customer the invoice has to be created.
filter_by
Optional
Filter invoices by any status or payment expected date.Allowed Values:
Status.All, Status.Sent, Status.Draft, Status.OverDue, Status.Paid, Status.Void, Status.Unpaid, Status.PartiallyPaid, Status.Viewed and Date.PaymentExpectedDate
search_text
Optional
Search invoices by invoice number or purchase order or customer name. Maximum length [100]
sort_column
Optional
Sort invoices.Allowed Values:
customer_name, invoice_number, date, due_date, total, balance and created_time |
Delete an invoice
Delete an existing invoice. Invoices which have payment or credits note applied cannot be deleted. oauthscope : ZohoInventory.invoices.DELETE
DELETE /invoices/{:invoice_id}
Request Example
$ curl https://inventory.zoho.com/api/v1/invoices/{:invoice_id}?organization_id=10234695 -X DELETE -H "Authorization: Zoho-oauthtoken 1000.41d9f2cfbd1b7a8f9e314b7aff7bc2d1.8fcc9810810a216793f385b9dd6e125f" -H "Content-Type: application/x-www-form-urlencoded;charset=UTF-8"
Response Example
HTTP/1.1 200 OK Content-Type:application/json;charset=UTF-8 { "code": 0, "message": "The invoice has been deleted." }
Mark an invoice as sent
Mark a draft invoice as sent. oauthscope : ZohoInventory.invoices.CREATE
POST /invoices/{:invoice_id}/status/sent
Request Example
$ curl https://inventory.zoho.com/api/v1/invoices/{:invoice_id}/status/sent?organization_id=10234695 -X POST -H "Authorization: Zoho-oauthtoken 1000.41d9f2cfbd1b7a8f9e314b7aff7bc2d1.8fcc9810810a216793f385b9dd6e125f" -H "Content-Type: application/x-www-form-urlencoded;charset=UTF-8"
Response Example
HTTP/1.1 200 OK Content-Type:application/json;charset=UTF-8 { "code": 0, "message": "Invoice status has been changed to Sent." }
Void an invoice
Mark an invoice status as void. Upon voiding, the payments and credits associated with the invoices will be unassociated and will be under customer credits. oauthscope : ZohoInventory.invoices.CREATE
POST /invoices/{:invoice_id}/status/void
Request Example
$ curl https://inventory.zoho.com/api/v1/invoices/{:invoice_id}/status/void?organization_id=10234695 -X POST -H "Authorization: Zoho-oauthtoken 1000.41d9f2cfbd1b7a8f9e314b7aff7bc2d1.8fcc9810810a216793f385b9dd6e125f" -H "Content-Type: application/x-www-form-urlencoded;charset=UTF-8"
Response Example
HTTP/1.1 200 OK Content-Type:application/json;charset=UTF-8 { "code": 0, "message": "Invoice status has been changed to Void." }
Mark as draft
Mark a voided invoice as draft. oauthscope : ZohoInventory.invoices.CREATE
POST /invoices/{:invoice_id}/status/draft
Request Example
$ curl https://inventory.zoho.com/api/v1/invoices/{:invoice_id}/status/draft?organization_id=10234695 -X POST -H "Authorization: Zoho-oauthtoken 1000.41d9f2cfbd1b7a8f9e314b7aff7bc2d1.8fcc9810810a216793f385b9dd6e125f" -H "Content-Type: application/x-www-form-urlencoded;charset=UTF-8"
Response Example
HTTP/1.1 200 OK Content-Type:application/json;charset=UTF-8 { "code": 0, "message": "Status of invoice changed from void to draft" }
Email an invoice
Email an invoice to the customer. Input json string is not mandatory. If input json string is empty, mail will be send with default mail content. oauthscope : ZohoInventory.invoices.CREATE
POST /invoices/{:invoice_id}/email
Request Example
$ curl https://inventory.zoho.com/api/v1/invoices/{:invoice_id}/email?organization_id=10234695 -X POST -H "Authorization: Zoho-oauthtoken 1000.41d9f2cfbd1b7a8f9e314b7aff7bc2d1.8fcc9810810a216793f385b9dd6e125f" -H "Content-Type: application/x-www-form-urlencoded;charset=UTF-8" -F 'JSONString="{ "send_from_org_email_id": false, "to_mail_ids": [ "willsmith@bowmanfurniture.com" ], "cc_mail_ids": [ "peterparker@bowmanfurniture.com" ], "subject": "Invoice from Zillium Inc (Invoice#: INV-00001)", "body": "Dear Customer, <br><br><br><br>Thanks for your business. <br><br><br><br>The invoice INV-00001 is attached with this email. You can choose the easy way out and <a href= https://invoice.zoho.com/SecurePayment?CInvoiceID=b9800228e011ae86abe71227bdacb3c68e1af685f647dcaed747812e0b9314635e55ac6223925675b371fcbd2d5ae3dc >pay online for this invoice.</a> <br><br>Here's an overview of the invoice for your reference. <br><br><br><br>Invoice Overview: <br><br>Invoice : INV-00001 <br><br>Date : 05 Aug 2013 <br><br>Amount : $541.82 <br><br><br><br>It was great working with you. Looking forward to working with you again.<br><br><br>\\nRegards<br>\\nZillium Inc<br>\\n\"," }"'
Response Example
HTTP/1.1 200 OK Content-Type:application/json;charset=UTF-8 { "code": 0, "message": "Your invoice has been sent." }
ARGUMENTS
|
send_from_org_email_id
Optional
Boolean to trigger the email from the organization's email address
to_mail_ids
Required
Array of email addresses of the recipients.
cc_mail_ids
Optional
Array of email addresses of the recipients to be CC'd.
subject
Optional
The subject of the mail
body
Optional
The body/content of the mail
|
Query Params
|
send_customer_statement
Optional
Send customer statement pdf a with email.
send_attachment
Optional
Send the invoice attachment a with the email.
attachments
Optional
Files to be attached to the email
|
Email invoices
Send invoices to your customers by email. Maximum of 10 invoices can be sent at once. oauthscope : ZohoInventory.invoices.CREATE
POST /invoices/email
Request Example
$ curl https://inventory.zoho.com/api/v1/invoices/email?organization_id=10234695 -X POST -H "Authorization: Zoho-oauthtoken 1000.41d9f2cfbd1b7a8f9e314b7aff7bc2d1.8fcc9810810a216793f385b9dd6e125f" -H "Content-Type: application/x-www-form-urlencoded;charset=UTF-8"
Response Example
HTTP/1.1 200 OK Content-Type:application/json;charset=UTF-8 { "code": 0, "message": "Mission accomplished! We've sent all the invoices." }
Query Params
|
invoice_ids
Required
Comma separated invoice ids which are to be emailed.
|
Get invoice email content
Get the email content of an invoice. oauthscope : ZohoInventory.invoices.READ
GET /invoices/{:invoice_id}/email
Request Example
$ curl https://inventory.zoho.com/api/v1/invoices/{:invoice_id}/email?organization_id=10234695 -H "Authorization: Zoho-oauthtoken 1000.41d9f2cfbd1b7a8f9e314b7aff7bc2d1.8fcc9810810a216793f385b9dd6e125f" -H "Content-Type: application/x-www-form-urlencoded;charset=UTF-8"
Response Example
HTTP/1.1 200 OK Content-Type:application/json;charset=UTF-8 { "code": 0, "message": "success", "data": { "bcc_mails": [ {...} ], "gateways_configured": true, "gateways_associated": true, "bcc_mails_str": "", "body": "Dear Customer, <br><br><br><br>Thanks for your business. <br><br><br><br>The invoice INV-00001 is attached with this email. You can choose the easy way out and <a href= https://invoice.zoho.com/SecurePayment?CInvoiceID=b9800228e011ae86abe71227bdacb3c68e1af685f647dcaed747812e0b9314635e55ac6223925675b371fcbd2d5ae3dc >pay online for this invoice.</a> <br><br>Here's an overview of the invoice for your reference. <br><br><br><br>Invoice Overview: <br><br>Invoice : INV-00001 <br><br>Date : 05 Aug 2013 <br><br>Amount : $541.82 <br><br><br><br>It was great working with you. Looking forward to working with you again.<br><br><br>\\nRegards<br>\\nZillium Inc<br>\\n\",", "documents": "", "customer_name": "Bowman & Co", "attach_pdf": true, "entity_id": "2000000007037", "cc_mails_list": [ { "user_name": "David Sujin" } ], "file_name_without_extension": "INV-000004", "to_mails_str": "", "cc_mails_str": "", "from_email": "", "from_address": "", "deprecated_placeholders_used": [ {...} ], "error_list": [ {...} ], "subject": "Invoice from Zillium Inc (Invoice#: INV-00001)", "emailtemplates": [ { "selected": true, "name": "Default", "email_template_id": "982000000000067" } ], "emailtemplate_documents": [ {...} ], "to_contacts": [ { "first_name": "David", "selected": true, "phone": "+1-925-921-9201", "last_name": "Sujin", "salutation": "Mr", "contact_person_id": 982000000567003, "mobile": "+1-4054439562" } ], "attachment_name": " ", "file_name": "INV-00001.pdf", "from_emails": [ { "user_name": "David Sujin", "selected": true, "organization_contact_id": "2000000002266", "is_org_email_id": true } ], "customer_id": 982000000567001 } }
Query Params
|
email_template_id
Optional
Get the email content based on a specific email template. If this param is not inputted, then the content will be based on the email template associated with the customer. If no template is associated with the customer, then default template will be used.
|
Get payment reminder mail content
Get the mail content of the payment reminder. oauthscope : ZohoInventory.invoices.READ
GET /invoices/{:invoice_id}/paymentreminder
Request Example
$ curl https://inventory.zoho.com/api/v1/invoices/{:invoice_id}/paymentreminder?organization_id=10234695 -H "Authorization: Zoho-oauthtoken 1000.41d9f2cfbd1b7a8f9e314b7aff7bc2d1.8fcc9810810a216793f385b9dd6e125f" -H "Content-Type: application/x-www-form-urlencoded;charset=UTF-8"
Response Example
HTTP/1.1 200 OK Content-Type:application/json;charset=UTF-8 { "code": 0, "message": "success", "data": { "bcc_mails": [ {...} ], "gateways_configured": true, "gateways_associated": true, "bcc_mails_str": "", "body": "<br>Dear Mr. Sujin, <br><br>You might have missed the payment date and the invoice is now overdue by 1 days.<br><br>----------------------------------------------------------------------------------------<br><h2>Invoice# : INV-000004 </h2>Dated : 23 Dec 2016<br>----------------------------------------------------------------------------------------<br><b> Due Date : 23 Dec 2016</b><br><b> Amount : $139.65</b><br>----------------------------------------------------------------------------------------<br><br><span>Not to worry at all ! </span>View your invoice and take the easy way out by making an <a href=\"https://invoice.zoho.com/portal/Zillium Inc/index#/invoices/invoice/2000000007037 \">online payment</a>.<br><br>If you have already paid, please accept our apologies and kindly ignore this payment reminder.<br><br><br>Regards,<br><br>David Sujin<br>Zillium Inc<br><br><br>", "documents": "", "customer_name": "Bowman & Co", "attach_pdf": true, "entity_id": "2000000007037", "cc_mails_list": [ { "user_name": "David Sujin" } ], "file_name_without_extension": "INV-000004", "to_mails_str": "", "cc_mails_str": "", "from_email": "", "from_address": "", "deprecated_placeholders_used": [ {...} ], "error_list": [ {...} ], "subject": "Invoice from Zillium Inc (Invoice#: INV-00001)", "emailtemplates": [ { "selected": true, "name": "Default", "email_template_id": "982000000000067" } ], "emailtemplate_documents": [ {...} ], "to_contacts": [ { "first_name": "David", "selected": true, "phone": "+1-925-921-9201", "last_name": "Sujin", "salutation": "Mr", "contact_person_id": 982000000567003, "mobile": "+1-4054439562" } ], "attachment_name": " ", "file_name": "INV-00001.pdf", "from_emails": [ { "user_name": "David Sujin", "selected": true, "organization_contact_id": "2000000002266", "is_org_email_id": true } ], "customer_id": 982000000567001 } }
Bulk export Invoices
Maximum of 25 invoices can be exported in a single pdf. oauthscope : ZohoInventory.invoices.READ
GET /invoices/pdf
Request Example
$ curl https://inventory.zoho.com/api/v1/invoices/pdf?organization_id=10234695 -H "Authorization: Zoho-oauthtoken 1000.41d9f2cfbd1b7a8f9e314b7aff7bc2d1.8fcc9810810a216793f385b9dd6e125f" -H "Content-Type: application/x-www-form-urlencoded;charset=UTF-8"
Response Example
HTTP/1.1 200 OK Content-Type:application/json;charset=UTF-8 { "code": 0, "message": "success" }
Query Params
|
invoice_ids
Required
Comma separated invoice ids which are to be export as pdf.
|
Bulk print invoices
Export invoices as pdf and print them. Maximum of 25 invoices can be printed. oauthscope : ZohoInventory.invoices.READ
GET /invoices/print
Request Example
$ curl https://inventory.zoho.com/api/v1/invoices/print?organization_id=10234695 -H "Authorization: Zoho-oauthtoken 1000.41d9f2cfbd1b7a8f9e314b7aff7bc2d1.8fcc9810810a216793f385b9dd6e125f" -H "Content-Type: application/x-www-form-urlencoded;charset=UTF-8"
Response Example
HTTP/1.1 200 OK Content-Type:application/json;charset=UTF-8 { "code": 0, "message": "success" }
Query Params
|
invoice_ids
Required
Export invoices as pdf and print them. Maximum of 25 invoices can be printed.
|
Disable payment reminder
Disable automated payment reminders for an invoice. oauthscope : ZohoInventory.invoices.CREATE
POST /invoices/{:invoice_id}/paymentreminder/disable
Request Example
$ curl https://inventory.zoho.com/api/v1/invoices/{:invoice_id}/paymentreminder/disable?organization_id=10234695 -X POST -H "Authorization: Zoho-oauthtoken 1000.41d9f2cfbd1b7a8f9e314b7aff7bc2d1.8fcc9810810a216793f385b9dd6e125f" -H "Content-Type: application/x-www-form-urlencoded;charset=UTF-8"
Response Example
HTTP/1.1 200 OK Content-Type:application/json;charset=UTF-8 { "code": 0, "message": "Reminders stopped." }
Enable payment reminder
Enable automated payment reminders for an invoice. oauthscope : ZohoInventory.invoices.CREATE
POST /invoices/{:invoice_id}/paymentreminder/enable
Request Example
$ curl https://inventory.zoho.com/api/v1/invoices/{:invoice_id}/paymentreminder/enable?organization_id=10234695 -X POST -H "Authorization: Zoho-oauthtoken 1000.41d9f2cfbd1b7a8f9e314b7aff7bc2d1.8fcc9810810a216793f385b9dd6e125f" -H "Content-Type: application/x-www-form-urlencoded;charset=UTF-8"
Response Example
HTTP/1.1 200 OK Content-Type:application/json;charset=UTF-8 { "code": 0, "message": "Reminders enabled." }
Write off invoice
Write off the invoice balance amount of an invoice. oauthscope : ZohoInventory.invoices.CREATE
POST /invoices/{:invoice_id}/writeoff
Request Example
$ curl https://inventory.zoho.com/api/v1/invoices/{:invoice_id}/writeoff?organization_id=10234695 -X POST -H "Authorization: Zoho-oauthtoken 1000.41d9f2cfbd1b7a8f9e314b7aff7bc2d1.8fcc9810810a216793f385b9dd6e125f" -H "Content-Type: application/x-www-form-urlencoded;charset=UTF-8"
Response Example
HTTP/1.1 200 OK Content-Type:application/json;charset=UTF-8 { "code": 0, "message": "Invoice has been written off" }
Cancel write off
Cancel the write off amount of an invoice. oauthscope : ZohoInventory.invoices.CREATE
POST /invoices/{:invoice_id}/writeoff/cancel
Request Example
$ curl https://inventory.zoho.com/api/v1/invoices/{:invoice_id}/writeoff/cancel?organization_id=10234695 -X POST -H "Authorization: Zoho-oauthtoken 1000.41d9f2cfbd1b7a8f9e314b7aff7bc2d1.8fcc9810810a216793f385b9dd6e125f" -H "Content-Type: application/x-www-form-urlencoded;charset=UTF-8"
Response Example
HTTP/1.1 200 OK Content-Type:application/json;charset=UTF-8 { "code": 0, "message": "The write off done for this invoice has been cancelled." }
Update billing address
Updates the billing address for this invoice alone. oauthscope : ZohoInventory.invoices.UPDATE
PUT /invoices/{:invoice_id}/address/billing
Request Example
$ curl https://inventory.zoho.com/api/v1/invoices/{:invoice_id}/address/billing?organization_id=10234695 -X PUT -H "Authorization: Zoho-oauthtoken 1000.41d9f2cfbd1b7a8f9e314b7aff7bc2d1.8fcc9810810a216793f385b9dd6e125f" -H "Content-Type: application/x-www-form-urlencoded;charset=UTF-8" -F 'JSONString="{ "address": "B-1104, 11F, \nHorizon International Tower, \nNo. 6, ZhiChun Road, HaiDian District", "city": "Beijing", "state": "Beijing", "zip": 1000881, "fax": "+86-10-82637827" }"'
Response Example
HTTP/1.1 200 OK Content-Type:application/json;charset=UTF-8 { "code": 0, "message": "Billing address updated" }
ARGUMENTS
|
address
Optional
Billing address of the customer
city
Optional
City of the customer's billing address
state
Optional
State of the customer's billing address
zip
Optional
ZIP code of the contact's billing address
country
Optional
Country of the contact's billing address
fax
Optional
FAX number of the customer
|
Update shipping address
Updates the shipping address for this invoice alone. oauthscope : ZohoInventory.invoices.UPDATE
PUT /invoices/{:invoice_id}/address/shipping
Request Example
$ curl https://inventory.zoho.com/api/v1/invoices/{:invoice_id}/address/shipping?organization_id=10234695 -X PUT -H "Authorization: Zoho-oauthtoken 1000.41d9f2cfbd1b7a8f9e314b7aff7bc2d1.8fcc9810810a216793f385b9dd6e125f" -H "Content-Type: application/x-www-form-urlencoded;charset=UTF-8" -F 'JSONString="{ "address": "4900 Hopyard Rd, Suit 310", "city": "Pleasanton", "state": "CA", "zip": 945881, "country": "USA", "fax": "+1-925-924-9600" }"'
Response Example
HTTP/1.1 200 OK Content-Type:application/json;charset=UTF-8 { "code": 0, "message": "Shipping address updated" }
ARGUMENTS
|
address
Optional
Shipping address of the customer
city
Optional
City of the contact's shipping address
state
Optional
State of the Contact's shipping address
zip
Optional
ZIP code of the contact's shipping address
country
Optional
Contact's country for the given shipping address
fax
Optional
FAX number of the contact
|
List invoice templates
Get all invoice pdf templates. oauthscope : ZohoInventory.invoices.READ
Get /invoices/templates
Request Example
$ curl https://inventory.zoho.com/api/v1/invoices/templates?organization_id=10234695 -X Get -H "Authorization: Zoho-oauthtoken 1000.41d9f2cfbd1b7a8f9e314b7aff7bc2d1.8fcc9810810a216793f385b9dd6e125f" -H "Content-Type: application/x-www-form-urlencoded;charset=UTF-8"
Response Example
HTTP/1.1 200 OK Content-Type:application/json;charset=UTF-8 { "code": 0, "message": "success", "templates": [ { "template_name": "Service - Classic", "template_id": 982000000000143, "template_type": "classic" } ] }
Update invoice template
Update the pdf template associated with the invoice. oauthscope : ZohoInventory.invoices.UPDATE
PUT /invoices/{:invoice_id}/templates/{:template_id}
Request Example
$ curl https://inventory.zoho.com/api/v1/invoices/{:invoice_id}/templates/{:template_id}?organization_id=10234695 -X PUT -H "Authorization: Zoho-oauthtoken 1000.41d9f2cfbd1b7a8f9e314b7aff7bc2d1.8fcc9810810a216793f385b9dd6e125f" -H "Content-Type: application/x-www-form-urlencoded;charset=UTF-8"
Response Example
HTTP/1.1 200 OK Content-Type:application/json;charset=UTF-8 { "code": 0, "message": "Invoice information has been updated." }
List invoice payments
Get the list of payments made for an invoice. oauthscope : ZohoInventory.invoices.READ
GET /invoices/{:invoice_id}/payments
Request Example
$ curl https://inventory.zoho.com/api/v1/invoices/{:invoice_id}/payments?organization_id=10234695 -H "Authorization: Zoho-oauthtoken 1000.41d9f2cfbd1b7a8f9e314b7aff7bc2d1.8fcc9810810a216793f385b9dd6e125f" -H "Content-Type: application/x-www-form-urlencoded;charset=UTF-8"
Response Example
HTTP/1.1 200 OK Content-Type:application/json;charset=UTF-8 { "code": 0, "message": "success", "payments": [ { "payment_id": "982000000567190", "payment_number": 7, "invoice_id": 982000000567036, "invoice_payment_id": 982000000567192, "payment_mode": "cash", "date": "2013-11-18", "reference_number": 99782374, "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 : ZohoInventory.invoices.READ
GET /invoices/{:invoice_id}/creditsapplied
Request Example
$ curl https://inventory.zoho.com/api/v1/invoices/{:invoice_id}/creditsapplied?organization_id=10234695 -H "Authorization: Zoho-oauthtoken 1000.41d9f2cfbd1b7a8f9e314b7aff7bc2d1.8fcc9810810a216793f385b9dd6e125f" -H "Content-Type: application/x-www-form-urlencoded;charset=UTF-8"
Response Example
HTTP/1.1 200 OK Content-Type:application/json;charset=UTF-8 { "code": 0, "message": "success", "credits": [ { "creditnote_id": 982000000567134, "creditnotes_invoice_id": "982000000567172", "creditnotes_number": "CN-00001", "credited_date": "2013-11-18", "amount_applied": 12.2 }, {...}, {...} ] }
Apply credits
Apply the customer credits either from credit notes or excess customer payments to an invoice. Multiple credits can be applied at once. oauthscope : ZohoInventory.invoices.CREATE
POST /invoices/{:invoice_id}/credits
Request Example
$ curl https://inventory.zoho.com/api/v1/invoices/{:invoice_id}/credits?organization_id=10234695 -X POST -H "Authorization: Zoho-oauthtoken 1000.41d9f2cfbd1b7a8f9e314b7aff7bc2d1.8fcc9810810a216793f385b9dd6e125f" -H "Content-Type: application/x-www-form-urlencoded;charset=UTF-8" -F 'JSONString="{ "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
Invoice payment list
payment_id
Optional
The ID of the payment
amount_applied
Optional
The amount applied to a creditnote
apply_creditnotes
Optional
Apply existing credit note of a customer against the invoice
creditnote_id
Optional
The ID of creditnote
amount_applied
Optional
The amount applied to a creditnote
|
Delete a payment
Delete a payment made to an invoice. oauthscope : ZohoInventory.invoices.DELETE
DELETE /invoices/{:invoice_id}/payments/{:invoice_payment_id}
Request Example
$ curl https://inventory.zoho.com/api/v1/invoices/{:invoice_id}/payments/{:invoice_payment_id}?organization_id=10234695 -X DELETE -H "Authorization: Zoho-oauthtoken 1000.41d9f2cfbd1b7a8f9e314b7aff7bc2d1.8fcc9810810a216793f385b9dd6e125f" -H "Content-Type: application/x-www-form-urlencoded;charset=UTF-8"
Response Example
HTTP/1.1 200 OK Content-Type:application/json;charset=UTF-8 { "code": 0, "message": "The payment has been deleted." }
Delete applied credit
Delete a particular credit applied to an invoice. oauthscope : ZohoInventory.invoices.DELETE
DELETE /invoices/{:invoice_id}/creditsapplied/{:creditnotes_invoice_id}
Request Example
$ curl https://inventory.zoho.com/api/v1/invoices/{:invoice_id}/creditsapplied/{:creditnotes_invoice_id}?organization_id=10234695 -X DELETE -H "Authorization: Zoho-oauthtoken 1000.41d9f2cfbd1b7a8f9e314b7aff7bc2d1.8fcc9810810a216793f385b9dd6e125f" -H "Content-Type: application/x-www-form-urlencoded;charset=UTF-8"
Response Example
HTTP/1.1 200 OK Content-Type:application/json;charset=UTF-8 { "code": 0, "message": "Credits applied to an invoice have been deleted." }
Get an invoice attachment
Returns the file attached to the invoice. oauthscope : ZohoInventory.invoices.READ
GET /invoices/{:invoice_id}/attachment
Request Example
$ curl https://inventory.zoho.com/api/v1/invoices/{:invoice_id}/attachment?organization_id=10234695 -H "Authorization: Zoho-oauthtoken 1000.41d9f2cfbd1b7a8f9e314b7aff7bc2d1.8fcc9810810a216793f385b9dd6e125f" -H "Content-Type: application/x-www-form-urlencoded;charset=UTF-8"
Response Example
HTTP/1.1 200 OK Content-Type:application/json;charset=UTF-8 { "code": 0, "message": "success" }
Query Params
|
preview
Optional
Get the thumbnail of the attachment.
|
Add attachment to an invoice
Attach a file to an invoice. oauthscope : ZohoInventory.invoices.CREATE
POST /invoices/{:invoice_id}/attachment
Request Example
$ curl https://inventory.zoho.com/api/v1 /invoices/{:invoice_id}/attachment?organization_id=10234695 -X POST -H "Authorization: Zoho-oauthtoken 1000.41d9f2cfbd1b7a8f9e314b7aff7bc2d1.8fcc9810810a216793f385b9dd6e125f" -H "Content-Type: application/x-www-form-urlencoded;charset=UTF-8"
Response Example
HTTP/1.1 200 OK Content-Type:application/json;charset=UTF-8 { "code": 0, "message": "Your file has been successfully attached to the invoice." }
Query Params
|
can_send_in_mail
Optional
True to send the attachment with the invoice when emailed.
attachment
Optional
The file to be attached.Allowed Extensions:
gif, png, jpeg, jpg, bmp and pdf |
Update attachment preference
Set whether you want to send the attached file while emailing the invoice. oauthscope : ZohoInventory.invoices.UPDATE
PUT /invoices/{:invoice_id}/attachment
Request Example
$ curl https://inventory.zoho.com/api/v1 /invoices/{:invoice_id}/attachment?organization_id=10234695 -X PUT -H "Authorization: Zoho-oauthtoken 1000.41d9f2cfbd1b7a8f9e314b7aff7bc2d1.8fcc9810810a216793f385b9dd6e125f" -H "Content-Type: application/x-www-form-urlencoded;charset=UTF-8"
Response Example
HTTP/1.1 200 OK Content-Type:application/json;charset=UTF-8 { "code": 0, "message": "Invoice information has been updated." }
Query Params
|
can_send_in_mail
Required
Boolean to send the attachment with the invoice when emailed.
|
Delete an attachment
Delete the file attached to the invoice. oauthscope : ZohoInventory.invoices.DELETE
DELETE /invoices/{:invoice_id}/attachment
Request Example
$ curl https://inventory.zoho.com/api/v1/invoices/{:invoice_id}/attachment?organization_id=10234695 -X DELETE -H "Authorization: Zoho-oauthtoken 1000.41d9f2cfbd1b7a8f9e314b7aff7bc2d1.8fcc9810810a216793f385b9dd6e125f" -H "Content-Type: application/x-www-form-urlencoded;charset=UTF-8"
Response Example
HTTP/1.1 200 OK Content-Type:application/json;charset=UTF-8 { "code": 0, "message": "Your file is no longer attached to the invoice." }
List invoice comments & history
Get the complete history and comments of an invoice. oauthscope : ZohoInventory.invoices.READ
GET /invoices/{:invoice_id}/comments
Request Example
$ curl https://inventory.zoho.com/api/v1 /invoices/{:invoice_id}/comments?organization_id=10234695 -H "Authorization: Zoho-oauthtoken 1000.41d9f2cfbd1b7a8f9e314b7aff7bc2d1.8fcc9810810a216793f385b9dd6e125f" -H "Content-Type: application/x-www-form-urlencoded;charset=UTF-8"
Response Example
HTTP/1.1 200 OK Content-Type:application/json;charset=UTF-8 { "code": 0, "message": "success", "comments": [ { "comment_id": 982000000567019, "invoice_id": 982000000567114, "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" } ] }
Add comment
Add a comment for an invoice. oauthscope : ZohoInventory.invoices.CREATE
POST /invoices/{:invoice_id}/comments
Request Example
$ curl https://inventory.zoho.com/api/v1/invoices/{:invoice_id}/comments?organization_id=10234695 -X POST -H "Authorization: Zoho-oauthtoken 1000.41d9f2cfbd1b7a8f9e314b7aff7bc2d1.8fcc9810810a216793f385b9dd6e125f" -H "Content-Type: application/x-www-form-urlencoded;charset=UTF-8"
Response Example
HTTP/1.1 200 OK Content-Type:application/json;charset=UTF-8 { "code": 0, "message": "Comments added." }
Query Params
|
description
Optional
A short note added
payment_expected_date
Optional
Expected date pf payment
show_comment_to_clients
Optional
Boolean to check if the comment to be shown to the clients
|
Update comment
Update an existing comment of an invoice. oauthscope : ZohoInventory.invoices.UPDATE
PUT /invoices/{:invoice_id}/comments/:comment_id
Request Example
$ curl https://inventory.zoho.com/api/v1/invoices/{:invoice_id}/comments/:comment_id?organization_id=10234695 -X PUT -H "Authorization: Zoho-oauthtoken 1000.41d9f2cfbd1b7a8f9e314b7aff7bc2d1.8fcc9810810a216793f385b9dd6e125f" -H "Content-Type: application/x-www-form-urlencoded;charset=UTF-8"
Response Example
HTTP/1.1 200 OK Content-Type:application/json;charset=UTF-8 { "code": 0, "message": "success", "comment_id": 982000000567019, "invoice_id": 982000000567114, "description": "500GB, USB 2.0 interface 1400 rpm, protective hard case.", "commented_by_id": 982000000554041, "commented_by": "John David", "date": "2013-11-17", "date_description": "yesterday", "time": "2:02 AM", "comment_type": "system" }
Query Params
|
description
Optional
The comment on a invoice
show_comment_to_clients
Optional
Boolean to check if the comment to be shown to the clients
|
Delete a comment
Delete an invoice comment. oauthscope : ZohoInventory.invoices.DELETE
DELETE /invoices/{:invoice_id}/comments/{:comment_id}
Request Example
$ curl https://inventory.zoho.com/api/v1/invoices/{:invoice_id}/comments/{:comment_id}?organization_id=10234695 -X DELETE -H "Authorization: Zoho-oauthtoken 1000.41d9f2cfbd1b7a8f9e314b7aff7bc2d1.8fcc9810810a216793f385b9dd6e125f" -H "Content-Type: application/x-www-form-urlencoded;charset=UTF-8"
Response Example
HTTP/1.1 200 OK Content-Type:application/json;charset=UTF-8 { "code": 0, "message": "The comment has been deleted." }
Retainer Invoices
A lot of businesses collect an advance payment (or retainer) for products sold or services rendered by them. This amount collected will not be an income but a liability to the company. The revenue is earned only when the product is delivered or the service is completed, if not delivered or completed the advance payment made will be returned to the customer.
Example
{ "retainerinvoice_id": 982000000567114, "customer_name": "Bowman & Co", "retainerinvoice_number": "RET-00003", "customer_id": 982000000567001, "status": "draft", "reference_number": " ", "project_or_estimate_name": "new project", "date": "2013-11-17", "currency_id": 982000000000190, "currency_code": "USD", "is_viewed_by_client": true, "client_viewed_time": true, "total": 40.6, "balance": 40.6, "created_time": "2013-11-18T02:31:51-0800", "last_modified_time": "2013-11-18T02:31:51-0800", "is_emailed": false, "last_payment_date": " ", "has_attachment": true }
Attribute
|
retainerinvoice_id
string
ID of the retainerinvoice
customer_name
string
The name of the customer. Max-length [100]
retainerinvoice_number
string
number of the retainer invoice.Variants:
retainerinvoice_number_startswith and retainerinvoice_number_contains. Max-length [100]
customer_id
string
ID of the customer the retainer invoice has to be created.
status
string
retainer invoice status.Allowed Values:
sent, draft, overdue, paid, void, unpaid, partially_paid and viewed
reference_number
string
The reference number of the retainer invoice. Max-length [100]
project_or_estimate_name
string
date
string
The date of creation of the retainer invoice.
currency_id
string
The currenct id of the currency
currency_code
string
The currency code in which the retainer invoice is created.
is_viewed_by_client
boolean
Boolean is retainer invoice viewed by client in client portal.
client_viewed_time
boolean
client viewed time for retainer invoice in client portal.
total
string
The total amount to be paid
balance
string
The unpaid amount
created_time
string
The time of creation of the retainer invoice
last_modified_time
string
The time of last modification of the retainer invoice
is_emailed
string
Boolean check to if the email was sent
last_payment_date
string
The last payment date of the retainer invoice
has_attachment
boolean
Boolean retainer invoice has attachment
|
Create a retainerinvoice
Create a retainer invoice for your customer. oauthscope : ZohoInventory.invoices.CREATE
POST /retainerinvoices
Request Example
$ curl https://inventory.zoho.com/api/v1/retainerinvoices?organization_id=10234695 -X POST -H "Authorization: Zoho-oauthtoken 1000.41d9f2cfbd1b7a8f9e314b7aff7bc2d1.8fcc9810810a216793f385b9dd6e125f" -H "Content-Type: application/x-www-form-urlencoded;charset=UTF-8" -F 'JSONString="{ "customer_id": 982000000567001, "reference_number": " ", "date": "2013-11-17", "contact_persons": [ "982000000567003" ], "custom_fields": [ { "index": 1, "show_on_pdf": false, "value": "The value of the custom field", "label": "Delivery Date" } ], "notes": "Looking forward for your business.", "terms": "Terms & Conditions apply", "line_items": [ { "item_order": 1, "rate": 120 } ], "payment_options": { "payment_gateways": [ { "additional_field1": "standard", "gateway_name": "paypal" } ] }, "template_id": 982000000000143, "place_of_supply": "TN" }"'
Response Example
HTTP/1.1 201 Created Content-Type:application/json;charset=UTF-8 { "code": 0, "message": "The retainer invoice has been created.", "retainerinvoice": { "retainerinvoices": { "retainerinvoice_id": 982000000567114, "retainerinvoice_number": "RET-00003", "date": "2013-11-17", "status": "draft", "is_pre_gst": false, "place_of_supply": "TN", "project_id": 982000000567154, "last_payment_date": " ", "reference_number": " ", "customer_id": 982000000567001, "customer_name": "Bowman & Co", "contact_persons": [ "982000000567003" ], "currency_id": 982000000000190, "currency_code": "USD", "currency_symbol": "USD", "exchange_rate": 1, "is_viewed_by_client": true, "client_viewed_time": true, "is_inclusive_tax": false, "line_items": [ { "line_item_id": 982000000567021, "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": [ { "configured": true, "additional_field1": "standard", "gateway_name": "paypal" } ] }, "is_emailed": false, "documents": [ {...} ], "billing_address": { "address": "Suite 125, McMillan Avenue", "street2": "McMillan Avenue", "city": "San Francisco", "state": "CA", "zip": 94134, "country": "U.S.A", "fax": "+86-10-82637827" }, "shipping_address": { "address": "Suite 125, McMillan Avenue", "city": "San Francisco", "state": "CA", "zip": 94134, "country": "U.S.A", "fax": "+86-10-82637827" }, "notes": "Looking forward for your business.", "terms": "Terms & Conditions apply", "custom_fields": [ { "index": 1, "show_on_pdf": false, "value": "The value of the custom field", "label": "Delivery Date" } ], "template_id": 982000000000143, "template_name": "Service - Classic", "page_width": "8.27in", "page_height": "11.69in", "orientation": "portrait", "template_type": "classic", "created_time": "2013-11-18T02:31:51-0800", "last_modified_time": "2013-11-18T02:31:51-0800", "created_by_id": 14909000000072000, "attachment_name": "new file", "can_send_in_mail": true } } }
ARGUMENTS
|
customer_id
Required
ID of the customer the retainer invoice has to be created.
reference_number
Optional
The reference number of the retainer invoice. Max-length [100]
date
Optional
The date of creation of the retainer invoice.
contact_persons
Optional
custom_fields
Optional
Custom fields for a reatiner invoice.
index
Optional
The index of the custom field
show_on_pdf
Optional
Boolean value to check if the custom field is to be dispplayed on the pdf.
value
Optional
label
Optional
The label of the custom field.
notes
Optional
The notes added below expressing gratitude or for conveying some information.
terms
Optional
The terms added below expressing gratitude or for conveying some information.
line_items
Required
Line items of a retainer invoice.
description
Optional
The description of the line items. Max-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.
template_id
Optional
ID of the pdf template associated with the retainer invoice.
place_of_supply
India Edition only.
Optional
Place where the goods/services are supplied to. (If not given,
place of contact given for the contact will be taken) |
Query Params
|
ignore_auto_number_generation
Optional
Ignore auto invoice number generation for this invoice. This mandates the invoice number. Allowed values
true and false |
update a retainerinvoice
Update an existing invoice. oauthscope : ZohoInventory.invoices.UPDATE
PUT /retainerinvoices/:retainerinvoice_id
Request Example
$ curl https://inventory.zoho.com/api/v1/retainerinvoices/:retainerinvoice_id?organization_id=10234695 -X PUT -H "Authorization: Zoho-oauthtoken 1000.41d9f2cfbd1b7a8f9e314b7aff7bc2d1.8fcc9810810a216793f385b9dd6e125f" -H "Content-Type: application/x-www-form-urlencoded;charset=UTF-8" -F 'JSONString="{ "customer_id": 982000000567001, "reference_number": " ", "date": "2013-11-17", "contact_persons": [ "982000000567003" ], "custom_fields": [ { "index": 1, "show_on_pdf": false, "value": "The value of the custom field", "label": "Delivery Date" } ], "notes": "Looking forward for your business.", "terms": "Terms & Conditions apply", "line_items": [ { "item_order": 1, "rate": 120 } ], "payment_options": { "payment_gateways": [ { "additional_field1": "standard", "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.", "retainerinvoice": { "retainerinvoices": { "retainerinvoice_id": 982000000567114, "retainerinvoice_number": "RET-00003", "date": "2013-11-17", "status": "draft", "is_pre_gst": false, "place_of_supply": "TN", "project_id": 982000000567154, "last_payment_date": " ", "reference_number": " ", "customer_id": 982000000567001, "customer_name": "Bowman & Co", "contact_persons": [ "982000000567003" ], "currency_id": 982000000000190, "currency_code": "USD", "currency_symbol": "USD", "exchange_rate": 1, "is_viewed_by_client": true, "client_viewed_time": true, "is_inclusive_tax": false, "line_items": [ { "line_item_id": 982000000567021, "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": [ { "configured": true, "additional_field1": "standard", "gateway_name": "paypal" } ] }, "is_emailed": false, "documents": [ {...} ], "billing_address": { "address": "Suite 125, McMillan Avenue", "street2": "McMillan Avenue", "city": "San Francisco", "state": "CA", "zip": 94134, "country": "U.S.A", "fax": "+86-10-82637827" }, "shipping_address": { "address": "Suite 125, McMillan Avenue", "city": "San Francisco", "state": "CA", "zip": 94134, "country": "U.S.A", "fax": "+86-10-82637827" }, "notes": "Looking forward for your business.", "terms": "Terms & Conditions apply", "custom_fields": [ { "index": 1, "show_on_pdf": false, "value": "The value of the custom field", "label": "Delivery Date" } ], "template_id": 982000000000143, "template_name": "Service - Classic", "page_width": "8.27in", "page_height": "11.69in", "orientation": "portrait", "template_type": "classic", "created_time": "2013-11-18T02:31:51-0800", "last_modified_time": "2013-11-18T02:31:51-0800", "created_by_id": 14909000000072000, "attachment_name": "new file", "can_send_in_mail": true } } }
ARGUMENTS
|
customer_id
Required
ID of the customer the retainer invoice has to be created.
reference_number
Optional
The reference number of the retainer invoice. Max-length [100]
date
Optional
The date of creation of the retainer invoice.
contact_persons
Optional
custom_fields
Optional
Custom fields for a reatiner invoice.
index
Optional
The index of the custom field
show_on_pdf
Optional
Boolean value to check if the custom field is to be dispplayed on the pdf.
value
Optional
label
Optional
The label of the custom field.
notes
Optional
The notes added below expressing gratitude or for conveying some information.
terms
Optional
The terms added below expressing gratitude or for conveying some information.
line_items
Required
Line items of a retainer invoice.
description
Optional
The description of the line items. Max-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.
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
|
List a retainer invoices
List all retainer invoices with pagination. oauthscope : ZohoInventory.invoices.READ
GET /retainerinvoices
Request Example
$ curl https://inventory.zoho.com/api/v1/retainerinvoices?organization_id=10234695 -H "Authorization: Zoho-oauthtoken 1000.41d9f2cfbd1b7a8f9e314b7aff7bc2d1.8fcc9810810a216793f385b9dd6e125f" -H "Content-Type: application/x-www-form-urlencoded;charset=UTF-8"
Response Example
HTTP/1.1 200 OK Content-Type:application/json;charset=UTF-8 { "code": 0, "message": "success", "retainerinvoices": [ { "retainerinvoice_id": 982000000567114, "customer_name": "Bowman & Co", "retainerinvoice_number": "RET-00003", "customer_id": 982000000567001, "status": "draft", "reference_number": " ", "project_or_estimate_name": "new project", "date": "2013-11-17", "currency_id": 982000000000190, "currency_code": "USD", "is_viewed_by_client": true, "client_viewed_time": true, "total": 40.6, "balance": 40.6, "created_time": "2013-11-18T02:31:51-0800", "last_modified_time": "2013-11-18T02:31:51-0800", "is_emailed": false, "last_payment_date": " ", "has_attachment": true } ], "page_context": { "page": 1, "per_page": 200, "has_more_page": false, "report_name": "Retainer Invoices", "applied_filter": "Status.All", "sort_column": "created_time", "sort_order": "D" } }
Query Params
|
print
Optional
Print the exported pdf.
sort_column
Optional
Sort retainer invoices.Allowed Values:
customer_name, retainer invoice_number, date, due_date, total, balance and created_time
filter_by
Optional
Filter invoices by any status or payment expected date.Allowed Values:
Status.All, Status.Sent, Status.Draft, Status.OverDue, Status.Paid, Status.Void, Status.Unpaid, Status.PartiallyPaid, Status.Viewed and Date.PaymentExpectedDate
sort_order
Optional
The order for sorting
page
Optional
Number of pages
|
Get a retainer invoice
Get the details of a retainer invoice. oauthscope : ZohoInventory.invoices.READ
GET /retainerinvoices/:retainerinvoice_id
Request Example
$ curl https://inventory.zoho.com/api/v1/retainerinvoices/:retainerinvoice_id?organization_id=10234695 -H "Authorization: Zoho-oauthtoken 1000.41d9f2cfbd1b7a8f9e314b7aff7bc2d1.8fcc9810810a216793f385b9dd6e125f" -H "Content-Type: application/x-www-form-urlencoded;charset=UTF-8"
Response Example
HTTP/1.1 200 OK Content-Type:application/json;charset=UTF-8 { "code": 0, "message": "success", "retainerinvoice": { "retainerinvoice": { "retainerinvoice_id": 982000000567114, "retainerinvoice_number": "RET-00003", "date": "2013-11-17", "status": "draft", "is_pre_gst": false, "place_of_supply": "TN", "project_id": 982000000567154, "last_payment_date": " ", "reference_number": " ", "customer_id": 982000000567001, "customer_name": "Bowman & Co", "contact_persons": [ "982000000567003" ], "currency_id": 982000000000190, "currency_code": "USD", "currency_symbol": "USD", "exchange_rate": 1, "is_viewed_by_client": true, "client_viewed_time": true, "is_inclusive_tax": false, "line_items": [ { "line_item_id": 982000000567021, "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": [ { "configured": true, "additional_field1": "standard", "gateway_name": "paypal" } ] }, "is_emailed": false, "documents": [ {...} ], "billing_address": { "address": "Suite 125, McMillan Avenue", "street2": "McMillan Avenue", "city": "San Francisco", "state": "CA", "zip": 94134, "country": "U.S.A", "fax": "+86-10-82637827" }, "shipping_address": { "address": "Suite 125, McMillan Avenue", "city": "San Francisco", "state": "CA", "zip": 94134, "country": "U.S.A", "fax": "+86-10-82637827" }, "notes": "Looking forward for your business.", "terms": "Terms & Conditions apply", "custom_fields": [ { "index": 1, "show_on_pdf": false, "value": "The value of the custom field", "label": "Delivery Date" } ], "template_id": 982000000000143, "template_name": "Service - Classic", "page_width": "8.27in", "page_height": "11.69in", "orientation": "portrait", "template_type": "classic", "created_time": "2013-11-18T02:31:51-0800", "last_modified_time": "2013-11-18T02:31:51-0800", "created_by_id": 14909000000072000, "attachment_name": "new file", "can_send_in_mail": true } } }
Delete a retainer invoice
Delete an existing retainer invoice. Invoices which have payment or credits note applied cannot be deleted. oauthscope : ZohoInventory.invoices.DELETE
DELETE /retainerinvoices/:retainerinvoice_id
Request Example
$ curl https://inventory.zoho.com/api/v1/retainerinvoices/:retainerinvoice_id?organization_id=10234695 -X DELETE -H "Authorization: Zoho-oauthtoken 1000.41d9f2cfbd1b7a8f9e314b7aff7bc2d1.8fcc9810810a216793f385b9dd6e125f" -H "Content-Type: application/x-www-form-urlencoded;charset=UTF-8"
Response Example
HTTP/1.1 200 OK Content-Type:application/json;charset=UTF-8 { "code": 0, "message": "The retainer invoice has been deleted." }
Mark a retainer invoice as sent
Mark a draft retainer invoice as sent. oauthscope : ZohoInventory.invoices.CREATE
POST /retainerinvoices/:retainerinvoice_id/status/sent
Request Example
$ curl https://inventory.zoho.com/api/v1/retainerinvoices/:retainerinvoice_id/status/sent?organization_id=10234695 -X POST -H "Authorization: Zoho-oauthtoken 1000.41d9f2cfbd1b7a8f9e314b7aff7bc2d1.8fcc9810810a216793f385b9dd6e125f" -H "Content-Type: application/x-www-form-urlencoded;charset=UTF-8"
Response Example
HTTP/1.1 200 OK Content-Type:application/json;charset=UTF-8 { "code": 0, "message": "Retainer Invoice status has been changed to Sent." }
Update retainer invoice template
Update the pdf template associated with the retainer invoice. oauthscope : ZohoInventory.invoices.UPDATE
PUT /retainerinvoices/:retainerinvoice_id/templates/:template_id
Request Example
$ curl https://inventory.zoho.com/api/v1/retainerinvoices/:retainerinvoice_id/templates/:template_id?organization_id=10234695 -X PUT -H "Authorization: Zoho-oauthtoken 1000.41d9f2cfbd1b7a8f9e314b7aff7bc2d1.8fcc9810810a216793f385b9dd6e125f" -H "Content-Type: application/x-www-form-urlencoded;charset=UTF-8"
Response Example
HTTP/1.1 200 OK Content-Type:application/json;charset=UTF-8 { "code": 0, "message": "Retainer Invoice information has been updated." }
Void a retainer invoice
Mark an invoice status as void. Upon voiding, the payments and credits associated with the retainer invoices will be unassociated and will be under customer credits. oauthscope : ZohoInventory.invoices.CREATE
POST /retainerinvoices/:retainerinvoice_id/status/void
Request Example
$ curl https://inventory.zoho.com/api/v1/retainerinvoices/:retainerinvoice_id/status/void?organization_id=10234695 -X POST -H "Authorization: Zoho-oauthtoken 1000.41d9f2cfbd1b7a8f9e314b7aff7bc2d1.8fcc9810810a216793f385b9dd6e125f" -H "Content-Type: application/x-www-form-urlencoded;charset=UTF-8"
Response Example
HTTP/1.1 200 OK Content-Type:application/json;charset=UTF-8 { "code": 0, "message": "Retainer Invoice status has been changed to 'Void'." }
Mark as draft
Mark a voided retainer invoice as draft. oauthscope : ZohoInventory.invoices.CREATE
POST /retainerinvoices/:reatinerinvoice_id/status/draft
Request Example
$ curl https://inventory.zoho.com/api/v1/retainerinvoices/:reatinerinvoice_id/status/draft?organization_id=10234695 -X POST -H "Authorization: Zoho-oauthtoken 1000.41d9f2cfbd1b7a8f9e314b7aff7bc2d1.8fcc9810810a216793f385b9dd6e125f" -H "Content-Type: application/x-www-form-urlencoded;charset=UTF-8"
Response Example
HTTP/1.1 200 OK Content-Type:application/json;charset=UTF-8 { "code": 0, "message": "Status of retainer invoice changed from void to draft." }
Submit a retainer invoice for approval
Submit a retainer invoice for approval. oauthscope : ZohoInventory.invoices.CREATE
POST /retainerinvoices/:reatinerinvoice_id/submit
Request Example
$ curl https://inventory.zoho.com/api/v1/retainerinvoices/:reatinerinvoice_id/submit?organization_id=10234695 -X POST -H "Authorization: Zoho-oauthtoken 1000.41d9f2cfbd1b7a8f9e314b7aff7bc2d1.8fcc9810810a216793f385b9dd6e125f" -H "Content-Type: application/x-www-form-urlencoded;charset=UTF-8"
Response Example
HTTP/1.1 200 OK Content-Type:application/json;charset=UTF-8 { "code": 0, "message": "The Retainer Invoice has been successfully submitted for approval." }
Approve a retainer invoice.
Approve a retainer invoice. oauthscope : ZohoInventory.invoices.CREATE
POST /retainerinvoices/:reatinerinvoice_id/approve
Request Example
$ curl https://inventory.zoho.com/api/v1/retainerinvoices/:reatinerinvoice_id/approve?organization_id=10234695 -X POST -H "Authorization: Zoho-oauthtoken 1000.41d9f2cfbd1b7a8f9e314b7aff7bc2d1.8fcc9810810a216793f385b9dd6e125f" -H "Content-Type: application/x-www-form-urlencoded;charset=UTF-8"
Response Example
HTTP/1.1 200 OK Content-Type:application/json;charset=UTF-8 { "code": 0, "message": "You have approved the Retainer Invoice." }
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 : ZohoInventory.invoices.CREATE
POST /retainerinvoices/:retainerinvoice_id/email
Request Example
$ curl https://inventory.zoho.com/api/v1/retainerinvoices/:retainerinvoice_id/email?organization_id=10234695 -X POST -H "Authorization: Zoho-oauthtoken 1000.41d9f2cfbd1b7a8f9e314b7aff7bc2d1.8fcc9810810a216793f385b9dd6e125f" -H "Content-Type: application/x-www-form-urlencoded;charset=UTF-8" -F 'JSONString="{ "send_from_org_email_id": false, "to_mail_ids": [ "willsmith@bowmanfurniture.com" ], "cc_mail_ids": [ "peterparker@bowmanfurniture.com" ], "subject": "Retainer Invoice from Zillium Inc (Retainer Invoice#: RET-00001)", "body": "Dear Customer, <br><br><br><br>Thanks for your business. <br><br><br><br>The retainer invoice RET-00001 is attached with this email.<br><br>Here's an overview of the invoice for your reference. <br><br><br><br>Invoice Overview: <br><br>Invoice : INV-00001 <br><br>Date : 05 Aug 2013 <br><br>Amount : $541.82 <br><br><br><br>It was great working with you. Looking forward to working with you again.<br><br><br>\\nRegards<br>\\nZillium Inc<br>\\n\"," }"'
Response Example
HTTP/1.1 200 OK Content-Type:application/json;charset=UTF-8 { "code": 0, "message": "Your retainer invoice has been sent." }
ARGUMENTS
|
send_from_org_email_id
Optional
Boolean to trigger the email from the organization's email address
to_mail_ids
Required
Array of email address of the recipients.
cc_mail_ids
Optional
Array of email address of the recipients to be cced.
subject
Optional
The subject of the mail
body
Optional
The body of the mail
|
Query Params
|
send_customer_statement
Optional
Send customer statement pdf a with email.
send_attachment
Optional
Send the retainer invoice attachment a with the email.
attachments
Optional
Files to be attached to the email
|
Get retainer invoice email content
Get the email content of a retainer invoice. oauthscope : ZohoInventory.invoices.READ
GET /retainerinvoices/:retainerinvoice_id/email
Request Example
$ curl https://inventory.zoho.com/api/v1/retainerinvoices/:retainerinvoice_id/email?organization_id=10234695 -H "Authorization: Zoho-oauthtoken 1000.41d9f2cfbd1b7a8f9e314b7aff7bc2d1.8fcc9810810a216793f385b9dd6e125f" -H "Content-Type: application/x-www-form-urlencoded;charset=UTF-8" -F 'JSONString="{}"'
Response Example
HTTP/1.1 200 OK Content-Type:application/json;charset=UTF-8 { "code": 0, "message": "success", "gateways_configured": true, "deprecated_placeholders_used": [ {...} ], "body": "Dear Customer, <br><br><br><br>Thanks for your business. <br><br><br><br>The retainer invoice RET-00001 is attached with this email.<br><br>Here's an overview of the invoice for your reference. <br><br><br><br>Invoice Overview: <br><br>Invoice : INV-00001 <br><br>Date : 05 Aug 2013 <br><br>Amount : $541.82 <br><br><br><br>It was great working with you. Looking forward to working with you again.<br><br><br>\\nRegards<br>\\nZillium Inc<br>\\n\",", "error_list": [ {...} ], "subject": "Retainer Invoice from Zillium Inc (Retainer Invoice#: RET-00001)", "to_contacts": [ { "first_name": "Will", "selected": false, "phone": "+1-925-921-9201", "email": "willsmith@bowmanfurniture.com", "last_name": "Smith", "salutation": "Mr", "contact_person_id": 982000000567003, "mobile": "+1-4054439562" } ], "attachment_name": "new file", "file_name": "RET-00001.pdf", "from_emails": [ { "user_name": [ {...} ], "selected": false, "email": "willsmith@bowmanfurniture.com" } ], "customer_id": 982000000567001 }
ARGUMENTS
|
email_template_id
Optional
Get the email content based on a specific email template. If this param is not inputted, then the content will be based on the email template associated with the customer. If no template is associated with the customer, then default template will be used.
|
Update billing address
Updates the billing address for this retainer invoice alone. oauthscope : ZohoInventory.invoices.UPDATE
PUT /retainerinvoices/:retainerinvoice_id/address/billing
Request Example
$ curl https://inventory.zoho.com/api/v1/retainerinvoices/:retainerinvoice_id/address/billing?organization_id=10234695 -X PUT -H "Authorization: Zoho-oauthtoken 1000.41d9f2cfbd1b7a8f9e314b7aff7bc2d1.8fcc9810810a216793f385b9dd6e125f" -H "Content-Type: application/x-www-form-urlencoded;charset=UTF-8" -F 'JSONString="{ "address": "B-1104, 11F, \nHorizon International Tower, \nNo. 6, ZhiChun Road, HaiDian District", "city": "Beijing", "state": "Beijing", "zip": 1000881, "fax": "+86-10-82637827" }"'
Response Example
HTTP/1.1 200 OK Content-Type:application/json;charset=UTF-8 { "code": 0, "message": "Billing address updated" }
ARGUMENTS
|
address
Optional
address of the customer
city
Optional
city of the customer
state
Optional
state of the customer
zip
Optional
zip of the customer
country
Optional
country of the customer
fax
Optional
fax of the customer
|
List retainer invoice templates
Get all retainer invoice pdf templates. oauthscope : ZohoInventory.invoices.READ
Get /retainerinvoices/templates
Request Example
$ curl https://inventory.zoho.com/api/v1/retainerinvoices/templates?organization_id=10234695 -X Get -H "Authorization: Zoho-oauthtoken 1000.41d9f2cfbd1b7a8f9e314b7aff7bc2d1.8fcc9810810a216793f385b9dd6e125f" -H "Content-Type: application/x-www-form-urlencoded;charset=UTF-8"
Response Example
HTTP/1.1 200 OK Content-Type:application/json;charset=UTF-8 { "code": 0, "message": "success", "templates": [ { "template_name": "Service - Classic", "template_id": 982000000000143, "template_type": "classic" } ] }
List retainer payments
Get the list of payments made for a retainer invoices. oauthscope : ZohoInventory.invoices.READ
GET /customerpayments/:retainerinvoice_id
Request Example
$ curl https://inventory.zoho.com/api/v1/customerpayments/:retainerinvoice_id?organization_id=10234695 -H "Authorization: Zoho-oauthtoken 1000.41d9f2cfbd1b7a8f9e314b7aff7bc2d1.8fcc9810810a216793f385b9dd6e125f" -H "Content-Type: application/x-www-form-urlencoded;charset=UTF-8"
Response Example
HTTP/1.1 200 OK Content-Type:application/json;charset=UTF-8 { "code": 0, "message": "success", "payments": [ { "payment_id": "982000000567190", "documents": [ {...} ], "customer_id": 982000000567001, "customer_name": "Bowman & Co", "retainerinvoice_id": 982000000567114, "payment_mode": "cash", "date": "2013-11-17", "currency_id": 982000000000190, "currency_code": "USD", "exchange_rate": 1, "amount": 100, "unused_amount": 100, "bank_charges": 20, "is_client_review_settings_enabled": true, "tax_amount_withheld": 10, "discount_amount": 10, "description": "500GB, USB 2.0 interface 1400 rpm, protective hard case.", "reference_number": " ", "online_transaction_id": "7843653940324085", "invoices": [ {...} ], "retainerinvoice": { "retainerinvoice_id": 982000000567114, "retainerinvoice_number": "RET-00003", "retainerinvoice_total": 3478, "retainerinvoice_balance": 3478, "retainerinvoice_date": "2016-12-20" }, "payment_refunds": [ {...} ], "last_four_digits": "", "html_string": "", "template_id": 982000000000143, "template_name": "Service - Classic", "page_width": "8.27in", "page_height": "11.69in", "orientation": "portrait", "template_type": "classic", "attachment_name": "new file", "can_send_in_mail": true, "is_payment_drawn_details_required": true, "custom_fields": [ { "index": 1, "show_on_pdf": false, "value": "The value of the custom field", "label": "Delivery Date" } ] } ] }
Delete a retainer payment
Delete a payment made to a retainer invoice. oauthscope : ZohoInventory.invoices.DELETE
DELETE /customerpayments/:retainer_payment_id
Request Example
$ curl https://inventory.zoho.com/api/v1/customerpayments/:retainer_payment_id?organization_id=10234695 -X DELETE -H "Authorization: Zoho-oauthtoken 1000.41d9f2cfbd1b7a8f9e314b7aff7bc2d1.8fcc9810810a216793f385b9dd6e125f" -H "Content-Type: application/x-www-form-urlencoded;charset=UTF-8"
Response Example
HTTP/1.1 200 OK Content-Type:application/json;charset=UTF-8 { "code": 0, "message": "The payment has been deleted." }
Get a retainer invoice attachment
Returns the file attached to the retainer invoice. oauthscope : ZohoInventory.invoices.READ
GET /retainerinvoices/:retainerinvoice_id/attachment
Request Example
$ curl https://inventory.zoho.com/api/v1/retainerinvoices/:retainerinvoice_id/attachment?organization_id=10234695 -H "Authorization: Zoho-oauthtoken 1000.41d9f2cfbd1b7a8f9e314b7aff7bc2d1.8fcc9810810a216793f385b9dd6e125f" -H "Content-Type: application/x-www-form-urlencoded;charset=UTF-8" -F 'JSONString="{}"'
Response Example
HTTP/1.1 200 OK Content-Type:application/json;charset=UTF-8 { "code": 0, "message": "success" }
ARGUMENTS
|
preview
Optional
Get the thumbnail of the attachment.
|
Add attachment to a retainer invoice
Attach a file to an invoice. oauthscope : ZohoInventory.invoices.CREATE
POST /retainerinvoices/:retainerinvoice_id/attachment
Request Example
$ curl https://inventory.zoho.com/api/v1/retainerinvoices/:retainerinvoice_id/attachment?organization_id=10234695 -X POST -H "Authorization: Zoho-oauthtoken 1000.41d9f2cfbd1b7a8f9e314b7aff7bc2d1.8fcc9810810a216793f385b9dd6e125f" -H "Content-Type: application/x-www-form-urlencoded;charset=UTF-8" -F 'JSONString="{ "can_send_in_mail": true }"'
Response Example
HTTP/1.1 200 OK Content-Type:application/json;charset=UTF-8 { "code": 0, "message": "Your file has been attached." }
ARGUMENTS
|
can_send_in_mail
Optional
attachment
Optional
The file to be attached. It has to be sent in multipart/formdata
|
Delete an attachment
Delete the file attached to the retainer invoice. oauthscope : ZohoInventory.invoices.DELETE
DELETE /retainerinvoices/:retainerinvoice_id/documents/:document_id
Request Example
$ curl https://inventory.zoho.com/api/v1/retainerinvoices/:retainerinvoice_id/documents/:document_id?organization_id=10234695 -X DELETE -H "Authorization: Zoho-oauthtoken 1000.41d9f2cfbd1b7a8f9e314b7aff7bc2d1.8fcc9810810a216793f385b9dd6e125f" -H "Content-Type: application/x-www-form-urlencoded;charset=UTF-8"
Response Example
HTTP/1.1 200 OK Content-Type:application/json;charset=UTF-8 { "code": 0, "message": "Your file is no longer attached to the invoice." }
List retainer invoice comments & history
Get the complete history and comments of a retainer invoice. oauthscope : ZohoInventory.invoices.READ
GET /retainerinvoices/:retainernvoice_id/comments
Request Example
$ curl https://inventory.zoho.com/api/v1 /retainerinvoices/:retainernvoice_id/comments?organization_id=10234695 -H "Authorization: Zoho-oauthtoken 1000.41d9f2cfbd1b7a8f9e314b7aff7bc2d1.8fcc9810810a216793f385b9dd6e125f" -H "Content-Type: application/x-www-form-urlencoded;charset=UTF-8"
Response Example
HTTP/1.1 200 OK Content-Type:application/json;charset=UTF-8 { "code": 0, "message": "success", "comments": [ { "comments": [ { "comment_id": 982000000567019, "retainerinvoice_id": 982000000567114, "description": "500GB, USB 2.0 interface 1400 rpm, protective hard case.", "commented_by_id": 982000000554041, "commented_by": "John David", "comment_type": "system", "operation_type": "Added", "date": "2013-11-17", "date_description": "yesterday", "time": "2:38 AM", "transaction_id": "982000000567204", "transaction_type": "retainer_payment" } ] }, {...}, {...} ] }
Add comment
Add a comment for a retainer invoice. oauthscope : ZohoInventory.invoices.CREATE
POST /retainerinvoices/:retainerinvoice_id/comments
Request Example
$ curl https://inventory.zoho.com/api/v1/retainerinvoices/:retainerinvoice_id/comments?organization_id=10234695 -X POST -H "Authorization: Zoho-oauthtoken 1000.41d9f2cfbd1b7a8f9e314b7aff7bc2d1.8fcc9810810a216793f385b9dd6e125f" -H "Content-Type: application/x-www-form-urlencoded;charset=UTF-8" -F 'JSONString="{ "description": "comment added", "payment_expected_date": " ", "show_comment_to_clients": true }"'
Response Example
HTTP/1.1 200 OK Content-Type:application/json;charset=UTF-8 { "code": 0, "message": "Comments added." }
ARGUMENTS
|
description
Optional
The description of the line items. Max-length [2000]
payment_expected_date
Optional
show_comment_to_clients
Optional
Boolean to check if the comment to be shown to the clients
|
Delete a comment
Delete a retainer invoice comment. oauthscope : ZohoInventory.invoices.DELETE
DELETE /retainerinvoices/:retainerinvoice_id/comments/:comment_id
Request Example
$ curl https://inventory.zoho.com/api/v1/retainerinvoices/:retainerinvoice_id/comments/:comment_id?organization_id=10234695 -X DELETE -H "Authorization: Zoho-oauthtoken 1000.41d9f2cfbd1b7a8f9e314b7aff7bc2d1.8fcc9810810a216793f385b9dd6e125f" -H "Content-Type: application/x-www-form-urlencoded;charset=UTF-8"
Response Example
HTTP/1.1 200 OK Content-Type:application/json;charset=UTF-8 { "code": 0, "message": "The comment has been deleted." }
Update comment
Update an existing comment of a retainer invoice. oauthscope : ZohoInventory.invoices.UPDATE
PUT /retainerinvoices/:retainerinvoice_id/comments/:comment_id
Request Example
$ curl https://inventory.zoho.com/api/v1/retainerinvoices/:retainerinvoice_id/comments/:comment_id?organization_id=10234695 -X PUT -H "Authorization: Zoho-oauthtoken 1000.41d9f2cfbd1b7a8f9e314b7aff7bc2d1.8fcc9810810a216793f385b9dd6e125f" -H "Content-Type: application/x-www-form-urlencoded;charset=UTF-8" -F 'JSONString="{ "show_comment_to_clients": true }"'
Response Example
HTTP/1.1 200 OK Content-Type:application/json;charset=UTF-8 { "code": 0, "message": "The comment has been deleted.", "comment": { "comment_id": 982000000567019, "retainerinvoice_id": 982000000567114, "description": "500GB, USB 2.0 interface 1400 rpm, protective hard case.", "commented_by_id": 982000000554041, "commented_by": "John David", "date": "2013-11-17", "date_description": "yesterday", "time": "2:38 AM", "comment_type": "system" } }
ARGUMENTS
|
description
Optional
The comment on a retainer invoice
show_comment_to_clients
Optional
Boolean to check if the comment to be shown to the clients
|
Customer Payments
A payment object describes details regarding a particular customer payment. There can be multiple payments for a single invoice. Multiple invoices can be paid in a single payment as well.
Example
{ "payment_id": "9030000079467", "payment_mode": "cash", "amount": 450, "amount_refunded": 50, "date": "2016-06-05", "status": "success", "reference_number": "INV-384", "description": "Payment has been added to INV-384", "customer_id": "903000000000099", "customer_name": "Bowman Furniture", "email": "benjamin.george@bowmanfurniture.com", "invoices": [ { "invoice_id": "90300000079426", "invoice_number": "INV-384", "date": "2016-06-05", "invoice_amount": 450, "amount_applied": 450, "balance_amount": 0, "tax_amount_withheld": 0 } ], "currency_code": "USD", "currency_symbol": "$", "exchange_rate": 1, "bank_charges": 10, "custom_fields": [ { "value": 129890, "label": "label", "data_type": "text" } ] }
Attribute
|
payment_id
string
Unique ID of the payment generated by the server. Maximum length allowed [2000]
payment_mode
string
Mode through which payment is made. This can be
check, cash, creditcard, banktransfer, bankremittance, autotransaction or others. Maximum length [100]
amount
double
Amount paid in the respective payment.
amount_refunded
double
Amount that is refunded. Refunds are applicable only for payments whose payment_mode is
autotransaction. Refunds would be made to the respective card provided by the customer.
date
string
Date on which payment is made. Date Format [yyyy-mm-dd]
status
string
Status of the payment. It can either be
success or failure.
reference_number
string
Reference number generated for the payment. A string of your choice can also be used as the reference number. Maximum length of the reference number [100]
description
string
Description about the payment.
customer_id
string
Customer ID of the customer involved in the payment.
customer_name
string
Name of the customer to whom the invoice is raised. Maximum length [100]
email
string
Email address of the customer involved in the payment.
invoices
list
List of invoices associated with the payment. Each invoice object contains
invoice_id, invoice_number, date, invoice_amount, amount_applied and balance_amount.
invoice_id
string
Invoice ID of the required invoice.
invoice_number
string
Unique ID (starts with INV) of an invoice.
date
string
Date on which payment is made. Date Format [yyyy-mm-dd]
invoice_amount
double
Total amount raised for the invoice.
amount_applied
double
Amount paid for the invoice.
balance_amount
double
Unpaid amount of the invoice.
tax_amount_withheld
double
Amount withheld for tax.
currency_code
string
Currency code in which the payment is made.
currency_symbol
string
Customer's currency symbol.
exchange_rate
double
Exchange rate for the currency used in the invoices and customer's currency. The payment amount would be the multiplicative product of the original amount and the exchange rate.
bank_charges
double
Denotes any additional bank charges.
custom_fields
list
Additional fields for the payments.
value
string
Value of the custom field.
label
string
Label of the custom field.
data_type
string
Data type of the custom field.
|
Create a payment
Create a new payment. oauthscope : ZohoInventory.customerpayments.CREATE
POST /customerpayments
Request Example
$ curl https://inventory.zoho.com/api/v1/customerpayments?organization_id=10234695 -X POST -H "Authorization: Zoho-oauthtoken 1000.41d9f2cfbd1b7a8f9e314b7aff7bc2d1.8fcc9810810a216793f385b9dd6e125f" -H "Content-Type: application/x-www-form-urlencoded;charset=UTF-8" -F 'JSONString="{ "customer_id": "903000000000099", "payment_mode": "cash", "amount": 450, "date": "2016-06-05", "reference_number": "INV-384", "description": "Payment has been added to INV-384", "invoices": [ { "invoice_id": "90300000079426", "amount_applied": 450, "tax_amount_withheld": 0 } ], "exchange_rate": 1, "bank_charges": 10, "account_id": "450000000000353", "tax_account_id": "", "custom_fields": [ { "label": "label", "value": 129890 } ] }"'
Response Example
HTTP/1.1 201 Created Content-Type:application/json;charset=UTF-8 { "code": 0, "message": "The payment has been created.", "payment": { "payment_id": "9030000079467", "payment_mode": "cash", "amount": 450, "amount_refunded": 50, "bank_charges": 10, "date": "2016-06-05", "status": "success", "reference_number": "INV-384", "customer_id": "903000000000099", "customer_name": "Bowman Furniture", "email": "benjamin.george@bowmanfurniture.com", "tax_amount_withheld": 0, "invoices": [ { "invoice_id": "90300000079426", "invoice_number": "INV-384", "date": "2016-06-05", "invoice_amount": 450, "amount_applied": 450, "balance_amount": 0 } ], "exchange_rate": 1, "currency_id": "3000000002321", "currency_code": "USD", "currency_symbol": "$", "account_id": "450000000000353", "account_name": "Petty Cash", "tax_account_id": "", "tax_account_name": "", "unused_amount": 0, "last_four_digits": 1111, "custom_fields": [ { "index": 1, "value": 129890, "label": "label", "data_type": "text" } ] } }
ARGUMENTS
|
customer_id
Required
Customer ID of the customer involved in the payment.
payment_mode
Required
Mode through which payment is made. This can be
check, cash, creditcard, banktransfer, bankremittance, autotransaction or others. Maximum length [100]
amount
Required
Amount paid in the respective payment.
date
Optional
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.
invoices
Required
List of invoices associated with the payment. Each invoice object contains
invoice_id, invoice_number, date, invoice_amount, amount_applied and balance_amount.
invoice_id
Required
Invoice ID of the required invoice.
amount_applied
Required
Amount paid for the invoice.
tax_amount_withheld
Optional
Amount withheld for tax.
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.
account_id
Optional
ID of the cash/ bank account the payment has to be deposited.
tax_account_id
Optional
ID of the tax account, in case of withholding tax.
custom_fields
Optional
Additional fields for the payments.
label
Optional
Label of the custom field.
value
Optional
Value of the custom field.
|
Update a payment
Update an existing payment information. oauthscope : ZohoInventory.customerpayments.UPDATE
PUT /customerpayments/{payment_id}
Request Example
$ curl https://inventory.zoho.com/api/v1/customerpayments/{payment_id}?organization_id=10234695 -X PUT -H "Authorization: Zoho-oauthtoken 1000.41d9f2cfbd1b7a8f9e314b7aff7bc2d1.8fcc9810810a216793f385b9dd6e125f" -H "Content-Type: application/x-www-form-urlencoded;charset=UTF-8" -F 'JSONString="{ "customer_id": "903000000000099", "payment_mode": "cash", "amount": 450, "date": "2016-06-05", "reference_number": "INV-384", "description": "Payment has been added to INV-384", "invoices": [ { "invoice_id": "90300000079426", "amount_applied": 450, "tax_amount_withheld": 0 } ], "exchange_rate": 1, "bank_charges": 10, "account_id": "450000000000353", "tax_account_id": "", "custom_fields": [ { "label": "label", "value": 129890 } ] }"'
Response Example
HTTP/1.1 200 OK Content-Type:application/json;charset=UTF-8 { "code": 0, "message": "The payment details have been updated.", "payment": { "payment_id": "9030000079467", "payment_mode": "cash", "amount": 450, "amount_refunded": 50, "bank_charges": 10, "date": "2016-06-05", "status": "success", "reference_number": "INV-384", "customer_id": "903000000000099", "customer_name": "Bowman Furniture", "email": "benjamin.george@bowmanfurniture.com", "tax_amount_withheld": 0, "invoices": [ { "invoice_id": "90300000079426", "invoice_number": "INV-384", "date": "2016-06-05", "invoice_amount": 450, "amount_applied": 450, "balance_amount": 0 } ], "exchange_rate": 1, "currency_id": "3000000002321", "currency_code": "USD", "currency_symbol": "$", "account_id": "450000000000353", "account_name": "Petty Cash", "tax_account_id": "", "tax_account_name": "", "unused_amount": 0, "last_four_digits": 1111, "custom_fields": [ { "index": 1, "value": 129890, "label": "label", "data_type": "text" } ] } }
ARGUMENTS
|
customer_id
Required
Customer ID of the customer involved in the payment.
payment_mode
Required
Mode through which payment is made. This can be
check, cash, creditcard, banktransfer, bankremittance, autotransaction or others. Maximum length [100]
amount
Required
Amount paid in the respective payment.
date
Optional
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.
invoices
Required
List of invoices associated with the payment. Each invoice object contains
invoice_id, invoice_number, date, invoice_amount, amount_applied and balance_amount.
invoice_id
Required
Invoice ID of the required invoice.
amount_applied
Required
Amount paid for the invoice.
tax_amount_withheld
Optional
Amount withheld for tax.
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.
account_id
Optional
ID of the cash/ bank account the payment has to be deposited.
tax_account_id
Optional
ID of the tax account, in case of withholding tax.
custom_fields
Optional
Additional fields for the payments.
label
Optional
Label of the custom field.
value
Optional
Value of the custom field.
|
Retrieve a payment
Details of an existing payment. oauthscope : ZohoInventory.customerpayments.READ
GET /customerpayments/{payment_id}
Request Example
$ curl https://inventory.zoho.com/api/v1/customerpayments/{payment_id}?organization_id=10234695 -H "Authorization: Zoho-oauthtoken 1000.41d9f2cfbd1b7a8f9e314b7aff7bc2d1.8fcc9810810a216793f385b9dd6e125f" -H "Content-Type: application/x-www-form-urlencoded;charset=UTF-8"
Response Example
HTTP/1.1 200 OK Content-Type:application/json;charset=UTF-8 { "code": 0, "message": "success", "payment": { "payment_id": "9030000079467", "payment_mode": "cash", "amount": 450, "amount_refunded": 50, "bank_charges": 10, "date": "2016-06-05", "status": "success", "reference_number": "INV-384", "customer_id": "903000000000099", "customer_name": "Bowman Furniture", "email": "benjamin.george@bowmanfurniture.com", "tax_amount_withheld": 0, "invoices": [ { "invoice_id": "90300000079426", "invoice_number": "INV-384", "date": "2016-06-05", "invoice_amount": 450, "amount_applied": 450, "balance_amount": 0 } ], "exchange_rate": 1, "currency_id": "3000000002321", "currency_code": "USD", "currency_symbol": "$", "account_id": "450000000000353", "account_name": "Petty Cash", "tax_account_id": "", "tax_account_name": "", "unused_amount": 0, "last_four_digits": 1111, "custom_fields": [ { "index": 1, "value": 129890, "label": "label", "data_type": "text" } ] } }
List Customer Payments
List all the payments made by your customer. oauthscope : ZohoInventory.customerpayments.READ
GET /customerpayments
Request Example
$ curl https://inventory.zoho.com/api/v1/customerpayments?organization_id=10234695 -H "Authorization: Zoho-oauthtoken 1000.41d9f2cfbd1b7a8f9e314b7aff7bc2d1.8fcc9810810a216793f385b9dd6e125f" -H "Content-Type: application/x-www-form-urlencoded;charset=UTF-8"
Response Example
HTTP/1.1 200 OK Content-Type:application/json;charset=UTF-8 { "code": 0, "message": "success", "customerpayments": [ { "payment_id": "9030000079467", "payment_number": "2", "invoice_number": "INV-384", "date": "2016-06-05", "payment_mode": "cash", "amount": 450, "bcy_amount": 450, "unused_amount": 0, "account_id": "450000000000353", "account_name": "Petty Cash", "description": "Payment has been added to INV-384", "reference_number": "INV-384", "customer_id": "903000000000099", "customer_name": "Bowman Furniture" }, {...}, {...} ] }
Query Params
|
customer_name
Optional
Search payments by customer name. Variants:
customer_name_startswith and customer_name_contains. Maximum length [100]
reference_number
Optional
Search payments by reference number. Variants:
reference_number_startswith and reference_number_contains. Maximum length [100]
date
Optional
Date on which payment is made. Date Format [yyyy-mm-dd]
amount
Optional
Search payments by payment amount. Variants:
amount_less_than, amount_less_equals, amount_greater_than and amount_greater_equals
notes
Optional
Search payments by customer notes. Variants:
notes_startswith and notes_contains
payment_mode
Optional
Search payments by payment mode. Variants:
payment_mode_startswith and payment_mode_contains
filter_by
Optional
Filter payments by mode.Allowed Values:
PaymentMode.All, PaymentMode.Check, PaymentMode.Cash, PaymentMode.BankTransfer, PaymentMode.Paypal, PaymentMode.CreditCard, PaymentMode.GoogleCheckout, PaymentMode.Credit, PaymentMode.Authorizenet, PaymentMode.BankRemittance, PaymentMode.Payflowpro, PaymentMode.Stripe, PaymentMode.TwoCheckout, PaymentMode.Braintree and PaymentMode.Others
sort_column
Optional
Sort based on selected column
search_text
Optional
Search payments by reference number or customer name or payment description. Maximum length [100]
|
Delete a payment
Delete an existing payment. oauthscope : ZohoInventory.customerpayments.DELETE
DELETE /customerpayments/{payment_id}
Request Example
$ curl https://inventory.zoho.com/api/v1/customerpayments/{payment_id}?organization_id=10234695 -X DELETE -H "Authorization: Zoho-oauthtoken 1000.41d9f2cfbd1b7a8f9e314b7aff7bc2d1.8fcc9810810a216793f385b9dd6e125f" -H "Content-Type: application/x-www-form-urlencoded;charset=UTF-8"
Response Example
HTTP/1.1 200 OK Content-Type:application/json;charset=UTF-8 { "code": 0, "message": "The payment has been deleted." }
Sales Returns
A Return Material Authorization (RMA) or Sales Return is the process of a seller accepting a purchased item back from the consumer. In turn, the customer receives credit, cash refund or a replacement.
Example
{ "salesreturn_id": 4815000000044972, "salesreturn_number": "RMA-00001", "date": "2015-05-28", "reason": "Sample Note", "line_items": [ { "line_item_id": 4815000000044897, "item_id": 4815000000044100, "name": "Laptop-white/15inch/dell", "description": "Just a sample description.", "unit": "qty", "rate": 122, "salesorder_item_id": 4815000000044892, "quantity": 3, "non_receive_quantity": 2, "warehouse_id": 130426000000664020, "warehouse_name": "WarehouseName" } ], "comments": [ { "comment_id": 16115000000097016, "salesreturn_id": 4815000000044972, "commented_by": "John", "date": "2015-05-28", "date_description": "few seconds ago", "time": "2:18 PM", "operation_type": "Updated", "transaction_id": 1232423434, "transaction_type": "salesreturn" } ], "salesreturn_status": "approved", "receive_status": "received", "refund_status": "refunded", "salesorder_id": 4815000000044936, "salesorder_number": "SO-00032", "salesreturnreceives": [ { "receive_id": 4815000000045035, "receive_number": "PR-00002", "date": "2015-05-28", "notes": "Sample Note" } ], "creditnotes": [ { "creditnote_id": 90300000072369, "creditnote_number": "CN-0029", "status": "closed", "date": "2015-05-28", "total": 2670 } ], "customer_id": 4815000000044080, "customer_name": "Molly", "refunded_amount": 2670 }
Attribute
|
salesreturn_id
long
Unique ID generated by the server for the Sales Return.
salesreturn_number
string
Return Merchandise Authorisation (RMA) number of the Sales Return.
date
string
Date on which the entity was created.
reason
string
The reason for raising a Sales Return.
line_items
list
The underlying items in a Sales Return
line_item_id
long
Unique ID generated by the server for each line item. This is used as an identifier.
item_id
long
Unique ID generated by the server for the item. This is used as an identifier.
name
string
Name of the line item.
description
string
Description of the line item.
unit
string
Measurement unit of the line item.
rate
double
Price of the line item in an entity.
salesorder_item_id
long
Unique ID generated by the server for each line item in a sales order.
quantity
double
The quantity that can be received for the line item.
non_receive_quantity
double
The quantity that cannot be received for the line item.
warehouse_id
long
Unique ID generated by the server for each warehouse
warehouse_name
string
Name of the warehouse
comments
list
History related to the Sales Return.
comment_id
long
Unique ID generated by the server for the comment(history). This is used as an identifier.
salesreturn_id
long
Unique ID generated by the server for the Sales Return.
commented_by
string
Indicates the user who performed the action on the purchase order.
comment_type
string
Indicates the type of the action
date
string
Date on which the entity was created.
date_description
string
Indicates the time duration since the action was performed
time
string
Indicates the time when the action was performed
operation_type
string
Type of operation performed on the transaction
transaction_id
long
Unique ID generated by the server for the transaction. This is used as an identifier.
transaction_type
string
Indicates the type of transaction.
salesreturn_status
string
Status of the Sales Return.
receive_status
string
Receive status of the Sales Return
refund_status
string
Refund status of the Sales Return
salesorder_id
long
Unique ID generated by the server for the Sales Order from which the Sales Return is created.
salesorder_number
string
Unique sales order number for each sales order.
salesreturnreceives
list
List of sales return receives for the sales return
receive_id
long
Unique ID generated by the server for the Sales Return Receive. This is used as an identifier.
receive_number
string
Unique Sales Return Receive Number
date
string
Date on which the entity was created.
notes
string
Notes for the current entity.
creditnotes
list
List of credit notes associated with a sales return.
creditnote_id
string
Unique ID of the credit note generated by the server.
creditnote_number
string
Unique number generated (starts with CN) which will be displayed in the interface and credit notes. Max-Length [100]
status
string
Status of the credit note.
date
string
Date on which the entity was created.
total
double
Total amount on the credit note.
customer_id
long
Unique ID generated by the server for the customer.
customer_name
string
Name of the customer.
refunded_amount
double
Total amount refunded to the customer.
|
Create a Sales Return
Creation of Sales Return. Sales return can be created for all the shipped units of the items in a sales order.oauthscope : ZohoInventory.salesreturns.CREATE
POST /salesreturns
Request Example
$ curl https://inventory.zoho.com/api/v1/salesreturns?organization_id=10234695 -X POST -H "Authorization: Zoho-oauthtoken 1000.41d9f2cfbd1b7a8f9e314b7aff7bc2d1.8fcc9810810a216793f385b9dd6e125f" -H "Content-Type: application/x-www-form-urlencoded;charset=UTF-8" -F 'JSONString="{ "salesreturn_number": "RMA-00001", "date": "2015-05-28", "reason": "Sample Note", "line_items": [ { "item_id": 4815000000044100, "salesorder_item_id": 4815000000044892, "quantity": 3, "non_receive_quantity": 2, "warehouse_id": 130426000000664020 } ] }"'
Response Example
HTTP/1.1 201 Created Content-Type:application/json;charset=UTF-8 { "code": 0, "message": "Return created successfully", "salesreturn": { "salesreturn_id": 4815000000044972, "salesreturn_number": "RMA-00001", "date": "2015-05-28", "reason": "Sample Note", "line_items": [ { "line_item_id": 4815000000044897, "item_id": 4815000000044100, "name": "Laptop-white/15inch/dell", "description": "Just a sample description.", "unit": "qty", "rate": 122, "salesorder_item_id": 4815000000044892, "quantity": 3, "non_receive_quantity": 2, "warehouse_id": 130426000000664020, "warehouse_name": "WarehouseName" } ], "comments": [ { "comment_id": 16115000000097016, "salesreturn_id": 4815000000044972, "commented_by": "John", "date": "2015-05-28", "date_description": "few seconds ago", "time": "2:18 PM", "operation_type": "Updated", "transaction_id": 1232423434, "transaction_type": "salesreturn" } ], "salesreturn_status": "approved", "salesorder_id": 4815000000044936, "salesorder_number": "SO-00032" } }
ARGUMENTS
|
salesreturn_number
Optional
Return Merchandise Authorisation (RMA) number of the Sales Return.
date
Optional
Date on which the entity was created.
reason
Optional
The reason for raising a Sales Return.
line_items
Required
The underlying items in a Sales Return
item_id
Optional
Unique ID generated by the server for the item. This is used as an identifier.
salesorder_item_id
Optional
Unique ID generated by the server for each line item in a sales order.
quantity
Optional
The quantity that can be received for the line item.
non_receive_quantity
Optional
The quantity that cannot be received for the line item.
warehouse_id
Optional
Unique ID generated by the server for each warehouse
|
Query Params
|
salesorder_id
Optional
Unique ID generated by the server for the Sales Order from which the Sales Return is created.
|
Update a Sales Return
Updation of Sales Return.oauthscope : ZohoInventory.salesreturns.UPDATE
PUT /salesreturns/{salesreturn_id}
Request Example
$ curl https://inventory.zoho.com/api/v1/salesreturns/{salesreturn_id}?organization_id=10234695 -X PUT -H "Authorization: Zoho-oauthtoken 1000.41d9f2cfbd1b7a8f9e314b7aff7bc2d1.8fcc9810810a216793f385b9dd6e125f" -H "Content-Type: application/x-www-form-urlencoded;charset=UTF-8" -F 'JSONString="{ "salesreturn_number": "RMA-00001", "date": "2015-05-28", "reason": "Sample Note", "line_items": [ { "line_item_id": 4815000000044897, "item_id": 4815000000044100, "salesorder_item_id": 4815000000044892, "quantity": 3, "non_receive_quantity": 2, "warehouse_id": 130426000000664020 } ] }"'
Response Example
HTTP/1.1 200 OK Content-Type:application/json;charset=UTF-8 { "code": 0, "message": "Return updated successfully", "salesreturn": { "salesreturn_id": 4815000000044972, "salesreturn_number": "RMA-00001", "date": "2015-05-28", "reason": "Sample Note", "line_items": [ { "line_item_id": 4815000000044897, "item_id": 4815000000044100, "name": "Laptop-white/15inch/dell", "description": "Just a sample description.", "unit": "qty", "rate": 122, "salesorder_item_id": 4815000000044892, "quantity": 3, "non_receive_quantity": 2, "warehouse_id": 130426000000664020, "warehouse_name": "WarehouseName" } ], "comments": [ { "comment_id": 16115000000097016, "salesreturn_id": 4815000000044972, "commented_by": "John", "date": "2015-05-28", "date_description": "few seconds ago", "time": "2:18 PM", "operation_type": "Updated", "transaction_id": 1232423434, "transaction_type": "salesreturn" } ], "salesreturn_status": "approved", "receive_status": "received", "refund_status": "refunded", "salesorder_id": 4815000000044936, "salesorder_number": "SO-00032", "salesreturnreceives": [ { "receive_id": 4815000000045035, "receive_number": "PR-00002", "date": "2015-05-28", "notes": "Sample Note", "line_items": [ { "line_item_id": 4815000000044897, "item_id": 4815000000044100, "name": "Laptop-white/15inch/dell", "unit": "qty", "quantity": 3 } ] } ], "creditnotes": [ {