v4.0.0

Merge Node SDK Release Notes - Version [4.0.0]

Release Date: [2026-03-11]

This release includes support for all of the latest updates to the Merge API. For more information, see https://www.merge.dev/changelog

---

Breaking Changes

Pagination API Overhaul:

All list() methods now return Page instead of HttpResponsePromise. The new Page object supports async iteration, built-in next page fetching, and direct access to the raw response.

  //  v3.x
  const result = client.accounting.invoices.list({ accountId: "..." });
  const response = await result;
  const items = response.results; // access paginated list directly

  //  v4.x
  const page = await client.accounting.invoices.list({ accountId: "..." });
  const items = page.data;                    // array of items on current page
  const fullResponse = page.response;         // full PaginatedInvoiceList object
  const raw = page.rawResponse;               // raw HTTP response

  // Check and fetch next page
  if (page.hasNextPage()) {
      const nextPage = await page.getNextPage();
  }

  // Or iterate through all pages automatically
  for await (const item of page) {
      console.log(item);
  }

Expand Parameter Type Changes:

Expand parameters changed from large string union types to individual enum items that accept a single value or an array. Old union combination types (e.g. "company,addresses,phone_numbers") have been removed.

    //  v3.x - Single combined string union
    const contacts = await client.accounting.contacts.list({
        expand: "company,addresses,phone_numbers"
    });

    //  v4.x - Single value or array of individual items
    const contacts = await client.accounting.contacts.list({
        expand: ["company", "addresses", "phone_numbers"]
    });

    // Single expand still works
    const contacts = await client.accounting.contacts.list({
        expand: "company"
    });

Affected types: All *ListRequestExpand and *RetrieveRequestExpand types have been replaced with *ListRequestExpandItem and *RetrieveRequestExpandItem equivalents across Accounting, ATS, CRM, HRIS, Ticketing, and File Storage modules.

---

Improvements

New Accounting Resources
- Sales Orders (client.accounting.salesOrders) - Full CRUD with list, create, retrieve, bulk create, and remote field classes support.
- Item Fulfillments (client.accounting.itemFulfillments) - Complete resource for managing item fulfillments with the same full operation set.

Bulk Operations Support
New bulk create and retrieve operations across major accounting endpoints including Invoices, Expenses, Sales Orders, and Item Fulfillments.

    // Initiate a bulk create operation
    const bulkResult = await client.accounting.invoices.bulkCreate({
        batchItems: [{ model: invoiceData1 }, { model: invoiceData2 }],
    });

    // Retrieve batch operation results
    const batchResults = await client.accounting.invoices.bulkRetrieve(batchId);

Typed Batch Status Enums
Batch operation status fields are typed with proper enums:
- BatchObjectStatusEnum: PENDING, SUCCESS, FAILURE
- BatchObjectsResponseStatusEnum: ENQUEUED, IN_PROGRESS, PARTIAL_SUCCESS, SUCCESS, FAILED, RATE_LIMITED

---

Notes

The method field on DataPassthroughRequest in the Accounting module has been narrowed from MethodEnum | string to MethodEnum, aligning it with the other five modules (ATS, CRM, HRIS,
Ticketing, File Storage) which already used MethodEnum directly. Enum validation at runtime continues to accept any strings, so this is a TypeScript compile-time change only.

Thank you for using Merge SDKs!