Creator Help

Create Zoho Invoice

Overview

The zoho.invoice.create() task is used to create an invoice in your Zoho Invoice account. The Deluge task zoho.invoice.createdraft() creates an invoice with "draft" status. A draft status indicates that the invoice is likely to undergo further modifications and its amount is yet to reflect in your sales figures. The Deluge task zoho.invoice.createinvoice() creates an invoice with "open" status. An open status for an invoice indicates that your customer is in receipt of the goods or services described on the invoice and the invoice is either fully or partially unpaid.

Deluge syntax

To create an invoice with "open" status,

<Inv Response> = zoho.invoice.createinvoice(<key:value>);

To create an invoice with "draft" status,

<Inv Response> = zoho.invoice.createdraft(<key:value>);

where,
<Key> refers to the name to be specified as the map key for each key:value pair. The key names must be the same name as given below.
<value> is the value as submitted in the Zoho Creator form, for a given key.
<Inv Response> is the map variable returned by Zoho Invoice as response.

Key names to create an invoice with a single item:

  • CustomerName - To specify the customer name. (Mandatory)
  • PONumber - To specify the reference of an associated document with the invoice, e.g. a project code or a purchase order number.
  • DueDate - To specify the date by which the payment has to be made. By default, date will be calculated based on the customer payment terms.
  • ItemName - To specify a single item. (Mandatory)
  • ItemRate - To specify rate of the given item. If rate is not specified, it will be displayed as "0" in the invoice. (Optional)
  • ItemDescription - To specify description for the given item.
  • Quantity - To specify the quantity of the item ordered. If quantity is not specified, it will be displayed as "1" in the invoice. (Optional)
  • Discount - To add discount to the given item. (Optional)
  • Tax1Name, Tax2Name - To add any taxes to the given item. Only existing Taxes in Zoho Invoice can be sent as params. (Optional)
  • CustomField1, CustomField2, CustomField3 - To specify values for the custom fields. (Optional)

Paypal related information:

  • Paypal - <! Allowed values:0 -> Not Selected, 1 -> PayPal Standard, 2 -> PayPal Business Payments -->
  • Authorize.Net - <!-- Allowed values: true / false -->
  • GoogleCheckOut - <!-- Allowed values: true / false -->

Note:

  • PayPal information should be given in a separate map and that map should be passed in the invoice task as shown in the example below.
    gateWays = { "PayPal" : input.PayPal, "Authorize.Net" : input.Authorize_Net, "GoogleCheckout" : input.GoogleCheckout };
    resp = zoho.invoice.createinvoice({ "CustomerName" : input.Customer_Name, "ItemName" : input.ItemName, "ItemRate" : input.ItemRate, "Quantity" : input.Quantity, "InvoiceDate" : input.Invoice_Date, "PaymentGateways" : gateWays }, false);
    //The second argument is a boolean whether to send Invoice to the customer.

Key names to create an invoice with multiple items :

  • CustomerName - To specify the customer name. (Mandatory)
  • Items - To specify multiple items whose value will be passed as a list with ItemName, ItemRate and Quantity. (Mandatory)
  • CustomField1, CustomField2, CustomField3 - To specify values for the custom fields. (Optional)

Note:

  • If a customer already exists in Zoho Invoice with the given customer name,
    • The item rate will be taken based on the currency specified in customer details
    • Due-date will be calculated based on payment terms provided in customer details. Due-date must be specified in YYYY-MM-DD format if not specified already in Zoho Creator.
  • We have not supported param to pass Invoice number, so enable auto generation Invoice number in Zoho Invoice
  • To use existing items present in Zoho Invoice, pass only the ItemName as created in Zoho Invoice.
  • Only existing Taxes in Zoho Invoice can be sent as params.

Zoho Accounts being part of more than one organization

Following is the syntax for zoho login that are part of more than one organization. The second argument must be a boolean whether to send Invoice to the customer and third argument should be the company name as given in the organization profile of the Zoho Invoice Account.

gateWays = { "PayPal" : input.PayPal, "Authorize.Net" : input.Authorize_Net, "GoogleCheckout" : input.GoogleCheckout }; resp = zoho.invoice.createinvoice({ "CustomerName" : input.Customer_Name, "ItemName" : input.ItemName, "ItemRate" : input.ItemRate, "Quantity" : input.Quantity, "InvoiceDate" : input.Invoice_Date, "PaymentGateways" : gateWays }, false, "Test");

Example to create an invoice with a single item

The steps to create an invoice with single item from Creator form is described below:

  1. Create a Form in Zoho Creator with the required fields, as shown in the screen-shot below:

2. Select Settings Icon -> Add Record -> Record Add from the Form header. This will display the Script Editor in the Workflow tab with the Form Actions -> On add -> On Success block selected in the left-side tree.

3. In the editor area, write the Deluge script to populate the INVOICE data in Zoho Invoice, in the format given below.

4. Click Save Script to save the script The sample code is given below for reference.

