Invoices

The Invoices module provides access to contextual information about the current invoice when a widget is rendered within invoice creation or invoice detail pages. Widgets can retrieve invoice identifiers, associated customer details, and conversion-related metadata for use in validations, conditional logic, and UI extensions.

Methods

Methods

Get Invoice 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 :

invoice.details.sidebarinvoice.creation.sidebarinvoice.lineitem.addinvoice.details.buttoninvoice.bulkaction.button

Sample Code :

REQUEST DETAILS

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

Supported Input Keys :

Property	Request
invoice_id	invoice.invoice_id
invoice_number	invoice.invoice_number
salesorder_id	invoice.salesorder_id
salesorder_number	invoice.salesorder_number
crm_owner_id	invoice.crm_owner_id
zcrm_potential_id	invoice.zcrm_potential_id
zcrm_potential_name	invoice.zcrm_potential_name
date	invoice.date
date_formatted	invoice.date_formatted
status	invoice.status

Show More Supported Input Keys

Property	Request
status_formatted	invoice.status_formatted
autobill_status	invoice.autobill_status
autobill_status_formatted	invoice.autobill_status_formatted
payment_terms	invoice.payment_terms
payment_terms_label	invoice.payment_terms_label
due_date	invoice.due_date
due_date_formatted	invoice.due_date_formatted
payment_expected_date	invoice.payment_expected_date
payment_expected_date_formatted	invoice.payment_expected_date_formatted
payment_discount	invoice.payment_discount
payment_discount_formatted	invoice.payment_discount_formatted
last_payment_date	invoice.last_payment_date
last_payment_date_formatted	invoice.last_payment_date_formatted
reference_number	invoice.reference_number
customer_id	invoice.customer_id
branch_id	invoice.branch_id
estimate_id	invoice.estimate_id
contact_category	invoice.contact_category
customer_name	invoice.customer_name
unused_credits_receivable_amount	invoice.unused_credits_receivable_amount
unused_credits_receivable_amount_formatted	invoice.unused_credits_receivable_amount_formatted
unused_retainer_payments	invoice.unused_retainer_payments
unused_retainer_payments_formatted	invoice.unused_retainer_payments_formatted
contact_persons	invoice.contact_persons
currency_id	invoice.currency_id
currency_code	invoice.currency_code
currency_symbol	invoice.currency_symbol
exchange_rate	invoice.exchange_rate
discount	invoice.discount
discount_applied_on_amount	invoice.discount_applied_on_amount
discount_type	invoice.discount_type
recurring_invoice_id	invoice.recurring_invoice_id
documents	invoice.documents
line_items	invoice.line_items
submitter_id	invoice.submitter_id
approver_id	invoice.approver_id
submitted_date	invoice.submitted_date
submitted_date_formatted	invoice.submitted_date_formatted
submitted_by	invoice.submitted_by
contact_persons_details	invoice.contact_persons_details
salesorders	invoice.salesorders
deliverychallans	invoice.deliverychallans
shipping_charge	invoice.shipping_charge
shipping_charge_formatted	invoice.shipping_charge_formatted
adjustment	invoice.adjustment
adjustment_formatted	invoice.adjustment_formatted
roundoff_value	invoice.roundoff_value
roundoff_value_formatted	invoice.roundoff_value_formatted
adjustment_description	invoice.adjustment_description
transaction_rounding_type	invoice.transaction_rounding_type
sub_total	invoice.sub_total
sub_total_formatted	invoice.sub_total_formatted
tax_total	invoice.tax_total
tax_total_formatted	invoice.tax_total_formatted
discount_total	invoice.discount_total
discount_total_formatted	invoice.discount_total_formatted
total	invoice.total
total_formatted	invoice.total_formatted
discount_percent	invoice.discount_percent
bcy_shipping_charge	invoice.bcy_shipping_charge
bcy_adjustment	invoice.bcy_adjustment
bcy_sub_total	invoice.bcy_sub_total
bcy_discount_total	invoice.bcy_discount_total
bcy_tax_total	invoice.bcy_tax_total
bcy_total	invoice.bcy_total
taxes	invoice.taxes
payment_made	invoice.payment_made
payment_made_formatted	invoice.payment_made_formatted
credits_applied	invoice.credits_applied
credits_applied_formatted	invoice.credits_applied_formatted
balance	invoice.balance
balance_formatted	invoice.balance_formatted
write_off_amount	invoice.write_off_amount
write_off_amount_formatted	invoice.write_off_amount_formatted
payment_options	invoice.payment_options
contact_persons_associated	invoice.contact_persons_associated
payments	invoice.payments
shipping_bills	invoice.shipping_bills
credits	invoice.credits
comments	invoice.comments
billing_address	invoice.billing_address
shipping_address	invoice.shipping_address
customer_default_billing_address	invoice.customer_default_billing_address
notes	invoice.notes
terms	invoice.terms
custom_fields	invoice.custom_fields
template_id	invoice.template_id
template_name	invoice.template_name
template_type	invoice.template_type
template_type_formatted	invoice.template_type_formatted
created_time	invoice.created_time
last_modified_time	invoice.last_modified_time
created_date	invoice.created_date
created_date_formatted	invoice.created_date_formatted
created_by_id	invoice.created_by_id
last_modified_by_id	invoice.last_modified_by_id
salesperson_id	invoice.salesperson_id
salesperson_name	invoice.salesperson_name
merchant_id	invoice.merchant_id
merchant_name	invoice.merchant_name
ecomm_operator_id	invoice.ecomm_operator_id
ecomm_operator_name	invoice.ecomm_operator_name
invoice_url	invoice.invoice_url
bills	invoice.bills
sub_total_inclusive_of_tax	invoice.sub_total_inclusive_of_tax
sub_total_inclusive_of_tax_formatted	invoice.sub_total_inclusive_of_tax_formatted
subject_content	invoice.subject_content
approvers_list	invoice.approvers_list
zoho_recruit_jobopening_id	invoice.zoho_recruit_jobopening_id
tcs_total	invoice.tcs_total
tds_total	invoice.tds_total
tcs_amount	invoice.tcs_amount
tds_amount	invoice.tds_amount
lineitem_location_id	invoice.lineitem_location_id
default_warehouse_id	invoice.default_warehouse_id

