Order from your own system

In five steps

1. Ask the studio for a partner account: you receive a key and your terms — on account or prepaid, a credit limit, a discount.
2. Upload each picture (POST /uploads) and keep the id it answers.
3. Price the order (POST /quote): each line, the shipping options, VAT, the total — and whether it would go straight into production.
4. Place it (POST /orders) with your own reference and an Idempotency-Key. It is priced again here; send expected_total so that a price that moved is refused, never charged.
5. Follow it on your webhook, or ask GET /orders?updated_since= now and then.

A partner account, a key, a question: info@xyz-prints.com.

Authentication

Every call carries your partner key in the header Authorization: Bearer <key>. The key reaches this API only, and only your own orders and files. Keep it on your server — never in a browser or an app. The studio mints and revokes keys: ask for a new one if it leaks. It can also hold your key to the addresses your servers call from, so a key that leaks is worth nothing elsewhere.

curl \
  -H "Authorization: Bearer $XYZ_KEY" \
  https://www.xyz-prints.com/api/v1/partner

Money is EUR with VAT included, as the storefront shows it; the rate follows the delivery country and your VAT number, checked with VIES. Prices are always computed here — your system never computes money.

Files

Send each picture once, as the multipart/form-data field file. Formats: tiff, jpg, png, pdf, psd, heic, bmp. Up to 2048 MB a file; a single request carries up to 8 MB, so send anything larger in chunks. A PDF gives one id per page. A file not ordered within 72 hours is removed.

curl \
  -H "Authorization: Bearer $XYZ_KEY" \
  -F "file=@harbour-at-dusk.tif" \
  https://www.xyz-prints.com/api/v1/partner/uploads

{
  "files": [
    {
      "id": "k3Fq9w2LxP0aZt7c",
      "name": "harbour-at-dusk.tif",
      "bytes": 88213504,
      "width_px": 7200,
      "height_px": 9000,
      "dpi": 300,
      "dpi_assumed": false,
      "colour": {
        "mode": "RGB",
        "bit_depth": 16,
        "profile": true,
        "assigned": null
      },
      "expires_at": "2026-09-28T10:00:00.000Z"
    }
  ]
}

In chunks: cut the file into parts of one size (the last may be shorter) and POST each one as multipart with session (your id for the file: up to 30 letters, digits, - and _), index (from 0), total, chunk_size, size (the whole file, in bytes), name and chunk. Each part answers 202; the last answers 201 with the file.

The answer gives the picture’s pixels, the resolution it declares and its colour profile. The resolution on the print depends on the size ordered: the quote warns below 100 DPI, which the studio calls a fair print.

What can be ordered

GET /catalogue lists today’s ids for each kind of line. Below, the same list, read live.

curl \
  -H "Authorization: Bearer $XYZ_KEY" \
  https://www.xyz-prints.com/api/v1/partner/catalogue

{
  "kind": "print",
  "qty": 2,
  "paper_id": 101,
  "width_cm": 40,
  "height_cm": 50,
  "file": "upl_…",
  "fit": "fill",
  "border_cm": 2
}

{
  "kind": "product",
  "qty": 3,
  "product": "the-slug"
}

Price it

POST /quote takes the body an order takes, reference aside, and writes nothing. It answers each line’s price, the shipping options, VAT and the total, warnings about the artwork (a low resolution, a crop), and would_be: the state the order would start in under your terms today.

curl \
  -H "Authorization: Bearer $XYZ_KEY" \
  -H "Content-Type: application/json" \
  -d @order.json \
  https://www.xyz-prints.com/api/v1/partner/quote

{
  "lines": [
    {
      "kind": "print",
      "qty": 2,
      "paper_id": 101,
      "width_cm": 40,
      "height_cm": 50,
      "file": "k3Fq9w2LxP0aZt7c",
      "fit": "fill",
      "border_cm": 2
    }
  ],
  "delivery": {
    "mode": "ship"
  },
  "ship_to": {
    "first_name": "Ana",
    "last_name": "Silva",
    "address_1": "Rua das Flores 12",
    "city": "Porto",
    "postcode": "4050-262",
    "country": "PT",
    "phone": "+351 912 345 678"
  },
  "note": "Gift — no invoice in the parcel."
}

