Update or Upsert Records Using Unique Custom Fields

Update or Upsert Records Using Unique Custom Fields

Hello customers,

We've enhanced the process of updating records via API. You can now:
  • Update records using unique custom fields
  • Upsert records using unique custom fields
Note: Both the features are available in the Zoho Books and Zoho Inventory apps.

Update Records Using Unique Custom Fields

Until now, records were updated using their unique ID. For example, when updating an invoice, the number displayed in the URL after invoices/ (/invoices/xxxx...) is the invoice's unique ID. When a PUT call is made, the record will be updated if the unique ID exists. If it does not exist, an error will be thrown.

You can now update records using unique custom fields if the Prevent Duplicate Values option is enabled for those custom fields. When a PUT call is made, the record will be updated if the unique custom field exists. If it does not exist, an error will be thrown.

For example, when integrating Zoho Books with a third-party application where a record, such as an item, has different unique IDs in both applications, you can create a custom field in Zoho Books to store the third-party application's unique ID. By enabling the Prevent Duplicate Values option for a custom field in the Items module, you can update records in the Items module using either the item's unique ID or the unique custom field.

How do I update records using unique custom field?  

To update a record using a unique custom field:
  • Pass the custom field's API name in the header X-Unique-Identifier-Key.
  • Pass the value of the third-party record's entity ID stored in the unique custom field in the header X-Unique-Identifier-Value.

Upsert Records Using Unique Custom Fields

What is Upsert?

Upsert is the combination of the terms Update and Insert. It refers to an API operation that allows you to either update an existing record or insert a new record if it does not already exist. This operation is particularly useful in scenarios where you want to ensure that a record is present in the database without having to first check if it exists.

How does Upsert work?

This is how Upsert works:
  • If the record exists, the Upsert method will update the existing record.  
  • If the record does not exist, the Upsert method will create a new record.

How do I Upsert records?

To upsert records:
  • Pass the custom field's API name in the header X-Unique-Identifier-Key.
  • Pass the value of the third-party record's entity ID stored in the unique custom field in the header X-Unique-Identifier-Value.
  • Pass the header X-Upsert with value set to true to make the API an Upsert API.
In the JSON string parameter, include the respective record's update payload.

To learn more, read our API help document on updating an item using a custom field's unique value.

If you've any queries regarding updating and upserting records, please contact support@zohobooks.com or support@zohoinventory.com, and we'll be happy to help you. 

