# 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
<a id="authentication-api"></a>
### 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`. |
---
<a id="order-submission-api"></a>
### 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 <YOUR_ACCESS_TOKEN>`) |
| Content-Type | string | Must be `application/json`. |
---
<a id="top-level-attributes"></a>
#### **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)**
<a id="items-attributes"></a> 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 | <details><summary>(optional) Object containing details for the item's customization.</summary><br/>• **artwork.url** — A publicly accessible, downloadable HTTPS URL for the artwork file.<br/>• **artwork.type** — The file format of the artwork (e.g. `pdf`).<br/><br/></details>
| price | object | <details><summary>(optional) Price breakdown details for the individual item.</summary><br/>• **price.totalAmount** — The total price of the item excluding tax. Must be a numerical string (e.g. `"19.99"`).<br/>• **price.taxAmount** — (optional) The calculated tax amount for the item. Must be a numerical string (e.g. `"2.10"`).<br/>• **price.discount** — (optional) The total discount applied to the item(s). Must be a numerical string (e.g. `"1.00"`).<br/><br/></details>
| shippingPrice | object | <details><summary>(optional) Shipping price breakdown details for the item.</summary><br/>• **shippingPrice.amount** — The total shipping price of the item excluding tax. Must be a numerical string (e.g. `"3.99"`).<br/>• **shippingPrice.taxAmount** — (optional) The calculated shipping tax amount for the item. Must be a numerical string (e.g. `"1.10"`).<br/>• **shippingPrice.discount** — (optional) The total discount applied to the item(s). Must be a numerical string (e.g. `"0.50"`).<br/><br/></details> |
</details>
<a id="shippingaddress-attributes"></a>
##### **ShippingAddress Attributes**
| Field | Type | Description |
|-|-|-|
| method | string | The predefined chosen shipping service level (e.g. `standard`, `express`). |
| name | string | Recipient's full name. |
| stateOrRegion | string | The state, region, or province name/code. |
| postalCode | string | The postal code or ZIP code. |
| countryCode | string | The country code, a two-character code in [ISO 3166-1](https://en.wikipedia.org/wiki/ISO_3166-1) alpha-2 format (e.g. `DE`). |
| city | string | The city name. |
| addressLine1 | string | The primary street address line. |
| addressLine2 | string | (optional) Secondary address details (e.g., apartment number, suite). |
| type | string | (optional) The shipping address classification (e.g. `residential`, `business`). |
| phone | string | (optional) Recipient's phone number (essential for delivery). |
| email | string | (optional) Recipient's email (essential for delivery). |
</details>
---
##### **Error Responses**
| Status Code | Description
|-|-|
| 400 Bad Request | Validation failure on payload structure or business rules.
| 401 Unauthorized | Invalid or expired Access Token.
| 429 Too Many Request | Rate limit exceeded.
| 500 Internal Server Error | An unexpected error occurred on the server side.
---
<a id="status-update-api"></a>
### 5.3. Status Update API
* **Endpoint:**
`https://[PARTNER-PROVIDED-ENDPOINT]`
* **Authentication:**
Cimpress Open will authenticate its requests to your endpoint. We will configure our system to use your required authentication mechanism during the integration setup.
**Status Payload Schema**
**Top Level Attributes**
| Field | Type | Description |
|-------------|--------|-------------|
| orderId | string | Partner Order Number |
| status | string | Partner Specific Order Status (e.g. `processing`, `shipped`) |
| timestamp | string | Time of Event [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601) |
| shipment | array | (optional) An array containing one or more shipment detail when status is `shipped`. See [Shipment Attribute](#shipment-attribute) |
<a id="shipment-attribute"></a>
**Shipment Attributes**
| Field | Type | Description |
|------|------|-------------|
| itemId | string | Order Item identifier being shipped. |
| quantity | number | Quantity of the item included in this shipment |
| trackingURL | string | Carrier Tracking URL |
Sign in with Wallet
Connect another wallet