Create record in Zoho Billing

Table of Contents

Note:

  • Each time the zoho.billing.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.billing.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 Billing. This task is based on Zoho Billing API <ModuleName> -> Create a <ModuleName>.

Syntax

 <variable> = zoho.billing.create(<module_name>, <org_id>, <data_map>, <connection>);

where:

ParameterData typeDescription
<variable>KEY-VALUEis the variable response returned by Zoho Billing.
<module_name> TEXTis the name of the module in where the record will be added.
<org_id>TEXT

Org ID of the organization in which the record will be created.c

Note: Learn how to fetch organization ID from the UI and from the response of zoho.billing.getOrganization task.
<data_map>KEY-VALUE

Input map with key as Zoho Billing field's name and the required value. For ex: {"display_name":input.Last_Name}

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

<connection>TEXT

specifies the link name of the Zoho Billing connection.

Note:

  • In view of stopping new authtoken generation, a Zoho OAuth connection with appropriate scopes is mandatory in order for new integration tasks (created after the deadline specified in the post) to work as expected. Existing integration tasks will continue to work with or without the connections parameter until you manually delete the authtoken from accounts.
  • Add relevant scopes mentioned in Zoho Billing API while creating the connection.
  • Refer to this post for the list of Zoho services that support the connections page.
  • Learn more about connections

Examples

1) Let's say we have a Zoho Creator form containing fields Customer_ID, and Plan code. On submission of this form, a subscription must be created in Zoho Billing with the details specified in the form. We can achieve this using the following snippet:

values = map();
values.put("customer_id", input.Customer_ID);
values.put("auto_collect", false);
values.put("plan", {"plan_code" : input.Plan_Code});
response = zoho.billing.create("Subscriptions", "66XXXXX66", values, "billing_connection");

where,

 values
is a MAP variable which hold key value pairs required to create a subscription
 "auto_collect"
 "plan"
 "plan_code"
 "customer_id"
are the TEXT that represents the label name of the field specified in Zoho Billing API. Customer ID can be viewed in the url in Zoho Billing when you click on a Customer record.
"Subscriptions"
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 Billing account in which the record needs to be created
"billing_connection"
is the TEXT that represents the link name of the Billing connection

2) Let’s take an example of creating a record in the "Customers" module in Zoho Billing using the following snippet.

 values=map();
 values.put("display_name","john");
 values.put("email","john@zylker.com");
 
 response = zoho.billing.create("Customers", "66XXXXX66​", values, "billing_connection");

where:

 values
is a MAP variable which hold key value pairs required to create a subscription
 "display_name"
 "email"
are the TEXT that represents the label name of the field specified in Zoho Billing API. 
"Customers"
is the TEXT that represents the module in which the record will be created
"billing_connection"
is the TEXT that represents the link name of the Billing connection

Sample Response

The following is a sample success response:

{  
   "message":"The customer has been added.",
   "code":0,
   "customer":{  
      "default_templates":{  
         "creditnote_template_id":"",
         "invoice_template_id":""
      },
      "phone":"",
      "payment_terms":0,
      "payment_terms_label":"Due On Receipt",
      "price_precision":2,
      "updated_time":"2015-03-10",
      "outstanding_receivable_amount":0,
      "shipping_address":{  
         "zip":"",
         "fax":"",
         "street":"",
         "state":"",
         "country":"",
         "city":""
      },
      "first_name":"",
      "company_name":"",
      "zcrm_contact_id":"",
      "currency_symbol":"Rs.",
      "outstanding":0,
      "currency_code":"INR",
      "custom_fields":"[]",
      "currency_id":"115888000000000099",
      "status":"active",
      "pricebook_id":"115888000000011001",
      "zcrm_account_id":"",
      "unused_credits":0,
      "display_name":"zoho",
      "email":"zohocorp@gmail.com",
      "last_name":"",
      "created_time":"2015-03-10",
      "notes":"",
      "customer_id":"115888000000046001",
      "mobile":"",
      "billing_address":{  
         "zip":"",
         "fax":"",
         "street":"",
         "state":"",
         "country":"",
         "city":""
      }
   }
}

To fetch the ID of the record from the returned response, use the following snippet:

info <response_variable>.get("<module_name>").get("<module_name>_id">
// example for <module_name> is customer and example for <module_name>_id is customer_id

The following is a sample failure response:

{
"message":"Enter valid Customer Name",
"code":3013
}

Related Links