Retainer Invoices

The Retainer Invoices module allows widgets to access retainer invoice context related to advance payments. It exposes identifiers and conversion-related information. This module supports extensions for advance billing and invoice adjustments.

Methods

Methods

Get Retainerinvoice Details

Retrieves data related to the current context. This method allows your widget to fetch record details, field values, or metadata required for rendering or processing logic.

Commonly used for :

• Fetch record information
• Read field values
• Access contextual module data

Supported Locations :

retainerinvoice.details.sidebarretainerinvoice.creation.sidebar

Sample Code :

REQUEST DETAILS

window.onload = function () {
  ZFAPPS.extension.init().then(function(App) {
    ZFAPPS.get('retainerinvoice').then(function (data) {
     //response Handling
    }).catch(function (err) {
     //error Handling
    });
  });
}

Supported Input Keys :

Property	Request
retainerinvoice_id	retainerinvoice.retainerinvoice_id
retainerinvoice_number	retainerinvoice.retainerinvoice_number
date	retainerinvoice.date
date_formatted	retainerinvoice.date_formatted
status	retainerinvoice.status
status_formatted	retainerinvoice.status_formatted
last_payment_date	retainerinvoice.last_payment_date
last_payment_date_formatted	retainerinvoice.last_payment_date_formatted
reference_number	retainerinvoice.reference_number
customer_id	retainerinvoice.customer_id

Show More Supported Input Keys

Property	Request
branch_id	retainerinvoice.branch_id
roundoff_value	retainerinvoice.roundoff_value
roundoff_value_formatted	retainerinvoice.roundoff_value_formatted
transaction_rounding_type	retainerinvoice.transaction_rounding_type
tax_treatment	retainerinvoice.tax_treatment
place_of_supply	retainerinvoice.place_of_supply
place_of_supply_formatted	retainerinvoice.place_of_supply_formatted
customer_name	retainerinvoice.customer_name
contact_persons	retainerinvoice.contact_persons
currency_id	retainerinvoice.currency_id
currency_code	retainerinvoice.currency_code
currency_symbol	retainerinvoice.currency_symbol
exchange_rate	retainerinvoice.exchange_rate
is_viewed_by_client	retainerinvoice.is_viewed_by_client
unused_retainer_payments	retainerinvoice.unused_retainer_payments
unused_retainer_payments_formatted	retainerinvoice.unused_retainer_payments_formatted
client_viewed_time	retainerinvoice.client_viewed_time
client_viewed_time_formatted	retainerinvoice.client_viewed_time_formatted
is_inclusive_tax	retainerinvoice.is_inclusive_tax
tax_rounding	retainerinvoice.tax_rounding
line_items	retainerinvoice.line_items
sub_total	retainerinvoice.sub_total
sub_total_formatted	retainerinvoice.sub_total_formatted
total	retainerinvoice.total
total_formatted	retainerinvoice.total_formatted
taxes	retainerinvoice.taxes
payment_made	retainerinvoice.payment_made
payment_made_formatted	retainerinvoice.payment_made_formatted
payment_drawn	retainerinvoice.payment_drawn
payment_drawn_formatted	retainerinvoice.payment_drawn_formatted
balance	retainerinvoice.balance
balance_formatted	retainerinvoice.balance_formatted
allow_partial_payments	retainerinvoice.allow_partial_payments
price_precision	retainerinvoice.price_precision
payment_options	retainerinvoice.payment_options
is_emailed	retainerinvoice.is_emailed
contact_persons_associated	retainerinvoice.contact_persons_associated
payments	retainerinvoice.payments
payment_refunds	retainerinvoice.payment_refunds
documents	retainerinvoice.documents
comments	retainerinvoice.comments
billing_address	retainerinvoice.billing_address
shipping_address	retainerinvoice.shipping_address
notes	retainerinvoice.notes
terms	retainerinvoice.terms
custom_fields	retainerinvoice.custom_fields
template_id	retainerinvoice.template_id
template_name	retainerinvoice.template_name
template_type	retainerinvoice.template_type
template_type_formatted	retainerinvoice.template_type_formatted
created_time	retainerinvoice.created_time
last_modified_time	retainerinvoice.last_modified_time
created_by_id	retainerinvoice.created_by_id
last_modified_by_id	retainerinvoice.last_modified_by_id
attachment_name	retainerinvoice.attachment_name
invoice_url	retainerinvoice.invoice_url
submitted_date	retainerinvoice.submitted_date
submitted_date_formatted	retainerinvoice.submitted_date_formatted
submitted_by	retainerinvoice.submitted_by
approvers_list	retainerinvoice.approvers_list

