Zoho Books API: Bulk update thousands of records using Node.js with OAuth refresh, retries and resume support

Zoho Books API: Bulk update thousands of records using Node.js with OAuth refresh, retries and resume support

Hello everyone,

During Zoho Books implementations, one common challenge is updating a large number of existing records. The current options are usually:

  • Update records manually from the UI using Mass Update (with limited batch size).
  • Update records one by one through code using the API.

For large data corrections, migrations, or post-implementation changes, manually updating records is not practical, so I created a Node.js utility that safely performs bulk custom-field updates through the Zoho Books API.

The workflow

  1. Create a custom view containing the records that need to be updated.
  2. Export the records and extract their IDs into a text file (one ID per line).
  3. Point the script at the IDs file.
  4. Define the custom fields and new values in .env.
  5. Run the migration in three stages: probe → dry-run → run.

Alternatively, instead of exporting IDs manually, you can write a small search function that retrieves the records you need and generates the IDs file automatically.

What the script supports

  • Multiple custom-field updates in the same request.
  • Any Books module (recurring invoices, invoices, contacts, bills, ...) via configuration — no code changes.
  • Zero-ceremony OAuth: you provide only the Self Client grant code — the script exchanges it for a refresh token on first run, persists it locally, and mints access tokens automatically from then on. No manual token calls, no hardcoded tokens.
  • Automatic re-refresh if Zoho invalidates the access token mid-run (401 handling).
  • Request timeouts, retry with backoff for HTTP 429 and 5xx (honours Retry-After).
  • Canary update: one record is updated and verified with a follow-up GET before the batch starts — a typo in a dropdown value aborts after one record, not after thousands.
  • Progress milestones roughly every 10% of the batch, with a live ETA (the initial estimate is measured from the canary request's actual round-trip, not guessed).
  • Resume capability: every outcome is appended to results.jsonl; re-running skips records already updated successfully. A token problem or a network drop mid-run costs nothing.
  • Failed-ID export (failed_ids.txt) for targeted retry.

Configuration

Everything lives in .env. You need exactly: data center, org ID, client ID/secret, a Self Client grant code, the module, the IDs file, and the fields to set — nothing else:

ZB_DC=eu
ZB_ORG_ID=123456789

ZB_CLIENT_ID=1000.xxxxx
ZB_CLIENT_SECRET=xxxxx
ZB_AUTH_CODE=1000.xxxxx

ZB_MODULE=recurringinvoices

ZB_IDS_FILE=invoice_ids.txt
ZB_THROTTLE_MS=700

ZB_FIELDS=[{"api_name":"cf_status","value":"Approved"},{"api_name":"cf_sync_date","value":"2026-07-16"}]

ZB_AUTH_CODE is the grant code from the API console (Self Client → Generate Code, with the scopes below). It is single-use and expires within 3–10 minutes, so run the script right after generating it — the first run exchanges it for a permanent refresh token and saves it to .zb_token_store.json. Add both .env and .zb_token_store.json to .gitignore, and revoke the client when the migration is done.

Gotchas worth knowing:

  • ZB_FIELDS must stay on a single line — dotenv does not parse unquoted multi-line values.
  • ZB_DC must match the data center the client was created on. A client from api-console.zoho.eu will not authenticate against accounts.zoho.com.
  • If the exchange fails with invalid_code, the grant code expired or was already consumed — generate a fresh one and re-run immediately.

ZB_MODULE is the URL path segment (recurringinvoices, invoices, contacts, ...). Note that Books responses wrap the record in a singular root key (invoice, recurring_invoice, ...) that doesn't match the URL segment — the script auto-detects it from the first GET, so you don't have to know this.

Usage

Probe the configuration and field mapping (read-only — this also performs the one-time grant-code exchange on first run):

bash
node zoho-books-bulk-cf-update.mjs probe

Update and verify one record, then stop:

bash
node zoho-books-bulk-cf-update.mjs dry-run

Execute the complete migration:

bash
node zoho-books-bulk-cf-update.mjs run

Sample run output:

48 IDs total · 0 already ok · 48 pending
  auto-detected response entity key: "invoice"
Probe 639896000003678005: custom_fields present: cf_status, cf_sync_date, ...
  cf_status → customfield_id 639896000000729241 (current: "Draft")
Canary update on 639896000003678005 ...
Canary verified.
Small batch (47 records) — throttle lowered to 300 ms.
1/48 · ETA 1.1 min
5/48 · ETA 1.0 min
10/48 · ETA 0.9 min
...
48/48 Done · ok=48 fail=0

Implementation details

The update process intentionally runs sequentially instead of firing parallel requests, to respect the per-minute API limit (100 requests/min per organization), avoid failures caused by throttling, and keep the migration predictable. The default 700 ms delay keeps the rate at roughly 85 requests/min. Batches of 90 records or fewer physically cannot breach the per-minute cap, so the script speeds those up automatically.

One detail that matters across orgs: custom fields in the update payload are addressed by customfield_id where possible. The script GETs one record first, resolves each api_name to its customfield_id, and only falls back to api_name addressing if the field is not present on the sample record.

Required scopes:

ZohoBooks.invoices.READ
ZohoBooks.invoices.UPDATE

(or the equivalent scopes for the module you are updating — always least-privilege rather than ZohoBooks.fullaccess.all)

Production considerations

  • Mind the daily API cap as well as the per-minute one — it varies by Books plan. A 10,000-record migration may need to be split across days on lower plans.
  • Dropdown custom fields must receive a value that matches an option exactly (spacing, hyphens, casing — especially with non-Latin characters). The canary catches this before the batch runs.
  • An in-memory ID list is fine into the tens of thousands; the point of results.jsonl is durability — progress survives crashes, token expiry, and Ctrl+C.
  • For extremely large or recurring migrations, the same logic can move into a queue-based Node.js worker where you control execution time, retry strategy, parallelism, and monitoring.

Where this is useful

  • Updating custom fields after migrations.
  • Fixing incorrectly imported data.
  • Updating integration-generated records.
  • Applying bulk corrections after changing business logic.
  • Cleaning up data after implementation projects.

Sharing this pattern because bulk updates are a common challenge when working with the Zoho Books API. Script and example .env attached.


      Zoho Campaigns Resources


        • Desk Community Learning Series


        • Digest


        • Functions


        • Meetups


        • Kbase


        • Resources


        • Glossary


        • Desk Marketplace


        • MVP Corner


        • Word of the Day


        • Ask the Experts


          Zoho CRM Plus Resources

            Zoho Books Resources


              Zoho Subscriptions Resources

                Zoho Projects Resources


                  Zoho Sprints Resources


                    Zoho Orchestly Resources


                      Zoho Creator Resources


                        Zoho WorkDrive Resources



                          Zoho CRM Resources

                          • CRM Community Learning Series

                            CRM Community Learning Series


                          • Tips

                            Tips

                          • Functions

                            Functions

                          • Meetups

                            Meetups

                          • Kbase

                            Kbase

                          • Resources

                            Resources

                          • Digest

                            Digest

                          • CRM Marketplace

                            CRM Marketplace

                          • MVP Corner

                            MVP Corner




                            Zoho Writer Writer

                            Get Started. Write Away!

                            Writer is a powerful online word processor, designed for collaborative work.

                              Zoho CRM コンテンツ



                                ご検討中の方

                                  • Recent Topics

                                  • Frustrated with Zoho Assist QuickSUpport

                                    Trialling Zoho Assist and I have a variety of clients. A lot are computer illiterate. Some have poor vision. The current support sessions are using apps which have desktop icons for the appropriate apps. I either connect on demand then the client approves

                                  • CRM x WorkDrive: We're rolling out the WorkDrive-powered file storage experience for existing users

                                    Release plan: Gradual rollout to customers without file storage add-ons, in this order: 1. Standalone CRM 2. CRM Plus and Zoho One DCs: All | Editions: All Available now for: - Standalone CRM accounts in Free and Standard editions without file storage

                                  • Zoho CRM Copilot Connector

                                    Hello, Are there plans to release a connector for Zoho CRM and Copilot? I'm in the early research stages of potentially switching our CRM solution to Microsoft Dynamics because of its out of the box integration with Copilot. The advantage being that we

                                  • Zoho Projects - Will there ever be a send email feature in Zoho Project?

                                    Hi team, Are there plans to or will there ever be a sendemail feature in Zoho Projects, brining it in line with other similar platforms like Asana, ClickUp and Monday? I know that you can add comments via email to a specific task, but I believe this only

                                  • Introducing Microsoft Word Integration in Zoho Contracts

                                    We are excited to announce a new feature that brings contract authoring and negotiation in your familiar environment — the Microsoft Word Integration. What This Integration Brings The Microsoft Word Integration connects Zoho Contracts with the Microsoft

                                  • Share Video Response Card ion Zobot

                                    I am using the zobot codeless bot builder in SalesIQ. I want to share a video but delay the next response card until after the video has finished playing or has been stopped. Is this possible?

                                  • Customer image field

                                    I created a custom image field for estimates, and it works as expected. The only issue I have is that I want to be able to place the custom image field in the estimate invoice. Is there a way I can do that, the field does not give the option to display

                                  • Sub Folders

                                    It would be great if there could be sub-folders in reports. We have a ton of individual reports and folders that would be easier to navigate this way 

                                  • Goals API - Zoho People

                                    Hi Team, I would like to get the API details for retrieving organisation-wise Goals from Zoho People. Currently, I am able to retrieve individual employee goals using the following API: https://people.zoho.com/api/v3/performance/goal/{emp_id} However,

                                  • Question and responses disapear

                                    I have a form where several people have had issues where the questions, responses or submission simply disappear when trying to complete the form. It seems to be random with no pattern of question, browser or OS. Hopefully there is a fix in the platform

                                  • Unable to send message;Reason:553 Relaying disallowed. Invalid Domain

                                    Hi, Now when I try to reply to an email, I see the Unable to send message;Reason:553 Relaying disallowed. Invalid Domain voicemessagedownloader.com error. I tested sending an email when I set it up in the past and it worked. I have checked the Zoho Organization

                                  • Guide customers to the right booking page with routing forms

                                    Greetings from the Zoho Bookings team! We're excited to introduce Routing Forms in Zoho Bookings. Routing forms let you collect information from customers before they schedule an appointment and automatically direct them to the most appropriate booking

                                  • Analytics Dashboard User Filters Default Value

                                    User Filters on Dashboard do not allow Unknown to be set as a default filter value. I have to include NULL values in my dashboard among other values but I can't include NULL/Unknown by default in Dashboard User Filters.

                                  • Horrible download speed

                                    Using a trial of Zoho Assist and downloading a 316 MB file on a 500/500 fibre connection to a remote computer on the same network took 7 mins to complete. On AnyDesk it took 1 min or so.

                                  • How to Backup Zoho to PST?

                                    I'm looking for a simple way to backup Zoho Mail emails to PST format. I tried the IMAP method with Outlook, but it seems slow and complicated for large mailboxes. I need a solution that can: Export Zoho emails to PST Preserve attachments and folder hierarchy

                                  • Zoho Books | Product updates | August 2026

                                    Hello users, July has been an exciting month for Zoho Books! This month, we're excited to introduce HTML PDF Templates, Placeholders as Pills, expanded approval workflows for Sales Returns and Journals, and significant compliance updates across the India,

                                  • Action required: WhatsApp now uses BSUID as the primary identifier

                                    Important If your support team uses WhatsApp to engage with customers, there is an important platform change you need to know about. BSUID support is now mandatory for all WhatsApp Business Platform partners and businesses. WhatsApp is introducing usernames,

                                  • Tip #83- Give Customers a Faster Way to Reach You with the Quick Support Plugin – 'Insider Insights'

                                    Hello Zoho Assist Community! Think about the last time a customer needed urgent support. They emailed in, waited for a response, got a session link, couldn't find it in their inbox, called back, and by the time the session actually started, a good chunk

                                  • Final Notice: Migrate Your ASAP Mobile SDK by August 31

                                    Alert August 31, 2026 is the deadline. After this date, older ASAP Mobile SDK versions will no longer work with the ASAP Help Widget. If your app hasn't been migrated to a supported SDK version, users will no longer be able to access the ASAP Help Widget

                                  • Approval Process configuration is now more flexible and fully customizable

                                    Hello everyone! Zoho CRM's Approval Process is back with a better user experience that makes it easier to add rules to your processes. This enhancement includes some UI updates that help you create highly structured approval stages—and more. Let's look

                                  • Kaizen #255 - Building a Real-Time Operational Dashboard with Zoho CRM Queries

                                    Hello Everyone, Welcome back to another edition of the Kaizen series, where we uncover powerful ways to extend and customize Zoho CRM. In the previous Query Kaizens, we explored how Queries can retrieve CRM data, invoke REST APIs, and even update CRM

                                  • 【Zoho CRM】キオスクに「ループ機能」が追加｜同じ処理を繰り返し実行可能に

                                    ユーザーの皆さま、こんにちは。 コミュニティグループの中野です。 Zoho CRMのキオスクに、同じ処理を繰り返し実行できる「ループ機能」が追加されました。 これまでは、同じ処理を複数回実行したい場合、同じ設定を繰り返し作成する必要がありました。 ループ機能を使うと、処理を一度設定するだけで、指定した回数や 取得したデータ数に応じて自動的に繰り返すことができます。 目次 ループ機能とは 設定方法 注意点 1. ループ機能とは ループ機能を使うと、キオスク内の画面や処理を指定した条件に応じて繰り返し実行できます。

                                  • Es posible cambiar el lenguaje de los modulos del ASAP?

                                    Es posible cambiar el lenguaje de estos textos? Tengo Zoho configurado en español pero aun así me muestra estos textos en ingles:

                                  • Where do I edit the "Welcome to [portal name]" message

                                    I am looking for a way to edit the "Welcome to" part of the message that is seen on the landing page (ex: https://help.zoho.com/portal/en/home). When I use the French interface, it doesn't make sense... I want to change it from "Bienvenue chez" to" Bienvenue au". Thanks!

                                  • Zoho ERP | Product updates | July 2026

                                    Hello users, We're back with another round of updates to help you streamline your operations. This month's release brings new features and enhancements designed to help you work more efficiently. Read on to discover everything that's new in Zoho ERP this

                                  • Automate Backups

                                    This is a feature request. Consider adding an auto backup feature. Where when you turn it on, it will auto backup on the 15-day schedule. For additional consideration, allow for the export of module data via API calls. Thank you for your consideration.

                                  • Shared Snippets Everyone

                                    Hi, Now that the Shared Snippets have been released and I think will be the most used feature implemented in 2023 :) Creating and Using Snippets in Ticket Responses - Online Help | Zoho Desk Maintain consistency in ticket responses with shared snippets

                                  • Multi-currency and Products

                                    One of the main reasons I have gone down the Zoho route is because I need multi-currency support. However, I find that products can only be priced in the home currency, We sell to the US and UK. However, we maintain different price lists for each. There

                                  • Remove "Subject" as a required field on quotations

                                    Not sure why, but Zoho has made 'Subject' a system defined required field. I'm not entirely sure why subject would be required as a key field (i.e. you cannot deactivate it or change it from required). It doesn't make much sense on many product quotations,

                                  • Displaying only unread tickets in ticket view

                                    Hello, I was wondering if someone might be able to help me with this one. We use filters to display our ticket list, typically using a saved filter which displays the tickets which are overdue or due today. What I'd really like is another filter that

                                  • Best way to setup Inventory bin tracking for products with multiple boxes/crates

                                    Hi - we need some advice from the community on setting up Items in the Inventory for products with multiple crates. We have large products in our warehouse where the product is delivered as two large (double pallet) crates. We've setup the Items for these

                                  • Can't find field from ZCRM for a trigger

                                    Hello, Currently I am revamping our CRM system and we have created second layouts from to try out new processes while not disrupting the old one. Moreover, we want to use different layouts for different processes. The issue is that when creating the ZCRM

                                  • Discount Per Item / Option Removed

                                    Hi, I was using Zoho Books for three years now and very saticfied. Now, as we try to add an invoice, we founds that the discount option per item was takn away, and a discount from total was implemented. However, we have cases when we add a diffrent discount to each item. Was this option removed permanently? Thanks, 

                                  • Any Possible to change the challan type in Delivery challan ?

                                    Hello Team, We need to add the more values in challan type in delivery challan module in Zoho Books.So how to add additional values in challan type field. Please find following snap for your reference. Thanks in Advance, Thisai Moorthy.

                                  • Show when an invoice has been viewed

                                    It would be nice to know if/when a customer has viewed an invoice. This would mean not having PDF attachments and just have the link to the invoice. My previous invoicing solution had this feature and I did not realize how much I used it until it was gone. Would this be possible, or this already available and I am just missing it?

                                  • Zoho Books | Product updates | March 2026

                                    Hello users, We’ve rolled out new features and enhancements in Zoho Books. From Advanced Reporting Tags to the ability to mark projects as completed, explore the latest updates designed to improve your bookkeeping experience. Introducing Advanced Reporting

                                  • Separator line

                                    Is there a way i can insert a line in an invoice or quote without showing qty or prices? e.g. Options I Item description qty and price Option II Item description qty and price Thanks

                                  • All new Address Field in Zoho CRM: maintain structured and accurate address inputs

                                    Availability Update: 29 September 2025: It's currently available for all new sign-ups and for existing Zoho CRM orgs which are in the Professional edition exclusively for IN DC users. 2 March 2026: Available to users in all DCs except US and EU DC. 24

                                  • BCC Drop Box Centralisation

                                    Hi Team, For the last few years, I have had a question related to the Zoho CRM BCC Dropbox feature. Although BCC Dropbox is very useful for tracking customer email communication, I have always wondered why its configuration is managed at the individual

                                  • Kiosk Page Refresh

                                    We have a Kiosk running from a button in contacts to update values and also add related lists, which works great, but when the kiosk is finished the page does not refresh to show the changes. Is there a way to force the contact to refresh/update when

                                  • Next Page