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 twin. The call does not return 409 while an unpublished overlay exists.

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.

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	Disk selector: image (photo or video) or file.

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 the sniffed kind of the bytes — image, video, or file — not 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"
}

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	Sniffed kind: image, video, or file.

Error Responses

Bad Request (400)

{
  "message": "Invalid product ID"
}

Product Not Found (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, or an unsupported image format also return 422.

Too Many Requests (429)

Returned when the store exceeds 60 uploads in 60 seconds. The Retry-After response header gives the number of seconds to wait.

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