Set Retainerinvoice Details

Updates or sets data within the current context. This method allows your widget to modify field values, update state, or pass data back to the host application.

Commonly used for :

• Update field values
• Set widget or module state
• Pass data to the parent application

Supported Locations :

retainerinvoice.creation.sidebar

Sample Code :

REQUEST DETAILS

window.onload = function () {
  ZFAPPS.extension.init().then(function(App) {
    ZFAPPS.set('retainerinvoice.name', <value>).then(function (data) {
     //response Handling
    }).catch(function (err) {
     //error Handling
    });
  });
}

Supported Input Keys :

Property	Request
retainerinvoice_id	retainerinvoice.retainerinvoice_id
retainerinvoice_number	retainerinvoice.retainerinvoice_number
date	retainerinvoice.date
date_formatted	retainerinvoice.date_formatted
status	retainerinvoice.status
status_formatted	retainerinvoice.status_formatted
last_payment_date	retainerinvoice.last_payment_date
last_payment_date_formatted	retainerinvoice.last_payment_date_formatted
reference_number	retainerinvoice.reference_number
customer_id	retainerinvoice.customer_id

Show More Supported Input Keys

Property	Request
branch_id	retainerinvoice.branch_id
roundoff_value	retainerinvoice.roundoff_value
roundoff_value_formatted	retainerinvoice.roundoff_value_formatted
transaction_rounding_type	retainerinvoice.transaction_rounding_type
tax_treatment	retainerinvoice.tax_treatment
place_of_supply	retainerinvoice.place_of_supply
place_of_supply_formatted	retainerinvoice.place_of_supply_formatted
customer_name	retainerinvoice.customer_name
contact_persons	retainerinvoice.contact_persons
currency_id	retainerinvoice.currency_id
currency_code	retainerinvoice.currency_code
currency_symbol	retainerinvoice.currency_symbol
exchange_rate	retainerinvoice.exchange_rate
is_viewed_by_client	retainerinvoice.is_viewed_by_client
unused_retainer_payments	retainerinvoice.unused_retainer_payments
unused_retainer_payments_formatted	retainerinvoice.unused_retainer_payments_formatted
client_viewed_time	retainerinvoice.client_viewed_time
client_viewed_time_formatted	retainerinvoice.client_viewed_time_formatted
is_inclusive_tax	retainerinvoice.is_inclusive_tax
tax_rounding	retainerinvoice.tax_rounding
line_items	retainerinvoice.line_items
sub_total	retainerinvoice.sub_total
sub_total_formatted	retainerinvoice.sub_total_formatted
total	retainerinvoice.total
total_formatted	retainerinvoice.total_formatted
taxes	retainerinvoice.taxes
payment_made	retainerinvoice.payment_made
payment_made_formatted	retainerinvoice.payment_made_formatted
payment_drawn	retainerinvoice.payment_drawn
payment_drawn_formatted	retainerinvoice.payment_drawn_formatted
balance	retainerinvoice.balance
balance_formatted	retainerinvoice.balance_formatted
allow_partial_payments	retainerinvoice.allow_partial_payments
price_precision	retainerinvoice.price_precision
payment_options	retainerinvoice.payment_options
is_emailed	retainerinvoice.is_emailed
contact_persons_associated	retainerinvoice.contact_persons_associated
payments	retainerinvoice.payments
payment_refunds	retainerinvoice.payment_refunds
documents	retainerinvoice.documents
comments	retainerinvoice.comments
billing_address	retainerinvoice.billing_address
shipping_address	retainerinvoice.shipping_address
notes	retainerinvoice.notes
terms	retainerinvoice.terms
custom_fields	retainerinvoice.custom_fields
template_id	retainerinvoice.template_id
template_name	retainerinvoice.template_name
template_type	retainerinvoice.template_type
template_type_formatted	retainerinvoice.template_type_formatted
created_time	retainerinvoice.created_time
last_modified_time	retainerinvoice.last_modified_time
created_by_id	retainerinvoice.created_by_id
last_modified_by_id	retainerinvoice.last_modified_by_id
attachment_name	retainerinvoice.attachment_name
invoice_url	retainerinvoice.invoice_url
submitted_date	retainerinvoice.submitted_date
submitted_date_formatted	retainerinvoice.submitted_date_formatted
submitted_by	retainerinvoice.submitted_by
approvers_list	retainerinvoice.approvers_list

