Purchase Orders

The Purchase Orders module provides access to contextual information about the current purchase order when a widget is rendered within supported purchase order–related pages. Widgets can retrieve purchase order identifiers, vendor details, and fulfillment-related metadata for use in validations, conditional logic, and UI extensions.

Methods

Methods

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

purchaseorder.creation.sidebarpurchaseorder.details.sidebarpurchaseorder.lineitem.addpurchaseorder.details.button

Sample Code :

REQUEST DETAILS

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

Supported Input Keys :

Property	Request
autonumbergenerationgroup_id	purchaseorder.autonumbergenerationgroup_id
location_id	purchaseorder.location_id
vendor_id	purchaseorder.vendor_id
contact_persons	purchaseorder.contact_persons
purchaseorder_number	purchaseorder.purchaseorder_number
adjustment	purchaseorder.adjustment
adjustment_description	purchaseorder.adjustment_description
reference_number	purchaseorder.reference_number
date	purchaseorder.date
delivery_date	purchaseorder.delivery_date

Show More Supported Input Keys

Property	Request
exchange_rate	purchaseorder.exchange_rate
discount	purchaseorder.discount
discount_account_id	purchaseorder.discount_account_id
is_discount_before_tax	purchaseorder.is_discount_before_tax
discount_type	purchaseorder.discount_type
custom_fields	purchaseorder.custom_fields
ship_via	purchaseorder.ship_via
line_items	purchaseorder.line_items
notes	purchaseorder.notes
notes_default	purchaseorder.notes_default
is_backorder	purchaseorder.is_backorder
terms	purchaseorder.terms
pricebook_id	purchaseorder.pricebook_id
next_action	purchaseorder.next_action
terms_default	purchaseorder.terms_default
delivery_org_address_id	purchaseorder.delivery_org_address_id
delivery_customer_id	purchaseorder.delivery_customer_id
delivery_customer_address_id	purchaseorder.delivery_customer_address_id
salesorder_id	purchaseorder.salesorder_id
is_drop_shipment	purchaseorder.is_drop_shipment
tax_reg_no	purchaseorder.tax_reg_no
taxes	purchaseorder.taxes
tax_override	purchaseorder.tax_override
tax_override_preference	purchaseorder.tax_override_preference
tds_override_preference	purchaseorder.tds_override_preference
tds_taxes	purchaseorder.tds_taxes
template_id	purchaseorder.template_id
is_update_customer	purchaseorder.is_update_customer
is_inclusive_tax	purchaseorder.is_inclusive_tax
crm_owner_id	purchaseorder.crm_owner_id
billing_address_id	purchaseorder.billing_address_id
shipping_address_id	purchaseorder.shipping_address_id
documents	purchaseorder.documents
gst_treatment	purchaseorder.gst_treatment
gst_no	purchaseorder.gst_no
source_of_supply	purchaseorder.source_of_supply
destination_of_supply	purchaseorder.destination_of_supply
tax_treatment	purchaseorder.tax_treatment
place_of_supply	purchaseorder.place_of_supply
payment_terms	purchaseorder.payment_terms
payment_terms_label	purchaseorder.payment_terms_label
tds_tax_id	purchaseorder.tds_tax_id
tds_amount	purchaseorder.tds_amount
is_tds_amount_in_percent	purchaseorder.is_tds_amount_in_percent
tcs_tax_id	purchaseorder.tcs_tax_id
tcs_amount	purchaseorder.tcs_amount
is_tcs_amount_in_percent	purchaseorder.is_tcs_amount_in_percent
is_adv_tracking_in_receive	purchaseorder.is_adv_tracking_in_receive

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

purchaseorder.creation.sidebarpurchaseorder.lineitem.add

Sample Code :

REQUEST DETAILS

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

Supported Input Keys :

Property	Request
autonumbergenerationgroup_id	purchaseorder.autonumbergenerationgroup_id
location_id	purchaseorder.location_id
vendor_id	purchaseorder.vendor_id
contact_persons	purchaseorder.contact_persons
purchaseorder_number	purchaseorder.purchaseorder_number
adjustment	purchaseorder.adjustment
adjustment_description	purchaseorder.adjustment_description
reference_number	purchaseorder.reference_number
date	purchaseorder.date
delivery_date	purchaseorder.delivery_date

Show More Supported Input Keys

