Version: eXtendPS-SE 1.5.0 and above
Audience: Administrator, Developer

Functional mappings allow you to configure and map complex data objects that cannot be directly mapped using a single field or hard-coded mapping. To meet these complex mapping needs based on your business requirements, you can utilize NetSuite's SuiteScript capabilities.

Please note that the features outlined in this document are designed for advanced users who may be able to implement them independently. However, if you require assistance from eXtendTech, please be aware that support for these features is billable, as they are not directly part of eXtendPromoStandards. We are more than happy to help you maximize these capabilities, and our team is here to provide support when you need it.

Note: Functional mappings for the Product Pricing & Configuration, Product Data, Live Inventory, Order Shipment Notification, Order Status, Media Content, and Invoice services are specified in the file suite_promoapi_invoice_transformers.js. Purchase Order service hooks are specified in the file suite_promoapi_transformers.js.

The out-of-the-box functions demonstrate the format in which data can be returned. However, you will need to modify the code according to your specific requirements. The function has access to the current items being returned in the response. If you need to access fields that are not configured in the PromoStandards Setup screens, you will need to configure them in the Additional Search Columns section under the respective setup screen.

1. Product Pricing & Configuration Service (1.0.0) (suite_promoapi_invoice_transformers.js)

The Pricing & Configuration service supports 8 dedicated transformer hooks implemented in suite_promoapi_invoice_transformers.js covering dynamic price levels, contextual search result filtering, individual part price objects, currency resolution, decoration charges from saved searches, global before-return payload interception, and custom service method implementations.

1.1 Item Price Level Mapping: getItemPriceLevelMap

Conditionally maps NetSuite price levels to PromoStandards price types (List, Net, Customer) during seasonal sales, tiered contract pricing, or promotional campaigns. Falls back to standard setup resolution via args.getDefaultItemPriceLevel(args).

/**
 * @service Product Pricing & Configuration Service (1.0.0)
 * @desc Dynamically resolves or overrides the NetSuite price level internal ID for customer-specific or blank pricing.
 *
 * @param {Object} args
 * @param {String} args.promoPriceType - Requested PromoStandards price type ("Customer", "List", "Net")
 * @param {Boolean} args.isMultiCurrency - Whether multicurrency feature is active in NetSuite
 * @param {String} args.nsCurrencyIndex - Resolved NetSuite currency internal ID / index (e.g. "1")
 * @param {Boolean} args.isMultiPricing - Whether multiple price levels / quantity pricing is active
 * @param {Array<String>} args.itemIds - Array of NetSuite item internal IDs being evaluated
 * @param {Object} args.userInfo - User authentication and customer context ({ customer, success })
 * @param {String} args.userInfo.customer - NetSuite customer internal ID mapped to authenticated user
 * @param {Boolean} args.userInfo.success - User authentication success flag
 * @param {Array<Object>} args.productSearchResults - NetSuite SearchResult rows for items
 * @param {Array<Object>} args.decorationSearchResults - NetSuite SearchResult rows for decorations
 * @param {Function} args.getDefaultItemPriceLevel - Helper function to retrieve fallback price level from setup
 * @returns {String|Number|Object} NetSuite price level internal ID (e.g. "1") or item-to-price-level map object
 */
function getItemPriceLevelMap(args) {
  if (args && typeof args.getDefaultItemPriceLevel === "function") {
    let ItemPriceLevelMap = args.getDefaultItemPriceLevel(args);
    log.debug({ title: "getItemPriceLevelMap ItemPriceLevelMap", details: ItemPriceLevelMap });
    return ItemPriceLevelMap;
  }
  // "101" and "102" are item internal IDs; "pl" is price level internal ID
  return { "101": { "pl": "1" }, "102": { "pl": "5" } };
}

Note: To include custom search columns in the main item search results, follow these steps:

  1. Go to the P&C setup screen.
  2. Under the Additional Configuration section, specify the columns you want to add in the Additional Item Search Columns field.
  3. For decoration data, make sure you have a saved search that includes the additional columns you need.
  4. In the Decoration Field Mapping section of the P&C setup, enter the saved search ID in the Saved Search ID for Decoration field.

1.2 Contextual Price Search Results: getContextualPriceSearchResult

Filters, reorders, or customizes NetSuite item pricing search results contextually (e.g. prioritizing customer-specific contracted price levels over general volume tiers).

/**
 * @service Product Pricing & Configuration Service (1.0.0)
 * @desc Filters or adjusts item pricing search results in real time based on customer contract rules or channel parameters.
 *
 * @param {Object} args
 * @param {Array<Object>} args.itemPricingSearchResults - NetSuite item search result rows containing price matrix columns
 * @param {Function} args.getDefaultItemContextualPriceSearchResult - Built-in helper resolving base price level context
 * @returns {Array<Object>} Filtered or augmented pricing search results array
 */
function getContextualPriceSearchResult(args) {
  if (
    args &&
    typeof args.getDefaultItemContextualPriceSearchResult === "function"
  ) {
    return args.getDefaultItemContextualPriceSearchResult(args);
  }
  return (args && args.itemPricingSearchResults) || [];
}

1.3 Individual Part Price Object Customizer: pcGetItemPriceObject

Customizes individual part price tier objects (adjusting effective start/expiry dates, overriding price unit of measure, or applying real-time currency conversions).

/**
 * @service Product Pricing & Configuration Service (1.0.0)
 * @desc Customizes individual part price objects (adjusting effective dates, price UOM, or tier flags).
 *
 * @param {Object} args
 * @param {Object} args.itemData - Metadata for the current item / part ({ priceType, PartPriceArray, partId })
 * @param {String} args.itemData.priceType - Price type enum (e.g. "List", "Net")
 * @param {Array} args.itemData.PartPriceArray - Array of part price tiers
 * @param {String} args.itemData.partId - Part SKU identifier
 * @param {Object} args.itemPriceObject - Default constructed part price object ({ price, discountCode, priceUom, priceEffectiveDate, priceExpiryDate })
 * @param {Number|String} args.itemPriceObject.price - Tier calculated unit price
 * @param {String} args.itemPriceObject.discountCode - Industry discount code (e.g. "A", "P", "G")
 * @param {String} args.itemPriceObject.priceUom - Price unit of measure (e.g. "EA")
 * @param {String|Object} args.itemPriceObject.priceEffectiveDate - Effective start date ISO string
 * @param {String|Object} args.itemPriceObject.priceExpiryDate - Expiry date ISO string
 * @param {Number|String} args.itemPriceObject.minQuantity - Tier minimum quantity threshold
 * @param {Object} args.itemSearchResult - NetSuite SearchResult for the current item
 * @param {Array<Object>} args.itemSearchResults - Full pricing search results array
 * @returns {Object} Final modified part price object
 */
function pcGetItemPriceObject(args) {
  var itemPriceObject = (args && args.itemPriceObject) || {};
  // Example: enforce specific UOM or adjust effective dates
  if (!itemPriceObject.priceUom) {
    itemPriceObject.priceUom = 'EA';
  }
  return itemPriceObject;
}

1.4 Currency Code & Index Resolver: pcGetCurrencyCode

Resolves or overrides the NetSuite currency index or internal ID based on user, country, currency, or customer account profiles.

/**
 * @service Product Pricing & Configuration Service (1.0.0)
 * @desc Resolves the NetSuite currency index or ISO code based on user, country, or customer profile.
 *
 * @param {Object} args
 * @param {String} args.nsCurrencyIndex - Resolved NetSuite currency index / code (e.g. "1")
 * @param {Boolean} args.isMultiCurrency - Whether multicurrency feature is active in account
 * @param {Object} args.userInfo - User and customer account metadata ({ customer, success })
 * @param {String} args.userInfo.customer - NetSuite customer internal ID mapped to authenticated user
 * @param {Boolean} args.userInfo.success - User authentication success flag
 * @returns {String} NetSuite currency index or internal ID (e.g. "1")
 */
function pcGetCurrencyCode(args) {
  return (args && args.nsCurrencyIndex) || "1";
}

1.5 Decoration Object from Saved Search: getDecorationObject

Customizes decoration / imprint method objects constructed from NetSuite decoration configuration records or saved search rows.

/**
 * @service Product Pricing & Configuration Service (1.0.0)
 * @desc Customizes decoration / imprint method objects constructed from NetSuite decoration configuration records.
 *
 * @param {Object} args
 * @param {Object} args.decorationObject - Default constructed decoration object ({ decorationId, decorationName, leadTime, rushLeadTime, ChargeArray })
 * @param {Number} args.decorationObject.decorationId - Decoration method ID
 * @param {String} args.decorationObject.decorationName - Imprint method description
 * @param {Number} args.decorationObject.leadTime - Standard lead time in days
 * @param {Number} args.decorationObject.rushLeadTime - Rush lead time in days
 * @param {Object} args.decorationObject.ChargeArray - Associated decoration charges container: { Charge: Array<Object> }
 * @param {Object} args.decoSearchResult - Current decoration setup search result row
 * @param {Array<Object>} args.decoSearchResults - Array of all decoration search results
 * @param {String|Number} args.nsPriceLevel - Resolved price level for decoration charges
 * @param {Array<String>} args.customPriceItemIds - Array of item IDs utilizing custom pricing
 * @param {String} args.nsCurrencyIndex - Resolved NetSuite currency index
 * @param {Object} args.chargeItemSearchResults - Map of charge item IDs to search results
 * @returns {Object} Final modified decoration object
 */
function getDecorationObject(args) {
  var decorationObject = (args && args.decorationObject) || {};
  // Example: customize rush lead times or add location-specific charges
  return decorationObject;
}

1.6 Pricing & Configuration Before Return Hook: pcPricingAndConfigBeforeRetrunHook

Interceptor hook called immediately before serializing and returning the final getConfigurationAndPricing payload.

/**
 * @service Product Pricing & Configuration Service (1.0.0)
 * @desc Interceptor hook called immediately before returning the final getConfigurationAndPricing payload.
 *
 * @param {Object} args
 * @param {Object} args.toReturnObject - Full final Configuration object assembled by the RESTlet ({ productId, currency, priceType, FobArray, DecorationArray, PartArray, LocationArray })
 * @param {Object} args.toReturnObject.productId - XML namespace wrapped product ID: { attributes: { xmlns }, $value: String }
 * @param {Object} args.toReturnObject.currency - XML namespace wrapped ISO currency code: { attributes: { xmlns }, $value: String }
 * @param {Object} args.toReturnObject.priceType - XML namespace wrapped price type enum: { attributes: { xmlns }, $value: String }
 * @param {Object} args.toReturnObject.FobArray - FOB shipping points container: { Fob: Array<Object> }
 * @param {Object} args.toReturnObject.DecorationArray - Decoration methods container: { Decoration: Array<Object> }
 * @param {Object} args.toReturnObject.PartArray - Product parts container: { Part: Array<Object> }
 * @param {Object} args.toReturnObject.LocationArray - Imprint locations container: { Location: Array<Object> }
 * @param {Array<Object>} args.itemSearchResults - Search results for parent item and component child items
 * @returns {Object} Final modified Configuration payload object
 */
