Supplier integration guideSupplier portal
Start here
Before you build
Specifications
After you submit
Supplier portal
The technical documentation behind a PromoTron integration.
What your systems have to produce, in what shape, and how often — for every one of the five integration levels.
You are most likely reading this because our team sent you the link after a first conversation. That conversation covered what an integration makes possible; this set covers the other half of it — the feeds, the fields, the formats and the checks your data has to pass.
It is written for whoever will build the export: your data team, your IT department, or the partner who maintains your ERP. Nothing here is a commercial condition, and no page in this set states one.
- Integration levels
- 1 – 5
- Feed formats
- CSV · XML · JSON
- Encoding
- UTF-8
- Last revised
- 8 September 2026
First time through
Five steps, in this order.
Level 1 is the foundation and nothing above it can be validated until it passes, so the order below is not a suggestion — it is also the order the rail on the left is in. If you already know which level you are implementing, go straight to its specification in the table underneath.
You
Read how levels work
What a level is, what depends on what, and which transport applies. Ten minutes, once.
You
Learn the shared rules
Encoding, delivery, identifiers and what a validation outcome means. They are the same at every level, so a mistake here is a mistake in all your feeds at once.
You
Check what you have to assemble
The per-level checklist, run before you write a line of the exporter. It is what stops a submission being rejected for something structural.
You
Build against the specification
Level 1 first — three feeds, product data, prices and stock availability, joined on identifiers that never change.
Together
Send a sample for validation
Twenty variants exercising every field you intend to populate. You get back a report naming the row, the field and the correction for anything that fails.
Every document in this set
Where a field definition appears in more than one place, the per-level specification is the normative one and every other page is a summary of it.
| Document | ID | Level | What it covers | Status |
|---|---|---|---|---|
| How integration levels work | REF-LVL-001 | All | What a level is, what depends on what, transport models, refresh cadence and why identifiers must stay stable | Active |
| Transport, formats and identifiers | REF-FMT-010 | All | Accepted encodings, delivery methods, identifier and standards rules, validation outcome classes | Active |
| Submission checklist | PREP-SUB-020 | All | What to assemble per level before you submit, the known failure modes, and how a submission is validated | Active |
| Level 1 — products, prices and stock | SPEC-L1-001 | L1 | Three mandatory feeds, their field tables, validation rules and a minimal record | Active |
| Level 2 — print options and print pricing | SPEC-L2-002 | L2 | Print options and print pricing feeds, quantity breaks, and what makes a pricing rule computable | Active |
| Level 3 — logo visualisation | SPEC-L3-003 | L3 | Image asset constraints, normalised overlay rectangles and physical size references | Active |
| Level 4 — Web2Print and production artwork | SPEC-L4-004 | L4 | Deployment models, product data categories, print-area definitions, output and validation states | Partial |
| Level 5 — order automation | SPEC-L5-005 | L5 | What the order API asks of your system: authentication, transport, payloads, events and idempotency | On request |
| Data operations | PREP-OPS-021 | All | What happens to your data after it is ingested — mapping, translation, regional pricing and asset preparation | Active |
Level 4 is marked partial
Its integration model is confirmed and its field-level naming is not. Every provisional clause inside that document is flagged, and a provisional name is not a feed contract — confirm your catalogue's before you build against it.
Level 5 is issued per supplier
The page in this set states what the order API asks of your system so you can judge the work. The endpoint specification itself is not published; the integration team issues it against your catalogue.
How to read these pages
The same five conventions apply on every page of this set.
| Convention | What it means |
|---|---|
| Clause numbers | Every clause of a specification carries a number — §1.0, §2.0 — and it does not change between revisions. Quote it in an email or a ticket and we will be reading the same paragraph. This index is not a specification, so it is not numbered. |
| A level in the 'required at' column | The lowest level at which a field becomes required. A field marked L2 is optional at Level 1 and required from Level 2 upward. |
| An em dash in that column | Optional at every level. It may still be checked for format if you supply it. |
| Monospace blue | A literal — a field name, an enum value or an error code — that appears in a feed exactly as written here. |
| A clause marked draft | Provisional. Names, types and numeric thresholds may still change, and only Level 4 currently carries any. |
Every page states its document ID and the date it was last revised at the top. A page in this set that does not is not a specification.
Not in this set
What a level costs, and what it makes possible.
This set describes what your systems have to produce. It deliberately says nothing about what an integration costs, what a membership includes or what any of it changes commercially — those are on the supplier pages, said once so they cannot go out of step with each other.
What each level makes possible
The same five levels stated as what a distributor can do with your range once you reach them — sell it, price a print on it, show a customer their logo on it.
What an integration costs
Each level is a one-time fee and the membership is the monthly part. The figures, the tiers and what each tier decides are on the membership page.
What happens before any of it
A free analysis of the data you already keep, then a scope and a price you approve before anything is built. Nothing in this set is committed to by reading it.
Send a sample before you build the whole exporter
Twenty variants exercising every field you intend to populate is enough to settle the contract. You get back a report naming the row, the field and the correction for anything that fails — and a passing sample means the exporter is right before you schedule it.
