Supplier integration guideChecklist
Start here
Before you build
Specifications
After you submit
Submission checklist
What to have ready before you submit.
One checklist per level, the six patterns that account for most rejections, and what happens after you send a sample.
Run the checklist for every level you are implementing before you send anything. These describe what to assemble; the field-level contract is in the per-level specification and takes precedence wherever the two appear to differ.
- Document
- PREP-SUB-020
- Revised
- 8 September 2026
- Report retained
- 7 days
Level 1 — products, prices and stock
Required- A product catalogue export, one row per sellable variant
- A unique, immutable ProductCode per variant
- A unique ModelCode grouping those variants
- At least one image per model1000 px or more on the longest side.
- A net price list with quantity breaks, in a single currency
- Stock quantities, or an endpoint we can poll
- Your chosen delivery method and a stable URL or directory
- A named technical contact for data questions
All three feeds, in any format
Product data, prices and stock each go as CSV, XML or JSON, over HTTPS pull or SFTP push. Stock may additionally be a pollable endpoint, which is what a tier above Premium usually needs.
Level 2 — print options and print pricing
Requires Level 1- Your current print price list as its source spreadsheetNot only a PDF — see the note below.
- Print positions per product family, each with a stable code
- Your technique list mapped to the six accepted values
- Setup fees, handling fees and minimum quantities
- A quantity-break table per technique and colour count
- The maximum printable area per position, in cm²
Send the source, not the export
A PDF price list can be parsed, but conditional rules written as prose are lost in the process. The spreadsheet your team maintains internally — however messy it looks to you — keeps the logic. Structure beats presentation here.
Level 3 — logo visualisation
Requires Levels 1 and 2- Product images of 1200 px or more, front and back as needed
- Clean backgroundsNo logos, watermarks or overlays already on the picture.
- One product in one colour per image
- An overlay rectangle per position, normalised 0–1
- The physical width in centimetres for each rectangleThis is what sets the preview scale, and it is the field with the most expensive failure mode.
- Public or long-lived signed URLs for every asset
- One canonical template image per model wherever the views match
- A sample set: one variant, one position, one image
Level 4 — Web2Print and production artwork
Requires Level 1 + print data- Every Level 3 asset requirement satisfied
- Your chosen deployment modelStandalone, embedded or ERP-driven — §2.0 of the Level 4 specification.
- Vector dielines or PDF templates where you have them
- Your production colour system, if it is Pantone-managed
- An output specification — bleed, resolution, delivery format
- A documented file-naming convention for image references
Level 4 is a partial specification
Its field names and numeric thresholds are provisional and are confirmed against your own catalogue. Confirm them before you build an exporter against them.
Level 5 — order automation
Requires Level 1- An ordering API over HTTPS, TLS 1.2 or higher
- OAuth2 — client credentials or authorisation code
- JSON payloads, UTF-8, ISO 8601 timestamps with an offset
- Idempotency-Key honoured on every POST
- Webhooks for order.created, order.updated and order.shipped
- Declared rate limits, and Retry-After respected on your side
- A sandbox with the same API surface as production
The endpoint specification is issued to you
It is written against your catalogue rather than published. Ask the integration team for it once the seven items above are answered.
The six patterns that account for most rejections
Each is checked automatically and named explicitly in the validation report, so none of them is a surprise you find out about later.
| Level | What was sent | What it causes, and the correction |
|---|---|---|
| L1 | Variant data flattened to model level | Every size and colour shares one row, so no orderable variant exists. Correct it with one row per variant — ModelCode plus the variant attributes in separate fields. |
| L1 | Stock delivered as a nightly batch | Availability shown to end customers can be up to a day stale, which produces orders against quantities you have already sold. Correct it with hourly deltas, or a pollable stock-by-SKU endpoint. |
| L2 | Pricing rules expressed as prose | A condition like "−12% above 500 units" cannot be evaluated and is discarded. Correct it with one column per variable — quantity, technique, colour count, surcharge. |
| L3 | Coordinates pinned to the wrong image | Rectangles normalised against a per-variant photo land on collars and seams when that photo differs. Correct it by pinning the geometry to one canonical template image per model. |
| All | Inconsistent attribute values | "Cotton 100%", "100% cotton" and "cotton" are three distinct values, which breaks faceted filtering. Correct it by submitting as-is — normalising against our taxonomy is a managed operation and not your work. |
| L5 | A non-idempotent order endpoint | Network retries create duplicate ERP orders. Correct it by honouring Idempotency-Key and returning the original order on a repeated key. |
The fifth one is not a mistake to fix before you send
Pre-cleaning attribute values usually costs you effort and loses information, because the mapper works better when it can see your original alongside the target. What the pipeline does with your data after ingest is a page of its own.
Submitting
A sample first, always. Twenty variants exercising every field you intend to populate is enough to validate the structure, and it settles the exporter contract in one round instead of three.
| Step | What to do | Why it is in this order |
|---|---|---|
| 01 | Send a sample, not the catalogue | Twenty variants covering every field you intend to populate. It can arrive by email even if production will not. |
| 02 | State the production transport | Name the format and the delivery method you will use in production, so the sample is validated against the contract it will actually run under. |
| 03 | Read the validation report | It names the row, the field, the failing rule and the correction for every rejection. Reports are retained for seven days. |
| 04 | Resubmit, then wire up the export | A passing sample means the exporter contract is settled. Scheduling the export before that is what turns one correction into a catalogue of them. |
You do not have to clean it first
Translation, taxonomy mapping, regional pricing and asset preparation all happen after your data arrives. Send it in the shape you already keep it in — the pipeline maps an inconsistent source better than a hand-cleaned export.
