## Zoho Invoice — Product, features, payments, integrations, solutions, and help Index

Access the complete documentation index at:
https://www.zoho.com/invoice/llms.txt

Use this file to discover all available documentation pages before proceeding.

# Software Development Kit methods

### Init

This is the first method to add for initializing the widgets.

```js
var ZInvoiceClient =  ZFAPPS.extension.init();

ZInvoiceClient.then(function(app) {    
   /* Below is an example to get the user name */
   ZFAPPS.get('organization').then(function (data) {
      //response Handling
   }).catch(function (err) {
      //error Handling
   });    
});
```

### Get

This method is used to request data from the source. In Zoho Invoice, you can fetch the details of the organization, user, invoice and other entities using this method. You can look into the different [‘get’ supported entity keys here](/invoice/developer/widgets/supported-entity-keys.html).

```js
ZFAPPS.get('invoice').then(function (data) {
    //response Handling
}).catch(function (err) {
    //error Handling       
});
```

##### **Response:**

```json
{
  "invoice": {
    "invoice_id": "112233",
    "invoice_number": "INV-000006",
    "salesorder_id": "",
    "salesorder_number": "",
    "crm_owner_id": "",
    "zcrm_potential_id": "",
    "zcrm_potential_name": "",
    "date": "2018-08-25",
    "date_formatted": "25 Aug 2019",
    "status": "paid",
    "status_formatted": "Paid",
    "amount": 101,
    "amount_formatted": "$101.00",
    .......
   }
}
```

### Set

The set method is used to set a module param while creating the transaction. For example, In Zoho Invoice, while creating the invoice you can modify the invoice params using this set handler.

To set invoice **reference number** from rendered sidebar widget:

```js
ZFAPPS.set('invoice.reference_number', '001122').then(function (data) {
  //response Handling
}).catch(function (err) {
  //error Handling
});
```

**Response:**

```json
{
   "invoice": {
      "invoice_id": "112233",
      "invoice_number": "INV-00006",
      "reference_number": "001122",
      .......
   }


}
```

### Request

This method is used to invoke a third-party API or Zoho Invoice API from the widget. The **connection\_link\_name** defined in the plugin-manifest.json file will be invoked.

**Notes:** Sometimes, you need data from a third-party service that doesn’t need authorization. In that case, you do not need to add **connection\_link\_name** in the options.

```js
var options = {
  url: 'https://desk.zoho.com/api/v1/tickets/',
	method: "GET/PUT/POST/DELETE" ,
	url_query: [{
		key: 'QUERY_NAME',
		value: 'QUERY_VALUE'
	}],
	header:[{
		key: 'header-key',
		value: 'header-value'
	}],
	body: {
		mode: 'urlencoded/formdata/raw',
		urlencoded: [{
			key: 'KEYNAME',
			value: 'VALUE',
			type: 'encodedType'
		}],
		formdata: [{
			key: 'KEYNAME',
			value: 'VALUE'
		}],
		raw: 'RAWDATA'
	},
	connection_link_name: 'zohodeskconnection'
};


ZFAPPS.request(options).then(function(value) {
    //response Handling
    let responseJSON = JSON.parse(data.body);
}).catch(function(err) {
    //error Handling
});
```

**Response:**

```json
{
   "code": "",
   "message": "Triggered Successfully",
   "data":{
      "body": {} // response of third party service
   }
}
```

Name

Type

Description

options

Object

Key

Type

Description

url

URL

URL of the third-party service.

method

String

Mention the type (GET/POST) of the request.

url\_query(optional)

Array

Parameters of the request. { key : 'ParamName', value: 'ParamValue' }

header(optional)

Array

Header of the request. { key : 'HeaderName', value: 'HeaderValue' }.

connection\_link\_name(optional)

String

Value mentioned in the plugin-manifest.json.

attachments(optional)

Array

Attachment for payload request. { key : 'param name to send as' , value: file Instance }  
Example, Zoho Invoice document upload API( /api/v3/documents)  
attachments: \[ { key: 'document', value: fileInstance }\]

body(optional)

Object

Key

Description

mode

Mode should either be **urlencoded, formdata or raw.**  
Based on these modes, other keys are not needed.

urlencoded

Array of key, value, and encodedType.

formdata

Array of key and value.

raw

rawdata

### Invoke

The invoke method is used to perform custom actions. It accepts two arguments, the name of an event that has to be trigged as the first argument and the corresponding value to the event that is passed as an object for the second argument.

Currently Zoho Invoice supports **RESIZE** and **REFRESH\_DATA** options.

#### Resize

By default, Zoho Invoice supports a sidebar widget with a width of 350px. In case, you want to resize the widget, you can invoke the below **RESIZE** method:

```js
ZFAPPS.invoke('RESIZE', { width: '100px', height: '100px'})
	.then(() => { console.log('Resized successfully');
});
```

#### Refresh Data

Let’s say you have a widget in the invoice details sidebar, and you want to trigger an API for changing the status of an invoice from **Draft** to **Sent**, but the status has not been updated in the invoice details page. In that case, to view the updated changes, the page needs to be reloaded.

Here is an example for refreshing the invoice details page:

```js
ZFAPPS.invoke('REFRESH_DATA', 'invoice')
	.then(() => { console.log('Reloaded successfully');
});
```

### Data Storage

Sometimes, the widgets you create might require data storage and retrieval capabilities. To help you in such cases, a data store is available to set **store** and get **retrieve** data.

The following APIs provide database management functionalities to widgets:

*   [store](/invoice/developer/widgets/sdk-method.html#store)
*   [retrieve](/invoice/developer/widgets/sdk-method.html#retrieve)

**Notes:** The key’s value can be a maximum of 20 characters.

#### Store

```js
ZFAPPS.store(`api_key`, {
   value: 'xxxxx'
}).then(function (data) {
    //response Handling
}).catch(function (err) {
    //error Handling
});   

ZInvoiceClient.then(async function(App) {
   let user = await ZFAPPS.get('user.zuId');
   let user_id = user['user.zuId'];

   ZFAPPS.store(`api_key_${user_id}`, {
	value: 'xxxxx',
	visiblity: 'onlyme'
   }).then(function (data) {
      //response Handling
   }).catch(function (err) {
      //error Handling
   });    
});
```

**Response:**

```json
{
    "messgage": "Stored Successfully",
    "api_key_XXXXX": "xxxxx"
}
```

Argument Name

Data Type

Description

Argument 1(Key)

String

Data to be stored corresponding to the key.

Argument 2 (ValueObject)

Object

Key

Description

value

Value of the specified key.

visibility

This option displays the key based on the visibility. You can choose **Only me** if you want the key to be visible to you alone, and **Everyone**, if you want to give access to everyone in the organisation.  
By default it will be marked as **Everyone**  
  
**Note: If the visibility is set to "onlyme", you have to affix the user\_id along with the param to store and retrieve data.Ex. api\_key\_${user\_id}**

#### Retrieve

Retrieves data from the data store.

```js
ZFAPPS.retrieve('api_key').then(function (data) {
     //response Handling
}).catch(function (err) {
   //error Handling
});

//If visibllity of param is onlyme, append the user_id to retrive it
ZInvoiceClient.then(async function(App) {  
   let user = await ZFAPPS.get('user.zuId');
   let user_id = user['user.zuId'];

   ZFAPPS.retrieve(`api_key_${user_id}`).then(function (data) {
            //response Handling
   }).catch(function (err) {
            //error Handling
   });    
});
```

**Response:**

```json
{
    "messgage": "Retrived Successfully",
    "api_key_XXXXX": "xxxxx"
}
```

### Event APIs

You can configure the widget to receive information when an event occurs, such as, when adding a line item in an invoice or changing the customer while creating the invoice.

#### On Change

While you add/modify the input params like customer, entity\_number, date, items etc., in Zoho Invoice, it’ll broadcast the event change. You can see the event and process the updated data.

Supported modules:  
Invoice - **ON\_INVOICE\_CHANGE**  
Estimate - **ON\_ESTIMATE\_CHANGE**  
Sales orders - **ON\_SALESORDER\_CHANGE**  
Customer - **ON\_CUSTOMER\_CHANGE**  
Vendor - **ON\_VENDOR\_CHANGE**  
Creditnote - **ON\_CREDITNOTE\_CHANGE**  
Retainer Invoice - **ON\_RETAINERINVOICE\_CHANGE**  

```js
ZInvoiceClient.then(function(App) {     
   App.instance.on('ON_INVOICE_CHANGE', function () {
	// Actions
   });  
});
```

#### On Preview

In the transaction details page, when the customer transitions between the entity records, Zoho Invoice will broadcast the on\_preview event. So you can see the event and process the updated data.

Supported modules:  
Invoice - **ON\_INVOICE\_PREVIEW**  
Estimate - **ON\_ESTIMATE\_PREVIEW**  
Salesorder - **ON\_SALESORDER\_PREVIEW**  
Customer - **ON\_CUSTOMER\_PREVIEW**  
Vendor - **ON\_VENDOR\_PREVIEW**  
Creditnote - **ON\_CREDITNOTE\_PREVIEW**  
Retainer Invoice - **ON\_RETAINERINVOICE\_PREVIEW**  

```js
ZInvoiceClient.then(function(App) {     
   App.instance.on('ON_INVOICE_PREVIEW', function () {
	// Actions
   });  
});
```

#### Saved

After the transaction is created, Zoho Invoice will broadcast the saved event. You can watch the event and write the required action to be triggered after the transaction is saved.

**Notes:** The saved event can be seen only by the background widgets.

Supported modules:  
Invoices - **INVOICE\_SAVED**  
Estimates - **ESTIMATE\_SAVED**  
Customer - **CUSTOMER\_SAVED**  
Creditnote - **CREDITNOTE\_SAVED**  

```js
ZInvoiceClient.then(function(App) {     
   App.instance.on('INVOICE_SAVED', function () {
	// Actions
   });  
});
```

#### Pre Save

After the transaction is created, Zoho Invoice will broadcast before the saved event. You can watch the event and write the required action to be triggered before the transaction is saved.

**Notes:** The saved event can be seen only by the background widgets.

Supported modules:  
Invoices - **ON\_INVOICE\_PRE\_SAVE**

```js
ZInvoiceClient.then(function(App) {     
   App.instance.on('ON_INVOICE_PRE_SAVE', function () {
      // Actions Return false if you want to prevent from saving
      return new Promise((resolve, reject) => {
         resolve({
            prevent_save: false,
         });
      });
   });  
});
```

### Modal

#### Show Modal

Display widget as a modal in the application.

**Notes:** If you want to display the widget as a modal instead of a sidebar, you’ll have to add **“widget\_type” : “modal”** in the plugin-manifest.json for that specific widget.

```js
ZInvoiceClient.then(function(App) {     
   ZFAPPS.showModal({
        url: "/app/modal.html#/?route=modal"
   });
});
```

#### Close Modal

You can use the following method to close the modal.

```js
ZInvoiceClient.then(function(App) {     
    ZFAPPS.closeModal();
});
```