N/format Module in NetSuite: Complete Guide to Date Formatting and Parsing in SuiteScript

The N/format module is one of the most underestimated modules in SuiteScript 2.1. If you’ve ever struggled with date comparisons failing, saved searches returning wrong results due to date string mismatches, or date fields not saving correctly — N/format is almost always the solution. This guide covers everything you need to know to work confidently with dates and other data types in NetSuite SuiteScript.

What is the N/format Module?

The N/format module provides utility functions for converting NetSuite field values between their internal (raw) format and their user-facing display format. It is especially important for date, datetime, and currency fields, which NetSuite stores internally in a normalized format that differs from what is displayed to the user.

Any time you read a date from a record, pass a date to a saved search filter, or write a date back to a field, you need to be aware of how NetSuite formats and parses that value. N/format makes this explicit and reliable.

How to Load the N/format Module

/**
 * @NApiVersion 2.1
 * @NScriptType Suitelet
 */
define(['N/format'], (format) => {
    const onRequest = (context) => {
        // format is now available
    };
    return { onRequest };
});

format.format() — Convert a JavaScript Date to a NetSuite String

Use format.format() to convert a JavaScript Date object (or a raw value) into the string format that NetSuite expects for a specific field type. This is the function you use before writing a value to a date field or passing it to a search filter.

/**
 * @NApiVersion 2.1
 * @NScriptType ScheduledScript
 */
define(['N/format', 'N/record'], (format, record) => {
    const execute = (context) => {
        // Create a JavaScript Date for today
        const today = new Date();

        // Format it as a NetSuite date string (e.g., "05/16/2026")
        const formattedDate = format.format({
            value: today,
            type: format.Type.DATE
        });

        log.debug('Formatted Date', formattedDate);

        // Now write it to a Sales Order's expected ship date
        record.submitFields({
            type: record.Type.SALES_ORDER,
            id: 1001,
            values: {
                shipdate: formattedDate
            }
        });
    };
    return { execute };
});

The output of format.format() depends on the user’s locale and date format preference set in NetSuite. In most US installations this will produce a string like 05/16/2026, while European installations may produce 16/05/2026. Never hard-code a date string — always use format.format() to produce the correct value for the running user’s environment.

format.parse() — Convert a NetSuite Date String Back to a JavaScript Date

Use format.parse() to convert a NetSuite-formatted date string (as returned by record.getValue() on a date field) back into a JavaScript Date object. This allows you to do arithmetic, comparisons, and calculations on the date in plain JavaScript.

/**
 * @NApiVersion 2.1
 * @NScriptType UserEventScript
 */
define(['N/format', 'N/log'], (format, log) => {
    const beforeSubmit = (context) => {
        const rec = context.newRecord;

        // Read a date field — this returns a string like "05/16/2026"
        const closeDateStr = rec.getValue({ fieldId: 'closedate' });

        if (!closeDateStr) {
            log.error('Missing Date', 'closedate is empty');
            return;
        }

        // Parse it into a real JavaScript Date object
        const closeDate = format.parse({
            value: closeDateStr,
            type: format.Type.DATE
        });

        // Now do date arithmetic — check if close date is in the past
        const today = new Date();
        today.setHours(0, 0, 0, 0);

        if (closeDate < today) {
            log.audit('Overdue Record', 'Close date is in the past: ' + closeDateStr);
        }
    };
    return { beforeSubmit };
});

Working with DATETIME Fields

NetSuite has separate format types for DATE (date only) and DATETIME (date and time). If you're working with fields like Created Date, Last Modified Date, or any timestamp field, use format.Type.DATETIME instead of format.Type.DATE.

/**
 * @NApiVersion 2.1
 * @NScriptType Suitelet
 */
define(['N/format', 'N/record'], (format, record) => {
    const onRequest = (context) => {
        const rec = record.load({
            type: record.Type.SALES_ORDER,
            id: 1001
        });

        // Read the createddate field — returns a datetime string
        const createdDateStr = rec.getValue({ fieldId: 'createddate' });

        // Parse the datetime string to a JavaScript Date
        const createdDate = format.parse({
            value: createdDateStr,
            type: format.Type.DATETIME
        });

        log.debug('Created Date Object', createdDate.toISOString());

        // Add 30 days and format it back
        const reminderDate = new Date(createdDate);
        reminderDate.setDate(reminderDate.getDate() + 30);

        const reminderFormatted = format.format({
            value: reminderDate,
            type: format.Type.DATE
        });

        log.debug('30-Day Reminder Date', reminderFormatted);
    };
    return { onRequest };
});

All Supported format.Type Values

The N/format module supports many data types beyond dates. Here is a complete reference of the most commonly used format.Type values in SuiteScript 2.1:

format.Type	Description	Example Raw Value
DATE	Date only field	05/16/2026
DATETIME	Date and time field	05/16/2026 3:45 pm
DATETIMETZ	Date, time, and timezone	05/16/2026 3:45 pm America/New_York
INTEGER	Whole number	1000
FLOAT	Decimal number	1234.56
CURRENCY	Currency amount	1,234.56
CURRENCY2	Secondary currency amount	1,234.56
PERCENT	Percentage value	12.5%
RATE	Exchange rate	1.2345
RATIO	Ratio field	1:2
BOOLEAN	Checkbox / true-false	T / F
MMYYDATE	Month/Year only	05/2026
TIMEOFDAY	Time field only	3:45 pm

