Mark Status In Zoho Books

Table of Contents

Note:

  • Each time the zoho.books.markStatus integration task is executed, it triggers an API request in the back-end. This call is deducted from the external calls limit available for the service from which the task is executed, based on your pricing plan.
  • Only actual executions that receive a response (whether success or failure) are counted, not the number of times the task appears in the script. For example, if zoho.books.markStatus integration task is placed inside a for each task that iterates five times, the number of external calls consumed will be five, even though the task appears only once in the script. 

Overview

This task is used to change the status field with one of the allowed values in the specified Zoho Books module.

This task is based on Zoho Books API modules - Estimates and Invoices.

Syntax

<variable> = zoho.books.markStatus(<module_name>, <org_ID>, <record_ID>, <status>, <connection>);
ParameterData typeDescription
<variable>KEY-VALUEVariable which will hold the response returned by Zoho Books.
<module_name> TEXT

specifies the name of the Zoho Books module in which the status field's value will be changed.

The following are the applicable modules:

  • Estimates
  • Invoices
<org_ID>TEXTspecifies the organization ID of the account in which the value of the status field will be changed.
<record_ID>TEXT

specifies the ID of the record whose status will be changed.

Learn how to fetch the ID of a record after creating it or fetching it.

<status>TEXT

specifies the status value. The following table presents the allowed status values for each module:

Module NameAllowed values
Estimatesaccepted
declined
sent
Invoicesvoid
sent
<connection>TEXT

is the link name of Zoho Books connection

Note:

  • In view of stopping new authtoken generation, a Zoho OAuth connection with appropriate scopes is mandatory for new integration tasks (created after the deadline specified in the post) to work as expected. Existing integration tasks will continue to work with or without the connections parameter unless the authtoken is manually deleted from accounts.
  • Add relevant scopes as mentioned in Zoho Books API -> <Module> -> Mark <ModuleName>.
  • Refer to this post for the list of Zoho services that support the connections page.
  • Learn more about connections

Example 1: Mark status with a static value

The following script sets the status of the specified record to "sent", in the Zoho Books module - Invoices.

 response = zoho.books.markStatus("Invoices","5379XXXX","176XXXXXXXXXXXXX180","sent", "books_connection");

where,

response
is the variable which holds the KEY-VALUE response returned by Zoho Books
"Invoices"
is the TEXT that represents the module name
"5379XXXX"
is the TEXT that represents the organization ID of the Zoho Books account
"176XXXXXXXXXXXXX180"
is the TEXT that represents the record ID whose status needs to be changed
"sent"
is the TEXT that represents the status value
"books_connection"
is the TEXT that represents the Zoho Books connection

Example 2: Mark status with dynamic value

The following script sets the status value as "declined" if the current date is greater than 3 months from the creation date of the estimate. Otherwise, it sets the status value as "sent".

 dynamic_value = "sent";
 estimate_date = "24-12-2018"; //Estimate date can be fetched using the task - zoho.books.getRecordsByID
 if(zoho.currentdate > estimate_date.addMonth(3))
 {
 dynamic_value = "declined";
 }
 response = zoho.books.markStatus("Estimates", "5379XXXX", "176XXXXXXXXXXXXX180", dynamic_value, "books_connection");

where,

response
is the variable which holds the KEY-VALUE response returned by Zoho Books
dynamic_value
is the TEXT that holds the status value
estimate_date
is the TEXT variable that holds the creation date of the estimate
"books_connection"
is the TEXT that represents the Zoho Books connection

Response Format

  • The following is a sample success response:

      {
      "code":0,
      "message":"Estimate status has been changed to Accepted."
      }

  • The failure response returned for incorrect / non-existent organization ID is of the following format.

      {
      "code":6041,
      "message":"This user is not associated with the CompanyID/CompanyName:638XXX318."
      }

  • The failure response returned for incorrect / non-existent record ID is of the following format.

      {
      "code":5,
      "message":"Invalid URL Passed"
      }

  • The failure response returned for supplying unallowed status value is of the following format.

      {
      "code":-1,
      "message":"Resource does not exist."
      }

Related Links