---
# System prepended metadata
title: Cimpress Open Partner Integration
tags: [Cimpress-Open, Cimpress]
---
# Cimpress Open Integration Guide
## 1. Overview
Cimpress Open is a unified integration platform that connects partners seamlessly with Cimpress Mass Customisation Platform (MCP). It simplifies order ingestion by removing the need for direct MCP integrations, ensuring smooth order processing, real-time status updates, flexible customization, and scalable growth.
## 2. Key Business Benefits
🔌 **Seamless Integration**
Cimpress Open enables your systems to inject orders directly into the Cimpress network through customized solutions and secure API, ensuring frictionless onboarding without complex technical rework.
🕒 **Near Real-Time Visibility**
Receive near real-time order status updates on your registered API callbacks, giving your businesses and customers clear visibility and confidence at every step.
🔒 **Secure & Scalable**
Built on an event-driven architecture, the platform scales with your business. Its modular and secure design ensures flexibility, privacy, and growth with minimal disruption, avoiding the noisy neighbor problem through isolated pipelines.
---
## 3. Capabilities
* **Secure Order Ingestion:**
Provides a single, secure HTTPS endpoint for receiving partner orders. The platform validates, transforms, and automatically routes orders to the correct fulfillment provider.
* **Automated Status Callbacks:**
Proactive, real-time status updates are pushed to your registered API endpoint (webhook). This includes "In Production" status and "Shipped" status with a tracking URL.
* **Centralized Authentication:**
All API communication is secured using the OAuth 2.0 Client Credentials flow for server-to-server authentication.
---
## 4. How It Works
The integration process includes two key stages: a **secure credential setup** and an **order processing flow** that enables seamless connectivity between partner systems and Cimpress Open.
### 4.1. Setup: Credential Management
All integrations with Cimpress Open are secured using the **OAuth 2.0 Client Credentials Flow** ensuring that only authorized systems access Cimpress Open APIs.
* The designated technical contact of the partner organization is invited and granted access to the Cimpress Authentication Portal, where API credentials can be managed and rotated.
* Partners must securely store credentials within their systems and rotate them before they expire.
### 4.2. Partner → Cimpress Open
This is the first step in the order flow. Your system authenticates using its credentials to get a short-lived Access Token ([see 5.1 Authentication API](#authentication-api)). You then use this token in the `Authorization` header to submit the new order to your dedicated API endpoint ([see 5.2 Order Submission API](#order-submission-api)).
### 4.3. Cimpress Open → Cimpress Fulfilment Network
Once your order is accepted, the Cimpress Open Processing Pipeline transforms the payload into Cimpress standardized data format. This includes:
* Applying partner-specific configurations and adapting to their PII handling requirements.
* Converting artwork files into Cimpress-standard formats.
* Routing the order to the correct fulfillment provider for production.
### 4.4. Cimpress Open → Partner
As the order's status changes (e.g., "Processing", "Shipped"), Cimpress Open sends real-time notifications to your registered API endpoint ([see 5.3 Status Update API](#status-update-api)). These outbound calls are authenticated using the method agreed upon during integration.
---
## 5. API Reference
### 5.1. Authentication API
Used to obtain an access token in exchange for client credentials.
* **Endpoint:**
`POST https://oauth.cimpress.io/v2/token`
* **Headers**
| Field | Type | Description |
| ------------ | ------ | ------------------ |
| Content-Type | string | `application/json` |
* **Request Body**
| Parameter | Type | Description |
| ------------- | ------ | ----------------------------- |
| grant_type | string | Must be `client_credentials`. |
| client_id | string | Your unique Client ID. |
| client_secret | string | Your unique Client Secret. |
| audience | string | Credential Audience |
* **Success Response (`200 OK`)**
| Field | Type | Description
|-|-|-|
| access_token | string | The Bearer token used for subsequent API requests.
| expires_in | integer | The token's lifespan in seconds (e.g. `86400`).
| token_type | string | Will always be `Bearer`
* **Error Responses**
| Status Code | Description
|-|-|
| 400 Bad Request | Invalid parameters (e.g., missing `client_id`). |
| 401 Unauthorized | Invalid `client_id` or `client_secret`. |
---
### 5.2. Order Submission API
Used to submit partner orders for processing within Cimpress Open.
* **Endpoint:**
`POST https://partnerapi.cimpressopen.cimpress.io/[PARTNER_IDENTIFIER]/v1/orders`
* **URL Params:**
| Field | Type | Description
|-|-|-|
| PARTNER_IDENTIFIER | string | A unique string to be allocated to each Cimpress Partner during the integration.
* **Headers:**
| Field | Type | Description
|-|-|-|
| Authorization | string | Cimpress Owned Access Token (e.g. `Bearer `) |
| Content-Type | string | Must be `application/json`. |
---
#### **Order Payload Schema**
##### **Top Level Attributes**
| Field | Type | Description
|-|-|-|
| orderId | string | Your unique order identifier (e.g. `Order-987654`)
| purchaseDate | string | The date when the order was created. In ISO 8601 date-time format (e.g. `2025-10-30T10:00:00Z`).
| currencyCode | string | The three-digit currency code. In [ISO 4217](https://en.wikipedia.org/wiki/ISO_4217) format (e.g. `EUR`, `USD`).
|items | array | An array containing one or more product item objects to be fulfilled. **See [Items Attributes](#items-attributes)**
shippingAddress | object | Contains all required details for the shipping destination. **See [ShippingAddress Attributes](#shippingaddress-attributes)**
| salesChannelId | string | (optional) The predefined region or market from which the order originated. Values are determined during integration (e.g. `NL`, `DE`).
| earliestShippedDate | string | (optional) The start of the time period within which you have committed to ship the order. In [ISO 8601](https://developer-docs.amazon.com/sp-api/docs/iso-8601) date time format.
| earliestDeliveryDate | string | (optional) The start of the time period within which you have committed to deliver the order. In [ISO 8601](https://developer-docs.amazon.com/sp-api/docs/iso-8601) date time format.
##### **Items Attributes**
| Field | Type | Description
-|-|-|
| itemId | string | A unique partner-defined identifier for this specific order item.
| variantId | string | A unique product variant id.
| quantity | integer | The total number of units for this item to be produced.
| artwork | object | (optional) Object containing details for the item's customization.
• **artwork.url** — A publicly accessible, downloadable HTTPS URL for the artwork file.
• **artwork.type** — The file format of the artwork (e.g. `pdf`).
(optional) Price breakdown details for the individual item.
• **price.totalAmount** — The total price of the item excluding tax. Must be a numerical string (e.g. `"19.99"`).
• **price.taxAmount** — (optional) The calculated tax amount for the item. Must be a numerical string (e.g. `"2.10"`).
• **price.discount** — (optional) The total discount applied to the item(s). Must be a numerical string (e.g. `"1.00"`).
(optional) Shipping price breakdown details for the item.
• **shippingPrice.amount** — The total shipping price of the item excluding tax. Must be a numerical string (e.g. `"3.99"`).
• **shippingPrice.taxAmount** — (optional) The calculated shipping tax amount for the item. Must be a numerical string (e.g. `"1.10"`).
• **shippingPrice.discount** — (optional) The total discount applied to the item(s). Must be a numerical string (e.g. `"0.50"`).