allthe

Artwork & decoration

Attach decoration to an order line two ways:

  • Fixed artwork — you supply a print-ready image (and optional mock) URL per print area.
  • Personalisation — you supply the buyer's inputs (text, images, colours) for a personalised product, and we render the print-ready artwork for you.

Both attach to a line via a decoration block on POST /orders (see Orders). We fetch every URL server-side, validate it, store it, and produce the same canonical artwork every fulfilment surface reads — you never upload file bytes to us directly.

Base URL: https://developer.allthe.com/api/v1 Required scope: orders:write

Validate a URL first (optional)

Dry-run an artwork or mock URL before you order — same fetch + validation as intake, but nothing is stored. Use it to catch a bad asset before placing (and paying for) an order.

POST /uploads/validate

| Field | Type | Required | Description | | ------ | -------- | -------- | --------------------------------------------- | | url | string | One of | A single URL to validate. | | urls | string[] | One of | Up to 10 URLs to validate in one call. |

curl -X POST "https://developer.allthe.com/api/v1/uploads/validate" \
  -H "Authorization: Bearer pat_live_..." \
  -H "Content-Type: application/json" \
  -d '{ "urls": ["https://cdn.example.com/front.png", "https://cdn.example.com/broken.gif"] }'

{
  "valid": false,
  "results": [
    { "url": "https://cdn.example.com/front.png", "valid": true, "mime": "image/png", "width": 4000, "height": 4000 },
    { "url": "https://cdn.example.com/broken.gif", "valid": false, "code": "format", "message": "Unsupported image format — PNG, JPEG or WebP only" }
  ]
}

valid is true only when every URL passed. Individual failures carry a code (scheme, ssrf, format, size, dimensions, fetch, …) and a human-readable message.

Validation rules

Applied on intake and by the validator. A failure on any URL rejects the whole order (422 validation_failed) — we never create a partially-decorated order.

| Rule | Limit | | ----------- | --------------------------------------------------------------------- | | Scheme | https only. | | Format | PNG, JPEG or WebP — detected by content, not file extension. | | Size | 50 MB max per file (streamed with a hard cap). | | Dimensions | 12,000 px per side and 60 megapixels max. | | Host | Public hosts only — private, loopback, link-local and cloud-metadata addresses are blocked (and re-checked across redirects). |

Fixed artwork

Add decoration.areas[] to a line. Each area names a print area and method configured on the product, plus an artwork_url and optional mock_url.

| Field | Type | Required | Description | | ------------------------ | ------ | -------- | ----------------------------------------------------------------- | | print_area | string | Yes | A print area configured on the product (e.g. Front). | | method | string | Yes | The decoration method for that area (e.g. DTG). | | artwork_url | string | Yes | Print-ready artwork. Fetched, validated, stored and normalised. | | mock_url | string | No | A garment mock for the line (first one becomes the line mock). |

curl -X POST "https://developer.allthe.com/api/v1/orders" \
  -H "Authorization: Bearer pat_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "items": [{
      "product_id": "ckor1abc...",
      "variant_sku": "G6400-BLK-M",
      "quantity": 10,
      "decoration": {
        "areas": [
          { "print_area": "Front", "method": "DTG", "artwork_url": "https://cdn.example.com/front.png", "mock_url": "https://cdn.example.com/front-mock.png" },
          { "print_area": "Back",  "method": "DTG", "artwork_url": "https://cdn.example.com/back.png" }
        ]
      }
    }],
    "shipping_address": { "contact_name": "Jane Doe", "line1": "12 Example Street", "city": "London", "postcode": "SW1A 1AA", "country_code": "GB" }
  }'

The order is created and charged synchronously — the response is the normal order object. Each area's artwork is then resized to that print area's exact print template (dimensions, DPI, format) asynchronously; the line is upgraded to print-ready in the background. decoration.areas supersedes any print_jobs on the same line.

Personalisation

Add decoration.personalisation to a line whose product_id is a personalised product. You supply inputs, keyed by the product's personalisation layer ids; we render the print-ready artwork.

| Field | Type | Required | Description | | --------------------------- | ------ | -------- | ------------------------------------------------------------------ | | inputs | object | Yes | Map of layerId → value. See below. |

Values by layer type:

| Layer | Value | | ---------------- | -------------------------------------------------------------------------------------- | | Text | The text string ("Sam"). | | Image | An image URL — we fetch, validate, store it, and use it in the render. | | Photo collage | A JSON-encoded array of image URLs ("[\"https://…/1.jpg\",\"https://…/2.jpg\"]"). | | Image select | The chosen option id. |

Optional overrides (when the layer allows them): "<layerId>#font" (font family) and "<layerId>#color" (hex colour). Send null to leave an optional layer empty. Positions, sizing and fonts are defined by the product template — you only supply values.

curl -X POST "https://developer.allthe.com/api/v1/orders" \
  -H "Authorization: Bearer pat_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "items": [{
      "product_id": "ckPersonalisedProduct...",
      "variant_sku": "G6400-WHT-L",
      "quantity": 1,
      "decoration": {
        "personalisation": {
          "inputs": {
            "layer_name":  "Sam",
            "layer_name#font":  "Poppins",
            "layer_name#color": "#E55934",
            "layer_photo": "https://cdn.example.com/pet.jpg"
          }
        }
      }
    }],
    "shipping_address": { "contact_name": "Jane Doe", "line1": "12 Example Street", "city": "London", "postcode": "SW1A 1AA", "country_code": "GB" }
  }'

A line may carry either areas or personalisation, not both. The order is created and charged synchronously; the personalised artwork is rendered in the background and attached to the line when ready.

Errors

| Status | Code | Reason | | ------ | ------------------- | ----------------------------------------------------------------- | | 422 | validation_failed | An artwork/mock URL failed validation; an unknown print_area/method or personalisation layerId; or the product isn't personalised. | | 404 | not_found | A product_id is unknown or belongs to another account. |

When is the line ready?

Decoration processing is asynchronous, so a freshly created decorated line may not have print-ready artwork the instant POST /orders returns. Ops routing waits for artwork to be present before a line enters production. Poll GET /orders/{id} for status; webhooks for readiness are on the roadmap.