Get Retainerinvoices List

Retrieves multiple data points or a collection of records related to the current context. This method is useful for fetching lists, related records, or bulk data required for your widget's functionality.

Commonly used for :

• Fetch related records
• Retrieve collections of data
• Access lists or tables of information

Supported Locations :

retainerinvoice.list.sidebar

Sample Code :

REQUEST DETAILS

window.onload = function () {
  ZFAPPS.extension.init().then(function(App) {
    ZFAPPS.get('retainerinvoices').then(function (data) {
     //response Handling
    }).catch(function (err) {
     //error Handling
    });
  });
}

Supported Input Keys :

Property	Request
retainerinvoice_id	retainerinvoice.retainerinvoice_id
customer_name	retainerinvoice.customer_name
retainerinvoice_number	retainerinvoice.retainerinvoice_number
customer_id	retainerinvoice.customer_id
status	retainerinvoice.status
status_formatted	retainerinvoice.status_formatted
reference_number	retainerinvoice.reference_number
project_or_estimate_name	retainerinvoice.project_or_estimate_name
project_name	retainerinvoice.project_name
estimate_number	retainerinvoice.estimate_number

Show More Supported Input Keys

Property	Request
date	retainerinvoice.date
date_formatted	retainerinvoice.date_formatted
currency_id	retainerinvoice.currency_id
currency_code	retainerinvoice.currency_code
is_viewed_by_client	retainerinvoice.is_viewed_by_client
client_viewed_time	retainerinvoice.client_viewed_time
client_viewed_time_formatted	retainerinvoice.client_viewed_time_formatted
total	retainerinvoice.total
total_formatted	retainerinvoice.total_formatted
balance	retainerinvoice.balance
balance_formatted	retainerinvoice.balance_formatted
created_time	retainerinvoice.created_time
last_modified_time	retainerinvoice.last_modified_time
last_payment_date	retainerinvoice.last_payment_date
last_payment_date_formatted	retainerinvoice.last_payment_date_formatted
selected	retainerinvoice.selected

Set Retainerinvoice customfields

Specifically designed to update custom field values within the current context. This method allows your widget to target and modify custom fields without affecting standard fields, ensuring precise data management.

Commonly used for :

• Update custom field values
• Manage user-defined data points
• Ensure targeted updates to specific fields

Supported Locations :

retainerinvoice.creation.sidebar

Sample Code :

REQUEST DETAILS

window.onload = function () {
  ZFAPPS.extension.init().then(function(App) {
    ZFAPPS.set('retainerinvoice.<custom_field_api_name>',<value>).then(function (data) {
     //response Handling
    }).catch(function (err) {
     //error Handling
    });
  });
}

Get Line Items

This method allows you to retrieve the line items associated with the current retainer invoice. It can be used to fetch details such as product information, quantity, rate, and total for each line item. This is particularly useful when you want to display or utilize the retainer invoice's line item details within your widget or extension.

