Upload Product Media

Host a file and return a URL. This does not change the product gallery, cover, or logos. It is not the downloadable files array on the product — those still use url on create / update. See Downloadable files. There is no /draft version of this endpoint, and it does not return 409 while has_draft is true.

Send the returned file_url on Update Product Media to add it to the gallery, or on Update Product Settings as logo_url / logo_square_url.

Limited to 60 uploads per 60 seconds per store, shared with completing an upload and with Upload Storefront Media.

Request

POST /products/{id}/media

Path Parameters

Parameter	Type	Required	Description
id	string	Yes	Product UUID

Request Body

multipart/form-data.

Parameter	Type	Required	Description
file	file	Yes	Bytes to host. The original filename is returned as name.
type	string	Yes	image for a photo or video — the bytes must be a supported image or video format. file for anything else.

Example Request

curl -X POST "https://cart.easy.tools/api/v1/products/0632bef5-c308-42cd-9cba-89a7a4f722bb/media" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -F "type=image" \
  -F "file=@gallery.png"

Response

Success Response (201)

The gallery is unchanged. type is detected from the file contents — image, video, or file — and can differ from the request type. A hosted still image is returned as WebP; file_url is the stored copy.

Only image and video uploads can go into the gallery: Update Product Media accepts those two type values and returns 422 for anything else. A file result is still usable as a logo URL on Update Product Settings.

{
  "name": "gallery.png",
  "file_url": "https://cdn.example.com/products/7f3a1c2e-9b4d-4e8a-a1c6-2d5e8f0b3a19.webp",
  "type": "image"
}

Response Fields

Field	Type	Nullable	Description
name	string	No	Original filename.
file_url	string	No	Stored location. Send this as file_url on gallery items or as a logo URL.
type	string	No	Kind detected from the file contents: image, video, or file.

Error Responses

Bad Request (400)

{
  "message": "Invalid product ID"
}

Not Found Error (404)

{
  "message": "Product with ID 0632bef5-c308-42cd-9cba-89a7a4f722bb not found"
}

Validation Error (422 Unprocessable Entity)

{
  "message": "The given data was invalid.",
  "errors": {
    "type": [
      "The selected type is invalid."
    ]
  }
}

Missing file, an empty filename, a file over the store upload limit, or an unsupported image format (including HEIC, HEIF, and AVIF — convert to JPG or PNG first) also return 422.

Rate Limit Error (429 Too Many Requests)

Returned when the store exceeds 60 uploads in 60 seconds, counting completed uploads and storefront uploads too. The Retry-After response header gives the number of seconds to wait.

{
  "message": "Too many requests. Please retry after 60 seconds."
}