Third-Party Camera/ Image Integration
This guide is for partners and customers integrating their own camera images — from own integrated cameras or mobile app etc. — into the CoolR platform. Once accepted, third-party images are processed identically to VistaZ images: full planogram compliance, OOS/facing analytics, StoreBuddy tasks, dashboards, and exports.
Overview
Images are submitted to a single upload endpoint alongside identifiers that let CoolR resolve which outlet and asset (cooler, freezer, or other cabinet) the image belongs to. From there, the image enters the same processing pipeline as any CoolR-captured image.
StoreAware refers to fixed camera image sources. StoreBuddy refers to mobile/phone camera image sources. These terms describe the type of capture, not who owns the hardware — see ImageReceivedFrom below.
Prerequisites
Before any image upload can resolve successfully:
- The outlet must already exist in the platform. See Outlet Import.
- The cabinet/asset must already exist and be linked to that outlet. See Asset Import.
Uploads for an outlet or asset that hasn't been provisioned yet will be rejected — there is no implicit creation of outlets or assets from an image upload.
Device identity mapping
An image upload must resolve to a specific asset. Several identifiers can be used, and integrators should choose whichever is reliably available on their side:
- Serial Number (recommended) — the cooler/asset serial, when known directly.
- Store/Outlet Number — outlet context, best used when a single cooler is mapped to that store.
- IMEI — the identity of the uploading device, for integrations where the device ID is known but the asset serial is not.
If you use IMEI-based mapping, the IMEI must first be associated with the corresponding asset record in the platform. This association can be set up either through manual entry in the platform or via the standard import/API mechanisms — talk to your CoolR contact to determine which is appropriate for your rollout.
Image quality recommendations
- 5MP minimum resolution is recommended for reliable planogram and OOS/facing analysis.
- Before rolling out a third-party camera at scale, qualify each cabinet model with that camera — image angle, lighting, and framing can vary enough between cabinet models to affect processing accuracy, and qualification catches mismatches early.
- Qualification isn't a one-time gate: CoolR provides ongoing feedback on processing quality after go-live, not just during initial qualification, so issues surfaced in production can still be addressed.
Subscription and volume limits
The number of images processed is limited by the customer's subscription. Images submitted beyond the subscription allowance are automatically rejected.
Because the constraint is on volume rather than timing, there is no fixed capture-cadence requirement — integrators aren't required to send images on a specific schedule, only within their allotted volume.
Authentication and scope
Authentication uses the same mechanism as any CoolR integration: a per-integrator token, not a per-device or per-outlet credential. The authentication context determines the client scope and what assets can be accessed.
Cabinet-level restrictions are enforced on the backend rather than by the token itself. For example, in a shared tenant, an OEM's token can be scoped so it can only push images for that OEM's own cabinets — this restriction is applied server-side, not encoded in the token.
Endpoint reference
POST {base_url}/Controllers/CoolRAPI.ashx?action=uploadImage
Content-Type: multipart/form-data
{base_url} varies by environment (dev/test/prod) — use the base URL provided for your target environment.
Sample URL:
POST {base_url}/Controllers/CoolRAPI.ashx?StoreNumber=1&SceneType=ProductAnalysis&action=uploadImage&IsStitchImage=False&SerialNumber=Dev-Temp-order_1&ImageReceivedFrom=2&IMEI=8473294723949
All parameters are sent as form fields along with uploaded file(s). The request must be multipart/form-data with at least one image file, and at least one of SerialNumber, StoreNumber, or IMEI must be provided to resolve the target asset/location.
Request parameters
| Parameter | Required | Type | Default | Description |
|---|---|---|---|---|
action | Yes | string | — | Must be uploadImage |
SerialNumber | Conditional* | string | — | Cooler/asset serial number |
StoreNumber | Conditional* | string | — | Outlet/store code (location code) |
IMEI | Conditional* | string | — | Device IMEI used for asset resolution in supported flows |
SceneType | No | string | ProductAnalysis | Scene category of the image |
ImageReceivedFrom | No | number | 1 | Source system identifier |
IsStitchImage | No | bool | true | Whether uploaded files should be stitched |
GridOrder | No | string | — | Comma-separated placement order for grid stitching |
BeforeAfterImage | No | number | 0 | Flags lifecycle context (before/after event) |
VerifyFileSize | No | bool | false | Marks zero-byte saved uploads as unsuccessful in response |
* At least one of SerialNumber, StoreNumber, or IMEI should be provided. If both SerialNumber and StoreNumber are sent, serial-based matching is preferred and store may be used for consistency checks.
Parameter details
SceneType
Common values:
ProductAnalysis(default)POSAssetBarcodeAssetViewStoreViewPromotion
ImageReceivedFrom
Identifies the type of camera source the image came from — not the ownership of the hardware.
1= StoreAware — fixed camera source2= StoreBuddy — mobile/phone camera source
This applies regardless of whether the camera or app is CoolR-provided or a third-party integration: a fixed third-party camera should still send 1, and a third-party mobile app should still send 2. This field is used for source tracking and source-specific processing behavior.
IsStitchImage
IsStitchImage=true: multiple uploaded files can be combined as a stitched image.IsStitchImage=false: no stitching occurs; each uploaded file is processed as a separate image.
GridOrder
Controls multi-file grid layout during stitching.
Example:
GridOrder=2,1,3
The number of positions should match the number of uploaded files.
BeforeAfterImage
Captures contextual stage of the image in operational workflows.
0= Not specified1= Before event such as - before merchandising2= After event such as - after merchandising
VerifyFileSize
If enabled, uploads saved as zero-byte files are returned with unsuccessful status (Success: false) and informational message.
Upload examples
Standard single upload
POST /Controllers/CoolRAPI.ashx?action=uploadImage
SerialNumber=XYZ789
SceneType=ProductAnalysis
ImageReceivedFrom=1
[file: shelf.jpg]
Multi-image stitched upload
POST /Controllers/CoolRAPI.ashx?action=uploadImage
SerialNumber=XYZ789
IsStitchImage=true
[file: left_panel.jpg]
[file: right_panel.jpg]
Grid-ordered stitched upload
POST /Controllers/CoolRAPI.ashx?action=uploadImage
SerialNumber=XYZ789
GridOrder=2,1,3
[file: center.jpg]
[file: left.jpg]
[file: right.jpg]
Upload by outlet code
POST /Controllers/CoolRAPI.ashx?action=uploadImage
StoreNumber=STORE-042
[file: shelf.jpg]
Upload by IMEI
POST /Controllers/CoolRAPI.ashx?action=uploadImage
IMEI=352099001761481
[file: shelf.jpg]
Response
The API returns a JSON array with one object per accepted upload result.
Success Response
[
{
"Success": true,
"Info": "Image uploaded successfully",
"UniqueGuid": "a3f1c29d-...",
"AssetPurityId": 84521
}
]
Error Response
[
{
"Success": false,
"Info": "Asset not found: ASSET-123"
}
]
| Field | Type | Description |
|---|---|---|
Success | bool | Whether upload was accepted successfully |
Info | string | Success or error message |
UniqueGuid | string | Unique image identifier (only present when Success: true) |
AssetPurityId | number | Internal image record identifier (only present when Success: true) |
Common errors
| Message | Meaning |
|---|---|
Action not found | Invalid or missing action parameter |
Invalid request. Client not specified | Authentication context is missing client scope |
No image files found to upload | Request has no file payload |
StoreNumber or Asset Serial# is required | Missing required asset/location identifier |
Asset not found: ... | Provided identifier(s) do not map to a known asset |
Outlet not Found OR is Linked with Asset... | Asset-location mapping is invalid or missing |
Asset assigned to outlet code X, passed code Y - mismatch | Serial and store code do not match expected mapping |
Files did not match with the grid order | GridOrder count differs from uploaded file count |
...Inactive | Target asset is inactive/disabled |
Image saved with 0 bytes | Zero-byte image persisted (with file-size verification enabled) |
Something went wrong | Unexpected server-side issue during upload |
Something went wrong while saving image | Unexpected error during image save operation |
Submission outcomes: after upload, images may be accepted as pending, auto-provisioned, or rejected depending on scene, planogram availability, and operational checks.
What stays the same
Once a third-party image is accepted, it is indistinguishable from a VistaZ-sourced image in downstream platform behavior: full planogram compliance checks, OOS/facing analytics, StoreBuddy task generation, dashboards, and exports all apply identically. There is no feature gap for third-party-sourced images.