Supported Locations :

retainerinvoice.creation.sidebar

Sample Code :

REQUEST DETAILS

window.onload = function () {
  ZFAPPS.extension.init().then(function(App) {
    ZFAPPS.get('retainerinvoice.line_items').then(function (res) {
      console.log('retainerinvoice line items : ', res);
    }).catch(function (err) {
      console.log('Error while fetching retainerinvoice line items : ', err);
    });
  });
}

Supported Input Keys :

Property	Request
line_item_id	line_item_id
description	description
item_order	item_order
product_type	product_type
rate	rate
tax_id	tax_id
tax_exemption_id	tax_exemption_id
tax_exemption_code	tax_exemption_code
tax_treatment_code	tax_treatment_code
gst_treatment_code	gst_treatment_code

Set Line Items

This methods is to allowed for set a list of line items in the current retainer invoice. It can be used to set details such as product information, quantity, rate, and total for multiple line items. This is particularly useful when you want to update or set multiple line items details within your widget or extension.This methods is append the line items to the existing line items in the retainer invoice.

Supported Locations :

retainerinvoice.creation.sidebar

Sample Code :

REQUEST DETAILS

window.onload = function () {
  ZFAPPS.extension.init().then(function(App) {
    var lineItemMetaData =[{'rate':'1000','description':'Table','name':'Table'},{'rate':'1000','description':'Monitor','name':'Monitor'}]
    ZFAPPS.set('retainerinvoice.line_items',lineItemMetaData).then(function (res) {
      console.log('retainerinvoice line items : ', res);
    }).catch(function (err) {
      console.log('Error while fetching retainerinvoice line items : ', err);
    });
  });
}

Supported Input Keys :

Property	Request
line_item_id	line_item_id
description	description
item_order	item_order
product_type	product_type
rate	rate
tax_id	tax_id
tax_exemption_id	tax_exemption_id
tax_exemption_code	tax_exemption_code
tax_treatment_code	tax_treatment_code
gst_treatment_code	gst_treatment_code

Set Single Line Items

This methods is to allowed for setting/updating a single line item in the current retainer invoice. It can be used to set details such as product information, quantity, rate, and total for a single line item. This is particularly useful when you want to update or set a single line item details within your widget or extension.

Supported Locations :

retainerinvoice.creation.sidebar

Sample Code :

REQUEST DETAILS

window.onload = function () {
  ZFAPPS.extension.init().then(function(App) {
    ZFAPPS.set('retainerinvoice.line_items[0]',{'rate':'1000'}).then(function (res) {
      console.log('retainerinvoice line item rate : ', res);
    }).catch(function (err) {
      console.log('Error while fetching retainerinvoice line item rate : ', err);
    });
  });
}

Supported Input Keys :

Property	Request
line_item_id	line_item_id
description	description
item_order	item_order
product_type	product_type
rate	rate
tax_id	tax_id
tax_exemption_id	tax_exemption_id
tax_exemption_code	tax_exemption_code
tax_treatment_code	tax_treatment_code
gst_treatment_code	gst_treatment_code

Set Bulk Line Items

This methods is to allowed for replacing/updating all the existing line items in the current retainer invoice. It can be used to set details such as product information, quantity, rate, and total for multiple line items. This is particularly useful when you want to update or set multiple line items details within your widget or extension.

Supported Locations :

retainerinvoice.creation.sidebar

Sample Code :

REQUEST DETAILS

window.onload = function () {
  ZFAPPS.extension.init().then(function(App) {
    var lineItemMetaData =[{'rate':'1000','description':'Table','name':'Table'},{'rate':'1000','description':'Monitor','name':'Monitor'}]
    ZFAPPS.set('retainerinvoice.line_items.bulk_update',lineItemMetaData).then(function (res) {
      console.log('retainerinvoice line items : ', res);
    }).catch(function (err) {
      console.log('Error while fetching retainerinvoice line items : ', err);
    });
  });
}

Supported Input Keys :