Set Invoice 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 :

invoice.creation.sidebarinvoice.lineitem.add

Sample Code :

REQUEST DETAILS

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

Supported Input Keys :

Property	Request
invoice_id	invoice.invoice_id
invoice_number	invoice.invoice_number
salesorder_id	invoice.salesorder_id
salesorder_number	invoice.salesorder_number
crm_owner_id	invoice.crm_owner_id
zcrm_potential_id	invoice.zcrm_potential_id
zcrm_potential_name	invoice.zcrm_potential_name
date	invoice.date
date_formatted	invoice.date_formatted
status	invoice.status

Show More Supported Input Keys

Property	Request
status_formatted	invoice.status_formatted
autobill_status	invoice.autobill_status
autobill_status_formatted	invoice.autobill_status_formatted
payment_terms	invoice.payment_terms
payment_terms_label	invoice.payment_terms_label
due_date	invoice.due_date
due_date_formatted	invoice.due_date_formatted
payment_expected_date	invoice.payment_expected_date
payment_expected_date_formatted	invoice.payment_expected_date_formatted
payment_discount	invoice.payment_discount
payment_discount_formatted	invoice.payment_discount_formatted
last_payment_date	invoice.last_payment_date
last_payment_date_formatted	invoice.last_payment_date_formatted
reference_number	invoice.reference_number
customer_id	invoice.customer_id
branch_id	invoice.branch_id
estimate_id	invoice.estimate_id
contact_category	invoice.contact_category
customer_name	invoice.customer_name
unused_credits_receivable_amount	invoice.unused_credits_receivable_amount
unused_credits_receivable_amount_formatted	invoice.unused_credits_receivable_amount_formatted
unused_retainer_payments	invoice.unused_retainer_payments
unused_retainer_payments_formatted	invoice.unused_retainer_payments_formatted
contact_persons	invoice.contact_persons
currency_id	invoice.currency_id
currency_code	invoice.currency_code
currency_symbol	invoice.currency_symbol
exchange_rate	invoice.exchange_rate
discount	invoice.discount
discount_applied_on_amount	invoice.discount_applied_on_amount
discount_type	invoice.discount_type
recurring_invoice_id	invoice.recurring_invoice_id
documents	invoice.documents
line_items	invoice.line_items
submitter_id	invoice.submitter_id
approver_id	invoice.approver_id
submitted_date	invoice.submitted_date
submitted_date_formatted	invoice.submitted_date_formatted
submitted_by	invoice.submitted_by
contact_persons_details	invoice.contact_persons_details
salesorders	invoice.salesorders
deliverychallans	invoice.deliverychallans
shipping_charge	invoice.shipping_charge
shipping_charge_formatted	invoice.shipping_charge_formatted
adjustment	invoice.adjustment
adjustment_formatted	invoice.adjustment_formatted
roundoff_value	invoice.roundoff_value
roundoff_value_formatted	invoice.roundoff_value_formatted
adjustment_description	invoice.adjustment_description
transaction_rounding_type	invoice.transaction_rounding_type
sub_total	invoice.sub_total
sub_total_formatted	invoice.sub_total_formatted
tax_total	invoice.tax_total
tax_total_formatted	invoice.tax_total_formatted
discount_total	invoice.discount_total
discount_total_formatted	invoice.discount_total_formatted
total	invoice.total
total_formatted	invoice.total_formatted
discount_percent	invoice.discount_percent
bcy_shipping_charge	invoice.bcy_shipping_charge
bcy_adjustment	invoice.bcy_adjustment
bcy_sub_total	invoice.bcy_sub_total
bcy_discount_total	invoice.bcy_discount_total
bcy_tax_total	invoice.bcy_tax_total
bcy_total	invoice.bcy_total
taxes	invoice.taxes
payment_made	invoice.payment_made
payment_made_formatted	invoice.payment_made_formatted
credits_applied	invoice.credits_applied
credits_applied_formatted	invoice.credits_applied_formatted
balance	invoice.balance
balance_formatted	invoice.balance_formatted
write_off_amount	invoice.write_off_amount
write_off_amount_formatted	invoice.write_off_amount_formatted
payment_options	invoice.payment_options
contact_persons_associated	invoice.contact_persons_associated
payments	invoice.payments
shipping_bills	invoice.shipping_bills
credits	invoice.credits
comments	invoice.comments
billing_address	invoice.billing_address
shipping_address	invoice.shipping_address
customer_default_billing_address	invoice.customer_default_billing_address
notes	invoice.notes
terms	invoice.terms
custom_fields	invoice.custom_fields
template_id	invoice.template_id
template_name	invoice.template_name
template_type	invoice.template_type
template_type_formatted	invoice.template_type_formatted
created_time	invoice.created_time
last_modified_time	invoice.last_modified_time
created_date	invoice.created_date
created_date_formatted	invoice.created_date_formatted
created_by_id	invoice.created_by_id
last_modified_by_id	invoice.last_modified_by_id
salesperson_id	invoice.salesperson_id
salesperson_name	invoice.salesperson_name
merchant_id	invoice.merchant_id
merchant_name	invoice.merchant_name
ecomm_operator_id	invoice.ecomm_operator_id
ecomm_operator_name	invoice.ecomm_operator_name
invoice_url	invoice.invoice_url
bills	invoice.bills
sub_total_inclusive_of_tax	invoice.sub_total_inclusive_of_tax
sub_total_inclusive_of_tax_formatted	invoice.sub_total_inclusive_of_tax_formatted
subject_content	invoice.subject_content
approvers_list	invoice.approvers_list
zoho_recruit_jobopening_id	invoice.zoho_recruit_jobopening_id
tcs_total	invoice.tcs_total
tds_total	invoice.tds_total
tcs_amount	invoice.tcs_amount
tds_amount	invoice.tds_amount
lineitem_location_id	invoice.lineitem_location_id
default_warehouse_id	invoice.default_warehouse_id

