Printumo API
Place canvas and fine art print orders from your own website or system, and read your products, orders, shipping rates and our catalogue. Create your API key in your dashboard under Stores → API.
API Documentation
Need help with the API? Contact our development team at dev@printumo.com
Overview
The Printumo API v1 provides RESTful endpoints for integrating external e-commerce platforms with Printumo's print-on-demand services. This API allows partners to access product catalogs, manage orders, and retrieve shipping information programmatically.
Base URL
https://printumo.com/api/v1
Authentication
All API requests require authentication using Bearer token authentication with API keys generated from your profile.
Authorization: Bearer YOUR_API_KEY
Response Format
All responses are returned in JSON format:
Success Response
{
"success": true,
"data": { ... }
}
Error Response
{
"success": false,
"error": "Error description",
"errors": ["Details..."]
}
Available Endpoints
/account
Retrieve the Printumo account the API key belongs to. Works with live and sandbox keys, and for an account with no products or orders yet.
account_id, name and email
account_id is a stable identifier that never changes for an account and is the same for every API key on it. The get_account_settings tool on the AI agent (MCP) connection returns the same account_id, so a platform that uses both can confirm that an API key and an AI agent connection belong to the same Printumo account.
{
"success": true,
"data": {
"account_id": "acct_3f9a1c0b7d2e4a6f8b1c5d7e",
"name": "Anna Berg",
"email": "anna@example.com"
}
}
/products
Retrieve all accepted products for the authenticated user.
/orders
Retrieve all orders for the authenticated user.
production_country_code, production_country_name; empty in sandbox), payments, shipping addresses, and tracking per shipment in fulfillments
Order status and tracking
status is one of:
PENDING_PAYMENT: created, not yet paidUNFULFILLED: paid, waiting to be sent to productionPRINTING_SCHEDULED,PRINTING_STARTED,PRINTED: in productionPRINTING_SCHEDULING_FAILED,PRINTING_ERRORED: production could not start; our support team is notifiedPARTIALLY_FULFILLED: some parcels have shippedIN_TRANSIT: every parcel has shippedDELIVERED: the courier reports deliveryCANCELLED,PRINTING_CANCELLED: cancelled
fulfillments holds one entry per shipped parcel and is empty until the first parcel ships. tracking_url is null for the rare untracked shipment.
"fulfillments": [
{
"carrier": "DHL",
"tracking_number": "00340434161234567890",
"tracking_url": "https://www.dhl.com/track?tracking-id=00340434161234567890",
"status": "FULFILLED",
"line_item_ids": [912]
}
]
/orders
Create a new order using existing products.
A new order starts as PENDING_PAYMENT. With auto-pay switched on under Billing and a saved card, it is paid by itself shortly after, the same way as an order from a connected store. Otherwise the seller pays it from the order page in the dashboard.
Optional: canvas_wrapping per line_item (wrap_type: mirrored/stretched/solid_color, wrap_color)
Example Request
curl -X POST 'https://printumo.com/api/v1/orders' \
-H 'Authorization: Bearer YOUR_API_KEY' \
-H 'Content-Type: application/json' \
-d '{
"line_items": [
{
"variant_id": 456,
"quantity": 1,
"canvas_wrapping": {
"wrap_type": "solid_color",
"wrap_color": "#FF0000"
}
}
],
"shipping_address": {
"email": "customer@example.com",
"first_name": "John",
"last_name": "Doe",
"address1": "123 Main Street",
"city": "Amsterdam",
"postcode": "1012AB",
"country_code": "NL"
},
"selected_currency": "EUR"
}'
/api_image_orders
Create orders directly from image URLs. Printumo downloads and processes the image, and builds an order asynchronously.
Provide one or more
line_items. Each item needs its own image_url and component IDs:
{"image_url","print_type_id","size_id","framing_id","market_id","passepartout_id?"}
market_id selects the catalog, the price list, the currency and the unit for the line item. It does not select where we print: we route every order to a facility from its shipping address. Use the Market Reference below for the valid IDs.
size_id and framing_id are specific to the print type. Pick the print type in the Size Reference and Framing Reference below, then take the IDs from the filtered rows.
Required keys: email, first_name, last_name, address1, city, postcode, country_code.
Returns
202 Accepted with api_image_order_id. Poll GET /api_image_orders/:id or configure webhook_url to be notified when the order is created, fails or ships.
The print product is checked against
shipping_address.country_code before the order is accepted. A combination we cannot make or ship to that country returns 422, for example "Fine art paper print is not available for shipping to JP", and nothing is created. Sandbox keys run the same check.
JPEG/PNG/TIFF up to 100 MB, minimum 100×100 px. We crop to the requested aspect ratio.
To order a frame with no print in it, use the Empty frame print type with a
size_id and framing_id from the Fine Art Paper rows, and the Fine Art Paper market. Leave out image_url and passepartout_id. An empty frame ships at the same rate as a framed print of that size, and an order can mix empty frames and prints. Empty frames are available on request: contact us to have them priced on your account.
curl -X POST 'https://printumo.com/api/v1/api_image_orders' \
-H 'Authorization: Bearer YOUR_API_KEY' \
-H 'Content-Type: application/json' \
-d '{
"line_items": [
{
"image_url": "https://example.com/art.jpg",
"print_type_id": 2,
"size_id": 15,
"framing_id": 4,
"market_id": 3,
"quantity": 1
},
{
"image_url": "https://example.com/art-2.jpg",
"print_type_id": 2,
"size_id": 18,
"framing_id": 4,
"market_id": 3,
"quantity": 2
}
],
"shipping_address": {
"email": "customer@example.com",
"first_name": "Test",
"last_name": "User",
"address1": "123 Main St",
"city": "Copenhagen",
"postcode": "2100",
"country_code": "DK"
},
"webhook_url": "https://merchant.com/webhooks/printumo"
}'
Status – GET /api_image_orders/{id}
Returns current state (pending, processing, completed, failed), any error_message, and the created order_id (when completed).
{
"success": true,
"data": {
"id": 25,
"status": "completed",
"order_id": 157,
"error_message": null,
"created_at": "2025-11-13T21:21:50Z",
"processed_at": "2025-11-13T21:22:12Z"
}
}
Webhook Payloads
We POST to your webhook_url with HMAC-signed payloads for api_image_order/completed, api_image_order/failed and api_image_order/shipped.
{
"topic": "api_image_order/completed",
"api_image_order_id": 25,
"status": "completed",
"order": { ...same order object as the shipped example... },
"created_at": "2025-11-13T21:22:10Z",
"processed_at": "2025-11-13T21:22:12Z"
}
{
"topic": "api_image_order/failed",
"api_image_order_id": 25,
"status": "failed",
"error_message": "Print product combination not found",
"created_at": "2025-11-13T21:22:10Z",
"processed_at": "2025-11-13T21:22:12Z"
}
api_image_order/shipped is sent once per parcel when it ships, so an order sent in two parcels produces two. Each carries the order with every parcel shipped so far in fulfillments. The top-level status is the image order's status and stays completed.
{
"topic": "api_image_order/shipped",
"api_image_order_id": 25,
"status": "completed",
"order": {
"id": 157,
"status": "IN_TRANSIT",
"total_cents": 6450,
"total_currency": "EUR",
"line_items": [
{ "id": 912, "variant_id": 4410, "quantity": 1 }
],
"fulfillments": [
{
"carrier": "DHL",
"tracking_number": "00340434161234567890",
"tracking_url": "https://www.dhl.com/track?tracking-id=00340434161234567890",
"status": "FULFILLED",
"line_item_ids": [912]
}
],
"created_at": "2025-11-13T21:22:12Z",
"updated_at": "2025-11-16T09:41:03Z"
},
"created_at": "2025-11-13T21:22:10Z",
"processed_at": "2025-11-13T21:22:12Z"
}
Each webhook is sent once and is not retried. If your endpoint may be unavailable, also poll GET /orders, which returns the same fulfillments.
Printumo does not email your customer. The shipping_address email is passed to the courier, which may send its own delivery updates. Our "Order shipped" email goes to your account address, and you can switch it off under Profile, Email notifications.
X-Printumo-Topic carries the event name. X-Printumo-Signature is HMAC-SHA256 of the raw request body, keyed with your API key exactly as issued, encoded as lowercase hex. Verify against the raw bytes, not a re-serialised object, and compare in constant time. There is no timestamp header.
expected = OpenSSL::HMAC.hexdigest("SHA256", ENV["PRINTUMO_API_KEY"], request.raw_post)
head :unauthorized unless OpenSSL.secure_compare(expected, request.headers["X-Printumo-Signature"].to_s)
Sandbox keys do not send webhooks, so a sandbox image order completes without notifying your endpoint.
/shipping_profiles
Get comprehensive shipping information including costs, zones, and regional data
Canvas Wrapping
Canvas products support three wrapping options that determine how the image extends around the canvas edges.
Mirrored (Default)
Image edges are reflected to create seamless margins
"wrap_type": "mirrored"
Stretched
Image is stretched to fill the entire canvas area
"wrap_type": "stretched"
Solid Color
Custom color margins around the image
"wrap_type": "solid_color"
"wrap_color": "#FF0000"
Important Notes
- Canvas wrapping only applies to canvas products (not paper)
- wrap_color is required when wrap_type is "solid_color"
- wrap_color must be a valid hex color format (#FF0000)
- If not specified, image orders use mirrored wrapping; orders for an existing product keep that product's saved wrap setting
- Historical wrap settings are preserved in orders
Print Type Reference
Print types define the production medium and which frame, passepartout, and wrapping options are allowed.
| ID | Name | Slug |
|---|---|---|
2
|
Canvas | canvas |
3
|
Canvas colored frames | canvas-colored-frames |
4
|
Empty frame | empty-frame |
1
|
Fine art paper print | fine-art-paper-print |
Size Reference
Size IDs are specific to the print type. Select the print type first, then take the size_id from the filtered rows. Only sizes you can order are listed.
| ID | Name | Centimeters | Inches | Aspect Ratio |
|---|---|---|---|---|
60
|
14.8 x 10.5 cm / 5 x 4″ (A6) | 14.8 × 10.5 cm | 5.8 × 4.1″ | A |
1
|
20 x 20 cm / 8 x 8″ | 20 × 20 cm | 8 × 8″ | 1:1 |
51
|
21 x 14.8 cm / 8 x 5″ (A5) | 21 × 14.8 cm | 8.3 × 5.8″ | A |
31
|
25 x 20 cm / 10 x 8″ | 25 × 20 cm | 10 × 8″ | 4:5 |
52
|
29.7 x 21 cm / 11 x 8″ (A4) | 29.7 × 21 cm | 11.7 × 8.3″ | A |
14
|
30 x 20 cm / 12 x 8″ | 30 × 20 cm | 12 × 8″ | 2:3 |
71
|
30.5 x 20.3 cm / 12 x 8″ | 30.5 × 20.3 cm | 12 × 8″ | 2:3 |
13
|
30 x 30 cm / 12 x 12″ | 30 × 30 cm | 12 × 12″ | 1:1 |
63
|
40 x 30 cm / 15 x 11″ | 40 × 30 cm | 15.7 × 11.8″ | 4:3 |
61
|
40 x 40 cm / 15 x 15″ | 40 × 40 cm | 15.7 × 15.7″ | 1:1 |
73
|
40.6 x 30.5 cm / 16 x 12″ | 40.6 × 30.5 cm | 16 × 12″ | 4:3 |
23
|
40 x 30 cm / 16 x 12″ | 40 × 30 cm | 16 × 12″ | 3:4 |
53
|
42 x 29.7 cm / 16 x 11″ (A3) | 42 × 29.7 cm | 16.5 × 11.7″ | A |
15
|
45 x 30 cm / 18 x 12″ | 45 × 30 cm | 18 × 12″ | 2:3 |
64
|
50 x 40 cm / 19 x 15″ | 50 × 40 cm | 19.7 × 15.7″ | 5:4 |
57
|
50 x 50 cm / 19 x 19″ | 50 × 50 cm | 19.7 × 19.7″ | 1:1 |
12
|
50 x 25 cm / 20 x 10″ | 50 × 25 cm | 20 × 10″ | 1:2 |
24
|
50 x 40 cm / 20 x 15″ | 50 × 40 cm | 20 × 15″ | 3:4 |
32
|
50 x 40 cm / 20 x 16″ | 50 × 40 cm | 20 × 16″ | 4:5 |
2
|
50 x 50 cm / 20 x 20″ | 50 × 50 cm | 20 × 20″ | 1:1 |
39
|
55 x 40 cm / 21 x 15″ | 55 × 40 cm | 21 × 15″ | 5:7 |
54
|
59.4 x 42 cm / 23 x 16″ (A2) | 59.4 × 42 cm | 23.4 × 16.5″ | A |
16
|
60 x 40 cm / 24 x 16″ | 60 × 40 cm | 24 × 16″ | 2:3 |
74
|
61 x 45.7 cm / 24 x 18″ | 61 × 45.7 cm | 24 × 18″ | 4:3 |
33
|
65 x 50 cm / 25 x 20″ | 65 × 50 cm | 25 × 20″ | 4:5 |
62
|
70 x 50 cm / 27 x 19″ | 70 × 50 cm | 27.6 × 19.7″ | 5:7 |
58
|
70 x 70 cm / 27 x 27″ | 70 × 70 cm | 27.6 × 27.6″ | 1:1 |
40
|
70 x 50 cm / 28 x 20″ | 70 × 50 cm | 28 × 20″ | 5:7 |
25
|
70 x 55 cm / 28 x 21″ | 70 × 55 cm | 28 × 21″ | 3:4 |
3
|
70 x 70 cm / 28 x 28″ | 70 × 70 cm | 28 × 28″ | 1:1 |
17
|
75 x 50 cm / 30 x 20″ | 75 × 50 cm | 30 × 20″ | 2:3 |
34
|
75 x 60 cm / 30 x 24″ | 75 × 60 cm | 30 × 24″ | 4:5 |
47
|
80 x 45 cm / 32 x 18″ | 80 × 45 cm | 32 × 18″ | 9:16 |
26
|
80 x 60 cm / 32 x 24″ | 80 × 60 cm | 32 × 24″ | 3:4 |
4
|
80 x 80 cm / 32 x 32″ | 80 × 80 cm | 32 × 32″ | 1:1 |
18
|
85 x 55 cm / 33 x 22″ | 85 × 55 cm | 33 × 22″ | 2:3 |
55
|
84.1 x 59.4 cm / 33 x 23″ (A1) | 84.1 × 59.4 cm | 33.1 × 23.4″ | A |
41
|
90 x 65 cm / 35 x 25″ | 90 × 65 cm | 35 × 25″ | 5:7 |
35
|
90 x 70 cm / 35 x 28″ | 90 × 70 cm | 35 × 28″ | 4:5 |
19
|
90 x 60 cm / 36 x 24″ | 90 × 60 cm | 36 × 24″ | 2:3 |
72
|
91.4 x 61 cm / 36 x 24″ | 91.4 × 61 cm | 36 × 24″ | 2:3 |
27
|
90 x 70 cm / 36 x 27″ | 90 × 70 cm | 36 × 27″ | 3:4 |
59
|
100 x 100 cm / 39 x 39″ | 100 × 100 cm | 39.4 × 39.4″ | 1:1 |
56
|
100 x 70 cm / 39 x 27″ | 100 × 70 cm | 39.4 × 27.6″ | 7:10 |
11
|
100 x 50 cm / 40 x 20″ | 100 × 50 cm | 40 × 20″ | 1:2 |
28
|
100 x 75 cm / 40 x 30″ | 100 × 75 cm | 40 × 30″ | 3:4 |
36
|
100 x 80 cm / 40 x 32″ | 100 × 80 cm | 40 × 32″ | 4:5 |
5
|
100 x 100 cm / 40 x 40″ | 100 × 100 cm | 40 × 40″ | 1:1 |
20
|
105 x 70 cm / 42 x 28″ | 105 × 70 cm | 42 × 28″ | 2:3 |
42
|
105 x 75 cm / 42 x 30″ | 105 × 75 cm | 42 × 30″ | 5:7 |
10
|
120 x 60 cm / 48 x 24″ | 120 × 60 cm | 48 × 24″ | 1:2 |
48
|
120 x 70 cm / 48 x 27″ | 120 × 70 cm | 48 × 27″ | 9:16 |
21
|
120 x 80 cm / 48 x 32″ | 120 × 80 cm | 48 × 32″ | 2:3 |
6
|
120 x 120 cm / 48 x 48″ | 120 × 120 cm | 48 × 48″ | 1:1 |
43
|
125 x 90 cm / 49 x 35″ | 125 × 90 cm | 49 × 35″ | 5:7 |
9
|
125 x 65 cm / 50 x 25″ | 125 × 65 cm | 50 × 25″ | 1:2 |
37
|
125 x 100 cm / 50 x 40″ | 125 × 100 cm | 50 × 40″ | 4:5 |
7
|
135 x 135 cm / 53 x 53″ | 135 × 135 cm | 53 × 53″ | 1:1 |
50
|
140 x 100 cm / 55 x 39″ | 140 × 100 cm | 55.1 × 39.4″ | 5:7 |
44
|
140 x 100 cm / 56 x 40″ | 140 × 100 cm | 56 × 40″ | 5:7 |
29
|
140 x 105 cm / 56 x 42″ | 140 × 105 cm | 56 × 42″ | 3:4 |
8
|
150 x 75 cm / 60 x 30″ | 150 × 75 cm | 60 × 30″ | 1:2 |
22
|
150 x 100 cm / 60 x 40″ | 150 × 100 cm | 60 × 40″ | 2:3 |
38
|
150 x 120 cm / 60 x 48″ | 150 × 120 cm | 60 × 48″ | 4:5 |
45
|
160 x 115 cm / 63 x 45″ | 160 × 115 cm | 63 × 45″ | 5:7 |
49
|
165 x 90 cm / 64 x 36″ | 165 × 90 cm | 64 × 36″ | 9:16 |
30
|
165 x 120 cm / 64 x 48″ | 165 × 120 cm | 64 × 48″ | 3:4 |
46
|
180 x 125 cm / 70 x 50″ | 180 × 125 cm | 70 × 50″ | 5:7 |
Framing Reference
Frame IDs vary by medium. Select the medium to see which frames you can use for canvas or fine art paper orders.
| ID | Name | Slug |
|---|---|---|
5
|
Zwart | black |
6
|
Black Wood | black-wood |
21
|
Blue | blue |
7
|
Blue Wood | blue-wood |
20
|
Donker eiken | dark-oak |
9
|
Green Wood | green-wood |
8
|
Grey Wood | cashmere-grey-wood |
11
|
Lilac Wood | lilac-wood |
12
|
Mint Wood | mint-wood |
2
|
Geen lijst | no-frame |
3
|
Eiken | oak |
13
|
Oak Dark | oak-dark |
14
|
Oak Nature | oak-nature |
22
|
Orange | orange |
15
|
Orange Wood | orange-wood |
23
|
Pink | pink |
16
|
Red Wood | red-wood |
17
|
Rose Wood | rose-wood |
10
|
Teal Wood | indian-teal-wood |
4
|
Wit | white |
18
|
White Wood | white-wood |
24
|
Yellow | yellow |
19
|
Yellow Wood | yellow-wood |
Passepartout Reference
Passepartout IDs are required when ordering fine art paper prints, framed or unframed. On framed orders the passepartout ships as a physical cardboard mat; on unframed orders the border is printed into the print file instead. Canvas orders should use the “No Passepartout” option.
| ID | Name | Slug |
|---|---|---|
6
|
Black | black |
7
|
Freja | freja |
3
|
Green | green |
12
|
Grey | cashmere-grey |
4
|
Light blue | lightblue |
2
|
Lilac | lilac |
1
|
No border | no-passepartout |
5
|
Orange | orange |
10
|
Red | red |
11
|
Teal | indian-teal |
9
|
White | white |
8
|
Yellow | yellow |
Market Reference
Use one of these IDs when you set market_id in an API payload. A market selects the catalog, the price list, the currency and the unit for a line item.
A market does not select where we produce the order. We pick the print facility from the shipping address of each order, so you never have to choose a country or a supplier yourself.
| ID | Name | Print Type | Currency | Units |
|---|---|---|---|---|
1
|
Europe & United Kingdom | Canvas | EUR | cm |
2
|
Europe, United Kingdom, United States & Australia | Canvas | USD | in |
3
|
Fine art paper print | Fine art paper print | EUR | cm |
Sandbox Mode
Use sandbox API keys to run end-to-end tests without triggering live fulfillment.
Sandbox traffic runs against the exact same endpoints (https://printumo.com/api/v1) but writes into isolated sandbox_orders or sandbox_api_image_orders records.
Create
- Go to Stores → API → API Keys.
- Check the Sandbox mode box when creating a key.
- Store the generated token securely; you’ll need it for HTTP calls.
Use
- Send requests with
Authorization: Bearer SANDBOX_KEY. POST /ordersvalidates payloads but stores them as sandbox orders.POST /api_image_ordersvalidates specs, simulates processing, and links to sandbox orders.GET /ordersandGET /api_image_orders/{id}return the sandbox records created with that key.
Notes
- Swap back to a live key to create real orders.
- Sandbox image orders are auto-completed immediately; webhooks are skipped.
- Sandbox responses mirror live responses, so you can reuse the same JSON parsing code.