function pcPricingAndConfigBeforeRetrunHook(args) {
  var toReturnConfig = (args && args.toReturnObject) || {};
  // Example: inject advisory warnings, adjust FOB points, or customize pricing tiers
  return toReturnConfig;
}

1.7 Get Available Charges API: getAvailableCharges

Implements the PromoStandards getAvailableCharges service method endpoint, returning the full schema-compliant JSON envelope including PromoStandards XML namespaces and productPricing.AvailableCharges.

/**
 * @service Product Pricing & Configuration Service (1.0.0)
 * @desc Custom hook implementation for GetAvailableCharges API request.
 * Returns sample JSON structure expected for GetAvailableCharges.
 *
 * @param {Object} args - Complete incoming request payload extended with authenticated user context
 * @param {String} args.productId - Requested product identifier
 * @param {String} args.wsVersion - Service version ("1.0.0")
 * @param {String} args.localizationLanguage - Optional requested language (e.g. "en-US")
 * @param {String} args.localizationCountry - Optional requested country (e.g. "US")
 * @param {Object} args.userInfo - Authenticated user account context ({ customer, success })
 * @param {String} args.userInfo.customer - NetSuite customer internal ID mapped to user
 * @param {Boolean} args.userInfo.success - User authentication success flag
 * @returns {Object} Response object containing productPricing.AvailableCharges
 */
function getAvailableCharges(args) {
  var productId = (args && args.productId) || "MUG-101";

  return {
    success: true,
    data: {
      __api_date_stamp__: new Date().toISOString(),
      productPricing: {
        AvailableCharges: {
          AvailableChargeArray: {
            AvailableCharge: [
              {
                chargeId: {
                  attributes: {
                    xmlns: "http://www.promostandards.org/WSDL/PricingAndConfiguration/1.0.0/SharedObjects/",
                  },
                  $value: 1,
                },
                chargeName: {
                  attributes: {
                    xmlns: "http://www.promostandards.org/WSDL/PricingAndConfiguration/1.0.0/SharedObjects/",
                  },
                  $value: "Setup Charge",
                },
                chargeDescription: {
                  attributes: {
                    xmlns: "http://www.promostandards.org/WSDL/PricingAndConfiguration/1.0.0/SharedObjects/",
                  },
                  $value: "Setup Charge Description",
                },
                chargeType: {
                  attributes: {
                    xmlns: "http://www.promostandards.org/WSDL/PricingAndConfiguration/1.0.0/SharedObjects/",
                  },
                  $value: "Setup",
                },
              },
              {
                chargeId: {
                  attributes: {
                    xmlns: "http://www.promostandards.org/WSDL/PricingAndConfiguration/1.0.0/SharedObjects/",
                  },
                  $value: 2,
                },
                chargeName: {
                  attributes: {
                    xmlns: "http://www.promostandards.org/WSDL/PricingAndConfiguration/1.0.0/SharedObjects/",
                  },
                  $value: "Run Charge",
                },
                chargeDescription: {
                  attributes: {
                    xmlns: "http://www.promostandards.org/WSDL/PricingAndConfiguration/1.0.0/SharedObjects/",
                  },
                  $value: "Run Charge Description",
                },
                chargeType: {
                  attributes: {
                    xmlns: "http://www.promostandards.org/WSDL/PricingAndConfiguration/1.0.0/SharedObjects/",
                  },
                  $value: "Run",
                },
              },
            ],
          },
        },
      },
    },
  };
}

1.8 Get Decoration Colors API: getDecorationColors

Implements the PromoStandards getDecorationColors service method endpoint, returning the structured DecorationColors response containing valid imprint colors (with PMS and full-color match flags), product and location IDs, and available decoration methods with XML namespaces.

/**
 * @service Product Pricing & Configuration Service (1.0.0)
 * @desc Custom hook implementation for GetDecorationColors API request.
 * Returns sample JSON structure expected for GetDecorationColors.
 *
 * @param {Object} args - Complete incoming request payload extended with authenticated user context
 * @param {String} args.productId - Requested product SKU
 * @param {String|Number} args.locationId - Requested decoration location ID
 * @param {String|Number} args.decorationId - Requested decoration method ID
 * @param {String} args.wsVersion - Service version ("1.0.0")
 * @param {Object} args.userInfo - Authenticated user context ({ customer, success })
 * @param {String} args.userInfo.customer - Customer internal ID mapped to user
 * @param {Boolean} args.userInfo.success - User authentication success flag
 * @returns {Object} Structured final response wrapping GetDecorationColorsResponse
 */
function getDecorationColors(args) {
  return {
    success: true,
    data: {
      __api_date_stamp__: new Date().toISOString(),
      productPricing: {
        DecorationColors: {
          ColorArray: {
            Color: [
              {
                colorId: {
                  attributes: {
                    xmlns: "http://www.promostandards.org/WSDL/PricingAndConfiguration/1.0.0/SharedObjects/",
                  },
                  $value: 1,
                },
                colorName: {
                  attributes: {
                    xmlns: "http://www.promostandards.org/WSDL/PricingAndConfiguration/1.0.0/SharedObjects/",
                  },
                  $value: "PMS Matching",
                },
              },
              {
                colorId: {
                  attributes: {
                    xmlns: "http://www.promostandards.org/WSDL/PricingAndConfiguration/1.0.0/SharedObjects/",
                  },
                  $value: 2,
                },
                colorName: {
                  attributes: {
                    xmlns: "http://www.promostandards.org/WSDL/PricingAndConfiguration/1.0.0/SharedObjects/",
                  },
                  $value: "White",
                },
              },
              {
                colorId: {
                  attributes: {
                    xmlns: "http://www.promostandards.org/WSDL/PricingAndConfiguration/1.0.0/SharedObjects/",
                  },
                  $value: 3,
                },
                colorName: {
                  attributes: {
                    xmlns: "http://www.promostandards.org/WSDL/PricingAndConfiguration/1.0.0/SharedObjects/",
                  },
                  $value: "Black",
                },
              },
            ],
          },
          productId: {
            attributes: {
              xmlns: "http://www.promostandards.org/WSDL/PricingAndConfiguration/1.0.0/SharedObjects/",
            },
            $value: (args && args.productId) || "MUG-101",
          },
          locationId: {
            attributes: {
              xmlns: "http://www.promostandards.org/WSDL/PricingAndConfiguration/1.0.0/SharedObjects/",
            },
            $value: (args && parseInt(args.locationId, 10)) || 1,
          },
          DecorationMethodArray: {
            DecorationMethod: [
              {
                decorationId: {
                  attributes: {
                    xmlns: "http://www.promostandards.org/WSDL/PricingAndConfiguration/1.0.0/SharedObjects/",
                  },
                  $value: 1,
                },
                decorationName: {
                  attributes: {
                    xmlns: "http://www.promostandards.org/WSDL/PricingAndConfiguration/1.0.0/SharedObjects/",
                  },
                  $value: "Screen Print",
                },
              },
            ],
          },
          pmsMatch: true,
          fullColor: false,
        },
      },
    },
  };
}

2. Product Data Service (1.0.0 & 2.0.0) (suite_promoapi_invoice_transformers.js)

The Product Data service supports 10 transformer hooks implemented in suite_promoapi_invoice_transformers.js covering packaging, marketing bullets, categories, related products, part colors, primary images, pricing group limits, compliance regulations, and full response interception.

2.1 Packaging & Shipping: getProductPackagingAndShippingData

Overrides or generates the ProductPackagingArray and ShippingPackageArray elements for Product Data 1.0.0 and 2.0.0.

/**
 * @service Product Data Service (1.0.0 & 2.0.0)
 * @desc Custom packaging and shipping specifications hook for Product Data 1.0.0 & 2.0.0
 *
 * @param {Object} args
 * @param {Object} args.partSearchResult - NetSuite SearchResult row for the current part/variant item
 * @param {Object} args.itemSearchResult - NetSuite SearchResult row for the parent product item
 * @param {Array<Object>} args.partSearchResults - Array of all part/variant SearchResult rows
 * @param {Array<Object>} args.itemSearchResults - Array of all parent product SearchResult rows
 * @returns {Object} Object containing ProductPackagingArray and ShippingPackageArray
 */
function getProductPackagingAndShippingData(args) {
  return {
    ProductPackagingArray: [
      {
        default: true,
        packageType: 'Gift Box',
        description: 'Deluxe presentation box',
        quantity: 1,
        dimensionUom: 'IN',
        depth: 8.5,
        height: 3.0,
        width: 4.5,
        weightUom: 'LB',
        weight: 1.25,
      },
    ],
    ShippingPackageArray: [
      {
        packageType: 'Master Carton',
        description: 'Corrugated master carton',
        quantity: 24,
        dimensionUom: 'IN',
        depth: 18.0,
        height: 12.0,
        width: 14.0,
        weightUom: 'LB',
        weight: 32.0,
      },
    ],
  };
}

2.2 Product Marketing Data: getProductMarketingData

Populates marketing points and product feature highlights in ProductMarketingPointArray for Product Data 1.0.0 & 2.0.0.

/**
 * @service Product Data Service (1.0.0 & 2.0.0)
 * @desc Custom marketing point highlights hook for Product Data 1.0.0 & 2.0.0
 *
 * @param {Object} args
 * @param {Object} args.itemSearchResult - NetSuite SearchResult row for the parent product item
 * @param {Array<Object>} args.itemSearchResults - Array of all parent product SearchResult rows
 * @returns {Array<Object>} Array of marketing points: [{ pointType: 'String', pointCopy: 'String' }]
 */
function getProductMarketingData(args) {
  var itemRow = args && args.itemSearchResult;
  return [
    {
      pointType: 'Highlights',
      pointCopy: 'Double-wall vacuum insulated stainless steel keeps beverages hot for 12 hours.',
    },
    {
      pointType: 'Materials',
      pointCopy: 'BPA-free Eastman Tritan lid with silicone spill-resistant gasket.',
    },
  ];
}

2.3 Product Categories: getProductCategories