Get Invoices 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 :

invoice.list.sidebarinvoice.list.buttoninvoice.bulkaction.button

Sample Code :

REQUEST DETAILS

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

Supported Input Keys :

Property	Request
invoice_id	invoice.invoice_id
zcrm_potential_id	invoice.zcrm_potential_id
zcrm_potential_name	invoice.zcrm_potential_name
customer_name	invoice.customer_name
customer_id	invoice.customer_id
company_name	invoice.company_name
status	invoice.status
status_formatted	invoice.status_formatted
invoice_number	invoice.invoice_number
reference_number	invoice.reference_number

Show More Supported Input Keys

Property	Request
date	invoice.date
date_formatted	invoice.date_formatted
due_date	invoice.due_date
due_date_formatted	invoice.due_date_formatted
due_days	invoice.due_days
currency_id	invoice.currency_id
currency_code	invoice.currency_code
template_type	invoice.template_type
project_name	invoice.project_name
total	invoice.total
total_formatted	invoice.total_formatted
balance	invoice.balance
balance_formatted	invoice.balance_formatted
created_time	invoice.created_time
last_modified_time	invoice.last_modified_time
payment_expected_date	invoice.payment_expected_date
payment_expected_date_formatted	invoice.payment_expected_date_formatted
last_payment_date	invoice.last_payment_date
last_payment_date_formatted	invoice.last_payment_date_formatted
custom_fields	invoice.custom_fields
template_id	invoice.template_id
documents	invoice.documents
salesperson_id	invoice.salesperson_id
salesperson_name	invoice.salesperson_name
shipping_charge	invoice.shipping_charge
shipping_charge_formatted	invoice.shipping_charge_formatted
adjustment	invoice.adjustment
adjustment_formatted	invoice.adjustment_formatted
write_off_amount	invoice.write_off_amount
write_off_amount_formatted	invoice.write_off_amount_formatted
exchange_rate	invoice.exchange_rate
selected	invoice.selected

Set Invoice 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 :

invoice.creation.sidebar

Sample Code :

REQUEST DETAILS