Practical Example: Calculate Days Between Two Dates

One of the most common use cases for N/format is calculating the number of days between two NetSuite date field values. Here is a reusable helper function that you can use in any script type:

/**
 * @NApiVersion 2.1
 * @NScriptType UserEventScript
 */
define(['N/format', 'N/log'], (format, log) => {

    /**
     * Returns the number of days between two NetSuite date strings.
     * @param {string} startDateStr - NetSuite formatted date string (e.g. "01/01/2026")
     * @param {string} endDateStr   - NetSuite formatted date string (e.g. "05/16/2026")
     * @returns {number} Number of calendar days between the two dates
     */
    const daysBetween = (startDateStr, endDateStr) => {
        const start = format.parse({ value: startDateStr, type: format.Type.DATE });
        const end   = format.parse({ value: endDateStr,   type: format.Type.DATE });
        const msPerDay = 1000 * 60 * 60 * 24;
        return Math.round((end - start) / msPerDay);
    };

    const afterSubmit = (context) => {
        const rec = context.newRecord;
        const startDate = rec.getValue({ fieldId: 'startdate' });
        const endDate   = rec.getValue({ fieldId: 'enddate' });

        if (startDate && endDate) {
            const days = daysBetween(startDate, endDate);
            log.audit('Duration', 'This project spans ' + days + ' days');
        }
    };

    return { afterSubmit };
});

Practical Example: Add Business Days to a Date

A common business requirement is to set a due date a certain number of business days (weekdays only) from today. Here is how to implement that using N/format to parse and re-format the dates:

/**
 * @NApiVersion 2.1
 * @NScriptType ScheduledScript
 */
define(['N/format', 'N/record'], (format, record) => {

    /**
     * Adds a number of business days (Mon–Fri) to a given date.
     * @param {Date} startDate - JavaScript Date to start from
     * @param {number} daysToAdd - Number of business days to add
     * @returns {Date} Resulting JavaScript Date
     */
    const addBusinessDays = (startDate, daysToAdd) => {
        let current = new Date(startDate);
        let added = 0;
        while (added < daysToAdd) {
            current.setDate(current.getDate() + 1);
            const dow = current.getDay(); // 0 = Sunday, 6 = Saturday
            if (dow !== 0 && dow !== 6) {
                added++;
            }
        }
        return current;
    };

    const execute = (context) => {
        const today = new Date();
        const dueDate = addBusinessDays(today, 5); // 5 business days from now

        const dueDateFormatted = format.format({
            value: dueDate,
            type: format.Type.DATE
        });

        log.debug('Due Date (5 business days)', dueDateFormatted);

        // Write to a custom task record
        record.submitFields({
            type: 'customrecord_task',
            id: 42,
            values: {
                custrecord_due_date: dueDateFormatted
            }
        });
    };

    return { execute };
});

Using N/format in Saved Search Filters

When building dynamic saved searches in SuiteScript, date filter values must be formatted as NetSuite date strings — not JavaScript Date objects and not ISO strings. Use format.format() to convert your JavaScript Date to the correct string before passing it as a filter value.

/**
 * @NApiVersion 2.1
 * @NScriptType Suitelet
 */
define(['N/format', 'N/search'], (format, search) => {
    const onRequest = (context) => {
        // Get the date 30 days ago as a NetSuite string
        const thirtyDaysAgo = new Date();
        thirtyDaysAgo.setDate(thirtyDaysAgo.getDate() - 30);

        const filterDate = format.format({
            value: thirtyDaysAgo,
            type: format.Type.DATE
        });

        // Search for all Sales Orders created in the last 30 days
        const results = search.create({
            type: search.Type.SALES_ORDER,
            filters: [
                ['trandate', 'onorafter', filterDate]
            ],
            columns: ['tranid', 'entity', 'trandate', 'amount']
        }).run().getRange({ start: 0, end: 50 });

        results.forEach((result) => {
            log.debug('Order', result.getValue('tranid') + ' | ' + result.getValue('trandate'));
        });
    };
    return { onRequest };
});

Common Mistakes and How to Avoid Them

The three most frequent N/format mistakes in SuiteScript development are using JavaScript's toLocaleDateString() or toISOString() instead of format.format() (which produces a string NetSuite does not recognize), forgetting to call format.parse() before doing date arithmetic (which causes NaN or wrong results because strings cannot be subtracted), and mixing DATE and DATETIME types when formatting and parsing (which can introduce timezone shifts).

Always match the format.Type you use in format.parse() to the field type in NetSuite. If the field is a Date field, use format.Type.DATE. If it is a Date/Time field, use format.Type.DATETIME. Using the wrong type will produce unexpected results silently without throwing an error.

Governance and Performance Notes

The N/format module functions are synchronous utility calls that execute entirely in the SuiteScript runtime — they do not make any API calls to the NetSuite server and therefore have zero governance cost. You can call format.format() and format.parse() as many times as needed inside a loop without any concern about governance limits. This makes N/format one of the most efficient tools in SuiteScript 2.1.

Next Steps

Now that you understand how to work with dates and data types using N/format, a natural next step is combining this with the N/search module for date-filtered bulk searches, or the N/record module for reading and writing date fields on records. You can also explore the N/runtime module to access the current user's date format preference if you need to build locale-aware utilities in your scripts.