Property	Request
exchange_rate	purchaseorder.exchange_rate
discount	purchaseorder.discount
discount_account_id	purchaseorder.discount_account_id
is_discount_before_tax	purchaseorder.is_discount_before_tax
discount_type	purchaseorder.discount_type
custom_fields	purchaseorder.custom_fields
ship_via	purchaseorder.ship_via
line_items	purchaseorder.line_items
notes	purchaseorder.notes
notes_default	purchaseorder.notes_default
is_backorder	purchaseorder.is_backorder
terms	purchaseorder.terms
pricebook_id	purchaseorder.pricebook_id
next_action	purchaseorder.next_action
terms_default	purchaseorder.terms_default
delivery_org_address_id	purchaseorder.delivery_org_address_id
delivery_customer_id	purchaseorder.delivery_customer_id
delivery_customer_address_id	purchaseorder.delivery_customer_address_id
salesorder_id	purchaseorder.salesorder_id
is_drop_shipment	purchaseorder.is_drop_shipment
tax_reg_no	purchaseorder.tax_reg_no
taxes	purchaseorder.taxes
tax_override	purchaseorder.tax_override
tax_override_preference	purchaseorder.tax_override_preference
tds_override_preference	purchaseorder.tds_override_preference
tds_taxes	purchaseorder.tds_taxes
template_id	purchaseorder.template_id
is_update_customer	purchaseorder.is_update_customer
is_inclusive_tax	purchaseorder.is_inclusive_tax
crm_owner_id	purchaseorder.crm_owner_id
billing_address_id	purchaseorder.billing_address_id
shipping_address_id	purchaseorder.shipping_address_id
documents	purchaseorder.documents
gst_treatment	purchaseorder.gst_treatment
gst_no	purchaseorder.gst_no
source_of_supply	purchaseorder.source_of_supply
destination_of_supply	purchaseorder.destination_of_supply
tax_treatment	purchaseorder.tax_treatment
place_of_supply	purchaseorder.place_of_supply
payment_terms	purchaseorder.payment_terms
payment_terms_label	purchaseorder.payment_terms_label
tds_tax_id	purchaseorder.tds_tax_id
tds_amount	purchaseorder.tds_amount
is_tds_amount_in_percent	purchaseorder.is_tds_amount_in_percent
tcs_tax_id	purchaseorder.tcs_tax_id
tcs_amount	purchaseorder.tcs_amount
is_tcs_amount_in_percent	purchaseorder.is_tcs_amount_in_percent
is_adv_tracking_in_receive	purchaseorder.is_adv_tracking_in_receive

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

purchaseorder.creation.sidebar

Sample Code :

REQUEST DETAILS

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

Supported Locations :

purchaseorder.creation.sidebarpurchaseorder.lineitem.add

Sample Code :

REQUEST DETAILS

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

Supported Input Keys :

Property	Request
item_id	item_id
line_item_id	line_item_id
account_id	account_id
name	name
description	description
item_custom_fields	item_custom_fields
item_order	item_order
rate	rate
quantity	quantity
tax_id	tax_id

Show More Supported Input Keys

Property	Request
tax_exemption_code	tax_exemption_code
tax_exemption_id	tax_exemption_id
product_type	product_type
discount	discount
discounts	discounts
acquisition_tax_id	acquisition_tax_id
reverse_charge_tax_id	reverse_charge_tax_id
tags	tags
hsn_or_sac	hsn_or_sac
warehouse_id	warehouse_id
location_id	location_id
gst_treatment_code	gst_treatment_code
tax_treatment_code	tax_treatment_code
project_id	project_id
salesorder_item_id	salesorder_item_id
pricebook_id	pricebook_id
header_name	header_name
header_id	header_id
unit	unit
unit_conversion_id	unit_conversion_id
tds_tax_id	tds_tax_id
purchase_request_items	purchase_request_items
quote_awarded_item_link	quote_awarded_item_link
product_tax_category	product_tax_category
replenishment_task_id	replenishment_task_id
tax_selection_mode	tax_selection_mode
line_item_taxes	line_item_taxes
line_item_tds	line_item_tds

Set Line Items

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

Supported Locations :

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

Supported Input Keys :

Property	Request
item_id	item_id
line_item_id	line_item_id
account_id	account_id
name	name
description	description
item_custom_fields	item_custom_fields
item_order	item_order
rate	rate
quantity	quantity
tax_id	tax_id

Show More Supported Input Keys

Property	Request
tax_exemption_code	tax_exemption_code
tax_exemption_id	tax_exemption_id
product_type	product_type
discount	discount
discounts	discounts
acquisition_tax_id	acquisition_tax_id
reverse_charge_tax_id	reverse_charge_tax_id
tags	tags
hsn_or_sac	hsn_or_sac
warehouse_id	warehouse_id
location_id	location_id
gst_treatment_code	gst_treatment_code
tax_treatment_code	tax_treatment_code
project_id	project_id
salesorder_item_id	salesorder_item_id
pricebook_id	pricebook_id
header_name	header_name
header_id	header_id
unit	unit
unit_conversion_id	unit_conversion_id
tds_tax_id	tds_tax_id
purchase_request_items	purchase_request_items
quote_awarded_item_link	quote_awarded_item_link
product_tax_category	product_tax_category
replenishment_task_id	replenishment_task_id
tax_selection_mode	tax_selection_mode
line_item_taxes	line_item_taxes
line_item_tds	line_item_tds

Set Single Line Items

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

purchaseorder.creation.sidebarpurchaseorder.lineitem.add

Sample Code :

REQUEST DETAILS

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

Supported Input Keys :

Property	Request
item_id	item_id
line_item_id	line_item_id
account_id	account_id
name	name
description	description
item_custom_fields	item_custom_fields
item_order	item_order
rate	rate
quantity	quantity
tax_id	tax_id

