<menuitem id="nqfdf"><menu id="nqfdf"></menu></menuitem>
  • <div id="nqfdf"></div>
  • <dl id="nqfdf"><s id="nqfdf"></s></dl>
    API Documentation
    Introduction

    Introduction

    API Root Endpoint

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

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

    Zoho Books API is built using REST principles which ensures predictable URLs that makes writing applications easy. This API follows HTTP rules, enabling a wide range of HTTP clients can be used to interact with the API.

    Every resource is exposed as a URL. The URL of each resource can be obtained by accessing the API Root Endpoint.

    Getting Started

    Example

        
    $ curl https://books.zoho.com/api/v3/organizations?organization_id=10234695 -H 'Authorization: Zoho-oauthtoken 1000.41d9f2cfbd1b7a8f9e314b7aff7bc2d1.8fcc9810810a216793f385b9dd6e125f'

    To use our API you must satisfy these prerequistes

    1. A valid Zoho username and password.
    2. An Authentication Token - authtoken in short!

    Authentication

    All Zoho Books API need to be authenticated using an authtoken.

    You can obtain an authtoken in any one of the following ways:

    1. Through a URL in your browser. (To be deprecated)
    2. Programmatically using the Zoho Accounts API. (To be deprecated)

    Sample Success Response

    # #Fri Apr 11 06:14:13 PST 2016 AUTHTOKEN=ba4604e8e433g9c892e360d53463oec5 RESULT=TRUE

    Sample Error Response

    # #Fri Apr 11 06:32:13 PST 2016 CAUSE=INVALID_API_AUTHTOKEN_SCOPE RESULT=FALSE

    In your browser

    Obtaining an authtoken in your browser is very simple. Login to your Zoho Account and go to the URL below.

    https://accounts.zoho.com/apiauthtoken/create?SCOPE=ZohoBooks/booksapi

    Programmatically using the API

    If you have chosen to obtain your authtoken via an API, please follow the instructions given below:

    Submit an HTTP POST request to the below URL.

    https://accounts.zoho.com/apiauthtoken/create.

    The POST body should include a string in the below format.

    ?SCOPE=ZohoBooks/booksapi&EMAIL_ID=[ZohoID/EmailID]&PASSWORD=[Password]

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

    Parameter Description
    SCOPE ZohoBooks/booksapi
    EMAIL_ID Your Zoho ID or Email ID.
    PASSWORD Your Zoho password or your TFA*

    * To know more about TFA and creating application password click here.

    Points To Note

    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

    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=ZohoBooks.invoices.CREATE,ZohoBooks.invoices.READ,ZohoBooks.invoices.UPDATE,ZohoBooks.invoices.DELETE&client_id=1000.0SRSZSY37WMZ69405H3TMYI2239V&state=testing&response_type=code&redirect_uri=http://www.8681910.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 : ZohoBooks.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.8681910.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 : ZohoBooks.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.8681910.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.

    List of scopes available in Zoho Books :

    Scope Description
    contacts To access contacts related APIs
    Availabe types: ZohoBooks.contacts.Create, ZohoBooks.contacts.UPDATE, ZohoBooks.contacts.READ, ZohoBooks.contacts.DELETE
    settings To access items, expense categories, users, taxes, currencies, opening balances related APIs
    Availabe types: ZohoBooks.settings.Create, ZohoBooks.settings.UPDATE, ZohoBooks.settings.READ, ZohoBooks.settings.DELETE
    estimates To access estimates related APIs
    Availabe types: ZohoBooks.estimates.Create, ZohoBooks.estimates.UPDATE, ZohoBooks.estimates.READ, ZohoBooks.estimates.DELETE
    invoices To access invoices related APIs
    Availabe types: ZohoBooks.invoices.Create, ZohoBooks.invoices.UPDATE, ZohoBooks.invoices.READ, ZohoBooks.invoices.DELETE
    customerpayments To access customer payments related APIs
    Availabe types: ZohoBooks.customerpayments.Create, ZohoBooks.customerpayments.UPDATE, ZohoBooks.customerpayments.READ, ZohoBooks.customerpayments.DELETE
    creditnotes To access credit notes related APIs
    Availabe types: ZohoBooks.creditnotes.Create, ZohoBooks.creditnotes.UPDATE, ZohoBooks.creditnotes.READ, ZohoBooks.creditnotes.DELETE
    projects To access projects related APIs
    Availabe types: ZohoBooks.projects.Create, ZohoBooks.projects.UPDATE, ZohoBooks.projects.READ, ZohoBooks.projects.DELETE
    expenses To access expenses related APIs
    Availabe types: ZohoBooks.expenses.Create, ZohoBooks.expenses.UPDATE, ZohoBooks.expenses.READ, ZohoBooks.expenses.DELETE
    salesorder To access salesorder related APIs
    Availabe types: ZohoBooks.salesorders.Create, ZohoBooks.salesorders.UPDATE, ZohoBooks.salesorders.READ, ZohoBooks.salesorders.DELETE
    purchaseorder To access purchaseorder related APIs
    Availabe types: ZohoBooks.purchaseorders.Create, ZohoBooks.purchaseorders.UPDATE, ZohoBooks.purchaseorders.READ, ZohoBooks.purchaseorders.DELETE
    bills To access bills related APIs
    Availabe types: ZohoBooks.bills.Create, ZohoBooks.bills.UPDATE, ZohoBooks.bills.READ, ZohoBooks.bills.DELETE
    debitnotes To access debitnote related APIs
    Availabe types: ZohoBooks.debitnotes.Create, ZohoBooks.debitnotes.UPDATE, ZohoBooks.debitnotes.READ, ZohoBooks.debitnotes.DELETE
    vendorpayments To access vendorpayment related APIs
    Availabe types: ZohoBooks.vendorpayments.Create, ZohoBooks.vendorpayments.UPDATE, ZohoBooks.vendorpayments.READ, ZohoBooks.vendorpayments.DELETE
    banking To access banking related APIs
    Availabe types: ZohoBooks.banking.Create, ZohoBooks.banking.UPDATE, ZohoBooks.banking.READ, ZohoBooks.banking.DELETE
    accountants To access accountant related APIs
    Availabe types: ZohoBooks.accountants.Create, ZohoBooks.accountants.UPDATE, ZohoBooks.accountants.READ, ZohoBooks.accountants.DELETE

    Organization ID

    Request Example

    $ curl https://books.zoho.com/api/v3/organizations -H 'Authorization: Zoho-oauthtoken 1000.41d9f2cfbd1b7a8f9e314b7aff7bc2d1.8fcc9810810a216793f385b9dd6e125f'

    Response Example

    HTTP/1.1 200 OK Content-Type:application/json;charset=UTF-8 { "code": 0, "message": "success", "organizations": [ { "organization_id": "10234695", "name": "Zillum", "contact_name": "John Smith", "email": "[email protected]", "is_default_org": false, "language_code": "en", "fiscal_year_start_month": 0, "account_created_date": "2016-02-18", "time_zone": "PST", "is_org_active": true, "currency_id": "460000000000097", "currency_code": "USD", "currency_symbol": "$", "currency_format": "###,##0.00", "price_precision": 2 }, {...}, {...} ]

    In Zoho Books, your business is termed as an organization. If you have multiple businesses, you simply set each of those up as an individual organization. Each organization is an independent Zoho Books Organization with it’s own organization ID, base currency, time zone, language, contacts, reports, etc.

    The parameter organization_id along with the organization ID should be sent in with every API request to identify the organization.

    The organization_id can be obtained from the GET /organizations API’s JSON response. Alternatively, it can be obtained from the Manage Organizations page in the admin console:

    Login to the Zoho Books admin console. Click the drop down with organization’s name as the label and click Manage Organizations.

    Manage Organizations

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

    Organization ID

    HTTP Methods

    Using GET method, you can get the list of resources or details of a particular instance of a resource. To get a list of contacts
    $ curl https://books.zoho.com/api/v3/contacts?organization_id=10234695 -H 'Authorization: Zoho-oauthtoken 1000.41d9f2cfbd1b7a8f9e314b7aff7bc2d1.8fcc9810810a216793f385b9dd6e125f'
    To get the details of a contact referred to by a specified contact_id
    $ curl https://books.zoho.com/api/v3/contacts/903000000000099?organization_id=10234695 -H 'Authorization: Zoho-oauthtoken 1000.41d9f2cfbd1b7a8f9e314b7aff7bc2d1.8fcc9810810a216793f385b9dd6e125f'

    Zoho Books API uses appropriate HTTP verbs for every action.

    Method Description
    GET Used for retrieving resources.
    POST Used for creating resources and performing resource actions.
    PUT Used for updating resources.
    DELETE Used for deleting resources.

    Response

    Response Structure

    The response structure for the Books API follows the below format.
    { "code" : 0, "message" : "success", "invoice" : { "invoice_id" : "..." } }

    Request Example

    $ curl https://books.zoho.com/api/v3/invoices/7000000079426?organization_id=10234695 -H 'Authorization: Zoho-oauthtoken 1000.41d9f2cfbd1b7a8f9e314b7aff7bc2d1.8fcc9810810a216793f385b9dd6e125f' -H 'Accept: application/pdf'
    OR
    $ curl https://books.zoho.com/api/v3/invoices/7000000079426?accept=pdf \ '&organization_id=10234695' -H 'Authorization: Zoho-oauthtoken 1000.41d9f2cfbd1b7a8f9e314b7aff7bc2d1.8fcc9810810a216793f385b9dd6e125f'

    Responses will be in the JSON format.

    Node Name Description
    code Zoho Books error code. This will be zero for a success response and non-zero in case of an error.
    message Message for the invoked API.
    resource name Comprises the invoked API’s Data.

    Response Header Example

    HTTP/1.1 200 OK Content-Disposition: attachment; filename="INV-384.pdf" Content-Type: application/pdf;charset=UTF-8


    Other Formats

    Certain APIs support csv and pdf formats as well for which the required response format needs to be specified in the respective request’s Accept header or accept query parameter.



















    Date

    All timestamps are returned in the ISO 8601 format - YYYY-MM-DDThh:mm:ssTZD.

    Example: 2016-06-11T17:38:06-0700

    Errors

    Request Example

    $ curl https://books.zoho.com/api/v3/invoices/700000007942?organization_id=10234695 -H 'Authorization: Zoho-oauthtoken 1000.41d9f2cfbd1b7a8f9e314b7aff7bc2d1.8fcc9810810a216793f385b9dd6e125f'

    Response Example

    HTTP/1.1 201 Successfully Created Content-Type: application/json;charset=UTF-8 { "code": 0, "message": "Successfully created." }
    HTTP/1.1 404 Not Found Content-Type: application/json;charset=UTF-8 { "code": 1002, "message": "Invoice does not exist." }
    HTTP/1.1 500 Internal error Content-Type: application/json;charset=UTF-8 { "code": 1000, "message": "Internal error" }

    Zoho Books uses HTTP status codes to indicate success or failure of an API call. In general, status codes in the 2xx range means success, 4xx range means there was an error in the provided information, and those in the 5xx range indicate server side errors. Commonly used HTTP status codes are listed below.

    HTTP Status Codes

    Status Code Descriptions
    2xxSuccess
    4xxBad request sent to server
    5xxServer side error
    Status Code Description
    200 SuccessThe request was successfully completed.
    201 CreatedThe request was a success and one or more resources have been created.
    400 Bad requestThe request cannot be performed. Usually because of malformed parameter or missing parameter.
    401 Unauthorized (Invalid AuthToken)Request was rejected because of invalid AuthToken.
    403 ForbiddenThe user does not have enough permission or possibly not an user of the respective organization to access the resource.
    404 URL Not Found The URL you’ve sent is wrong. It’s possible that the resource you’ve requested has been moved to another URL.
    405 Method Not AllowedThe requested resource does not support the HTTP method used. For example, requesting List of all customers API with PUT as the HTTP method.
    406 Not AcceptableThe requested response type is not supported by the client.
    429 Too many requests Too many requests within a certain time frame. To know more about api call limits, click here.
    500 Server errorZoho Books server encountered an error which prevents it from fulfilling the request. Although this rarely happens, we recommend you to contact us at [email protected] if you receive this error.

    Pagination

    Example

    $ curl https://books.zoho.com/api/v3/contacts?page=2&per_page=25 { "code": 0, "message": "success", "contacts": [ {...}, {...} ], "page_context": { "page": 2, "per_page": 25, "has_more_page": false } }

    Zoho Books provides APIs to retrieve lists of contacts, plans and other resources - paginated to 200 items by default. The pagination information will be included in the list API response under the node name page_context.

    API Call Limit

    API calls are limited to provide better quality of service and availability to all the users. The limits on total calls are illustrated below:

    API Collection

    To try out our API, you can use the Postman, a REST client. You can download our API collection and give it a swing. Just click the button below.

    After importing the collection, you have to configure the environment. You can either do it manualy or simply import our sample environment file and follow the steps given below.

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

      domain_url: books.zoho.com

      Organization.Organization_ID: organization ID

      User.Auth_Token: authtoken

    3. In the Postman app, click the settings icon (cog icon) on the top-right and go to
      Manage Environment
    4. Click the Import button and upload this updated sample file and complete the process

    Contacts

    The list of contacts created.

    Example

    { "contact_name": "Bowman and Co", "company_name": "Bowman and Co", "first_name": "Will", "last_name": "Smith", "email": "[email protected]", "phone": "+1-925-921-9201", "facebook": "zoho", "twitter": "zoho", "billing_address": { "attention": "Mr.John", "address": "4900 Hopyard Rd", "street2": "Suite 310", "state_code": "CA", "city": "Pleasanton", "state": "CA", "zip": 94588, "country": "U.S.A", "fax": "+1-925-924-9600", "phone": "+1-925-921-9201" }, "shipping_address": { "attention": "Mr.John", "address": "4900 Hopyard Rd", "street2": "Suite 310", "state_code": "CA", "city": "Pleasanton", "state": "CA", "zip": 94588, "country": "U.S.A", "fax": "+1-925-924-9600", "phone": "+1-925-921-9201" }, "contact_persons": [ { "salutation": "Mr", "first_name": "Will", "last_name": "Smith", "email": "[email protected]", "phone": "+1-925-921-9201", "mobile": "+1-4054439562", "designation": "Sales Executive", "department": "Sales and Marketing", "skype": "Zoho", "is_primary_contact": true, "enable_portal": true } ] }

    Attribute

    contact_name
    string
    Display Name of the contact. Max-length [200]
    company_name
    string
    Company Name of the contact. Max-length [200]
    first_name
    string
    Max-length [100]
    last_name
    string
    Max-length [100]
    email
    string
    Email address of the contact person.
    phone
    string
    Search contacts by phone number of the contact person. Variants: phone_startswith and phone_contains
    facebook
    string
    Facebook profile account. max-length [100]
    twitter
    string
    Twitter account. max-length [100]
    language_code
    string
    language of a contact. allowed values de,en,es,fr,it,ja,nl,pt,pt_br,sv,zh,en_gb
    billing_address
    object
    Billing address of the contact.
    attention
    string
    address
    string
    Max-length [500]
    street2
    string
    state_code
    string
    city
    string
    City of the customer’s billing address.
    state
    string
    State of the customer’s billing address.
    zip
    string
    Zip code of the customer’s billing address.
    country
    string
    Country of the customer’s billing address.
    fax
    string
    Customer's fax number.
    phone
    string
    Search contacts by phone number of the contact person. Variants: phone_startswith and phone_contains
    shipping_address
    object
    Customer's shipping address object.
    attention
    string
    address
    string
    Max-length [500]
    street2
    string
    state_code
    string
    city
    string
    City of the customer’s billing address.
    state
    string
    State of the customer’s billing address.
    zip
    string
    Zip code of the customer’s billing address.
    country
    string
    Country of the customer’s billing address.
    fax
    string
    Customer's fax number.
    phone
    string
    Search contacts by phone number of the contact person. Variants: phone_startswith and phone_contains
    contact_persons
    list
    salutation
    string
    Salutation for the contact
    first_name
    string
    Max-length [100]
    last_name
    string
    Max-length [100]
    email
    string
    Email address of the contact person.
    phone
    string
    Search contacts by phone number of the contact person. Variants: phone_startswith and phone_contains
    mobile
    string
    Search contacts by mobile number of the contact person.
    designation
    string
    Designation for the contact person.
    department
    string
    Department for the contact person.
    skype
    string
    Skype details for the contact person.
    is_primary_contact
    boolean
    To mark contact person as primary for contact. Allowed value is true only.
    enable_portal
    boolean
    To enable client portal for the primary contact. Allowed value is true and false.

    Create a Contact

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

    POST /contacts

    Request Example

      
    $ curl https://books.zoho.com/api/v3/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", "website": "www.bowmanfurniture.com", "contact_type": "customer", "is_portal_enabled": true, "currency_id": 460000000000097, "payment_terms": 15, "payment_terms_label": "Net 15", "notes": "Payment option : Through check", "billing_address": { "attention": "Mr.John", "address": "4900 Hopyard Rd", "street2": "Suite 310", "state_code": "CA", "city": "Pleasanton", "state": "CA", "zip": 94588, "country": "U.S.A", "fax": "+1-925-924-9600", "phone": "+1-925-921-9201" }, "shipping_address": { "attention": "Mr.John", "address": "4900 Hopyard Rd", "street2": "Suite 310", "state_code": "CA", "city": "Pleasanton", "state": "CA", "zip": 94588, "country": "U.S.A", "fax": "+1-925-924-9600", "phone": "+1-925-921-9201" }, "contact_persons": [ { "salutation": "Mr", "first_name": "Will", "last_name": "Smith", "email": "[email protected]", "phone": "+1-925-921-9201", "mobile": "+1-4054439562", "designation": "Sales Executive", "department": "Sales and Marketing", "skype": "Zoho", "is_primary_contact": true, "enable_portal": true } ], "default_templates": { "invoice_template_id": 460000000052069, "estimate_template_id": 460000000000179, "creditnote_template_id": 460000000000211, "purchaseorder_template_id": 460000000000213, "salesorder_template_id": 460000000000214, "retainerinvoice_template_id": 460000000000215, "paymentthankyou_template_id": 460000000000216, "retainerinvoice_paymentthankyou_template_id": 460000000000217, "invoice_email_template_id": 460000000052071, "estimate_email_template_id": 460000000052073, "creditnote_email_template_id": 460000000052075, "purchaseorder_email_template_id": 460000000000218, "salesorder_email_template_id": 460000000000219, "retainerinvoice_email_template_id": 460000000000220, "paymentthankyou_email_template_id": 460000000000221, "retainerinvoice_paymentthankyou_email_template_id": 460000000000222 }, "custom_fields": [ { "index": 1, "value": "GBGD078" } ], "owner_id": 460000000016051, "tax_reg_no": 12345678912345, "place_of_contact": "TN", "gst_no": "22AAAAA0000A1Z5", "gst_treatment": "business_gst", "tax_exemption_id": 11149000000061054, "tax_authority_id": 11149000000061052, "tax_id": 11149000000061058, "is_taxable": true, "facebook": "zoho", "twitter": "zoho" }"'

    Response Example

      
    HTTP/1.1 201 Created Content-Type:application/json;charset=UTF-8 { "code": 0, "message": "The contact has been created", "contact": { "contact": { "contact_id": 460000000026049, "contact_name": "Bowman and Co", "company_name": "Bowman and Co", "has_transaction": true, "contact_type": "customer", "is_portal_enabled": true, "is_taxable": true, "tax_id": 11149000000061058, "tax_name": "CGST", "tax_percentage": 12, "tax_authority_id": 11149000000061052, "tax_exemption_id": 11149000000061054, "place_of_contact": "TN", "gst_no": "22AAAAA0000A1Z5", "gst_treatment": "business_gst", "is_linked_with_zohocrm": false, "website": "www.bowmanfurniture.com", "owner_id": 460000000016051, "primary_contact_id": 460000000026051, "payment_terms": 15, "payment_terms_label": "Net 15", "currency_id": 460000000000097, "currency_code": "USD", "currency_symbol": "$", "outstanding_receivable_amount": 250, "outstanding_receivable_amount_bcy": 250, "unused_credits_receivable_amount": 1369.66, "unused_credits_receivable_amount_bcy": 1369.66, "status": "active", "payment_reminder_enabled": true, "custom_fields": [ { "index": 1, "value": "GBGD078", "label": "VAT ID" } ], "billing_address": { "attention": "Mr.John", "address": "4900 Hopyard Rd", "street2": "Suite 310", "state_code": "CA", "city": "Pleasanton", "state": "CA", "zip": 94588, "country": "U.S.A", "fax": "+1-925-924-9600", "phone": "+1-925-921-9201" }, "shipping_address": { "attention": "Mr.John", "address": "4900 Hopyard Rd", "street2": "Suite 310", "state_code": "CA", "city": "Pleasanton", "state": "CA", "zip": 94588, "country": "U.S.A", "fax": "+1-925-924-9600", "phone": "+1-925-921-9201" }, "facebook": "zoho", "twitter": "zoho", "contact_persons": [ { "contact_person_id": 460000000026051, "salutation": "Mr", "first_name": "Will", "last_name": "Smith", "email": "[email protected]", "phone": "+1-925-921-9201", "mobile": "+1-4054439562", "designation": "Sales Executive", "department": "Sales and Marketing", "skype": "Zoho", "is_primary_contact": true, "enable_portal": true } ], "default_templates": { "invoice_template_id": 460000000052069, "estimate_template_id": 460000000000179, "creditnote_template_id": 460000000000211, "purchaseorder_template_id": 460000000000213, "salesorder_template_id": 460000000000214, "retainerinvoice_template_id": 460000000000215, "paymentthankyou_template_id": 460000000000216, "retainerinvoice_paymentthankyou_template_id": 460000000000217, "invoice_email_template_id": 460000000052071, "estimate_email_template_id": 460000000052073, "creditnote_email_template_id": 460000000052075, "purchaseorder_email_template_id": 460000000000218, "salesorder_email_template_id": 460000000000219, "retainerinvoice_email_template_id": 460000000000220, "paymentthankyou_email_template_id": 460000000000221, "retainerinvoice_paymentthankyou_email_template_id": 460000000000222 }, "notes": "Payment option : Through check", "created_time": "2013-08-05T12:06:10+0530", "last_modified_time": "2013-10-07T18:24:51+0530" } } }

    ARGUMENTS

    contact_name
    Required
    Display Name of the contact. Max-length [200]
    company_name
    Optional
    Company Name of the contact. Max-length [200]
    website
    Optional
    Website of the contact.
    language_code
    Optional
    language of a contact. allowed values de,en,es,fr,it,ja,nl,pt,pt_br,sv,zh,en_gb
    contact_type
    Optional
    Contact type of the contact
    is_portal_enabled
    Optional
    To enable client portal for the contact. Allowed value is true and false.
    currency_id
    Optional
    Currency ID of the customer's currency.
    payment_terms
    Optional
    Net payment term for the customer.
    payment_terms_label
    Optional
    Label for the paymet due details.
    notes
    Optional
    Commennts about the payment made by the contact.
    billing_address
    Optional
    Billing address of the contact.
    attention
    Optional
    address
    Optional
    Max-length [500]
    street2
    Optional
    state_code
    Optional
    city
    Optional
    City of the customer’s billing address.
    state
    Optional
    State of the customer’s billing address.
    zip
    Optional
    Zip code of the customer’s billing address.
    country
    Optional
    Country of the customer’s billing address.
    fax
    Optional
    Customer's fax number.
    phone
    Optional
    Search contacts by phone number of the contact person. Variants: phone_startswith and phone_contains
    shipping_address
    Optional
    Customer's shipping address object.
    attention
    Optional
    address
    Optional
    Max-length [500]
    street2
    Optional
    state_code
    Optional
    city
    Optional
    City of the customer’s billing address.
    state
    Optional
    State of the customer’s billing address.
    zip
    Optional
    Zip code of the customer’s billing address.
    country
    Optional
    Country of the customer’s billing address.
    fax
    Optional
    Customer's fax number.
    phone
    Optional
    Search contacts by phone number of the contact person. Variants: phone_startswith and phone_contains
    contact_persons
    Optional , default isContact persons of a contact.
    salutation
    Optional
    Salutation for the contact
    first_name
    Optional
    Max-length [100]
    last_name
    Optional
    Max-length [100]
    email
    Optional
    Email address of the contact person.
    phone
    Optional
    Search contacts by phone number of the contact person. Variants: phone_startswith and phone_contains
    mobile
    Optional
    Search contacts by mobile number of the contact person.
    designation
    Optional
    Designation for the contact person.
    department
    Optional
    Department for the contact person.
    skype
    Optional
    Skype details for the contact person.
    is_primary_contact
    Optional
    To mark contact person as primary for contact. Allowed value is true only.
    enable_portal
    Optional
    To enable client portal for the primary contact. Allowed value is true and false.
    default_templates
    Optional
    invoice_template_id
    Optional
    Default invoice template id used for this contact while creating invoice.
    estimate_template_id
    Optional
    Default estimate template id used for this contact while creating estimate.
    creditnote_template_id
    Optional
    Default credit note template id used for this contact while creating credit note.
    purchaseorder_template_id
    Optional
    Default purchase order template id used for this contact while creating purchase order(for Vendors only).
    salesorder_template_id
    Optional
    Default sales order template id used for this contact while creating sales order.
    retainerinvoice_template_id
    Optional
    Default retainer invoice template id used for this contact while creating retainer invoice.
    paymentthankyou_template_id
    Optional
    Default payment thankyou template id used for this contact while sending payment thankyou note.
    retainerinvoice_paymentthankyou_template_id
    Optional
    Default retainer invoice paymnet thankyou template id used for this contact while sending payment thankyou note for retainer invoice.
    invoice_email_template_id
    Optional
    Default invoice email template id used for this contact while sending invoices.
    estimate_email_template_id
    Optional
    Default estimate email template id used for this contact while sending estimates.
    creditnote_email_template_id
    Optional
    Default credit note email template id used for this contact while sending credit notes.
    purchaseorder_email_template_id
    Optional
    Default purchase order template id used for this contact while creating purchase order(for Vendors only).
    salesorder_email_template_id
    Optional
    Default sales order template id used for this contact while creating sales order.
    retainerinvoice_email_template_id
    Optional
    Default retainer invoice template id used for this contact while creating retainer invoice.
    paymentthankyou_email_template_id
    Optional
    Default payment thankyou template id used for this contact while sending payment thankyou note.
    retainerinvoice_paymentthankyou_email_template_id
    Optional
    Default retainer invoice paymnet thankyou template id used for this contact while sending payment thankyou note for retainer invoice.
    custom_fields
    Optional
    index
    Optional
    Index of the custom field. It can hold any value from 1 to 10.
    value
    Optional
    Value of the custom field.
    vat_reg_no
    UK Edition and Avalara integration only
    Optional
    For UK Edition: VAT Registration number of a contact with VAT treatment as eu_vat_registered. Length should be between 2 and 12 characters.(This node is only available for EU VAT registered contacts.)
    For Avalara: If you are doing sales in the European Union (EU) then provide VAT Registration Number of your customers here. This is used to calculate VAT for B2B sales, from Avalara.
    owner_id
    Optional
    For Customer Only : If a contact is assigned to any particular user, that user can manage transactions for the contact.
    tax_reg_no
    GCC editions only
    Optional
    15 digit Tax Registration number of a contact with Tax treatment as vat_registered,gcc_vat_registered,dz_vat_registered.
    country_code
    UK Edition,GCC Editions and Avalara integration only
    Optional
    For UK Edition: Two letter country code of a contact with VAT treatment as eu_vat_registered.(This node is only available for EU VAT registered contacts.)
    For Avalara: Two letter country code for the customer country, if your customer is not in US. Refer [AvaTax Codes for Countries and States][2].
    For GCC Editions : Two Letter country code for the GCC Country or the UAE emirate of the contact which will be considered as place of supply.
    Supported codes for UAE emirates are :
    Abu Dhabi - AB,
    Ajman - AJ,
    Dubai - DU,
    Fujairah - FU,
    Ras al-Khaimah - RA,
    Sharjah - SH,
    Umm al-Quwain - UM.
    Supported codes for the GCC countries are :
    United Arab Emirates - AE,
    Saudi Arabia - SA,
    Bahrain - BH,
    Kuwait - KW,
    Oman - OM,
    Qatar - QA.
    vat_treatment
    UK edition only
    Optional
    VAT treatment of the contact.Allowed Values: uk, eu_vat_not_registered, eu_vat_registered and non_eu.
    tax_treatment
    GCC Editions only
    Optional
    VAT treatment of the contact.Allowed Values: vat_registered,vat_not_registered,gcc_vat_not_registered,gcc_vat_registered,non_gcc,dz_vat_registered and dz_vat_not_registered.
    place_of_contact
    India Edition only.
    Optional
    Location of the contact. (This node identifies the place of supply and source of supply when invoices/bills are raised for the customer/vendor respectively. This is not applicable for Overseas contacts)
    gst_no
    India Edition only.
    Optional
    15 digit GST identification number of the customer/vendor.
    gst_treatment
    India Edition only.
    Optional
    Choose whether the contact is GST registered/unregistered/consumer/overseas. Allowed values are business_gst , business_none , overseas , consumer .
    tax_authority_name
    Optional
    Enter tax authority name.
    avatax_exempt_no
    Avalara integration only
    Optional
    Exemption certificate number of the customer.
    avatax_use_code
    Avalara integration only
    Optional
    Used to group like customers for exemption purposes. It is a custom value that links customers to a tax rule. Select from Avalara [standard codes][1] or enter a custom code.
    tax_exemption_id
    US, Canada, Australia and India editions only
    Optional
    ID of the tax exemption.
    tax_exemption_code
    US, Canada, Australia and India editions only
    Optional
    Enter tax exemption code
    tax_authority_id
    US edition only
    Optional
    ID of the tax authority. Tax authority depends on the location of the customer. For example, if the customer is located in NY, then the tax authority is NY tax authority.
    tax_id
    India edition and US edition only
    Optional
    ID of the tax or tax group that can be collected from the contact. Tax can be given only if is_taxable is true.
    is_taxable
    US, Canada, Australia, and India Editions only.
    Optional
    Boolean to track the taxability of the customer.
    facebook
    Optional
    Facebook profile account. max-length [100]
    twitter
    Optional
    Twitter account. max-length [100]
    track_1099
    US Edition Only
    Optional
    Boolean to track a contact for 1099 reporting.
    tax_id_type
    US Edition Only
    Optional
    Tax ID type of the contact, it can be SSN, ATIN, ITIN or EIN.
    tax_id_value
    US Edition Only
    Optional
    Tax ID of the contact.

    Update a Contact

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

    PUT /contacts/{contact_id}

    Request Example

      
    $ curl https://books.zoho.com/api/v3/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, "payment_terms_label": "Net 15", "contact_type": "customer", "currency_id": 460000000000097, "website": "www.bowmanfurniture.com", "owner_id": 460000000016051, "custom_fields": [ { "index": 1, "value": "GBGD078", "label": "VAT ID" } ], "billing_address": { "attention": "Mr.John", "address": "4900 Hopyard Rd", "street2": "Suite 310", "state_code": "CA", "city": "Pleasanton", "state": "CA", "zip": 94588, "country": "U.S.A", "fax": "+1-925-924-9600", "phone": "+1-925-921-9201" }, "shipping_address": { "attention": "Mr.John", "address": "4900 Hopyard Rd", "street2": "Suite 310", "state_code": "CA", "city": "Pleasanton", "state": "CA", "zip": 94588, "country": "U.S.A", "fax": "+1-925-924-9600", "phone": "+1-925-921-9201" }, "contact_persons": [ { "contact_person_id": 460000000026051, "salutation": "Mr", "first_name": "Will", "last_name": "Smith", "email": "[email protected]", "phone": "+1-925-921-9201", "mobile": "+1-4054439562", "designation": "Sales Executive", "department": "Sales and Marketing", "skype": "Zoho", "is_primary_contact": true, "enable_portal": true } ], "default_templates": { "invoice_template_id": 460000000052069, "estimate_template_id": 460000000000179, "creditnote_template_id": 460000000000211, "purchaseorder_template_id": 460000000000213, "salesorder_template_id": 460000000000214, "retainerinvoice_template_id": 460000000000215, "paymentthankyou_template_id": 460000000000216, "retainerinvoice_paymentthankyou_template_id": 460000000000217, "invoice_email_template_id": 460000000052071, "estimate_email_template_id": 460000000052073, "creditnote_email_template_id": 460000000052075, "purchaseorder_email_template_id": 460000000000218, "salesorder_email_template_id": 460000000000219, "retainerinvoice_email_template_id": 460000000000220, "paymentthankyou_email_template_id": 460000000000221, "retainerinvoice_paymentthankyou_email_template_id": 460000000000222 }, "notes": "Payment option : Through check", "tax_reg_no": 12345678912345, "place_of_contact": "TN", "gst_no": "22AAAAA0000A1Z5", "gst_treatment": "business_gst", "tax_exemption_id": 11149000000061054, "tax_authority_id": 11149000000061052, "tax_id": 11149000000061058, "is_taxable": true, "facebook": "zoho", "twitter": "zoho" }"'

    Response Example

      
    HTTP/1.1 200 OK Content-Type:application/json;charset=UTF-8 { "code": 0, "message": "Contact has been updated successfully", "contact": { "contact": { "contact_id": 460000000026049, "contact_name": "Bowman and Co", "company_name": "Bowman and Co", "has_transaction": true, "contact_type": "customer", "is_taxable": true, "tax_id": 11149000000061058, "tax_name": "CGST", "tax_percentage": 12, "tax_authority_id": 11149000000061052, "tax_exemption_id": 11149000000061054, "place_of_contact": "TN", "gst_no": "22AAAAA0000A1Z5", "gst_treatment": "business_gst", "is_linked_with_zohocrm": false, "website": "www.bowmanfurniture.com", "owner_id": 460000000016051, "primary_contact_id": 460000000026051, "payment_terms": 15, "payment_terms_label": "Net 15", "currency_id": 460000000000097, "currency_code": "USD", "currency_symbol": "$", "outstanding_receivable_amount": 250, "outstanding_receivable_amount_bcy": 250, "unused_credits_receivable_amount": 1369.66, "unused_credits_receivable_amount_bcy": 1369.66, "status": "active", "payment_reminder_enabled": true, "custom_fields": [ { "index": 1, "value": "GBGD078", "label": "VAT ID" } ], "billing_address": { "attention": "Mr.John", "address": "4900 Hopyard Rd", "street2": "Suite 310", "state_code": "CA", "city": "Pleasanton", "state": "CA", "zip": 94588, "country": "U.S.A", "fax": "+1-925-924-9600", "phone": "+1-925-921-9201" }, "shipping_address": { "attention": "Mr.John", "address": "4900 Hopyard Rd", "street2": "Suite 310", "state_code": "CA", "city": "Pleasanton", "state": "CA", "zip": 94588, "country": "U.S.A", "fax": "+1-925-924-9600", "phone": "+1-925-921-9201" }, "facebook": "zoho", "twitter": "zoho", "contact_persons": [ { "contact_person_id": 460000000026051, "salutation": "Mr", "first_name": "Will", "last_name": "Smith", "email": "[email protected]", "phone": "+1-925-921-9201", "mobile": "+1-4054439562", "designation": "Sales Executive", "department": "Sales and Marketing", "skype": "Zoho", "is_primary_contact": true, "enable_portal": true } ], "default_templates": { "invoice_template_id": 460000000052069, "estimate_template_id": 460000000000179, "creditnote_template_id": 460000000000211, "purchaseorder_template_id": 460000000000213, "salesorder_template_id": 460000000000214, "retainerinvoice_template_id": 460000000000215, "paymentthankyou_template_id": 460000000000216, "retainerinvoice_paymentthankyou_template_id": 460000000000217, "invoice_email_template_id": 460000000052071, "estimate_email_template_id": 460000000052073, "creditnote_email_template_id": 460000000052075, "purchaseorder_email_template_id": 460000000000218, "salesorder_email_template_id": 460000000000219, "retainerinvoice_email_template_id": 460000000000220, "paymentthankyou_email_template_id": 460000000000221, "retainerinvoice_paymentthankyou_email_template_id": 460000000000222 }, "notes": "Payment option : Through check", "created_time": "2013-08-05T12:06:10+0530", "last_modified_time": "2013-10-07T18:24:51+0530" } } }

    ARGUMENTS

    contact_name
    Required
    Display Name of the contact. Max-length [200]
    company_name
    Optional
    Company Name of the contact. Max-length [200]
    payment_terms
    Optional
    Net payment term for the customer.
    payment_terms_label
    Optional
    Label for the paymet due details.
    contact_type
    Optional
    Contact type of the contact
    currency_id
    Optional
    Currency ID of the customer's currency.
    website
    Optional
    Website of the contact.
    owner_id
    Optional
    For Customer Only : If a contact is assigned to any particular user, that user can manage transactions for the contact.
    custom_fields
    Optional
    index
    Optional
    Index of the custom field. It can hold any value from 1 to 10.
    value
    Optional
    Value of the custom field.
    label
    Optional
    Label of the custom field.
    billing_address
    Optional
    Billing address of the contact.
    attention
    Optional
    address
    Optional
    Max-length [500]
    street2
    Optional
    state_code
    Optional
    city
    Optional
    City of the customer’s billing address.
    state
    Optional
    State of the customer’s billing address.
    zip
    Optional
    Zip code of the customer’s billing address.
    country
    Optional
    Country of the customer’s billing address.
    fax
    Optional
    Customer's fax number.
    phone
    Optional
    Search contacts by phone number of the contact person. Variants: phone_startswith and phone_contains
    shipping_address
    Optional
    Customer's shipping address object.
    attention
    Optional
    address
    Optional
    Max-length [500]
    street2
    Optional
    state_code
    Optional
    city
    Optional
    City of the customer’s billing address.
    state
    Optional
    State of the customer’s billing address.
    zip
    Optional
    Zip code of the customer’s billing address.
    country
    Optional
    Country of the customer’s billing address.
    fax
    Optional
    Customer's fax number.
    phone
    Optional
    Search contacts by phone number of the contact person. Variants: phone_startswith and phone_contains
    contact_persons
    Optional , default isContact persons of a contact.
    contact_person_id
    Optional
    The id of the contact person. For an existing contact person, pass the contact_person_id.
    salutation
    Optional
    Salutation for the contact
    first_name
    Optional
    Max-length [100]
    last_name
    Optional
    Max-length [100]
    email
    Optional
    Email address of the contact person.
    phone
    Optional
    Search contacts by phone number of the contact person. Variants: phone_startswith and phone_contains
    mobile
    Optional
    Search contacts by mobile number of the contact person.
    designation
    Optional
    Designation for the contact person.
    department
    Optional
    Department for the contact person.
    skype
    Optional
    Skype details for the contact person.
    is_primary_contact
    Optional
    To mark contact person as primary for contact. Allowed value is true only.
    enable_portal
    Optional
    To enable client portal for the primary contact. Allowed value is true and false.
    default_templates
    Optional
    invoice_template_id
    Optional
    Default invoice template id used for this contact while creating invoice.
    estimate_template_id
    Optional
    Default estimate template id used for this contact while creating estimate.
    creditnote_template_id
    Optional
    Default credit note template id used for this contact while creating credit note.
    purchaseorder_template_id
    Optional
    Default purchase order template id used for this contact while creating purchase order(for Vendors only).
    salesorder_template_id
    Optional
    Default sales order template id used for this contact while creating sales order.
    retainerinvoice_template_id
    Optional
    Default retainer invoice template id used for this contact while creating retainer invoice.
    paymentthankyou_template_id
    Optional
    Default payment thankyou template id used for this contact while sending payment thankyou note.
    retainerinvoice_paymentthankyou_template_id
    Optional
    Default retainer invoice paymnet thankyou template id used for this contact while sending payment thankyou note for retainer invoice.
    invoice_email_template_id
    Optional
    Default invoice email template id used for this contact while sending invoices.
    estimate_email_template_id
    Optional
    Default estimate email template id used for this contact while sending estimates.
    creditnote_email_template_id
    Optional
    Default credit note email template id used for this contact while sending credit notes.
    purchaseorder_email_template_id
    Optional
    Default purchase order template id used for this contact while creating purchase order(for Vendors only).
    salesorder_email_template_id
    Optional
    Default sales order template id used for this contact while creating sales order.
    retainerinvoice_email_template_id
    Optional
    Default retainer invoice template id used for this contact while creating retainer invoice.
    paymentthankyou_email_template_id
    Optional
    Default payment thankyou template id used for this contact while sending payment thankyou note.
    retainerinvoice_paymentthankyou_email_template_id
    Optional
    Default retainer invoice paymnet thankyou template id used for this contact while sending payment thankyou note for retainer invoice.
    notes
    Optional
    Commennts about the payment made by the contact.
    vat_reg_no
    UK Edition and Avalara integration only
    Optional
    For UK Edition: VAT Registration number of a contact with VAT treatment as eu_vat_registered. Length should be between 2 and 12 characters.(This node is only available for EU VAT registered contacts.)
    For Avalara: If you are doing sales in the European Union (EU) then provide VAT Registration Number of your customers here. This is used to calculate VAT for B2B sales, from Avalara.
    tax_reg_no
    GCC editions only
    Optional
    15 digit Tax Registration number of a contact with Tax treatment as vat_registered,gcc_vat_registered,dz_vat_registered.
    country_code
    UK Edition,GCC Editions and Avalara integration only
    Optional
    For UK Edition: Two letter country code of a contact with VAT treatment as eu_vat_registered.(This node is only available for EU VAT registered contacts.)
    For Avalara: Two letter country code for the customer country, if your customer is not in US. Refer [AvaTax Codes for Countries and States][2].
    For GCC Editions : Two Letter country code for the GCC Country or the UAE emirate of the contact which will be considered as place of supply.
    Supported codes for UAE emirates are :
    Abu Dhabi - AB,
    Ajman - AJ,
    Dubai - DU,
    Fujairah - FU,
    Ras al-Khaimah - RA,
    Sharjah - SH,
    Umm al-Quwain - UM.
    Supported codes for the GCC countries are :
    United Arab Emirates - AE,
    Saudi Arabia - SA,
    Bahrain - BH,
    Kuwait - KW,
    Oman - OM,
    Qatar - QA.
    tax_treatment
    GCC Editions only
    Optional
    VAT treatment of the contact.Allowed Values: vat_registered,vat_not_registered,gcc_vat_not_registered,gcc_vat_registered,non_gcc,dz_vat_registered and dz_vat_not_registered.
    vat_treatment
    UK edition only
    Optional
    VAT treatment of the contact.Allowed Values: uk, eu_vat_not_registered, eu_vat_registered and non_eu.
    place_of_contact
    India Edition only.
    Optional
    Location of the contact. (This node identifies the place of supply and source of supply when invoices/bills are raised for the customer/vendor respectively. This is not applicable for Overseas contacts)
    gst_no
    India Edition only.
    Optional
    15 digit GST identification number of the customer/vendor.
    gst_treatment
    India Edition only.
    Optional
    Choose whether the contact is GST registered/unregistered/consumer/overseas. Allowed values are business_gst , business_none , overseas , consumer .
    tax_authority_name
    Optional
    Enter tax authority name.
    avatax_exempt_no
    Avalara integration only
    Optional
    Exemption certificate number of the customer.
    avatax_use_code
    Avalara integration only
    Optional
    Used to group like customers for exemption purposes. It is a custom value that links customers to a tax rule. Select from Avalara [standard codes][1] or enter a custom code.
    tax_exemption_id
    US, Canada, Australia and India editions only
    Optional
    ID of the tax exemption.
    tax_exemption_code
    US, Canada, Australia and India editions only
    Optional
    Enter tax exemption code
    tax_authority_id
    US edition only
    Optional
    ID of the tax authority. Tax authority depends on the location of the customer. For example, if the customer is located in NY, then the tax authority is NY tax authority.
    tax_id
    India edition and US edition only
    Optional
    ID of the tax or tax group that can be collected from the contact. Tax can be given only if is_taxable is true.
    is_taxable
    US, Canada, Australia, and India Editions only.
    Optional
    Boolean to track the taxability of the customer.
    facebook
    Optional
    Facebook profile account. max-length [100]
    twitter
    Optional
    Twitter account. max-length [100]
    track_1099
    US Edition Only
    Optional
    Boolean to track a contact for 1099 reporting.
    tax_id_type
    US Edition Only
    Optional
    Tax ID type of the contact, it can be SSN, ATIN, ITIN or EIN.
    tax_id_value
    US Edition Only
    Optional
    Tax ID of the contact.

    List Contacts

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

    GET /contacts

    Request Example

      
    $ curl https://books.zoho.com/api/v3/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": [ { "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": "[email protected]", "phone": "+1-925-921-9201", "mobile": "+1-4054439562", "created_time": "2013-08-05T12:06:10+0530", "last_modified_time": "2013-10-07T18:24:51+0530" } ], "page_context": { "page": 1, "per_page": 200, "has_more_page": false, "applied_filter": "Status.All", "sort_column": "contact_name", "sort_order": "D" } }, {...}, {...} ] }

    Query Params

    contact_name
    Optional
    Search contacts by contact name. Max-length [100] Variants: contact_name_startswith and contact_name_contains. Max-length [100]
    company_name
    Optional
    Search contacts by company name. Max-length [100] Variants: company_name_startswith and company_name_contains
    first_name
    Optional
    Search contacts by first name of the contact person. Max-length [100] Variants: first_name_startswith and first_name_contains
    last_name
    Optional
    Search contacts by last name of the contact person. Max-length [100] Variants: last_name_startswith and last_name_contains
    address
    Optional
    Search contacts by any of the address fields. Max-length [100] Variants: address_startswith and address_contains
    email
    Optional
    Search contacts by email of the contact person. Max-length [100] Variants: email_startswith and email_contains
    phone
    Optional
    Search contacts by phone number of the contact person. Max-length [100] Variants: phone_startswith and phone_contains
    filter_by
    Optional
    Filter contacts by status. Allowed Values: Status.All, Status.Active, Status.Inactive, Status.Duplicate and Status.Crm
    search_text
    Optional
    Search contacts by contact name or notes. Max-length [100]
    sort_column
    Optional
    Sort contacts. Allowed Values: contact_name, first_name, last_name, email, outstanding_receivable_amount, created_time and last_modified_time

    Get Contact

    Get details of a contact.
    oauthscope : ZohoBooks.contacts.READ

    GET /contacts/{:contacts_id}

    Request Example

      
    $ curl https://books.zoho.com/api/v3/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": { "contact_id": 460000000026049, "contact_name": "Bowman and Co", "company_name": "Bowman and Co", "has_transaction": true, "contact_type": "customer", "is_taxable": true, "tax_id": 11149000000061058, "tax_name": "CGST", "tax_percentage": 12, "tax_authority_id": 11149000000061052, "tax_exemption_id": 11149000000061054, "place_of_contact": "TN", "gst_no": "22AAAAA0000A1Z5", "gst_treatment": "business_gst", "is_linked_with_zohocrm": false, "website": "www.bowmanfurniture.com", "owner_id": 460000000016051, "primary_contact_id": 460000000026051, "payment_terms": 15, "payment_terms_label": "Net 15", "currency_id": 460000000000097, "currency_code": "USD", "currency_symbol": "$", "outstanding_receivable_amount": 250, "outstanding_receivable_amount_bcy": 250, "unused_credits_receivable_amount": 1369.66, "unused_credits_receivable_amount_bcy": 1369.66, "status": "active", "facebook": "zoho", "twitter": "zoho", "payment_reminder_enabled": true, "custom_fields": [ { "index": 1, "value": "GBGD078", "label": "VAT ID" } ], "billing_address": { "attention": "Mr.John", "address": "4900 Hopyard Rd", "street2": "Suite 310", "state_code": "CA", "city": "Pleasanton", "state": "CA", "zip": 94588, "country": "U.S.A", "fax": "+1-925-924-9600", "phone": "+1-925-921-9201" }, "shipping_address": { "attention": "Mr.John", "address": "4900 Hopyard Rd", "street2": "Suite 310", "state_code": "CA", "city": "Pleasanton", "state": "CA", "zip": 94588, "country": "U.S.A", "fax": "+1-925-924-9600", "phone": "+1-925-921-9201" }, "contact_persons": [ { "contact_person_id": 460000000026051, "salutation": "Mr", "first_name": "Will", "last_name": "Smith", "email": "[email protected]", "phone": "+1-925-921-9201", "mobile": "+1-4054439562", "designation": "Sales Executive", "department": "Sales and Marketing", "skype": "Zoho", "is_primary_contact": true, "enable_portal": true } ], "default_templates": { "invoice_template_id": 460000000052069, "estimate_template_id": 460000000000179, "creditnote_template_id": 460000000000211, "purchaseorder_template_id": 460000000000213, "salesorder_template_id": 460000000000214, "retainerinvoice_template_id": 460000000000215, "paymentthankyou_template_id": 460000000000216, "retainerinvoice_paymentthankyou_template_id": 460000000000217, "invoice_email_template_id": 460000000052071, "estimate_email_template_id": 460000000052073, "creditnote_email_template_id": 460000000052075, "purchaseorder_email_template_id": 460000000000218, "salesorder_email_template_id": 460000000000219, "retainerinvoice_email_template_id": 460000000000220, "paymentthankyou_email_template_id": 460000000000221, "retainerinvoice_paymentthankyou_email_template_id": 460000000000222 }, "notes": "Payment option : Through check", "created_time": "2013-08-05T12:06:10+0530", "last_modified_time": "2013-10-07T18:24:51+0530" } } }

    Delete a Contact

    Delete an existing contact.
    oauthscope : ZohoBooks.contacts.DELETE

    DELETE /contacts/{:contact_id}

    Request Example

      
    $ curl https://books.zoho.com/api/v3/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 /contacts/{:contact_id}/active

    Request Example

      
    $ curl https://books.zoho.com/api/v3/contacts/{: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://books.zoho.com/api/v3/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." }

    Enable Portal Access

    Enable portal access for a contact.
    oauthscope : ZohoBooks.contacts.CREATE

    POST /contacts/{:contact_id}/portal/enable

    Request Example

      
    $ curl https://books.zoho.com/api/v3/contacts/{:contact_id}/portal/enable?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_persons": [ { "contact_person_id": 460000000026051 } ] }"'

    Response Example

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

    ARGUMENTS

    contact_persons
    Required
    contact_person_id
    Optional
    The id of the contact person

    Enable Payment Reminders

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

    POST /contacts/{:contact_id}/paymentreminder/enable

    Request Example

      
    $ curl https://books.zoho.com/api/v3/contacts/{:contact_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": "All reminders associated with this contact have been enabled." }

    Disable Payment Reminders

    Disable automated payment reminders for a contact.
    oauthscope : ZohoBooks.contacts.CREATE

    POST /contacts/{:contact_id}/paymentreminder/disable

    Request Example

      
    $ curl https://books.zoho.com/api/v3/contacts/{:contact_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": "All reminders associated with this contact have been stopped." }

    Email Statement

    Email statement to the contact. If JSONString is not inputted, mail will be sent with the default mail content.
    oauthscope : ZohoBooks.contacts.CREATE

    POST /contacts/{:contact_id}/statements/email

    Request Example

      
    $ curl https://books.zoho.com/api/v3/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": [ "[email protected]" ], "cc_mail_ids": [ "[email protected]" ], "subject": "Statement of transactions with Zillium Inc", "body": "Dear Customer, <br/>We have attached with this email a list of all your transactions with us for the period 01 Sep 2013 to 30 Sep 2013. You can write to us or call us if you need any assistance or clarifications. <br/>Thanks for your business.<br/>Regards<br/>Zillium Inc" }"'

    Response Example

      
    HTTP/1.1 200 OK Content-Type:application/json;charset=UTF-8 { "code": 0, "message": "Statement has been sent to the Customer." }

    ARGUMENTS

    send_from_org_email_id
    Optional
    Boolean to trigger the email from the organization's email address
    to_mail_ids
    Required
    Array of email address of the recipients.
    cc_mail_ids
    Optional
    Array of email address of the recipients to be cced.
    subject
    Required
    Subject of an email has to be sent. Max-length [1000]
    body
    Required
    Body of an email has to be sent. Max-length [5000]

    Query Params

    start_date
    Optional
    If start_date and end_date are not given, current month's statement will be sent to contact. Date format [yyyy-mm-dd]
    end_date
    Optional
    End date for the statement. Date format [yyyy-mm-dd]
    multipart_or_formdata
    Optional
    Files to be attached along with the statement.

    Get Statement Mail Content

    Get the statement mail content.
    oauthscope : ZohoBooks.contacts.READ

    GET /contacts/{:contact_id}/statements/email

    Request Example

      
    $ curl https://books.zoho.com/api/v3/contacts/{:contact_id}/statements/email?organization_id=10234695 -H "Authorization: Zoho-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": { "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": "[email protected]", "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": "[email protected]" } ], "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 : ZohoBooks.contacts.CREATE

    POST /contacts/{:contact_id}/email

    Request Example

      
    $ curl https://books.zoho.com/api/v3/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": [ "[email protected]" ], "subject": "Welcome to Zillium Inc .", "body": "Dear Customer, <br/>We have attached with this email a list of all your transactions with us for the period 01 Sep 2013 to 30 Sep 2013. You can write to us or call us if you need any assistance or clarifications. <br/>Thanks for your business.<br/>Regards<br/>Zillium Inc" }"'

    Response Example

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

    ARGUMENTS

    to_mail_ids
    Required
    Array of email address of the recipients.
    subject
    Required
    Subject of an email has to be sent. Max-length [1000]
    body
    Required
    Body of an email has to be sent. Max-length [5000]
    attachments
    Optional
    Files to be attached to the email. It has to be sent in multipart/formdata

    Query Params

    send_customer_statement
    Optional
    Send customer statement pdf with email.

    List Comments

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

    GET /contacts/{:contact_id}/comments

    Request Example

      
    $ curl https://books.zoho.com/api/v3/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": [ { "comment_id": 460000000053131, "contact_id": 460000000026049, "contact_name": "Bowman and Co", "description": "", "commented_by_id": 460000000024003, "commented_by": "John David", "date": "2013-11-19", "date_description": "4 days ago", "time": "6:03 PM", "transaction_id": 460000000053123, "transaction_type": "customer_payment", "is_entity_deleted": false, "operation_type": "added" } ], "page_context": { "page": 1, "per_page": 200, "has_more_page": false, "applied_filter": "Status.All", "sort_column": "contact_name", "sort_order": "D" } }

    Get Contact Addresses

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

    GET /contacts/{:contact_id}/address

    Request Example

      
    $ curl https://books.zoho.com/api/v3/contacts/{:contact_id}/address?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", "addresses": [ { "address_id": 1053791000000186000, "attention": "Mr.John", "address": "4900 Hopyard Rd", "street2": "Suite 310", "city": "Pleasanton", "state": "CA", "zip": 94588, "country": "U.S.A", "fax": "+1-925-924-9600", "phone": "+1-925-921-9201" }, {...}, {...} ] }

    Add Additional Address

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

    POST /contacts/{:contact_id}/address

    Request Example

      
    $ curl https://books.zoho.com/api/v3/contacts/{:contact_id}/address?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="{ "attention": "Mr.John", "address": "4900 Hopyard Rd", "street2": "Suite 310", "city": "Pleasanton", "state": "CA", "zip": 94588, "country": "U.S.A", "fax": "+1-925-924-9600", "phone": "+1-925-921-9201" }"'

    Response Example

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

    ARGUMENTS

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

    Edit Additional Address

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

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

    Request Example

      
    $ curl https://books.zoho.com/api/v3/contacts/{:contact_id}/address/{:address_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="{ "attention": "Mr.John", "address": "4900 Hopyard Rd", "street2": "Suite 310", "city": "Pleasanton", "state": "CA", "zip": 94588, "country": "U.S.A", "fax": "+1-925-924-9600", "phone": "+1-925-921-9201" }"'

    Response Example

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

    ARGUMENTS

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

    Delete Additional Address

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

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

    Request Example

      
    $ curl https://books.zoho.com/api/v3/contacts/{:contact_id}/address/{:address_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 address has been deleted." }

    List Refunds

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

    GET /contacts/{:contact_id}/refunds

    Request Example

      
    $ curl https://books.zoho.com/api/v3/contacts/{:contact_id}/refunds?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", "creditnote_refunds": [ { "creditnote_refund_id": 982000000567158, "creditnote_id": 982000000567134, "date": "2013-11-19", "refund_mode": "cash", "reference_number": 782364, "creditnote_number": "CN-00001", "customer_name": "Bowman & Co", "description": "", "amount_bcy": 57.15, "amount_fcy": 57.15 } ], "page_context": { "page": 1, "per_page": 200, "has_more_page": false, "report_name": "Credit Notes Refund", "sort_column": "contact_name", "sort_order": "D" } }

    Track 1099

    Track a contact for 1099 reporting: (Note: This API is only available when the organization's country is U.S.A).
    oauthscope : ZohoBooks.contacts.CREATE

    POST /contacts/{:contact_id}/track1099

    Request Example

      
    $ curl https://books.zoho.com/api/v3/contacts/{:contact_id}/track1099?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": "1099 tracking is enabled." }

    Untrack 1099

    Use this API to stop tracking payments to a vendor for 1099 reporting. (Note: This API is only available when the organization's country is U.S.A).
    oauthscope : ZohoBooks.contacts.CREATE

    POST /contacts/{:contact_id}/untrack1099

    Request Example

      
    $ curl https://books.zoho.com/api/v3/contacts/{:contact_id}/untrack1099?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": "1099 tracking is disabled." }

    Contact-Persons

    The list of contacts created.

    Example

    { "contact_id": 460000000026049, "first_name": "Will", "last_name": "Smith", "email": "[email protected]", "skype": "zoho", "designation": "Sales Engineer", "department": "Sales" }

    Attribute

    contact_id
    string
    Contact id of the contact
    first_name
    string
    First name of the contact person. Max-length [100]
    last_name
    string
    Last name of the contact person. Max-length [100]
    email
    string
    Email address of the contact person. Max-length [100]
    skype
    string
    skype address. Max-length [50]
    designation
    string
    designation of a person. Max-length [50]
    department
    string
    department on which a person belongs. Max-length [50]

    Create a contact person

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

    POST /contacts/contactpersons

    Request Example

      
    $ curl https://books.zoho.com/api/v3/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": "[email protected]", "phone": "+1-925-921-9201", "mobile": "+1-4054439562", "skype": "zoho", "designation": "Sales Engineer", "department": "Sales", "enable_portal": true }"'

    Response Example

      
    HTTP/1.1 201 Created Content-Type:application/json;charset=UTF-8 { "code": 0, "message": "The contactperson has been Created", "contact_person": { "contact_person": [ { "contact_id": 460000000026049, "contact_person_id": 460000000026051, "salutation": "Mr", "first_name": "Will", "last_name": "Smith", "email": "[email protected]", "phone": "+1-925-921-9201", "mobile": "+1-4054439562", "is_primary_contact": true, "skype": "zoho", "designation": "Sales Engineer", "department": "Sales", "is_added_in_portal": true } ] } }

    ARGUMENTS

    contact_id
    Optional
    Contact id of the contact
    salutation
    Optional
    Salutation for the contact. Max-length [25]
    first_name
    Required
    First name of the contact person. Max-length [100]
    last_name
    Optional
    Last name of the contact person. Max-length [100]
    email
    Optional
    Email address of the contact person. Max-length [100]
    phone
    Optional
    Max-length [50]
    mobile
    Optional
    Max-length [50]
    skype
    Optional
    skype address. Max-length [50]
    designation
    Optional
    designation of a person. Max-length [50]
    department
    Optional
    department on which a person belongs. Max-length [50]
    enable_portal
    Optional
    option to enable the portal access. allowed values true,false

    Update a contact person

    Update an existing contact person.
    oauthscope : ZohoBooks.contacts.UPDATE

    PUT /contacts/contactpersons/{:contact_person_id}

    Request Example

      
    $ curl https://books.zoho.com/api/v3/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": "[email protected]", "phone": "+1-925-921-9201", "mobile": "+1-4054439562", "skype": "zoho", "designation": "Sales Engineer", "department": "Sales", "enable_portal": true, "is_primary_contact": true }"'

    Response Example

      
    HTTP/1.1 200 OK Content-Type:application/json;charset=UTF-8 { "code": 0, "message": "The contactperson details has been updated.", "contact_person": { "contact_person": [ { "contact_id": 460000000026049, "contact_person_id": 460000000026051, "salutation": "Mr", "first_name": "Will", "last_name": "Smith", "email": "[email protected]", "phone": "+1-925-921-9201", "mobile": "+1-4054439562", "is_primary_contact": true, "skype": "zoho", "designation": "Sales Engineer", "department": "Sales", "is_added_in_portal": true } ] } }

    ARGUMENTS

    contact_id
    Required
    Contact id of the contact
    salutation
    Optional
    Salutation for the contact. Max-length [25]
    first_name
    Required
    First name of the contact person. Max-length [100]
    last_name
    Optional
    Last name of the contact person. Max-length [100]
    email
    Optional
    Email address of the contact person. Max-length [100]
    phone
    Optional
    Max-length [50]
    mobile
    Optional
    Max-length [50]
    skype
    Optional
    skype address. Max-length [50]
    designation
    Optional
    designation of a person. Max-length [50]
    department
    Optional
    department on which a person belongs. Max-length [50]
    enable_portal
    Optional
    option to enable the portal access. allowed values true,false
    is_primary_contact
    Optional
    To mark contact person as primary for contact

    List contact persons

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

    GET /contacts/{:contact_id}/contactpersons

    Request Example

      
    $ curl https://books.zoho.com/api/v3/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_persons": [ { "contact_person_id": 460000000026051, "salutation": "Mr", "first_name": "Will", "last_name": "Smith", "email": "[email protected]", "phone": "+1-925-921-9201", "mobile": "+1-4054439562", "is_primary_contact": true, "skype": "zoho", "designation": "Sales Engineer", "department": "Sales", "is_added_in_portal": true } ], "page_context": { "page": 1, "per_page": 200, "has_more_page": false, "sort_column": "contact_person_id", "sort_order": "A" } }, {...}, {...} ] }

    Get a contact person

    Get the contact person details.
    oauthscope : ZohoBooks.contacts.READ

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

    Request Example

      
    $ curl https://books.zoho.com/api/v3/contacts/{:contact_id}/contactpersons/{:contact_person_id}?organization_id=10234695 -H "Authorization: Zoho-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_person": { "contact_id": 460000000026049, "contact_person_id": 460000000026051, "salutation": "Mr", "first_name": "Will", "last_name": "Smith", "email": "[email protected]", "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://books.zoho.com/api/v3/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 the contact.
    oauthscope : ZohoBooks.contacts.CREATE

    POST /contacts/contactpersons/{:contact_person_id}/primary

    Request Example

      
    $ curl https://books.zoho.com/api/v3/contacts/contactpersons/{:contact_person_id}/primary?organization_id=10234695 -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." }

    Estimates

    An estimate is a quote or a proposal for the products you sell or the services you render to your clients to take your business forward.

    Example

    { "estimates": [ { "estimate_id": 982000000567011, "customer_name": "Bowman & Co", "customer_id": 982000000567001, "status": "draft", "estimate_number": "EST-00002", "reference_number": "QRT-12346", "date": "2013-11-18", "currency_id": 982000000000190, "currency_code": "USD", "total": 40.6, "created_time": "2013-11-18T02:17:40-0800", "accepted_date": " ", "declined_date": " ", "expiry_date": "2013-11-30" } ], "page_context": [ { "page": 1, "per_page": 200, "has_more_page": false, "report_name": "Estimates", "applied_filter": "Status.All", "sort_column": "created_time", "sort_order": "D" } ] }

    Attribute

    list
    The list of all estimates
    estimate_id
    string
    The unique id of a particular estimate
    customer_name
    string
    Search estimates by customer name.Variants customer_name_startswith and customer_name_contains
    customer_id
    string
    Search estimates by customer id..
    status
    string
    Search estimates by status.Allowed Valuesdraft, sent, invoiced , accepted, declined and expired
    estimate_number
    string
    Search estimates by estimate number.Variantsestimate_number_startswith and estimate_number_contains
    reference_number
    string
    Search estimates by reference number.Variants reference_number_startswith and reference_number_contains
    date
    string
    Search estimates by estimate date.Variants date_start, date_end, date_before and date_after
    currency_id
    string
    The id of the customer
    currency_code
    string
    Currency code of the currency in which the customer wants to pay. If currency_code is not specified here, the currency chosen in your Zoho Subscriptions organization will be used for billing. currency_id and currency_symbol are set automatically in accordance to the currency_code.
    total
    double
    Search estimates by estimate total.Variants total_less_than, total_less_equals, total_greater_than and total_greater_equals
    created_time
    string
    The time of creation of the estimates
    accepted_date
    string
    The date of acceptance of the estimates
    declined_date
    string
    The date of declination of the estimates
    expiry_date
    string
    The date of expiration of the estimates
    page_context
    list
    The context of a particular page.
    page
    integer
    Number of pages
    per_page
    integer
    Per page values
    has_more_page
    boolean
    Check if has more pages
    report_name
    string
    The report name
    applied_filter
    string
    The filer applied for sorting
    sort_column
    string
    Sort estimates. Allowed Values customer_name, estimate_number, date, total and created_time
    sort_order
    string
    The order for sorting

    Create an Estimate

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

    POST /estimates

    Request Example

      
    $ curl https://books.zoho.com/api/v3/estimates?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, "template_id": 982000000000143, "place_of_supply": "TN", "gst_treatment": "business_gst", "gst_no": "22AAAAA0000A1Z5", "estimate_number": "EST-00002", "reference_number": "QRT-12346", "date": "2013-11-18", "expiry_date": "2013-11-30", "exchange_rate": 1, "discount": 0, "is_discount_before_tax": true, "discount_type": "item_level", "is_inclusive_tax": false, "custom_body": " ", "custom_subject": " ", "salesperson_name": "Will smith", "custom_fields": [ { "index": 1, "value": "15 Dec 2013" } ], "line_items": [ { "item_id": " ", "line_item_id": 982000000567021, "name": "Hard Drive", "description": "500GB, USB 2.0 interface 1400 rpm, protective hard case.", "product_type": "goods", "hsn_or_sac": 80540, "item_order": 1, "bcy_rate": 120, "rate": 120, "quantity": 1, "unit": " ", "discount_amount": 0, "discount": 0, "tax_id": "982000000557028", "tax_name": "VAT", "tax_type": "tax", "tax_percentage": 12.5, "tax_treatment_code": "uae_others", "item_total": 120 } ], "notes": "Looking forward for your business.", "terms": "Terms & Conditions apply", "shipping_charge": 0, "adjustment": 0, "adjustment_description": " ", "tax_id": "982000000557028", "tax_exemption_id": 11149000000061054, "tax_authority_id": 11149000000061052, "tax_treatment": "vat_registered", "item_id": " ", "line_item_id": 982000000567021, "name": "Hard Drive", "description": "500GB, USB 2.0 interface 1400 rpm, protective hard case.", "rate": 120, "unit": " ", "quantity": 1 }"'

    Response Example

      
    HTTP/1.1 201 Created Content-Type:application/json;charset=UTF-8 { "code": 0, "message": "The estimate has been created", "estimate": { "estimate": { "estimate_id": 982000000567011, "estimate_number": "EST-00002", "date": "2013-11-18", "reference_number": "QRT-12346", "is_pre_gst": false, "place_of_supply": "TN", "gst_no": "22AAAAA0000A1Z5", "gst_treatment": "business_gst", "tax_treatment": "vat_registered", "status": "draft", "customer_id": 982000000567001, "customer_name": "Bowman & Co", "currency_id": 982000000000190, "currency_code": "USD", "exchange_rate": 1, "expiry_date": "2013-11-30", "discount": 0, "is_discount_before_tax": true, "discount_type": "item_level", "is_inclusive_tax": false, "line_items": [ { "item_id": " ", "line_item_id": 982000000567021, "name": "Hard Drive", "description": "500GB, USB 2.0 interface 1400 rpm, protective hard case.", "item_order": 1, "product_type": "goods", "bcy_rate": 120, "rate": 120, "quantity": 1, "unit": " ", "discount_amount": 0, "discount": 0, "tax_id": "982000000557028", "tax_name": "VAT", "tax_type": "tax", "tax_percentage": 12.5, "tax_treatment_code": "uae_others", "item_total": 120 } ], "shipping_charge": 0, "adjustment": 0, "adjustment_description": " ", "sub_total": 153, "total": 40.6, "tax_total": 22.6, "price_precision": 2, "taxes": [ { "tax_name": "VAT", "tax_amount": 19.13 } ], "billing_address": { "address": "4900 Hopyard Rd, Suite 310", "city": "Pleasanton", "state": "CA", "zip": 94588, "country": "U.S.A", "fax": "+1-925-924-9600" }, "shipping_address": { "address": "4900 Hopyard Rd, Suite 310", "city": "Pleasanton", "state": "CA", "zip": 94588, "country": "U.S.A", "fax": "+1-925-924-9600" }, "notes": "Looking forward for your business.", "terms": "Terms & Conditions apply", "custom_fields": [ { "index": 1, "show_on_pdf": false, "value": "15 Dec 2013", "label": "Delivery Date" } ], "template_id": 982000000000143, "template_name": "Service - Classic", "created_time": "2013-11-18T02:17:40-0800", "last_modified_time": "2016-06-17T04:46:45-0500", "salesperson_id": 982000000567003, "salesperson_name": "Will smith" } } }

    ARGUMENTS

    customer_id
    Required
    Search estimates by customer id..
    contact_persons
    Optional
    Array if contact person(S) for whom estimate has to be sent.
    template_id
    Optional
    ID of the pdf template associated with the estimate.
    place_of_supply
    India Edition and GCC Editions only.
    Optional
    Place where the goods/services are supplied to. (If not given, place of contact given for the contact will be taken)
    Supported codes for UAE emirates are :
    Abu Dhabi - AB,
    Ajman - AJ,
    Dubai - DU,
    Fujairah - FU,
    Ras al-Khaimah - RA,
    Sharjah - SH,
    Umm al-Quwain - UM
    Supported codes for the GCC countries are :
    United Arab Emirates - AE,
    Saudi Arabia - SA,
    Bahrain - BH,
    Kuwait - KW,
    Oman - OM,
    Qatar - QA.
    gst_treatment
    India Edition only
    Optional
    Choose whether the contact is GST registered/unregistered/consumer/overseas. Allowed values are business_gst , business_none , overseas , consumer .
    gst_no
    India Edition only
    Optional
    15 digit GST identification number of the customer.
    estimate_number
    Optional
    Search estimates by estimate number.Variantsestimate_number_startswith and estimate_number_contains
    reference_number
    Optional
    Search estimates by reference number.Variants reference_number_startswith and reference_number_contains
    date
    Optional
    Search estimates by estimate date.Variants date_start, date_end, date_before and date_after
    expiry_date
    Optional
    The date of expiration of the estimates
    exchange_rate
    Optional
    Exchange rate of the currency.
    discount
    Optional
    Discount applied to the invoice. It can be either in % or in amount. e.g. 12.5% or 190.
    is_discount_before_tax
    Optional
    Used to specify how the discount has to applied. Either before or after the calculation of tax.
    discount_type
    Optional
    How the discount is specified. Allowed values are entity_level or item_level.Allowed Values: entity_level and item_level
    is_inclusive_tax
    Not applicable for US and Canada editions
    Optional
    Used to specify whether the line item rates are inclusive or exclusive of tax.
    custom_body
    Optional
    custom_subject
    Optional
    salesperson_name
    Optional
    Name of the sales person.
    custom_fields
    Optional
    Custom fields for an estimate.
    index
    Optional
    value
    Optional
    Required
    Line items of an estimate.
    item_id
    Optional
    ID of the item.
    line_item_id
    Optional
    ID of the line item. Mandatory, if the existing line item has to be updated. If empty, a new line item will be created.
    name
    Optional
    The name of the line item
    description
    Optional
    The description of the line items
    product_type
    Optional
    Enter goods/services
    hsn_or_sac
    India Edition only
    Optional
    Add HSN/SAC code for your goods/services
    item_order
    Optional
    The order of the line item_order
    bcy_rate
    Optional
    base currency rate
    rate
    Optional
    Rate of the line item.
    quantity
    Optional
    The quantity of line item
    unit
    Optional
    Unit of the line item e.g. kgs, Nos.
    discount_amount
    Optional
    The discount amount on the line item
    discount
    Optional
    Discount applied to the invoice. It can be either in % or in amount. e.g. 12.5% or 190.
    tax_id
    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
    tax_treatment_code
    GCC Editions only
    Optional
    Specify reason for using out of scope.
    Supported values for UAE are uae_same_tax_group, uae_reimbursed_expense and uae_others.
    Supported values for Bahrain are bahrain_same_tax_group, bahrain_transfer_of_concern, bahrain_disbursement, bahrain_head_to_branch_transaction and bahrain_others.
    Supported values for Saudi Arabia are ksa_pvt_health, ksa_pvt_edu and ksa_house_sales.
    item_total
    Optional
    The total amount of the line items
    notes
    Optional
    The notes added below expressing gratitude or for conveying some information.
    terms
    Optional
    shipping_charge
    Optional
    Shipping charges applied to the invoice.
    adjustment
    Optional
    Adjustments made to the invoice.
    adjustment_description
    Optional
    Customize the adjustment description. E.g. Rounding off.
    tax_id
    Optional
    ID of the tax or tax group applied to the estimate
    tax_exemption_id
    Inida and US edition only
    Optional
    ID of the tax exemption.
    tax_authority_id
    US edition only
    Optional
    ID of the tax authority. Tax authority depends on the location of the customer. For example, if the customer is located in NY, then the tax authority is NY tax authority.
    avatax_use_code
    Avalara integration only
    Optional
    Used to group like customers for exemption purposes. It is a custom value that links customers to a tax rule. Select from Avalara [standard codes][1] or enter a custom code.
    avatax_exempt_no
    Avalara integration only
    Optional
    Exemption certificate number of the customer.
    vat_treatment
    Optional
    Enter vat treatment
    tax_treatment
    GCC Editions only
    Optional
    VAT treatment for the Estimate.Allowed Values: vat_registered,vat_not_registered,gcc_vat_not_registered,gcc_vat_registered,non_gcc.
    dz_vat_registered and dz_vat_not_registered supported only for UAE.
    item_id
    Optional
    ID of the item.
    line_item_id
    Optional
    ID of the line item. Mandatory, if the existing line item has to be updated. If empty, a new line item will be created.
    name
    Optional
    The name of the line item
    description
    Optional
    The description of the line items
    rate
    Optional
    Rate of the line item.
    unit
    Optional
    Unit of the line item e.g. kgs, Nos.
    quantity
    Optional
    The quantity of line item

    Query Params

    send
    Optional
    Send the estimate to the contact person(s) associated with the estimate.Allowed Values: true and false
    ignore_auto_number_generation
    Optional
    Ignore auto estimate number generation for this estimate. This mandates the estimate number.

    Update an Estimate

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

    PUT /estimates/{:estimate_id}

    Request Example

      
    $ curl https://books.zoho.com/api/v3/estimates/{:estimate_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, "template_id": 982000000000143, "place_of_supply": "TN", "gst_treatment": "business_gst", "gst_no": "22AAAAA0000A1Z5", "estimate_number": "EST-00002", "reference_number": "QRT-12346", "date": "2013-11-18", "expiry_date": "2013-11-30", "exchange_rate": 1, "discount": 0, "is_discount_before_tax": true, "discount_type": "item_level", "is_inclusive_tax": false, "custom_body": " ", "custom_subject": " ", "salesperson_name": "Will smith", "custom_fields": [ { "index": 1, "value": "15 Dec 2013" } ], "line_items": [ { "item_id": " ", "line_item_id": 982000000567021, "name": "Hard Drive", "description": "500GB, USB 2.0 interface 1400 rpm, protective hard case.", "product_type": "goods", "hsn_or_sac": 80540, "item_order": 1, "bcy_rate": 120, "rate": 120, "quantity": 1, "unit": " ", "discount_amount": 0, "discount": 0, "tax_id": "982000000557028", "tax_name": "VAT", "tax_type": "tax", "tax_percentage": 12.5, "tax_treatment_code": "uae_others", "item_total": 120 } ], "notes": "Looking forward for your business.", "terms": "Terms & Conditions apply", "shipping_charge": 0, "adjustment": 0, "adjustment_description": " ", "tax_id": "982000000557028", "tax_exemption_id": 11149000000061054, "tax_authority_id": 11149000000061052, "tax_treatment": "vat_registered", "item_id": " ", "line_item_id": 982000000567021, "name": "Hard Drive", "description": "500GB, USB 2.0 interface 1400 rpm, protective hard case.", "rate": 120, "unit": " ", "quantity": 1 }"'

    Response Example

      
    HTTP/1.1 200 OK Content-Type:application/json;charset=UTF-8 { "code": 0, "message": "Estimate information has been updated.", "estimate": { "estimate": { "estimate_id": 982000000567011, "estimate_number": "EST-00002", "date": "2013-11-18", "reference_number": "QRT-12346", "is_pre_gst": false, "place_of_supply": "TN", "gst_no": "22AAAAA0000A1Z5", "gst_treatment": "business_gst", "tax_treatment": "vat_registered", "status": "draft", "customer_id": 982000000567001, "customer_name": "Bowman & Co", "currency_id": 982000000000190, "currency_code": "USD", "exchange_rate": 1, "expiry_date": "2013-11-30", "discount": 0, "is_discount_before_tax": true, "discount_type": "item_level", "is_inclusive_tax": false, "line_items": [ { "item_id": " ", "line_item_id": 982000000567021, "name": "Hard Drive", "description": "500GB, USB 2.0 interface 1400 rpm, protective hard case.", "item_order": 1, "product_type": "goods", "bcy_rate": 120, "rate": 120, "quantity": 1, "unit": " ", "discount_amount": 0, "discount": 0, "tax_id": "982000000557028", "tax_name": "VAT", "tax_type": "tax", "tax_percentage": 12.5, "tax_treatment_code": "uae_others", "item_total": 120 } ], "shipping_charge": 0, "adjustment": 0, "adjustment_description": " ", "sub_total": 153, "total": 40.6, "tax_total": 22.6, "price_precision": 2, "taxes": [ { "tax_name": "VAT", "tax_amount": 19.13 } ], "billing_address": { "address": "4900 Hopyard Rd, Suite 310", "city": "Pleasanton", "state": "CA", "zip": 94588, "country": "U.S.A", "fax": "+1-925-924-9600" }, "shipping_address": { "address": "4900 Hopyard Rd, Suite 310", "city": "Pleasanton", "state": "CA", "zip": 94588, "country": "U.S.A", "fax": "+1-925-924-9600" }, "notes": "Looking forward for your business.", "terms": "Terms & Conditions apply", "custom_fields": [ { "index": 1, "show_on_pdf": false, "value": "15 Dec 2013", "label": "Delivery Date" } ], "template_id": 982000000000143, "template_name": "Service - Classic", "created_time": "2013-11-18T02:17:40-0800", "last_modified_time": "2016-06-17T04:46:45-0500", "salesperson_id": 982000000567003, "salesperson_name": "Will smith" } } }

    ARGUMENTS

    customer_id
    Required
    Search estimates by customer id..
    contact_persons
    Optional
    Array if contact person(S) for whom estimate has to be sent.
    template_id
    Optional
    ID of the pdf template associated with the estimate.
    place_of_supply
    India Edition and GCC Editions only.
    Optional
    Place where the goods/services are supplied to. (If not given, place of contact given for the contact will be taken)
    Supported codes for UAE emirates are :
    Abu Dhabi - AB,
    Ajman - AJ,
    Dubai - DU,
    Fujairah - FU,
    Ras al-Khaimah - RA,
    Sharjah - SH,
    Umm al-Quwain - UM
    Supported codes for the GCC countries are :
    United Arab Emirates - AE,
    Saudi Arabia - SA,
    Bahrain - BH,
    Kuwait - KW,
    Oman - OM,
    Qatar - QA.
    gst_treatment
    India Edition only
    Optional
    Choose whether the contact is GST registered/unregistered/consumer/overseas. Allowed values are business_gst , business_none , overseas , consumer .
    gst_no
    India Edition only
    Optional
    15 digit GST identification number of the customer.
    estimate_number
    Optional
    Search estimates by estimate number.Variantsestimate_number_startswith and estimate_number_contains
    reference_number
    Optional
    Search estimates by reference number.Variants reference_number_startswith and reference_number_contains
    date
    Optional
    Search estimates by estimate date.Variants date_start, date_end, date_before and date_after
    expiry_date
    Optional
    The date of expiration of the estimates
    exchange_rate
    Optional
    Exchange rate of the currency.
    discount
    Optional
    Discount applied to the invoice. It can be either in % or in amount. e.g. 12.5% or 190.
    is_discount_before_tax
    Optional
    Used to specify how the discount has to applied. Either before or after the calculation of tax.
    discount_type
    Optional
    How the discount is specified. Allowed values are entity_level or item_level.Allowed Values: entity_level and item_level
    is_inclusive_tax
    Not applicable for US and Canada editions
    Optional
    Used to specify whether the line item rates are inclusive or exclusive of tax.
    custom_body
    Optional
    custom_subject
    Optional
    salesperson_name
    Optional
    Name of the sales person.
    custom_fields
    Required
    Custom fields for an estimate.
    index
    Optional
    value
    Optional
    Optional
    Line items of an estimate.
    item_id
    Optional
    ID of the item.
    line_item_id
    Optional
    ID of the line item. Mandatory, if the existing line item has to be updated. If empty, a new line item will be created.
    name
    Optional
    The name of the line item
    description
    Optional
    The description of the line items
    product_type
    Optional
    Enter goods/services
    hsn_or_sac
    India Edition only
    Optional
    Add HSN/SAC code for your goods/services
    item_order
    Optional
    The order of the line item_order
    bcy_rate
    Optional
    base currency rate
    rate
    Optional
    Rate of the line item.
    quantity
    Optional
    The quantity of line item
    unit
    Optional
    Unit of the line item e.g. kgs, Nos.
    discount_amount
    Optional
    The discount amount on the line item
    discount
    Optional
    Discount applied to the invoice. It can be either in % or in amount. e.g. 12.5% or 190.
    tax_id
    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
    tax_treatment_code
    GCC Editions only
    Optional
    Specify reason for using out of scope.
    Supported values for UAE are uae_same_tax_group, uae_reimbursed_expense and uae_others.
    Supported values for Bahrain are bahrain_same_tax_group, bahrain_transfer_of_concern, bahrain_disbursement, bahrain_head_to_branch_transaction and bahrain_others.
    Supported values for Saudi Arabia are ksa_pvt_health, ksa_pvt_edu and ksa_house_sales.
    item_total
    Optional
    The total amount of the line items
    notes
    Optional
    The notes added below expressing gratitude or for conveying some information.
    terms
    Optional
    shipping_charge
    Optional
    Shipping charges applied to the invoice.
    adjustment
    Optional
    Adjustments made to the invoice.
    adjustment_description
    Optional
    Customize the adjustment description. E.g. Rounding off.
    tax_id
    Optional
    ID of the tax or tax group applied to the estimate
    tax_exemption_id
    Inida and US edition only
    Optional
    ID of the tax exemption.
    tax_authority_id
    US edition only
    Optional
    ID of the tax authority. Tax authority depends on the location of the customer. For example, if the customer is located in NY, then the tax authority is NY tax authority.
    avatax_use_code
    Avalara integration only
    Optional
    Used to group like customers for exemption purposes. It is a custom value that links customers to a tax rule. Select from Avalara [standard codes][1] or enter a custom code.
    avatax_exempt_no
    Avalara integration only
    Optional
    Exemption certificate number of the customer.
    vat_treatment
    Optional
    Enter vat treatment
    tax_treatment
    GCC Editions only
    Optional
    VAT treatment for the Estimate.Allowed Values: vat_registered,vat_not_registered,gcc_vat_not_registered,gcc_vat_registered,non_gcc.
    dz_vat_registered and dz_vat_not_registered supported only for UAE.
    item_id
    Optional
    ID of the item.
    line_item_id
    Optional
    ID of the line item. Mandatory, if the existing line item has to be updated. If empty, a new line item will be created.
    name
    Optional
    The name of the line item
    description
    Optional
    The description of the line items
    rate
    Optional
    Rate of the line item.
    unit
    Optional
    Unit of the line item e.g. kgs, Nos.
    quantity
    Optional
    The quantity of line item

    Query Params

    ignore_auto_number_generation
    Optional
    Ignore auto estimate number generation for this estimate. This mandates the estimate number.

    Get an estimate

    Get the details of an estimate.
    oauthscope : ZohoBooks.estimates.READ

    GET /estimates/{:estimate_id}

    Request Example

      
    $ curl https://books.zoho.com/api/v3/estimates/{:estimate_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", "estimate": { "estimate": { "estimate_id": 982000000567011, "estimate_number": "EST-00002", "date": "2013-11-18", "reference_number": "QRT-12346", "is_pre_gst": false, "place_of_supply": "TN", "gst_no": "22AAAAA0000A1Z5", "gst_treatment": "business_gst", "tax_treatment": "vat_registered", "status": "draft", "customer_id": 982000000567001, "customer_name": "Bowman & Co", "currency_id": 982000000000190, "currency_code": "USD", "exchange_rate": 1, "expiry_date": "2013-11-30", "discount": 0, "is_discount_before_tax": true, "discount_type": "item_level", "is_inclusive_tax": false, "is_viewed_by_client": true, "client_viewed_time": "2016-06-19T05:49:12-0500", "line_items": [ { "item_id": " ", "line_item_id": 982000000567021, "name": "Hard Drive", "description": "500GB, USB 2.0 interface 1400 rpm, protective hard case.", "item_order": 1, "product_type": "goods", "bcy_rate": 120, "rate": 120, "quantity": 1, "unit": " ", "discount_amount": 0, "discount": 0, "tax_id": "982000000557028", "tax_name": "VAT", "tax_type": "tax", "tax_percentage": 12.5, "tax_treatment_code": "uae_others", "item_total": 120 } ], "shipping_charge": 0, "adjustment": 0, "adjustment_description": " ", "sub_total": 153, "total": 40.6, "tax_total": 22.6, "price_precision": 2, "taxes": [ { "tax_name": "VAT", "tax_amount": 19.13 } ], "billing_address": { "address": "4900 Hopyard Rd, Suite 310", "city": "Pleasanton", "state": "CA", "zip": 94588, "country": "U.S.A", "fax": "+1-925-924-9600" }, "shipping_address": { "address": "4900 Hopyard Rd, Suite 310", "city": "Pleasanton", "state": "CA", "zip": 94588, "country": "U.S.A", "fax": "+1-925-924-9600" }, "custom_fields": [ { "index": 1, "show_on_pdf": false, "value": "15 Dec 2013", "label": "Delivery Date" } ], "template_id": 982000000000143, "template_name": "Service - Classic", "created_time": "2013-11-18T02:17:40-0800", "last_modified_time": "2016-06-17T04:46:45-0500", "salesperson_id": 982000000567003, "salesperson_name": "Will smith" } } }

    Query Params

    print
    Optional
    Print the exported pdf.
    accept
    Optional
    Get the details of a particular estimate in formats such as json/ pdf/ html. Default format is json.Allowed Values: json, pdf and html

    List estimates

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

    GET /estimates

    Request Example

      
    $ curl https://books.zoho.com/api/v3/estimates?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", "estimates": [ { "estimates": [ { "estimate_id": 982000000567011, "customer_name": "Bowman & Co", "customer_id": 982000000567001, "status": "draft", "estimate_number": "EST-00002", "reference_number": "QRT-12346", "date": "2013-11-18", "currency_id": 982000000000190, "currency_code": "USD", "total": 40.6, "created_time": "2013-11-18T02:17:40-0800", "last_modified_time": "2016-06-17T04:46:45-0500", "accepted_date": " ", "declined_date": " ", "expiry_date": "2013-11-30", "has_attachment": false, "is_viewed_by_client": true, "client_viewed_time": "2016-06-19T05:49:12-0500" } ], "page_context": [ { "page": 1, "per_page": 200, "has_more_page": false, "report_name": "Estimates", "applied_filter": "Status.All", "sort_column": "created_time", "sort_order": "D" } ] }, {...}, {...} ] }

    Query Params

    estimate_number
    Optional
    Search estimates by estimate number.Variantsestimate_number_startswith and estimate_number_contains
    reference_number
    Optional
    Search estimates by reference number.Variants reference_number_startswith and reference_number_contains
    customer_name
    Optional
    Search estimates by customer name.Variants customer_name_startswith and customer_name_contains
    total
    Optional
    Search estimates by estimate total.Variants total_less_than, total_less_equals, total_greater_than and total_greater_equals
    customer_id
    Optional
    Search estimates by customer id..
    item_id
    Optional
    ID of the item.
    item_name
    Optional
    Search estimates by item name.Variants item_name_startswith and item_name_contains
    item_description
    Optional
    Search estimates by item description.Variantsitem_description_startswith and item_description_contains
    custom_field
    Optional
    Search estimates by custom field.Variantscustom_field_startswith and custom_field_contains
    expiry_date
    Optional
    The date of expiration of the estimates
    date
    Optional
    Search estimates by estimate date.Variants date_start, date_end, date_before and date_after
    status
    Optional
    Search estimates by status.Allowed Valuesdraft, sent, invoiced , accepted, declined and expired
    filter_by
    Optional
    Filter estimates by status.Allowed Values Status.All, Status.Sent, Status.Draft, Status.Invoiced, Status.Accepted, Status.Declined and Status.Expired
    search_text
    Optional
    Search estimates by estimate number or reference or customer name.
    sort_column
    Optional
    Sort estimates. Allowed Values customer_name, estimate_number, date, total and created_time

    Delete an Estimate

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

    DELETE /estimates/{:estimate_id}

    Request Example

      
    $ curl https://books.zoho.com/api/v3/estimates/{:estimate_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 estimate has been deleted." }

    Mark an estimate as sent

    Mark a draft estimate as sent.
    oauthscope : ZohoBooks.estimates.CREATE

    POST /estimates/{:estimate_id}/status/sent

    Request Example

      
    $ curl https://books.zoho.com/api/v3/estimates/{:estimate_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": "Estimate status has been changed to Sent" }

    Mark an estimate as accepted

    Mark a sent estimate as accepted if the customer has accepted it.
    oauthscope : ZohoBooks.estimates.CREATE

    POST /estimates/{:estimate_id}/status/accepted

    Request Example

      
    $ curl https://books.zoho.com/api/v3/estimates/{:estimate_id}/status/accepted?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": "Estimate status has been changed to Accepted." }

    Mark an estimate as declined

    Mark a sent estimate as declined if the customer has rejected it.
    oauthscope : ZohoBooks.estimates.CREATE

    POST /estimates/{:estimate_id}/status/declined

    Request Example

      
    $ curl https://books.zoho.com/api/v3/estimates/{:estimate_id}/status/declined?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": "Estimate status has been changed to Declined." }

    Submit an estimate for approval

    Submit an estimate for approval.
    oauthscope : ZohoBooks.estimates.CREATE

    POST /estimates/{:estimate_id}/submit

    Request Example

      
    $ curl https://books.zoho.com/api/v3/estimates/{:estimate_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 estimate has been successfully submitted for approval" }

    Approve an estimate.

    Approve an estimate.
    oauthscope : ZohoBooks.estimates.CREATE

    POST /estimates/{:estimate_id}/approve

    Request Example

      
    $ curl https://books.zoho.com/api/v3/estimates/{:estimate_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 estimate." }

    Email an estimate

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

    POST /estimates/{:estimate_id}/email

    Request Example

      
    $ curl https://books.zoho.com/api/v3/estimates/{:estimate_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": [ {} ], "cc_mail_ids": [ {} ], "subject": "Statement of transactions with Zillium Inc", "body": "Dear Customer, Thanks for your business enquiry. The estimate EST-000002 is attached with this email. We can get started if you send us your consent. For any assistance you can reach us via email or phone. Looking forward to hearing back from you. Here's an overview of the estimate for your reference. Estimate Overview: Estimate : EST-000002 Date : 03 Oct 2013 Amount : $36.47 Regards<br>\\nZillium Inc<br>\\n\"\"" }"'

    Response Example

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

    ARGUMENTS

    send_from_org_email_id
    Optional
    Boolean to trigger the email from the organization's email address
    to_mail_ids
    Required
    Array of email address of the recipients.
    cc_mail_ids
    Optional
    Array of email address of the recipients to be cced.
    subject
    Optional
    Subject of an email has to be sent.
    body
    Optional
    Body of an email has to be sent.

    Query Params

    attachments
    Optional
    Files to be attached to the email

    Email multiple estimates

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

    POST /estimates/email

    Request Example

      
    $ curl https://books.zoho.com/api/v3/estimates/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 estimates." }

    Query Params

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

    Get estimate email content

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

    GET /estimates/{:estimate_id}/email

    Request Example

      
    $ curl https://books.zoho.com/api/v3/estimates/{:estimate_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", "body": "Dear Customer, Thanks for your business enquiry. The estimate EST-000002 is attached with this email. We can get started if you send us your consent. For any assistance you can reach us via email or phone. Looking forward to hearing back from you. Here's an overview of the estimate for your reference. Estimate Overview: Estimate : EST-000002 Date : 03 Oct 2013 Amount : $36.47 Regards<br>\\nZillium Inc<br>\\n\"\"", "error_list": [ {...} ], "subject": "Statement of transactions with Zillium Inc", "emailtemplates": [ { "selected": true, "name": "Hard Drive", "email_template_id": 982000000000079 } ], "to_contacts": [ { "first_name": "Sujin", "selected": true, "phone": "+1-925-921-9201", "last_name": "Kumar", "salutation": ":Mr", "contact_person_id": "982000000567003", "mobile": "+1-4054439562" } ], "file_name": "EST-00001.pdf", "from_emails": [ { "user_name": "John Smith", "selected": true } ], "customer_id": 982000000567001 }

    Query Params

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

    Bulk export estimates

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

    GET /estimates/pdf

    Request Example

      
    $ curl https://books.zoho.com/api/v3/estimates/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": "Invalid value passed for estimate_ids" }

    Query Params

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

    Bulk print estimates

    Export estimates as pdf and print them. Maximum of 25 estimates can be printed.
    oauthscope : ZohoBooks.estimates.READ

    GET /estimates/print

    Request Example

      
    $ curl https://books.zoho.com/api/v3/estimates/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

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

    Update billing address

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

    PUT /estimates/{:estimate_id}/address/billing

    Request Example

      
    $ curl https://books.zoho.com/api/v3/estimates/{:estimate_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, "country": "China", "fax": "+86-10-82637827" }"'

    Response Example

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

    ARGUMENTS

    address
    Optional
    Billing address for the estimate
    city
    Optional
    City of the customer’s billing address.
    state
    Optional
    State of the customer’s billing address.
    zip
    Optional
    Zip code of the customer’s billing address.
    country
    Optional
    Country of the customer’s billing address.
    fax
    Optional
    Customer's fax number.

    Update shipping address

    Updates the shipping address for an existing estimate alone.
    oauthscope : ZohoBooks.estimates.UPDATE

    PUT /estimates/{:estimate_id}/address/shipping

    Request Example

      
    $ curl https://books.zoho.com/api/v3/estimates/{:estimate_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, Suite 310", "city": "Pleasanton", "state": "CA", "zip": 94588, "country": "U.S.A", "fax": "+1-925-924-9600" }"'

    Response Example

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

    ARGUMENTS

    address
    Optional
    Billing address for the estimate
    city
    Optional
    City of the customer’s billing address.
    state
    Optional
    State of the customer’s billing address.
    zip
    Optional
    Zip code of the customer’s billing address.
    country
    Optional
    Country of the customer’s billing address.
    fax
    Optional
    Customer's fax number.

    List estimate template

    Get all estimate pdf templates.
    oauthscope : ZohoBooks.estimates.READ

    GET /estimates/templates

    Request Example

      
    $ curl https://books.zoho.com/api/v3/estimates/templates?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", "templates": [ { "templates": { "template_name": "Service - Classic", "template_id": 982000000000143, "template_type": "classic" } }, {...}, {...} ] }

    Update estimate template

    Update the pdf template associated with the estimate.
    oauthscope : ZohoBooks.estimates.UPDATE

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

    Request Example

      
    $ curl https://books.zoho.com/api/v3/estimates/{:estimate_id}/templates/{:template_id}?organization_id=10234695 -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": "Estimate information has been updated." }

    List estimate comments & history

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

    GET /estimates/{:estimate_id}/comments

    Request Example

      
    $ curl https://books.zoho.com/api/v3/estimates/{:estimate_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, "estimate_id": 982000000567011, "description": "Estimate created", "commented_by_id": 982000000554041, "commented_by": "Sujin Kumar", "comment_type": "system", "date": "2013-11-18", "date_description": "yesterday", "time": "2:02 AM", "operation_type": "Added", "transaction_id": " ", "transaction_type": "estimate" } }, {...}, {...} ] }

    Add Comments

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

    POST /estimates/{:estimate_id}/comments

    Request Example

      
    $ curl https://books.zoho.com/api/v3/estimates/{:estimate_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": "Estimate marked as sent", "show_comment_to_clients": true }"'

    Response Example

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

    ARGUMENTS

    description
    Optional
    The description of the line items
    show_comment_to_clients
    Optional
    Boolean to show the comments to contacts in portal.

    Update comment

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

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

    Request Example

      
    $ curl https://books.zoho.com/api/v3/estimates/{:estimate_id}/comments/{:comment_id}?organization_id=10234695 -X PUT -H "Authorization: Zoho-oauthtoken 1000.41d9f2cfbd1b7a8f9e314b7aff7bc2d1.8fcc9810810a216793f385b9dd6e125f" -H "Content-Type: application/x-www-form-urlencoded;charset=UTF-8" -F 'JSONString="{ "description": "Estimate created", "show_comment_to_clients": " " }"'

    Response Example

      
    HTTP/1.1 200 OK Content-Type:application/json;charset=UTF-8 { "code": 0, "message": "Comment has been updated successfully.", "comment": { "comment_id": 982000000567019, "estimate_id": 982000000567011, "description": "500GB, USB 2.0 interface 1400 rpm, protective hard case.", "commented_by_id": 982000000554041, "commented_by": "Sujin Kumar", "date": "2013-11-18", "date_description": "yesterday", "time": "2:02 AM", "comment_type": "system" } }

    ARGUMENTS

    description
    Optional
    The description of the line items
    show_comment_to_clients
    Optional
    Boolean to show the comments to contacts in portal.

    Delete a comment

    Delete an estimate comment.
    oauthscope : ZohoBooks.estimates.DELETE

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

    Request Example

      
    $ curl https://books.zoho.com/api/v3/estimates/{:estimate_id}/comments/{:comment_id}?organization_id=10234695 -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." }

    Sales-Order

    A sales order is a financial document that confirms an impending sale. It is raised when an initial estimate is approved and the transaction is underway, and details the exact quantity, price and delivery details of the products or services being sold.

    Example

    { "salesorder": [ { "salesorder_id": "460000000039129", "documents": [ {} ], "is_pre_gst": false, "gst_no": "22AAAAA0000A1Z5", "gst_treatment": "business_gst", "place_of_supply": "TN", "tax_treatment": "vat_registered", "salesorder_number": "SO-00001", "date": "2014-07-28", "status": "open", "reference_number": "REF-001", "customer_id": "460000000017138", "customer_name": "SAF Instruments Inc", "contact_persons": [ "460000000870911", "460000000870915" ], "currency_id": "460000000000097", "currency_code": "USD", "currency_symbol": "$", "exchange_rate": 1.233, "discount_amount": 0, "discount_applied_on_amount": 0, "is_discount_before_tax": true, "discount_type": "entity_level", "delivery_method": "Air", "is_inclusive_tax": false, "line_items": [ { "item_order": 0, "item_id": "460000000017088", "rate": 120, "name": "Hard Drive", "description": "500GB, USB 2.0 interface 1400 rpm, protective hard case.", "quantity": 40, "product_type": "goods", "hsn_or_sac": 80540, "tax_id": "460000000017094", "tags": [ {} ], "unit": "Nos", "item_custom_fields": [ { "index": 1, "value": "Normal", "label": "Priority" } ], "tax_treatment_code": "uae_others" } ], "shipping_charge": 2, "adjustment": 0.2, "adjustment_description": "Adjustment", "sub_total": 11800, "tax_total": 600, "total": 12400, "taxes": [ { "tax_id": "460000000017094", "tax_amount": 600 } ], "price_precision": 2, "is_emailed": false, "billing_address": { "address": "B-1104, 11F, \nHorizon International Tower, \nNo. 6, ZhiChun Road, HaiDian District", "street2": "McMillan Avenue", "city": "Beijing", "state": "Beijing", "zip": "1000881", "country": "China", "fax": "+86-10-82637827" }, "shipping_address": { "address": "B-1104, 11F, \nHorizon International Tower, \nNo. 6, ZhiChun Road, HaiDian District", "street2": "McMillan Avenue", "city": "Beijing", "state": "Beijing", "zip": "1000881", "country": "China", "fax": "+86-10-82637827" }, "custom_fields": [ { "index": 1, "value": "Normal", "label": "Priority" } ], "template_id": "460000000021001", "template_name": "Standard Template", "page_width": "8.27in", "page_height": "11.69in", "orientation": "portrait", "template_type": "standard", "created_time": "2014-07-28T08:29:07+0530", "last_modified_time": "2014-08-25T11:23:26+0530", "created_by_id": "460000000053001", "can_send_in_mail": true, "salesperson_name": "John Roberts" } ] }

    Attribute

    list
    salesorder_id
    string
    ID of the Sales Order
    list
    is_pre_gst
    India Edition only.
    boolean
    Applicable for transactions that fall before july 1, 2017
    gst_no
    India Edition only.
    string
    15 digit GST identification number of the customer.
    gst_treatment
    India Edition only.
    string
    Choose whether the contact is GST registered/unregistered/consumer/overseas. Allowed values are business_gst , business_none , overseas , consumer .
    place_of_supply
    India Edition and GCC Editions only.
    string
    Place where the goods/services are supplied to. (If not given, place of contact given for the contact will be taken)
    Supported codes for UAE emirates are :
    Abu Dhabi - AB,
    Ajman - AJ,
    Dubai - DU,
    Fujairah - FU,
    Ras al-Khaimah - RA,
    Sharjah - SH,
    Umm al-Quwain - UM
    Supported codes for the GCC countries are :
    United Arab Emirates - AE,
    Saudi Arabia - SA,
    Bahrain - BH,
    Kuwait - KW,
    Oman - OM,
    Qatar - QA.
    vat_treatment
    string
    Enter vat treatment
    tax_treatment
    GCC Editions only
    string
    VAT treatment for the sales order.Allowed Values: vat_registered,vat_not_registered,gcc_vat_not_registered,gcc_vat_registered,non_gcc.
    dz_vat_registered and dz_vat_not_registered supported only for UAE.
    zcrm_potential_id
    string
    zcrm_potential_name
    string
    salesorder_number
    string
    Mandatory if auto number generation is disabled.
    date
    string
    The date, the sales order is created.
    status
    string
    Status of the Sales Order
    shipment_date
    string
    Shipping date of sales order.
    reference_number
    string
    Reference Number of the Sales Order.
    customer_id
    string
    ID of the customer to whom the sales order has to be created.
    customer_name
    string
    Name of the customer associated with the Sales Order
    contact_persons
    array
    Array of contact person(s) for whom sales order has to be sent.
    currency_id
    string
    ID of the Currency in Sales Order
    currency_code
    string
    Code of the Currency involved in the Sales Order
    currency_symbol
    string
    exchange_rate
    double
    Exchange rate of the currency.
    discount_amount
    double
    discount
    string
    Discount applied to the sales order. It can be either in % or in amount. e.g. 12.5% or 190.
    discount_applied_on_amount
    integer
    is_discount_before_tax
    boolean
    Used to specify how the discount has to applied. Either before or after the calculation of tax.
    discount_type
    string
    How the discount is specified. Allowed values are entity_level or item_level. Allowed Values: entity_level and item_level.
    estimate_id
    string
    ID of the estimate from which the sales order is created.
    delivery_method
    string
    delivery_method_id
    string
    is_inclusive_tax
    Not applicable for US and CA editions
    boolean
    Used to specify whether the line item rates are inclusive or exclusive of tax.
    list
    Line items of a sales order.
    item_order
    integer
    item_id
    string
    ID of the item.
    rate
    double
    Rate of the line item.
    name
    string
    Name of the line item.
    description
    string
    Description of the line item.
    quantity
    double
    Quantity of the line item.
    product_type
    string
    Enter goods/services
    hsn_or_sac
    India Edition only
    string
    Add HSN/SAC code for your goods/services
    warehouse_id
    string
    ID of the warehouse
    discount
    string
    Discount applied to the sales order. It can be either in % or in amount. e.g. 12.5% or 190.
    tax_id
    string
    ID of the tax or tax group applied
    unit
    string
    Unit of the line item e.g. kgs, Nos.
    item_custom_fields
    list
    Custom fields for a sales order items.
    custom_field_id
    long
    ID of the Custom Field
    index
    integer
    value
    string
    label
    string
    tax_exemption_id
    India Edition and US Edition only
    string
    ID of the tax exemption applied
    tax_exemption_code
    India Edition and US Edition Only
    string
    Code of Tax Exemption that is applied
    tax_treatment_code
    GCC Editions only
    string
    Specify reason for using out of scope.
    Supported values for UAE are uae_same_tax_group, uae_reimbursed_expense and uae_others.
    Supported values for Bahrain are bahrain_same_tax_group, bahrain_transfer_of_concern, bahrain_disbursement, bahrain_head_to_branch_transaction and bahrain_others.
    Supported values for Saudi Arabia are ksa_pvt_health, ksa_pvt_edu and ksa_house_sales.
    avatax_exempt_no
    Avalara integration only
    string
    Exemption certificate number of the customer.
    avatax_use_code
    Avalara integration only
    string
    Used to group like customers for exemption purposes. It is a custom value that links customers to a tax rule.
    shipping_charge
    double
    adjustment
    double
    adjustment_description
    string
    sub_total
    double
    Sub Total of the Sales Order
    tax_total
    double
    total
    double
    Total of the Sales Order
    tax_id
    string
    ID of the tax or tax group applied
    tax_name
    string
    tax_amount
    double
    price_precision
    integer
    is_emailed
    boolean
    Check if the Sales Order is emailed to the customer
    billing_address
    object
    address
    string
    Address
    street2
    string
    city
    string
    City of the address
    state
    string
    State of the Address
    zip
    string
    ZIP Code of the Address
    country
    string
    Country of the Address
    fax
    string
    Fax Number
    attention
    string
    shipping_address
    object
    address
    string
    Address
    street2
    string
    city
    string
    City of the address
    state
    string
    State of the Address
    zip
    string
    ZIP Code of the Address
    country
    string
    Country of the Address
    fax
    string
    Fax Number
    attention
    string
    notes
    string
    Notes for this Sales Order
    terms
    string
    custom_fields
    list
    Custom fields for a sales order.
    custom_field_id
    long
    ID of the Custom Field
    index
    integer
    value
    string
    label
    string
    template_id
    string
    ID of the pdf template.
    template_name
    string
    Name of the template
    page_width
    string
    page_height
    string
    orientation
    string
    template_type
    string
    Type of the template
    created_time
    string
    Creation Time of the Sales Order
    last_modified_time
    string
    Last Modified time of the Sales Order
    created_by_id
    string
    attachment_name
    string
    can_send_in_mail
    boolean
    Can the file be sent in mail.
    salesperson_id
    string
    salesperson_name
    string
    Name of the sales person.

    Create a sales order

    Create a sales order for your customer.
    oauthscope : ZohoBooks.salesorders.CREATE

    POST /salesorders

    Request Example

      
    $ curl https://books.zoho.com/api/v3/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": "460000000017138", "contact_persons": [ "460000000870911", "460000000870915" ], "date": "2014-07-28", "custom_fields": [ { "index": 1, "value": "Normal", "label": "Priority" } ], "place_of_supply": "TN", "gst_treatment": "business_gst", "gst_no": "22AAAAA0000A1Z5", "is_inclusive_tax": false, "line_items": [ { "item_order": 0, "item_id": "460000000017088", "rate": 120, "name": "Hard Drive", "description": "500GB, USB 2.0 interface 1400 rpm, protective hard case.", "quantity": 40, "product_type": "goods", "hsn_or_sac": 80540, "tax_id": "460000000017094", "tags": [ {} ], "unit": "Nos", "item_custom_fields": [ { "index": 1, "value": "Normal", "label": "Priority" } ], "tax_treatment_code": "uae_others" } ], "billing_address_id": 460000000032174, "tax_treatment": "vat_registered", "salesorder_number": "SO-00001", "reference_number": "REF-001", "is_update_customer": false, "exchange_rate": 1.233, "salesperson_name": "John Roberts", "tax_id": "460000000017094", "shipping_charge": 2, "adjustment": 0.2, "delivery_method": "Air", "is_discount_before_tax": true, "discount_type": "entity_level", "adjustment_description": "Adjustment", "template_id": "460000000021001", "documents": [ {} ] }"'

    Response Example

      
    HTTP/1.1 201 Created Content-Type:application/json;charset=UTF-8 { "code": 0, "message": "Sales Order Created Successfully.", "salesorder": [ { "salesorder_id": "460000000039129", "documents": [ {...} ], "is_pre_gst": false, "gst_no": "22AAAAA0000A1Z5", "gst_treatment": "business_gst", "place_of_supply": "TN", "tax_treatment": "vat_registered", "salesorder_number": "SO-00001", "date": "2014-07-28", "status": "open", "reference_number": "REF-001", "customer_id": "460000000017138", "customer_name": "SAF Instruments Inc", "contact_persons": [ "460000000870911", "460000000870915" ], "currency_id": "460000000000097", "currency_code": "USD", "currency_symbol": "$", "exchange_rate": 1.233, "discount_amount": 0, "discount_applied_on_amount": 0, "is_discount_before_tax": true, "discount_type": "entity_level", "delivery_method": "Air", "is_inclusive_tax": false, "line_items": [ { "item_order": 0, "item_id": "460000000017088", "rate": 120, "name": "Hard Drive", "description": "500GB, USB 2.0 interface 1400 rpm, protective hard case.", "quantity": 40, "product_type": "goods", "hsn_or_sac": 80540, "tax_id": "460000000017094", "tags": [ {...} ], "unit": "Nos", "item_custom_fields": [ { "index": 1, "value": "Normal", "label": "Priority" } ], "tax_treatment_code": "uae_others" } ], "shipping_charge": 2, "adjustment": 0.2, "adjustment_description": "Adjustment", "sub_total": 11800, "tax_total": 600, "total": 12400, "taxes": [ { "tax_id": "460000000017094", "tax_amount": 600 } ], "price_precision": 2, "is_emailed": false, "billing_address": { "address": "B-1104, 11F, \nHorizon International Tower, \nNo. 6, ZhiChun Road, HaiDian District", "street2": "McMillan Avenue", "city": "Beijing", "state": "Beijing", "zip": "1000881", "country": "China", "fax": "+86-10-82637827" }, "shipping_address": { "address": "B-1104, 11F, \nHorizon International Tower, \nNo. 6, ZhiChun Road, HaiDian District", "street2": "McMillan Avenue", "city": "Beijing", "state": "Beijing", "zip": "1000881", "country": "China", "fax": "+86-10-82637827" }, "custom_fields": [ { "index": 1, "value": "Normal", "label": "Priority" } ], "template_id": "460000000021001", "template_name": "Standard Template", "page_width": "8.27in", "page_height": "11.69in", "orientation": "portrait", "template_type": "standard", "created_time": "2014-07-28T08:29:07+0530", "last_modified_time": "2014-08-25T11:23:26+0530", "created_by_id": "460000000053001", "can_send_in_mail": true, "salesperson_name": "John Roberts" } ] }

    ARGUMENTS

    customer_id
    Required
    ID of the customer to whom the sales order has to be created.
    contact_persons
    Optional
    Array of contact person(s) for whom sales order has to be sent.
    date
    Optional
    The date, the sales order is created.
    shipment_date
    Optional
    Shipping date of sales order.
    custom_fields
    Optional
    Custom fields for a sales order.
    custom_field_id
    Optional
    ID of the Custom Field
    index
    Optional
    value
    Optional
    label
    Optional
    place_of_supply
    India Edition and GCC Editions only.
    Optional
    Place where the goods/services are supplied to. (If not given, place of contact given for the contact will be taken)
    Supported codes for UAE emirates are :
    Abu Dhabi - AB,
    Ajman - AJ,
    Dubai - DU,
    Fujairah - FU,
    Ras al-Khaimah - RA,
    Sharjah - SH,
    Umm al-Quwain - UM
    Supported codes for the GCC countries are :
    United Arab Emirates - AE,
    Saudi Arabia - SA,
    Bahrain - BH,
    Kuwait - KW,
    Oman - OM,
    Qatar - QA.
    gst_treatment
    India Edition only.
    Optional
    Choose whether the contact is GST registered/unregistered/consumer/overseas. Allowed values are business_gst , business_none , overseas , consumer .
    gst_no
    India Edition only.
    Optional
    15 digit GST identification number of the customer.
    is_inclusive_tax
    Not applicable for US and CA editions
    Optional
    Used to specify whether the line item rates are inclusive or exclusive of tax.
    Optional
    Line items of a sales order.
    item_order
    Optional
    item_id
    Optional
    ID of the item.
    rate
    Optional
    Rate of the line item.
    name
    Optional
    Name of the line item.
    description
    Optional
    Description of the line item.
    quantity
    Optional
    Quantity of the line item.
    product_type
    Optional
    Enter goods/services
    hsn_or_sac
    India Edition only
    Optional
    Add HSN/SAC code for your goods/services
    warehouse_id
    Optional
    ID of the warehouse
    discount
    Optional
    Discount applied to the sales order. It can be either in % or in amount. e.g. 12.5% or 190.
    tax_id
    Optional
    Tax ID for the Sales Order.
    Optional
    unit
    Optional
    Unit of the line item e.g. kgs, Nos.
    item_custom_fields
    Optional
    Custom fields for a sales order items.
    custom_field_id
    Optional
    ID of the Custom Field
    index
    Optional
    value
    Optional
    label
    Optional
    tax_exemption_id
    India Edition and US Edition only
    Optional
    ID of the tax exemption applied
    tax_exemption_code
    India Edition and US Edition Only
    Optional
    Code of Tax Exemption that is applied
    tax_treatment_code
    GCC Editions only
    Optional
    Specify reason for using out of scope.
    Supported values for UAE are uae_same_tax_group, uae_reimbursed_expense and uae_others.
    Supported values for Bahrain are bahrain_same_tax_group, bahrain_transfer_of_concern, bahrain_disbursement, bahrain_head_to_branch_transaction and bahrain_others.
    Supported values for Saudi Arabia are ksa_pvt_health, ksa_pvt_edu and ksa_house_sales.
    avatax_exempt_no
    Avalara integration only
    Optional
    Exemption certificate number of the customer.
    avatax_use_code
    Avalara integration only
    Optional
    Used to group like customers for exemption purposes. It is a custom value that links customers to a tax rule.
    notes
    Optional
    Notes for this Sales Order
    terms
    Optional
    billing_address_id
    Optional
    ID of the Billing Address
    shipping_address_id
    Optional
    ID of the Shipping Address
    crm_owner_id
    Optional
    crm_custom_reference_id
    Optional
    vat_treatment
    Optional
    Enter vat treatment
    tax_treatment
    GCC Editions only
    Optional
    VAT treatment for the sales order.Allowed Values: vat_registered,vat_not_registered,gcc_vat_not_registered,gcc_vat_registered,non_gcc.
    dz_vat_registered and dz_vat_not_registered supported only for UAE.
    salesorder_number
    Optional
    Mandatory if auto number generation is disabled.
    reference_number
    Optional
    Reference Number of the Sales Order.
    is_update_customer
    Optional
    Boolean to update billing address of customer.
    discount
    Optional
    Discount applied to the sales order. It can be either in % or in amount. e.g. 12.5% or 190.
    exchange_rate
    Optional
    Exchange rate of the currency.
    salesperson_name
    Optional
    Name of the sales person.
    notes_default
    Optional
    Default Notes for the Sales Order
    terms_default
    Optional
    Default Terms of the Sales Order
    tax_id
    Optional
    Tax ID for the Sales Order.
    tax_authority_id
    US Edition only
    Optional
    ID of the tax authority. Tax authority depends on the location of the customer.
    tax_exemption_id
    India Edition and US Edition only
    Optional
    ID of the tax exemption applied
    tax_authority_name
    US Edition Only
    Optional
    Tax Authority's name.
    tax_exemption_code
    India Edition and US Edition Only
    Optional
    Code of Tax Exemption that is applied
    avatax_exempt_no
    Avalara integration only
    Optional
    Exemption certificate number of the customer.
    avatax_use_code
    Avalara integration only
    Optional
    Used to group like customers for exemption purposes. It is a custom value that links customers to a tax rule.
    shipping_charge
    Optional
    adjustment
    Optional
    delivery_method
    Optional
    estimate_id
    Optional
    ID of the estimate associated with the Sales Order
    is_discount_before_tax
    Optional
    Used to specify how the discount has to applied. Either before or after the calculation of tax.
    discount_type
    Optional
    How the discount is specified. Allowed values are entity_level or item_level. Allowed Values: entity_level and item_level.
    adjustment_description
    Optional
    pricebook_id
    Optional
    template_id
    Optional
    ID of the pdf template.
    Optional
    zcrm_potential_id
    Optional
    zcrm_potential_name
    Optional

    Query Params

    ignore_auto_number_generation
    Optional
    Ignore auto sales order number generation for this sales order. This mandates the sales order number.
    can_send_in_mail
    Optional
    Can the file be sent in mail.
    totalFiles
    Optional
    Total number of files.
    doc
    Optional
    Document that is to be attached

    Update a sales order

    Update an existing sales order. To delete a line item just remove it from the line_items list.
    oauthscope : ZohoBooks.salesorders.UPDATE

    PUT /salesorders/{salesorder_id}

    Request Example

      
    $ curl https://books.zoho.com/api/v3/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="{ "customer_id": "460000000017138", "contact_persons": [ "460000000870911", "460000000870915" ], "date": "2014-07-28", "custom_fields": [ { "index": 1, "value": "Normal", "label": "Priority" } ], "place_of_supply": "TN", "gst_treatment": "business_gst", "gst_no": "22AAAAA0000A1Z5", "is_inclusive_tax": false, "line_items": [ { "item_order": 0, "line_item_id": "460000000039131", "item_id": "460000000017088", "rate": 120, "name": "Hard Drive", "description": "500GB, USB 2.0 interface 1400 rpm, protective hard case.", "quantity": 40, "tax_id": "460000000017094", "tags": [ {} ], "unit": "Nos", "item_custom_fields": [ { "index": 1, "value": "Normal", "label": "Priority" } ], "tax_treatment_code": "uae_others" } ], "billing_address_id": 460000000032174, "tax_treatment": "vat_registered", "salesorder_number": "SO-00001", "reference_number": "REF-001", "is_update_customer": false, "exchange_rate": 1.233, "salesperson_name": "John Roberts", "tax_id": "460000000017094", "shipping_charge": 2, "adjustment": 0.2, "delivery_method": "Air", "is_discount_before_tax": true, "discount_type": "entity_level", "adjustment_description": "Adjustment", "template_id": "460000000021001", "documents": [ {} ] }"'

    Response Example

      
    HTTP/1.1 200 OK Content-Type:application/json;charset=UTF-8 { "code": 0, "message": "Sales Order Updated Successfully.", "salesorder": [ { "salesorder_id": "460000000039129", "documents": [ {...} ], "is_pre_gst": false, "gst_no": "22AAAAA0000A1Z5", "gst_treatment": "business_gst", "place_of_supply": "TN", "tax_treatment": "vat_registered", "salesorder_number": "SO-00001", "date": "2014-07-28", "status": "open", "reference_number": "REF-001", "customer_id": "460000000017138", "customer_name": "SAF Instruments Inc", "contact_persons": [ "460000000870911", "460000000870915" ], "currency_id": "460000000000097", "currency_code": "USD", "currency_symbol": "$", "exchange_rate": 1.233, "discount_amount": 0, "discount_applied_on_amount": 0, "is_discount_before_tax": true, "discount_type": "entity_level", "delivery_method": "Air", "is_inclusive_tax": false, "line_items": [ { "item_order": 0, "item_id": "460000000017088", "rate": 120, "name": "Hard Drive", "description": "500GB, USB 2.0 interface 1400 rpm, protective hard case.", "quantity": 40, "product_type": "goods", "hsn_or_sac": 80540, "tax_id": "460000000017094", "tags": [ {...} ], "unit": "Nos", "item_custom_fields": [ { "index": 1, "value": "Normal", "label": "Priority" } ], "tax_treatment_code": "uae_others" } ], "shipping_charge": 2, "adjustment": 0.2, "adjustment_description": "Adjustment", "sub_total": 11800, "tax_total": 600, "total": 12400, "taxes": [ { "tax_id": "460000000017094", "tax_amount": 600 } ], "price_precision": 2, "is_emailed": false, "billing_address": { "address": "B-1104, 11F, \nHorizon International Tower, \nNo. 6, ZhiChun Road, HaiDian District", "street2": "McMillan Avenue", "city": "Beijing", "state": "Beijing", "zip": "1000881", "country": "China", "fax": "+86-10-82637827" }, "shipping_address": { "address": "B-1104, 11F, \nHorizon International Tower, \nNo. 6, ZhiChun Road, HaiDian District", "street2": "McMillan Avenue", "city": "Beijing", "state": "Beijing", "zip": "1000881", "country": "China", "fax": "+86-10-82637827" }, "custom_fields": [ { "index": 1, "value": "Normal", "label": "Priority" } ], "template_id": "460000000021001", "template_name": "Standard Template", "page_width": "8.27in", "page_height": "11.69in", "orientation": "portrait", "template_type": "standard", "created_time": "2014-07-28T08:29:07+0530", "last_modified_time": "2014-08-25T11:23:26+0530", "created_by_id": "460000000053001", "can_send_in_mail": true, "salesperson_name": "John Roberts" } ] }

    ARGUMENTS

    customer_id
    Required
    ID of the customer to whom the sales order has to be created.
    contact_persons
    Optional
    Array of contact person(s) for whom sales order has to be sent.
    date
    Optional
    The date, the sales order is created.
    shipment_date
    Optional
    Shipping date of sales order.
    custom_fields
    Optional
    Custom fields for a sales order.
    custom_field_id
    Optional
    ID of the Custom Field
    index
    Optional
    value
    Optional
    label
    Optional
    place_of_supply
    India Edition and GCC Editions only.
    Optional
    Place where the goods/services are supplied to. (If not given, place of contact given for the contact will be taken)
    Supported codes for UAE emirates are :
    Abu Dhabi - AB,
    Ajman - AJ,
    Dubai - DU,
    Fujairah - FU,
    Ras al-Khaimah - RA,
    Sharjah - SH,
    Umm al-Quwain - UM
    Supported codes for the GCC countries are :
    United Arab Emirates - AE,
    Saudi Arabia - SA,
    Bahrain - BH,
    Kuwait - KW,
    Oman - OM,
    Qatar - QA.
    gst_treatment
    India Edition only.
    Optional
    Choose whether the contact is GST registered/unregistered/consumer/overseas. Allowed values are business_gst , business_none , overseas , consumer .
    gst_no
    India Edition only.
    Optional
    15 digit GST identification number of the customer.
    is_inclusive_tax
    Not applicable for US and CA editions
    Optional
    Used to specify whether the line item rates are inclusive or exclusive of tax.
    Optional
    Line items of a sales order.
    item_order
    Optional
    line_item_id
    Optional
    ID of the line item. Mandatory if the existing line item has to be updated. If empty, a new line item will be created.
    item_id
    Optional
    ID of the item.
    rate
    Optional
    Rate of the line item.
    name
    Optional
    Name of the line item.
    description
    Optional
    Description of the line item.
    quantity
    Optional
    Quantity of the line item.
    discount
    Optional
    Discount applied to the sales order. It can be either in % or in amount. e.g. 12.5% or 190.
    tax_id
    Optional
    Tax ID for the Sales Order.
    Optional
    unit
    Optional
    Unit of the line item e.g. kgs, Nos.
    item_custom_fields
    Optional
    Custom fields for a sales order items.
    custom_field_id
    Optional
    ID of the Custom Field
    index
    Optional
    value
    Optional
    label
    Optional
    tax_exemption_id
    India Edition and US Edition only
    Optional
    ID of the tax exemption applied
    tax_exemption_code
    India Edition and US Edition Only
    Optional
    Code of Tax Exemption that is applied
    tax_treatment_code
    GCC Editions only
    Optional
    Specify reason for using out of scope.
    Supported values for UAE are uae_same_tax_group, uae_reimbursed_expense and uae_others.
    Supported values for Bahrain are bahrain_same_tax_group, bahrain_transfer_of_concern, bahrain_disbursement, bahrain_head_to_branch_transaction and bahrain_others.
    Supported values for Saudi Arabia are ksa_pvt_health, ksa_pvt_edu and ksa_house_sales.
    avatax_exempt_no
    Avalara integration only
    Optional
    Exemption certificate number of the customer.
    avatax_use_code
    Avalara integration only
    Optional
    Used to group like customers for exemption purposes. It is a custom value that links customers to a tax rule.
    notes
    Optional
    Notes for this Sales Order
    terms
    Optional
    billing_address_id
    Optional
    ID of the Billing Address
    shipping_address_id
    Optional
    ID of the Shipping Address
    crm_owner_id
    Optional
    crm_custom_reference_id
    Optional
    vat_treatment
    Optional
    Enter vat treatment
    tax_treatment
    GCC Editions only
    Optional
    VAT treatment for the sales order.Allowed Values: vat_registered,vat_not_registered,gcc_vat_not_registered,gcc_vat_registered,non_gcc.
    dz_vat_registered and dz_vat_not_registered supported only for UAE.
    salesorder_number
    Optional
    Mandatory if auto number generation is disabled.
    reference_number
    Optional
    Reference Number of the Sales Order.
    is_update_customer
    Optional
    Boolean to update billing address of customer.
    discount
    Optional
    Discount applied to the sales order. It can be either in % or in amount. e.g. 12.5% or 190.
    exchange_rate
    Optional
    Exchange rate of the currency.
    salesperson_name
    Optional
    Name of the sales person.
    notes_default
    Optional
    Default Notes for the Sales Order
    terms_default
    Optional
    Default Terms of the Sales Order
    tax_id
    Optional
    Tax ID for the Sales Order.
    tax_authority_id
    US Edition only
    Optional
    ID of the tax authority. Tax authority depends on the location of the customer.
    tax_exemption_id
    India Edition and US Edition only
    Optional
    ID of the tax exemption applied
    tax_authority_name
    US Edition Only
    Optional
    Tax Authority's name.
    tax_exemption_code
    India Edition and US Edition Only
    Optional
    Code of Tax Exemption that is applied
    avatax_exempt_no
    Avalara integration only
    Optional
    Exemption certificate number of the customer.
    avatax_use_code
    Avalara integration only
    Optional
    Used to group like customers for exemption purposes. It is a custom value that links customers to a tax rule.
    shipping_charge
    Optional
    adjustment
    Optional
    delivery_method
    Optional
    is_discount_before_tax
    Optional
    Used to specify how the discount has to applied. Either before or after the calculation of tax.
    discount_type
    Optional
    How the discount is specified. Allowed values are entity_level or item_level. Allowed Values: entity_level and item_level.
    adjustment_description
    Optional
    pricebook_id
    Optional
    template_id
    Optional
    ID of the pdf template.
    Optional
    zcrm_potential_id
    Optional
    zcrm_potential_name
    Optional

    Query Params

    ignore_auto_number_generation
    Optional
    Ignore auto sales order number generation for this sales order. This mandates the sales order number.
    can_send_in_mail
    Optional
    Can the file be sent in mail.
    totalFiles
    Optional
    Total number of files.
    doc
    Optional
    Document that is to be attached

    List sales orders

    List all sales orders.
    oauthscope : ZohoBooks.salesorders.READ

    GET /salesorders

    Request Example

      
    $ curl https://books.zoho.com/api/v3/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": "460000000039129", "customer_name": "SAF Instruments Inc", "customer_id": "460000000017138", "status": "open", "salesorder_number": "SO-00001", "reference_number": "REF-001", "date": "2014-07-28", "shipment_days": 2, "currency_id": "460000000000097", "currency_code": "USD", "total": 12400, "sub_total": 11800, "bcy_total": 400, "created_time": "2014-07-28T08:29:07+0530", "last_modified_time": "2014-08-25T11:23:26+0530", "is_emailed": false, "has_attachment": false, "custom_fields": [ { "index": 1, "value": "Normal", "label": "Priority" } ] }, {...}, {...} ] }

    Query Params

    sort_column
    Optional
    Sort sales orders. Allowed Values: customer_name, salesorder_number, shipment_date, total, date and created_time.
    search_text
    Optional
    Search sales order by sales order number or reference number or customer name.
    filter_by
    Optional
    Filter sales order by status. Allowed Values: Status.All, Status.Open, Status.Draft, Status.OverDue, Status.PartiallyInvoiced, Status.Invoiced, Status.Void and Status.Closed
    salesorder_number
    Optional
    Search Sales Order by Sales Order Number. Variants: salesorder_number.startswith, salesorder_number.contains. Maximum Length : 100
    item_name
    Optional
    Search sales order by item name. Variants: item_name.startswith and item_name.contains. Maximum Length : 100
    item_id
    Optional
    Search Sales Order Based on Item ID.
    item_description
    Optional
    Search sales order by item description. Variants: item_description.startswith and item_description.contains. Maximum Length: 100
    reference_number
    Optional
    Search sales order by reference number. Variants: reference_number.startswith and reference_number.contains.
    customer_name
    Optional
    Search sales order by customer name. Variants: customer_name.startswith and customer_name.contains. Maximum Length : 100
    total
    Optional
    Search sales order by sales order total. Variants: total.start, total.end, total.less_than, total.less_equals, total.greater_than and total.greater_equals.
    date
    Optional
    Search sales order by sales order date. Variants: date.start, date.end, date.before and date.after. Default date format : yyyy-mm-dd
    shipment_date
    Optional
    Search sales order by sales order shipment date. Variants: shipment_date.start, shipment_date.end, shipment_date.before and shipment_date.after. Default date format : yyyy-mm-dd
    status
    Optional
    Search sales order by sales order status. Allowed Values: draft, open, invoiced, partially_invoiced, void and overdue.
    customer_id
    Optional
    Search Sales Order based on customer_id

    Get a sales order

    Get the details of a sales order.
    oauthscope : ZohoBooks.salesorders.READ

    GET /salesorders/{salesorder_id}

    Request Example

      
    $ curl https://books.zoho.com/api/v3/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", "salesorder": [ { "customer_id": "460000000017138", "billing_address_id": 460000000032174, "is_pre_gst": false, "gst_no": "22AAAAA0000A1Z5", "gst_treatment": "business_gst", "place_of_supply": "TN", "tax_treatment": "vat_registered", "is_update_customer": false, "contact_persons": [ {...} ], "salesorder_number": "SO-00001", "reference_number": "REF-001", "template_id": "460000000021001", "documents": [ {...} ], "exchange_rate": 1.233, "is_discount_before_tax": true, "discount_type": "entity_level", "salesperson_name": "John Roberts", "tax_id": "460000000017094", "is_inclusive_tax": false, "custom_fields": [ { "index": 1, "value": "Normal", "label": "Priority" } ], "line_items": [ { "line_item_id": "460000000039131", "bcy_rate": 120, "tax_id": "460000000017094", "tax_treatment_code": "uae_others", "is_taxable": false, "item_total_inclusive_of_tax": 48, "product_type": "goods", "hsn_or_sac": 80540, "is_invoiced": false } ], "shipping_charge": 2, "adjustment": 0.2, "adjustment_description": "Adjustment", "delivery_method": "Air" } ] }

    Query Params

    print
    Optional
    Print the exported pdf.
    accept
    Optional
    Get the details of a particular sales order in formats such as json/ pdf/ html. Default format is json. Allowed Values: json, pdf and html.

    Delete a sales order

    Delete an existing sales order. Invoiced sales order cannot be deleted.
    oauthscope : ZohoBooks.salesorders.DELETE

    DELETE /salesorders/{salesorder_id}

    Request Example

      
    $ curl https://books.zoho.com/api/v3/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": "Sales Order Deleted Successfully." }

    Mark a sales order as open

    Mark a draft sales order as open.
    oauthscope : ZohoBooks.salesorders.CREATE

    POST /salesorders/{salesorder_id}/status/open

    Request Example

      
    $ curl https://books.zoho.com/api/v3/salesorders/{salesorder_id}/status/open?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 201 Created Content-Type:application/json;charset=UTF-8 { "code": 0, "message": "Sales order status has been changed to Open." }

    Mark a sales order as void

    Mark a sales order as void.
    oauthscope : ZohoBooks.salesorders.CREATE

    POST /salesorders/{salesorder_id}/status/void

    Request Example

      
    $ curl https://books.zoho.com/api/v3/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 201 Created Content-Type:application/json;charset=UTF-8 { "code": 0, "message": "Sales order status has been changed to Void." }

    Email a sales order

    Email a sales order to the customer. Input json string is not mandatory. If input json string is empty, mail will be send with default mail content.
    oauthscope : ZohoBooks.salesorders.CREATE

    POST /salesorders/{salesorder_id}/email

    Request Example

      
    $ curl https://books.zoho.com/api/v3/salesorders/{salesorder_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="{ "from_address_id": "[email protected]", "send_from_org_email_id": true, "to_mail_ids": [ {} ], "cc_mail_ids": [ {} ], "bcc_mail_ids": [ {} ], "subject": "Sales Order from Zillium Inc (Sales Order #: SO-00001)", "invoice_id": 460000000028192, "body": "<br>Dear SAF Instruments Inc,&nbsp;<br><br>Thanks for your interest in our services. Please find our sales order attached with this mail.<br><br> An overview of the sales order is available below for your reference: &nbsp;<br><br> ----------------------------------------------------------------------------------------<br> <h2>Sales Order&nbsp;# :&nbsp;SO-00001</h2><br> ----------------------------------------------------------------------------------------<br> <b>&nbsp;Order Date &nbsp; &nbsp;&nbsp;&nbsp;: &nbsp;28 Jul 2014</b><br><b>&nbsp;Amount &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; : &nbsp;&nbsp;$12,400.00</b><br>----------------------------------------------------------------------------------------<br><br><span>Assuring you of our best services at all times.</span><br><br><br>Regards,<br><br>John<br>Zillium Inc<br><br><br>" }"'

    Response Example

      
    HTTP/1.1 201 Created Content-Type:application/json;charset=UTF-8 { "code": 0, "message": "Your Sales Order has been sent." }

    ARGUMENTS

    from_address_id
    Optional
    From Address of the Email Address
    send_from_org_email_id
    Optional
    Boolean to trigger the email from the organization's email address.
    to_mail_ids
    Required
    Array of email address of the recipients.
    cc_mail_ids
    Optional
    Array of email address of the recipients to be CC ed.
    bcc_mail_ids
    Optional
    Array of email address of the recipients to be BCC ed.
    subject
    Required
    Subject of the mail.
    Optional
    invoice_id
    Optional
    ID of the invoice
    body
    Required
    Body of the mail.

    Query Params

    salesorder_id
    Optional
    ID of the Sales Order
    attachments
    Optional
    Attachments of the Sales Order
    send_attachment
    Optional
    Send the sales order attachment a with the email.
    file_name
    Optional
    Name of the file.

    Submit a sales order for approval

    Submit a sales order for approval.
    oauthscope : ZohoBooks.salesorders.CREATE

    POST /salesorders/{salesorder_id}/submit

    Request Example

      
    $ curl https://books.zoho.com/api/v3/salesorders/{salesorder_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 Sales Order has been successfully submitted for approval." }

    Approve a sales order.

    Approve a sales order.
    oauthscope : ZohoBooks.salesorders.CREATE

    POST /salesorders/{salesorder_id}/approve

    Request Example

      
    $ curl https://books.zoho.com/api/v3/salesorders/{salesorder_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 Sales Order." }

    Get sales order email content

    Get the email content of a sales order.
    oauthscope : ZohoBooks.salesorders.READ

    GET /salesorders/{salesorder_id}/email

    Request Example

      
    $ curl https://books.zoho.com/api/v3/salesorders/{salesorder_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": [ {...} ], "body": "<br>Dear SAF Instruments Inc,&nbsp;<br><br>Thanks for your interest in our services. Please find our sales order attached with this mail.<br><br> An overview of the sales order is available below for your reference: &nbsp;<br><br> ----------------------------------------------------------------------------------------<br> <h2>Sales Order&nbsp;# :&nbsp;SO-00001</h2><br> ----------------------------------------------------------------------------------------<br> <b>&nbsp;Order Date &nbsp; &nbsp;&nbsp;&nbsp;: &nbsp;28 Jul 2014</b><br><b>&nbsp;Amount &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; : &nbsp;&nbsp;$12,400.00</b><br>----------------------------------------------------------------------------------------<br><br><span>Assuring you of our best services at all times.</span><br><br><br>Regards,<br><br>John<br>Zillium Inc<br><br><br>", "error_list": [ {...} ], "documents": [ {...} ], "subject": "Sales Order from Zillium Inc (Sales Order #: SO-00001)", "customer_name": "SAF Instruments Inc", "entity_id": "460000000058039", "cc_mails_list": [], "from_emails": [ { "organization_contact_id": "460000000053003", "selected": true, "is_org_email_id": true } ], "file_name_without_extension": "SO-00001", "emailtemplates": [ { "selected": true, "name": "Hard Drive", "email_template_id": 460000000001287 } ], "to_contacts": [ { "selected": true, "salutation": "Ms." } ], "customer_id": "460000000017138" } ] }

    Query Params

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

    Bulk export sales orders

    Maximum of 25 sales orders can be exported in a single pdf.
    oauthscope : ZohoBooks.salesorders.READ

    GET /salesorders/pdf

    Request Example

      
    $ curl https://books.zoho.com/api/v3/salesorders/pdf?organization_id=10234695 -H "Authorization: Zoho-oauthtoken 1000.41d9f2cfbd1b7a8f9e314b7aff7bc2d1.8fcc9810810a216793f385b9dd6e125f" -H "Content-Type: application/x-www-form-urlencoded;charset=UTF-8" -F 'JSONString="{ "salesorder_ids": 460108000000072000 }"'

    Response Example

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

    ARGUMENTS

    salesorder_ids
    Required
    Comma separated sales order ids which are to be export as pdf.

    Bulk print sales orders

    Export sales orders as pdf and print them. Maximum of 25 sales orders can be printed.
    oauthscope : ZohoBooks.salesorders.READ

    GET /salesorders/print

    Request Example

      
    $ curl https://books.zoho.com/api/v3/salesorders/print?organization_id=10234695 -H "Authorization: Zoho-oauthtoken 1000.41d9f2cfbd1b7a8f9e314b7aff7bc2d1.8fcc9810810a216793f385b9dd6e125f" -H "Content-Type: application/x-www-form-urlencoded;charset=UTF-8" -F 'JSONString="{ "salesorder_ids": 460108000000072000 }"'

    Response Example

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

    ARGUMENTS

    salesorder_ids
    Required
    Comma separated sales order ids which are to be export as pdf.

    Update billing address

    Updates the billing address for this sales order alone.
    oauthscope : ZohoBooks.salesorders.UPDATE

    PUT /salesorders/{salesorder_id}/address/billing

    Request Example

      
    $ curl https://books.zoho.com/api/v3/salesorders/{salesorder_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", "country": "China", "fax": "+86-10-82637827", "is_one_off_address": true, "is_update_customer": false }"'

    Response Example

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

    ARGUMENTS

    address
    Optional
    Address
    city
    Optional
    City of the address
    state
    Optional
    State of the Address
    zip
    Optional
    ZIP Code of the Address
    country
    Optional
    Country of the Address
    fax
    Optional
    Fax Number
    attention
    Optional
    is_one_off_address
    Optional
    is_update_customer
    Optional
    Boolean to update billing address of customer.
    is_verified
    Avalara Integration Only
    Optional
    Check if the Address is verified

    Update shipping address

    Updates the shipping address for this sales order alone.
    oauthscope : ZohoBooks.salesorders.UPDATE

    PUT /salesorders/{salesorder_id}/address/shipping

    Request Example

      
    $ curl https://books.zoho.com/api/v3/salesorders/{salesorder_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": "B-1104, 11F, \nHorizon International Tower, \nNo. 6, ZhiChun Road, HaiDian District", "city": "Beijing", "state": "Beijing", "zip": "1000881", "country": "China", "fax": "+86-10-82637827", "is_one_off_address": true, "is_update_customer": false }"'

    Response Example

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

    ARGUMENTS

    address
    Optional
    Address
    city
    Optional
    City of the address
    state
    Optional
    State of the Address
    zip
    Optional
    ZIP Code of the Address
    country
    Optional
    Country of the Address
    fax
    Optional
    Fax Number
    attention
    Optional
    is_one_off_address
    Optional
    is_update_customer
    Optional
    Boolean to update billing address of customer.
    is_verified
    Avalara Integration Only
    Optional
    Check if the Address is verified

    List sales order templates

    Get all sales order pdf templates.
    oauthscope : ZohoBooks.salesorders.READ

    GET /salesorders/templates

    Request Example

      
    $ curl https://books.zoho.com/api/v3/salesorders/templates?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", "templates": [ { "template_name": "Standard Template", "template_id": "460000000021001", "template_type": "standard" } ] }

    Update sales order template

    Update the pdf template associated with the sales order.
    oauthscope : ZohoBooks.salesorders.UPDATE

    PUT /salesorders/{salesorder_id}/templates/{template_id}

    Request Example

      
    $ curl https://books.zoho.com/api/v3/salesorders/{salesorder_id}/templates/{template_id}?organization_id=10234695 -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": "Sales Order Updated Successfully." }

    Get a sales order attachment

    Returns the file attached to the sales order.
    oauthscope : ZohoBooks.salesorders.READ

    GET /salesorders/{salesorder_id}/attachment

    Request Example

      
    $ curl https://books.zoho.com/api/v3/salesorders/{salesorder_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
    Check if preview of the Sales Order is required
    inline
    Optional
    Check if inline response is required

    Add attachment to a sales order

    Attach a file to a sales order.
    oauthscope : ZohoBooks.salesorders.CREATE

    POST /salesorders/{salesorder_id}/attachment

    Request Example

      
    $ curl https://books.zoho.com/api/v3/salesorders/{salesorder_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 201 Created Content-Type:application/json;charset=UTF-8 { "code": 0, "message": "Your file has been successfully attached to the sales order." }

    Query Params

    attachment
    Optional
    The file that is to be added as an Attachment in the Sales Order
    can_send_in_mail
    Optional
    Can the file be sent in mail.
    doc
    Optional
    Document that is to be attached
    totalFiles
    Optional
    Total number of files.
    document_ids
    Optional
    ID's of the document

    Update attachment preference

    Set whether you want to send the attached file while emailing the sales order.
    oauthscope : ZohoBooks.salesorders.UPDATE

    PUT /salesorders/{salesorder_id}/attachment

    Request Example

      
    $ curl https://books.zoho.com/api/v3/salesorders/{salesorder_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": "Sales Oder Updated Successfully." }

    Query Params

    can_send_in_mail
    Required
    Can the file be sent in mail.

    Delete an attachment

    Delete the file attached to the sales order.
    oauthscope : ZohoBooks.salesorders.DELETE

    DELETE /salesorders/{salesorder_id}/attachment

    Request Example

      
    $ curl https://books.zoho.com/api/v3/salesorders/{salesorder_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 sales order." }

    List sales order comments & history

    Get the complete history and comments of sales order.
    oauthscope : ZohoBooks.salesorders.READ

    GET /salesorders/{salesorder_id}/comments

    Request Example

      
    $ curl https://books.zoho.com/api/v3/salesorders/{salesorder_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" }

    Add comment

    Add a comment for a sales order.
    oauthscope : ZohoBooks.salesorders.CREATE

    POST /salesorders/{salesorder_id}/comments

    Request Example

      
    $ curl https://books.zoho.com/api/v3/salesorders/{salesorder_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": "500GB, USB 2.0 interface 1400 rpm, protective hard case." }"'

    Response Example

      
    HTTP/1.1 200 OK Content-Type:application/json;charset=UTF-8 { "code": 0, "message": "Comments added.", "comment": [ { "salesorder_id": "460000000039129", "comment_id": "460000000048023", "description": "500GB, USB 2.0 interface 1400 rpm, protective hard case.", "commented_by_id": "460000000017003", "commented_by": "John", "comment_type": "system", "date": "2014-07-28", "date_description": "6 minutes ago", "time": "2:12 PM", "operation_type": "Added", "transaction_type": "salesorder" } ] }

    ARGUMENTS

    description
    Optional
    Description of the line item.

    Update comment

    Update existing comment of a sales order.
    oauthscope : ZohoBooks.salesorders.UPDATE

    PUT /salesorders/{salesorder_id}/comments/{comment_id}

    Request Example

      
    $ curl https://books.zoho.com/api/v3/salesorders/{salesorder_id}/comments/{comment_id}?organization_id=10234695 -X PUT -H "Authorization: Zoho-oauthtoken 1000.41d9f2cfbd1b7a8f9e314b7aff7bc2d1.8fcc9810810a216793f385b9dd6e125f" -H "Content-Type: application/x-www-form-urlencoded;charset=UTF-8" -F 'JSONString="{ "description": "500GB, USB 2.0 interface 1400 rpm, protective hard case." }"'

    Response Example

      
    HTTP/1.1 200 OK Content-Type:application/json;charset=UTF-8 { "code": 0, "message": "Comment has been updated.", "comment": [ { "salesorder_id": "460000000039129", "comment_id": "460000000048023", "description": "500GB, USB 2.0 interface 1400 rpm, protective hard case.", "commented_by_id": "460000000017003", "commented_by": "John", "comment_type": "system", "date": "2014-07-28", "date_description": "6 minutes ago", "time": "2:12 PM", "operation_type": "Added", "transaction_type": "salesorder" } ] }

    ARGUMENTS

    description
    Optional
    Description of the line item.

    Delete a comment

    Delete a sales order comment.
    oauthscope : ZohoBooks.salesorders.DELETE

    DELETE /salesorders/{salesorder_id}/comments/{comment_id}

    Request Example

      
    $ curl https://books.zoho.com/api/v3/salesorders/{salesorder_id}/comments/{comment_id}?organization_id=10234695 -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." }

    Invoices

    Invoice is a document sent to your client that indicates the products/services sold by you with the payment information that the client has to make.

    Example

    { "invoice_number": "INV-00003", "item_name": "Desktop Units", "item_id": 982000000030049, "recurring_invoice_id": " ", "custom_field": " ", "search_text": " ", "sort_column": "created_time", "invoices": [ {} ] }

    Attribute

    invoice_number
    string
    Search invoices by invoice number.Variants: invoice_number_startswith and invoice_number_contains. Max-length [100]
    item_name
    string
    Search invoices by item name.Variants: item_name_startswith and item_name_contains. Max-length [100]
    item_id
    string
    Search invoices by item id.
    recurring_invoice_id
    string
    ID of the recurring invoice from which the invoice is created.
    email
    Search contacts by email id. Max-length [100]
    custom_field
    string
    Search invoices by custom fields.Variants: custom_field_startswith and custom_field_contains
    search_text
    string
    Search invoices by invoice number or purchase order or customer name. Max-length [100]
    sort_column
    string
    Sort invoices.Allowed Values: customer_name, invoice_number, date, due_date, total, balance and created_time
    list
    The invoices created by the user

    Create an invoice

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

    POST /invoices

    Request Example

      
    $ curl https://books.zoho.com/api/v3/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": [ "982000000870911", "982000000870915" ], "invoice_number": "INV-00003", "place_of_supply": "TN", "tax_treatment": "vat_registered", "gst_treatment": "business_gst", "gst_no": "22AAAAA0000A1Z5", "reference_number": " ", "template_id": 982000000000143, "date": "2013-11-17", "payment_terms": 15, "payment_terms_label": "Net 15", "due_date": "2013-12-03", "discount": 0, "is_discount_before_tax": true, "discount_type": "item_level", "is_inclusive_tax": false, "exchange_rate": 1, "recurring_invoice_id": " ", "invoiced_estimate_id": " ", "salesperson_name": " ", "custom_fields": [ { "customfield_id": "46000000012845", "value": "Normal" } ], "project_id": " ", "line_items": [ { "item_id": 982000000030049, "project_id": " ", "time_entry_ids": [ {} ], "product_type": "goods", "hsn_or_sac": 80540, "warehouse_id": "", "expense_id": " ", "name": "Hard Drive", "description": "500GB, USB 2.0 interface 1400 rpm, protective hard case.", "item_order": 1, "bcy_rate": 120, "rate": 120, "quantity": 1, "unit": " ", "discount_amount": 0, "discount": 0, "tax_id": 982000000557028, "tax_name": "VAT", "tax_type": "tax", "tax_percentage": 12.5, "tax_treatment_code": "uae_others" } ], "payment_options": {}, "allow_partial_payments": true, "custom_body": " ", "custom_subject": " ", "notes": "Looking forward for your business.", "terms": "Terms & Conditions apply", "shipping_charge": 0, "adjustment": 0, "adjustment_description": " ", "reason": " ", "tax_authority_id": 11149000000061052, "tax_exemption_id": 11149000000061054, "tax_id": 982000000557028, "expense_id": " ", "salesorder_item_id": " ", "time_entry_ids": [ {} ], "payment_gateways": [ {} ], "gateway_name": "paypal", "additional_field1": "standard" }"'

    Response Example

      
    HTTP/1.1 201 Created Content-Type:application/json;charset=UTF-8 { "code": 0, "message": "The invoice has been created.", "invoice": { "invoice": { "invoice_id": 982000000567114, "ach_payment_initiated": false, "invoice_number": "INV-00003", "is_pre_gst": true, "place_of_supply": "TN", "gst_no": "22AAAAA0000A1Z5", "gst_treatment": "business_gst", "tax_treatment": "vat_registered", "date": "2013-11-17", "status": "draft", "payment_terms": 15, "payment_terms_label": "Net 15", "due_date": "2013-12-03", "payment_expected_date": " ", "last_payment_date": " ", "reference_number": " ", "customer_id": 982000000567001, "customer_name": "Bowman & Co", "contact_persons": [ "982000000870911", "982000000870915" ], "currency_id": 982000000000190, "currency_code": "USD", "exchange_rate": 1, "discount": 0, "is_discount_before_tax": true, "discount_type": "item_level", "is_inclusive_tax": false, "recurring_invoice_id": " ", "is_viewed_by_client": false, "has_attachment": false, "client_viewed_time": "", "line_items": [ { "line_item_id": 982000000567021, "item_id": 982000000030049, "project_id": " ", "time_entry_ids": [ {...} ], "warehouses": [ { "warehouse_id": "", "warehouse_name": "", "warehouse_stock_on_hand": "" } ], "item_type": "goods", "product_type": "goods", "expense_id": " ", "name": "Hard Drive", "description": "500GB, USB 2.0 interface 1400 rpm, protective hard case.", "item_order": 1, "bcy_rate": 120, "rate": 120, "quantity": 1, "unit": " ", "discount_amount": 0, "discount": 0, "tax_id": 982000000557028, "tax_name": "VAT", "tax_type": "tax", "tax_percentage": 12.5, "tax_treatment_code": "uae_others", "item_total": 120 } ], "shipping_charge": 0, "adjustment": 0, "adjustment_description": " ", "sub_total": 153, "tax_total": 22.6, "total": 40.6, "taxes": [ { "tax_name": "VAT", "tax_amount": 19.13 } ], "payment_reminder_enabled": true, "payment_made": 26.91, "credits_applied": 22.43, "tax_amount_withheld": 0, "balance": 40.6, "write_off_amount": 0, "allow_partial_payments": true, "price_precision": 2, "payment_options": {...}, "is_emailed": false, "reminders_sent": 1, "last_reminder_sent_date": " ", "billing_address": {...}, "shipping_address": {...}, "notes": "Looking forward for your business.", "terms": "Terms & Conditions apply", "custom_fields": [ { "customfield_id": "46000000012845", "value": "Normal" } ], "template_id": 982000000000143, "template_name": "Service - Classic", "created_time": "2013-11-18T02:17:40-0800", "last_modified_time": "2013-11-18T02:02:51-0800", "attachment_name": " ", "can_send_in_mail": true, "salesperson_id": " ", "salesperson_name": " ", "invoice_url": "https://books.zoho.com/SecurePayment?CInvoiceID=23d84d0cf64f9a72ea0c66fded25a08c8bafd0ab508aff05323a9f80e2cd03fdc5dd568d3d6407bbda969d3e870d740b6fce549a9438c4ea" } } }

    ARGUMENTS

    customer_id
    Required
    ID of the customer the invoice has to be created.
    contact_persons
    Optional
    Array of contact person(s) for whom invoice has to be sent.
    invoice_number
    Optional
    Search invoices by invoice number.Variants: invoice_number_startswith and invoice_number_contains. Max-length [100]
    place_of_supply
    India Edition and GCC Editions only.
    Optional
    Place where the goods/services are supplied to. (If not given, place of contact given for the contact will be taken)
    Supported codes for UAE emirates are :
    Abu Dhabi - AB,
    Ajman - AJ,
    Dubai - DU,
    Fujairah - FU,
    Ras al-Khaimah - RA,
    Sharjah - SH,
    Umm al-Quwain - UM
    Supported codes for the GCC countries are :
    United Arab Emirates - AE,
    Saudi Arabia - SA,
    Bahrain - BH,
    Kuwait - KW,
    Oman - OM,
    Qatar - QA.
    vat_treatment
    Optional
    Enter vat treatment
    tax_treatment
    GCC Editions only
    Optional
    VAT treatment for the invoice .Choose whether the contact falls under: vat_registered,vat_not_registered,gcc_vat_not_registered,gcc_vat_registered,non_gcc.
    dz_vat_registered and dz_vat_not_registered supported only for UAE.
    gst_treatment
    India Edition only.
    Optional
    Choose whether the contact is GST registered/unregistered/consumer/overseas. Allowed values are business_gst , business_none , overseas , consumer .
    gst_no
    India Edition only.
    Optional
    15 digit GST identification number of the customer.
    reference_number
    Optional
    The reference number of the invoice
    template_id
    Optional
    ID of the pdf template associated with the invoice.
    date
    Optional
    Search invoices by invoice date. Default date format is yyyy-mm-dd. Variants: due_date_start, due_date_end, due_date_before and due_date_after.
    payment_terms
    Optional
    Payment terms in days e.g. 15, 30, 60. Invoice due date will be calculated based on this. Max-length [100]
    payment_terms_label
    Optional
    Used to override the default payment terms label. Default value for 15 days is "Net 15 Days". Max-length [100]
    due_date
    Optional
    Search invoices by due date. Default date format is yyyy-mm-dd. Variants: due_date_start, due_date_end, due_date_before and due_date_after
    discount
    Optional
    Discount applied to the invoice. It can be either in % or in amount. e.g. 12.5% or 190. Max-length [100]
    is_discount_before_tax
    Optional
    Used to specify how the discount has to applied. Either before or after the calculation of tax.
    discount_type
    Optional
    How the discount is specified. Allowed values: entity_level and item_level.
    is_inclusive_tax
    Optional
    Used to specify whether the line item rates are inclusive or exclusivr of tax.
    exchange_rate
    Optional
    Exchange rate of the currency.
    recurring_invoice_id
    Optional
    ID of the recurring invoice from which the invoice is created.
    invoiced_estimate_id
    Optional
    ID of the invoice from which the invoice is created.
    salesperson_name
    Optional
    Name of the salesperson. Max-length [200]
    custom_fields
    Optional
    Custom fields for an invoice.
    customfield_id
    Optional
    value
    Optional
    Value of the Custom Field
    project_id
    Optional
    Required
    item_id
    Required
    Search invoices by item id.
    project_id
    Optional
    time_entry_ids
    Optional
    IDs of the time entries associated with the project.
    product_type
    Optional
    Enter goods/services
    hsn_or_sac
    India Edition only
    Optional
    Add HSN/SAC code for your goods/services
    warehouse_id
    Optional
    Enter warehouse ID
    expense_id
    Optional
    expense_receipt_name
    Optional
    name
    Optional
    The name of the line item. Max-length [100]
    description
    Optional
    The description of the line items. Max-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. Max-length [100]
    discount_amount
    Optional
    The discount amount on the line item
    discount
    Optional
    Discount applied to the invoice. It can be either in % or in amount. e.g. 12.5% or 190. Max-length [100]
    tax_id
    Optional
    ID of the tax.
    tax_name
    Optional
    The name of the tax
    tax_type
    Optional
    The type of the tax
    tax_percentage
    Optional
    The percentage of tax levied
    tax_treatment_code
    GCC Editions only
    Optional
    Specify reason for using out of scope.
    Supported values for UAE are uae_same_tax_group, uae_reimbursed_expense and uae_others.
    Supported values for Bahrain are bahrain_same_tax_group, bahrain_transfer_of_concern, bahrain_disbursement, bahrain_head_to_branch_transaction and bahrain_others.
    Supported values for Saudi Arabia are ksa_pvt_health, ksa_pvt_edu and ksa_house_sales.
    payment_options
    Optional
    Payment options for the invoice, online payment gateways and bank accounts. Will be displayed in the pdf.
    allow_partial_payments
    Optional
    Boolean to check if partial payments are allowed for the contact
    custom_body
    Optional
    custom_subject
    Optional
    notes
    Optional
    The notes added below expressing gratitude or for conveying some information.
    terms
    Optional
    The terms added below expressing gratitude or for conveying some information.
    shipping_charge
    Optional
    Shipping charges applied to the invoice. Max-length [100]
    adjustment
    Optional
    Adjustments made to the invoice.
    adjustment_description
    Optional
    Customize the adjustment description. E.g. Rounding off.
    reason
    Optional
    tax_authority_id
    US edition only
    Optional
    ID of the tax authority. Tax authority depends on the location of the customer. For example, if the customer is located in NY, then the tax authority is NY tax authority.
    tax_exemption_id
    India and US edition only
    Optional
    ID of the tax exemption.
    avatax_use_code
    Avalara integration only
    Optional
    Used to group like customers for exemption purposes. It is a custom value that links customers to a tax rule. Select from Avalara [standard codes][1] or enter a custom code. Max-length [25]
    avatax_exempt_no
    Avalara integration only
    Optional
    Exemption certificate number of the customer. Max-length [25]
    vat_treatment
    Optional
    Enter vat treatment
    tax_id
    Optional
    ID of the tax.
    expense_id
    Optional
    salesorder_item_id
    Optional
    ID of the sales order line item which is invoices.
    avatax_tax_code
    Avalara integration only
    Optional
    A tax code is a unique label used to group Items (products, services, or charges) together. Refer the [link][2] for more deails. Max-length [25]
    time_entry_ids
    Optional
    IDs of the time entries associated with the project.
    payment_gateways
    Optional
    Online payment gateways through which payment can be made.
    gateway_name
    Optional
    Name of the payment gateway associated with the invoice. E.g. paypal, stripe.Allowed Values: paypal, authorize_net, payflow_pro, stripe, 2checkout and braintree
    additional_field1
    Optional
    Paypal payment method. Allowed Values: standard and adaptive

    Query Params

    send
    Optional
    Send the invoice to the contact person(s) associated with the invoice. Allowed values true and false.
    ignore_auto_number_generation
    Optional
    Ignore auto invoice number generation for this invoice. This mandates the invoice number. Allowed values true and false

    Update an invoice

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

    PUT /invoices/:invoice_id

    Request Example

      
    $ curl https://books.zoho.com/api/v3/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": [ "982000000870911", "982000000870915" ], "invoice_number": "INV-00003", "place_of_supply": "TN", "tax_treatment": "vat_registered", "gst_treatment": "business_gst", "gst_no": "22AAAAA0000A1Z5", "reference_number": " ", "template_id": 982000000000143, "date": "2013-11-17", "payment_terms": 15, "payment_terms_label": "Net 15", "due_date": "2013-12-03", "discount": 0, "is_discount_before_tax": true, "discount_type": "item_level", "is_inclusive_tax": false, "exchange_rate": 1, "recurring_invoice_id": " ", "invoiced_estimate_id": " ", "salesperson_name": " ", "custom_fields": [ { "customfield_id": "46000000012845", "value": "Normal" } ], "project_id": " ", "line_items": [ { "item_id": 982000000030049, "project_id": " ", "time_entry_ids": [ {} ], "product_type": "goods", "hsn_or_sac": 80540, "warehouse_id": "", "expense_id": " ", "name": "Hard Drive", "description": "500GB, USB 2.0 interface 1400 rpm, protective hard case.", "item_order": 1, "bcy_rate": 120, "rate": 120, "quantity": 1, "unit": " ", "discount_amount": 0, "discount": 0, "tax_id": 982000000557028, "tax_name": "VAT", "tax_type": "tax", "tax_percentage": 12.5, "tax_treatment_code": "uae_others" } ], "payment_options": {}, "allow_partial_payments": true, "custom_body": " ", "custom_subject": " ", "notes": "Looking forward for your business.", "terms": "Terms & Conditions apply", "shipping_charge": 0, "adjustment": 0, "adjustment_description": " ", "reason": " ", "tax_authority_id": 11149000000061052, "tax_exemption_id": 11149000000061054, "tax_id": 982000000557028, "expense_id": " ", "salesorder_item_id": " ", "payment_gateways": [ {} ], "gateway_name": "paypal", "additional_field1": "standard", "line_item_id": 982000000567021 }"'

    Response Example

      
    HTTP/1.1 200 OK Content-Type:application/json;charset=UTF-8 { "code": 0, "message": "Invoice information has been updated.", "invoice": { "invoice_id": 982000000567114, "ach_payment_initiated": false, "invoice_number": "INV-00003", "is_pre_gst": true, "place_of_supply": "TN", "gst_no": "22AAAAA0000A1Z5", "gst_treatment": "business_gst", "tax_treatment": "vat_registered", "date": "2013-11-17", "status": "draft", "payment_terms": 15, "payment_terms_label": "Net 15", "due_date": "2013-12-03", "payment_expected_date": " ", "last_payment_date": " ", "reference_number": " ", "customer_id": 982000000567001, "customer_name": "Bowman & Co", "contact_persons": [ "982000000870911", "982000000870915" ], "currency_id": 982000000000190, "currency_code": "USD", "exchange_rate": 1, "discount": 0, "is_discount_before_tax": true, "discount_type": "item_level", "is_inclusive_tax": false, "recurring_invoice_id": " ", "is_viewed_by_client": false, "has_attachment": false, "client_viewed_time": "", "line_items": [ { "line_item_id": 982000000567021, "item_id": 982000000030049, "project_id": " ", "time_entry_ids": [ {...} ], "warehouses": [ { "warehouse_id": "", "warehouse_name": "", "warehouse_stock_on_hand": "" } ], "item_type": "goods", "product_type": "goods", "expense_id": " ", "name": "Hard Drive", "description": "500GB, USB 2.0 interface 1400 rpm, protective hard case.", "item_order": 1, "bcy_rate": 120, "rate": 120, "quantity": 1, "unit": " ", "discount_amount": 0, "discount": 0, "tax_id": 982000000557028, "tax_name": "VAT", "tax_type": "tax", "tax_percentage": 12.5, "tax_treatment_code": "uae_others", "item_total": 120 } ], "shipping_charge": 0, "adjustment": 0, "adjustment_description": " ", "sub_total": 153, "tax_total": 22.6, "total": 40.6, "taxes": [ { "tax_name": "VAT", "tax_amount": 19.13 } ], "payment_reminder_enabled": true, "payment_made": 26.91, "credits_applied": 22.43, "tax_amount_withheld": 0, "balance": 40.6, "write_off_amount": 0, "allow_partial_payments": true, "price_precision": 2, "payment_options": {...}, "is_emailed": false, "reminders_sent": 1, "last_reminder_sent_date": " ", "billing_address": {...}, "shipping_address": {...}, "notes": "Looking forward for your business.", "terms": "Terms & Conditions apply", "custom_fields": [ { "customfield_id": "46000000012845", "value": "Normal" } ], "template_id": 982000000000143, "template_name": "Service - Classic", "created_time": "2013-11-18T02:17:40-0800", "last_modified_time": "2013-11-18T02:02:51-0800", "attachment_name": " ", "can_send_in_mail": true, "salesperson_id": " ", "salesperson_name": " ", "invoice_url": "https://books.zoho.com/SecurePayment?CInvoiceID=23d84d0cf64f9a72ea0c66fded25a08c8bafd0ab508aff05323a9f80e2cd03fdc5dd568d3d6407bbda969d3e870d740b6fce549a9438c4ea" } }

    ARGUMENTS

    customer_id
    Required
    ID of the customer the invoice has to be created.
    contact_persons
    Optional
    Array of contact person(s) for whom invoice has to be sent.
    invoice_number
    Optional
    Search invoices by invoice number.Variants: invoice_number_startswith and invoice_number_contains. Max-length [100]
    place_of_supply
    India Edition and GCC Editions only.
    Optional
    Place where the goods/services are supplied to. (If not given, place of contact given for the contact will be taken)
    Supported codes for UAE emirates are :
    Abu Dhabi - AB,
    Ajman - AJ,
    Dubai - DU,
    Fujairah - FU,
    Ras al-Khaimah - RA,
    Sharjah - SH,
    Umm al-Quwain - UM
    Supported codes for the GCC countries are :
    United Arab Emirates - AE,
    Saudi Arabia - SA,
    Bahrain - BH,
    Kuwait - KW,
    Oman - OM,
    Qatar - QA.
    vat_treatment
    Optional
    Enter vat treatment
    tax_treatment
    GCC Editions only
    Optional
    VAT treatment for the invoice .Choose whether the contact falls under: vat_registered,vat_not_registered,gcc_vat_not_registered,gcc_vat_registered,non_gcc.
    dz_vat_registered and dz_vat_not_registered supported only for UAE.
    gst_treatment
    India Edition only.
    Optional
    Choose whether the contact is GST registered/unregistered/consumer/overseas. Allowed values are business_gst , business_none , overseas , consumer .
    gst_no
    India Edition only.
    Optional
    15 digit GST identification number of the customer.
    reference_number
    Optional
    The reference number of the invoice
    template_id
    Optional
    ID of the pdf template associated with the invoice.
    date
    Optional
    Search invoices by invoice date. Default date format is yyyy-mm-dd. Variants: due_date_start, due_date_end, due_date_before and due_date_after.
    payment_terms
    Optional
    Payment terms in days e.g. 15, 30, 60. Invoice due date will be calculated based on this. Max-length [100]
    payment_terms_label
    Optional
    Used to override the default payment terms label. Default value for 15 days is "Net 15 Days". Max-length [100]
    due_date
    Optional
    Search invoices by due date. Default date format is yyyy-mm-dd. Variants: due_date_start, due_date_end, due_date_before and due_date_after
    discount
    Optional
    Discount applied to the invoice. It can be either in % or in amount. e.g. 12.5% or 190. Max-length [100]
    is_discount_before_tax
    Optional
    Used to specify how the discount has to applied. Either before or after the calculation of tax.
    discount_type
    Optional
    How the discount is specified. Allowed values: entity_level and item_level.
    is_inclusive_tax
    Optional
    Used to specify whether the line item rates are inclusive or exclusivr of tax.
    exchange_rate
    Optional
    Exchange rate of the currency.
    recurring_invoice_id
    Optional
    ID of the recurring invoice from which the invoice is created.
    invoiced_estimate_id
    Optional
    ID of the invoice from which the invoice is created.
    salesperson_name
    Optional
    Name of the salesperson. Max-length [200]
    custom_fields
    Optional
    Custom fields for an invoice.
    customfield_id
    Optional
    value
    Optional
    Value of the Custom Field
    project_id
    Optional
    Required
    item_id
    Required
    Search invoices by item id.
    project_id
    Optional
    time_entry_ids
    Optional
    IDs of the time entries associated with the project.
    product_type
    Optional
    Enter goods/services
    hsn_or_sac
    India Edition only
    Optional
    Add HSN/SAC code for your goods/services
    warehouse_id
    Optional
    Enter warehouse ID
    expense_id
    Optional
    expense_receipt_name
    Optional
    name
    Optional
    The name of the line item. Max-length [100]
    description
    Optional
    The description of the line items. Max-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. Max-length [100]
    discount_amount
    Optional
    The discount amount on the line item
    discount
    Optional
    Discount applied to the invoice. It can be either in % or in amount. e.g. 12.5% or 190. Max-length [100]
    tax_id
    Optional
    ID of the tax.
    tax_name
    Optional
    The name of the tax
    tax_type
    Optional
    The type of the tax
    tax_percentage
    Optional
    The percentage of tax levied
    tax_treatment_code
    GCC Editions only
    Optional
    Specify reason for using out of scope.
    Supported values for UAE are uae_same_tax_group, uae_reimbursed_expense and uae_others.
    Supported values for Bahrain are bahrain_same_tax_group, bahrain_transfer_of_concern, bahrain_disbursement, bahrain_head_to_branch_transaction and bahrain_others.
    Supported values for Saudi Arabia are ksa_pvt_health, ksa_pvt_edu and ksa_house_sales.
    payment_options
    Optional
    Payment options for the invoice, online payment gateways and bank accounts. Will be displayed in the pdf.
    allow_partial_payments
    Optional
    Boolean to check if partial payments are allowed for the contact
    custom_body
    Optional
    custom_subject
    Optional
    notes
    Optional
    The notes added below expressing gratitude or for conveying some information.
    terms
    Optional
    The terms added below expressing gratitude or for conveying some information.
    shipping_charge
    Optional
    Shipping charges applied to the invoice. Max-length [100]
    adjustment
    Optional
    Adjustments made to the invoice.
    adjustment_description
    Optional
    Customize the adjustment description. E.g. Rounding off.
    reason
    Optional
    tax_authority_id
    US edition only
    Optional
    ID of the tax authority. Tax authority depends on the location of the customer. For example, if the customer is located in NY, then the tax authority is NY tax authority.
    tax_exemption_id
    India and US edition only
    Optional
    ID of the tax exemption.
    avatax_use_code
    Avalara integration only
    Optional
    Used to group like customers for exemption purposes. It is a custom value that links customers to a tax rule. Select from Avalara [standard codes][1] or enter a custom code. Max-length [25]
    avatax_exempt_no
    Avalara integration only
    Optional
    Exemption certificate number of the customer. Max-length [25]
    vat_treatment
    Optional
    Enter vat treatment
    tax_id
    Optional
    ID of the tax.
    expense_id
    Optional
    salesorder_item_id
    Optional
    ID of the sales order line item which is invoices.
    avatax_tax_code
    Avalara integration only
    Optional
    A tax code is a unique label used to group Items (products, services, or charges) together. Refer the [link][2] for more deails. Max-length [25]
    payment_gateways
    Optional
    Online payment gateways through which payment can be made.
    gateway_name
    Optional
    Name of the payment gateway associated with the invoice. E.g. paypal, stripe.Allowed Values: paypal, authorize_net, payflow_pro, stripe, 2checkout and braintree
    additional_field1
    Optional
    Paypal payment method. Allowed Values: standard and adaptive
    line_item_id
    Optional
    The line item id

    Query Params

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

    Get an invoice

    Get the details of an invoice.
    oauthscope : ZohoBooks.invoices.READ

    GET /invoices/:invoice_id

    Request Example

      
    $ curl https://books.zoho.com/api/v3/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": { "invoice_id": 982000000567114, "ach_payment_initiated": false, "invoice_number": "INV-00003", "is_pre_gst": true, "place_of_supply": "TN", "gst_no": "22AAAAA0000A1Z5", "gst_treatment": "business_gst", "tax_treatment": "vat_registered", "date": "2013-11-17", "status": "draft", "payment_terms": 15, "payment_terms_label": "Net 15", "due_date": "2013-12-03", "payment_expected_date": " ", "last_payment_date": " ", "reference_number": " ", "customer_id": 982000000567001, "customer_name": "Bowman & Co", "contact_persons": [ "982000000870911", "982000000870915" ], "currency_id": 982000000000190, "currency_code": "USD", "exchange_rate": 1, "discount": 0, "is_discount_before_tax": true, "discount_type": "item_level", "is_inclusive_tax": false, "recurring_invoice_id": " ", "is_viewed_by_client": false, "has_attachment": false, "client_viewed_time": "", "line_items": [ { "line_item_id": 982000000567021, "item_id": 982000000030049, "project_id": " ", "time_entry_ids": [ {...} ], "warehouses": [ { "warehouse_id": "", "warehouse_name": "", "warehouse_stock_on_hand": "" } ], "item_type": "goods", "product_type": "goods", "expense_id": " ", "name": "Hard Drive", "description": "500GB, USB 2.0 interface 1400 rpm, protective hard case.", "item_order": 1, "bcy_rate": 120, "rate": 120, "quantity": 1, "unit": " ", "discount_amount": 0, "discount": 0, "tax_id": 982000000557028, "tax_name": "VAT", "tax_type": "tax", "tax_percentage": 12.5, "tax_treatment_code": "uae_others", "item_total": 120 } ], "shipping_charge": 0, "adjustment": 0, "adjustment_description": " ", "sub_total": 153, "tax_total": 22.6, "total": 40.6, "taxes": [ { "tax_name": "VAT", "tax_amount": 19.13 } ], "payment_reminder_enabled": true, "payment_made": 26.91, "credits_applied": 22.43, "tax_amount_withheld": 0, "balance": 40.6, "write_off_amount": 0, "allow_partial_payments": true, "price_precision": 2, "payment_options": {...}, "is_emailed": false, "reminders_sent": 1, "last_reminder_sent_date": " ", "billing_address": {...}, "shipping_address": {...}, "notes": "Looking forward for your business.", "terms": "Terms & Conditions apply", "custom_fields": [ { "customfield_id": "46000000012845", "value": "Normal" } ], "template_id": 982000000000143, "template_name": "Service - Classic", "created_time": "2013-11-18T02:17:40-0800", "last_modified_time": "2013-11-18T02:02:51-0800", "attachment_name": " ", "can_send_in_mail": true, "salesperson_id": " ", "salesperson_name": " ", "invoice_url": "https://books.zoho.com/SecurePayment?CInvoiceID=23d84d0cf64f9a72ea0c66fded25a08c8bafd0ab508aff05323a9f80e2cd03fdc5dd568d3d6407bbda969d3e870d740b6fce549a9438c4ea" } } }

    Query Params

    print
    Optional
    Print the exported pdf.
    accept
    Optional
    Get the details of a particular invoice in formats such as json/ pdf/ html. Default format is json. Allowed values json pdf and html

    List invoices

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

    GET /invoices

    Request Example

      
    $ curl https://books.zoho.com/api/v3/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-18T02:17:40-0800", "last_modified_time": "2013-11-18T02:02:51-0800", "is_emailed": false, "reminders_sent": 1, "last_reminder_sent_date": " ", "payment_expected_date": " ", "last_payment_date": " ", "custom_fields": [ { "customfield_id": "46000000012845", "value": "Normal" } ], "documents": "", "salesperson_id": " ", "salesperson_name": " ", "shipping_charge": 0, "adjustment": 0, "write_off_amount": 0, "exchange_rate": 1 } ], "page_context": [ { "page": 1, "per_page": 200, "has_more_page": false, "report_name": "Invoices", "applied_filter": "Status.All", "sort_column": "created_time", "sort_order": "D" } ] }

    Query Params

    invoice_number
    Optional
    Search invoices by invoice number.Variants: invoice_number_startswith and invoice_number_contains. Max-length [100]
    item_name
    Optional
    Search invoices by item name.Variants: item_name_startswith and item_name_contains. Max-length [100]
    item_id
    Optional
    Search invoices by item id.
    item_description
    Optional
    Search invoices by item description.Variants: item_description_startswith and item_description_contains. Max-length [100]
    reference_number
    Optional
    The reference number of the invoice
    customer_name
    Optional
    The name of the customer. Max-length [100]
    recurring_invoice_id
    Optional
    ID of the recurring invoice from which the invoice is created.
    email
    Optional
    Search contacts by email id. Max-length [100]
    total
    Optional
    The total amount to be paid
    balance
    Optional
    The unpaid amount
    custom_field
    Optional
    Search invoices by custom fields.Variants: custom_field_startswith and custom_field_contains
    date
    Optional
    Search invoices by invoice date. Default date format is yyyy-mm-dd. Variants: due_date_start, due_date_end, due_date_before and due_date_after.
    due_date
    Optional
    Search invoices by due date. Default date format is yyyy-mm-dd. Variants: due_date_start, due_date_end, due_date_before and due_date_after
    last_modified_time
    Optional
    status
    Optional
    Search invoices by invoice status.Allowed Values: sent, draft, overdue, paid, void, unpaid, partially_paid and viewed
    customer_id
    Optional
    ID of the customer the invoice has to be created.
    filter_by
    Optional
    Filter invoices by any status or payment expected date.Allowed Values: Status.All, Status.Sent, Status.Draft, Status.OverDue, Status.Paid, Status.Void, Status.Unpaid, Status.PartiallyPaid, Status.Viewed and Date.PaymentExpectedDate
    search_text
    Optional
    Search invoices by invoice number or purchase order or customer name. Max-length [100]
    sort_column
    Optional
    Sort invoices.Allowed Values: customer_name, invoice_number, date, due_date, total, balance and created_time

    Delete an invoice

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

    DELETE /invoices/:invoice_id

    Request Example

      
    $ curl https://books.zoho.com/api/v3/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 : ZohoBooks.invoices.CREATE

    POST /invoices/:invoice_id/status/sent

    Request Example

      
    $ curl https://books.zoho.com/api/v3/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 : ZohoBooks.invoices.CREATE

    POST /invoices/:invoice_id/status/void

    Request Example

      
    $ curl https://books.zoho.com/api/v3/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 : ZohoBooks.invoices.CREATE

    POST /invoices/:invoice_id/status/draft

    Request Example

      
    $ curl https://books.zoho.com/api/v3/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 : ZohoBooks.invoices.CREATE

    POST /invoices/:invoice_id/email

    Request Example

      
    $ curl https://books.zoho.com/api/v3/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": [ "[email protected]" ], "cc_mail_ids": [ "[email protected]" ], "subject": "Invoice from Zillium Inc (Invoice#: INV-00001)", "body": "Dear Customer, <br><br><br><br>Thanks for your business. <br><br><br><br>The invoice INV-00001 is attached with this email. You can choose the easy way out and <a href= https://invoice.zoho.com/SecurePayment?CInvoiceID=b9800228e011ae86abe71227bdacb3c68e1af685f647dcaed747812e0b9314635e55ac6223925675b371fcbd2d5ae3dc >pay online for this invoice.</a> <br><br>Here's an overview of the invoice for your reference. <br><br><br><br>Invoice Overview: <br><br>Invoice : INV-00001 <br><br>Date : 05 Aug 2013 <br><br>Amount : $541.82 <br><br><br><br>It was great working with you. Looking forward to working with you again.<br><br><br>\\nRegards<br>\\nZillium Inc<br>\\n\"," }"'

    Response Example

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

    ARGUMENTS

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

    Query Params

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

    Email invoices

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

    POST /invoices/email

    Request Example

      
    $ curl https://books.zoho.com/api/v3/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" -F 'JSONString="{ "contacts": [ {} ], "contact_id": 460000000026049 }"'

    Response Example

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

    ARGUMENTS

    Optional
    Contacts for whom email or snail mail has to be sent.
    contact_id
    Required
    ID of the contact. Can specify if email or snail mail has to be sent for each contact.

    Query Params

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

    Submit an invoice for approval

    Submit an invoice for approval.
    oauthscope : ZohoBooks.invoices.CREATE

    POST /invoices/:invoice_id/submit

    Request Example

      
    $ curl https://books.zoho.com/api/v3/invoices/:invoice_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 invoice has been submitted for approval successfully." }

    Approve an invoice.

    Approve an invoice.
    oauthscope : ZohoBooks.invoices.CREATE

    POST /invoices/:invoice_id/approve

    Request Example

      
    $ curl https://books.zoho.com/api/v3/invoices/:invoice_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 invoice." }

    Get invoice email content

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

    GET /invoices/{:invoice_id}/email

    Request Example

      
    $ curl https://books.zoho.com/api/v3/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": "Sujin Kumar" } ], "file_name_without_extension": "INV-000004", "to_mails_str": "", "cc_mails_str": "", "from_email": "", "from_address": "", "deprecated_placeholders_used": [ {...} ], "error_list": [ {...} ], "subject": "Invoice from Zillium Inc (Invoice#: INV-00001)", "emailtemplates": [ { "selected": true, "name": "Hard Drive" } ], "emailtemplate_documents": [ {...} ], "to_contacts": [ { "first_name": "Sujin", "selected": true, "phone": "+1-925-921-9201", "last_name": "Kumar", "salutation": "Mr", "contact_person_id": 982000000567003, "mobile": "+1-4054439562" } ], "attachment_name": " ", "file_name": "INV-00001.pdf", "from_emails": [ { "user_name": "Sujin Kumar", "selected": true, "organization_contact_id": "2000000002266", "is_org_email_id": true } ], "customer_id": 982000000567001 } }

    Query Params

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

    Remind Customer

    Remind your customer about an unpaid invoice by email. Reminder will be sent, only for the invoices which are in open or overdue status.
    oauthscope : ZohoBooks.invoices.CREATE

    POST /invoices/{:invoice_id}/paymentreminder

    Request Example

      
    $ curl https://books.zoho.com/api/v3/invoices/{:invoice_id}/paymentreminder?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": [ "[email protected]" ], "cc_mail_ids": [ "[email protected]" ], "subject": "Invoice from Zillium Inc (Invoice#: INV-00001)", "body": "<br>Dear Mr. Sujin,&nbsp;<br><br>You might have missed the payment date and the invoice is now overdue by&nbsp;1&nbsp;days.<br><br>----------------------------------------------------------------------------------------<br><h2>Invoice# : INV-000004 </h2>Dated : 23 Dec 2016<br>----------------------------------------------------------------------------------------<br><b>&nbsp;Due Date &nbsp; &nbsp; &nbsp; &nbsp; : &nbsp;&nbsp;23 Dec 2016</b><br><b>&nbsp;Amount &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; : &nbsp;&nbsp;$139.65</b><br>----------------------------------------------------------------------------------------<br><br><span>Not to worry at all !&nbsp;</span>View your invoice and take the easy way out by making an&nbsp;<a href=\"https://books.zoho.com/portal/zilliuminc/index#/invoices/invoice/2000000007037 \">online payment</a>.<br><br>If you have already paid, please accept our apologies and kindly ignore this payment reminder.<br><br><br>Regards,<br><br>David Sujin<br>Zillium Inc<br><br><br>", "send_from_org_email_id": false }"'

    Response Example

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

    ARGUMENTS

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

    Query Params

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

    Bulk invoice reminder

    Remind your customer about an unpaid invoices by email. Reminder mail will be send, only for the invoices is in open or overdue status. Maximum 10 invoices can be reminded at once.
    oauthscope : ZohoBooks.invoices.CREATE

    POST /invoices/paymentreminder

    Request Example

      
    $ curl https://books.zoho.com/api/v3/invoices/paymentreminder?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 201 Created Content-Type:application/json;charset=UTF-8 { "code": 0, "message": "success", "info": { "email_success_info": { "message": "The reminders were successfully sent", "sent_count": 2 }, "email_errors_info": [ { "message": "The reminders were successfully sent", "ids": [ {...} ] } ], "code": 4083 } }

    Query Params

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

    Get payment reminder mail content

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

    GET /invoices/{:invoice_id}/paymentreminder

    Request Example

      
    $ curl https://books.zoho.com/api/v3/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,&nbsp;<br><br>You might have missed the payment date and the invoice is now overdue by&nbsp;1&nbsp;days.<br><br>----------------------------------------------------------------------------------------<br><h2>Invoice# : INV-000004 </h2>Dated : 23 Dec 2016<br>----------------------------------------------------------------------------------------<br><b>&nbsp;Due Date &nbsp; &nbsp; &nbsp; &nbsp; : &nbsp;&nbsp;23 Dec 2016</b><br><b>&nbsp;Amount &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; : &nbsp;&nbsp;$139.65</b><br>----------------------------------------------------------------------------------------<br><br><span>Not to worry at all !&nbsp;</span>View your invoice and take the easy way out by making an&nbsp;<a href=\"https://books.zoho.com/portal/zilliuminc/index#/invoices/invoice/2000000007037 \">online payment</a>.<br><br>If you have already paid, please accept our apologies and kindly ignore this payment reminder.<br><br><br>Regards,<br><br>David Sujin<br>Zillium Inc<br><br><br>", "documents": "", "customer_name": "Bowman & Co", "attach_pdf": true, "entity_id": "2000000007037", "cc_mails_list": [ { "user_name": "Sujin Kumar" } ], "file_name_without_extension": "INV-000004", "to_mails_str": "", "cc_mails_str": "", "from_email": "", "from_address": "", "deprecated_placeholders_used": [ {...} ], "error_list": [ {...} ], "subject": "Invoice from Zillium Inc (Invoice#: INV-00001)", "emailtemplates": [ { "selected": true, "name": "Hard Drive" } ], "emailtemplate_documents": [ {...} ], "to_contacts": [ { "first_name": "Sujin", "selected": true, "phone": "+1-925-921-9201", "last_name": "Kumar", "salutation": "Mr", "contact_person_id": 982000000567003, "mobile": "+1-4054439562" } ], "attachment_name": " ", "file_name": "INV-00001.pdf", "from_emails": [ { "user_name": "Sujin Kumar", "selected": true, "organization_contact_id": "2000000002266", "is_org_email_id": true } ], "customer_id": 982000000567001 } }

    Bulk export Invoices

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

    GET /invoices/pdf

    Request Example

      
    $ curl https://books.zoho.com/api/v3/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 : ZohoBooks.invoices.READ

    GET /invoices/print

    Request Example

      
    $ curl https://books.zoho.com/api/v3/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 : ZohoBooks.invoices.CREATE

    POST /invoices/{:invoice_id}/paymentreminder/disable

    Request Example

      
    $ curl https://books.zoho.com/api/v3/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 : ZohoBooks.invoices.CREATE

    POST /invoices/{:invoice_id}/paymentreminder/enable

    Request Example

      
    $ curl https://books.zoho.com/api/v3/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 : ZohoBooks.invoices.CREATE

    POST /invoices/{:invoice_id}/writeoff

    Request Example

      
    $ curl https://books.zoho.com/api/v3/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 : ZohoBooks.invoices.CREATE

    POST /invoices/{:invoice_id}/writeoff/cancel

    Request Example

      
    $ curl https://books.zoho.com/api/v3/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 : ZohoBooks.invoices.UPDATE

    PUT /invoices/{:invoice_id}/address/billing

    Request Example

      
    $ curl https://books.zoho.com/api/v3/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 for the invoice
    city
    Optional
    City of the customer’s billing address.
    state
    Optional
    State of the customer’s billing address.
    zip
    Optional
    Zip code of the customer’s billing address.
    country
    Optional
    Country of the customer’s billing address.
    fax
    Optional
    Customer's fax number.

    Update shipping address

    Updates the shipping address for this invoice alone.
    oauthscope : ZohoBooks.invoices.UPDATE

    PUT /invoices/{:invoice_id}/address/shipping

    Request Example

      
    $ curl https://books.zoho.com/api/v3/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
    Billing address for the invoice
    city
    Optional
    City of the customer’s billing address.
    state
    Optional
    State of the customer’s billing address.
    zip
    Optional
    Zip code of the customer’s billing address.
    country
    Optional
    Country of the customer’s billing address.
    fax
    Optional
    Customer's fax number.

    List invoice templates

    Get all invoice pdf templates.
    oauthscope : ZohoBooks.invoices.READ

    Get /invoices/templates

    Request Example

      
    $ curl https://books.zoho.com/api/v3/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 : ZohoBooks.invoices.UPDATE

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

    Request Example

      
    $ curl https://books.zoho.com/api/v3/invoices/{:invoice_id}/templates/{:template_id}?organization_id=10234695 -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 : ZohoBooks.invoices.READ

    GET /invoices/{:invoice_id}/payments

    Request Example

      
    $ curl https://books.zoho.com/api/v3/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": 982000000567114, "invoice_payment_id": 982000000567192, "payment_mode": "cash", "description": "500GB, USB 2.0 interface 1400 rpm, protective hard case.", "date": "2013-11-17", "reference_number": " ", "exchange_rate": 1, "amount": 10.57, "tax_amount_withheld": 0, "online_transaction_id": "", "is_single_invoice_payment": true } ] }

    List credits applied

    Get the list of credits applied for an invoice.
    oauthscope : ZohoBooks.invoices.READ

    GET /invoices/{:invoice_id}/creditsapplied

    Request Example

      
    $ curl https://books.zoho.com/api/v3/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 : ZohoBooks.invoices.CREATE

    POST /invoices/{:invoice_id}/credits

    Request Example

      
    $ curl https://books.zoho.com/api/v3/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": 982000000567190, "amount_applied": 12.2 } ], "apply_creditnotes": [ { "creditnote_id": 982000000567134, "amount_applied": 12.2 } ] }"'

    Response Example

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

    ARGUMENTS

    invoice_payments
    Required
    payment_id
    Optional
    The id of the payment
    amount_applied
    Optional
    The applied amount to the creditnote
    apply_creditnotes
    Required
    creditnote_id
    Optional
    The id of creditnote
    amount_applied
    Optional
    The applied amount to the creditnote

    Delete a payment

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

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

    Request Example

      
    $ curl https://books.zoho.com/api/v3/invoices/{:invoice_id}/payments/{:invoice_payment_id}?organization_id=10234695 -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 : ZohoBooks.invoices.DELETE

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

    Request Example

      
    $ curl https://books.zoho.com/api/v3/invoices/{:invoice_id}/creditsapplied/{:creditnotes_invoice_id}?organization_id=10234695 -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 : ZohoBooks.invoices.READ

    GET /invoices/{:invoice_id}/attachment

    Request Example

      
    $ curl https://books.zoho.com/api/v3/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 : ZohoBooks.invoices.CREATE

    POST /invoices/{:invoice_id}/attachment

    Request Example

      
    $ curl https://books.zoho.com/api/v3 /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 : ZohoBooks.invoices.UPDATE

    PUT /invoices/{:invoice_id}/attachment

    Request Example

      
    $ curl https://books.zoho.com/api/v3 /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 : ZohoBooks.invoices.DELETE

    DELETE /invoices/{:invoice_id}/attachment

    Request Example

      
    $ curl https://books.zoho.com/api/v3/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." }

    Delete the expense receipt

    Delete the expense receipts attached to an invoice which is raised from an expense.
    oauthscope : ZohoBooks.invoices.DELETE

    DELETE /invoices/expenses/{:expense_id}/receipt

    Request Example

      
    $ curl https://books.zoho.com/api/v3 /invoices/expenses/{:expense_id}/receipt?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 attached expense receipt has been deleted." }

    List invoice comments & history

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

    GET /invoices/{:invoice_id}/comments

    Request Example

      
    $ curl https://books.zoho.com/api/v3 /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": [ { "comments": [ { "comment_id": 982000000567019, "invoice_id": 982000000567114, "description": "500GB, USB 2.0 interface 1400 rpm, protective hard case.", "commented_by_id": 982000000554041, "commented_by": "John David", "comment_type": "system", "operation_type": "Added", "date": "2013-11-17", "date_description": "yesterday", "time": "2:02 AM", "transaction_id": " ", "transaction_type": "invoice" } ] }, {...}, {...} ] }

    Add comment

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

    POST /invoices/{:invoice_id}/comments

    Request Example

      
    $ curl https://books.zoho.com/api/v3/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
    The description of the line items. Max-length [2000]
    payment_expected_date
    Optional
    The expected date of payment
    show_comment_to_clients
    Optional
    Boolean to check if the comment to be shown to the clients

    Update comment

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

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

    Request Example

      
    $ curl https://books.zoho.com/api/v3/invoices/{:invoice_id}/comments/:comment_id?organization_id=10234695 -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": { "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 : ZohoBooks.invoices.DELETE

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

    Request Example

      
    $ curl https://books.zoho.com/api/v3/invoices/{:invoice_id}/comments/{:comment_id}?organization_id=10234695 -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." }

    Recurring-Invoices

    Recurring invoices are invoices that are created and sent to your customers on a recurring schedule.

    Example

    { "recurring_invoice_id": "90300000072369", "recurrence_name": "MonthlyInvoice", "customer_name": "Sujin Kumar", "customer_id": "903000000000099", "date": "2016-06-05", "start_date": "2016-06-12", "end_date": "2017-06-12", "last_sent_date": "2016-06-12", "next_invoice_date": "2016-06-17", "recurrence_frequency": "weeks", "repeat_every": 2, "status": "active", "email": "[email protected]", "item_id": "90300000081501", "description": "prorated amount for items", "type": 1, "quantity": 1, "price": 100, "item_total": 100, "currency_id": "982000000000190", "currency_code": "USD", "created_time": "2016-06-05T02:30:08-0700", "updated_time": "2016-06-05T02:30:08-0700", "contact_persons": [ "90300000065322" ], "exchange_rate": "5.5", "notes": "Offer for the referral", "terms": "", "tax_name": "Basic Tax", "tax_percentage": "10%", "tax_amount": "2.50", "recurring_invoice_items": [ { "item_id": "90300000081501", "description": "prorated amount for items", "quantity": 1, "price": 100, "item_total": 100 } ] }

    Attribute

    recurring_invoice_id
    string
    Unique ID of the recurring invoice generated by the server.
    recurrence_name
    string
    Unique name for the recurring profile given by the user. Max-length [100]
    customer_name
    string
    Name of the customer to whom the recurring invoice is raised.
    customer_id
    string
    Customer ID of the customer for whom the recurring invoice is raised.
    date
    string
    The date on which recurring invoice is raised.
    start_date
    string
    The date on which the recurring invoice starts.
    end_date
    string
    The date on which the recurring invoice expires.
    last_sent_date
    string
    The date at which the last invoice was sent.
    next_invoice_date
    string
    The date at which next invoice is to be sent.
    recurrence_frequency
    enum
    The frequency of time interval at which the invoice is to be generated.
    repeat_every
    integer
    The period between every recurrency frequency.
    status
    string
    Status of the recurring invoice. This can be active, stopped or expired.
    email
    string
    Email address of the customer.
    item_id
    string
    Unique string generated for the item for which invoice is to be sent.
    description
    required
    A small description about the item. Max-length [2000]
    type
    integer
    Type of the recurring invoice line item.
    quantity
    required
    Quantity of the item included.
    price
    double
    The price of the item included.
    item_total
    double
    Total rate raised by this item. This would be the multiplicative product of item price and quantity.
    currency_id
    string
    The currenct id of the currency
    currency_code
    string
    The currency code in which the invoice is created.
    created_time
    string
    Time at which the recurring invoice was created.
    updated_time
    string
    Time at which the recurring invoice details were last updated.
    contact_persons
    array
    Contact Persons associated with the recurring invoice.
    exchange_rate
    string
    Exchange rate for the currency associated with the customer.
    notes
    string
    A short note for the recurring invoice.
    terms
    string
    Terms & condition to be displayed in the recurring invoice.
    tax_name
    string
    Unique name for tax.
    tax_percentage
    string
    Percentage of tax
    tax_amount
    string
    Tax amount applied to the subscription.
    recurring_invoice_items
    list
    item_id
    string
    Unique string generated for the item for which invoice is to be sent.
    description
    required
    A small description about the item. Max-length [2000]
    quantity
    required
    Quantity of the item included.
    price
    double
    The price of the item included.
    item_total
    double
    Total rate raised by this item. This would be the multiplicative product of item price and quantity.

    Create a Recurring Invoice

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

    POST /recurringinvoices

    Request Example

      
    $ curl https://books.zoho.com/api/v3/recurringinvoices?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="{ "recurrence_name": "MonthlyInvoice", "reference_number": "12314", "customer_id": "903000000000099", "contact_persons": [ "90300000065322" ], "place_of_supply": "TN", "gst_treatment": "business_gst", "tax_treatment": "vat_registered", "gst_no": "22AAAAA0000A1Z5", "start_date": "2016-06-12", "end_date": "2017-06-12", "recurrence_frequency": "weeks", "repeat_every": 2, "line_items": [ { "line_item_id": "982000000567021", "quantity": 1, "name": "Hard Drive", "item_total": 100, "product_type": "goods", "hsn_or_sac": 80540, "warehouse_id": "", "tax_id": "903000000000356", "tax_treatment_code": "uae_others" } ], "tax_id": "903000000000356", "email": "[email protected]", "billing_address": { "address": "4900 Hopyard Rd, Suite 310", "street2": "McMillan Avenue", "city": "Pleasanton", "state": "CA", "zip": "94588", "country": "U.S.A", "fax": "+1-925-924-9600" }, "shipping_address": { "address": "4900 Hopyard Rd, Suite 310", "city": "Pleasanton", "state": "CA", "zip": "94588", "country": "U.S.A", "fax": "+1-925-924-9600" }, "payment_gateways": [ { "configured": true, "additional_field1": "standard", "gateway_name": "paypal" } ], "template_id": "90300000001336", "payment_terms": 0, "payment_terms_label": "Next 15 days", "tax_authority_id": "903000006345", "tax_exemption_id": "903000006345", "exchange_rate": "5.5", "payment_options": { "payment_gateways": [ { "configured": true, "additional_field1": "standard", "gateway_name": "paypal" } ] }, "gateway_name": "paypal", "additional_field1": "standard", "discount": "30%", "is_discount_before_tax": true, "discount_type": "entity level", "is_inclusive_tax": false, "item_id": "90300000081501", "name": "Hard Drive", "description": "prorated amount for items", "rate": 0, "quantity": 1, "unit": "kgs", "avatax_tax_code": " ", "salesperson_name": " ", "shipping_charge": 0, "adjustment": 0, "adjustment_description": "Rounding off" }"'

    Response Example

      
    HTTP/1.1 201 Created Content-Type:application/json;charset=UTF-8 { "code": 0, "message": "The recurring invoice has been created.", "recurring_invoice": { "recurring_invoice": { "recurring_invoice_id": "90300000072369", "recurrence_name": "MonthlyInvoice", "reference_number": "12314", "customer_name": "Sujin Kumar", "is_pre_gst": false, "gst_no": "22AAAAA0000A1Z5", "gst_treatment": "business_gst", "tax_treatment": "vat_registered", "place_of_supply": "TN", "customer_id": "903000000000099", "currency_id": "982000000000190", "currency_code": "USD", "start_date": "2016-06-12", "end_date": "2017-06-12", "last_sent_date": "2016-06-12", "next_invoice_date": "2016-06-17", "line_items": [ { "line_item_id": "982000000567021", "quantity": 1, "name": "Hard Drive", "item_total": 100, "sku": "LEV-JN-SL-36-GN", "product_type": "goods", "warehouse_id": "", "warehouses": [ { "warehouse_id": "", "warehouse_stock_on_hand": "" } ], "tax_id": "903000000000356", "tax_treatment_code": "uae_others" } ], "billing_address": { "address": "4900 Hopyard Rd, Suite 310", "street2": "McMillan Avenue", "city": "Pleasanton", "state": "CA", "zip": "94588", "country": "U.S.A", "fax": "+1-925-924-9600" }, "shipping_address": { "address": "4900 Hopyard Rd, Suite 310", "city": "Pleasanton", "state": "CA", "zip": "94588", "country": "U.S.A", "fax": "+1-925-924-9600" }, "payment_gateways": [ { "configured": true, "additional_field1": "standard", "gateway_name": "paypal" } ], "payment_options": { "configured": true, "additional_field1": "standard", "gateway_name": "paypal" } }, "page_context": { "page": 1, "per_page": 200, "has_more_page": false, "report_name": "Recurring Invoices", "applied_filter": "Status.All", "sort_column": "created_time", "sort_order": "D" } } }

    ARGUMENTS

    recurrence_name
    Required
    Unique name for the recurring profile given by the user. Max-length [100]
    reference_number
    Optional
    The Order number of the Recurring Invoice.
    customer_id
    Required
    Customer ID of the customer for whom the recurring invoice is raised.
    contact_persons
    Optional
    Contact Persons associated with the recurring invoice.
    place_of_supply
    India Edition and GCC Editions only.
    Optional
    Place where the goods/services are supplied to. (If not given, place of contact given for the contact will be taken)
    Supported codes for UAE emirates are :
    Abu Dhabi - AB,
    Ajman - AJ,
    Dubai - DU,
    Fujairah - FU,
    Ras al-Khaimah - RA,
    Sharjah - SH,
    Umm al-Quwain - UM
    Supported codes for the GCC countries are :
    United Arab Emirates - AE,
    Saudi Arabia - SA,
    Bahrain - BH,
    Kuwait - KW,
    Oman - OM,
    Qatar - QA.
    vat_treatment
    Optional
    Enter vat treatment
    gst_treatment
    India Edition only.
    Optional
    Choose whether the contact is GST registered/unregistered/consumer/overseas. Allowed values are business_gst , business_none , overseas , consumer .
    tax_treatment
    GCC Editions only
    Optional
    Choose whether the vat treatment for the contact falls under: vat_registered,vat_not_registered,gcc_vat_not_registered,gcc_vat_registered,non_gcc.
    dz_vat_registered and dz_vat_not_registered supported only for UAE.
    gst_no
    India Edition only.
    Optional
    15 digit GST identification number of the customer.
    start_date
    Optional
    The date on which the recurring invoice starts.
    end_date
    Optional
    The date on which the recurring invoice expires.
    recurrence_frequency
    Required
    The frequency of time interval at which the invoice is to be generated.
    repeat_every
    Optional
    The period between every recurrency frequency.
    Optional
    Line items of an invoice.
    line_item_id
    Optional
    The line item id
    quantity
    Optional
    Quantity of the item included.
    name
    Optional
    The name of the line item. max-length [100]
    item_total
    Optional
    Total rate raised by this item. This would be the multiplicative product of item price and quantity.
    product_type
    Optional
    Enter goods/services
    hsn_or_sac
    India Edition only
    Optional
    Add HSN/SAC code for your goods/services
    warehouse_id
    Optional
    Enter ID of the warehouse
    tax_id
    Optional
    ID of the tax or tax group associated to the recurring invoice.
    tax_treatment_code
    GCC Editions only
    Optional
    Specify reason for using out of scope.
    Supported values for UAE are uae_same_tax_group, uae_reimbursed_expense and uae_others.
    Supported values for Bahrain are bahrain_same_tax_group, bahrain_transfer_of_concern, bahrain_disbursement, bahrain_head_to_branch_transaction and bahrain_others.
    Supported values for Saudi Arabia are ksa_pvt_health, ksa_pvt_edu and ksa_house_sales.
    tax_id
    Optional
    ID of the tax or tax group associated to the recurring invoice.
    email
    Optional
    Email address of the customer.
    billing_address
    Optional
    address
    Optional
    Billing address for the invoice
    street2
    Optional
    city
    Optional
    City of the customer’s billing address.
    state
    Optional
    State of the customer’s billing address.
    zip
    Optional
    Zip code of the customer’s billing address.
    country
    Optional
    Country of the customer’s billing address.
    fax
    Optional
    Customer's fax number.
    shipping_address
    Optional
    address
    Optional
    Billing address for the invoice
    city
    Optional
    City of the customer’s billing address.
    state
    Optional
    State of the customer’s billing address.
    zip
    Optional
    Zip code of the customer’s billing address.
    country
    Optional
    Country of the customer’s billing address.
    fax
    Optional
    Customer's fax number.
    payment_gateways
    Optional
    configured
    Optional
    Boolean check to see if a payment gateway ahs been configured
    additional_field1
    Optional
    Paypal payment method. Allowed Values: standard and adaptive
    gateway_name
    Optional
    Name of the payment gateway associated with the invoice. E.g. paypal, stripe.Allowed Values: paypal, authorize_net, payflow_pro, stripe, 2checkout and braintree
    avatax_use_code
    Avalara integration only
    Optional
    Used to group like customers for exemption purposes. It is a custom value that links customers to a tax rule. Select from Avalara [standard codes][1] or enter a custom code. Max-length [25]
    avatax_exempt_no
    Avalara integration only
    Optional
    Exemption certificate number of the customer. Max-length [25]
    template_id
    Optional
    Unique ID of the recurring invoice template.
    payment_terms
    Optional
    Payment terms in days. E.g: 15,30,60. Invoice due date will be calculated based on this.
    payment_terms_label
    Optional
    Used to overridethe default payment terms label. Default value for 15 days is "Next 15 days".
    tax_authority_id
    US edition Only
    Optional
    Unique ID of the tax authority. Tax authority depends on the location of the customer. For example, if the customer is located in NY, then the tax authority is NY tax authority.
    tax_exemption_id
    Applicable for India, US, AU and CA Editions Only
    Optional
    Unique ID of the tax exemption.
    vat_treatment
    Optional
    Enter vat treatment
    exchange_rate
    Optional
    Exchange rate for the currency associated with the customer.
    payment_options
    Optional
    payment_gateways
    Optional
    configured
    Optional
    Boolean check to see if a payment gateway ahs been configured
    additional_field1
    Optional
    Paypal payment method. Allowed Values: standard and adaptive
    gateway_name
    Optional
    Name of the payment gateway associated with the invoice. E.g. paypal, stripe.Allowed Values: paypal, authorize_net, payflow_pro, stripe, 2checkout and braintree
    gateway_name
    Optional
    Name of the payment gateway associated with the invoice. E.g. paypal, stripe.Allowed Values: paypal, authorize_net, payflow_pro, stripe, 2checkout and braintree
    additional_field1
    Optional
    Paypal payment method. Allowed Values: standard and adaptive
    discount
    Optional
    Discount applied to the invoice. It can be either in % or in amount. E.g: 12.5% or 190.
    is_discount_before_tax
    Optional
    Used to specify how the discount has to applied. Either before or after the calculation of tax.
    discount_type
    Optional
    How the discount is specified. Allowed values: entity_level and item_level.
    is_inclusive_tax
    Not applicable for US and CA editions.
    Optional
    Used to specify whether the line item rates are inclusive or exclusive of tax.
    item_id
    Optional
    Unique string generated for the item for which invoice is to be sent.
    name
    Optional
    The name of the line item. max-length [100]
    description
    Optional
    A small description about the item. Max-length [2000]
    rate
    Optional
    Rate of the line item.
    quantity
    Optional
    Quantity of the item included.
    unit
    Optional
    Unit of the line item. E.g: kgs, Nos.
    avatax_tax_code
    Optional
    A tax code is a unique label used to group items together.
    salesperson_name
    Applicable for US, AU and CA Editions Only
    Optional
    Name of the sales person
    shipping_charge
    Optional
    Shipping charges applied to the invoice.
    adjustment
    Optional
    Adjustments made to the invoice.
    adjustment_description
    Optional
    Customize the adjustment description. E.g: Rounding off.

    Update Recurring Invoice

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

    PUT /recurringinvoices/{recurring_invoice_id}

    Request Example

      
    $ curl https://books.zoho.com/api/v3/recurringinvoices/{recurring_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="{ "recurrence_name": "MonthlyInvoice", "reference_number": "12314", "customer_id": "903000000000099", "contact_persons": [ "90300000065322" ], "start_date": "2016-06-12", "end_date": "2017-06-12", "recurrence_frequency": "weeks", "repeat_every": 2, "place_of_supply": "TN", "gst_treatment": "business_gst", "tax_treatment": "vat_registered", "gst_no": "22AAAAA0000A1Z5", "line_items": [ { "item_id": "90300000081501", "name": "Hard Drive", "description": "prorated amount for items", "rate": 0, "quantity": 1, "discount": "30%", "tax_id": "903000000000356", "tax_exemption_id": "903000006345", "tax_treatment_code": "uae_others", "avatax_tax_code": " ", "item_total": 100, "product_type": "goods", "hsn_or_sac": 80540, "warehouse_id": "" } ], "email": "[email protected]", "payment_gateways": [ { "configured": true, "additional_field1": "standard", "gateway_name": "paypal" } ], "tax_id": "903000000000356", "tax_authority_id": "903000006345", "tax_exemption_id": "903000006345" }"'

    Response Example

      
    HTTP/1.1 200 OK Content-Type:application/json;charset=UTF-8 { "code": 0, "message": "success", "recurring_invoice": { "recurring_invoice_id": "90300000072369", "recurrence_name": "MonthlyInvoice", "reference_number": "12314", "customer_name": "Sujin Kumar", "is_pre_gst": false, "gst_no": "22AAAAA0000A1Z5", "gst_treatment": "business_gst", "tax_treatment": "vat_registered", "place_of_supply": "TN", "customer_id": "903000000000099", "currency_id": "982000000000190", "currency_code": "USD", "start_date": "2016-06-12", "end_date": "2017-06-12", "last_sent_date": "2016-06-12", "next_invoice_date": "2016-06-17", "line_items": [ { "line_item_id": "982000000567021", "quantity": 1, "name": "Hard Drive", "item_total": 100, "sku": "LEV-JN-SL-36-GN", "product_type": "goods", "warehouse_id": "", "warehouses": [ { "warehouse_id": "", "warehouse_stock_on_hand": "" } ], "tax_id": "903000000000356", "tax_treatment_code": "uae_others" } ], "billing_address": { "address": "4900 Hopyard Rd, Suite 310", "street2": "McMillan Avenue", "city": "Pleasanton", "state": "CA", "zip": "94588", "country": "U.S.A", "fax": "+1-925-924-9600" }, "shipping_address": { "address": "4900 Hopyard Rd, Suite 310", "city": "Pleasanton", "state": "CA", "zip": "94588", "country": "U.S.A", "fax": "+1-925-924-9600" }, "payment_gateways": [ { "configured": true, "additional_field1": "standard", "gateway_name": "paypal" } ], "payment_options": { "configured": true, "additional_field1": "standard", "gateway_name": "paypal" } } }

    ARGUMENTS

    recurrence_name
    Required
    Unique name for the recurring profile given by the user. Max-length [100]
    reference_number
    Optional
    The Order number of the Recurring Invoice.
    customer_id
    Required
    Customer ID of the customer for whom the recurring invoice is raised.
    contact_persons
    Optional
    Contact Persons associated with the recurring invoice.
    start_date
    Optional
    The date on which the recurring invoice starts.
    end_date
    Optional
    The date on which the recurring invoice expires.
    recurrence_frequency
    Required
    The frequency of time interval at which the invoice is to be generated.
    repeat_every
    Optional
    The period between every recurrency frequency.
    place_of_supply
    India Edition and GCC Editions only.
    Optional
    Place where the goods/services are supplied to. (If not given, place of contact given for the contact will be taken)
    Supported codes for UAE emirates are :
    Abu Dhabi - AB,
    Ajman - AJ,
    Dubai - DU,
    Fujairah - FU,
    Ras al-Khaimah - RA,
    Sharjah - SH,
    Umm al-Quwain - UM
    Supported codes for the GCC countries are :
    United Arab Emirates - AE,
    Saudi Arabia - SA,
    Bahrain - BH,
    Kuwait - KW,
    Oman - OM,
    Qatar - QA.
    vat_treatment
    Optional
    Enter vat treatment
    gst_treatment
    India Edition only.
    Optional
    Choose whether the contact is GST registered/unregistered/consumer/overseas. Allowed values are business_gst , business_none , overseas , consumer .
    tax_treatment
    GCC Editions only
    Optional
    Choose whether the vat treatment for the contact falls under: vat_registered,vat_not_registered,gcc_vat_not_registered,gcc_vat_registered,non_gcc.
    dz_vat_registered and dz_vat_not_registered supported only for UAE.
    gst_no
    India Edition only.
    Optional
    15 digit GST identification number of the customer.
    Optional
    Line items of an invoice.
    item_id
    Optional
    Unique string generated for the item for which invoice is to be sent.
    name
    Optional
    The name of the line item. max-length [100]
    description
    Optional
    A small description about the item. Max-length [2000]
    rate
    Optional
    Rate of the line item.
    quantity
    Optional
    Quantity of the item included.
    discount
    Optional
    Discount applied to the invoice. It can be either in % or in amount. E.g: 12.5% or 190.
    tax_id
    Optional
    ID of the tax or tax group associated to the recurring invoice.
    tax_exemption_id
    Applicable for India, US, AU and CA Editions Only
    Optional
    Unique ID of the tax exemption.
    tax_treatment_code
    GCC Editions only
    Optional
    Specify reason for using out of scope.
    Supported values for UAE are uae_same_tax_group, uae_reimbursed_expense and uae_others.
    Supported values for Bahrain are bahrain_same_tax_group, bahrain_transfer_of_concern, bahrain_disbursement, bahrain_head_to_branch_transaction and bahrain_others.
    Supported values for Saudi Arabia are ksa_pvt_health, ksa_pvt_edu and ksa_house_sales.
    avatax_tax_code
    Optional
    A tax code is a unique label used to group items together.
    avatax_use_code
    Avalara integration only
    Optional
    Used to group like customers for exemption purposes. It is a custom value that links customers to a tax rule. Select from Avalara [standard codes][1] or enter a custom code. Max-length [25]
    item_total
    Optional
    Total rate raised by this item. This would be the multiplicative product of item price and quantity.
    product_type
    Optional
    Enter goods/services
    hsn_or_sac
    India Edition only
    Optional
    Add HSN/SAC code for your goods/services
    warehouse_id
    Optional
    Enter ID of the warehouse
    email
    Optional
    Email address of the customer.
    payment_gateways
    Optional
    configured
    Optional
    Boolean check to see if a payment gateway ahs been configured
    additional_field1
    Optional
    Paypal payment method. Allowed Values: standard and adaptive
    gateway_name
    Optional
    Name of the payment gateway associated with the invoice. E.g. paypal, stripe.Allowed Values: paypal, authorize_net, payflow_pro, stripe, 2checkout and braintree
    tax_id
    Optional
    ID of the tax or tax group associated to the recurring invoice.
    tax_authority_id
    US edition Only
    Optional
    Unique ID of the tax authority. Tax authority depends on the location of the customer. For example, if the customer is located in NY, then the tax authority is NY tax authority.
    tax_exemption_id
    Applicable for India, US, AU and CA Editions Only
    Optional
    Unique ID of the tax exemption.
    vat_treatment
    Optional
    Enter vat treatment
    avatax_use_code
    Avalara integration only
    Optional
    Used to group like customers for exemption purposes. It is a custom value that links customers to a tax rule. Select from Avalara [standard codes][1] or enter a custom code. Max-length [25]
    avatax_exempt_no
    Avalara integration only
    Optional
    Exemption certificate number of the customer. Max-length [25]

    Get a Recurring Invoice

    Get the details of a recurring invoice.
    oauthscope : ZohoBooks.invoices.READ

    get /recurringinvoices/:recurring_invoice_id

    Request Example

      
    $ curl https://books.zoho.com/api/v3/recurringinvoices/:recurring_invoice_id?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": "Details of a recurring invoice is displayed successfully.", "recurring_invoice": { "recurring_invoice": { "recurring_invoice_id": "90300000072369", "recurrence_name": "MonthlyInvoice", "reference_number": "12314", "customer_name": "Sujin Kumar", "customer_id": "903000000000099", "company_name": "ABC Studios", "is_pre_gst": false, "gst_no": "22AAAAA0000A1Z5", "gst_treatment": "business_gst", "tax_treatment": "vat_registered", "place_of_supply": "TN", "customer_email": "[email protected]", "customer_mobile_phone": 9876543210, "customer_phone": "012-12345678", "photo_url": "https://secure.gravatar.com/avatar/xxxxxxxxxx?&d=mm", "currency_id": "982000000000190", "currency_code": "USD", "start_date": "2016-06-12", "end_date": "2017-06-12", "last_sent_date": "2016-06-12", "next_invoice_date": "2016-06-17", "line_items": [ { "line_item_id": "982000000567021", "quantity": 1, "name": "Hard Drive", "item_total": 100, "sku": "LEV-JN-SL-36-GN", "product_type": "goods", "warehouse_id": "", "warehouses": [ { "warehouse_id": "", "warehouse_stock_on_hand": "" } ], "tax_id": "903000000000356", "tax_treatment_code": "uae_others" } ], "paid_invoices_total": 100, "unpaid_invoices_balance": 100, "billing_address": { "address": "4900 Hopyard Rd, Suite 310", "street2": "McMillan Avenue", "city": "Pleasanton", "state": "CA", "zip": "94588", "country": "U.S.A", "fax": "+1-925-924-9600" }, "shipping_address": { "address": "4900 Hopyard Rd, Suite 310", "city": "Pleasanton", "state": "CA", "zip": "94588", "country": "U.S.A", "fax": "+1-925-924-9600" }, "payment_gateways": [ { "configured": true, "additional_field1": "standard", "gateway_name": "paypal" } ], "payment_options": { "configured": true, "additional_field1": "standard", "gateway_name": "paypal" } }, "page_context": { "page": 1, "per_page": 200, "has_more_page": false, "report_name": "Recurring Invoices", "applied_filter": "Status.All", "sort_column": "created_time", "sort_order": "D" } } }

    List all Recurring Invoice

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

    get /recurringinvoices

    Request Example

      
    $ curl https://books.zoho.com/api/v3/recurringinvoices?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": "Details of a recurring invoice is displayed successfully.", "recurring_invoice": [ { "recurring_invoices": [ { "recurring_invoice_id": "90300000072369", "recurrence_name": "MonthlyInvoice", "customer_name": "Sujin Kumar", "customer_id": "903000000000099", "currency_id": "982000000000190", "currency_code": "USD", "start_date": "2016-06-12", "end_date": "2017-06-12", "last_sent_date": "2016-06-12", "next_invoice_date": "2016-06-17", "line_items": [ { "line_item_id": "982000000567021", "quantity": 1, "name": "Hard Drive", "item_total": 100 } ], "billing_address": { "address": "4900 Hopyard Rd, Suite 310", "street2": "McMillan Avenue", "city": "Pleasanton", "state": "CA", "zip": "94588", "country": "U.S.A", "fax": "+1-925-924-9600" }, "shipping_address": { "address": "4900 Hopyard Rd, Suite 310", "city": "Pleasanton", "state": "CA", "zip": "94588", "country": "U.S.A", "fax": "+1-925-924-9600" }, "payment_gateways": [ { "configured": true, "additional_field1": "standard", "gateway_name": "paypal" } ], "payment_options": { "configured": true, "additional_field1": "standard", "gateway_name": "paypal" } } ], "page_context": { "page": 1, "per_page": 200, "has_more_page": false, "report_name": "Recurring Invoices", "applied_filter": "Status.All", "sort_column": "created_time", "sort_order": "D" } }, {...}, {...} ] }

    Query Params

    recurrence_name
    Optional
    Unique name for the recurring profile given by the user. Max-length [100]
    item_name
    Optional
    Search recurring invoices by item name. Variants: item_name_startswith and profileitemname_contains.
    item_description
    Optional
    Search recurring invoices by item description. Variants: item_description_startswith and item_description_contains.
    customer_name
    Optional
    Name of the customer to whom the recurring invoice is raised.
    line_item_id
    Optional
    The line item id
    item_id
    Optional
    Unique string generated for the item for which invoice is to be sent.
    tax_id
    Optional
    ID of the tax or tax group associated to the recurring invoice.
    notes
    Optional
    A short note for the recurring invoice.
    start_date
    Optional
    The date on which the recurring invoice starts.
    end_date
    Optional
    The date on which the recurring invoice expires.
    customer_id
    Optional
    Customer ID of the customer for whom the recurring invoice is raised.
    status
    Optional
    Status of the recurring invoice. This can be active, stopped or expired.
    filter_by
    Optional
    Filter Recurring invoices by any status or payment expected date.Allowed Values: Status.All, Status.Active, Status.Stopped, Status.Expired
    search_text
    Optional
    Search invoices by invoice number or purchase order or customer name. Max-length [100]
    sort_column
    Optional

    Delete a Recurring Invoice

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

    delete /recurringinvoices/:recurring_invoice_id

    Request Example

      
    $ curl https://books.zoho.com/api/v3/recurringinvoices/:recurring_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" -F 'JSONString="{ "recurring_invoice_id": "90300000072369" }"'

    Response Example

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

    ARGUMENTS

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

    Stop a Recurring Invoice

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

    post /recurringinvoices/:recurring_invoice_id/status/stop

    Request Example

      
    $ curl https://books.zoho.com/api/v3/recurringinvoices/:recurring_invoice_id/status/stop?organization_id=10234695 -X post -H "Authorization: Zoho-oauthtoken 1000.41d9f2cfbd1b7a8f9e314b7aff7bc2d1.8fcc9810810a216793f385b9dd6e125f" -H "Content-Type: application/x-www-form-urlencoded;charset=UTF-8" -F 'JSONString="{ "recurring_invoice_id": "90300000072369" }"'

    Response Example

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

    ARGUMENTS

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

    Resume a Recurring Invoice

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

    post /recurringinvoices/:recurring_invoice_id/status/resume

    Request Example

      
    $ curl https://books.zoho.com/api/v3/recurringinvoices/:recurring_invoice_id/status/resume?organization_id=10234695 -X post -H "Authorization: Zoho-oauthtoken 1000.41d9f2cfbd1b7a8f9e314b7aff7bc2d1.8fcc9810810a216793f385b9dd6e125f" -H "Content-Type: application/x-www-form-urlencoded;charset=UTF-8" -F 'JSONString="{ "recurring_invoice_id": "90300000072369" }"'

    Response Example

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

    ARGUMENTS

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

    Update Recurring Invoice template

    Update the pdf template associated with the recurring invoice.
    oauthscope : ZohoBooks.invoices.UPDATE

    put /recurringinvoices/:recurring_invoice_id/templates/:template_id

    Request Example

      
    $ curl https://books.zoho.com/api/v3/recurringinvoices/:recurring_invoice_id/templates/:template_id?organization_id=10234695 -X put -H "Authorization: Zoho-oauthtoken 1000.41d9f2cfbd1b7a8f9e314b7aff7bc2d1.8fcc9810810a216793f385b9dd6e125f" -H "Content-Type: application/x-www-form-urlencoded;charset=UTF-8" -F 'JSONString="{ "recurring_invoice_id": "90300000072369", "template_id": "90300043563547" }"'

    Response Example

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

    ARGUMENTS

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

    List Recurring Invoice History

    Get the complete history and comments of a recurring invoice.
    oauthscope : ZohoBooks.invoices.READ

    get /recurringinvoices/:recurring_invoice_id/comments

    Request Example

      
    $ curl https://books.zoho.com/api/v3/recurringinvoices/:recurring_invoice_id/comments?organization_id=10234695 -X get -H "Authorization: Zoho-oauthtoken 1000.41d9f2cfbd1b7a8f9e314b7aff7bc2d1.8fcc9810810a216793f385b9dd6e125f" -H "Content-Type: application/x-www-form-urlencoded;charset=UTF-8" -F 'JSONString="{ "recurring_invoice_id": "90300000072369" }"'

    Response Example

      
    HTTP/1.1 200 OK Content-Type:application/json;charset=UTF-8 { "code": 0, "message": "The complete history and comments of a recurring invoice are displayed successfully.", "recurring_invoice": [ { "comments": [ { "comment_id": "982000000567019", "recurring_invoice_id": "90300000072369", "comment_description": "Recurring Invoice created", "commented_by_id": "982000000554041", "commented_by": "Sujin Kumar", "comment_type": "system", "operation_type": "Added", "date": "2016-06-05", "date_description": "yesterday", "time": "2:02 AM", "transaction_id": "903000002072369", "transaction_type": "estimate" } ] }, {...}, {...} ] }

    ARGUMENTS

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

    Credit-Notes

    Credit notes are created when a refund is to be made to a customer. A credit note object allows you to keep track of all credit note related information.

    Example

    { "creditnote_id": "90300000072369", "creditnote_number": "CN-29", "ignore_auto_number_generation": false, "date": "2016-06-05", "status": "draft", "customer_id": "903000000000099", "customer_name": "Bowman Furniture", "custom_fields": [ {} ], "reference_number": "INV-384", "email": "[email protected]", "total": 450, "balance": 10, "line_items": [ { "item_id": "90300000081501", "line_item_id": 903000006245, "account_id": "903000000000388", "name": "Basic Monthly", "description": "prorated amount for items", "item_order": 0, "rate": 0, "quantity": 1, "unit": "kgs", "discount": 10, "tax_id": "903000000000356", "tax_exemption_id": "903000006345", "tax_exemption_code": "GST FREE", "tax_treatment_code": "uae_others", "product_type": "goods", "hsn_or_sac": 80540, "item_custom_fields": [ {} ], "warehouse_id": 90300000072378 } ], "invoices": [ {} ], "currency_code": "USD", "currency_symbol": "$", "created_time": "2016-06-05T02:30:08-0700", "updated_time": "2016-06-05T02:30:08-0700", "template_id": "90300000001336", "template_name": "Standard Template" }

    Attribute

    creditnote_id
    string
    Unique ID of the credit note generated by the server.
    creditnote_number
    string
    Unique number generated (starts with CN) which will be displayed in the interface and credit notes. Max-Length [100]
    ignore_auto_number_generation
    boolean
    Set to true if you need to provide your own credit note number.
    date
    string
    The date on which credit note is raised. Format [yyyy-mm-dd]
    status
    string
    Status of the credit note. This can be open, closed or void.
    customer_id
    string
    Customer ID of the customer for whom the credit note is raised.
    customer_name
    string
    Name of the customer to whom the credit note is raised. Max-Length [100]
    custom_fields
    list
    Additional fields for the Credit-Notes.
    reference_number
    string
    Reference number generated for the payment. A string of your choice can also be used as the reference number. Max-Length [100]
    email
    string
    Email address of the customer.
    total
    double
    Total credits raised in this credit note.
    balance
    double
    The unapplied credits.
    list
    Line items of a credit note.
    item_id
    string
    Unique string generated for the item to which a refund is to be made.
    line_item_id
    string
    Search credit notes by credit note line item id.
    account_id
    string
    Unique ID to denote the account.
    name
    string
    Name of the credit
    description
    required
    A small description about the item.
    item_order
    integer
    Enter order of the item
    rate
    double
    Rate of the line item.
    quantity
    required
    Quantity of the item included.
    unit
    string
    Unit of the line item. E.g: kgs, Nos.
    discount
    double
    Enter discount percentage.
    tax_id
    string
    Unique to denote the tax associate dto the creditnote
    tax_exemption_id
    Applicable for Inida, US, AU and CA Editions Only
    string
    Unique ID of the tax exemption.
    tax_exemption_code
    Applicable for Inida, US, AU and CA Editions Only
    string
    Unique code of the tax exemption.
    tax_treatment_code
    GCC Editions only
    string
    Specify reason for using out of scope.
    Supported values for UAE are uae_same_tax_group, uae_reimbursed_expense and uae_others.
    Supported values for Bahrain are bahrain_same_tax_group, bahrain_transfer_of_concern, bahrain_disbursement, bahrain_head_to_branch_transaction and bahrain_others.
    Supported values for Saudi Arabia are ksa_pvt_health, ksa_pvt_edu and ksa_house_sales.
    avatax_use_code
    Avalara integration only
    string
    Used to group like customers for exemption purposes. It is a custom value that links customers to a tax rule. Select from Avalara [standard codes][1] or enter a custom code. Max-length [25]
    avatax_tax_code
    Avalara integration only
    string
    A tax code is a unique label used to group Items (products, services, or charges) together. Refer the [link][2] for more deails. Max-length [25]
    product_type
    string
    Enter goods/services
    hsn_or_sac
    India Edition only
    string
    Add HSN/SAC code for your goods/services
    item_custom_fields
    list
    Enter custom field information
    warehouse_id
    string
    ID of the warehouse
    serial_numbers
    string
    Enter serial number
    list
    List of invoices for which the credit note has been raised. This contains invoice_id and amount.
    currency_code
    string
    Customer's currency code. This currency code is used in credit notes.
    currency_symbol
    string
    Customer's currency symbol.
    created_time
    string
    Time at which the credit note was created.
    updated_time
    string
    Time at which the credit note details were last updated.
    template_id
    string
    Unique ID of the creditnote template
    template_name
    string
    Name of the default template of the creditnote.

    Create a credit note

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

    POST /creditnotes

    Request Example

      
    $ curl https://books.zoho.com/api/v3/creditnotes?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", "contact_persons": [ "903000006532" ], "date": "2016-06-05", "is_draft": true, "exchange_rate": "5.5", "line_items": [ { "item_id": "90300000081501", "description": "prorated amount for items", "code": "basic-monthly", "name": "Basic Monthly", "type": 1, "account_id": "903000000000388", "account_name": "Sales", "quantity": 1, "tax_id": "903000000000356", "tax_treatment_code": "uae_others", "product_type": "goods", "warehouse_id": 90300000072378 } ], "creditnote_number": "CN-29", "gst_treatment": "business_gst", "tax_treatment": "vat_registered", "gst_no": "22AAAAA0000A1Z5", "place_of_supply": "TN", "ignore_auto_number_generation": false, "reference_number": "INV-384", "custom_fields": [ {} ], "notes": "Offer for the referral", "terms": "", "template_id": "90300000001336", "tax_id": "903000000000356", "tax_authority_id": "903000006345", "tax_exemption_id": "903000006345", "is_inclusive_tax": "fasle" }"'

    Response Example

      
    HTTP/1.1 201 Created Content-Type:application/json;charset=UTF-8 { "code": 0, "message": "The credit note has been created.", "credit_note": { "creditnote": { "creditnote_id": "90300000072369", "creditnote_number": "CN-29", "date": "2016-06-05", "is_pre_gst": true, "place_of_supply": "TN", "gst_no": "22AAAAA0000A1Z5", "gst_treatment": "business_gst", "tax_treatment": "vat_registered", "status": "draft", "customer_id": "903000000000099", "customer_name": "Bowman Furniture", "custom_fields": [ { "index": 1, "value": 129890, "label": "label", "data_type": "text" } ], "reference_number": "INV-384", "email": "[email protected]", "total": 450, "balance": 10, "line_items": [ { "item_id": "90300000081501", "line_item_id": 903000006245, "account_id": "903000000000388", "name": "Basic Monthly", "description": "prorated amount for items", "item_order": 0, "rate": 0, "quantity": 1, "unit": "kgs", "discount": 10, "tax_id": "903000000000356", "tax_exemption_id": "903000006345", "tax_exemption_code": "GST FREE", "tax_treatment_code": "uae_others", "product_type": "goods", "hsn_or_sac": 80540, "item_custom_fields": [ {...} ], "warehouse_id": 90300000072378 } ], "invoices": [ { "invoice_id": "90300000079426", "invoice_number": "INV-384", "amount": 450 } ], "taxes": [ { "tax_id": "903000000000356", "tax_name": "Basic Tax", "tax_amount": "2.50" } ], "currency_code": "USD", "currency_symbol": "$", "billing_address": { "address": "4900 Hopyard Rd, Suite 310", "street2": "McMillan Avenue", "city": "Pleasanton", "state": "CA", "zip": 94588, "country": "U.S.A", "fax": "+1-925-924-9600" }, "shipping_address": { "address": "4900 Hopyard Rd, Suite 310", "street2": "McMillan Avenue", "city": "Pleasanton", "state": "CA", "zip": 94588, "country": "U.S.A", "fax": "+1-925-924-9600" }, "created_time": "2016-06-05T02:30:08-0700", "updated_time": "2016-06-05T02:30:08-0700", "template_id": "90300000001336", "template_name": "Standard Template", "notes": "Offer for the referral", "terms": "" } } }

    ARGUMENTS

    customer_id
    Required
    Customer ID of the customer for whom the credit note is raised.
    contact_persons
    Optional
    Contact Persons associated with the credit note.
    date
    Required
    The date on which credit note is raised. Format [yyyy-mm-dd]
    is_draft
    Optional
    Set to true if credit note has to be created in draft status.
    exchange_rate
    Optional
    Exchange rate for the currency associated with the customer.
    Required
    Line items of a credit note.
    item_id
    Optional
    Unique string generated for the item to which a refund is to be made.
    description
    Optional
    A small description about the item.
    code
    Optional
    Unique code for the creditnote line item.
    name
    Optional
    Name of the credit
    type
    Optional
    Type of the creditnote line item.
    account_id
    Optional
    Unique ID to denote the account.
    account_name
    Optional
    Name of the account.
    quantity
    Optional
    Quantity of the item included.
    tax_id
    Optional
    Unique to denote the tax associate dto the creditnote
    tax_treatment_code
    GCC Editions only
    Optional
    Specify reason for using out of scope.
    Supported values for UAE are uae_same_tax_group, uae_reimbursed_expense and uae_others.
    Supported values for Bahrain are bahrain_same_tax_group, bahrain_transfer_of_concern, bahrain_disbursement, bahrain_head_to_branch_transaction and bahrain_others.
    Supported values for Saudi Arabia are ksa_pvt_health, ksa_pvt_edu and ksa_house_sales.
    product_type
    Optional
    Enter goods/services
    serial_numbers
    Optional
    Enter serial number
    warehouse_id
    Optional
    ID of the warehouse
    warehouse_name
    Optional
    Name of the warehouse.
    creditnote_number
    Required
    Unique number generated (starts with CN) which will be displayed in the interface and credit notes. Max-Length [100]
    gst_treatment
    India Edition only
    Optional
    Choose whether the contact is GST registered/unregistered/consumer/overseas. Allowed values are business_gst , business_none , overseas , consumer .
    tax_treatment
    GCC Editions only
    Optional
    VAT treatment for the credit note .Choose whether the contact falls under: vat_registered,vat_not_registered,gcc_vat_not_registered,gcc_vat_registered,non_gcc.
    dz_vat_registered and dz_vat_not_registered supported only for UAE.
    gst_no
    India Edition only
    Optional
    15 digit GST identification number of the customer.
    place_of_supply
    India Edition and GCC Editions only.
    Optional
    Place where the goods/services are supplied to. (If not given, place of contact given for the contact will be taken)
    Supported codes for UAE emirates are :
    Abu Dhabi - AB,
    Ajman - AJ,
    Dubai - DU,
    Fujairah - FU,
    Ras al-Khaimah - RA,
    Sharjah - SH,
    Umm al-Quwain - UM
    Supported codes for the GCC countries are :
    United Arab Emirates - AE,
    Saudi Arabia - SA,
    Bahrain - BH,
    Kuwait - KW,
    Oman - OM,
    Qatar - QA.
    ignore_auto_number_generation
    Optional
    Set to true if you need to provide your own credit note number.
    reference_number
    Optional
    Reference number generated for the payment. A string of your choice can also be used as the reference number. Max-Length [100]
    custom_fields
    Optional
    Additional fields for the Credit-Notes.
    notes
    Optional
    A short note for the credit note. Max-length [5000]
    terms
    Optional
    Terms & condition to be displayed in the credit note. Max-length [10000]
    template_id
    Optional
    Unique ID of the creditnote template
    tax_id
    Optional
    Unique to denote the tax associate dto the creditnote
    tax_authority_id
    US edition Only
    Optional
    Unique ID of the tax authority. Tax authority depends on the location of the customer. For example, if the customer is located in NY, then the tax authority is NY tax authority.
    tax_exemption_id
    Applicable for Inida, US, AU and CA Editions Only
    Optional
    Unique ID of the tax exemption.
    avatax_use_code
    Avalara integration only
    Optional
    Used to group like customers for exemption purposes. It is a custom value that links customers to a tax rule. Select from Avalara [standard codes][1] or enter a custom code. Max-length [25]
    avatax_exempt_no
    Avalara integration only
    Optional
    Exemption certificate number of the customer. Max-length [25]
    vat_treatment
    Optional
    Enter vat treatment
    is_inclusive_tax
    Not applicable for US and CA editions.
    Optional
    Used to specify whether the line item rates are inclusive or exclusive of tax.
    avatax_tax_code
    Avalara integration only
    Optional
    A tax code is a unique label used to group Items (products, services, or charges) together. Refer the [link][2] for more deails. Max-length [25]

    Query Params

    invoice_id
    Optional
    Invoice ID of the required invoice.
    ignore_auto_number_generation
    Optional
    Set to true if you need to provide your own credit note number.

    Update a credit note

    Details of an existing creditnote.
    oauthscope : ZohoBooks.creditnotes.UPDATE

    PUT /creditnotes/{:creditnote_id}

    Request Example

      
    $ curl https://books.zoho.com/api/v3/creditnotes/{:creditnote_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", "contact_persons": [ "903000006532" ], "date": "2016-06-05", "is_draft": true, "exchange_rate": "5.5", "line_items": [ { "item_id": "90300000081501", "line_item_id": 903000006245, "account_id": "903000000000388", "name": "Basic Monthly", "description": "prorated amount for items", "item_order": 0, "rate": 0, "quantity": 1, "unit": "kgs", "discount": 10, "tax_id": "903000000000356", "tax_exemption_id": "903000006345", "tax_exemption_code": "GST FREE", "tax_treatment_code": "uae_others", "product_type": "goods", "hsn_or_sac": 80540, "item_custom_fields": [ {} ], "warehouse_id": 90300000072378 } ], "creditnote_number": "CN-29", "gst_treatment": "business_gst", "tax_treatment": "vat_registered", "gst_no": "22AAAAA0000A1Z5", "place_of_supply": "TN", "ignore_auto_number_generation": false, "reference_number": "INV-384", "custom_fields": [ {} ], "notes": "Offer for the referral", "terms": "", "template_id": "90300000001336", "tax_id": "903000000000356", "tax_authority_id": "903000006345", "tax_exemption_id": "903000006345", "is_inclusive_tax": "fasle", "item_id": "90300000081501", "account_id": "903000000000388", "name": "Basic Monthly", "description": "prorated amount for items", "unit": "kgs", "rate": 0, "quantity": 1 }"'

    Response Example

      
    HTTP/1.1 200 OK Content-Type:application/json;charset=UTF-8 { "code": 0, "message": "The credit note has been updated.", "credit_note": { "creditnote": { "creditnote_id": "90300000072369", "creditnote_number": "CN-29", "date": "2016-06-05", "is_pre_gst": true, "place_of_supply": "TN", "gst_no": "22AAAAA0000A1Z5", "gst_treatment": "business_gst", "tax_treatment": "vat_registered", "status": "draft", "customer_id": "903000000000099", "customer_name": "Bowman Furniture", "custom_fields": [ { "index": 1, "value": 129890, "label": "label", "data_type": "text" } ], "reference_number": "INV-384", "email": "[email protected]", "total": 450, "balance": 10, "line_items": [ { "item_id": "90300000081501", "description": "prorated amount for items", "code": "basic-monthly", "name": "Basic Monthly", "type": 1, "account_id": "903000000000388", "account_name": "Sales", "quantity": 1, "tax_id": "903000000000356", "tax_treatment_code": "uae_others", "product_type": "goods", "warehouse_id": 90300000072378 } ], "invoices": [ { "invoice_id": "90300000079426", "invoice_number": "INV-384", "amount": 450 } ], "taxes": [ { "tax_id": "903000000000356", "tax_name": "Basic Tax", "tax_amount": "2.50" } ], "currency_code": "USD", "currency_symbol": "$", "billing_address": { "address": "4900 Hopyard Rd, Suite 310", "street2": "McMillan Avenue", "city": "Pleasanton", "state": "CA", "zip": 94588, "country": "U.S.A", "fax": "+1-925-924-9600", "attention": " " }, "shipping_address": { "address": "4900 Hopyard Rd, Suite 310", "street2": "McMillan Avenue", "city": "Pleasanton", "state": "CA", "zip": 94588, "country": "U.S.A", "fax": "+1-925-924-9600", "attention": " " }, "created_time": "2016-06-05T02:30:08-0700", "updated_time": "2016-06-05T02:30:08-0700", "template_id": "90300000001336", "template_name": "Standard Template", "notes": "Offer for the referral", "terms": "" } } }

    ARGUMENTS

    customer_id
    Required
    Customer ID of the customer for whom the credit note is raised.
    contact_persons
    Optional
    Contact Persons associated with the credit note.
    date
    Required
    The date on which credit note is raised. Format [yyyy-mm-dd]
    is_draft
    Optional
    Set to true if credit note has to be created in draft status.
    exchange_rate
    Optional
    Exchange rate for the currency associated with the customer.
    Required
    Line items of a credit note.
    item_id
    Optional
    Unique string generated for the item to which a refund is to be made.
    line_item_id
    Optional
    Search credit notes by credit note line item id.
    account_id
    Optional
    Unique ID to denote the account.
    name
    Optional
    Name of the credit
    description
    Optional
    A small description about the item.
    item_order
    Optional
    Enter order of the item
    rate
    Optional
    Rate of the line item.
    quantity
    Optional
    Quantity of the item included.
    unit
    Optional
    Unit of the line item. E.g: kgs, Nos.
    discount
    Optional
    Enter discount percentage.
    tax_id
    Optional
    Unique to denote the tax associate dto the creditnote
    tax_exemption_id
    Applicable for Inida, US, AU and CA Editions Only
    Optional
    Unique ID of the tax exemption.
    tax_exemption_code
    Applicable for Inida, US, AU and CA Editions Only
    Optional
    Unique code of the tax exemption.
    tax_treatment_code
    GCC Editions only
    Optional
    Specify reason for using out of scope.
    Supported values for UAE are uae_same_tax_group, uae_reimbursed_expense and uae_others.
    Supported values for Bahrain are bahrain_same_tax_group, bahrain_transfer_of_concern, bahrain_disbursement, bahrain_head_to_branch_transaction and bahrain_others.
    Supported values for Saudi Arabia are ksa_pvt_health, ksa_pvt_edu and ksa_house_sales.
    avatax_use_code
    Avalara integration only
    Optional
    Used to group like customers for exemption purposes. It is a custom value that links customers to a tax rule. Select from Avalara [standard codes][1] or enter a custom code. Max-length [25]
    avatax_tax_code
    Avalara integration only
    Optional
    A tax code is a unique label used to group Items (products, services, or charges) together. Refer the [link][2] for more deails. Max-length [25]
    product_type
    Optional
    Enter goods/services
    hsn_or_sac
    India Edition only
    Optional
    Add HSN/SAC code for your goods/services
    item_custom_fields
    Optional
    Enter custom field information
    warehouse_id
    Optional
    ID of the warehouse
    serial_numbers
    Optional
    Enter serial number
    creditnote_number
    Required
    Unique number generated (starts with CN) which will be displayed in the interface and credit notes. Max-Length [100]
    gst_treatment
    India Edition only
    Optional
    Choose whether the contact is GST registered/unregistered/consumer/overseas. Allowed values are business_gst , business_none , overseas , consumer .
    tax_treatment
    GCC Editions only
    Optional
    VAT treatment for the credit note .Choose whether the contact falls under: vat_registered,vat_not_registered,gcc_vat_not_registered,gcc_vat_registered,non_gcc.
    dz_vat_registered and dz_vat_not_registered supported only for UAE.
    gst_no
    India Edition only
    Optional
    15 digit GST identification number of the customer.
    place_of_supply
    India Edition and GCC Editions only.
    Optional
    Place where the goods/services are supplied to. (If not given, place of contact given for the contact will be taken)
    Supported codes for UAE emirates are :
    Abu Dhabi - AB,
    Ajman - AJ,
    Dubai - DU,
    Fujairah - FU,
    Ras al-Khaimah - RA,
    Sharjah - SH,
    Umm al-Quwain - UM
    Supported codes for the GCC countries are :
    United Arab Emirates - AE,
    Saudi Arabia - SA,
    Bahrain - BH,
    Kuwait - KW,
    Oman - OM,
    Qatar - QA.
    ignore_auto_number_generation
    Optional
    Set to true if you need to provide your own credit note number.
    reference_number
    Optional
    Reference number generated for the payment. A string of your choice can also be used as the reference number. Max-Length [100]
    custom_fields
    Optional
    Additional fields for the Credit-Notes.
    notes
    Optional
    A short note for the credit note. Max-length [5000]
    terms
    Optional
    Terms & condition to be displayed in the credit note. Max-length [10000]
    template_id
    Optional
    Unique ID of the creditnote template
    tax_id
    Optional
    Unique to denote the tax associate dto the creditnote
    tax_authority_id
    US edition Only
    Optional
    Unique ID of the tax authority. Tax authority depends on the location of the customer. For example, if the customer is located in NY, then the tax authority is NY tax authority.
    tax_exemption_id
    Applicable for Inida, US, AU and CA Editions Only
    Optional
    Unique ID of the tax exemption.
    avatax_use_code
    Avalara integration only
    Optional
    Used to group like customers for exemption purposes. It is a custom value that links customers to a tax rule. Select from Avalara [standard codes][1] or enter a custom code. Max-length [25]
    avatax_exempt_no
    Avalara integration only
    Optional
    Exemption certificate number of the customer. Max-length [25]
    vat_treatment
    Optional
    Enter vat treatment
    is_inclusive_tax
    Not applicable for US and CA editions.
    Optional
    Used to specify whether the line item rates are inclusive or exclusive of tax.
    item_id
    Optional
    Unique string generated for the item to which a refund is to be made.
    account_id
    Optional
    Unique ID to denote the account.
    name
    Optional
    Name of the credit
    avatax_tax_code
    Avalara integration only
    Optional
    A tax code is a unique label used to group Items (products, services, or charges) together. Refer the [link][2] for more deails. Max-length [25]
    description
    Optional
    A small description about the item.
    unit
    Optional
    Unit of the line item. E.g: kgs, Nos.
    rate
    Optional
    Rate of the line item.
    quantity
    Optional
    Quantity of the item included.

    Query Params

    ignore_auto_number_generation
    Optional
    Set to true if you need to provide your own credit note number.

    Get a credit note

    Details of an existing creditnote.
    oauthscope : ZohoBooks.creditnotes.READ

    GET /creditnotes/{creditnote_id}

    Request Example

      
    $ curl https://books.zoho.com/api/v3/creditnotes/{creditnote_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", "credit_note": { "creditnote": { "creditnote_id": "90300000072369", "creditnote_number": "CN-29", "date": "2016-06-05", "is_pre_gst": true, "place_of_supply": "TN", "gst_no": "22AAAAA0000A1Z5", "gst_treatment": "business_gst", "tax_treatment": "vat_registered", "status": "draft", "customer_id": "903000000000099", "customer_name": "Bowman Furniture", "custom_fields": [ { "index": 1, "value": 129890, "label": "label", "data_type": "text" } ], "reference_number": "INV-384", "email": "[email protected]", "total": 450, "balance": 10, "line_items": [ { "item_id": "90300000081501", "description": "prorated amount for items", "code": "basic-monthly", "name": "Basic Monthly", "type": 1, "account_id": "903000000000388", "account_name": "Sales", "quantity": 1, "tax_id": "903000000000356", "tax_treatment_code": "uae_others", "product_type": "goods", "warehouse_id": 90300000072378 } ], "invoices": [ { "invoice_id": "90300000079426", "invoice_number": "INV-384", "amount": 450 } ], "taxes": [ { "tax_id": "903000000000356", "tax_name": "Basic Tax", "tax_amount": "2.50" } ], "currency_code": "USD", "currency_symbol": "$", "created_time": "2016-06-05T02:30:08-0700", "updated_time": "2016-06-05T02:30:08-0700", "billing_address": { "address": "4900 Hopyard Rd, Suite 310", "street2": "McMillan Avenue", "city": "Pleasanton", "state": "CA", "zip": 94588, "country": "U.S.A", "fax": "+1-925-924-9600", "attention": " " }, "shipping_address": { "address": "4900 Hopyard Rd, Suite 310", "street2": "McMillan Avenue", "city": "Pleasanton", "state": "CA", "zip": 94588, "country": "U.S.A", "fax": "+1-925-924-9600", "attention": " " }, "template_id": "90300000001336", "template_name": "Standard Template", "notes": "Offer for the referral", "terms": "" } } }

    Query Params

    print
    Optional
    Export credit note pdf with default print option. Allowed Values: true, false, on and off
    accept
    Optional
    You can get credit note details as json/pdf/html. Default format is html. Allowed Values: json, pdf and html

    List all Credit Notes

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

    GET /creditnotes

    Request Example

      
    $ curl https://books.zoho.com/api/v3/creditnotes?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", "credit_note": [ { "creditnotes": { "creditnote_id": "90300000072369", "creditnote_number": "CN-29", "status": "draft", "reference_number": "INV-384", "date": "2016-06-05", "total": 450, "balance": 10, "customer_id": "903000000000099", "customer_name": "Bowman Furniture", "currency_id": "982000000567240", "currency_code": "USD", "created_time": "2016-06-05T02:30:08-0700", "last_modified_time": "2016-06-05T02:30:08-0700", "is_emailed": true } }, {...}, {...} ] }

    Query Params

    creditnote_number
    Optional
    Unique number generated (starts with CN) which will be displayed in the interface and credit notes. Max-Length [100]
    date
    Optional
    The date on which credit note is raised. Format [yyyy-mm-dd]
    status
    Optional
    Status of the credit note. This can be open, closed or void.
    total
    Optional
    Total credits raised in this credit note.
    reference_number
    Optional
    Reference number generated for the payment. A string of your choice can also be used as the reference number. Max-Length [100]
    customer_name
    Optional
    Name of the customer to whom the credit note is raised. Max-Length [100]
    item_name
    Optional
    Search credit notes by item name.Max_lenght [100]
    customer_id
    Optional
    Customer ID of the customer for whom the credit note is raised.
    item_description
    Optional
    description for the item.Variants item_description_startswith and item_description_contains. Max-length [100]
    item_id
    Optional
    Unique string generated for the item to which a refund is to be made.
    line_item_id
    Optional
    Search credit notes by credit note line item id.
    tax_id
    Optional
    Unique to denote the tax associate dto the creditnote
    filter_by
    Optional
    Filter credit notes by statuses. Allowed values Status.All Status.Open Status.Draft Status.Closed and Status.Void
    search_text
    Optional
    Search credit notes by credit note number or customer name or credit note reference number. Max-length [100]
    sort_column
    Optional
    Sort credit notes by following columns customer_name, creditnote_number, balance, total, date and created_time. Allowed Values customer_name creditnote_number balance total date and created_time

    Email a credit note

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

    POST /creditnotes/{creditnote_id}/email

    Request Example

      
    $ curl https://books.zoho.com/api/v3/creditnotes/{creditnote_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": [ "[email protected]", "[email protected]" ], "cc_mail_ids": [ "[email protected]" ], "subject": "Credit note for subscription.", "body": "Please find attached the credit note for your subscription." }"'

    Response Example

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

    ARGUMENTS

    to_mail_ids
    Required
    The email IDs to which the credit note is to be mailed.
    cc_mail_ids
    Optional
    The email IDs that have to be copied when the credit note is to be mailed.
    subject
    Required
    The subject of the email. Max-length [1000]
    body
    Required
    The body of the email. Max-length [5000]

    Query Params

    customer_id
    Optional
    Customer ID of the customer for whom the credit note is raised.
    attachments
    Optional
    The files to be attached with the email.

    Void a Credit Note

    Mark the credit note as Void.
    oauthscope : ZohoBooks.creditnotes.CREATE

    POST /creditnotes/{creditnote_id}/void

    Request Example

      
    $ curl https://books.zoho.com/api/v3/creditnotes/{creditnote_id}/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 credit note has been marked as void." }

    Convert Credit Note to Draft.

    Convert a voided credit note to Draft.
    oauthscope : ZohoBooks.creditnotes.CREATE

    POST /creditnotes/{creditnote_id}/draft

    Request Example

      
    $ curl https://books.zoho.com/api/v3/creditnotes/{creditnote_id}/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": "The credit note has been marked as Draft." }

    Convert to Open

    Convert a credit note in Draft status to Open.
    oauthscope : ZohoBooks.creditnotes.CREATE

    POST /creditnotes/{creditnote_id}/converttoopen

    Request Example

      
    $ curl https://books.zoho.com/api/v3/creditnotes/{creditnote_id}/converttoopen?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 the credit note has been changed to open." }

    Submit a credit note for approval

    Submit an estimate for approval.
    oauthscope : ZohoBooks.creditnotes.CREATE

    POST /creditnotes/{creditnote_id}/submit

    Request Example

      
    $ curl https://books.zoho.com/api/v3/creditnotes/{creditnote_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 Credit Note has been successfully submitted for approval." }

    Approve a credit note.

    Approve a credit note.
    oauthscope : ZohoBooks.creditnotes.CREATE

    POST /creditnotes/{creditnote_id}/approve

    Request Example

      
    $ curl https://books.zoho.com/api/v3/creditnotes/{creditnote_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 Credit Note." }

    Delete a credit note

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

    DELETE /creditnotes/{creditnote_id}

    Request Example

      
    $ curl https://books.zoho.com/api/v3/creditnotes/{creditnote_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 credit note has been deleted." }

    Email history

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

    GET /creditnotes/{creditnote_id}/emailhistory

    Request Example

      
    $ curl https://books.zoho.com/api/v3/creditnotes/{creditnote_id}/emailhistory?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", "email_history": [ { "mailhistory_id": 982000000570005, "from": "[email protected]", "to_mail_ids": [ "[email protected]", "[email protected]" ], "subject": "Credit note for subscription.", "date": "2016-06-05" } ] }

    Get email content

    Get email content of a credit note.
    oauthscope : ZohoBooks.creditnotes.READ

    GET /creditnotes/{creditnote_id}/email

    Request Example

      
    $ curl https://books.zoho.com/api/v3/creditnotes/{creditnote_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": [ { "body": "The credit note is attached with this email.", "error_list": [], "subject": "Credit Note from Zillium Inc(Credit Note #: CN-00001)", "emailtemplates": [ { "selected": "fasle", "name": "Default", "email_template_id": "460000000000085" } ], "to_contacts": [ { "first_name": "Will", "selected": "fasle", "phone": "+1-925-921-9201", "email": "[email protected]", "contact_person_id": "460000000026051", "last_name": "Parker", "salutation": "Mr.", "mobile": "+1-4054439760" } ], "file_name": "CN-00001.pdf", "from_emails": [ { "user_name": "John Smith", "selected": "fasle", "email": "[email protected]" } ], "customer_id": "46000000002609" } ] }

    Query Params

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

    Update billing address

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

    PUT /creditnotes/{creditnote_id}/address/billing

    Request Example

      
    $ curl https://books.zoho.com/api/v3/creditnotes/{creditnote_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": "4900 Hopyard Rd, Suite 310", "city": "Pleasanton", "state": "CA", "zip": 94588, "country": "USA", "fax": "+1-925-924-9600" }"'

    Response Example

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

    ARGUMENTS

    address
    Optional
    Billing address for the invoice
    city
    Optional
    City of the customer’s billing address.
    state
    Optional
    State of the customer’s billing address.
    zip
    Optional
    Zip code of the customer’s billing address.
    country
    Optional
    Country of the customer’s billing address.
    fax
    Optional
    Customer's fax number.

    Update Shipping address

    Updates the shipping address for an existing credit note alone.
    oauthscope : ZohoBooks.creditnotes.UPDATE

    PUT /creditnotes/{creditnote_id}/address/shipping

    Request Example

      
    $ curl https://books.zoho.com/api/v3/creditnotes/{creditnote_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": "Suite 125, McMillan Avenue", "city": "San Francisco", "state": "CA", "zip": 94134, "country": "USA", "fax": "+1-925-924-9600" }"'

    Response Example

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

    ARGUMENTS

    address
    Optional
    Billing address for the invoice
    city
    Optional
    City of the customer’s billing address.
    state
    Optional
    State of the customer’s billing address.
    zip
    Optional
    Zip code of the customer’s billing address.
    country
    Optional
    Country of the customer’s billing address.
    fax
    Optional
    Customer's fax number.

    List credit note template

    Get all credit note pdf templates.
    oauthscope : ZohoBooks.creditnotes.READ

    GET /creditnotes/templates

    Request Example

      
    $ curl https://books.zoho.com/api/v3/creditnotes/templates?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", "templates": [ { "template_name": "Standard Template", "template_id": "90300000001336", "template_type": "professional" } ] }

    Update a credit note template

    Update the pdf template associated with the credit note.
    oauthscope : ZohoBooks.creditnotes.UPDATE

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

    Request Example

      
    $ curl https://books.zoho.com/api/v3/creditnotes/{creditnote_id}/templates/{template_id}?organization_id=10234695 -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": "The credit note has been updated." }

    List invoices credited

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

    GET /creditnotes/:creditnote_id/invoices

    Request Example

      
    $ curl https://books.zoho.com/api/v3/creditnotes/:creditnote_id/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_credited": [ { "creditnote_id": "90300000072369", "invoice_id": "90300000079426", "creditnote_invoice_id": "982000000567172", "date": "2016-06-05", "invoice_number": "INV-384", "creditnote_number": "CN-29", "credited_amount": 12.02 } ] }

    Credit to an invoice

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

    POST /creditnotes/:creditnote_id/invoices

    Request Example

      
    $ curl https://books.zoho.com/api/v3/creditnotes/:creditnote_id/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="{ "invoices": [ { "invoice_id": "90300000079426", "amount_applied": 41.82 } ], "invoice_id": "90300000079426", "amount_applied": 41.82 }"'

    Response Example

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

    ARGUMENTS

    Optional
    List of invoices for which the credit note has been raised. This contains invoice_id and amount.
    invoice_id
    Required
    Invoice ID of the required invoice.
    amount_applied
    Required
    The total amount applied form the credit note on an invoice.
    invoice_id
    Required
    Invoice ID of the required invoice.
    amount_applied
    Required
    The total amount applied form the credit note on an invoice.

    Delete invoices credited

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

    DELETE /creditnotes/:creditnote_id/invoices/:creditnote_invoice_id

    Request Example

      
    $ curl https://books.zoho.com/api/v3/creditnotes/:creditnote_id/invoices/:creditnote_invoice_id?organization_id=10234695 -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." }

    List credit note comments & history

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

    GET /creditnotes/:creditnote_id/comments

    Request Example

      
    $ curl https://books.zoho.com/api/v3/creditnotes/:creditnote_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": "Comments of the credit note are displayed successfully.", "comments": [ { "comment_id": "982000000570001", "creditnote_id": "90300000072369", "description": "Credits applied to invoice INV-00004", "commented_by_id": "982000000554041", "commented_by": "Sujin Kumar", "comment_type": "system", "date": "2016-06-05", "date_description": "7 hours ago", "time": "10:43 PM", "operation_type": "Updated", "transaction_id": "903000002072369", "transaction_type": "email" } ] }

    Add a comment

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

    POST /creditnotes/:creditnote_id/comments

    Request Example

      
    $ curl https://books.zoho.com/api/v3/creditnotes/:creditnote_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": "Credits applied to invoice INV-00004" }"'

    Response Example

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

    ARGUMENTS

    description
    Optional
    A small description about the item.

    Delete a Comment

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

    DELETE /creditnotes/:creditnote_id/comments/:comment_id

    Request Example

      
    $ curl https://books.zoho.com/api/v3/creditnotes/:creditnote_id/comments/:comment_id?organization_id=10234695 -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." }

    List credit note refunds

    List all refunds with pagination.
    oauthscope : ZohoBooks.creditnotes.READ

    GET /creditnotes/refunds

    Request Example

      
    $ curl https://books.zoho.com/api/v3/creditnotes/refunds?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": "The list of credit note refunds are displayed successfully.", "creditnote_refunds": [ { "creditnote_refund_id": "982000000567158", "creditnote_id": "90300000072369", "date": "2016-06-05", "refund_mode": "cash", "reference_number": "INV-384", "creditnote_number": "CN-29", "customer_name": "Bowman Furniture", "description": "", "amount_bcy": 10, "amount_fcy": 10 } ], "page_context": { "page": 1, "per_page": 200, "has_more_page": false, "report_name": "Credit Notes Refund", "sort_column": "created_time", "sort_order": "D" } }

    Query Params

    customer_id
    Optional
    Customer ID of the customer for whom the credit note is raised.
    sort_column
    Optional
    Sort refunds list. Allowed Values: refund_mode, reference_number, date, creditnote_number, customer_name, amount_bcy and amount_fcy

    List refunds of a credit note

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

    GET /creditnotes/:creditnote_id/refunds

    Request Example

      
    $ curl https://books.zoho.com/api/v3/creditnotes/:creditnote_id/refunds?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": "The refunds of the existing credit note are displayed successfully.", "creditnote_refunds": [ { "creditnote_refund_id": "982000000567158", "creditnote_id": "90300000072369", "date": "2016-06-05", "refund_mode": "cash", "reference_number": "INV-384", "creditnote_number": "CN-29", "customer_name": "Bowman Furniture", "description": "", "amount_bcy": 10, "amount_fcy": 10 } ], "page_context": { "page": 1, "per_page": 200, "has_more_page": false, "report_name": "Credit Notes Refund", "sort_column": "created_time", "sort_order": "D" } }

    Get credit note refund

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

    GET /creditnotes/:creditnote_id/refunds/:creditnote_refund_id

    Request Example

      
    $ curl https://books.zoho.com/api/v3/creditnotes/:creditnote_id/refunds/:creditnote_refund_id?organization_id=10234695 -H "Authorization: Zoho-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 refund of the credit note is displayed successfully.", "creditnote_refund": { "creditnote_refund_id": "982000000567158", "creditnote_id": "90300000072369", "date": "2016-06-05", "refund_mode": "cash", "reference_number": "INV-384", "amount": 450, "customer_name": "Bowman Furniture", "description": "prorated amount for items" } }

    Refund credit note

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

    POST /creditnotes/:creditnote_id/refunds

    Request Example

      
    $ curl https://books.zoho.com/api/v3/creditnotes/:creditnote_id/refunds?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": "2016-06-05", "refund_mode": "cash", "reference_number": "INV-384", "amount": 450, "exchange_rate": "5.5", "from_account_id": " ", "description": "prorated amount for items" }"'

    Response Example

      
    HTTP/1.1 200 OK Content-Type:application/json;charset=UTF-8 { "code": 0, "message": "The credit note amount is refunded successfully.", "creditnote_refund": { "creditnote_refund_id": "982000000567158", "creditnote_id": "90300000072369", "date": "2016-06-05", "refund_mode": "cash", "reference_number": "INV-384", "amount": 450, "customer_name": "Bowman Furniture", "description": "prorated amount for items" } }

    ARGUMENTS

    date
    Optional
    The date on which credit note is raised. Format [yyyy-mm-dd]
    refund_mode
    Optional
    The method of refund.
    reference_number
    Optional
    Reference number generated for the payment. A string of your choice can also be used as the reference number. Max-Length [100]
    amount
    Optional
    Amount paid for the invoice.
    exchange_rate
    Optional
    Exchange rate for the currency associated with the customer.
    from_account_id
    Optional
    The account from which credit note is refunded.
    description
    Optional
    A small description about the item.

    Update credit note refund

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

    PUT /creditnotes/:creditnote_id/refunds/:creditnote_refund_id

    Request Example

      
    $ curl https://books.zoho.com/api/v3/creditnotes/:creditnote_id/refunds/:creditnote_refund_id?organization_id=10234695 -X PUT -H "Authorization: Zoho-oauthtoken 1000.41d9f2cfbd1b7a8f9e314b7aff7bc2d1.8fcc9810810a216793f385b9dd6e125f" -H "Content-Type: application/x-www-form-urlencoded;charset=UTF-8" -F 'JSONString="{ "date": "2016-06-05", "refund_mode": "cash", "reference_number": "INV-384", "amount": 450, "exchange_rate": "5.5", "from_account_id": " ", "description": "prorated amount for items" }"'

    Response Example

      
    HTTP/1.1 200 OK Content-Type:application/json;charset=UTF-8 { "code": 0, "message": "The credit note refund is updated successfully.", "creditnote_refund": { "creditnote_refund_id": "982000000567158", "creditnote_id": "90300000072369", "date": "2016-06-05", "refund_mode": "cash", "reference_number": "INV-384", "amount": 450, "customer_name": "Bowman Furniture", "description": "prorated amount for items" } }

    ARGUMENTS

    date
    Optional
    The date on which credit note is raised. Format [yyyy-mm-dd]
    refund_mode
    Optional
    The method of refund.
    reference_number
    Optional
    Reference number generated for the payment. A string of your choice can also be used as the reference number. Max-Length [100]
    amount
    Optional
    Amount paid for the invoice.
    exchange_rate
    Optional
    Exchange rate for the currency associated with the customer.
    from_account_id
    Optional
    The account from which credit note is refunded.
    description
    Optional
    A small description about the item.

    Delete credit note refund

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

    DELETE /creditnotes/:creditnote_id/refunds/:creditnote_refund_id

    Request Example

      
    $ curl https://books.zoho.com/api/v3/creditnotes/:creditnote_id/refunds/:creditnote_refund_id?organization_id=10234695 -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 refund has been successfully deleted." }

    Customer-Payments

    Payments from Customers towards Invoices.

    Example

    { "payment_id": "9030000079467", "payment_mode": "cash", "amount": 450, "amount_refunded": 50, "date": "2016-06-05", "status": "success", "reference_number": "INV-384", "description": "Payment has been added to INV-384", "customer_id": "903000000000099", "customer_name": "Bowman Furniture", "email": "[email protected]", "invoices": [ { "invoice_id": "90300000079426", "invoice_number": "INV-384", "date": "2016-06-05", "invoice_amount": 450, "amount_applied": 450, "balance_amount": 0 } ], "currency_code": "USD", "currency_symbol": "$", "exchange_rate": 1, "bank_charges": 10, "custom_fields": [ { "value": 129890, "label": "label", "data_type": "text" } ] }

    Attribute

    payment_id
    string
    Unique ID of the payment generated by the server. Max-length [2000]
    payment_mode
    string
    Mode through which payment is made. This can be check, cash, creditcard, banktransfer, bankremittance, autotransaction or others. Max-length [100]
    amount
    double
    Amount paid in the respective payment.
    amount_refunded
    double
    Amount that is refund. Refunds are applicable only for payments whose payment_mode is autotransaction. Refunds would be made to the respective card provided by the customer.
    date
    string
    Date on which payment is made. Format [yyyy-mm-dd]
    status
    string
    Status of the payment. It can either be success or failure.
    reference_number
    string
    Reference number generated for the payment. A string of your choice can also be used as the reference number. Max-length [100]
    description
    string
    Description about the payment.
    customer_id
    string
    Customer ID of the customer involved in the payment.
    customer_name
    string
    Name of the customer to whom the invoice is raised. Max-length [100]
    email
    string
    Email address of the customer involved in the payment.
    list
    List of invoices associated with the payment. Each invoice object contains invoice_id, invoice_number, date, invoice_amount, amount_applied and balance_amount.
    invoice_id
    string
    Invoice ID of the required invoice.
    invoice_number
    string
    Unique ID (starts with INV) of an invoice.
    date
    string
    Date on which payment is made. Format [yyyy-mm-dd]
    invoice_amount
    double
    Total amount raised for the invoice.
    amount_applied
    double
    Amount paid for the invoice.
    balance_amount
    double
    Unpaid amount of the invoice.
    currency_code
    string
    Currency code in which the payment is made.
    currency_symbol
    string
    Customer's currency symbol.
    exchange_rate
    double
    Exchange rate for the currency used in the invoices and customer's currency. The payment amount would be the multiplicative product of the original amount and the exchange rate.
    bank_charges
    double
    Denotes any additional bank charges.
    custom_fields
    list
    Additional fields for the payments.
    value
    string
    Value of the custom field.
    label
    string
    Label of the custom field.
    data_type
    string
    Data type of the custom field.

    Create a payment

    Create a new payment.

    POST /customerpayments

    Request Example

      
    $ curl https://books.zoho.com/api/v3/customerpayments?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 } ], "exchange_rate": 1, "bank_charges": 10, "custom_fields": [ { "label": "label", "value": 129890 } ], "invoice_id": "90300000079426", "amount_applied": 450, "tax_amount_withheld": 0, "account_id": " ", "contact_persons": [ "982000000870911", "982000000870915" ] }"'

    Response Example

      
    HTTP/1.1 201 Created Content-Type:application/json;charset=UTF-8 { "code": 0, "message": "The payment has been created. <br><code>oauthscope :<span style=\"color:#6C69F3;\"> ZohoBooks.customerpayments.CREATE </span></code>", "payment": { "payment": { "payment_id": "9030000079467", "payment_mode": "cash", "amount": 450, "amount_refunded": 50, "bank_charges": 10, "date": "2016-06-05", "status": "success", "reference_number": "INV-384", "description": "Payment has been added to INV-384", "customer_id": "903000000000099", "customer_name": "Bowman Furniture", "email": "[email protected]", "invoices": [ { "invoice_id": "90300000079426", "invoice_number": "INV-384", "date": "2016-06-05", "invoice_amount": 450, "amount_applied": 450, "balance_amount": 0 } ], "currency_code": "USD", "currency_symbol": "$", "custom_fields": [ { "index": 1, "value": 129890, "label": "label", "data_type": "text" } ] } } }

    ARGUMENTS

    customer_id
    Required
    Customer ID of the customer involved in the payment.
    payment_mode
    Required
    Mode through which payment is made. This can be check, cash, creditcard, banktransfer, bankremittance, autotransaction or others. Max-length [100]
    amount
    Required
    Amount paid in the respective payment.
    date
    Required
    Date on which payment is made. Format [yyyy-mm-dd]
    reference_number
    Optional
    Reference number generated for the payment. A string of your choice can also be used as the reference number. Max-length [100]
    description
    Optional
    Description about the payment.
    Required
    List of invoices associated with the payment. Each invoice object contains invoice_id, invoice_number, date, invoice_amount, amount_applied and balance_amount.
    invoice_id
    Optional
    Invoice ID of the required invoice.
    amount_applied
    Optional
    Amount paid for the invoice.
    exchange_rate
    Optional , default is 1
    Exchange rate for the currency used in the invoices and customer's currency. The payment amount would be the multiplicative product of the original amount and the exchange rate.
    bank_charges
    Optional
    Denotes any additional bank charges.
    custom_fields
    Optional
    Additional fields for the payments.
    label
    Optional
    Label of the custom field.
    value
    Optional
    Value of the custom field.
    invoice_id
    Optional
    Invoice ID of the required invoice.
    amount_applied
    Optional
    Amount paid for the invoice.
    tax_amount_withheld
    Optional
    Amount withheld for tax.
    account_id
    Optional
    ID of the cash/bank account the payment has to be deposited.
    contact_persons
    Optional
    IDs of the contact personsthe thank you mail has to be triggered.

    Update a payment

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

    PUT /customerpayments/{payment_id}

    Request Example

      
    $ curl https://books.zoho.com/api/v3/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 } ], "exchange_rate": 1, "bank_charges": 10, "custom_fields": [ { "label": "label", "value": 129890 } ], "invoice_id": "90300000079426", "amount_applied": 450, "tax_amount_withheld": 0, "account_id": " " }"'

    Response Example

      
    HTTP/1.1 200 OK Content-Type:application/json;charset=UTF-8 { "code": 0, "message": "The payment details have been updated.", "payment": { "payment": { "payment_id": "9030000079467", "payment_mode": "cash", "amount": 450, "amount_refunded": 50, "bank_charges": 10, "date": "2016-06-05", "status": "success", "reference_number": "INV-384", "description": "Payment has been added to INV-384", "customer_id": "903000000000099", "customer_name": "Bowman Furniture", "email": "[email protected]", "invoices": [ { "invoice_id": "90300000079426", "invoice_number": "INV-384", "date": "2016-06-05", "invoice_amount": 450, "amount_applied": 450, "balance_amount": 0 } ], "currency_code": "USD", "currency_symbol": "$", "custom_fields": [ { "index": 1, "value": 129890, "label": "label", "data_type": "text" } ] } } }

    ARGUMENTS

    customer_id
    Required
    Customer ID of the customer involved in the payment.
    payment_mode
    Required
    Mode through which payment is made. This can be check, cash, creditcard, banktransfer, bankremittance, autotransaction or others. Max-length [100]
    amount
    Required
    Amount paid in the respective payment.
    date
    Optional
    Date on which payment is made. Format [yyyy-mm-dd]
    reference_number
    Optional
    Reference number generated for the payment. A string of your choice can also be used as the reference number. Max-length [100]
    description
    Optional
    Description about the payment.
    Required
    List of invoices associated with the payment. Each invoice object contains invoice_id, invoice_number, date, invoice_amount, amount_applied and balance_amount.
    invoice_id
    Optional
    Invoice ID of the required invoice.
    amount_applied
    Optional
    Amount paid for the invoice.
    exchange_rate
    Optional , default is 1
    Exchange rate for the currency used in the invoices and customer's currency. The payment amount would be the multiplicative product of the original amount and the exchange rate.
    bank_charges
    Optional
    Denotes any additional bank charges.
    custom_fields
    Optional
    Additional fields for the payments.
    label
    Optional
    Label of the custom field.
    value
    Optional
    Value of the custom field.
    invoice_id
    Optional
    Invoice ID of the required invoice.
    amount_applied
    Optional
    Amount paid for the invoice.
    tax_amount_withheld
    Optional
    Amount withheld for tax.
    account_id
    Optional
    ID of the cash/bank account the payment has to be deposited.

    Retrieve a payment

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

    GET /customerpayments/{payment_id}

    Request Example

      
    $ curl https://books.zoho.com/api/v3/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": { "payment_id": "9030000079467", "payment_mode": "cash", "amount": 450, "amount_refunded": 50, "bank_charges": 10, "date": "2016-06-05", "status": "success", "reference_number": "INV-384", "description": "Payment has been added to INV-384", "customer_id": "903000000000099", "customer_name": "Bowman Furniture", "email": "[email protected]", "invoices": [ { "invoice_id": "90300000079426", "invoice_number": "INV-384", "date": "2016-06-05", "invoice_amount": 450, "amount_applied": 450, "balance_amount": 0 } ], "currency_code": "USD", "currency_symbol": "$", "custom_fields": [ { "index": 1, "value": 129890, "label": "label", "data_type": "text" } ] } } }

    List Customer Payments

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

    GET /customerpayments

    Request Example

      
    $ curl https://books.zoho.com/api/v3/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", "customer_payments": [ { "payment_id": "9030000079467", "payment_number": "2", "invoice_number": "INV-384&