Inscrivez-vous et profitez de 30 % de réduction sur votre première commande !

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
API keys are 32-character base64-encoded tokens. Each key tracks usage and belongs to a specific user account.

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

GET /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.

Returns: 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"
  }
}
GET /products

Retrieve all accepted products for the authenticated user.

Returns: Products with variants, pricing, print types, markets, image URLs, and canvas wrapping settings (for canvas products)
GET /orders

Retrieve all orders for the authenticated user.

Returns: Order status, line items with wrapping settings and production country (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 paid
  • UNFULFILLED: paid, waiting to be sent to production
  • PRINTING_SCHEDULED, PRINTING_STARTED, PRINTED: in production
  • PRINTING_SCHEDULING_FAILED, PRINTING_ERRORED: production could not start; our support team is notified
  • PARTIALLY_FULFILLED: some parcels have shipped
  • IN_TRANSIT: every parcel has shipped
  • DELIVERED: the courier reports delivery
  • CANCELLED, 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]
  }
]
POST /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.

Required: line_items (variant_id, quantity), shipping_address (email, name, address, city, postcode, country_code).
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"
  }'
ASYNC /api_image_orders

Create orders directly from image URLs. Printumo downloads and processes the image, and builds an order asynchronously.

Line Items
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?"}
passepartout_id is optional (canvas defaults to no passepartout). Each line item is processed into its own product variant before the order is created.
Market and production
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 and frame 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.
Shipping Address
Required keys: email, first_name, last_name, address1, city, postcode, country_code.
Async Response
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.
Destination Check
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.
Image Requirements
JPEG/PNG/TIFF up to 100 MB, minimum 100×100 px. We crop to the requested aspect ratio.
Empty frames
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.

GET /shipping_profiles

Get comprehensive shipping information including costs, zones, and regional data

Includes: Pricing, shipping zones, country/province coverage, additional unit costs

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 Noir black
6 Black Wood black-wood
21 Blue blue
7 Blue Wood blue-wood
20 Chêne foncé dark-oak
9 Green Wood green-wood
8 Grey Wood cashmere-grey-wood
11 Lilac Wood lilac-wood
12 Mint Wood mint-wood
2 Sans cadre no-frame
3 Chêne 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 Blanc 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

  1. Go to Stores → API → API Keys.
  2. Check the Sandbox mode box when creating a key.
  3. Store the generated token securely; you’ll need it for HTTP calls.

Use

  • Send requests with Authorization: Bearer SANDBOX_KEY.
  • POST /orders validates payloads but stores them as sandbox orders.
  • POST /api_image_orders validates specs, simulates processing, and links to sandbox orders.
  • GET /orders and GET /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.