input.Invoice_Detail_Status = zoho.invoice.createinvoice({ "CustomerName" : input.Customer_Name, "ItemName" : input.Item_Name,
"ItemRate" : input.Item_Rate, "Quantity" : input.Quantity });

Code Explanation:

In the above code, zoho.invoice.createinvoice will create a new invoice in Zoho Invoice with the specified Customer Name, Item Name, Item Rate and Quantity as specified in Zoho Creator form. Invoice_Detail_Status which is a hidden field in the form will be updated with the response from Zoho Invoice.

When the end-user fills the form and clicks the submit button it automatically creates the invoice in Zoho Invoice, as shown in the screen-shot below.

Sample Response Format

{
"TemplateType":"1",
"CreatedTimeInMillis":"1356517962734",
"InvoiceID":"141995000000137005",
"InvoiceDate":"30 Dec 2012",
"LateFeeAmount":"Rs.0.00",
"_DueDate":"2012-12-30",
"Payment":"Rs.0.00",
"AllowPartialPayments":"false",
"_LateFeeAmount":"0.000",
"DecimalPlace":"2",
"PaymentMade":"Rs.0.00",
"Balance":"Rs.945.00",
"GoogleCheckout":"true",
"Authorize.Net":"true",
"Items":
"[
{
ItemID=141995000000137009,
Quantity=21.000000,
_Price=45.000000,
ProductID=,
Tax2Name=,
Tax2ID=,
Tax1Type=0,
Tax1ID=,
Tax1Name=,
Tax1Percentage=,
ItemName=Test
Price=Rs.45.00,
ItemTotal=Rs.945.00,
Tax2Percentage=,
Discount=0.00,
Tax2Type=0,
ItemDescription=
}
]","
TemplateName":"Classic",
"_Balance":"945.000",
"PaymentsDue":"Due On Receipt",
"CreatedTime":"2012-12-26 16:02:42 IST",
"DueDate":"30 Dec 2012",
"_PaymentsDue":"0",
"PONumber":"","_InvoiceDate":"2012-12-30",
"CurrencyCode":"INR",
"InvoiceNumber":"INV-573",
"CustomerName":"Ayisha",
"Source":"3",
"Status":"Draft",
"ExchangeRate":"1.000000",
"InvoiceItemTotal":"Rs.945.00",
"CustomerID":"141995000000139007",
"CreditsApplied":"Rs.0.00",
"TaxTotal":"Rs.0.00",
"PayPal":"Standard",
"LastModifiedTime":"2012-12-26 16:02:42 IST",
"InvoiceView":"http://invoice.zoho.com:80/ZB_SecurePaymentOption.cc CInvoiceID=985f5369cbdc35f3ceeab0226",
"Total":"Rs.945.00"
}

Example to create an invoice with multiple items

The steps to create an invoice with multiple items is described below:

1. Create a form in Zoho Creator with the required items, as shown in the screen-shot below.

2. Select Settings Icon -> Add Record -> RecordAdd from the Form header. This will display the Script Editor in the Script tab with the Form Actions -> On add -> On Success block selected in the left-side tree.

3. In the editor area, write the Deluge script to populate the INVOICE data in Zoho Invoice, in the format given below. The sample code is given below for reference.

Note:

The zoho.invoice.createinvoice task is not supported in Script Buider GUI. You have to select the Free-flow scripting link and add the required code.

itemsList = List:Map();
itemsList.add({ "ItemName" : "Hard Drive", "ItemRate" : "100", "Quantity" : input.Hard_Drive_100 });
itemsList.add({ "ItemName" : "Floppies", "ItemRate" : "30", "Quantity" : input.Floppies_30 });
itemsList.add({ "ItemName" : "Keyboard", "ItemRate" : "120", "Quantity" : input.Keyboard_120 });
if (input.Make_Invoice_Open)
{
input.Invoice_Detail_Status = zoho.invoice.createinvoice({ "CustomerName" : input.Customer_Name, "Items" : itemsList });
}
else
{
input.Invoice_Detail_Status = zoho.invoice.createdraft({ "CustomerName" : input.Customer_Name, "Items" : itemsList });
}

Code Explanation:

  • itemList is a list variable that will hold the list of ItemName, ItemRate and Quantity.
  • itemList.add() will add each item to the list
  • zoho.invoice.createinvoice () will create an invoice in Zoho invoice with "open" status with the specified Customer Name and Item list.
  • zoho.invoice.createidraft () will create an invoice in Zoho invoice with "draft" status with the specified Customer Name and Item list.
  • Invoice_Detail_Status which is a hidden field in the form will be updated with the response from Zoho Invoice.

On submit, the record is added to Zoho Invoice as shown in the screen-shot below with multiple items.

Sample Application

Please refer the Zoho Creator sample application CRM-Creator-Invoice Integration

Related Links

http://www.zoho.com/invoice/api/invoices/invoices.html#how-do-i-add-an-Invoice?

Top