BlotPrints API

All our products can be ordered through our API. Made for developers and for AI agents.

Introduction

The base URL is:

https://www.blotprints.com/api/v1

• Requests and responses are JSON (Content-Type: application/json).
• No API key is needed. Calls are rate limited per IP address (see Rate limits).
• Dates and times are in ISO 8601, in UTC, like 2026-10-25T12:00:00Z.
• There’s no test mode: a quote is free and changes nothing, and an order only becomes real once it’s paid.

Example order

Ordering a hardcover book from PDFs that are online.

1. Get a quote

curl -X POST https://www.blotprints.com/api/v1/quotes \
  -H "Content-Type: application/json" \
  -d '{
    "items": [{
      "product": "hardcover",
      "size": "a5-portrait",
      "options": { "cover": "matte", "paper": "matte_standard" },
      "quantity": 1,
      "files": {
        "interior": { "url": "https://example.com/book-interior.pdf" },
        "cover": { "url": "https://example.com/book-cover.pdf" }
      }
    }],
    "shipping": { "country": "NL", "method": "standard" }
  }'

2. Place the order, with the quoteId from the response. If the quote has warnings, add "acceptWarnings": true (see 3. Get a quote).

curl -X POST https://www.blotprints.com/api/v1/orders \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: 5f1c2d3e-my-unique-key" \
  -d '{
    "quoteId": "quo_8hQ2kV7xLm3pR9tY",
    "acceptTerms": true,
    "email": "[email protected]",
    "shippingAddress": {
      "name": "Jane Doe",
      "line1": "Keizersgracht 123",
      "postalCode": "1015 CJ",
      "city": "Amsterdam",
      "country": "NL"
    }
  }'

3. Complete payment: open the paymentUrl from the response in a browser.

Placing an order

1. Choose a product

The products tell you what you can order: per product its sizes, options and prices, and the files we need. Use the names from here (product, size, the option values) in your quote.

All products

GET https://www.blotprints.com/api/v1/products

Everything you can order, with its sizes, options and prices.

{
  "products": [
    {
      "product": "hardcover",
      "name": "Hardcover book",
      "sizes": [
        {
          "size": "a5-portrait",
          "width": 148,
          "height": 210,
          "pages": { "min": 24, "max": 400, "step": 2 },
          "files": {
            "interior": { "fileTypes": ["pdf"], "width": 154, "height": 216, "bleed": 3 },
            "cover": { "fileTypes": ["pdf", "jpg", "png"], "width": 354, "height": 255, "bleed": 19 }
          },
          "price": { "base": 15.99, "perExtraPage": 0.40 },
          "options": {
            "cover": {
              "values": [
                { "value": "matte", "name": "Hardcover matte", "price": 5.99 },
                { "value": "glossy", "name": "Hardcover glossy", "price": 0 }
              ],
              "default": "matte"
            },
            "paper": {
              "values": [
                { "value": "matte_standard", "name": "Standard matte", "price": 0, "perExtraPage": 0 },
                { "value": "matte_heavy", "name": "Heavy matte", "price": 1.44, "perExtraPage": 0.07 }
              ],
              "default": "matte_standard"
            }
          }
        },
        {
          "size": "a5-landscape",
          "width": 210,
          "height": 148,
          "pages": { "min": 24, "max": 400, "step": 2 },
          "files": {
            "interior": { "fileTypes": ["pdf"], "width": 216, "height": 154, "bleed": 3 },
            "cover": { "fileTypes": ["pdf", "jpg", "png"], "width": 470, "height": 193, "bleed": 19 }
          },
          "price": { "base": 15.99, "perExtraPage": 0.40 },
          "options": {
            "cover": {
              "values": [
                { "value": "matte", "name": "Hardcover matte", "price": 5.99 },
                { "value": "glossy", "name": "Hardcover glossy", "price": 0 }
              ],
              "default": "matte"
            },
            "paper": {
              "values": [
                { "value": "matte_standard", "name": "Standard matte", "price": 0, "perExtraPage": 0 },
                { "value": "matte_heavy", "name": "Heavy matte", "price": 1.44, "perExtraPage": 0.07 }
              ],
              "default": "matte_standard"
            }
          }
        }
      ]
    }
  ]
}

One product

GET https://www.blotprints.com/api/v1/products/{product}

