Artwork & Print Files

When you create an order with createOrderFromGtin, each order item carries one or more images. The printing images are the actual files Riverr sends to production. This page describes the file requirements those artwork URLs must meet, and — importantly — the hosting guarantee they must satisfy.

You pass artwork as URLs, not bytes. Riverr stores the URL you provide and fetches it downstream during batching, printing, PDF generation, and fulfillment. Two things follow from that: the file must be print-ready, and the URL must stay reachable for a long time.

Print-file spec

Property	Requirement
Format	PNG or JPEG. (Transparent backgrounds → PNG.)
Color profile	sRGB. Do not submit CMYK files.
Bit depth	8-bit per channel.
Other formats	TIFF, PSD, PDF, SVG and CMYK files are not accepted as printing artwork.
Resolution	Target 300 DPI at the printed size. 100 DPI is the hard floor — below that, print quality is rejected/degraded.
File size	Keep files lean — production-grade PNG/JPEG, generally under ~50 MB.

What is enforced where

Riverr's designer UI accepts only image/png and image/jpeg for uploads and enforces the 100-DPI floor on placed artwork (see Effective DPI below). The OpenAPI layer does not validate color profile, bit depth, format, DPI, or file size on the URLs you submit — it stores the URL verbatim. Treat the table above as your responsibility to satisfy before submitting: a CMYK, low-DPI, or oversized file will pass the API call and then fail or look wrong in production.

Effective DPI

DPI is not a property of the file alone — it depends on how large the image is printed. Riverr's designer computes an effective DPI per placement as:

dpiX = sourceWidthInPixels  / printedWidthInInches
dpiY = sourceHeightInPixels / printedHeightInInches
effectiveDPI = min(dpiX, dpiY)

If the effective DPI of a placed image drops below 100, the designer scales it back up (or warns) rather than printing it. When you submit artwork through the API, pre-validate this yourself: make sure the pixel dimensions of your file divided by the physical print dimensions for the chosen placement stay at or above 100 — and aim for 300 — because the API will not check it for you.

Rule of thumb: for a print area W × H inches, supply at least W*300 × H*300 pixels (e.g. a 12" × 16" front print → ~3600 × 4800 px).

Hosting requirement: the URL must stay permanently public

This is the requirement integrators most often get wrong.

The artwork URL you submit is stored on the order and re-fetched repeatedly across the whole production lifecycle — batching, RIP/printing, PDF/print-file generation, fulfillment, and any later reprint. Riverr does not copy the bytes at order-create time; it keeps your URL.

Therefore the URL must be:

• Permanently reachable — it must outlive the entire batch → print → fulfillment → reprint cycle (which can be days or weeks, and reprints can come much later). Do not delete the file after submitting.
• Publicly fetchable over HTTPS — no auth headers, no cookies, no IP allow-listing.
• Stable, not expiring — do not use short-lived pre-signed URLs (e.g. time-limited S3/GCS signed links) that expire. If the link 404s when Riverr fetches it later, the file cannot be printed.

Expiring URLs break printing

A signed URL that works at order creation but expires hours later will cause the print/reprint step to fail. Host artwork at a durable, public, non-expiring location.

How artwork is attached to an order

Each image needs a url, a placement (a string placement ID — see Placements), and a type (printing for the file to be printed, mockup for the visual proof):

mutation {
  createOrderFromGtin(input: {
    orderNumber: "ORD-3001"
    shopId: "shop_123"
    shippingAddress: { name: "John Doe", address1: "123 Main St", city: "New York", country: "US" }
    orderItems: [{
      gtin: "00123456789012"
      quantity: 1
      price: 19.99
      images: [
        { url: "https://cdn.example.com/front-300dpi.png", placement: "1", type: printing }
        { url: "https://cdn.example.com/front-mockup.png",  placement: "1", type: mockup }
      ]
    }]
  }) {
    id
    orderItems { id images { url placement type } }
  }
}

Mapping readiness

For an order item to become "mapped" and flow into production, every printing image must carry a url and a placement, and the item must resolve to a blank product/variant (which createOrderFromGtin handles for you via the GTIN). Items missing a placement or with an unreachable artwork URL will not map cleanly. Always set placement on every printing image, and confirm the URL is publicly reachable before submitting.