True Catalog Upsert

I’m trying to build a Catalog synchronization feature, and it occurs to me that the Catalog Upsert API call is a misnomer because you are required to use different IDs to distinguish between a create operation and an update operation.

This is problematic. We can use the temporary ID format to create an object and save the system generated ID for later. Meanwhile, the user deletes the object from the Square Catalog. We go to update the object using the system ID and this fails. By the way, it’s really annoying that the object not found error is returned as a generic 400 Bad Request error, rather than a more specific 404 Not Found error.

In order to solve this error, we need to catch the error, update the ID that we use to the temporary form and then retry the request. This is not really how an upsert operation is meant to work.

I believe that the API would be a whole lot easier to use if you allowed the use of user-assigned handles in the ID field. These symbolic IDs could be used to access the catalog objects without needing to know the underlying system ID. For example, we could create an item with an ID of “#Item_1234” and then use the same ID to update, retrieve or delete the item. If this could be done, then you would actually have a true upsert capability because the same ID could be used to create and update an item. If the item doesn’t exist, then it automatically creates it.

Unfortunately, using the ID that was used the the create request to update the catalog object isn’t available.

Is the synchronization feature your building listening for updates via webhooks to get the latest version of an object? You can then be notified of any deleted objects on the client side so you won’t get the 4xx errors.

If you’re not using webhooks to keep the objects in sync we recommend bringing in the latest version of an object prior to updated it so you avoid these concurrency errors. This is when two or more applications at the same or different time access the same objects, they can interfere with each other in unexpected ways. For more here is our documentation on Optimistic concurrency. :slightly_smiling_face:

We have a complex environment and we’re looking to be driving the data that gets put into the catalog.

We don’t anticipate supporting catalog updates from anywhere other than our system. That’s why I’m coming from the “I don’t care about the version field” point of view.

Offering two-way synchronization is possible, but something for the future at the moment.

We’re constantly working to improve our features based on feedback like this, so I’ll be sure to share your request to the API product team. :slightly_smiling_face: