Supplier integration guideHow levels work
Start here
Before you build
Specifications
After you submit
Concepts · All suppliers
How integration levels work.
A level describes the depth of data exchange between your systems and PromoTron. It is a scope boundary — not a ranking, and not a product tier.
Each level is a fixed bundle of feeds and assets plus the validation rules those feeds have to satisfy. Implementing a level means your systems produce that bundle on a schedule. Nothing about a level describes how you sell, where you sell, or at what margin.
There are five. Level 1 is what puts your catalogue on the network and is required. Levels 2 to 5 are optional and additive: each one enables a capability that would otherwise be unavailable, and each can be implemented on its own provided its dependencies are met.
- Document
- REF-LVL-001
- Revised
- 8 September 2026
- Applies to
- All suppliers
The five levels
The name of a level is the data it covers, never the product it happens to unlock. The products in the last column but one are what a distributor gains access to once your data reaches that depth.
| Level | What it covers | Unlocks | Depends on | Specification |
|---|---|---|---|---|
| L1 | Products, prices and stock — the catalogue itself | TronShop, TronManager | — | SPEC-L1-001 |
| L2 | Print options and print pricing — where, how and at what cost decoration can be applied | TronCalculator | L1 | SPEC-L2-002 |
| L3 | Imagery and print coordinates for virtual logo sampling | TronLogo | L1 + L2 | SPEC-L3-003 |
| L4 | Web2Print — validated, production-ready artwork out of customer input | TronDesigner | L1 + print data | SPEC-L4-004 |
| L5 | Order automation — orders reaching your ERP without anyone retyping them | Your own ERP | L1 | SPEC-L5-005 |
Additive, not sequential
Level 5 needs only Level 1, so a supplier with an ordering API can automate orders without ever implementing print pricing. Read the dependency column rather than the numbers.
Dependencies and additivity
Dependencies exist because later levels consume identifiers produced by earlier ones. Level 2 pricing rows join to Level 1 products by ModelCode; Level 3 coordinates join to Level 2 positions by PositionCode; Level 4 print areas reference both. If an upstream feed is missing the join key, the downstream level cannot be validated at all — it is not degraded, it is inert.
| What a distributor can do | L1 | L2 | L3 | L4 and L5 |
|---|---|---|---|---|
| See your products in their webshop | Yes | Yes | Yes | Yes |
| Quote from live stock and pricing | Yes | Yes | Yes | Yes |
| Calculate a printed price online | — | Yes | Yes | Yes |
| Show a customer their logo on the product | — | — | Yes | Yes |
| Send you production-ready artwork | — | — | — | L4 |
| Place an order into your ERP automatically | — | — | — | L5 |
Level 4 does not strictly require Level 3
Print and decoration data improves the result, but print areas can also be defined from dielines or configured by hand. The exact relationship for your catalogue is confirmed during onboarding — see §2.0 of the Level 4 specification.
Transport models compared
Every level below Level 5 is delivered as files, or as file-shaped HTTP responses. The transport you choose changes operational behaviour, not the schema: the same field tables apply either way.
| Method | Direction | Credentials | Available at | When it fits |
|---|---|---|---|---|
| HTTPS pull | We fetch | Yours, or an unauthenticated URL | L1–L4 | The default and the least work for you: expose one stable URL per feed and we schedule the retrieval. |
| SFTP push | You send | We issue them | L1–L4 | Where your export already runs on an internal scheduler you own and would rather keep owning. |
| API poll | We fetch | Yours — OAuth2 or bearer | L5 | Order flow only. |
| Webhook | You notify | A shared secret | L5 | Order flow only. |
Why event transports exist only at Level 5
Only order flow is event-shaped. Catalogue data is a snapshot by nature, so it is delivered as one and refreshed on a schedule rather than announced.
Refresh cadence and freshness
Two different clocks matter. Catalogue cadence is how often your product and pricing structure is re-read; stock cadence is how often quantities are. Stock is the one that causes visible failures, because distributor webshops show availability to end customers in real time.
| Membership tier | Catalogue data | Stock | What that asks of your export |
|---|---|---|---|
| Premium | Every 2 weeks | Every 4 hours | The stock export has to run unattended. |
| Gold | Weekly | Hourly | An hourly stock delta, or an endpoint we can poll. |
| Platinum | Within 24 hours | Every 5–10 minutes | Stock has to be queried live rather than exported. |
A nightly stock batch meets no tier
It is the single most common source of oversold orders: availability shown to an end customer can be up to a day stale. If your ERP cannot export more often, expose a stock-by-SKU endpoint we can poll for deltas instead of regenerating the whole file.
The tiers are the membership tiers
These are the refresh limits your membership sets, not a separate technical setting. What each tier costs and what else it decides is on the membership page.
The values are the maximum permitted age of the data at the moment a distributor queries it.
Why identifiers must stay stable
Two identifiers carry the entire join graph. ModelCode groups variants into a model; ProductCode identifies a single sellable variant. Every downstream artefact — print positions, logo coordinates, print areas, order lines — is keyed to one of them.
| Identifier | Identifies | Consumed by |
|---|---|---|
| ModelCode | A model — the group its variants belong to | Level 2 print options, and through them Levels 3 and 4 |
| ProductCode | One sellable variant, at SKU level | Prices, stock, Level 3 coordinates and Level 5 order lines |
An identifier is immutable for the life of the product
If a code changes value between submissions, we cannot tell 'this variant was renamed' from 'this variant was deleted and a new one appeared'. The observable result is that the old variant is withdrawn, the new one is created empty, and all print and coordinate data attached to it is orphaned. If a code must change, treat it as a deletion plus a creation and tell us in advance — and never reuse a retired code for a different item.
The normative rules for both, along with the three other codes a feed can carry, are in §4.0 of the transport and formats document.
What a level does not affect
A level decides which technical capabilities are enabled for your account, and nothing else. Everything in the table below is governed separately and is described nowhere in this documentation set.
| Question | Set by the integration level | Where it is decided instead |
|---|---|---|
| Which capabilities your data supports | Yes | This documentation set |
| What an integration or a membership costs | No | The membership page — one fee per level, plus the monthly membership |
| How often your data is refreshed | No | Your membership tier — see §4.0 above |
| Where your range is surfaced first | No | Promo Campaigns, which membership makes you eligible to buy |
| Commercial terms of any kind | No | Your agreement with us. Nothing in a feed affects them |
A commercial condition on a page here is an error
Report it to the integration team. Prices and terms live on the supplier pages so there is one copy of each, and a second copy here would go out of step the first time either changed.
Pick the levels before anything is built
Nothing above commits you to a level. The scope, and what it costs, are settled after a free analysis of the data you already keep — and the levels are priced one at a time, so you can start where it makes sense and build up.
