Challenges in Updating CatalogObjects of Type ITEM with UpsertCatalogObject API

Questions
1

I was reading through this thread: visit.developer.squareup.com/forums/t/cannot-upsert-update-catalogobjects-of-type-item/20517, and it made me curious about a related issue I’ve been facing.

When trying to update a CatalogObject of type ITEM, I keep running into the NOT_FOUND error, even though the RetrieveCatalogObject endpoint successfully returns the correct object with all its details. I’ve tried using the same ID, passing the version retrieved from the object, and even incrementing it slightly as suggested elsewhere, but the update still fails.

Here’s the tricky part, I’m wondering if there’s something about how linked CatalogObjects (like variations or modifiers) are handled during an update that could cause this error. Is it necessary to include linked objects in the request, even when they’re not being updated Or is there a specific condition that prevents certain ITEM types from being updated through the UpsertCatalogObject API??

Any detailed insights or advanced troubleshooting steps would be great! Here’s my current request body for context:

{
    idempotency_key: crypto.randomUUID(),
    object: {
      id: "EXAMPLE_ITEM_ID",
      type: "ITEM",
      item_data: {
        name: "Updated Item Name",
      },
    },
  };
2

:wave: I’m Square Dev AI, here to help answer your question!
Based on the information you’ve provided, the following documentation will help answer your question:

Additional Documentation

Retrieve Catalog Objects
Design a Catalog
Search for Items and Objects

If this documentation helped you find a solution, please check the box indicating that this reply solves the problem.
Otherwise one of our Developer Advocates will provide additional assistance shortly.

3

When updating a CatalogObject of type ITEM, you don’t need to include linked objects like variations or modifiers in the request if they’re not being updated. The UpsertCatalogObject endpoint should update the specified fields of the object without affecting its linked objects.

The NOT_FOUND error typically indicates that the API couldn’t find an object with the provided ID. If you’re sure the ID is correct, one possible issue could be a mismatch between the object ID and the type specified in the request. In your request body, you’re specifying the type as “ITEM”. Make sure the ID you’re using is indeed the ID of an ITEM object, not an ITEM_VARIATION or other type of object.

Also, ensure that the ID you’re using is the correct ID for the object in the current state of your catalog. If the object was deleted or replaced, its ID may have changed or may no longer exist.

Lastly, the version number is not required when updating an object. However, if you do include it, make sure it’s the current version number of the object. Incrementing the version number arbitrarily could lead to a version mismatch error.

This answer was reviewed by @Bryan-Square.