window.onload = function () {
  ZFAPPS.extension.init().then(function(App) {
    ZFAPPS.set('invoice.<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 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 invoice's line item details within your widget or extension.

Supported Locations :

invoice.creation.sidebarinvoice.lineitem.add

Sample Code :

REQUEST DETAILS

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

Supported Input Keys :

Property	Request
location_id	location_id
autonumbergenerationgroup_id	autonumbergenerationgroup_id
customer	customer
invoice_number	invoice_number
reference_number	reference_number
payment_terms	payment_terms
payment_terms_label	payment_terms_label
payment_options	payment_options
late_fee	late_fee
customer_id	customer_id

Show More Supported Input Keys

Property	Request
contact_persons	contact_persons
contact_persons_associated	contact_persons_associated
date	date
due_date	due_date
notes	notes
notes_default	notes_default
terms	terms
terms_default	terms_default
is_inclusive_tax	is_inclusive_tax
line_items	line_items
allow_partial_payments	allow_partial_payments
custom_fields	custom_fields
contacts	contacts
exchange_rate	exchange_rate
recurring_invoice_id	recurring_invoice_id
invoiced_estimate_id	invoiced_estimate_id
account_id	account_id
adjustment_account_id	adjustment_account_id
shipping_charge_account_id	shipping_charge_account_id
is_discount_before_tax	is_discount_before_tax
discount	discount
discount_type	discount_type
shipping_charge	shipping_charge
adjustment	adjustment
adjustment_description	adjustment_description
salesperson_id	salesperson_id
merchant_id	merchant_id
reason	reason
tax_exemption_code	tax_exemption_code
tax_authority_name	tax_authority_name
tax_id	tax_id
is_update_customer	is_update_customer
zcrm_potential_id	zcrm_potential_id
zcrm_potential_name	zcrm_potential_name
pricebook_id	pricebook_id
template_id	template_id
avatax_use_code	avatax_use_code
avatax_exempt_no	avatax_exempt_no
project_id	project_id
apply_available_retainer_payments	apply_available_retainer_payments
retainers_to_apply	retainers_to_apply
documents	documents
mail_attachments	mail_attachments
mail_id	mail_id
email_account_type	email_account_type
email_account_id	email_account_id
email_folder_id	email_folder_id
billing_address_id	billing_address_id
shipping_address_id	shipping_address_id
dispatch_from_address_id	dispatch_from_address_id
gst_treatment	gst_treatment
gst_no	gst_no
place_of_supply	place_of_supply
type	type
reference_invoice_id	reference_invoice_id
reason_for_debit_note	reason_for_debit_note
is_reverse_charge_applied	is_reverse_charge_applied
is_export_with_payment	is_export_with_payment
reference_invoice_type	reference_invoice_type
next_action	next_action
tax_treatment	tax_treatment
quick_create_payment	quick_create_payment
batch_payments	batch_payments
shipping_charge_tax_id	shipping_charge_tax_id
shipping_charge_tax_treatment_code	shipping_charge_tax_treatment_code
shipping_charge_tax_exemption_code	shipping_charge_tax_exemption_code
shipping_charge_taxes	shipping_charge_taxes
shipping_charge_sac_code	shipping_charge_sac_code
is_customer_liable_for_tax	is_customer_liable_for_tax
subject_content	subject_content
tcs_tax_id	tcs_tax_id
tcs_amount	tcs_amount
is_tcs_amount_in_percent	is_tcs_amount_in_percent
tax_reg_no	tax_reg_no
taxes	taxes
tax_override	tax_override
tax_override_preference	tax_override_preference
tds_override_preference	tds_override_preference
tax_rounding_increment	tax_rounding_increment
rounding_increment	rounding_increment
transaction_rounding_type	transaction_rounding_type
rounding_mode	rounding_mode
tds_tax_id	tds_tax_id
is_tds_amount_in_percent	is_tds_amount_in_percent
tds_amount	tds_amount
reason_for_credit_debit_note	reason_for_credit_debit_note
supply_date	supply_date
special_transaction_type	special_transaction_type
currency_id	currency_id
cfdi_usage	cfdi_usage
cfdi_reference_type	cfdi_reference_type
reference_invoice_id	reference_invoice_id
classes	classes
tds_taxes	tds_taxes
preceding_invoice_id	preceding_invoice_id
salesroute_id	salesroute_id
foreign_tax_reg_no	foreign_tax_reg_no
early_payment_discount_percentage	early_payment_discount_percentage
early_payment_discount_due_days	early_payment_discount_due_days
early_payment_discount_amount	early_payment_discount_amount
retention_items	retention_items
retention_override_preference	retention_override_preference
vat_treatment	vat_treatment
total	total
total_override	total_override
computation_type	computation_type
payment_form	payment_form
txn_posting_date	txn_posting_date
discount_account_id	discount_account_id
tags	tags
bank_account_id	bank_account_id
payment_mode	payment_mode
shipping_charge_tax_category_code	shipping_charge_tax_category_code
tax_selection_mode	tax_selection_mode
tax_authority_id	tax_authority_id
service_start_date	service_start_date
service_end_date	service_end_date
payment_installments	payment_installments
payment_terms_id	payment_terms_id
coupon_code	coupon_code
cost_source	cost_source
purchase_price	purchase_price

Set Line Items

This methods is to allowed for set a list of line items in the current 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 invoice.

Supported Locations :

invoice.creation.sidebarinvoice.lineitem.add

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('invoice.line_items',lineItemMetaData).then(function (res) {
      console.log('invoice line items : ', res);
    }).catch(function (err) {
      console.log('Error while fetching invoice line items : ', err);
    });
  });
}

Supported Input Keys :

Property	Request
location_id	location_id
autonumbergenerationgroup_id	autonumbergenerationgroup_id
customer	customer
invoice_number	invoice_number
reference_number	reference_number
payment_terms	payment_terms
payment_terms_label	payment_terms_label
payment_options	payment_options
late_fee	late_fee
customer_id	customer_id

Show More Supported Input Keys

Property	Request
contact_persons	contact_persons
contact_persons_associated	contact_persons_associated
date	date
due_date	due_date
notes	notes
notes_default	notes_default
terms	terms
terms_default	terms_default
is_inclusive_tax	is_inclusive_tax
line_items	line_items
allow_partial_payments	allow_partial_payments
custom_fields	custom_fields
contacts	contacts
exchange_rate	exchange_rate
recurring_invoice_id	recurring_invoice_id
invoiced_estimate_id	invoiced_estimate_id
account_id	account_id
adjustment_account_id	adjustment_account_id
shipping_charge_account_id	shipping_charge_account_id
is_discount_before_tax	is_discount_before_tax
discount	discount
discount_type	discount_type
shipping_charge	shipping_charge
adjustment	adjustment
adjustment_description	adjustment_description
salesperson_id	salesperson_id
merchant_id	merchant_id
reason	reason
tax_exemption_code	tax_exemption_code
tax_authority_name	tax_authority_name
tax_id	tax_id
is_update_customer	is_update_customer
zcrm_potential_id	zcrm_potential_id
zcrm_potential_name	zcrm_potential_name
pricebook_id	pricebook_id
template_id	template_id
avatax_use_code	avatax_use_code
avatax_exempt_no	avatax_exempt_no
project_id	project_id
apply_available_retainer_payments	apply_available_retainer_payments
retainers_to_apply	retainers_to_apply
documents	documents
mail_attachments	mail_attachments
mail_id	mail_id
email_account_type	email_account_type
email_account_id	email_account_id
email_folder_id	email_folder_id
billing_address_id	billing_address_id
shipping_address_id	shipping_address_id
dispatch_from_address_id	dispatch_from_address_id
gst_treatment	gst_treatment
gst_no	gst_no
place_of_supply	place_of_supply
type	type
reference_invoice_id	reference_invoice_id
reason_for_debit_note	reason_for_debit_note
is_reverse_charge_applied	is_reverse_charge_applied
is_export_with_payment	is_export_with_payment
reference_invoice_type	reference_invoice_type
next_action	next_action
tax_treatment	tax_treatment
quick_create_payment	quick_create_payment
batch_payments	batch_payments
shipping_charge_tax_id	shipping_charge_tax_id
shipping_charge_tax_treatment_code	shipping_charge_tax_treatment_code
shipping_charge_tax_exemption_code	shipping_charge_tax_exemption_code
shipping_charge_taxes	shipping_charge_taxes
shipping_charge_sac_code	shipping_charge_sac_code
is_customer_liable_for_tax	is_customer_liable_for_tax
subject_content	subject_content
tcs_tax_id	tcs_tax_id
tcs_amount	tcs_amount
is_tcs_amount_in_percent	is_tcs_amount_in_percent
tax_reg_no	tax_reg_no
taxes	taxes
tax_override	tax_override
tax_override_preference	tax_override_preference
tds_override_preference	tds_override_preference
tax_rounding_increment	tax_rounding_increment
rounding_increment	rounding_increment
transaction_rounding_type	transaction_rounding_type
rounding_mode	rounding_mode
tds_tax_id	tds_tax_id
is_tds_amount_in_percent	is_tds_amount_in_percent
tds_amount	tds_amount
reason_for_credit_debit_note	reason_for_credit_debit_note
supply_date	supply_date
special_transaction_type	special_transaction_type
currency_id	currency_id
cfdi_usage	cfdi_usage
cfdi_reference_type	cfdi_reference_type
reference_invoice_id	reference_invoice_id
classes	classes
tds_taxes	tds_taxes
preceding_invoice_id	preceding_invoice_id
salesroute_id	salesroute_id
foreign_tax_reg_no	foreign_tax_reg_no
early_payment_discount_percentage	early_payment_discount_percentage
early_payment_discount_due_days	early_payment_discount_due_days
early_payment_discount_amount	early_payment_discount_amount
retention_items	retention_items
retention_override_preference	retention_override_preference
vat_treatment	vat_treatment
total	total
total_override	total_override
computation_type	computation_type
payment_form	payment_form
txn_posting_date	txn_posting_date
discount_account_id	discount_account_id
tags	tags
bank_account_id	bank_account_id
payment_mode	payment_mode
shipping_charge_tax_category_code	shipping_charge_tax_category_code
tax_selection_mode	tax_selection_mode
tax_authority_id	tax_authority_id
service_start_date	service_start_date
service_end_date	service_end_date
payment_installments	payment_installments
payment_terms_id	payment_terms_id
coupon_code	coupon_code
cost_source	cost_source
purchase_price	purchase_price

Set Single Line Items

This methods is to allowed for setting/updating a single line item in the current 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 :

invoice.creation.sidebarinvoice.lineitem.add

Sample Code :

REQUEST DETAILS

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

Supported Input Keys :

Property	Request
location_id	location_id
autonumbergenerationgroup_id	autonumbergenerationgroup_id
customer	customer
invoice_number	invoice_number
reference_number	reference_number
payment_terms	payment_terms
payment_terms_label	payment_terms_label
payment_options	payment_options
late_fee	late_fee
customer_id	customer_id

Show More Supported Input Keys

Property	Request
contact_persons	contact_persons
contact_persons_associated	contact_persons_associated
date	date
due_date	due_date
notes	notes
notes_default	notes_default
terms	terms
terms_default	terms_default
is_inclusive_tax	is_inclusive_tax
line_items	line_items
allow_partial_payments	allow_partial_payments
custom_fields	custom_fields
contacts	contacts
exchange_rate	exchange_rate
recurring_invoice_id	recurring_invoice_id
invoiced_estimate_id	invoiced_estimate_id
account_id	account_id
adjustment_account_id	adjustment_account_id
shipping_charge_account_id	shipping_charge_account_id
is_discount_before_tax	is_discount_before_tax
discount	discount
discount_type	discount_type
shipping_charge	shipping_charge
adjustment	adjustment
adjustment_description	adjustment_description
salesperson_id	salesperson_id
merchant_id	merchant_id
reason	reason
tax_exemption_code	tax_exemption_code
tax_authority_name	tax_authority_name
tax_id	tax_id
is_update_customer	is_update_customer
zcrm_potential_id	zcrm_potential_id
zcrm_potential_name	zcrm_potential_name
pricebook_id	pricebook_id
template_id	template_id
avatax_use_code	avatax_use_code
avatax_exempt_no	avatax_exempt_no
project_id	project_id
apply_available_retainer_payments	apply_available_retainer_payments
retainers_to_apply	retainers_to_apply
documents	documents
mail_attachments	mail_attachments
mail_id	mail_id
email_account_type	email_account_type
email_account_id	email_account_id
email_folder_id	email_folder_id
billing_address_id	billing_address_id
shipping_address_id	shipping_address_id
dispatch_from_address_id	dispatch_from_address_id
gst_treatment	gst_treatment
gst_no	gst_no
place_of_supply	place_of_supply
type	type
reference_invoice_id	reference_invoice_id
reason_for_debit_note	reason_for_debit_note
is_reverse_charge_applied	is_reverse_charge_applied
is_export_with_payment	is_export_with_payment
reference_invoice_type	reference_invoice_type
next_action	next_action
tax_treatment	tax_treatment
quick_create_payment	quick_create_payment
batch_payments	batch_payments
shipping_charge_tax_id	shipping_charge_tax_id
shipping_charge_tax_treatment_code	shipping_charge_tax_treatment_code
shipping_charge_tax_exemption_code	shipping_charge_tax_exemption_code
shipping_charge_taxes	shipping_charge_taxes
shipping_charge_sac_code	shipping_charge_sac_code
is_customer_liable_for_tax	is_customer_liable_for_tax
subject_content	subject_content
tcs_tax_id	tcs_tax_id
tcs_amount	tcs_amount
is_tcs_amount_in_percent	is_tcs_amount_in_percent
tax_reg_no	tax_reg_no
taxes	taxes
tax_override	tax_override
tax_override_preference	tax_override_preference
tds_override_preference	tds_override_preference
tax_rounding_increment	tax_rounding_increment
rounding_increment	rounding_increment
transaction_rounding_type	transaction_rounding_type
rounding_mode	rounding_mode
tds_tax_id	tds_tax_id
is_tds_amount_in_percent	is_tds_amount_in_percent
tds_amount	tds_amount
reason_for_credit_debit_note	reason_for_credit_debit_note
supply_date	supply_date
special_transaction_type	special_transaction_type
currency_id	currency_id
cfdi_usage	cfdi_usage
cfdi_reference_type	cfdi_reference_type
reference_invoice_id	reference_invoice_id
classes	classes
tds_taxes	tds_taxes
preceding_invoice_id	preceding_invoice_id
salesroute_id	salesroute_id
foreign_tax_reg_no	foreign_tax_reg_no
early_payment_discount_percentage	early_payment_discount_percentage
early_payment_discount_due_days	early_payment_discount_due_days
early_payment_discount_amount	early_payment_discount_amount
retention_items	retention_items
retention_override_preference	retention_override_preference
vat_treatment	vat_treatment
total	total
total_override	total_override
computation_type	computation_type
payment_form	payment_form
txn_posting_date	txn_posting_date
discount_account_id	discount_account_id
tags	tags
bank_account_id	bank_account_id
payment_mode	payment_mode
shipping_charge_tax_category_code	shipping_charge_tax_category_code
tax_selection_mode	tax_selection_mode
tax_authority_id	tax_authority_id
service_start_date	service_start_date
service_end_date	service_end_date
payment_installments	payment_installments
payment_terms_id	payment_terms_id
coupon_code	coupon_code
cost_source	cost_source
purchase_price	purchase_price

Set Bulk Line Items

This methods is to allowed for replacing/updating all the existing line items in the current 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 :

invoice.creation.sidebarinvoice.lineitem.add

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('invoice.line_items.bulk_update',lineItemMetaData).then(function (res) {
      console.log('invoice line items : ', res);
    }).catch(function (err) {
      console.log('Error while fetching invoice line items : ', err);
    });
  });
}