{
  "quote": {
    "currency": "EUR",
    "lines": [
      {
        "kind": "print",
        "name": "Hahnemühle Photo Rag 308",
        "qty": 2,
        "unit_price": 54.12,
        "total": 108.24,
        "vat_rate": 23,
        "details": [
          {
            "name": "File",
            "value": "harbour-at-dusk.tif"
          },
          {
            "name": "Sheet",
            "value": "40 × 50 cm"
          },
          {
            "name": "Image",
            "value": "36 × 46 cm"
          }
        ]
      }
    ],
    "warnings": [
      {
        "line": 0,
        "code": "cropped",
        "message": "fill cuts 3.2% of the picture away to cover the print; send fit to keep all of it."
      }
    ],
    "delivery": {
      "mode": "ship",
      "service": "ctt_express",
      "label": "CTT Expresso",
      "options": [
        {
          "id": "ctt_express",
          "label": "CTT Expresso",
          "price": 12.05,
          "days": [
            1,
            2
          ]
        }
      ]
    },
    "totals": {
      "goods": 108.24,
      "discount": 0,
      "shipping": 12.05,
      "vat": 22.49,
      "total": 120.29
    },
    "vat": {
      "rate": 23,
      "exempt": false,
      "reason": null,
      "number": "PT509999999",
      "status": "valid_domestic"
    },
    "would_be": {
      "state": "in_production",
      "holds": []
    }
  }
}

Place it

POST /orders needs an Idempotency-Key header: a retry with the same key answers the first result and never places a second order. Your reference is unique as well — a second order carrying it is refused and the first one comes back. Send expected_total, the total /quote gave you, and a price that changed meanwhile is refused (409 price_changed) instead of charged.

curl \
  -H "Authorization: Bearer $XYZ_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: SHOP-10482-1" \
  -d @order.json \
  https://www.xyz-prints.com/api/v1/partner/orders

{
  "reference": "SHOP-10482",
  "lines": [
    {
      "kind": "print",
      "qty": 2,
      "paper_id": 101,
      "width_cm": 40,
      "height_cm": 50,
      "file": "k3Fq9w2LxP0aZt7c",
      "fit": "fill",
      "border_cm": 2
    }
  ],
  "delivery": {
    "mode": "ship"
  },
  "ship_to": {
    "first_name": "Ana",
    "last_name": "Silva",
    "address_1": "Rua das Flores 12",
    "city": "Porto",
    "postcode": "4050-262",
    "country": "PT",
    "phone": "+351 912 345 678"
  },
  "note": "Gift — no invoice in the parcel.",
  "expected_total": 120.29
}

{
  "order": {
    "number": 6214,
    "reference": "SHOP-10482",
    "state": "in_production",
    "holds": [],
    "status": "processing",
    "created_at": "2026-09-25T10:04:11.000Z",
    "updated_at": "2026-09-25T10:04:11.000Z",
    "currency": "EUR",
    "payment": {
      "terms": "account",
      "state": "unpaid",
      "paid_at": null
    },
    "totals": {
      "goods": 108.24,
      "discount": 0,
      "shipping": 12.05,
      "vat": 22.49,
      "total": 120.29,
      "refunded": 0
    },
    "vat": {
      "rate": 23,
      "exempt": false,
      "reason": null,
      "number": "PT509999999"
    },
    "delivery": {
      "mode": "ship",
      "service": "CTT Expresso",
      "ship_to": {
        "first_name": "Ana",
        "last_name": "Silva",
        "address_1": "Rua das Flores 12",
        "city": "Porto",
        "postcode": "4050-262",
        "country": "PT",
        "phone": "+351 912 345 678"
      },
      "tracking": null
    },
    "invoice": null,
    "note": "Gift — no invoice in the parcel.",
    "lines": [
      {
        "kind": "print",
        "name": "Hahnemühle Photo Rag 308",
        "qty": 2,
        "unit_price": 54.12,
        "total": 108.24,
        "vat_rate": 23,
        "details": [
          {
            "name": "File",
            "value": "harbour-at-dusk.tif"
          },
          {
            "name": "Sheet",
            "value": "40 × 50 cm"
          },
          {
            "name": "Image",
            "value": "36 × 46 cm"
          }
        ],
        "file": "k3Fq9w2LxP0aZt7c"
      }
    ]
  },
  "warnings": [
    {
      "line": 0,
      "code": "cropped",
      "message": "fill cuts 3.2% of the picture away to cover the print; send fit to keep all of it."
    }
  ]
}

ship_to is the recipient: first_name and last_name, or company; address_1, city, postcode and country (two letters); a phone and an e-mail help the carrier. Your own company is the one invoiced — the studio keeps it on your account. delivery.service picks one of the shipping options /quote gave; without it, the first. The recipient hears nothing from the studio unless you ask for it.

Payment and acceptance

On account: an order that passes every check goes straight into production. It is invoiced to you and paid by bank transfer against the invoice; the studio records the payment.

Prepaid: the order waits for its money. payment.pay_url is its payment page (card, MB WAY, PayPal…); paid, it goes into production by itself.

A hold keeps an order out of production until the studio releases it; holds says why:

• review — Your account is set so that a person looks at every order first.
• credit_limit — This order takes what you owe on account past your credit limit.
• no_credit_limit — Your account is on credit, but no credit limit has been agreed yet — the studio sets one, then releases the order.

The state of an order

An order that is held, or still waiting for its payment, can be cancelled: POST /orders/{number}/cancel. Once it is in production, write to the studio.

