Development
  • Guides
  • API Reference
  • API Explorer
  • SDKs
  • Sample apps
  • System status
Support
  • Developer forums
  • Developer blog
  • YouTube
  • X
More
  • Square Home
  • Square Developer
  • App Marketplace
  • Partner with Square
  • Solutions Partner Program
  • Pricing
  • Sales

© 2026 Square, Inc.

  • Developer terms of service
  • Developer Integration and Marketing Agreement
  • Privacy policy
  • Partnerships
  • Sign In
  • Sign In

    Catalog

  • Batch delete catalog objects

  • Batch retrieve catalog objects

  • Batch upsert catalog objects

  • Create catalog image

  • Update catalog image

  • Catalog info

  • List catalog

  • Upsert catalog object

  • Delete catalog object

  • Retrieve catalog object

  • Search catalog objects

  • Search catalog items

  • Update item modifier lists

  • Update item taxes

  • Webhooks

  • catalog.version.updated

<- Catalog API

Catalog API

All versions ->

Update catalog imageBeta

PUT

 /v2/catalog/images/{image_id}

Uploads a new image file to replace the existing one in the specified CatalogImage object.

This UpdateCatalogImage endpoint accepts HTTP multipart/form-data requests with a JSON part and an image file part in JPEG, PJPEG, PNG, or GIF format. The maximum file size is 15MB.

Permissions:ITEMS_WRITE
Try in API Explorer
Link to section

Path parameters

Example code

Link to section

image_id

string

Required

The ID of the CatalogImage object to update the encapsulated image file.

Link to section

Request body

Link to section

idempotency_key

string

Required

A unique string that identifies this UpdateCatalogImage request. Keys can be any valid string but must be unique for every UpdateCatalogImage request.

See Idempotency keys for more information.

Min Length
1
Max Length
128
Link to section

Response fields

Link to section

errors

Any errors that occurred during the request.

Link to section

image

The newly updated CatalogImage including a Square-generated URL for the encapsulated image file.

Link to section

Examples

All versions ->

PUT /v2/catalog/images/{image_id}
curl https://connect.squareup.com/v2/catalog/images/L52QOQN2SW3M5QTF9JOCQKNB \ -X PUT \ -H 'Square-Version: 2026-11-18' \ -H 'Authorization: Bearer ACCESS_TOKEN' \ -H 'Accept: application/json' \ -F 'file=@/local/path/to/file.jpg' \ -F 'request={ "idempotency_key": "528dea59-7bfb-43c1-bd48-4a6bba7dd61f86", "object_id": "ND6EA5AAJEO5WL3JNNIAQA32", "image": { "type": "IMAGE", "image_data": { "name": "Coffee", "caption": "A picture of a cup of coffee" } } }'

Response JSON

{ "image": { "id": "L52QOQN2SW3M5QTF9JOCQKNB", "type": "IMAGE", "image_data": { "name": "Coffee", "url": "https://...", "caption": "A picture of a cup of coffee" } } }