Supported Input Keys :

Property	Request
location_id	location_id
autonumbergenerationgroup_id	autonumbergenerationgroup_id
customer	customer
invoice_number	invoice_number
reference_number	reference_number
payment_terms	payment_terms
payment_terms_label	payment_terms_label
payment_options	payment_options
late_fee	late_fee
customer_id	customer_id

Show More Supported Input Keys

Property	Request
contact_persons	contact_persons
contact_persons_associated	contact_persons_associated
date	date
due_date	due_date
notes	notes
notes_default	notes_default
terms	terms
terms_default	terms_default
is_inclusive_tax	is_inclusive_tax
line_items	line_items
allow_partial_payments	allow_partial_payments
custom_fields	custom_fields
contacts	contacts
exchange_rate	exchange_rate
recurring_invoice_id	recurring_invoice_id
invoiced_estimate_id	invoiced_estimate_id
account_id	account_id
adjustment_account_id	adjustment_account_id
shipping_charge_account_id	shipping_charge_account_id
is_discount_before_tax	is_discount_before_tax
discount	discount
discount_type	discount_type
shipping_charge	shipping_charge
adjustment	adjustment
adjustment_description	adjustment_description
salesperson_id	salesperson_id
merchant_id	merchant_id
reason	reason
tax_exemption_code	tax_exemption_code
tax_authority_name	tax_authority_name
tax_id	tax_id
is_update_customer	is_update_customer
zcrm_potential_id	zcrm_potential_id
zcrm_potential_name	zcrm_potential_name
pricebook_id	pricebook_id
template_id	template_id
avatax_use_code	avatax_use_code
avatax_exempt_no	avatax_exempt_no
project_id	project_id
apply_available_retainer_payments	apply_available_retainer_payments
retainers_to_apply	retainers_to_apply
documents	documents
mail_attachments	mail_attachments
mail_id	mail_id
email_account_type	email_account_type
email_account_id	email_account_id
email_folder_id	email_folder_id
billing_address_id	billing_address_id
shipping_address_id	shipping_address_id
dispatch_from_address_id	dispatch_from_address_id
gst_treatment	gst_treatment
gst_no	gst_no
place_of_supply	place_of_supply
type	type
reference_invoice_id	reference_invoice_id
reason_for_debit_note	reason_for_debit_note
is_reverse_charge_applied	is_reverse_charge_applied
is_export_with_payment	is_export_with_payment
reference_invoice_type	reference_invoice_type
next_action	next_action
tax_treatment	tax_treatment
quick_create_payment	quick_create_payment
batch_payments	batch_payments
shipping_charge_tax_id	shipping_charge_tax_id
shipping_charge_tax_treatment_code	shipping_charge_tax_treatment_code
shipping_charge_tax_exemption_code	shipping_charge_tax_exemption_code
shipping_charge_taxes	shipping_charge_taxes
shipping_charge_sac_code	shipping_charge_sac_code
is_customer_liable_for_tax	is_customer_liable_for_tax
subject_content	subject_content
tcs_tax_id	tcs_tax_id
tcs_amount	tcs_amount
is_tcs_amount_in_percent	is_tcs_amount_in_percent
tax_reg_no	tax_reg_no
taxes	taxes
tax_override	tax_override
tax_override_preference	tax_override_preference
tds_override_preference	tds_override_preference
tax_rounding_increment	tax_rounding_increment
rounding_increment	rounding_increment
transaction_rounding_type	transaction_rounding_type
rounding_mode	rounding_mode
tds_tax_id	tds_tax_id
is_tds_amount_in_percent	is_tds_amount_in_percent
tds_amount	tds_amount
reason_for_credit_debit_note	reason_for_credit_debit_note
supply_date	supply_date
special_transaction_type	special_transaction_type
currency_id	currency_id
cfdi_usage	cfdi_usage
cfdi_reference_type	cfdi_reference_type
reference_invoice_id	reference_invoice_id
classes	classes
tds_taxes	tds_taxes
preceding_invoice_id	preceding_invoice_id
salesroute_id	salesroute_id
foreign_tax_reg_no	foreign_tax_reg_no
early_payment_discount_percentage	early_payment_discount_percentage
early_payment_discount_due_days	early_payment_discount_due_days
early_payment_discount_amount	early_payment_discount_amount
retention_items	retention_items
retention_override_preference	retention_override_preference
vat_treatment	vat_treatment
total	total
total_override	total_override
computation_type	computation_type
payment_form	payment_form
txn_posting_date	txn_posting_date
discount_account_id	discount_account_id
tags	tags
bank_account_id	bank_account_id
payment_mode	payment_mode
shipping_charge_tax_category_code	shipping_charge_tax_category_code
tax_selection_mode	tax_selection_mode
tax_authority_id	tax_authority_id
service_start_date	service_start_date
service_end_date	service_end_date
payment_installments	payment_installments
payment_terms_id	payment_terms_id
coupon_code	coupon_code
cost_source	cost_source
purchase_price	purchase_price

