Square Annoyingly Wipes Item Descriptions on New Batch Upsert's of Existing Products – Confirmed Bug + Workaround

Questions
1

I’ve spent hours trying to figure this out thinking it was my code and pulling my hair out. It wasn’t.

If you use batch-upsert with a catalog item that already exists and has a description, Square will wipe the description unless you send back a new and different one.

Even if you send the exact same description value as before, Square still deletes it. With no response, or anything else.

This is silent, undocumented, and 100% reproducible.

Tested Scenarios:

  • Existing item with description → send same description again → wiped

  • Existing item with description → send no description → wiped

  • Add new variation without updating description → wiped

  • Send different description → replaces it

  • Trick it with minor change (e.g. appending a dash) → preserved

Workaround:

  1. Always send item_data.description with every upsert.

  2. If the description hasn’t changed, append a character (I use a dash -) to bypass Square’s weird logic.

Posting this so the someone else doesn’t waste hours trying to figure this out.

2

:waving_hand: 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

Define Item Variations Using Options
Synchronize a Catalog with an External Platform
Add a Catalog Item

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.