Dynamically resolves or injects product category and subcategory classifications into ProductCategoryArray.

/**
 * @service Product Data Service (1.0.0 & 2.0.0)
 * @desc Returns custom hierarchical product category classifications.
 *
 * @param {Object} args
 * @param {Object} args.itemSearchResult - NetSuite SearchResult row for the parent product item
 * @param {Array<Object>} args.itemSearchResults - Array of all parent product SearchResult rows
 * @param {String} args.wsVersion - Web service version ("1.0.0" | "2.0.0")
 * @returns {Array<Object>} Array of category objects: [{ category: 'String', subCategory: 'String' }]
 */
function getProductCategories(args) {
  return [
    {
      category: 'Drinkware',
      subCategory: 'Travel Mugs & Tumblers',
    },
  ];
}

2.4 Related Products (Cross-Sell / Up-Sell): getRelatedProducts

Maps cross-sell, substitute, and accessory products in RelatedProductArray.

/**
 * @service Product Data Service (1.0.0 & 2.0.0)
 * @desc Returns related products (cross-sells, accessories, up-sells) for a product.
 *
 * @param {Object} args
 * @param {Object} args.itemSearchResult - NetSuite SearchResult row for the parent product item
 * @param {Array<Object>} args.itemSearchResults - Array of all parent product SearchResult rows
 * @returns {Array<Object>} Array of related products: [{ relationType: 'Substitute', productId: 'SKU-1' }]
 */
function getRelatedProducts(args) {
  var ns = 'http://www.promostandards.org/WSDL/ProductDataService/1.0.0/SharedObjects/';
  return [
    {
      relationType: 'Substitute',
      productId: {
        attributes: { xmlns: ns },
        $value: 'MUG-200',
      },
      partId: {
        attributes: { xmlns: ns },
        $value: 'MUG-200-WHT',
      },
    },
  ];
}

2.5 Multi-Color Part Arrays: product_getPartColorArray & product_getPartPrimaryColor

Defines multi-color support for apparel and hard goods variants in Product Data 2.0.0.

/**
 * @service Product Data Service (2.0.0)
 * @desc Custom multi-color array builder for Product Data 2.0.0 parts.
 *
 * @param {Object} args
 * @param {Object} args.partItemSearchResult - NetSuite SearchResult row for the component/variant item
 * @param {Array<Object>} args.partItemSearchResults - Array of all component/variant item SearchResult rows
 * @param {Object} args.itemSearchResult - NetSuite SearchResult row for the parent product item
 * @param {Array<Object>} args.itemSearchResults - Array of all parent product SearchResult rows
 * @param {Object} args.setupPartColorFieldMap - Setup mapping for part colors ({ colorName, hexCode, approximatePms, standardColorName, useAsPrimaryColor })
 * @param {String} args.setupPartColorFieldMap.colorName - Field ID for color name
 * @param {String} args.setupPartColorFieldMap.hexCode - Field ID for hex code
 * @param {String} args.setupPartColorFieldMap.approximatePms - Field ID for PMS color
 * @param {String} args.setupPartColorFieldMap.standardColorName - Field ID for standard color enum
 * @param {String} args.setupPartColorFieldMap.useAsPrimaryColor - Primary color flag ("T"|"F")
 * @returns {Array<Object>} Array of Color objects: [{ colorName: 'Red', hexCode: 'FF0000' }]
 */
function product_getPartColorArray(options) {
  return [
    {
      Color: [
        {
          colorName: 'Navy Blue',
          hexCode: '#000080',
          approximatePms: '289 C',
          standardColorName: 'Blue',
        },
      ],
    },
  ];
}

/**
 * @service Product Data Service (2.0.0)
 * @desc Custom primary color selector from partColorArray for Product Data 2.0.0.
 *
 * @param {Object} args
 * @param {Array<Object>} args.partColorArray - Array of color objects generated by product_getPartColorArray ({ colorName, hexCode, approximatePms, standardColorName })
 * @param {String} args.partColorArray[].colorName - Color description
 * @param {String} args.partColorArray[].hexCode - Hex color code
 * @param {String} args.partColorArray[].approximatePms - Pantone PMS code
 * @param {String} args.partColorArray[].standardColorName - Standard PromoStandards color name
 * @param {Object} args.partItemSearchResult - NetSuite SearchResult row for the component/variant item
 * @param {Array<Object>} args.partItemSearchResults - Array of all component/variant item SearchResult rows
 * @param {Object} args.itemSearchResult - NetSuite SearchResult row for the parent product item
 * @param {Array<Object>} args.itemSearchResults - Array of all parent product SearchResult rows
 * @param {Object} args.setupPartColorFieldMap - Setup mapping for part colors ({ colorName, hexCode, approximatePms, standardColorName, useAsPrimaryColor })
 * @param {String} args.setupPartColorFieldMap.colorName - Field ID for color name
 * @param {String} args.setupPartColorFieldMap.hexCode - Field ID for hex code
 * @param {String} args.setupPartColorFieldMap.approximatePms - Field ID for PMS color
 * @param {String} args.setupPartColorFieldMap.standardColorName - Field ID for standard color enum
 * @param {String} args.setupPartColorFieldMap.useAsPrimaryColor - Primary color flag ("T"|"F")
 * @returns {Array<Object>} Primary Color array (single-element array or empty array)
 */
function product_getPartPrimaryColor(args) {
  var partColorArray = (args && args.partColorArray) || [];
  return partColorArray.length ? partColorArray : [];
}

2.6 Primary Image URL Override: getItemPrimaryImageUrlForProduct2

Dynamically resolves or alters the primary hero display image in Product Data 2.0.0.

/**
 * @service Product Data Service (2.0.0)
 * @desc Returns custom primary image URL for Product Data 2.0.0.
 *
 * @param {Object} args
 * @param {Object} args.itemSearchResult - NetSuite SearchResult row for the item
 * @param {Array<Object>} args.itemSearchResults - Array of all item SearchResult rows
 * @returns {String} Primary image absolute URL
 */
function getItemPrimaryImageUrlForProduct2(args) {
  var itemRow = args && args.itemSearchResult;
  var customUrl = itemRow && itemRow.getValue({ name: 'custitem_custom_cdn_hero_image' });
  return customUrl || 'https://cdn.supplier.com/images/default-hero.jpg';
}

2.7 Maximum Quantity for Pricing Groups: getProductDataMaximumQuantityForPricingGroup

Sets the upper bound quantity limit for pricing groups in Product Data 2.0.0.

/**
 * @service Product Data Service (2.0.0)
 * @desc Overrides the maximum quantity threshold for product pricing groups.
 *
 * @param {Object} args
 * @param {Object} args.itemSearchResult - NetSuite SearchResult row for the parent product item
 * @param {Array<Object>} args.itemSearchResults - Array of all product SearchResult rows
 * @returns {Number} Maximum quantity threshold
 */
function getProductDataMaximumQuantityForPricingGroup(args) {
  return 99999999;
}

2.8 Compliance & Regulations: getProductsWithRegulations

Populates California Proposition 65 or consumer safety compliance groups for items modified within a requested date window.

/**
 * @service Product Data Service / Product Compliance Service (1.0.0)
 * @desc Returns products subject to compliance regulations (California Prop 65, CPSIA, etc.)
 *
 * @param {Object} args
 * @param {String} args.changeTimeStamp - ISO 8601 timestamp string representing the modification cutoff filter
 * @param {Date} args.formattedChangeDate - Parsed JavaScript Date object of the modification filter
 * @returns {Object} Object with ProductWithRegulations array: { ProductWithRegulations: Array<Object> }
 */
function getProductsWithRegulations(args) {
  return {
    ProductWithRegulations: [
      {
        productId: 'MUG-101',
        partId: 'MUG-101-BLU',
        complianceGroups: [{ complianceGroup: 'CaliforniaProp65' }],
      },
    ],
  };
}

2.9 Product Data 2.0 Before Return Hook: getProductData200BeforeReturnHook

Provides complete access to the final Product Data 2.0.0 response object tree immediately before JSON/XML transmission.

/**
 * @service Product Data Service (2.0.0)
 * @desc Interceptor hook called immediately before returning the final Product Data 2.0.0 payload.
 *
 * @param {Object} args
 * @param {Array<Object>} args.itemSearchResults - Combined parent and component SearchResult rows
 * @param {Object} args.response - Full assembled PromoStandards Product 2.0.0 response object ({ productId, productName, description, PartArray, ProductCategoryArray, ProductPackagingArray, ShippingPackageArray })
 * @param {String} args.response.productId - Product SKU
 * @param {String} args.response.productName - Product name
 * @param {String} args.response.description - Product description
 * @param {Array<Object>} args.response.PartArray - Array of product part / variant objects
 * @param {Array<Object>} args.response.ProductCategoryArray - Array of product categories
 * @returns {Object} Modified Product 2.0.0 response object
 */
function getProductData200BeforeReturnHook(args) {
  var product = (args && args.response) || {};
  // Example: append copyright notice or inject custom distributor pricing groups
  return product;
}

2.10 Product Data 2.0 Configuration Constants: PRODUCT_DATA_2_CONFIG

Configuration object exported from suite_promoapi_invoice_transformers.js to set core defaults for Product Data 2.0 searches and pricing lookups.

var PRODUCT_DATA_2_CONFIG = {
  DEFAULT_BASE_PRICE: {
    text: "Base Price",
    value: 1,
  },
  MAX_QTY_LIMIT: 99999999,
  MAX_PRODUCT_PRICING_SEARCH_LIMIT: 1000,
};

3. Live Inventory Service (1.2.1 & 2.0.0) (suite_promoapi_invoice_transformers.js)

Supports 2 transformer hooks implemented in suite_promoapi_invoice_transformers.js for Available-to-Build (ATB) manufacturing capacity and dynamic warehouse location caching.

3.1 Available-to-Build (ATB) Capacity: getMinAvailableToBuild

Calculates available manufacturing capacity for assembled items based on multi-level BOM component stock, open purchase orders, dynamic inventory overrides, and NetSuite UOM conversions.

/**
 * @service Live Inventory Service (1.2.1 & 2.0.0)
 * @desc Calculates Available-to-Build manufacturing capacity for assemblies and kits.
 *
 * @param {Object} args
 * @param {Number} args.minAvailableToBuild - Initial computed ATB capacity from component stock / ratio arithmetic
 * @param {Object} args.availableToBuildQuantity - Map of item IDs to stock quantities ({ [itemId]: qty })
 * @param {Object} args.availableToBuildData - Raw component quantities per location / item
 * @param {Array<Object>} args.availableToBuildSearch - Component item search results
 * @param {Object} args.configRecordSearch - Setup configuration settings ({ suppressAssemblyComponents, dynamicInventoryOverride, allowSubCustomerSearch })
 * @param {Boolean} args.configRecordSearch.suppressAssemblyComponents - Hide assembly component items flag
 * @param {Boolean} args.configRecordSearch.dynamicInventoryOverride - Dynamic inventory overrides flag
 * @param {Boolean} args.configRecordSearch.allowSubCustomerSearch - Sub-customer query flag
 * @param {Object} args.itemId_POComment - Open PO comment and dock date map ({ [itemId]: { comment, dockDate } })
 * @param {Array<Object>} args.purchaseOrderSearch - Open PO search results for future replenishment
 * @param {Object} args.unitsTypeDataObject - UOM conversion rates map
 * @param {Object} args.unitsOfMeasureObject - UOM lookup table
 * @param {Object} args.itemIdAndUnitTypeObject - Item to unit type mapping
 * @param {Boolean} args.isQuantityPerLocation - Quantity per location flag (true when grouped by warehouse)
 * @param {Boolean} args.isAssembly - Assembly / BOM item flag
 * @param {Array<String>|String} args.id - Parent item internal ID(s)
 * @returns {Number} Adjusted Available-to-Build capacity
 */
function getMinAvailableToBuild(args) {
  return 1500;
}

3.2 Dynamic Warehouse Location Filter: getItemInventoryLocations

Extracts and returns warehouse location internal IDs to populate in the item location cache for Live Inventory 2.0.0.

/**
 * @service Live Inventory Service (2.0.0) / Location Cache
 * @desc Extracts warehouse location IDs for item location cache.
 *
 * @param {Object} args
 * @param {Array<Object>} args.itemData - Grouped item location result rows ({ id, recordType, values })
 * @param {String|Number} args.itemData[].id - Item internal ID
 * @param {String} args.itemData[].recordType - Item record type ("inventoryitem", "assemblyitem", etc.)
 * @param {Object} args.itemData[].values - Column values object ({ inventorylocation: Array<Object> })
 * @param {Array<Object>} args.itemData[].values.inventorylocation - Inventory location reference objects
 * @param {String} args.itemData[].values.inventorylocation[].value - Inventory location internal ID
 * @param {String} args.itemData[].values.inventorylocation[].text - Inventory location display name
 * @returns {Array<String>|String} Location ID(s)
 */
function getItemInventoryLocations(args) {
  var itemData = (args && args.itemData) || [];
  if (itemData.length && itemData[0].values && itemData[0].values.inventorylocation) {
    return itemData[0].values.inventorylocation[0].value;
  }
  return [];
}

4. Order Shipment Notification (OSN 1.0.0 & 2.0.0) (suite_promoapi_invoice_transformers.js)

Supports 7 transformer hooks across OSN 1.0.0 and OSN 2.0.0 (SuiteQL) implemented in suite_promoapi_invoice_transformers.js.

4.1 OSN 2.0.0 Package Dimensions & Weight: getDimensionHook

Returns custom package dimensionSize and dimensionWeight objects for OSN 2.0.0 fulfillments.

/**
 * @service Order Shipment Notification (OSN 2.0.0)
 * @desc Returns custom package dimensionSize and dimensionWeight objects for OSN 2.0.0 fulfillments.
 *
 * @param {Object} shipment - SuiteQL result row for the fulfillment / package ({ so_id, so_status, fulfillment_id, fulfillment_status, shipment_date, ship_carrier, ship_service, ship_to_city, ship_to_state, ship_to_zip, ship_to_country, ship_to_phone, package_tracking_number, package_weight, is_pre_prod, salesOrderShippedInFull })
 * @param {String} shipment.so_id - Sales Order internal ID
 * @param {String} shipment.so_status - Sales Order status code
 * @param {String} shipment.fulfillment_id - Item Fulfillment internal ID
 * @param {String} shipment.fulfillment_status - Item Fulfillment status ("shipped", "picked", "packed")
 * @param {String} shipment.shipment_date - Fulfillment transaction date
 * @param {String} shipment.ship_carrier - Shipping carrier name
 * @param {String} shipment.ship_service - Shipping service method
 * @param {String} shipment.ship_to_city - Destination city
 * @param {String} shipment.ship_to_state - Destination state / province
 * @param {String} shipment.ship_to_zip - Destination postal code
 * @param {String} shipment.ship_to_country - Destination country code
 * @param {String} shipment.ship_to_phone - Destination telephone
 * @param {String} shipment.package_tracking_number - Package tracking number
 * @param {Number} shipment.package_weight - Package scale weight
 * @param {String|Boolean} shipment.is_pre_prod - Pre-production proof status
 * @param {Boolean} shipment.salesOrderShippedInFull - Order fulfillment completion flag
 * @param {Object} osnSetupData - Active OSN setup configuration record ({ supplierPartId, supplierProductId, distributorProductId, distributorPartId, shipMethod, preProductionProof })
 * @param {String} osnSetupData.supplierPartId - Field ID for supplier part SKU
 * @param {String} osnSetupData.supplierProductId - Field ID for product SKU
 * @param {String} osnSetupData.distributorProductId - Field ID for distributor product
 * @param {String} osnSetupData.distributorPartId - Field ID for distributor part
 * @param {String} osnSetupData.shipMethod - Shipping method field mapping
 * @param {String} osnSetupData.preProductionProof - Pre-production proof field configuration
 * @returns {Object} Object with dimensionSize ({ dimensionUom, depth, height, width }) and dimensionWeight ({ weightUom, weight })
 */
function getDimensionHook(shipment, osnSetupData) {
  return {
    dimensionSize: {
      dimensionUom: 'Inches',
      depth: 10,
      width: 10,
      height: 10,
    },
    dimensionWeight: {
      weightUom: 'Pounds',
      weight: (shipment && shipment.package_weight) || 10,
    },
  };
}

4.2 OSN 2.0.0 Dynamic SuiteQL Clauses: getOSN2Filters & getOSN2Columns

Injects custom SuiteQL WHERE filter clauses and SELECT columns dynamically into OSN 2.0.0 queries.

/**
 * @service Order Shipment Notification (OSN 2.0.0)
 * @desc Injects custom SuiteQL WHERE filter clauses dynamically into OSN 2.0.0 queries.
 *
 * @param {Object} setUpData
 * @param {String} setUpData.queryType - Query type ("1" = PO, "2" = SO, "3" = Date)
 * @param {Object} setUpData.requestData - Incoming request payload ({ queryType, referenceNumber, shipmentDate })
 * @param {String} setUpData.requestData.queryType - Query type
 * @param {String} setUpData.requestData.referenceNumber - PO or SO reference number
 * @param {String} setUpData.requestData.shipmentDate - Shipment date timestamp
 * @param {String} setUpData.customerId - NetSuite customer internal ID
 * @param {Array<String>} setUpData.filters - Existing SQL WHERE conditions
 * @param {Object} setUpData.osnSetupData - Active OSN setup configuration record
 * @returns {Array<String>} Array of SQL WHERE condition strings (e.g. ["so.tranid NOT LIKE '%TEST%'"])
 */
function getOSN2Filters(setUpData) {
  // Example: exclude internal test orders or draft transactions
  // return ["so.tranid NOT LIKE '%TEST%'"];
  return [];
}

/**
 * @service Order Shipment Notification (OSN 2.0.0)
 * @desc Injects custom SuiteQL SELECT columns dynamically into OSN 2.0.0 queries.
 *
 * @param {Object} setUpData
 * @param {String} setUpData.queryType - Query type ("1" = PO, "2" = SO, "3" = Date)
 * @param {Object} setUpData.requestData - Incoming request payload ({ queryType, referenceNumber, shipmentDate })
 * @param {String} setUpData.requestData.queryType - Query type
 * @param {String} setUpData.requestData.referenceNumber - PO or SO reference number
 * @param {String} setUpData.requestData.shipmentDate - Shipment date timestamp
 * @param {String} setUpData.customerId - NetSuite customer internal ID
 * @param {Object} setUpData.osnSetupData - Active OSN setup configuration record
 * @returns {Array<String>} Array of SQL SELECT column strings (e.g. ["itemFulfillment.custbody_bol_num AS bol_number"])
 */
function getOSN2Columns(setUpData) {
  // Example: select additional custom transaction field
  // return ["itemFulfillment.custbody_bol_num AS bol_number"];
  return [];
}

4.3 OSN 1.0.0 Shipping Method Translator: getShipmentMethod

Translates NetSuite shipping method names or Item Fulfillment ship methods into standardized PromoStandards carrier service codes.

/**
 * @service Order Shipment Notification (OSN 1.0.0)
 * @desc Translates or overrides NetSuite shipping method names to PromoStandards carrier strings.
 *
 * @param {Object} args
 * @param {String} args.fieldId - Configured field ID on Item Fulfillment holding the carrier / service
 * @param {Object} args.searchResult - NetSuite SearchResult row for the fulfillment
 * @returns {String} Standardized shipmentMethod string
 */
function getShipmentMethod(args) {
  var fieldId = args && args.fieldId;
  var searchResult = args && args.searchResult;

  var shipMethod = fieldId && searchResult
    ? searchResult.getText({ name: fieldId }) || searchResult.getValue({ name: fieldId })
    : 'UPS Ground';

  return shipMethod || 'UPS Ground';
}

4.4 OSN 1.0.0 Address Builders: getOSNShipFromAddressData & getOSNShipToAddressData

Customizes origin (ShipFrom) and destination (ShipTo) address structures for OSN 1.0.0 responses.

/**
 * @service Order Shipment Notification (OSN 1.0.0)
 * @desc Builds custom shipFromAddress object for OSN 1.0.0 responses.
 *
 * @param {Object} args
 * @param {Array<Object>} args.searchResults - Full array of Item Fulfillment and Location search results
 * @param {Object} args.fulfillmentSearchResult - NetSuite SearchResult row for the specific fulfillment
 * @returns {Object} PromoStandards address object: { address1, address2, city, region, postalCode, country }
 */
function getOSNShipFromAddressData(args) {
  var shipFromAddress = (args && args.shipFromAddress) || {};
  return shipFromAddress;
}

/**
 * @service Order Shipment Notification (OSN 1.0.0)
 * @desc Builds custom shipToAddress object for OSN 1.0.0 responses.
 *
 * @param {Object} args
 * @param {Array<Object>} args.searchResults - Full array of Item Fulfillment search results
 * @param {Object} args.fulfillmentSearchResult - NetSuite SearchResult row for the specific fulfillment
 * @returns {Object} PromoStandards address object: { address1, address2, address3, city, region, postalCode, country }
 */