Follow it

GET /orders/{number} reads one order; GET /orders?reference= finds yours by your reference. To keep your system in step without a webhook, ask GET /orders?updated_since=<the last updated_at you saw>: every order changed since, oldest change first.

curl \
  -H "Authorization: Bearer $XYZ_KEY" \
  "https://www.xyz-prints.com/api/v1/partner/orders?updated_since=2026-09-25T10:04:11.000Z"

Webhooks

Give the studio an https address and every change to your orders is POSTed there as JSON, with the order as it stands. Answer with any 2xx within 8 seconds. Each message is sent once: if you were down, GET /orders?updated_since= catches you up. Messages can arrive out of order — compare data.order.updated_at.

The studio’s “Send a test” posts the event ping, signed the same way, with no order.

{
  "id": "evt_6f1c0a9b2d3e4f5a6b7c8d9e",
  "event": "order.shipped",
  "created_at": "2026-09-27T15:31:02.000Z",
  "data": {
    "tracking": "EA123456789PT",
    "order": {
      "number": 6214,
      "reference": "SHOP-10482",
      "state": "shipped",
      "holds": [],
      "status": "processing",
      "created_at": "2026-09-25T10:04:11.000Z",
      "updated_at": "2026-09-25T10:04:11.000Z",
      "currency": "EUR",
      "payment": {
        "terms": "account",
        "state": "unpaid",
        "paid_at": null
      },
      "totals": {
        "goods": 108.24,
        "discount": 0,
        "shipping": 12.05,
        "vat": 22.49,
        "total": 120.29,
        "refunded": 0
      },
      "vat": {
        "rate": 23,
        "exempt": false,
        "reason": null,
        "number": "PT509999999"
      },
      "delivery": {
        "mode": "ship",
        "service": "CTT Expresso",
        "ship_to": {
          "first_name": "Ana",
          "last_name": "Silva",
          "address_1": "Rua das Flores 12",
          "city": "Porto",
          "postcode": "4050-262",
          "country": "PT",
          "phone": "+351 912 345 678"
        },
        "tracking": "EA123456789PT"
      },
      "invoice": null,
      "note": "Gift — no invoice in the parcel.",
      "lines": [
        {
          "kind": "print",
          "name": "Hahnemühle Photo Rag 308",
          "qty": 2,
          "unit_price": 54.12,
          "total": 108.24,
          "vat_rate": 23,
          "details": [
            {
              "name": "File",
              "value": "harbour-at-dusk.tif"
            },
            {
              "name": "Sheet",
              "value": "40 × 50 cm"
            },
            {
              "name": "Image",
              "value": "36 × 46 cm"
            }
          ],
          "file": "k3Fq9w2LxP0aZt7c"
        }
      ]
    }
  }
}

Every message is signed: X-WebOffice-Signature: t=<unix time>,v1=<HMAC-SHA256 of “t.body” under your signing secret, in hex>. Check it against the raw body, and refuse a t more than five minutes away. The studio gives you the secret and can rotate it.

import crypto from 'node:crypto'

// raw: the request body exactly as it arrived (a string, before any JSON parsing)
// header: the X-WebOffice-Signature header; secret: your signing secret (whsec_…)
export function verified(raw, header, secret) {
  const parts = Object.fromEntries(String(header).split(',').map((kv) => kv.trim().split('=')))
  const t = Number(parts.t)
  if (!Number.isInteger(t) || Math.abs(Date.now() / 1000 - t) > 300) return false
  const want = crypto.createHmac('sha256', secret).update(t + '.' + raw).digest('hex')
  const got = String(parts.v1 || '')
  return got.length === want.length && crypto.timingSafeEqual(Buffer.from(got), Buffer.from(want))
}

Errors

An error answers an HTTP status and { error: { code, message, fields } }; fields names each problem the way the body spells it (lines[0].width_cm). Codes are stable, messages are for people.

{
  "error": {
    "code": "invalid_lines",
    "message": "Hahnemühle Photo Rag 308: That size is too large for this paper — the largest print it can make is 111.8 × 1500 cm.",
    "fields": [
      {
        "field": "lines[0].width_cm",
        "code": "size_not_available",
        "message": "Hahnemühle Photo Rag 308: That size is too large for this paper — the largest print it can make is 111.8 × 1500 cm."
      }
    ]
  }
}

Per key, every ten minutes: 600 calls, 2000 lines priced (a quote or an order counts its lines) and 8192 MB of uploads. Per account: 120 orders an hour, 20 GB of files waiting for an order, and a body of up to 1024 KB. Past a limit the answer is 429 with Retry-After (507 for the files). Calls with a bad key are throttled per address.

Every call

The same, as OpenAPI 3.1 for a code generator: https://www.xyz-prints.com/api/v1/partner/openapi.json?brand=xyz-prints