Creator Help

Create Records in Zoho Invoice

 Overview

The zoho.invoice.create() task can be executed to add a record in any of the supported modules of Zoho Invoice. By placing it in the required form actions block of Zoho Creator, the process of creating records in Zoho Invoice can easily be automated as per requirement. Lets say we have a Zoho Creator form which is used by users to order certain products. To create the customer(user) contact simultaneously in our Zoho Invoice's "Contacts" module, you can execute zoho.invoice.create() task in the “On Success” form actions block. This will create a record in Zoho Invoice whenever the Zoho Creator form is submitted with customer's details. Further details on how to execute this task are explained below.

 Supported Modules

  • Invoices
  • CustomerPayments
  • Items
  • Contacts
  • Expenses
  • Estimates
  • ExpenseCategory

 Syntax

response =zoho.invoice.create(module_name, organisation_id, {data_map})

where,
<response> - is the map variable returned by Zoho Invoice as response. 
<moduleName> - name of module in Zoho Invoice where the record will be added. (mandatory)
<organisation_id> - required org id in which the records will be added. (mandatory)
<dataMap> - map variable that holds the key,value pairs. The map key is the label name as specified in Zoho Invoice module and the map value is the field value as submitted in the ZC form. For example, "First Name" : input.First_Name . Here, "First Name" is the the label name as specified in Zoho Invoice module and input.First_Name refers to the value specified in the First_Name field in the Zoho Creator form. (mandatory)

 Examples

1) Let's say we have a Creator form which is used to order certain products. This form consists of fields,

  • Contact Name
  • Company Name
  • Address
  • City
  • State
  • Zip
  • Country
  • Fax

You can add the following script to On Add -> On Success block of the Creator Form so that whenever this form is submitted, a record is created in Zoho Invoice's specified module with specified details. In this case, the module is "Contacts".

values = map();
values.put("contact_name" , input.Contact_Name);
values.put("company_name" , input.Company_Name);
            
addressDetails = map();
addressDetails.put("address", input.Address);
addressDetails.put("city", input.City);
addressDetails.put("state", input.State);
addressDetails.put("zip" , input.Zip);
addressDetails.put("country", input.Country);
addressDetails.put("fax", input.Fax);
 
values.put("billing_address" , addressDetails);

 

response = zoho.invoice.create("Contacts", "10982991", values );

where,
response - is the map variable returned by Zoho Invoice as response. 
Contacts - name of module in Zoho Invoice where the record will be added.
10982991 - sample Org ID where the records will be added.
Map values contain keynames of Invoice fields in quotes followed by it's value(form field input).

2) Let's take an example of creating an invoice in Zoho Invoice. Assume we have a Creator form used to store invoice details. The Form consists of the following fields:

  • Invoice Number
  • Customer Name
  • Date
  • Products Subform with fields Item Name, Rate and Quantity

We will first fetch the Customer ID to which the invoice has to be linked. This can be achieved using the following code

resp = zoho.invoice.getRecords("contacts", "10982991", "", input.Customer_Name);
detail = (resp.get("contacts").toJSONList().get(0)).toMap();
customer_id = detail.get("contact_id");

To create an invoice in Zoho Invoice whenever the Form is submitted, add the following script in On Add > On Success block of the form:

itemsList = list();
 for each record in Products
  {
     item = map();
     item.put("name", record.Item_Name );
     item.put("rate", record.Rate);
     item.put("quantity", record.Quantity);
     itemsList.add(item);
  }

values = map();
values.put("customer_id" , customer_id); 
values.put("invoice_number", input.Inv_number);
values.put("date" , input.Date);
values.put("line_items", itemsList);

response = zoho.invoice.create("Invoices", "10982991" , values);

where,
response - is the map variable returned by Zoho Invoice as response. 
Invoice - name of module in Zoho Invoice where the record will be added.
10982991 - sample Org ID where the records will be added.
Map values contain keynames of Invoice fields in quotes followed by it's value(form field input).

 Response

Response returned by Zoho Invoice for example 1 as map:

