Supplier integration guideLevel 3
Start here
Before you build
Specifications
After you submit
Level 3 · Optional
Level 3 — logo visualisation.
You supply the images and the per-position overlay geometry. The rendering engine is ours.
Level 3 puts a distributor's customer logo onto your product imagery, so a buyer sees the branded product before they order rather than after. It unlocks TronLogo.
Geometry is expressed in normalised image space plus one physical size reference, which is what lets a preview scale correctly at any render size. The rectangle is normalised against the target image and not against the product, so re-cropping an image invalidates its rectangle.
- Document
- SPEC-L3-003
- Revised
- 8 September 2026
- Depends on
- Levels 1 and 2
What has to be true first
Requires Levels 1 and 2Level 2 — print options and print pricing
- Level 1 is activeCoordinates join to variants by ProductCode.
- Your Level 2 print positions existEvery PositionCode used here must be declared in the print options feed — §2.0 of the Level 2 specification.
- MaxAreaCm2 is set on the positions you will useWhere it is present, overlay rectangles are validated against it. Where it is not, that check is skipped.
Image assets
| Asset | Constraint | Required at | Notes |
|---|---|---|---|
| Base product image | 1200 px or more on the longest side | L3 | JPG or PNG on a white or transparent background. No watermarks, no existing logos, no overlays. |
| Front view | As the base image | L3 | Required wherever the item has front and back positions. |
| Back view | As the base image | Conditional | Required for any BACK position. |
| Alternate colour views | One per variant | Conditional | Required where the product colour changes how a logo renders on it. |
What resolution actually buys
Measured on the shorter side. The middle row is the one to build a catalogue on.
| Reference | Shorter side | Result |
|---|---|---|
| Minimum | 600 px | Accepted. Preview quality degrades at large render sizes. |
| Optimal | 1000 px | The recommended baseline for a whole catalogue. |
| Best | 1400 px and above | Full-quality previews at every render size. |
Overlay coordinates
One row per image, per position. The rectangle is normalised against the target image rather than against the product, so a re-crop of that image invalidates the rectangle.
| Field | Type | Required at | Constraint |
|---|---|---|---|
| ProductCode | string | L3 | Must resolve against Level 1. |
| PositionCode | string | L3 | Must resolve against the Level 2 print options. |
| ImageURL | url | L3 | The exact image the rectangle applies to. Public, or a signed URL — never behind an authentication wall. |
| RectX / RectY | decimal 0–1 | L3 | The top-left corner as a fraction of image width and height. |
| RectW / RectH | decimal 0–1 | L3 | Width and height as a fraction of image width and height. RectX plus RectW must not exceed 1. |
| RectRotation | decimal degrees | — | Clockwise, about the centre of the rectangle. Defaults to 0. |
| RealWidthCm | decimal | L3 | The physical width of the rectangle on the product, in centimetres. It sets the preview scale. |
RealWidthCm drives the scale, not the pixels
A logo preview is sized from this value and not from the pixel rectangle. An incorrect RealWidthCm produces a preview that is geometrically valid and visually wrong — a logo that looks twice its actual print size — so nothing is rejected and nobody notices until a customer does. It is the single highest-impact field in this specification.
Validation rules
| Rule | Code | Outcome |
|---|---|---|
| A rectangle value outside 0 to 1 | E-210 | Row rejected. |
| The rectangle extends past the image bounds | E-211 | Row rejected. RectX plus RectW, or RectY plus RectH, exceeded 1. |
| ImageURL is behind authentication | E-403 | Row rejected. A signed URL is accepted if it is valid for at least 30 days. |
| The PositionCode is unknown at Level 2 | E-303 | Row rejected. |
| The implied area exceeds MaxAreaCm2 | W-322 | Row accepted and flagged for review. It indicates a mismatch between your Level 2 and Level 3 data. |
| RealWidthCm is zero, negative or absent | E-122 | Row rejected — the preview scale cannot be derived. |
| Coordinates pinned to a per-variant image | W-323 | Accepted and flagged. Pin geometry to one canonical image per model wherever the views are identical. |
One position on one image
{
"ProductCode": "POLO-CLASSIC-BLK-M",
"PositionCode": "CHEST_L",
"ImageURL": "https://cdn.example.com/polo-classic-blk-front.jpg",
"RectX": 0.36, "RectY": 0.22,
"RectW": 0.12, "RectH": 0.10,
"RectRotation": 0,
"RealWidthCm": 8.0
}Start with one variant, one position, one image
A single coordinate row against a single photograph is enough to confirm that your geometry and ours agree. Getting that one right before you generate the rest is the difference between one correction and a catalogue of them.
