Wix Velo Upsert Guide: Prevent Duplicates & Fix Form Submissions

For e-commerce store owners leveraging custom forms on their Wix sites, efficient and accurate data management is paramount. Whether you're tracking customer preferences, managing event registrations, or handling product declarations, the ability to seamlessly update existing records or insert new ones—a process often called an "upsert"—is a core requirement. However, implementing this logic correctly can be tricky, often leading to frustrating issues like duplicate entries, data inconsistencies, or unexpected errors.

This article dives into common challenges faced when developing custom upsert functionality in Wix Velo and provides a robust, data-driven approach to ensure your forms operate flawlessly.

The Upsert Challenge: Diagnosing Common Pitfalls

A frequent scenario involves a form designed to check if a record (e.g., a horse declaration for an organization) already exists based on identifiers like first and last name. If found, the record should be updated; if not, a new record should be created. The challenge arises when the conditional logic to handle these two scenarios doesn't behave as expected, leading to:

Duplicate Entries: An existing record is updated, but a new, identical record is also created, cluttering your database.
Undefined ID Errors: When no existing record is found, the system attempts to access an ID that doesn't exist, causing console errors and preventing new data insertion.
Misbehaving Conditional Logic: The if/else statement designed to differentiate between update and insert operations seems to fail, leading to incorrect actions.

Unpacking the Root Causes: Why Upserts Go Wrong

These issues typically stem from a few key areas in the Velo code implementation:

1. Premature Data Object Construction

One common mistake is constructing the toUpdate data object before confirming if an existing record was actually found. Consider this problematic snippet:

const entrytoUpdate = await wixData.query("yourCollection").eq("field1", value1).find();
let toUpdate = {
  "_id": entrytoUpdate.items[0]._id, // ERROR if entrytoUpdate.items is empty!
  "field1": value1,
  // ... other fields
};
if (entrytoUpdate.items.length > 0) { /* ... update logic ... */ }
else { /* ... insert logic ... */ }

If the query entrytoUpdate.find() returns an empty array (meaning no matching record was found), then entrytoUpdate.items[0] will be undefined. Attempting to access ._id on an undefined object will throw an error, halting execution before the if/else block can even properly evaluate. The _id is crucial for update operations, as it tells Wix Data which specific record to modify.

2. Dual Submission Pathways: Dataset vs. Custom Code

The "duplicate entries" problem often arises when a submit button is configured to perform both a default dataset submission *and* trigger custom Velo code that also handles data saving (wixData.insert or wixData.update). If your form elements are connected to a dataset, and the submit button's default action is to "Submit" the dataset, clicking it will initiate a save operation via the dataset. If your onClick handler on that same button also contains explicit wixData.insert or wixData.update calls, you're essentially performing two save operations for one click.

For custom upsert logic, it's critical to decide on a single data submission pathway. If you're managing the insert/update logic entirely through Velo code, the submit button should *not* be connected to a dataset's default submit action. Instead, its primary role is to trigger your custom onClick handler.

Building Robust Upsert Logic: A Best Practice Approach

To implement a reliable upsert mechanism, follow these principles:

Decouple Form Submission: If using custom wixData operations, ensure your submit button is not linked to any dataset submission action. Your Velo onClick handler will be the sole trigger for data saving.
Query First, Then Conditionally Act: Always perform your database query to check for an existing record *before* attempting to construct data objects for update or insert.
Construct Data Objects Conditionally: Create the toUpdate object (which requires the _id) only if a record is found. Similarly, create the toInsert object only if no record is found.
Implement Clear Success and Error Handling: Provide user feedback and log errors effectively using .then() and .catch() blocks.

Step-by-Step Implementation Guide

Here’s how to structure your Velo code for a robust upsert operation:

Step 1: Set Up Your Form and Database

Ensure your form inputs are correctly named (e.g., #fname, #lname, #horse1) and your database collection (e.g., "2026declaredhorses") has matching field keys (e.g., "fname", "lname", "declaredhorse1").

Step 2: Prepare Your Submit Button's onClick Handler

Your primary logic will reside within the submit button's onClick event. Remember to disconnect it from any default dataset submission.

Step 3: Query for Existing Records

Before doing anything else, query your database to see if a record matching your criteria (e.g., first name and last name) already exists.

import wixData from 'wix-data';

$w.onReady(function () {
  // ... other onReady setup like hiding elements, captcha handlers ...

  $w('#submit').onClick(async () => {
    let fnameinput = $w('#fname').value;
    let lnameinput = $w('#lname').value;

    const queryResult = await wixData.query("2026declaredhorses")
      .eq("fname", fnameinput)
      .eq("lname", lnameinput)
      .find();

    // ... rest of the logic will go here
  });
});

Step 4: Collect All Form Data Dynamically

For forms with many similar inputs (like multiple horse names), collect them efficiently. This also makes your code cleaner and easier to maintain.

    let horseData = {};
    for (let i = 1; i <= 20; i++) {
      // Only include fields that have a value to avoid saving empty strings for unused inputs
      // Or, validate that only expanded fields are considered
      if ($w(`#horse${i}`).value) {
        horseData[`declaredhorse${i}`] = $w(`#horse${i}`).value;
      }
    }
    let memberID = "Need Membership Database ID"; // Ensure this is dynamically fetched or derived

Step 5: Implement Conditional Update or Insert Logic

Now, use the queryResult to decide whether to update or insert, constructing the appropriate data object within each branch.

    if (queryResult.items.length > 0) {
      // Record found: prepare to update
      let existingItem = queryResult.items[0];
      let toUpdate = {
        "_id": existingItem._id, // Essential for update
        "memberid": existingItem.memberid || memberID, // Preserve existing member ID or assign new
        "fname": fnameinput,
        "lname": lnameinput,
        ...horseData // Spread operator to include all collected horse data
      };

      wixData.update("2026declaredhorses", toUpdate)
        .then(() => {
          console.log("Data successfully updated.");
          $w('#horsepayment').show(); // Show payment section on success
          // Optional: Display success message to user
        })
        .catch((err) => {
          console.error("Error updating data:", err);
          // Optional: Display error message to user
        });
    } else {
      // No record found: prepare to insert
      let toInsert = {
        "fname": fnameinput,
        "lname": lnameinput,
        "memberid": memberID, // Assign new member ID
        ...horseData
      };

      wixData.insert("2026declaredhorses", toInsert)
        .then(() => {
          console.log("Data successfully inserted.");
          $w('#horsepayment').show(); // Show payment section on success
          // Optional: Display success message to user
        })
        .catch((err) => {
          console.error("Error inserting data:", err);
          // Optional: Display error message to user
        });
    }
  }); // End of onClick handler
}); // End of onReady handler

This refined structure ensures that the _id is only accessed when an existing record is confirmed, and that only one data saving operation (insert or update) is performed per submission. It also provides a clear framework for error handling and user feedback.

Beyond the Code: User Experience and Data Validation

While robust backend logic is crucial, remember the user-facing aspects. Provide clear feedback upon submission—whether it's a success message, a redirection, or the display of a payment section. Implement client-side validation to catch common input errors before submission, further enhancing the user experience and data quality. For fields like memberID, ensure they are either automatically fetched, securely generated, or clearly provided through the form, rather than being a static placeholder.

By adopting these best practices for upsert operations in Wix Velo, e-commerce store owners can build more reliable, user-friendly custom forms that accurately manage their valuable data, avoiding common pitfalls and ensuring a smooth operational workflow.

Streamlining Data Management: Mastering Upsert Operations in Wix Velo Forms