{
    "code": 0,
    "message": "The contact has been added.",
    "contact": {
        "contact_id": "219715000000070001",
        "contact_name": "sample",
        "company_name": "",
        "website": "",
        "language_code": "",
        "language_code_formatted": "",
        "contact_salutation": "",
        "is_client_review_asked": false,
        "has_transaction": false,
        "contact_type": "customer",
        "owner_id": "",
        "owner_name": "",
        "source": "api",
        "is_crm_customer": false,
        "is_linked_with_zohocrm": false,
        "primary_contact_id": "",
        "zcrm_account_id": "",
        "zcrm_contact_id": "",
        "payment_terms": 0,
        "payment_terms_label": "Due On Receipt",
        "currency_id": "219715000000000099",
        "currency_code": "INR",
        "currency_symbol": "Rs.",
        "price_precision": 2,
        "outstanding_receivable_amount": 0,
        "outstanding_receivable_amount_bcy": 0,
        "unused_credits_receivable_amount": 0,
        "unused_credits_receivable_amount_bcy": 0,
        "status": "active",
        "payment_reminder_enabled": true,
        "is_client_review_settings_enabled": false,
        "average_client_rating": "-0.0",
        "custom_fields": [],
        "billing_address": {
            "address": "",
            "city": "",
            "state": "",
            "zip": "",
            "country": "",
            "fax": ""
        },
        "shipping_address": {
            "address": "",
            "city": "",
            "state": "",
            "zip": "",
            "country": "",
            "fax": ""
        },
        "contact_persons": [],
        "pricebook_id": "",
        "pricebook_name": "",
        "default_templates": {
            "invoice_template_id": "",
            "invoice_template_name": "",
            "estimate_template_id": "",
            "estimate_template_name": "",
            "creditnote_template_id": "",
            "creditnote_template_name": "",
            "paymentthankyou_template_id": "",
            "paymentthankyou_template_name": "",
            "invoice_email_template_id": "",
            "invoice_email_template_name": "",
            "estimate_email_template_id": "",
            "estimate_email_template_name": "",
            "creditnote_email_template_id": "",
            "creditnote_email_template_name": "",
            "paymentthankyou_email_template_id": "",
            "paymentthankyou_email_template_name": ""
        },
        "associated_with_square": false,
        "cards": [],
        "checks": [],
        "bank_accounts": [],
        "notes": "",
        "created_time": "2016-02-08T13:21:54+0530",
        "last_modified_time": "2016-02-08T13:21:54+0530"
    }
}

Response returned by Zoho Invoice for example 2 as map:

{
    "code": 0,
    "message": "The invoice has been created.",
    "invoice": {
        "invoice_id": "219715000000070007",
        "invoice_number": "INV-000017",
        "zcrm_potential_id": "",
        "zcrm_potential_name": "",
        "date": "2016-02-08",
        "status": "draft",
        "payment_terms": 0,
        "payment_terms_label": "Due On Receipt",
        "due_date": "2016-02-08",
        "payment_expected_date": "",
        "stop_reminder_until_payment_expected_date": false,
        "last_payment_date": "",
        "reference_number": "",
        "customer_id": "219715000000070001",
        "estimate_id": "",
        "is_client_review_settings_enabled": false,
        "customer_name": "sunil",
        "contact_persons": [],
        "currency_id": "219715000000000099",
        "currency_code": "INR",
        "currency_symbol": "Rs.",
        "exchange_rate": 1,
        "discount": 0,
        "discount_applied_on_amount": 0,
        "is_discount_before_tax": true,
        "discount_type": "item_level",
        "recurring_invoice_id": "",
        "documents": [],
        "is_viewed_by_client": false,
        "client_viewed_time": "",
        "is_inclusive_tax": false,
        "line_items": [
           {
               "line_item_id": "219715000000070015",
               "item_id": "",
               "salesorder_item_id": "",
               "project_id": "",
               "time_entry_ids": "",
               "expense_id": "",
               "expense_receipt_name": "",
               "name": "Hard Drive",
               "description": "500GB, USB 2.0 interface 1400 rpm, protective hard case.",
               "item_order": 1,
               "bcy_rate": 120,
               "rate": 120,
               "quantity": 1,
               "unit": "",
               "discount_amount": 0,
               "discount": 0,
               "tax_id": "",
               "tax_name": "",
               "tax_type": "tax",
               "tax_percentage": 0,
               "item_total": 120,
               "documents": []
           }
        ],
        "shipping_charge": 0,
        "adjustment": 0,
        "adjustment_description": "",
        "late_fee": {
            "name": "",
            "type": "percentage",
            "rate": 0,
            "amount": 0,
            "frequency_type": "month"
        },
        "sub_total": 120,
        "tax_total": 0,
        "total": 120,
        "taxes": [],
        "payment_reminder_enabled": true,
        "payment_made": 0,
        "credits_applied": 0,
        "tax_amount_withheld": 0,
        "balance": 120,
        "write_off_amount": 0,
        "allow_partial_payments": false,
        "price_precision": 2,
        "payment_options": {
            "payment_gateways": []
        },
        "is_emailed": false,
        "reminders_sent": 0,
        "last_reminder_sent_date": "",
        "billing_address": {
            "address": "",
            "city": "",
            "state": "",
            "zip": "",
            "country": "",
            "fax": ""
        },
        "shipping_address": {
            "address": "",
            "city": "",
            "state": "",
            "zip": "",
            "country": "",
            "fax": ""
        },
        "notes": "Thanks for your business.",
        "terms": "",
        "custom_fields": [],
        "template_id": "219715000000043021",
        "template_name": "Grand",
        "template_type": "grand",
        "created_time": "2016-02-08T13:26:53+0530",
        "last_modified_time": "2016-02-08T13:26:53+0530",
        "created_by_id": "219715000000043001",
        "attachment_name": "",
        "can_send_in_mail": false,
        "salesperson_id": "",
        "salesperson_name": "",
        "is_autobill_enabled": false,
        "invoice_url": "https://invoice.zoho.com/portal/sampletest/secure?CInvoiceID=2-576e0c8724661463e3ad3e00ecf1cf09a0fd32de6df1ccd4e6cddd11545a3935460d2a05eb636b8d30214a816848de1cc28700b0dfd6eff4"     }
}

Failure Response:

{"message":"Invalid value passed for contact_name","code":4}

Share this post : FacebookTwitter

Still can't find what you're looking for?

Write to us: support@zohocreator.com