SuiteScript Async and Promise Patterns — Writing Modern, Efficient Code in NetSuite 2.1

Introduction

With the release of SuiteScript 2.1, NetSuite finally embraced modern JavaScript syntax — including Async/Await, Promises, and arrow functions.

These features make your scripts cleaner, faster, and easier to maintain, especially when dealing with asynchronous operations like record loading, searching, or external API calls.

In this blog, you’ll learn:

• How async and promises work in SuiteScript 2.1.
• Why async functions simplify your code.
• Common pitfalls when mixing synchronous and asynchronous calls.
• Real-world examples you can apply in your scripts today.

Why Async/Await in SuiteScript 2.1?

In traditional SuiteScript 2.0, most operations (like record.load(), search.run()) are synchronous — they block the thread until they finish.

But when integrating with external APIs (RESTlets, third-party systems), synchronous code becomes a bottleneck.

Using async/await allows your script to handle asynchronous tasks without freezing execution.

🧠 Analogy:

Think of it as multitasking — your script can fetch data from Shopify or Salesforce while continuing to process other tasks.

Understanding Promises in SuiteScript

A Promise represents an operation that may complete in the future.

Example:

function getCustomerData(id) {
  return new Promise((resolve, reject) => {
    try {
      const customer = record.load({
        type: record.Type.CUSTOMER,
        id: id
      });
      resolve(customer);
    } catch (error) {
      reject(error);
    }
  });
}

You can then use it like:

getCustomerData(123)
  .then(customer => log.debug('Customer Name', customer.getValue('entityid')))
  .catch(err => log.error('Error loading customer', err));

Async/Await Example (SuiteScript 2.1)

With SuiteScript 2.1, you can simplify the above Promise-based code using async and await:

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

  const execute = async () => {
    try {
      const customer = await loadCustomer(123);
      log.debug('Customer Loaded', customer.getValue('entityid'));
    } catch (error) {
      log.error('Error', error);
    }
  };

  const loadCustomer = async (id) => {
    return record.load({ type: record.Type.CUSTOMER, id });
  };

  return { execute };
});

✅ Cleaner syntax
✅ Better readability
✅ Easy error handling with try/catch

Combining Async with External APIs

Async/await shines when calling REST APIs or external services.

Example (fetching data from Shopify API):

define(['N/https', 'N/log'], (https, log) => {

  const execute = async () => {
    const url = 'https://api.shopify.com/v1/products.json';
    const headers = { 'Authorization': 'Bearer YOUR_TOKEN' };

    try {
      const response = await https.get({ url, headers });
      const data = JSON.parse(response.body);
      log.debug('Products', data.products.length);
    } catch (err) {
      log.error('API Error', err.message);
    }
  };

  return { execute };
});

This pattern ensures your script waits for the response without locking the system.

Parallel Execution with Promise.all()

When you need to run multiple asynchronous tasks at once:

const [customer, invoice] = await Promise.all([
  record.load.promise({ type: record.Type.CUSTOMER, id: 1001 }),
  record.load.promise({ type: record.Type.INVOICE, id: 2002 })
]);

log.debug('Loaded Records', `Customer: ${customer.id}, Invoice: ${invoice.id}`);

This executes both loads simultaneously, reducing total execution time.

Common Pitfalls to Avoid

⚠️ Don’t mix async/await with non-promise-based APIs incorrectly.
⚠️ Ensure your NetSuite version supports SuiteScript 2.1 (enabled in account).
⚠️ Avoid long async chains inside loops — use batching or Promise.all instead.
⚠️ Always handle rejections using try/catch or .catch().

Benefits of Async and Promise Patterns

Real-World Use Cases

• API Integrations (Shopify, Salesforce, PayPal, CommerceHub)
• Long-running Scheduled Scripts (async data fetch + processing)
• Suitelet Interfaces (fetching live data from external sources)
• Map/Reduce async batch processing

Conclusion

Async and Promise patterns bring NetSuite SuiteScript up to modern JavaScript standards. They reduce complexity, improve readability, and allow developers to handle large-scale integrations efficiently.

If you’re building anything that interacts with external systems or performs heavy data operations, learning async/await is essential.