In the documentation for items, it indicates that a master_image array can be passed along with the public url.
In my request payload I have:
{ ...
"master_image": { "url":"https://planx.com/toystore/img/store/figurine/medium/acorn/f_l_acorns_woak.jpg",
"id": "f_l_acorns_woak.jpg"},
... }
but the item response shows:
{ ...
'images': [],
... }
All the other documentation I found indicates that one has to upload the image. These doesn't seem reasonable when I am already providing public access to (potentially hundreds of) the images.
What am I doing wrong? (and can the documentation be corrected)
The documentation is correct I believe, you need to upload the image to Square using the image upload endpoint. That will change what appears in the master_image section of the items response, but you can't change that directly with a PUT on the item.
Square needs to have the image itself to create thumbnails and deliver the image to the Square register app. By storing the image for you, Square can ensure that it's always available in the various places where it's needed.