Creator Help

Create Zoho Invoice

Overview

You can use Zoho Creator Form to collect information and populate it in Zoho Invoice to create an invoice with "Draft" / "Open" status. The Deluge task zoho.invoice.createdraft() will create 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() will create 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 information should be given in a separate map and that map should passed in the invoice task

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

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, if due date is not specified in Zoho Creator,
  • DueDate must be specified in YYYY-MM-DD format.
  • 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.

Example

Sample script to create an invoice .The second argument must be a boolean whether to send Invoice to the customer.

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);

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