Zoho Invoice

Help Docs

Back to Settings Overview

Custom Functions

Custom functions in Zoho Invoice allows you to write small pieces of code to automate your business processes. Be it providing a special discount on your customers’ invoice, or adding a late fee when an invoice becomes overdue, all you have to do is write a piece of code using Deluge script and link it to a workflow rule and automation of the process will be taken care of.

What is Deluge?

Deluge(Data Enriched Language for the Universal Grid Environment) is an online scripting language integrated with Zoho Creator. It enables users to add logic to the application, incrementally, making it more powerful and robust.

To know about Deluge, refer the Deluge Reference Guide.

If you wish to learn Deluge by writing code samples, click here.

Creating and Executing a Custom function

To setup a custom function,

New Custom function button

Custom function form

Now, the next step is to create a workflow rule using the newly created custom function.

Now, whenever the criteria is met, the workflow rule will be triggered, which in turn will trigger the custom function.

Default fields

As of now, custom functions support User, Organization, Estimate, Invoice, Customer, Recurring Invoice, Expense and Item modules.

These modules will have the following fields from which you can get the necessary paramters for your custom function.

user

The user field supports the following parameters:

Key Fields Description
name Name of the user
zuid ZUID of the user
organization

The organization map supports the following fields:

Key Fields Description
organization_id Your organization ID
name Organization name
time_zone Time zone of your organization
language_code Organization’s language
date_format Your organization’s date format
currency_id Currency ID
currency_code Currency code
currency_symbol Currency symbol
address Organization address
phone Organization’s contact number
fax Fax number
website Organization URL
email Email address
portal_name Portal name of your organization

Sample map:

{
	"time_zone": "Asia/Calcutta",
	"language_code": "en",
	"currency_id": "7605000000000099",
	"phone": "99999999999",
	"fax": "check",
	"website": "",
	"email": "charles@zylker.com",
	"address": {
		"zip": "624001",
		"country": "India",
		"city": "New Delhi",
		"street_address2": "Block 15",
		"street_address1": "6/35 Garden Lane,",
		"state": "Delhi"
	},
	"organization_id": "12345678",
	"name": "Zlyker Industries",
	"date_format": "dd MMM yyyy",
	"currency_symbol": "Rs.",
	"portal_name": "zylkerindustry",
	"currency_code": "INR"
}
estimate

The estimate map supports the following fields:

Key Fields Description
estimate_id Estimate ID
estimate_number Your estimate number
date Estimate date
reference_number Reference number of your Estimate
status Status of your estimate
customer_id ID of the customer who is assigned to the estimate
customer_name Your customer name
currency_id Currency ID
currency_code Currency code
currency_symbol Currency symbol
exchange_rate Exchange rate involved in the estimate
expiry_date Expiry date of the estimate
discount_amount Discount amount
discount Discount
shipping_charge Shipping charge entered in the estimate
adjustment Adjustments
sub_total Sub total of the estimate
total Estimate total
tax_total Total tax amount in the estimate
billing_address Billing address of the customer
shipping_address Shipping address of the customer
notes Notes
terms Terms and conditions
custom_fields Estimate custom fields
salesperson_id ID of the salesperson
salesperson_name Name of the salesperson

Sample map:

{
	"total": "12000.0",
	"terms": “checking",
	"estimate_id": "7605000000320001",
	"date": "2016-06-03",
	"estimate_number": "EST-000026",
	"shipping_address": {
		"zip": "94588",
		"country": "USA",
		"address": "4910 Hopyard Rd",
		"city": "Pleasanton",
		"state": "CA",
		"fax": “Fax Number”
	},
	"salesperson_name": “Salesperson”,
	"adjustment": "0.0",
	"currency_symbol": "Rs.",
	"salesperson_id": "7605000000336089",
	"currency_code": "INR",
	"shipping_charge": "0.0",
	"custom_fields": [
		{
			"customfield_id": "7605000000190011",
			"is_active": true,
			"show_in_all_pdf": false,
			"value_formatted": "Check-6",
			"data_type": "autonumber",
			"index": 1,
			"label": "auto number",
			"show_on_pdf": false,
			"value": "Check-6"
		}
	],
	"currency_id": "7605000000000099",
	"exchange_rate": "1.0",
	"status": "invoiced",
	"sub_total": "12000.0",
	"customer_name": “Customer”,
	"discount_amount": "0.0",
	"discount": "0.0",
	"tax_total": "0.0",
	"reference_number": “Ref number”,
	"notes": "Looking forward for your business.",
	"expiry_date": "2016-06-03",
	"customer_id": "7605000000258011",
	"billing_address": {
		"zip": "94588",
		"country": "USA",
		"address": "4910 Hopyard Rd",
		"city": "Pleasanton",
		"state": "CA",
		"fax": "Fax Number"
	}
}
invoice