The same as one product in the list.

2. Add your files

Your files are what we print: the design of a poster or panel, or a book’s pages and cover, as PDF, JPG or PNG. Which files a size needs is in its files (see 1. Choose a product). You can send each file in two ways: as a link we download it from, or uploaded to us.

Download link

Give a URL we can download, with https. Handy for files that are already online.

{ "url": "https://example.com/book-interior.pdf" }

The link has to work, without logging in, when you get the quote: that’s when we download the file. Links that expire (like presigned storage links) are fine.

Upload a file

For files on your computer (or an agent’s), ask for an upload address and send the file there.

POST https://www.blotprints.com/api/v1/uploads

No body is needed. Response:

{
  "uploadId": "upl_3vN8qR2xKt5mW7yZ",
  "uploadUrl": "https://…",
  "expiresAt": "2026-10-25T14:30:00Z"
}

Then send the file:

curl -T book-interior.pdf "<uploadUrl>"

And use the upload in your quote:

{ "uploadId": "upl_3vN8qR2xKt5mW7yZ" }

• File types: PDF, JPG and PNG, as the product allows. We go by what’s in the file, not its name or extension: anything else is refused (unsupported_file_type).
• Up to 200 MB per file.
• An upload we refuse (another type, or too large) is deleted right away: upload the right file again.
• An upload address works for an hour; an upload is kept for a day.

3. Get a quote

A quote is the step before an order: you send what you want to print, with the files, and we check the files and tell you what it costs, including shipping. Nothing is ordered or paid yet. If it looks good, you place the order with the quote.

POST https://www.blotprints.com/api/v1/quotes

{
  "items": [
    {
      "product": "poster",
      "size": "a3-landscape",
      "options": { "paper": "matte", "hanging": "photo_frame_black" },
      "quantity": 2,
      "files": { "design": { "uploadId": "upl_3vN8qR2xKt5mW7yZ" } }
    }
  ],
  "shipping": { "country": "NL", "method": "standard" }
}

Response:

{
  "quoteId": "quo_8hQ2kV7xLm3pR9tY",
  "expiresAt": "2026-10-26T12:00:00Z",
  "previewUrl": "https://www.blotprints.com/preview/quo_8hQ2kV7xLm3pR9tY",
  "items": [
    {
      "product": "poster",
      "size": "a3-landscape",
      "options": { "paper": "matte", "hanging": "photo_frame_black" },
      "quantity": 2,
      "unitPrice": 25.98,
      "price": 51.96,
      "vat": 9.02,
      "warnings": [
        {
          "code": "design_adjusted",
          "file": "design",
          "message": "The design is a different size or shape than the size needs. We zoom it in to fit, so 9.1% is cut off at the edges. Check the preview.",
          "values": { "cutOffPercent": 9.1 }
        }
      ],
      "previews": [
        {
          "file": "design",
          "url": "https://www.blotprints.com/api/v1/quotes/quo_8hQ2kV7xLm3pR9tY/previews/0-design.jpg",
          "width": 1200,
          "height": 853,
          "description": "The design as it's printed. The red line is where it's cut."
        }
      ]
    }
  ],
  "shipping": {
    "method": "standard",
    "price": 5.00,
    "vat": 0.87,
    "estimatedDelivery": { "from": "2026-10-28", "to": "2026-10-29" },
    "note": null
  },
  "shippingOptions": [
    {
      "method": "standard",
      "price": 5.00,
      "vat": 0.87,
      "estimatedDelivery": { "from": "2026-10-28", "to": "2026-10-29" }
    },
    {
      "method": "express",
      "price": 12.50,
      "vat": 2.17,
      "estimatedDelivery": { "from": "2026-10-27", "to": "2026-10-27" }
    }
  ],
  "total": 56.96,
  "vat": 9.89,
  "currency": "EUR",
  "termsUrl": "https://www.blotprints.com/terms"
}

A file we can’t print (wrong type, too few pages, can’t be read) is an error: the quote fails with 422 and lists every problem of every file in problems, so you can fix them all at once. See Errors.

A quote can be ordered once. For another order, get a new quote.

4. Place the order

An order is a quote you’ve decided to buy, with the address to ship it to. You get a payment link: once it’s paid, we print and ship it, and you can follow its status until it arrives.