function getOSNShipToAddressData(args) {
  var shipToAddress = (args && args.shipToAddress) || {};
  return shipToAddress;
}

4.5 OSN 1.0.0 Custom Package Tracking: getPackageMethod

Customizes package structures and tracking assignments for individual packages in OSN 1.0.0.

/**
 * @service Order Shipment Notification (OSN 1.0.0)
 * @desc Customizes individual Package objects (tracking details, shipping carrier, account).
 *
 * @param {Object} args - Search result context ({ searchResults, fulfillmentSearchResult })
 * @param {Array<Object>} args.searchResults - Full array of search results
 * @param {Object} args.fulfillmentSearchResult - Current Item Fulfillment SearchResult
 * @param {Object} packageObject - Default constructed package tracking object ({ trackingNumber, shipmentDate, carrier, shipmentMethod, shippingAccount })
 * @param {String} packageObject.trackingNumber - Tracking number string
 * @param {String} packageObject.shipmentDate - ISO date string of shipment
 * @param {String} packageObject.carrier - Shipping carrier description
 * @param {String} packageObject.shipmentMethod - Shipping service level method
 * @param {String} packageObject.shippingAccount - Shipper account number
 * @returns {Object} Modified Package object
 */
function getPackageMethod(args, packageArrayObject) {
  var toReturnPackageObject = packageArrayObject || {};
  return toReturnPackageObject;
}

5. Order Status Service (1.0.0 & 2.0.0) (suite_promoapi_invoice_transformers.js)

Supports 5 transformer hooks across Order Status 1.0.0 and Order Status 2.0.0 implemented in suite_promoapi_invoice_transformers.js.

5.1 Order Status 2.0.0 (SuiteQL Mapping): getOrderStatus2_0

Translates NetSuite transaction status codes to PromoStandards 2.0 lowercase status enums.

/**
 * @service Order Status (2.0.0)
 * @desc Translates SuiteQL query results into a valid PromoStandards 2.0.0 order status string.
 *
 * @param {Object} args
 * @param {Object} args.searchResult - NetSuite SuiteQL result row for the Sales Order
 * @param {Array<String>} args.promoValidStatusList - PromoStandards compliant status enums list
 * @param {Boolean} args.isQuery - Query mode flag (true)
 * @returns {String} PromoStandards 2.0.0 status string
 */
function getOrderStatus2_0(args) {
  var row = (args && args.searchResult) || {};
  var orderStatus = row.status || '';

  var statusMapping = {
    A: 'received',     // Pending Approval
    B: 'confirmed',    // Pending Fulfillment
    C: 'canceled',     // Cancelled
    D: 'inProduction', // Partially Fulfilled
    E: 'inProduction', // Pending Billing / Part Fulfilled
    F: 'complete',     // Pending Billing
    G: 'complete',     // Fully Billed
    H: 'canceled',     // Closed
  };

  return statusMapping[orderStatus] || 'received';
}

5.2 Line-Level Order Status: getLineLevelOrderStatus

Calculates fulfillment status for individual line items based on quantities shipped, billed, picked, or packed.

/**
 * @service Order Status (2.0.0)
 * @desc Translates individual line item state into a valid PromoStandards 2.0.0 line item status string.
 *
 * @param {Object} args
 * @param {String} args.orderStatus - Current parent order-level status string
 * @param {Object} args.lineItem - NetSuite SuiteQL line item object ({ id, line, item, itemType, isClosed, quantity, quantityShipped, quantityBilled, quantityPicked, quantityPacked, lineIssueCategory, expectedShipDate })
 * @param {String|Number} args.lineItem.id - Line item internal ID
 * @param {Number} args.lineItem.line - Sales Order line sequence number
 * @param {String} args.lineItem.item - Item name / SKU
 * @param {String} args.lineItem.itemType - NetSuite item type ("InvtPart", "NonInvtPart", etc.)
 * @param {Boolean} args.lineItem.isClosed - NetSuite line closure flag
 * @param {Number} args.lineItem.quantity - Ordered line quantity
 * @param {Number} args.lineItem.quantityShipped - Quantity fulfilled / shipped
 * @param {Number} args.lineItem.quantityBilled - Quantity invoiced / billed
 * @param {Number} args.lineItem.quantityPicked - Quantity picked
 * @param {Number} args.lineItem.quantityPacked - Quantity packed
 * @param {String} args.lineItem.lineIssueCategory - Line-level issue category code
 * @param {String} args.lineItem.expectedShipDate - Line-level expected shipment date
 * @param {Array<String>} args.promoValidStatusList - PromoStandards compliant status enums list
 * @param {Boolean} args.isQuery - Query mode flag (true)
 * @returns {String} PromoStandards 2.0.0 line status string
 */
function getLineLevelOrderStatus(args) {
  var line = (args && args.lineItem) || {};
  if (line.isClosed) {
    return 'canceled';
  }
  if (line.quantityShipped >= line.quantity) {
    return 'complete';
  } else if (line.quantityShipped > 0 && line.quantityShipped < line.quantity) {
    return 'partiallyShipped';
  } else if (line.quantityShipped === 0 && (line.quantityPicked > 0 || line.quantityPacked > 0)) {
    return 'inStorage';
  }
  return 'received';
}

5.3 Order Status 2.0 Dynamic SuiteQL Clauses: getOrderStatusFilters & getOrderStatusColumns

Injects custom SuiteQL WHERE clauses and SELECT columns dynamically into Order Status 2.0.0 queries.

/**
 * @service Order Status (2.0.0)
 * @desc Injects custom SuiteQL WHERE clauses dynamically into Order Status 2.0.0 queries.
 *
 * @param {Object} setUpData
 * @param {String} setUpData.queryType - Query type ("1" = PO, "2" = SO, "3" = Status Date, "4" = Issue)
 * @param {Object} setUpData.requestData - Incoming request payload ({ queryType, referenceNumber, statusTimeStamp })
 * @param {String} setUpData.requestData.queryType - Query type
 * @param {String} setUpData.requestData.referenceNumber - Reference number
 * @param {String} setUpData.requestData.statusTimeStamp - Status timestamp
 * @param {String} setUpData.customerId - NetSuite internal ID of customer
 * @param {Array<String>} setUpData.filters - Existing SuiteQL WHERE filters array
 * @param {Object} setUpData.orderStatusSetupValuesSearch - Order Status setup record configuration
 * @returns {Array<String>} Array of SQL WHERE filter strings (e.g. ["salesOrder.custbody_suppress_ps_status != 'T'"])
 */
function getOrderStatusFilters(setUpData) {
  // Example: exclude orders with internal test or suppression flags
  // return ["salesOrder.custbody_suppress_ps_status != 'T'"];
  return [];
}

/**
 * @service Order Status (2.0.0)
 * @desc Injects custom SuiteQL SELECT columns dynamically into Order Status 2.0.0 queries.
 *
 * @param {Object} setUpData
 * @param {String} setUpData.queryType - Query type ("1" = PO, "2" = SO, "3" = Status Date, "4" = Issue)
 * @param {Object} setUpData.requestData - Incoming request payload ({ queryType, referenceNumber, statusTimeStamp })
 * @param {String} setUpData.requestData.queryType - Query type
 * @param {String} setUpData.requestData.referenceNumber - Reference number
 * @param {String} setUpData.requestData.statusTimeStamp - Status timestamp
 * @param {String} setUpData.customerId - NetSuite internal ID of customer
 * @param {Object} setUpData.orderStatusSetupValuesSearch - Order Status setup record configuration
 * @returns {Array<String>} Array of SQL SELECT column strings (e.g. ["salesOrder.custbody_factory_order_num AS factoryOrderNumber"])
 */
function getOrderStatusColumns(setUpData) {
  // Example: select additional custom transaction field
  // return ["salesOrder.custbody_factory_order_num AS factoryOrderNumber"];
  return [];
}

5.4 Order Status 1.0.0 Status Translator: getOrderStatus

Translates NetSuite transaction saved search statusref into one of the 14 valid PromoStandards 1.0.0 status strings.

/**
 * @service Order Status (1.0.0)
 * @desc Translates NetSuite search result statusref into a valid PromoStandards 1.0.0 status string.
 *
 * @param {Object} args
 * @param {Object} args.searchResult - NetSuite SearchResult row for the Sales Order
 * @param {Array<String>} args.promoValidStatusList - PromoStandards 1.0.0 compliant valid order status strings
 * @returns {String} PromoStandards 1.0.0 status string (e.g. "Order Confirmed", "Complete")
 */
function getOrderStatus(args) {
  var searchResult = args && args.searchResult;
  var currentOrderStatus = searchResult ? searchResult.getValue({ name: "statusref" }) : "";

  var orderStatusMap = {
    pendingApproval: "Order Received",
    pendingFulfillment: "Order Confirmed",
    cancelled: "Canceled",
    closed: "Canceled",
    partiallyFulfilled: "In Production",
    pendingBillingPartFulfilled: "In Production",
    fullyBilled: "Complete",
    pendingBilling: "Complete",
  };

  return orderStatusMap[currentOrderStatus] || "Order Received";
}

Note: Only valid PromoStandards Order Status values should be returned. Valid values are listed below.

  1. Order Received
  2. Order Entry Hold
  3. Order Confirmed
  4. Pre-Production
  5. General Hold
  6. Credit Hold
  7. Proof Hold
  8. Art Hold
  9. Back Order Hold
  10. In Production
  11. In Storage
  12. Partial Shipment
  13. Complete
  14. Canceled

6. Media Content Service (1.1.0) (suite_promoapi_invoice_transformers.js)

Supports 2 transformer hooks implemented in suite_promoapi_invoice_transformers.js for generating synthetic media objects or enriching NetSuite Media Details search results with custom decoration and location tags.

6.1 Synthetic Media Object Generator: getMediaObject

Generates or overrides media objects for products and parts when no native NetSuite media records exist.

/**
 * @service Media Content Service (1.1.0)
 * @desc Generates synthetic media objects on-the-fly for products lacking saved search media records.
 *
 * @param {Object} args
 * @param {Object} args.requestObject - Incoming request parameters ({ productId, partId, classType, cultureName, mediaContent })
 * @param {String} args.requestObject.productId - Requested product identifier
 * @param {String} args.requestObject.partId - Optional part identifier filter
 * @param {String|Number} args.requestObject.classType - Media class type filter code
 * @param {String} args.requestObject.cultureName - Culture / language code
 * @param {Object} args.requestObject.mediaContent - Media content configuration object
 * @param {Array<Object>} args.productSearchResults - Item saved search results for matching product SKU
 * @returns {Array<Object>} Array of MediaContent objects: [{ url, mediaType, ClassTypeArray }]
 */