The invoice map supports the following fields:

Key Fields Description
due_date Invoice due date
payment_expected_date Expected payment date for the invoice
reference_number Reference number of the invoice
customer_id Customer ID
customer_name Name of the customer who is assigned to the invoice
currency_id Currency ID
currency_code Currency code
currency_symbol Currency symbol
exchange_rate Exchange rate involved in the invoice
discount_amount Discount amount involved in the invoice
discount Discount involved in the invoice
shipping_charge Shipping charge entered in the invoice
adjustment Adjustments
sub_total Sub total of the invoice
tax_total Total tax amount in the invoice
total Total amount
balance Balance
price_precision Number of Decimal places
billing_address Billing address of the customer
shipping_address Shipping address of the customer
notes Notes
terms Terms and conditions
custom_fields Invoice custom fields
salesperson_id ID of the salesperson

Sample map:

{
	"total": "0.0",
	"payment_terms": "0",
	"terms": “Checking”,
	"price_precision": "2",
	"payment_expected_date": "2016-06-31”,
	"date": "2016-06-30",
	"shipping_address": {
		"zip": "94588",
		"country": "USA",
		"address": "4910 Hopyard Rd",
		"city": "Pleasanton",
		"state": "CA",
		"fax": "Fax Number"
	},
	"balance": "0.0",
	"adjustment": "0.0",
	"currency_symbol": "Rs.",
	"salesperson_id": “7605000000336089”,
	"currency_code": "INR",
	"shipping_charge": "0.0",
	"custom_fields": [
		{
			"customfield_id": "7605000000336081",
			"is_active": true,
			"show_in_all_pdf": false,
			"value_formatted": "INV-8",
			"data_type": "autonumber",
			"index": 1,
			"label": "AutoNumber",
			"show_on_pdf": false,
			"value": "INV-8"
		},
		{
			"customfield_id": "7605000000351027",
			"is_active": true,
			"show_in_all_pdf": true,
			"value_formatted": "01 Aug 2016",
			"data_type": "date",
			"index": 2,
			"label": "Date",
			"show_on_pdf": true,
			"value": "2016-08-01"
		}
	],
	"currency_id": "7605000000000099",
	"exchange_rate": "1.0",
	"status": "draft",
	"sub_total": "12000.0",
	"customer_name": “Customer”,
	"invoice_number": "INV-000087",
	"discount_amount": "12000.0",
	"discount": "100.00%",
	"tax_total": "0.0",
	"reference_number": “checking”,
	"due_date": "2016-06-30",
	"invoice_id": "7605000000369043",
	"notes": "Thanks for your business.",
	"customer_id": "7605000000258011",
	"billing_address": {
		"zip": "94588",
		"country": "USA",
		"address": "4910 Hopyard Rd",
		"city": "Pleasanton",
		"state": "CA",
		"fax": "Fax Number"
	}
}
customer

The customer map supports the following fields:

Key Fields Description
owner_id ID of associated owner
billing_address Billing address associated to customer
source Source of the customer
contact_id Contact ID
payment_terms Payments terms associated to customer
currency_code Currency code
language_code Language code
contact_type Type of the contact
twitter Twitter info
zcrm_contact_id ID of the contact in Zoho CRM
shipping_address Shipping address associated to customer
pricebook_id ID of pricebook associated
contact_name Name of contact
website Website of contact
owner_name Name of contact owner
currency_symbol Currency symbol
zcrm_account_id ID of Zoho CRM account
custom_fields Custom fields associated with customer
facebook Facebook info
pricebook_name Name of pricebook associated
primary_contact_id ID of orimary contact
company_name Name of the company
contact_salutation Contact salutation
crm_owner_id ID of CRM owner
currency_id Currency ID
payment_terms_label Payment terms label
status Status

