Product Image Upload
Attach images to an existing product. Create products first using Product Import.
| Product thumbnail (packshot) | Product reference images | |
|---|---|---|
| Purpose | Main image in product lists and planogram renderings | Views for computer vision training |
| Endpoint | Product.ashx?action=save | ProductImage.ashx?action=save |
| Authentication | Basic authentication or session cookie | Basic authentication or session cookie |
| Format | PNG; content is validated | Use PNG or JPEG (.png, .jpg, .jpeg) |
| Stored dimensions | Fits within 200 × 500 pixels, preserving aspect ratio; smaller images are not enlarged | Original dimensions; no resizing or conversion |
| Repeat upload | Replaces the thumbnail for the same product | Creates another image record when id is omitted or 0 |
For one packshot per product, use the thumbnail endpoint. These endpoints save product images; they do not return image-recognition results or training status.
Authentication and access
Use your CoolR integration account with access to the Product module and the target product. For setup, see Authentication and Authorization. Basic authentication must be enabled for your deployment; it is configured for both Product.ashx and ProductImage.ashx.
The curl examples use Bash syntax and sample values. Replace the host with your assigned Portal URL, and use your own IDs, credentials, and files.
Find the ProductId
Use the product list endpoint to resolve a SKU or product name before uploading. This example URL-encodes an exact SKU search:
curl --get 'https://portal.coolrgroup.com/Controllers/Product.ashx' \
-u 'user@example.com:yourpassword' \
--data-urlencode 'action=list' \
--data-urlencode 'asArray=0' \
--data-urlencode 'quickSearch=COOLR-001' \
--data-urlencode 'fields=["SKU"]' \
--data-urlencode 'quickSearchOperator=Equals'
For a product name, use fields=["Product"] and replace quickSearch with the name. Without quickSearchOperator=Equals, the default is a prefix search. Plain SKU=... or Product=... parameters do not filter the product list.
Read ProductId from records when asArray=0. A shortened, illustrative response is:
{
"recordCount": 1,
"records": [
{ "ProductId": 10452, "Product": "CoolR Sample Product", "SKU": "COOLR-001", "ClientId": 42 }
]
}
SKU and product name are unique within a client, not across all clients an account may access. If your account spans clients, select the intended client using ClientId and verify the returned record before uploading. Treat an empty result as no accessible match; do not upload with a missing or zero product ID.
Several SKUs in one call
Use multiSearch with multiSearchFields=["SKU"] to match several SKUs exactly:
curl --get 'https://portal.coolrgroup.com/Controllers/Product.ashx' \
-u 'user@example.com:yourpassword' \
--data-urlencode 'action=list' \
--data-urlencode 'asArray=0' \
--data-urlencode 'multiSearch=COOLR-001,COOLR-002,COOLR-003' \
--data-urlencode 'multiSearchFields=["SKU"]' \
--data-urlencode 'start=0' \
--data-urlencode 'limit=100'
Results contain accessible matches, not placeholders for missing SKUs. Match records by SKU and client, rather than response order. Use start and limit for remaining pages when recordCount exceeds the number returned; see Paging. Split large requests into batches that fit your deployment's URL limits. Multi-search splits values on commas, line breaks, and tabs and trims whitespace; use a single exact search for identifiers containing those characters.
Product thumbnail (packshot)
POST https://portal.coolrgroup.com/Controllers/Product.ashx?action=save
Content-Type: multipart/form-data
| Form field | Type | Description |
|---|---|---|
id | number | Existing, nonzero CoolR ProductId |
file | file | One valid PNG image |
TagsValue | string | Complete comma-separated tag names to retain; omitted or empty clears existing tags |
action=save is already in the URL. Omit unrelated writable fields such as Name and SKU, which update the record rather than identify it. The thumbnail endpoint also supports ProductId or ExternalProductCode when id is omitted; this example uses id to target an existing product.
A thumbnail upload also saves product tags. Omitting TagsValue, or sending it empty, removes existing tags even when no other product fields are supplied.
For a tagged product, first load the same product with Product.ashx?action=load&id=10452 and read each tag's Name from moreInfo. Submit the complete current set as TagsValue, joined with commas. For example, use TagsValue=Seasonal,Featured only if those are exactly the tags to retain. This replaces the tag set; it is not an atomic preserve operation. For tag names containing commas or concurrent tag edits, obtain a supported workflow from CoolR before automating uploads.
The minimal example below applies only to a product verified to have no tags:
curl 'https://portal.coolrgroup.com/Controllers/Product.ashx?action=save' \
-u 'user@example.com:yourpassword' \
-F 'id=10452' \
-F 'file=@coolr-sample.png;type=image/png'
Renaming a JPEG to .png is insufficient; validation checks the file content.
Product thumbnails must have a transparent background. This image requirement is separate from the endpoint's PNG file validation; the endpoint does not check background transparency.
For display quality, use a front-facing, closely cropped image with enough resolution for the stored dimensions. Keep files small; deployment request limits and image validation can reject large uploads. Confirm the applicable size limit with CoolR for your environment.
Product reference images
POST https://portal.coolrgroup.com/Controllers/ProductImage.ashx?action=save
Content-Type: multipart/form-data
| Form field | Type | Description |
|---|---|---|
id | number | 0 to create a new image record; this is the image record ID, not ProductId |
ProductId | number | Existing, nonzero CoolR ProductId |
ImageCategoryId | number | Include a category from the table below to classify the image |
file | file | One PNG or JPEG image |
Send one file per request. With multiple files, only the first receives the submitted category; additional images are saved without it. The controller does not require a category, so omitting it can create an uncategorized record.
ImageCategoryId | Category |
|---|---|
6532 | Front Image |
6533 | Back Image |
6534 | L Side Image |
6535 | R Side Image |
6536 | Top Image |
6537 | Bottom Image |
curl 'https://portal.coolrgroup.com/Controllers/ProductImage.ashx?action=save' \
-u 'user@example.com:yourpassword' \
-F 'id=0' \
-F 'ProductId=10452' \
-F 'ImageCategoryId=6532' \
-F 'file=@coolr-sample-front.jpg;type=image/jpeg'
PNG/JPEG extension checks belong to the Portal uploader; this API controller does not perform the thumbnail endpoint's content validation. Upload valid images with clear product views and a plain or transparent background. Confirm your deployment's file-size limit with CoolR.
Responses and retries
Both save endpoints return success and the saved record in data. These shortened responses are illustrative, based on the source contract; the examples have not been verified against a server.
Thumbnail:
{
"success": true,
"data": { "Id": 10452, "Name": "CoolR Sample Product", "SKU": "COOLR-001", "ProductThumbnail": "10452.png" }
}
Reference image:
{
"success": true,
"data": { "Id": 1542, "ProductId": 10452, "Filename": "coolr-sample-front.jpg", "ImageCategoryId": 6532 }
}
A thumbnail that fails PNG pre-validation returns:
{
"success": false,
"data": null,
"info": "The selected file is not a valid PNG image. Please upload a valid PNG file."
}
Check the HTTP response and parse the body before reading success. Save errors can appear in info, but authentication or request-size failures may return a non-JSON response. Correct validation and access problems before retrying.
Uploads are handled during the request. The thumbnail controller saves the product record before its final image processing and storage, so success=true alone does not guarantee the thumbnail was stored correctly. Check the displayed image after uploading. Neither response confirms that recognition training or downstream updates have completed.
After a timeout or uncertain result, inspect the product's images before retrying. A new reference-image request creates another record and can duplicate an earlier upload. Repeating a thumbnail upload targets the same thumbnail, but also updates product image metadata; it is not a side-effect-free retry.
For support, contact support@coolrgroup.com.