POST https://www.blotprints.com/api/v1/orders

{
  "quoteId": "quo_8hQ2kV7xLm3pR9tY",
  "acceptTerms": true,
  "acceptWarnings": true,
  "reference": "SHOP-2026-0042",
  "email": "[email protected]",
  "shippingAddress": {
    "name": "Jane Doe",
    "line1": "Keizersgracht 123",
    "line2": "",
    "postalCode": "1015 CJ",
    "city": "Amsterdam",
    "country": "NL"
  }
}

Response (201):

{
  "orderId": "1042-x7Kq2mV9pL4tR8wN3bY6zA",
  "reference": "SHOP-2026-0042",
  "status": "awaiting_payment",
  "paymentUrl": "https://www.blotprints.com/pay/1042-x7Kq2mV9pL4tR8wN3bY6zA",
  "total": 56.96,
  "currency": "EUR"
}

5. Complete payment

Open the paymentUrl in a browser. It shows the order and asks for payment (iDEAL, card, and the other methods of the country). Once it’s paid, we print. An order that isn’t paid within 7 days is cancelled.

6. Track the order

GET https://www.blotprints.com/api/v1/orders/{orderId}

{
  "orderId": "1042-x7Kq2mV9pL4tR8wN3bY6zA",
  "reference": "SHOP-2026-0042",
  "status": "shipped",
  "createdAt": "2026-10-25T12:00:00Z",
  "paidAt": "2026-10-25T12:05:00Z",
  "items": [
    {
      "product": "poster",
      "size": "a3-landscape",
      "options": { "paper": "matte", "hanging": "photo_frame_black" },
      "quantity": 2,
      "unitPrice": 25.98,
      "price": 51.96,
      "vat": 9.02
    }
  ],
  "shipping": {
    "method": "standard",
    "price": 5.00,
    "vat": 0.87,
    "trackingUrl": "https://…"
  },
  "shippingAddress": {
    "name": "Jane Doe",
    "line1": "Keizersgracht 123",
    "line2": "",
    "postalCode": "1015 CJ",
    "city": "Amsterdam",
    "country": "NL"
  },
  "total": 56.96,
  "vat": 9.89,
  "currency": "EUR",
  "paymentUrl": null
}

status is one of:

Reference

Errors

An error has an HTTP status and a body like this:

{
  "error": {
    "code": "file_check_failed",
    "message": "The interior has 18 pages. It needs at least 24. The cover isn't a file type we print.",
    "item": 0,
    "file": "interior",
    "problems": [
      {
        "item": 0,
        "file": "interior",
        "code": "too_few_pages",
        "message": "The interior has 18 pages. It needs at least 24.",
        "values": { "pageCount": 18, "min": 24 }
      },
      {
        "item": 0,
        "file": "cover",
        "code": "unsupported_file_type",
        "message": "The cover isn't a file type we print."
      }
    ]
  }
}

Idempotency

Networks fail, and scripts and agents try again. To make sure an order is never placed twice, send an Idempotency-Key header with POST /orders: any unique text, like a UUID.

Sending the same key again within 24 hours gives back the same order, instead of a new one. Use a new key for each new order.

Rate limits

Per IP address:

Over a limit, you get 429 with a Retry-After header: the seconds to wait.

For AI agents

This page is also plain Markdown, at /api/docs.md: read that to learn the API. AI tools can also find it through /llms.txt, with the tips below.

MCP server. AI assistants that support the Model Context Protocol (Claude, ChatGPT, Copilot, …) can add BlotPrints as a connector, at:

https://www.blotprints.com/mcp

No login is needed. The assistant then gets the steps of this page as tools: list_products, get_product, create_upload, get_quote, place_order and get_order.

OpenAPI. The API is also described as OpenAPI 3.1, at /api/openapi.json: for tools that read it, like code generators or a custom GPT’s actions.

Tips for agents:

• Start with GET /products to see what’s possible, and pick sizes and options from it: don’t guess names.
• For files on the user’s computer, use an upload: curl -T file.pdf "<uploadUrl>".
• Show the user the quote’s preview (previewUrl), price, warnings and terms (termsUrl) before you place the order, and ask whether the preview looks right.
• Give the user the paymentUrl to pay: you can’t pay yourself.
• Keep the orderId to check on the order later.

Frequently asked questions