Sample map:

{
	"owner_id": "",
	"shipping_address": {
		"zip": "94588",
		"country": "USA",
		"address": "4910 Hopyard Rd",
		"city": "Pleasanton",
		"state": "CA",
		"fax": "Fax Number"
	},
	"source": "user",
	"contact_id": "7605000000197147",
	"payment_terms": "0",
	"currency_code": "INR",
	"language_code": "en",
	"contact_type": "customer",
	"twitter": "",
	"zcrm_contact_id": "",
	"billing_address": {
		"zip": "94588",
		"country": "USA",
		"address": "4910 Hopyard Rd",
		"city": "Pleasanton",
		"state": "CA",
		"fax": "Fax Number"
	},
	"pricebook_id": "",
	"contact_name": "Arun",
	"website": "www.zoho.com",
	"owner_name": "",
	"currency_symbol": "Rs.",
	"zcrm_account_id": "418070000000135001",
	"custom_fields": [
		{
			"customfield_id": "7605000000063049",
			"is_active": true,
			"show_in_all_pdf": false,
			"value_formatted": "1234",
			"data_type": "number",
			"index": 1,
			"label": "Unpaid Invoices",
			"show_on_pdf": false,
			"value": "1234"
		}
	],
	"facebook": "",
	"pricebook_name": "",
	"primary_contact_id": "7605000000197149",
	"company_name": "Zoho",
	"contact_salutation": "",
	"crm_owner_id": "",
	"currency_id": "7605000000000099",
	"payment_terms_label": "Due on Receipt",
	"status": "active"
}

recurring invoice

The recurring invoice map supports the following fields:

Key Fields Description
end_date End date of the recurring invoice profile
tax_total Total tax amount in the recurring invoice
discount_amount Discount amount involved in the recurring invoice
repeat_every Repetition period of recurring invoice profile
discount Discount involved in the recurring invoice
taxes Taxes associated with the recurring invoice
billing_address Billing address of the customer
line_items Line items in the recurring invoice
payment_terms Payments terms associated to customer
currency_code Currency code
last_sent_date Date of the last sent invoice
total Total amount
recurrence_name Name of the recurring invoice profile
shipping_address Shipping address of the customer
next_invoice_date Date of the next invoice to be sent
recurrence_frequency Frequency of the recurring invoice profile
recurring_invoice_id ID of the recurring invoice profile
contact_persons Contact persons involved in recurring invoice
start_date Starting date of the recurring invoice profile
exchange_rate Exchange rate involved in the recurring invoice
currency_symbol Currency symbol
custom_fields Recurring invoice custom fields
salesperson_name Name of the sales person involved
salesperson_id ID of the sales person involved
shipping_charge Shipping charge entered in the recurring invoice
sub_total Sub-total of the recurring invoice
adjustment Adjustments made
customer_name Name of the customer involved
customer_id ID of the customer involved
status Status of the recurring invoice profile

Sample map:


{
	"end_date": "2016-10-15",
	"tax_total": "0.0",
	"discount_amount": "1.0",
	"repeat_every": "2",
	"discount": "1.00%",
	"taxes": "[]",
	"billing_address": {"zip":"","fax":"","address":"","state":"","country":"","city":""},
	"line_items": [{"tags":[],"tax_name":"","tax_type":"tax","item_custom_fields":[],"product_type":"service","line_item_id":"348960000000103013","discount":0,"unit":"","item_order":0,"rate":100,"item_id":"","description":"%(d)%-%(m-2)%-%(y)%","name":"","quantity":1,"tax_id":"","tax_percentage":0,"item_total":100}],
	"payment_terms": "0",
	"currency_code": "GBP",
	"last_sent_date": "",
	"total": "200.0",
	"recurrence_name": "1",
	"shipping_address": {"zip":"","fax":"","address":"","state":"","country":"","city":""},
	"next_invoice_date": "",
	"recurrence_frequency": "months",
	"recurring_invoice_id": "348960000000103005",
	"contact_persons": "[]",
	"start_date": "2016-01-07",
	"exchange_rate": "1.0",
	"currency_symbol": "£",
	"custom_fields": [{"value_formatted":"EST-001","index":1,"is_active":true,"data_type":"string","show_on_pdf":false,"value":"EST-001","show_in_all_pdf":false,"label":"Estimate Number","customfield_id":"348960000000056001"},{"value_formatted":"15 Oct 2016","index":2,"is_active":true,"data_type":"date","show_on_pdf":false,"value":"2016-10-15","show_in_all_pdf":false,"label":"Date","customfield_id":"348960000000056003"},{"value_formatted":"true","index":3,"is_active":true,"data_type":"check_box","show_on_pdf":false,"value":true,"show_in_all_pdf":false,"label":"Invoice Factoring","customfield_id":"348960000000056079"},{"value_formatted":"£100.00","index":4,"is_active":true,"data_type":"amount","show_on_pdf":true,"value":100,"show_in_all_pdf":true,"label":"Amount","customfield_id":"348960000000060003"},{"value_formatted":"10%","index":5,"is_active":true,"data_type":"percent","show_on_pdf":true,"value":10,"show_in_all_pdf":true,"label":"Percentage","customfield_id":"348960000000060005"}],
	"salesperson_name": "Arun N",
	"salesperson_id": "348960000000111001",
	"shipping_charge": "100.0",
	"sub_total": "100.0",
	"adjustment": "1.0",
	"customer_name": "iArun",
	"customer_id": "348960000000051041",
	"status": "expired"
}