Set Line Items Customfields

This method is allowed for setting/updating custom fields for line items in the current 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 :

invoice.creation.sidebarinvoice.lineitem.add

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('invoice.line_items',lineItemMetaData).then(function (res) {
      console.log('invoice line items : ', res);
    }).catch(function (err) {
      console.log('Error while fetching invoice line items : ', err);
    });
  });
}

Supported Input Keys :

Property	Request
location_id	location_id
autonumbergenerationgroup_id	autonumbergenerationgroup_id
customer	customer
invoice_number	invoice_number
reference_number	reference_number
payment_terms	payment_terms
payment_terms_label	payment_terms_label
payment_options	payment_options
late_fee	late_fee
customer_id	customer_id

Show More Supported Input Keys

Property	Request
contact_persons	contact_persons
contact_persons_associated	contact_persons_associated
date	date
due_date	due_date
notes	notes
notes_default	notes_default
terms	terms
terms_default	terms_default
is_inclusive_tax	is_inclusive_tax
line_items	line_items
allow_partial_payments	allow_partial_payments
custom_fields	custom_fields
contacts	contacts
exchange_rate	exchange_rate
recurring_invoice_id	recurring_invoice_id
invoiced_estimate_id	invoiced_estimate_id
account_id	account_id
adjustment_account_id	adjustment_account_id
shipping_charge_account_id	shipping_charge_account_id
is_discount_before_tax	is_discount_before_tax
discount	discount
discount_type	discount_type
shipping_charge	shipping_charge
adjustment	adjustment
adjustment_description	adjustment_description
salesperson_id	salesperson_id
merchant_id	merchant_id
reason	reason
tax_exemption_code	tax_exemption_code
tax_authority_name	tax_authority_name
tax_id	tax_id
is_update_customer	is_update_customer
zcrm_potential_id	zcrm_potential_id
zcrm_potential_name	zcrm_potential_name
pricebook_id	pricebook_id
template_id	template_id
avatax_use_code	avatax_use_code
avatax_exempt_no	avatax_exempt_no
project_id	project_id
apply_available_retainer_payments	apply_available_retainer_payments
retainers_to_apply	retainers_to_apply
documents	documents
mail_attachments	mail_attachments
mail_id	mail_id
email_account_type	email_account_type
email_account_id	email_account_id
email_folder_id	email_folder_id
billing_address_id	billing_address_id
shipping_address_id	shipping_address_id
dispatch_from_address_id	dispatch_from_address_id
gst_treatment	gst_treatment
gst_no	gst_no
place_of_supply	place_of_supply
type	type
reference_invoice_id	reference_invoice_id
reason_for_debit_note	reason_for_debit_note
is_reverse_charge_applied	is_reverse_charge_applied
is_export_with_payment	is_export_with_payment
reference_invoice_type	reference_invoice_type
next_action	next_action
tax_treatment	tax_treatment
quick_create_payment	quick_create_payment
batch_payments	batch_payments
shipping_charge_tax_id	shipping_charge_tax_id
shipping_charge_tax_treatment_code	shipping_charge_tax_treatment_code
shipping_charge_tax_exemption_code	shipping_charge_tax_exemption_code
shipping_charge_taxes	shipping_charge_taxes
shipping_charge_sac_code	shipping_charge_sac_code
is_customer_liable_for_tax	is_customer_liable_for_tax
subject_content	subject_content
tcs_tax_id	tcs_tax_id
tcs_amount	tcs_amount
is_tcs_amount_in_percent	is_tcs_amount_in_percent
tax_reg_no	tax_reg_no
taxes	taxes
tax_override	tax_override
tax_override_preference	tax_override_preference
tds_override_preference	tds_override_preference
tax_rounding_increment	tax_rounding_increment
rounding_increment	rounding_increment
transaction_rounding_type	transaction_rounding_type
rounding_mode	rounding_mode
tds_tax_id	tds_tax_id
is_tds_amount_in_percent	is_tds_amount_in_percent
tds_amount	tds_amount
reason_for_credit_debit_note	reason_for_credit_debit_note
supply_date	supply_date
special_transaction_type	special_transaction_type
currency_id	currency_id
cfdi_usage	cfdi_usage
cfdi_reference_type	cfdi_reference_type
reference_invoice_id	reference_invoice_id
classes	classes
tds_taxes	tds_taxes
preceding_invoice_id	preceding_invoice_id
salesroute_id	salesroute_id
foreign_tax_reg_no	foreign_tax_reg_no
early_payment_discount_percentage	early_payment_discount_percentage
early_payment_discount_due_days	early_payment_discount_due_days
early_payment_discount_amount	early_payment_discount_amount
retention_items	retention_items
retention_override_preference	retention_override_preference
vat_treatment	vat_treatment
total	total
total_override	total_override
computation_type	computation_type
payment_form	payment_form
txn_posting_date	txn_posting_date
discount_account_id	discount_account_id
tags	tags
bank_account_id	bank_account_id
payment_mode	payment_mode
shipping_charge_tax_category_code	shipping_charge_tax_category_code
tax_selection_mode	tax_selection_mode
tax_authority_id	tax_authority_id
service_start_date	service_start_date
service_end_date	service_end_date
payment_installments	payment_installments
payment_terms_id	payment_terms_id
coupon_code	coupon_code
cost_source	cost_source
purchase_price	purchase_price

