Product Images — Upload

Uploads a new image for the given product.

Image upload is REST-only. A binary file part cannot be carried in a JSON GraphQL request, so the createAdminCatalogProductImage mutation exists as a placeholder and rejects any call. Reordering and deleting images, which carry no binary payload, do work over GraphQL.

Endpoint

Endpoint	Method
/api/admin/catalog/products/{productId}/images	POST

Content type

multipart/form-data — required.

Form fields

Field	Type	Required	Notes
image	file	yes	One of bmp, jpeg, jpg, png, webp.
position	integer	no	Sort position; appended to the end if omitted.
alt_text	string	no	Description of the image, stored for every locale the request covers. Editable afterwards through update.

Response

201 Created

Field	Type	Notes
id	integer	New product_images.id.
productId	integer	Parent product ID (echoed).
path	string	Storage-relative file path.
position	integer	Sort position.
url	string	Public URL.
altText	string	Alt text stored for the current locale, or null.

Errors

HTTP	Cause
401 Unauthorized	Missing or invalid admin Bearer token.
403 Forbidden	Admin role lacks catalog.products.edit.
404 Not Found	Product not found.
422 Unprocessable Entity	Missing file, invalid mime, or oversized payload.