Show More Supported Input Keys

Property	Request
tax_exemption_code	tax_exemption_code
tax_exemption_id	tax_exemption_id
product_type	product_type
discount	discount
discounts	discounts
acquisition_tax_id	acquisition_tax_id
reverse_charge_tax_id	reverse_charge_tax_id
tags	tags
hsn_or_sac	hsn_or_sac
warehouse_id	warehouse_id
location_id	location_id
gst_treatment_code	gst_treatment_code
tax_treatment_code	tax_treatment_code
project_id	project_id
salesorder_item_id	salesorder_item_id
pricebook_id	pricebook_id
header_name	header_name
header_id	header_id
unit	unit
unit_conversion_id	unit_conversion_id
tds_tax_id	tds_tax_id
purchase_request_items	purchase_request_items
quote_awarded_item_link	quote_awarded_item_link
product_tax_category	product_tax_category
replenishment_task_id	replenishment_task_id
tax_selection_mode	tax_selection_mode
line_item_taxes	line_item_taxes
line_item_tds	line_item_tds

Set Bulk Line Items

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

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

Supported Input Keys :

Property	Request
item_id	item_id
line_item_id	line_item_id
account_id	account_id
name	name
description	description
item_custom_fields	item_custom_fields
item_order	item_order
rate	rate
quantity	quantity
tax_id	tax_id

Show More Supported Input Keys

Property	Request
tax_exemption_code	tax_exemption_code
tax_exemption_id	tax_exemption_id
product_type	product_type
discount	discount
discounts	discounts
acquisition_tax_id	acquisition_tax_id
reverse_charge_tax_id	reverse_charge_tax_id
tags	tags
hsn_or_sac	hsn_or_sac
warehouse_id	warehouse_id
location_id	location_id
gst_treatment_code	gst_treatment_code
tax_treatment_code	tax_treatment_code
project_id	project_id
salesorder_item_id	salesorder_item_id
pricebook_id	pricebook_id
header_name	header_name
header_id	header_id
unit	unit
unit_conversion_id	unit_conversion_id
tds_tax_id	tds_tax_id
purchase_request_items	purchase_request_items
quote_awarded_item_link	quote_awarded_item_link
product_tax_category	product_tax_category
replenishment_task_id	replenishment_task_id
tax_selection_mode	tax_selection_mode
line_item_taxes	line_item_taxes
line_item_tds	line_item_tds

Set Line Items Customfields

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

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

Supported Input Keys :

Property	Request
item_id	item_id
line_item_id	line_item_id
account_id	account_id
name	name
description	description
item_custom_fields	item_custom_fields
item_order	item_order
rate	rate
quantity	quantity
tax_id	tax_id

Show More Supported Input Keys

Property	Request
tax_exemption_code	tax_exemption_code
tax_exemption_id	tax_exemption_id
product_type	product_type
discount	discount
discounts	discounts
acquisition_tax_id	acquisition_tax_id
reverse_charge_tax_id	reverse_charge_tax_id
tags	tags
hsn_or_sac	hsn_or_sac
warehouse_id	warehouse_id
location_id	location_id
gst_treatment_code	gst_treatment_code
tax_treatment_code	tax_treatment_code
project_id	project_id
salesorder_item_id	salesorder_item_id
pricebook_id	pricebook_id
header_name	header_name
header_id	header_id
unit	unit
unit_conversion_id	unit_conversion_id
tds_tax_id	tds_tax_id
purchase_request_items	purchase_request_items
quote_awarded_item_link	quote_awarded_item_link
product_tax_category	product_tax_category
replenishment_task_id	replenishment_task_id
tax_selection_mode	tax_selection_mode
line_item_taxes	line_item_taxes
line_item_tds	line_item_tds

Events

Events

ON_PURCHASEORDER_PREVIEW

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

Supported Locations :

purchaseorder.details.sidebar

Sample Code :

REQUEST DETAILS

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

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

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

Supported Locations :

purchaseorder.creation.sidebar

Sample Code :

REQUEST DETAILS

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

      var moduleResponse = await ZFAPPS.get('purchaseorder');
      var moduleName = moduleResponse.module.api_name;

      var recordResponse = await ZFAPPS.get('purchaseorder');
      var record = recordResponse[moduleName];

      // Check if vendor is selected
      if (record.vendor_name && record.vendor_name.name === 'ABC Suppliers') {

        // Apply 5% vendor discount at module level
        await ZFAPPS.set(moduleName + '.discount_type', 'entity_level');
        await ZFAPPS.set(moduleName + '.discount', '5%');

        await ZFAPPS.invoke('SHOW_NOTIFICATION', {
          type: 'info',
          message: 'A 5% preferred vendor discount has been applied for ABC Suppliers.'
        });
      }

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

ON_PURCHASEORDER_PRE_SAVE

This event is triggered just before the purchaseorder 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 :

purchaseorder.creation.sidebar

Sample Code :

REQUEST DETAILS

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

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

PURCHASEORDER_SAVED

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

purchaseorder.creation.sidebar

Sample Code :

REQUEST DETAILS

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