Property	Request
line_item_id	line_item_id
description	description
item_order	item_order
product_type	product_type
rate	rate
tax_id	tax_id
tax_exemption_id	tax_exemption_id
tax_exemption_code	tax_exemption_code
tax_treatment_code	tax_treatment_code
gst_treatment_code	gst_treatment_code

Set Line Items Customfields

This method is allowed for setting/updating custom fields for line items in the current retainer invoice. It can be used to set details such as product information, quantity, rate, total, and custom field values for multiple line items. This is particularly useful when you want to update or set multiple line items details along with their custom field values within your widget or extension.

Supported Locations :

retainerinvoice.creation.sidebar

Sample Code :

REQUEST DETAILS

window.onload = function () {
  ZFAPPS.extension.init().then(function(App) {
    var lineItemMetaData =[{'rate':'1000','description':'Table','name':'Table','item_custom_fields':[{'api_name':'<line_item_custom_field_name>', 'value':'<value>'}]}]
    ZFAPPS.set('retainerinvoice.line_items',lineItemMetaData).then(function (res) {
      console.log('retainerinvoice line items : ', res);
    }).catch(function (err) {
      console.log('Error while fetching retainerinvoice line items : ', err);
    });
  });
}

Supported Input Keys :

Property	Request
line_item_id	line_item_id
description	description
item_order	item_order
product_type	product_type
rate	rate
tax_id	tax_id
tax_exemption_id	tax_exemption_id
tax_exemption_code	tax_exemption_code
tax_treatment_code	tax_treatment_code
gst_treatment_code	gst_treatment_code

Events

Events

RETAINERINVOICE_SAVED

This event is triggered after the retainerinvoice record is successfully saved in your organization. You can use this event to perform post-save actions such as syncing data, triggering notifications, or updating external systems.

Supported Locations :

retainerinvoice.creation.sidebar

Sample Code :

REQUEST DETAILS

ZFAPPS.extension.init().then(function(App) {
  App.instance.on('ON_RETAINERINVOICE_SAVED').then(function(data) {

    var recordId = data && data.record_id;

    ZFAPPS.invoke('SHOW_NOTIFICATION', {
      type: 'success',
      message: 'Record saved successfully. Record ID: ' + recordId
    });

    console.log('Saved record ID:', recordId);

  }).catch(function(err) {
    console.error('Error:', err);
  });
});

ON_RETAINERINVOICE_CHANGE

This event is triggered whenever a supported field value is changed within the retainerinvoice form. The event is fired based on the configured supported keys, allowing your widget to react dynamically to user input.

Supported Locations :

retainerinvoice.creation.sidebar

Sample Code :

REQUEST DETAILS

ZFAPPS.extension.init().then(function(App) {
  App.instance.on('ON_RETAINERINVOICE_CHANGE').then(async function() {

    var record = await ZFAPPS.get('retainerinvoice');
    record = record?.['custom_fields'];

    if (record.cf_special_flag) {
      ZFAPPS.invoke('SHOW_NOTIFICATION', {
        type: 'success',
        message: 'Special option selected. Please review additional details before saving.'
      });
    }

  }).catch(function(err) {
    console.error('Error:', err);
  });
});

ON_RETAINERINVOICE_PREVIEW

This event is triggered when the preview of a retainerinvoice record is opened in your organization. It allows your widget to access record data and render contextual information during the preview phase.

Supported Locations :

retainerinvoice.details.sidebar

Sample Code :

REQUEST DETAILS

ZFAPPS.extension.init().then(function(App) {
  App.instance.on('ON_RETAINERINVOICE_PREVIEW').then(async function() {

    var record = await ZFAPPS.get('retainerinvoice');
    record = record?.['custom_fields'];

    if (record.cf_priority_level === 'High') {
      ZFAPPS.invoke('SHOW_NOTIFICATION', {
        type: 'error',
        message: 'This record is marked as High Priority.'
      });
    }

  }).catch(function(err) {
    console.error('Error:', err);
  });
});