function getMediaObject(args) {
  var req = (args && args.requestObject) || {};
  var productId = req.productId || "CUP-100";
  var partId = req.partId || productId;

  return [
    {
      productId: productId,
      partId: partId,
      url: "https://media.promostandards.org/products/" + productId + ".jpg",
      mediaType: "Image",
      ClassTypeArray: {
        ClassType: [
          {
            classTypeId: 1001,
            classTypeName: "Blank",
          },
        ],
      },
      fileSize: 150000,
      width: 1024,
      height: 768,
      dpi: 72,
      color: "RGB",
      description: "Primary product catalog image",
      singlePart: true,
      changeTimeStamp: new Date().toISOString(),
    },
  ];
}

6.2 Search-Result Media Enricher: getMediaObjectFromMediaSearch

Enriches media records discovered from native NetSuite search results with dynamic decoration and location tags.

/**
 * @service Media Content Service (1.1.0)
 * @desc Enriches media objects with custom locations and decorations from Media Details records.
 *
 * @param {Object} args
 * @param {Array<Object>} args.mediaContentSearchResults - Full array of NetSuite Media Details search results
 * @param {Object} args.mediaContentSearchResult - Current NetSuite Media Details SearchResult row
 * @returns {Object} Object with optional LocationArray and DecorationArray
 */
function getMediaObjectFromMediaSearch(args) {
  var row = args && args.mediaContentSearchResult;
  var locationId = row && row.getValue({ name: 'custrecord_extend_promo_standards_loc' });

  return {
    locationArray: locationId ? [{ locationId: locationId, locationName: 'Front Chest' }] : [],
    decorationArray: [{ decorationId: '1', decorationName: 'Screen Print' }],
  };
}

7. Invoice Service (0.0.1 & 1.0.0) (suite_promoapi_invoice_transformers.js)

Supports 2 transformer hooks implemented in suite_promoapi_invoice_transformers.js for calculating financial breakdown amounts and tax totals for Invoice 0.0.1 and 1.0.0.

7.1 Invoice Financial Breakdown & Tax Calculator: getInvoiceData & validateAndGetInvoiceData

Calculates financial breakdown amounts (sales amount, shipping & handling, advance payment, total, and balance due) and validates invoices against custom accounting business rules.

/**
 * @service Invoice Service (0.0.1)
 * @desc Calculates financial breakdown amounts (sales amount, shipping & handling, advance payment, total, and balance due) for Invoice 0.0.1.
 *
 * @param {Object} args
 * @param {Array<Object>} args.searchResults - NetSuite Invoice search result rows
 * @param {Object} args.invoiceResponse - Pre-assembled invoice response object ({ invoiceId, invoiceDate, paymentTerms, salesAmount, shippingAndHandlingAmount, totalAmount, advancePaymentAmount, invoiceAmount, InvoiceLineItemsArray, TaxArray })
 * @param {String} args.invoiceResponse.invoiceId - Invoice document number / tranId
 * @param {String} args.invoiceResponse.invoiceDate - Transaction date
 * @param {String} args.invoiceResponse.paymentTerms - Customer payment terms description
 * @param {Number} args.invoiceResponse.salesAmount - Net merchandise sales amount
 * @param {Number} args.invoiceResponse.shippingAndHandlingAmount - Combined shipping and handling charges
 * @param {Number} args.invoiceResponse.totalAmount - Gross transaction total amount
 * @param {Number} args.invoiceResponse.advancePaymentAmount - Prepayment / deposit amount applied
 * @param {Number} args.invoiceResponse.invoiceAmount - Remaining balance due amount
 * @param {Object} args.invoiceResponse.InvoiceLineItemsArray - Line items container: { InvoiceLineItem: Array<Object> }
 * @param {Array<Object>} args.invoiceResponse.InvoiceLineItemsArray.InvoiceLineItem - Array of invoice line item objects
 * @param {Object} args.invoiceResponse.TaxArray - Tax lines container: { Tax: Array<Object> }
 * @param {Array<Object>} args.invoiceResponse.TaxArray.Tax - Array of invoice tax breakdown objects
 * @returns {Object} Object containing financial amount overrides (salesAmount, shippingAndHandlingAmount, totalAmount, advancePaymentAmount, invoiceAmount)
 */
function getInvoiceData(args) {
  var searchResults = args.searchResults;
  var invoiceResponse = args.invoiceResponse;

  var lookup = search.lookupFields({
    type: searchResults[0].recordType,
    id: searchResults[0].id,
    columns: [
      "amountpaid",
      "amountremaining",
      "total",
      "shippingamount",
      "handlingcost",
      "taxtotal",
    ],
  });

  var shippingAmount = +lookup.shippingamount || 0;
  var handlingAmount = +lookup.handlingcost || +lookup.handlingamount || 0;
  var totalAmount = +lookup.total || 0;
  var taxTotal = +lookup.taxtotal || 0;
  var amountpaid = +lookup.amountpaid || 0;

  var shippingAndHandlingAmount = shippingAmount + handlingAmount;
  var salesAmount = totalAmount - shippingAndHandlingAmount - taxTotal;
  var invoiceAmount = totalAmount - amountpaid;

  return {
    salesAmount: salesAmount,
    shippingAndHandlingAmount: shippingAndHandlingAmount,
    totalAmount: totalAmount,
    advancePaymentAmount: amountpaid,
    invoiceAmount: invoiceAmount,
  };
}

/**
 * @service Invoice Service (1.0.0)
 * @desc Validates and calculates invoice financial amounts (sales amount, shipping & handling, advance payment, total, and balance due) for Invoice 1.0.0.
 *
 * @param {Object} args
 * @param {Array<Object>} args.searchResults - NetSuite Invoice search result rows
 * @param {Object} args.invoiceResponse - Pre-assembled invoice response object ({ invoiceId, invoiceDate, paymentTerms, salesAmount, shippingAndHandlingAmount, totalAmount, advancePaymentAmount, invoiceAmount, InvoiceLineItemsArray, TaxArray })
 * @param {String} args.invoiceResponse.invoiceId - Invoice document number / tranId
 * @param {String} args.invoiceResponse.invoiceDate - Transaction date
 * @param {String} args.invoiceResponse.paymentTerms - Customer payment terms description
 * @param {Number} args.invoiceResponse.salesAmount - Net merchandise sales amount
 * @param {Number} args.invoiceResponse.shippingAndHandlingAmount - Combined shipping and handling charges
 * @param {Number} args.invoiceResponse.totalAmount - Gross transaction total amount
 * @param {Number} args.invoiceResponse.advancePaymentAmount - Prepayment / deposit amount applied
 * @param {Number} args.invoiceResponse.invoiceAmount - Remaining balance due amount
 * @param {Object} args.invoiceResponse.InvoiceLineItemsArray - Line items container: { InvoiceLineItem: Array<Object> }
 * @param {Array<Object>} args.invoiceResponse.InvoiceLineItemsArray.InvoiceLineItem - Array of invoice line item objects
 * @param {Object} args.invoiceResponse.TaxArray - Tax lines container: { Tax: Array<Object> }
 * @param {Array<Object>} args.invoiceResponse.TaxArray.Tax - Array of invoice tax breakdown objects
 * @returns {Object} Final validated and calculated invoiceResponse object
 */
function validateAndGetInvoiceData(args) {
  var invoiceResponse = (args && args.invoiceResponse) || {};
  // Example: custom sales amount or tax validation logic
  return invoiceResponse;
}

8. Purchase Order Service 1.0.0 (suite_promoapi_transformers.js)

The Purchase Order service utilizes a dedicated transformer file (suite_promoapi_transformers.js) with 15 hooks intercepting Sales Order record creation across lines, charges, decorations, shipments, customer address upserts, duplicate validation, and commit lifecycle events.

Note: Purchase Order hooks are specified in suite_promoapi_transformers.js, not suite_promoapi_invoice_transformers.js. Purchase Order implementation and support are billed on a time and materials basis.

8.1 Shared Purchase Order Hook Context: hookContext

All Purchase Order transformer hooks receive a shared hookContext object containing dynamic record handles and parsed request data:

  • hookContext.soRecord (NetSuite record.Record): Dynamic NetSuite Sales Order record instance created via record.create({ type: 'salesorder', isDynamic: true }).
  • hookContext.PO (Object): Deserialized PromoStandards Purchase Order request payload:
  • PO.poNumber (String): Customer Purchase Order number
  • PO.orderType (String): "Blank", "Sample", "Simple", "Configured", "Repeat"
  • PO.orderDate (String): PO creation date ISO string
  • PO.lastModified (String): Timestamp of last change
  • PO.totalAmount (Number): Total declared purchase order amount
  • PO.paymentTerms (String): Payment terms description
  • PO.rush (Boolean): Rush production flag
  • PO.salesChannel (String): Sales channel identifier
  • PO.termsAndConditions (String): Terms text
  • PO.LineItemArray (Array<Object>): Array of PO line items
  • PO.ShipmentArray (Array<Object>): Array of shipping destinations and carriers
  • PO.OrderContactArray (Array<Object>): Array of billing, shipping, and sales contacts
  • PO.DigitalProof (Object): Proof and artwork instructions
  • hookContext.userInfo (Object): Authenticated user context:
  • userInfo.customer (String): NetSuite customer internal ID
  • userInfo.username (String): PromoStandards username
  • hookContext.cache (Object): In-memory lookup cache:
  • cache.partIdMap (Object): Map of part SKUs to NetSuite item internal IDs and metadata
  • cache.fobIdMap (Object): Map of FOB IDs to warehouse location internal IDs
  • cache.currencyMap (Object): Map of ISO currency codes to NetSuite currency internal IDs
  • cache.isMultiCurrency (Boolean): Multi-currency active flag

8.2 Line Item Before Commit: partLineItemBeforeCommit

Executed before committing an inventory or assembly item line on the Sales Order.

