Supplier integration guideLevel 5
Start here
Before you build
Specifications
After you submit
Level 5 · Optional · On request
Level 5 — order automation.
Orders reach your ERP without anyone retyping them, and their status travels back the same way.
Level 5 needs only Level 1, so it can be implemented on its own without ever touching print pricing or artwork. It pays off for suppliers who already have an ordering API, higher order volumes, and real order-administration costs to remove.
The endpoint specification is issued per supplier rather than published, because it is written against your catalogue. This page is what it asks of your side, so your IT team can size the work before that specification exists.
- Document
- SPEC-L5-005
- Revised
- 8 September 2026
- Depends on
- Level 1
What the order API asks of your system
Seven requirements. If your ordering API already meets them, the integration is a mapping exercise rather than a build.
| Item | Requirement |
|---|---|
| Authentication | OAuth2 — client credentials or authorisation code. |
| Transport | HTTPS, TLS 1.2 or higher. |
| Payload | JSON, UTF-8, ISO 8601 timestamps with an offset. |
| Events | Webhooks for order.created, order.updated and order.shipped. |
| Idempotency | Idempotency-Key honoured on every POST. A repeated key returns the original resource rather than creating a second one. |
| Rate limits | Declared on your side. We honour Retry-After. |
| Sandbox | Required, with the same API surface as production. |
A non-idempotent order endpoint duplicates orders
A network retry that reaches your system twice creates two ERP orders, and nothing in the exchange reveals it until somebody in production notices. Honouring Idempotency-Key and returning the original order on a repeated key is what prevents it, and it is the requirement most often found missing during a first review.
Respond fast and process asynchronously
A webhook must respond 2xx within 500 ms and queue its work. A synchronous write into an ERP causes retry cascades — see §2.0 of the transport and formats document.
What an order looks like
The shape of an order as it reaches you. The path, the field names and the event contract in your own specification are written against your catalogue and may differ.
POST /v1/orders
Authorization: Bearer …
Idempotency-Key: 2b4c-4f…
{
"order_id": "PT-2026-00042",
"distributor_id": "DST-204",
"lines": [
{ "ProductCode": "POLO-CLASSIC-BLK-M", "qty": 50 }
],
"print_jobs": [
{ "PositionCode": "CHEST_L", "TechniqueCode": "SCREEN", "Colors": 2 }
]
}An order carries print jobs only where the supplier is at Level 2 or above. At Level 1 alone, the lines arrive without decoration.
Ask for the specification when you are ready
It is written against your catalogue and issued to your technical contact. Bring what your ordering API already does — the answer to whether this is a build or a mapping exercise is usually in the seven rows above.
