Create record in Zoho Invoice

Table of Contents

Note:

  • Each time the zoho.invoice.create 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.invoice.create 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 create a record in Zoho Invoice.

Syntax

<variable> = zoho.invoice.create(<module_name>, <org_ID>, <data_map>, <connection>);

where,

ParameterData typeDescription
<variable> KEY-VALUEspecifies the variable which will hold the response returned by Zoho Invoice.
<module_name>TEXT

specifies the Zoho Invoice's module in which the record will be created.

Following are the applicable modules.

ContactsInvoicesCustomer PaymentsItems
EstimatesExpensesExpenseCategory

Projects

(applicable to all Zoho services except Zoho Creator)

<org_ID>TEXTspecifies the organization ID of the account in which the record will be created.
<data_map>KEY-VALUE

Input map with key as Invoice field's name and the required value.

To learn about the mandatory fields, click here and go to <ModuleName> -> Create <ModuleName>

<connection>*

(optional)

TEXT

specifies the name of the Zoho Invoice connection.

*Note: This param is not supported when used in Zoho Creator.

Examples

1) Let's say we have a Zoho Creator form containing a field called Customer_ID, and a subform called Products. The subform contains fields item_id, name, rate, and quantity. On submission of this form, an invoice must be created in Zoho Invoice with the details specified in the subform. We can achieve this using the following snippet:

listVar = List();

​//iterating each row in the subform
for each  line in Products
{
  mapVar = map();
  mapVar.put("item_id", line.item_id);
  mapVar.put("name", line.name);
  mapVar.put("rate", line.rate);
  mapVar.put("quantity", line.quantity);
  listVar.add(mapVar);
}
values = map();
values.put("customer_id", input.Customer_ID);
values.put("line_items", listVar);
response = zoho.invoice.create("Invoices", "66XXXXX66", values);

where,

listVar
is the LIST variable that holds the list of key value pairs for the line items in the invoice
 mapVar
 values
are the MAP variables which hold key value pairs
 "item_id"
 "name"
 "rate"
 "quantity"
 "customer_id"
 "line_items"
are the TEXT that represents the label name of the field specified in Zoho Invoice' API. Customer ID and Item ID can be viewed in the url in Zoho Invoice account when you click on a record in Customers or Items modules respectively.
"Invoices"
is the TEXT that represents the module in which the record needs to be created
"66XXXXX66"
is the TEXT that represents the organization ID of the Zoho Invoice account in which the record needs to be created

2) The following script creates a new record in the Zoho Invoice module - customerpayments.

 CusPayMap=map();
 CusPayMap.put("customer_id","13144XXXXXXXXXXXX");
 CusPayMap.put("payment_mode","cheque");
 CusPayMap.put("amount","450");
 CusPayMap.put("date","2017-01-01");
 response =zoho.invoice.create("Customerpayments", "5368XXXX",CusPayMap);

where,

CusPayMap
is the KEY-VALUE variable that holds the values of the record that needs to be created
 "customer_id"
 "payment_mode"
 "amount"
 "date"
are the TEXT that represents the label names of fields specified in Zoho Invoice's API
"Customerpayments"
is the TEXT that represents the module in which the record needs to be created
"5368XXXX"
is the TEXT that represents the organization ID of the Zoho Invoice account in which the record needs to be created

Sample Response

Success Format

  • The following is a sample success response:

    {  
       "payment":{  
          "date":"2017-01-01",
          "can_send_in_mail":true,
          "documents":[  

          ],
          "discount_amount":0.0,
          "is_payment_details_required":true,
          "attachment_name":"",
          "is_client_review_settings_enabled":false,
          "description":"",
          "currency_code":"INR",
          "online_transaction_id":"",
          "page_width":"8.27in",
          "bank_charges":0.0,
          "invoices":[  

          ],
          "payment_id":"13144XXXXXXXXXXXX",
          "tax_amount_withheld":0.0,
          "custom_field_hash":{  

          },
          "template_type":"elite",
          "product_description":"",
          "last_four_digits":"",
          "payment_mode":"check",
          "amount":450.0,
          "orientation":"portrait",
          "exchange_rate":1.0,
          "custom_fields":[  

          ],
          "payment_refunds":[  

          ],
          "card_type":"",
          "reference_number":"",
          "template_name":"Elite Template",
          "template_id":"13144XXXXXXXXXXXX",
          "customer_name":"Bowman and Cos",
          "unused_amount":450.0,
          "customer_id":"13144XXXXXXXXXXXX",
          "is_pre_gst":true,
          "currency_id":"13144XXXXXXXXXXXX",
          "page_height":"11.69in"
       },
       "code":0,
       "instrumentation":{  
          "response_write_time":11,
          "query_execution_time":28,
          "page_context_write_time":0,
          "request_handling_time":1012
       },
       "message":"The payment from the customer has been recorded"
    }

To get the ID of the newly created record, execute the following script:

<variable> = <response_variable>.get("<module_name>").get("<module_name>_id"> ;
// example for <module_name> is contact and example for <module_name>_id is contact_id

Failure Response

  • The failure response returned due to incorrect organization ID is of the following format:

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

Related Links