/**
 * @service Purchase Order Service (1.0.0)
 * @desc Executed before each part line item is committed to the NetSuite Sales Order item sublist.
 *
 * @param {Object} hookContext - Shared PO execution context ({ PO, soRecord, poSetupData, nsCustomer, userInfo })
 * @param {Object} hookContext.PO - Validated PromoStandards Purchase Order payload
 * @param {Object} hookContext.soRecord - Dynamic NetSuite Sales Order record instance
 * @param {Object} hookContext.poSetupData - PO service setup configuration record
 * @param {String|Number} hookContext.nsCustomer - Resolved NetSuite Customer internal ID
 * @param {Object} hookContext.userInfo - Authenticated user credentials and connection metadata
 * @param {Object} hookArgs - Line item iteration data ({ lineItem, part, partIndex, poLineNumber, currentPOLineNumber })
 * @param {Object} hookArgs.lineItem - PromoStandards parent line item object ({ lineNumber, description, lineType, requestedShipDate, requestedInHands, allowPartialShipments, fobId, PartArray, Configuration })
 * @param {Number} hookArgs.lineItem.lineNumber - 1-based line sequence number
 * @param {String} hookArgs.lineItem.description - Line item description
 * @param {String} hookArgs.lineItem.lineType - Line item classification
 * @param {String} hookArgs.lineItem.requestedShipDate - Requested shipment date
 * @param {String} hookArgs.lineItem.requestedInHands - In-hands required date
 * @param {Boolean} hookArgs.lineItem.allowPartialShipments - Partial delivery allowed flag
 * @param {String} hookArgs.lineItem.fobId - Shipping FOB origin ID
 * @param {Array<Object>} hookArgs.lineItem.PartArray - Component parts array
 * @param {Object} hookArgs.lineItem.Configuration - Decoration configuration details
 * @param {Object} hookArgs.part - Current part object ({ partId, customerPartId, description, unitPrice, Quantity })
 * @param {String} hookArgs.part.partId - Supplier part SKU
 * @param {String} hookArgs.part.customerPartId - Customer custom SKU
 * @param {String} hookArgs.part.description - Part description
 * @param {Number} hookArgs.part.unitPrice - Unit price value
 * @param {Object} hookArgs.part.Quantity - Quantity specification ({ value, uom })
 * @param {Number} hookArgs.part.Quantity.value - Quantity count
 * @param {String} hookArgs.part.Quantity.uom - Unit of measure
 * @param {Number} hookArgs.partIndex - 0-based index of part within PartArray
 * @param {Number} hookArgs.poLineNumber - Sequence number across all generated SO lines
 * @param {Number} hookArgs.currentPOLineNumber - Initial line count before current line processing
 * @returns {void}
 */
partLineItemBeforeCommit: function (hookContext, hookArgs) {
  var itemSublistWrapper = hookArgs.itemSublistWrapper;
  var part = hookArgs.part;
  // Example: assign custom department, class, or inspection notes
  itemSublistWrapper.setValue({
    fieldId: 'custcol_ps_part_cust_sku',
    value: part.customerPartId || '',
  });
}

8.3 Order Charge Before Commit: orderChargeLineItemBeforeCommit

Executed before committing an order-level charge line (e.g. rush fees, shipping charges, packaging fees) on the Sales Order.

/**
 * @service Purchase Order Service (1.0.0)
 * @desc Executed before each non-decoration order charge line is committed to the NetSuite Sales Order item sublist.
 *
 * @param {Object} hookContext - Shared PO execution context ({ PO, soRecord, poSetupData, nsCustomer, userInfo })
 * @param {Object} hookContext.PO - Validated PromoStandards Purchase Order payload
 * @param {Object} hookContext.soRecord - Dynamic NetSuite Sales Order record instance
 * @param {Object} hookContext.poSetupData - PO service setup configuration record
 * @param {String|Number} hookContext.nsCustomer - Resolved NetSuite Customer internal ID
 * @param {Object} hookContext.userInfo - Authenticated user credentials and connection metadata
 * @param {Object} hookArgs - Charge iteration data ({ orderCharge, lineItem, currentChargeIndex, poLineNumber })
 * @param {Object} hookArgs.orderCharge - Order charge object ({ chargeId, chargeName, description, unitPrice, Quantity, originalIndex })
 * @param {String|Number} hookArgs.orderCharge.chargeId - Charge SKU / service identifier
 * @param {String} hookArgs.orderCharge.chargeName - Charge title
 * @param {String} hookArgs.orderCharge.description - Charge description
 * @param {Number} hookArgs.orderCharge.unitPrice - Charge unit price
 * @param {Object} hookArgs.orderCharge.Quantity - Charge quantity ({ value, uom })
 * @param {Number} hookArgs.orderCharge.Quantity.value - Charge quantity count
 * @param {String} hookArgs.orderCharge.Quantity.uom - Unit of measure
 * @param {Number} hookArgs.orderCharge.originalIndex - Original charge index
 * @param {Object} hookArgs.lineItem - Parent PromoStandards line item
 * @param {Number} hookArgs.currentChargeIndex - Index of current charge being committed
 * @param {Number} hookArgs.poLineNumber - Sequence number across all generated SO lines
 * @returns {void}
 */
orderChargeLineItemBeforeCommit: function (hookContext, hookArgs) {
  var itemSublistWrapper = hookArgs.itemSublistWrapper;
  var orderCharge = hookArgs.orderCharge;
  log.debug({ title: 'orderChargeLineItemBeforeCommit', details: orderCharge });
}

8.4 Decoration Charge Before Commit: decoChargeLineItemBeforeCommit

Executed before committing setup or run decoration charge lines on the Sales Order.

/**
 * @service Purchase Order Service (1.0.0)
 * @desc Executed before each decoration charge line (setup, run, screen) is committed to the NetSuite Sales Order.
 *
 * @param {Object} hookContext - Shared PO execution context ({ PO, soRecord, poSetupData, nsCustomer, userInfo })
 * @param {Object} hookContext.PO - Validated PromoStandards Purchase Order payload
 * @param {Object} hookContext.soRecord - Dynamic NetSuite Sales Order record instance
 * @param {Object} hookContext.poSetupData - PO service setup configuration record
 * @param {String|Number} hookContext.nsCustomer - Resolved NetSuite Customer internal ID
 * @param {Object} hookContext.userInfo - Authenticated user credentials and connection metadata
 * @param {Object} hookArgs - Decoration charge iteration data ({ decoCharge, lineItem, currentChargeIndex, poLineNumber })
 * @param {Object} hookArgs.decoCharge - Decoration charge object ({ chargeId, chargeName, description, unitPrice, Quantity, chargeType })
 * @param {String|Number} hookArgs.decoCharge.chargeId - Charge SKU / service identifier
 * @param {String} hookArgs.decoCharge.chargeName - Imprint / decoration charge description
 * @param {String} hookArgs.decoCharge.description - Detailed charge description
 * @param {Number} hookArgs.decoCharge.unitPrice - Unit price value
 * @param {Object} hookArgs.decoCharge.Quantity - Charge quantity ({ value, uom })
 * @param {Number} hookArgs.decoCharge.Quantity.value - Charge quantity count
 * @param {String} hookArgs.decoCharge.Quantity.uom - Unit of measure
 * @param {String} hookArgs.decoCharge.chargeType - Decoration charge classification (e.g. "Run", "Setup")
 * @param {Object} hookArgs.lineItem - Parent PromoStandards line item
 * @param {Number} hookArgs.currentChargeIndex - Index of current charge being committed
 * @param {Number} hookArgs.poLineNumber - Sequence number across all generated SO lines
 * @returns {void}
 */
decoChargeLineItemBeforeCommit: function (hookContext, hookArgs) {
  var itemSublistWrapper = hookArgs.itemSublistWrapper;
  var deco = hookArgs.decoration;
  // Example: stamp decoration method onto line item
  itemSublistWrapper.setValue({
    fieldId: 'custcol_imprint_method_name',
    value: deco.decorationName || '',
  });
}

8.5 Shipment Lifecycle Hooks: shipmentBeforeUpdate, getShipmentMethod, & shipmentAfterUpdate

Executed before and after processing each shipment destination in PO.ShipmentArray.

/**
 * @service Purchase Order Service (1.0.0)
 * @desc Executed before updating native Sales Order shipping fields from a PromoStandards Shipment object.
 *
 * @param {Object} hookContext - Shared PO execution context ({ PO, soRecord, poSetupData, nsCustomer, userInfo })
 * @param {Object} hookContext.PO - Validated PromoStandards Purchase Order payload
 * @param {Object} hookContext.soRecord - Dynamic NetSuite Sales Order record instance
 * @param {Object} hookContext.poSetupData - PO service setup configuration record
 * @param {String|Number} hookContext.nsCustomer - Resolved NetSuite Customer internal ID
 * @param {Object} hookContext.userInfo - Authenticated user credentials and connection metadata
 * @param {Object} shipmentHookArgs - Shipment iteration payload ({ shipment, shipmentIndex })
 * @param {Object} shipmentHookArgs.shipment - Validated shipment object ({ shipmentId, shipTo, carrier, service, comments, packageArray })
 * @param {String|Number} shipmentHookArgs.shipment.shipmentId - Shipment identifier
 * @param {Object} shipmentHookArgs.shipment.shipTo - Destination address object ({ customerAddressId, shipToName, address1, address2, address3, city, state, postalCode, country, email, phone })
 * @param {String} shipmentHookArgs.shipment.carrier - Shipping carrier code
 * @param {String} shipmentHookArgs.shipment.service - Shipping service method
 * @param {String} shipmentHookArgs.shipment.comments - Shipping handling instructions
 * @param {Array<Object>} shipmentHookArgs.shipment.packageArray - Packages breakdown
 * @param {Number} shipmentHookArgs.shipmentIndex - 0-based index of shipment within ShipmentArray
 * @returns {void}
 */
shipmentBeforeUpdate: function (hookContext, shipmentHookArgs) {
  log.debug({ title: 'shipmentBeforeUpdate', details: shipmentHookArgs.shipment });
},

/**
 * @service Purchase Order Service (1.0.0)
 * @desc Custom shipping method translator mapping carrier/service strings to NetSuite shipmethod IDs.
 *
 * @param {Object} hookContext - Shared PO execution context ({ PO, soRecord, poSetupData, nsCustomer, userInfo })
 * @param {Object} shipmentHookArgs - Shipment iteration payload ({ shipment, shipmentIndex })
 * @param {Object} shipmentHookArgs.shipment - Validated shipment object ({ shipmentId, shipTo, carrier, service, comments, packageArray })
 * @param {String} shipmentHookArgs.shipment.carrier - Shipping carrier code
 * @param {String} shipmentHookArgs.shipment.service - Shipping service method
 * @param {Number} shipmentHookArgs.shipmentIndex - 0-based index of shipment within ShipmentArray
 * @returns {String|Number} NetSuite shipmethod internal ID
 */