Cheers,
The Zoho Finance Team


    • Recent Topics

    • Automate Credit Card Surcharge

      Is there a way to create an automation that will add a 3.0% credit card surcharge to a subscription whenever a customer pays via credit card?

    • How to charge Convenience fee OR payment gateway charges to the end client who is paying the invoice?

      Hello, I am creating this topic after having discussions with various sets of users and have understood that with people moving more and more to digital payments, it is important for the client to enable the "Convenience fee" kind of scenario. I have

    • How to add a fee based on payment method

      I currently accept both ACH payments and credit card. I want to add a 3% fee to a number of my subscription plans if the customer chooses to use a credit card (and not ACH/checking). How do I do this? Is there an in-built feature, or would i have to create

    • Zoho Inventory - Profit Margin Feature - Allow Users to Set Default Cost Price Calculation Method

      Hi Zoho Inventory Team, I'm working with an automotive parts distributor using Zoho Inventory. They have expressed frustration about having to change the Cost Price Method on every line item they add from the defult "Inventory Valuation Method" to "Item

    • 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

    • Deprecation Notice: OpenAI Assistants API will be shut down on August 26, 2026

      I recieved this email from openAI what does it means for us that are using the integration and what should we do? Earlier this year, we shared our plan to deprecate the Assistants API once the Responses API reached feature parity. With the launch of Conversations,

    • Payment for product renewal

      Good morning, I am requesting your kind assistance to renew my subscription because when I try to make the payment I get this way

    • 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

    • API - Available Stock Definitions

      Okay, Zoho team... your copywriters fell down on the job for this one :) I think these warrant a bit more explanation as to what they include and what they don't.

    • Feature Request: Add Sort by Cell Color and Text Color functionality

      Hello Zoho Sheet Development Team, I am writing to suggest a feature enhancement for Zoho Sheet. Currently, the platform supports "Filter by Color," which is incredibly useful. However, there is no native option to "Sort by Color" (by cell fill or text

    • Calendar Year View?

      Is there a way I can view the calendar in year view? Maybe create a page with a view like this?

    • Razorpay + Zoho Billing + Zoho Books Integration

      Please help us set up this integration.

    • Proyecto SII

      Buenas tardes amigos de zoho. en mi empresa vamos a implementar el proyecto de emisión de facturas SII pero para poder hacerlo hay que subir un xml, estoy intentando automatizar este proceso pero no se como convertir la factura que retorna books a xml

    • Automate Workflows at the Subform Level

      Hello, Enterprise Support Community! We are excited to introduce an enhancement to Workflow Rules that gives you more control over automation within your records. Previously, Workflow Rules could only be configured at the module level, which meant changes

    • Custom module - change from autonumber to name

      I fear I know the answer to this already, but thought I'd ask the question. I created a custom module and instead of having a name as being the primary field, I changed it to an auto-number. I didn't realise that all searches would only show this reference.

    • What is wrong with this sendmail message?

      I keep getting improper statement errors on the message, but I cannot see a problem. Also, if the message is much longer the whole message turns black instead of being coloured yellow, red and blue. client = Clients[ID == input.Client_Lookup]; sendmail

    • sales IQ issue on website

      i integrated the zoho sales IQ code on the website but it is comming in distroted form i am sharing the screenshot below the website is bulit in wix platform

    • Zoho Creator - Install app from Gallery takes too long

      I'm trying to install the 'Volunteer Portal' from the app Gallery of Zoho Creator. It has been busy installing the app for over 2 hours now. It might be okay, but how long is something like that supposed to take? I never installed anything from that Gallery

    • 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,

    • How can I load a network into the cliq desktop app?

      I have both the standard cliq log in for my org and I am part of a cliq network. In the browser I can choose which I log in to. However, in teh desktop app if I log in it will alwasy load my org's cliq. Can I switch this to the network I have create

    • 4.7.500 Server busy. Please try again later from [136.143.188.52]. (S77719) [SJ1PEPF00001CE2.namprd05.prod.outlook.com 2026-09-04T11:42:24.261Z 08DF0918255760D6]

      4.7.500 Server busy. Please try again later from [136.143.188.52]. (S77719) [SJ1PEPF00001CE2.namprd05.prod.outlook.com 2026-09-04T11:42:24.261Z 08DF0918255760D6]

    • Set Up Google Tag Manager for Your Zoho Recruit Career Site

      Understanding how candidates interact with your career site can help you improve their experience and make better decisions about your recruitment process. With the new Google Tag Manager (GTM) integration in Zoho Recruit, you can connect your career

    • Gmail users think they've replied to invite when they havent.

      Hi, I think there's an issue when inviting gmail users to a zoho calendar event. Basically, when an invite from zoho calendar is received by a gmail user, gmail has this functionality where it will render "yes/no/maybe" buttons that, when clicked, they

    • Translated country names in Address field not sorted alphabetically

      Hello. I have a form with an address field that includes the country dropdown. The primary form language is English (as is the Zoho Forms account language). The form has been translated into German from the form's Settings > Translation functionality.

    • Zoho Commerce Microstore to bypass customer portal on spesific items

      Hi everyone, I’m currently testing the Microstore feature in Zoho Commerce and trying to understand how it behaves with access restrictions. My goal is the following: Even though the customer portal is enabled (and the main store requires users to sign

    • Calendar Attachments in iOS Mail App

      It appears that viewing or accessing attachments to a calendar event is not possible in the iOS mail app. Is this correct? The ability to view calendar attachments in the mobile app is vital for me. Is this just a setting I'm missing somewhere?

    • Grey border on inserted Sheet on Write document

      When inserting a Sheet on a Write document, it show an ugly gray border. How to get rid of it?

    • Send workflow alerts as a single mass email to all recipients

      Managing workflow notifications becomes easier when everyone needs visibility into who received an alert. With this enhancement, workflow email alerts can now be sent as a single email to all recipients, giving recipients visibility into the other users

    • Kaizen #253 : Custom Validation for Blueprint to Enforce Mandatory File Uploads and File Extension Compliance Using Client Script

      Welcome to another exciting Kaizen post on Client Script! Have you ever wanted more control over what gets uploaded to a File or Image field in Zoho CRM, like restricting file types, validating file names, or showing a custom error before an inappropriate

    • WORK DRIVE CUSTOMIZATION

      WORK DRIVE CUSTOMIZATION Create folder for every Case by “Contact Name “in Work Drive under Associate Deals Folder Directory: User Work Drive Accounts: Route Directory Associate Cases Case Name, Case Number Client Upload- Shared with contact (for collaboration)

    • How do I migrate from Office 365 to Zoho Mail?

      Check out Advik Email Migration Wizard, this software is specially developed to move mailboxes from Office 365 to Zoho Webmail. In addition you can migrate from Gmail, Yahoo, Rediffmail and 80+ webmail servers to ZOHO MAIL. Isn't it amazing? This is an all in one email migration solution. Steps to export emails from Office 365 to Zoho Webmail are as follows; Run Advik Email Migration Tool in your system. Select Office 365 as source and enter its login credentials. Select mailbox folders and choose

    • 【続々公開】Zoholics Japan 2026 セッション情報を更新しました！

      ユーザーの皆さま、こんにちは！ Zoholics Japan 2026のセッション情報を続々と公開しています！ 今年は3つのトラックで、Zohoの最新情報やAI活用、製品アップデート、 活用事例など、多彩なセッションをお届けします。 現在公開中のセッション（一部） ・Zoho CRM 製品アップデート ・Zoho CRM Plus 製品アップデート ・Zoho Community セッション ・Zoho Desk セッション ・中堅・成長企業の人事DX ～AI時代に何から始めるべきか？～ ・Zoho

    • Zoho Forms integration Google Sheets

      Hi, quick one. I wonder if you can help. I have a Zoho Form integrated to a Google Sheet. The fields are showing across the top, but no records are there. I have checked in Zoho Forms to see if there have been any failed integrations, but there are none.

    • What's New in Zoho POS - August 2026

      Hello everyone, Welcome to Zoho POS’s monthly update, where we share our latest feature updates, enhancements, events, and more. This month, we’re taking a closer look at our new Loyalty Program functionality and exploring how it can help your business.

    • Zoho ERP | Product updates | June 2026

      Hello users, We launched Zoho ERP on January 23, and since then, our goal has been to help businesses streamline and manage their operations with greater efficiency, flexibility, and control. Since the launch, we've continued to enhance the platform every

    • 3 numbers after comma in discount field

      Hi, i need to make discount like: ex. 34,345% it's possible? Thank you.

    • ZOHO Campaigns in ZOHO Analytics - Campaigns vs Contacts Table

      There seems to be information in the Zoho Campaigns table such as Unique Opens and Unique Clicks that can't be found in the Campaigns vs Contacts table where only Opens and Clicks are shown on a per contact level. Is there a way to bring Unique Opens

    • Canva Integration

      Hello! As many marketing departments are streamlining their teams, many have begun utilizing Canva for all design mockups and approvals prior to its integration into Marketing automation software. While Zoho Social has this integration already accomplished,

    • Default Country list suggestions on CRM is different then on Book; how do/did others address this?

      So I already have a support ticket in for this and waiting for a response but figured I'd ask the community also to see if others experienced the same problems and/or how they went about addressing it because sometimes I feel like I'm going crazy with

    • Vehicle Tracking

      we have GPS devices that installed on our vehicles, and we would like to know if it's possible to  get vehicle live location data from the GPS device To Zoho Creator App.   Thank You

    • Next Page