Events

Events

ON_INVOICE_PRE_SAVE

This event is triggered just before the invoice record is saved in your organization. It allows your widget to validate data, modify field values, or perform custom checks before the save operation is completed.

Supported Locations :

invoice.creation.sidebar

Sample Code :

REQUEST DETAILS

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

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

    if (record.cf_approval_required && !record.cf_approval_notes) {

      await ZFAPPS.invoke('SHOW_NOTIFICATION', {
        type: 'error',
        message: 'Approval notes are required when Approval Required is selected.'
      });

      return {
        prevent_save: true
      };
    }

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

INVOICE_SAVED

This event is triggered after the invoice 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 :

invoice.creation.sidebar

Sample Code :

REQUEST DETAILS

ZFAPPS.extension.init().then(function(App) {
  App.instance.on('ON_INVOICE_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_INVOICE_CHANGE

This event is triggered whenever there is a change in the invoice record while you are creating or editing an invoice. It allows your widget to respond to changes in real time, enabling dynamic updates, validations, or calculations based on the modified invoice data.

Supported Locations :

invoice.creation.sidebar

Sample Code :

REQUEST DETAILS

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

      var recordResponse = await ZFAPPS.get('invoice');
      var record = recordResponse.invoice;
      var lineItems = record.line_items || [];

      for (var i = 0; i < lineItems.length; i++) {
        var item = lineItems[i];

        // Check if target product
        if (item.name === 'Premium Subscription') {

          // Skip if discount already applied
          if (item.cf_discount_applied) continue;

          var response = await ZFAPPS.confirm({
            title: 'Discount Available',
            message: '10% discount available for this item. Apply now?'
          });

          if (response && response.ok) {

            var discountAmount = (item.rate * 0.10).toFixed(2);

            // Update record discount
            await ZFAPPS.set('invoice.discount', discountAmount);

            // Mark line item as processed
            await ZFAPPS.set(
              'invoice.line_items.' + item.line_item_id + '.cf_discount_applied',
              true
            );

            await ZFAPPS.invoke('SHOW_NOTIFICATION', {
              type: 'success',
              message: 'Discount applied successfully.'
            });
          }
        }
      }

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

ON_INVOICE_PREVIEW

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

Supported Locations :

invoice.details.sidebar

Sample Code :

REQUEST DETAILS

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

    var record = await ZFAPPS.get('invoice');
    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);
  });
});

ON_INVOICE_PAGE_LOAD

This event is triggered when the widget is loaded for the first time on the invoice page. You can use this event to initialize data, fetch required resources, or set up the initial state of your widget.

Supported Locations :

invoice.creation.sidebar

Sample Code :

REQUEST DETAILS

ZFAPPS.extension.init().then(function(App) {
  App.instance.on('ON_INVOICE_PAGE_LOAD').then(async function() {
    // Set default value for a custom field
    await ZFAPPS.set('invoice.cf_priority_level', 'Normal');

    ZFAPPS.invoke('SHOW_NOTIFICATION', {
      type: 'success',
      message: 'Default priority level has been set to Normal.'
    });
  }).catch(function(err) {
    console.error('Error:', err);
  });
});