getShipmentMethod: function (hookContext, shipmentHookArgs) {
  var freight = shipmentHookArgs.shipment.FreightDetails || {};
  if (freight.carrier === 'UPS' && freight.service === 'Ground') {
    return '15'; // Internal ID for UPS Ground
  }
  return null; // Fallback to standard lookup
},

/**
 * @service Purchase Order Service (1.0.0)
 * @desc Executed after native Sales Order shipping fields and addresses have been populated.
 *
 * @param {Object} hookContext - Shared PO execution context ({ PO, soRecord, poSetupData, nsCustomer, userInfo })
 * @param {Object} hookContext.PO - Validated PromoStandards Purchase Order payload
 * @param {Object} hookContext.soRecord - Dynamic NetSuite Sales Order record instance
 * @param {Object} shipmentHookArgs - Shipment iteration payload ({ shipment, shipmentIndex })
 * @param {Object} shipmentHookArgs.shipment - Validated shipment object ({ shipmentId, shipTo, carrier, service, comments, packageArray })
 * @param {Number} shipmentHookArgs.shipmentIndex - 0-based index of shipment within ShipmentArray
 * @returns {void}
 */
shipmentAfterUpdate: function (hookContext, shipmentHookArgs) {
  log.debug({ title: 'shipmentAfterUpdate', details: shipmentHookArgs });
}

8.6 Contact & Address Lifecycle Hooks: orderContactsBeforeUpdate, orderContactBeforeUpdate, orderContactAfterUpdate, & orderContactsAfterUpdate

Executed before and after upserting billing, shipping, and sales order contacts as NetSuite Customer address subrecords.

/**
 * @service Purchase Order Service (1.0.0)
 * @desc Executed before iterating through the OrderContactArray to update customer contacts and addresses.
 *
 * @param {Object} hookContext - Shared PO execution context ({ PO, soRecord, poSetupData, nsCustomer, userInfo })
 * @param {Object} hookContext.PO - Validated PromoStandards Purchase Order payload
 * @param {Object} hookContext.soRecord - Dynamic NetSuite Sales Order record instance
 * @param {Object} hookContext.poSetupData - PO service setup configuration record
 * @param {String|Number} hookContext.nsCustomer - Resolved NetSuite Customer internal ID
 * @param {Object} hookContext.userInfo - Authenticated user credentials and connection metadata
 * @returns {void}
 */
orderContactsBeforeUpdate: function (hookContext) {
  log.debug({ title: 'orderContactsBeforeUpdate' });
},

/**
 * @service Purchase Order Service (1.0.0)
 * @desc Executed before an individual contact from OrderContactArray is committed or attached.
 *
 * @param {Object} hookContext - Shared PO execution context ({ PO, soRecord, poSetupData, nsCustomer, userInfo })
 * @param {Object} hookArgs - Individual contact iteration payload ({ contact, contactIndex })
 * @param {Object} hookArgs.contact - Contact entry object ({ contactType, ContactDetails })
 * @param {String} hookArgs.contact.contactType - Contact type enum (e.g. "Order", "Billing", "Shipping")
 * @param {Object} hookArgs.contact.ContactDetails - Contact details ({ attentionTo, companyName, address1, address2, address3, city, state, postalCode, country, email, phone })
 * @param {String} hookArgs.contact.ContactDetails.attentionTo - Attention to name
 * @param {String} hookArgs.contact.ContactDetails.companyName - Company name
 * @param {String} hookArgs.contact.ContactDetails.address1 - Address line 1
 * @param {String} hookArgs.contact.ContactDetails.address2 - Address line 2
 * @param {String} hookArgs.contact.ContactDetails.address3 - Address line 3
 * @param {String} hookArgs.contact.ContactDetails.city - City
 * @param {String} hookArgs.contact.ContactDetails.state - State / Province
 * @param {String} hookArgs.contact.ContactDetails.postalCode - Postal / Zip code
 * @param {String} hookArgs.contact.ContactDetails.country - Country code
 * @param {String} hookArgs.contact.ContactDetails.email - Email address
 * @param {String} hookArgs.contact.ContactDetails.phone - Phone number
 * @param {Number} hookArgs.contactIndex - 0-based index of contact within OrderContactArray
 * @returns {void}
 */
orderContactBeforeUpdate: function (hookContext, hookArgs) {
  var contact = hookArgs.contact;
  var customerRecord = hookArgs.customerRecord;
  // Example: tag customer record with custom buyer department
  customerRecord.setValue({ fieldId: 'custentity_buyer_email', value: contact.ContactDetails.email || '' });
  hookArgs.customerRecordUpdated = true;
},

/**
 * @service Purchase Order Service (1.0.0)
 * @desc Executed after an individual contact has been saved or linked to the Sales Order.
 *
 * @param {Object} hookContext - Shared PO execution context ({ PO, soRecord, poSetupData, nsCustomer, userInfo })
 * @param {Object} hookArgs - Individual contact iteration payload ({ contact, contactIndex, addressRecordId })
 * @param {Object} hookArgs.contact - Contact entry object ({ contactType, ContactDetails })
 * @param {String|Number} hookArgs.addressRecordId - Saved NetSuite address record internal ID
 * @param {Number} hookArgs.contactIndex - 0-based index of contact within OrderContactArray
 * @returns {void}
 */
orderContactAfterUpdate: function (hookContext, hookArgs) {
  log.debug({ title: 'orderContactAfterUpdate', details: 'Address ID: ' + hookArgs.addressRecordId });
},

/**
 * @service Purchase Order Service (1.0.0)
 * @desc Executed after all contacts in OrderContactArray have been processed and attached.
 *
 * @param {Object} hookContext - Shared PO execution context ({ PO, soRecord, poSetupData, nsCustomer, userInfo })
 * @param {Object} hookContext.PO - Validated PromoStandards Purchase Order payload
 * @param {Object} hookContext.soRecord - Dynamic NetSuite Sales Order record instance
 * @returns {void}
 */
orderContactsAfterUpdate: function (hookContext, contactsAfterArgs) {
  log.debug({ title: 'orderContactsAfterUpdate' });
}

8.7 Order Commit Lifecycle Hooks: beforeSave & afterSave

Executed immediately before calling soRecord.save() and immediately after successful transaction commit.

/**
 * @service Purchase Order Service (1.0.0)
 * @desc Final pre-save interceptor called immediately before committing the Sales Order record.
 *
 * @param {Object} hookContext - Shared PO execution context ({ PO, soRecord, poSetupData, nsCustomer, userInfo })
 * @param {Object} hookContext.PO - Validated PromoStandards Purchase Order payload
 * @param {Object} hookContext.soRecord - Dynamic NetSuite Sales Order record instance
 * @param {Object} hookContext.poSetupData - PO service setup configuration record
 * @param {String|Number} hookContext.nsCustomer - Resolved NetSuite Customer internal ID
 * @param {Object} hookContext.userInfo - Authenticated user credentials and connection metadata
 * @returns {void}
 */
beforeSave: function (hookContext) {
  var soRecord = hookContext.soRecord;
  var firstLine = hookContext.PO.LineItemArray && hookContext.PO.LineItemArray[0];
  if (firstLine && firstLine.lineType === 'Repeat') {
    soRecord.setValue({
      fieldId: 'custbody_extend_ps_se_repeat_order',
      value: true,
    });
  }
},

/**
 * @service Purchase Order Service (1.0.0)
 * @desc Post-save lifecycle hook invoked immediately after the Sales Order is successfully saved to the database.
 *
 * @param {Object} hookContext - Shared PO execution context ({ PO, soRecord, poSetupData, nsCustomer, userInfo })
 * @param {Object} hookContext.PO - Validated PromoStandards Purchase Order payload
 * @param {Object} hookContext.soRecord - Dynamic NetSuite Sales Order record instance
 * @param {Object} hookArgs - Post-commit result payload ({ recordId })
 * @param {String|Number} hookArgs.recordId - NetSuite internal ID of the committed Sales Order
 * @returns {void}
 */
afterSave: function (hookContext, hookArgs) {
  log.audit({
    title: 'PO Created Successfully',
    details: 'Sales Order Internal ID: ' + hookArgs.recordId + ' for PO: ' + hookContext.PO.poNumber,
  });
}

8.8 Duplicate PO Validation Hooks: getOrderSearch & getOrderSearchResults

Allows full customization of the NetSuite duplicate Purchase Order detection search.

/**
 * @service Purchase Order Service (1.0.0)
 * @desc Custom duplicate PO check search constructor returning a NetSuite Search instance.
 *
 * @param {Object} args
 * @param {Object} args.PO - Incoming PromoStandards Purchase Order payload ({ poNumber, orderType, orderDate, totalAmount })
 * @param {String} args.PO.poNumber - Customer purchase order number
 * @param {String} args.PO.orderType - Order type
 * @param {String} args.PO.orderDate - Order creation ISO timestamp
 * @param {Number} args.PO.totalAmount - Total order dollar amount
 * @returns {Object} NetSuite Search instance
 */
getOrderSearch: function (args) {
  var po = args.PO;
  return search.create({
    type: 'salesorder',
    filters: [
      ['mainline', 'is', 'T'],
      'and',
      ['otherrefnum', 'equalto', po.poNumber],
    ],
    columns: ['internalid', 'status', 'tranid'],
  });
},

/**
 * @service Purchase Order Service (1.0.0)
 * @desc Filters or interprets the duplicate PO search results to determine if an existing order should block or update.
 *
 * @param {Object} args
 * @param {Object} args.PO - Incoming PromoStandards Purchase Order payload ({ poNumber, orderType, orderDate, totalAmount })
 * @param {String} args.PO.poNumber - Customer purchase order number
 * @param {String} args.PO.orderType - Order type
 * @param {String} args.PO.orderDate - Order creation ISO timestamp
 * @param {Number} args.PO.totalAmount - Total order dollar amount
 * @param {Array<Object>} args.searchResults - NetSuite SearchResult rows returned from initial lookup
 * @returns {Array<Object>} Filtered search results array
 */
getOrderSearchResults: function (args) {
  return args.searchResults || [];
}

8.9 Supported Order Types: getSupportedOrderTypes

Defines which PromoStandards purchase order types are accepted by the endpoint.

/**
 * @service Purchase Order Service (1.0.0)
 * @desc Declares the PromoStandards order types supported by the supplier's integration endpoint.
 *
 * @returns {Array<String>} Array of supported order type string literals (e.g. ["Simple", "Configured", "Blank", "Sample"])
 */
getSupportedOrderTypes: function () {
  return ['Blank', 'Sample', 'Simple', 'Configured', 'Repeat'];
}