expense

The expense map supports the following fields:

Key Fields Description
date Date
payment_mode Mode of payment
custom_fields Expense custom fields
is_billable Billability of the expense
line_items Line items in the expense
project_name Name of the project involved
reference_number Reference number of the expense
currency_code Currency code
total Total
project_id ID of the project involved
sub_total Sub-total on the expense
customer_name Name if the customer involved
customer_id ID of the customer involved
expense_id Expense ID
currency_id Currency ID

Sample map:

{
	"date": "2016-10-08",
	"payment_mode": "Cash",
	"custom_fields": "[]",
	"is_billable": "true",
	"line_items": [{"tags":[],"tax_name":"Standard Rate","item_order":1,"tax_type":"tax","account_id":"348960000000000400","description":"Notes","tax_amount":16.67,"product_type":"goods","tax_id":"348960000000044037","line_item_id":"348960000000184015","tax_percentage":20,"item_total":83.33,"account_name":"Office Supplies"}],
	"project_name": "",
	"reference_number": "12345",
	"currency_code": "GBP",
	"total": "100.0",
	"project_id": "",
	"sub_total": "83.33",
	"customer_name": "Accounts",
	"customer_id": "348960000000111017",
	"expense_id": "348960000000184003",
	"currency_id": "348960000000000103"
}

item

The item map supports the following fields:

Key Fields Description
item_id Item ID
custom_fields Item custom fields
tax_name Name of the tax involved
zcrm_product_id ID of the product in Zoho CRM
tax_id ID of the tax involved
unit Unit of the item
account_id Sales account ID
tax_type Type of the tax involved
rate Sales rate of the item
account_name Name of the sales account involved
name Name of the item
tax_percentage Percentage of tax involved
pricebook_rate Pricebook rate
sku SKU of the item
status Status of the item

Sample map:

{
	"item_id": "348960000000051011",
	"custom_fields": [{"value_formatted":"100","index":1,"is_active":true,"data_type":"decimal","show_on_pdf":true,"value":100,"show_in_all_pdf":true,"label":"Profit","customfield_id":"348960000000134003"}],
	"tax_name": "",
	"zcrm_product_id": "1665395000000205001",
	"tax_id": "",
	"unit": "1",
	"account_id": "348960000000000388",
	"tax_type": "",
	"rate": "1000.0",
	"account_name": "Sales",
	"name": "Item",
	"tax_percentage": "0",
	"pricebook_rate": "1000.0",
	"sku": "SKU",
	"status": "active"
}

A few example explaining how these fields would help in fetching the necessary paramters:

Example 1:

To fetch estimate id, use:

estimateid = estimate.get("estimate_id");

Example 2:

To fetch your organization name, use:

orgid = organization.get("name");

Example 3:

To fetch a user’s name and ZUID, use:

username = user.get("name");
zuid = user.get("zuid");

To know more about how to use Deluge scripts for writing custom functions, refer the Deluge Reference Guide.

To know more about different scenarios where custom functions could be useful, refer our Custom Function Scenarios page.

Was this document helpful?
Thank you for your feedback!
TOP