V1 vs V2

If you're moving from V1 to V2, this page is a quick orientation.

V2 is a fresh design rather than a like-for-like upgrade, so the smoothest path is usually to write a new integration against V2 alongside your existing V1 code, then switch over once you're happy. The sections below walk through the conceptual differences and give you an endpoint mapping so you can find the V2 equivalent of what you use in V1.

Authentication

In V1 you sent two headers, X-IPP-PARTNERCODE and X-IPP-APIKEY. In V2 you send a single header:

X-Printeers-Secret-Key: <your_secret>

Your V1 partner code and API key won't work against V2. You'll generate a V2 secret key in the dashboard before your first call. See the Getting Started guide for the steps.

Base URL

Field naming

V1 fields are snake_case (partner_reference, image_reference, shipping_kind). V2 fields are lowerCamelCase (customIdentifier, imageReference, shippingKind). When you port a request or response, you'll be renaming most field keys.

Response shape

V1 puts resource data at the top level of the response body. V2 wraps single-resource responses under a named field, and list responses under a field named for the resource:

// V1
{ "reference": "TESTCODE-123", "status": "..." }

// V2 (single)
{ "order": { "reference": "Order_...", "status": { ... } } }

// V2 (list)
{ "orders": [ ... ], "nextCursor": "..." }

See the Pagination guide for cursor-based list responses.

References

In V1 you identified resources with composite codes: store codes (TESTCODE), order references (TESTCODE-123), SKUs (PART0037). In V2 each resource has a typed, opaque reference of the shape <Resource>_<26 opaque characters>:

Your old codes still appear on V2 resources as legacyCode / legacySku / legacyOrderCode fields so you can match them to V2 references during the move. These legacy fields will be removed in V3, so plan to switch your storage to V2 references over time. The /utilities/lookup-*-by-legacy-* endpoints help you translate codes you already have on file.

See the Items, Products and SKUs guide for how product identifiers map across versions.

Endpoint mapping

V2 also adds areas that didn't exist in V1: claims, shipments, organization read endpoints, addresses, scenes/perspectives/compositions for renders, and warehouse items. You can adopt these as you need them.

Image upload

V1 accepts a base64-encoded JPEG/PNG inside a JSON body. V2 expects the raw image bytes as the request body with Content-Type: application/octet-stream. If you're porting a V1 upload routine, you can drop the base64 step.

Notifications

The orderUpdated callback you configured for V1 keeps firing for orders created via V2, so your existing notification handler continues to work. A broader webhook system covering more events is on our roadmap.

Errors

V1 and V2 both return a { "code": "...", "message": "..." } body for 4xx responses. The set of error codes differs per endpoint; see each endpoint's reference page for the codes you may receive.

Rate limiting

V2 publishes its rate-limit policies and returns a 429 Too Many Requests response with Retry-After, X-RateLimit, and X-RateLimit-Policy headers, so you can back off without guessing. V1 limits were implicit. See the Rate Limiting guide.

Versioning

V2 follows semantic versioning: additive changes ship as minor versions and won't break your client; breaking changes wait for the next major version. See the API Versioning guide for the deprecation policy and what counts as a non-breaking change.