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

                                  • OpenAI Is Moving to the Responses API: Here's What It Means for SalesIQ

                                    OpenAI has deprecated its Assistants API and is moving to the Responses API. If you're using OpenAI Assistants with SalesIQ, you may be wondering if you need to make any changes to your existing setup. You don't. SalesIQ has already taken care of the

                                  • Need Native Support for docx files in Zoho Writer

                                    Absolutely love Zoho Writer, but often need to share files by email with people who are in the Office ecosystem. Downloading a file as docx, then sending it by email, getting the comments back, converting it to Zoho format, editing it, then converting

                                  • CRM integration issues

                                    hi Just start testing Campaigns. Read up on up on these issues but can not find an answer. I am super admin. 1) its only showing 1002 contacts, I have a 2500 plan which is confirmed in dashboard. I says it sync'd 1400. I've looked at missing contacts,

                                  • What's New in Zoho Expense: Integrated Business Travel and AI-Powered Expense Management

                                    This release brings a wide range of updates across Zoho Expense, including new AI-powered capabilities, enhancements to corporate cards, expense management, audits, and more. Keep reading to know how the new updates can transform your travel and expense

                                  • ChatGPT Plugin / MCP Server auth error

                                    Hi all I'm trying to connect the ChatGPT plugin for Zoho CRM but after username stage of the auth process, I get this error from the URL https://mcp.zoho.eu/mcp-client/ {"error_description":"Invalid request url, Request is not as per defined in oauth

                                  • Project Management Platforms for AI Agents: What Matters Most?

                                    Zoho Projects is already going beyond basic AI assistance with MCP, AI Bridge, and integrations that let AI models access project data and perform actions. That raises an interesting question: what should a project management platform for AI agents actually

                                  • Sync workdrive feature inside ZohoCRM

                                    Hi, I'm exploring the new workdrive/ZohoCRM connector released by Zoho to replace the free extension workdriveforCRM which is decomissioned https://marketplace.zoho.com/app/crm/zoho-workdrive-for-zoho-crm I'm rather upset with this long awaited feature,

                                  • Adding Custom Status Options in Work Order Action Menu

                                    Hello FSM Team, We would like to inquire if it is possible to add more custom options in the Work Order action/status dropdown (e.g., Cancel, Terminate, Non-Billable, Void, etc.). Currently, the available options are limited, and we are unable to customize

                                  • MTA - BAD IP reputation by outlook/hotmail

                                    Messages to Microsoft email servers are bouncing back due to poor reputation. Message: 4.7.650 The mail server [136.143.188.206] has been temporarily rate limited due to IP reputation. For e-mail delivery information see https://postmaster.live.com (S775)

                                  • Timesheet Task Icons

                                    In the image below which shows the task field drop down when creating a timesheet against a project and task. What do the icons mean the the right side column against each task? I can't find any documentation or guide that explains what the no entry sign,

                                  • Open Records in a New Browser Tab

                                    Hi FSM Team, Just a suggestion: It would be helpful to have a right-click → Open in New Tab option in FSM, similar to CRM. This should ideally work for any clickable record or module, allowing users to open multiple records in separate tabs without losing

                                  • Facturation électronique 2026 - obligation dès le 1er septembre 2026

                                    Bonjour, Je me permets de réagir à divers posts publiés ici et là concernant le projet de E-Invoicing, dans le cadre de la facturation électronique prévue très prochainement. Dans le cadre du passage à la facturation électronique pour les entreprises,

                                  • Marketing Tip #18: Make your online store mobile-friendly to improve traffic

                                    Most online shoppers browse on their phones first. If your store is hard to read, slow to load, or tricky to navigate on mobile, they’ll bounce fast. A mobile-friendly store doesn’t just look nice; it improves engagement, reduces drop-offs, and helps

                                  • Cannot add note to record on mobile

                                    In the latest version of the mobile app - if a record already has notes associated with it - you can add a note via the mobile app - if a record does not have previous notes there is no way to add a new one - it allows me only to send email

                                  • Dashboards for Customers

                                    Is it possible to build dashboards for each customers in the community for their tickets?

                                  • Custom color coding for your entities

                                    Our brains are fine tuned to recognize colors before any text or shapes, making color coding a powerful tool to organize data and find items quickly. Color coding of our day-to-day work help with quickly processing the information, reducing cognitive

                                  • The Social Wall: August 2026

                                    Hello everyone. Welcome to the August 2026 edition of The Social Wall. This month, we're bringing you updates that make it easier to reach your audience, manage more channels, and streamline your publishing workflow. Here’s what’s new. WhatsApp bulk messaging

                                  • Check out in Meetings

                                    Why there is no check out in Meetings of Zoho CRM, very difficult to track

                                  • How do I get to "Admin Panel"

                                    I just started a Cliq account. I am the sole administrator. As I read the documentation, I keep seeing reference to an "Admin Panel". I see no way to access this from my Cliq account. How do I access this panel?

                                  • 【初開催！ オンライン】Zoho Campaigns メール配信の基礎・活用勉強会を開催します！ 10/15 参加無料

                                    ユーザーの皆さま、こんにちは。 Zoho コミュニティグループの中野です。 Zoho ユーザーコミュニティ初となる、メールマーケティングをテーマにしたオンライン勉強会を開催します！ ▶︎イベント詳細・参加登録はこちら 今回取り上げるサービスは「Zoho Campaigns」です。 「Zoho CRMとZoho Campaignsのどちらからメールを配信すればよいか分からない」 「一斉配信はできるようになったけれど、現在のリスト管理や設定が正しいか不安」 「メールを送るだけで終わり、配信後の改善につなげられていない」

                                  • Marketing Tip #46: Run flash sales the right way

                                    A flash sale can do a lot for your store. It can clear slow-moving inventory, spike revenue on a slow day, or reward your most loyal customers. But if done carelessly, flash sales can backfire. Customers start expecting discounts, stop buying at full

                                  • Introducing Smart Fields in Zoho Forms

                                    Hello form builders! We are excited to introduce Smart Fields in Zoho Forms - a faster way to add calculations to your forms without writing formulas. Instead of creating multiple fields and configuring complex calculations yourself, you can now drag

                                  • Checkbox not displaying correctly in subform

                                    Greetings: I have shared my app (wv) with support.  I am having problems with a checkbox field not displaying correctly in a subform.  The main form is called volunteers and the subform is called volunteers_subform.  The field in question is called roles. When you access the subform by itself the checkbox lookup displays as checkboxes.  But when you view it in the main volunteers form, it displays as a multi-select dropdown instead.   I have attached jpegs showing the difference.   Any thoughts?

                                  • Unbundle feature for composite items

                                    We receive composite items from our vendors and sell them either individually or create other composite items out of them. So, there is a lot of bundling and unbundling involved with our composite items. Previously, this feature was supported in form

                                  • Valid characters for use in email addresses using Zoho's apps/APIs

                                    We have found an issue with the + sign character in zoho subs - we are allowed to create a customer with an email address that has a plus sign but the API doesn't allow the + so the billing portal is not created. We are going to prevent users from using

                                  • Expand Zoho Analytics Spatial Capabitlities

                                    Dear Analytics team Thanks for the great product - I'm a big fan on Analytics and the monthly release highlights is one of my favourite emails to receive. I'd like to request expansion and improvement of Zoho Analytics spatial data capabilities, namely:

                                  • Automate customer follow-ups with Sequences in Bigin

                                    Greetings, We hope you're all doing well! We're happy to announce a new feature that we've added to Bigin. Following up with every lead at the right time can be challenging, especially when your team is managing multiple conversations across emails, calls,

                                  • 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

                                  • Can we have an automated TDS Receivable Recon with Form 26AS of Income Tax Portal ?

                                    Can we have an automated TDS Receivable Recon with Form 26AS of Income Tax Portal ?

                                  • Customers would like to add tips when paying in Client Portal

                                    I am happy with the clean interface of the Client Portal. However, I am running into a challenge: my customers would like to be able to add tips/gratuities when making payments. Currently, this is very clunky because they have to 1) manually over-pay,

                                  • Tag Limi?

                                    is there any way to create more than 20 tags? 

                                  • prefill_data for Creator + Merge & Sign

                                    Hello, Is there an option to use prefill_data for signer fields from creator? I see the option for CRM but it will not work with creator? I have tried passing the value in the signer data, and that also does not work. Alternatively, is there a way to

                                  • Can I Build a Gaming Website Using Zoho? Need a Quick Roadmap

                                    Hi Dear Members, I want to create a gaming website using Zoho. Is it possible? My goal is to build a sleek, unique, easy-to-navigate, and fast-loading website for a gaming project. I want the site to look professional, user-friendly, and optimized for

                                  • Remove Due Date from Statements

                                    Is it possible to remove the Due Date on the Invoice transation line on statements? I have figured work arounds to get the Invoice detail on the Statement but cannot work out haw to simplify the stament by removing the "- due on xx/xx/2026" - it really

                                  • What Should an Agent-Native Project Workspace Look Like

                                    AI is moving beyond assistants that simply answer questions. With tools like MCP, agents can now interact directly with project data and perform actions. That makes me wonder: what should an agent-native project workspace actually look like? For me, it

                                  • unable to join meeting due to speaker issue

                                    unable to join meeting due to speaker issue

                                  • How to add formatting in zoho.cliq.postToUser(...) message?

                                    In a CRM Deluge function, I'm trying to use the message formatting guidelines given here: https://www.zoho.com/deluge/help/cliq/posting-to-zoho-cliq.html#message-formats My message is: message: #Title text. The result in Cliq is: #Title text. (no large

                                  • Marketing Tip #50: Sell digital products and use them to grow your store

                                    Physical products need packaging, shipping, and stock management. Digital products need none of that. Once created, they can be sold an unlimited number of times, delivered instantly, and never go out of stock. What counts as a digital product? A digital

                                  • Can I import customer data from Zoho Invoice to Zoho CRM?

                                    I have been using zoho invoice for a couple of years and have built up my client list here. I am now giving Zoho CRM a shot and am hoping I can get a lot of my already established data (financial trading records) over to zoho crm?  Can anyone tell me if this is possible and how can I do it? 

                                  • Turn off Mobile Optimize

                                    Hello is it possible to stop the automatic mobile optimization of my site as it looks much better on a mobile in full site format rather than mobile format. Thanks

                                  • Next Page