API

Print orders

Send Yuzu orders to print.

Print orders

Send one or more Yuzu orders to print.

POST https://app.yuzu.so/api/orders/print

Headers

Content-Type: application/json
X-API-Key: YOUR_API_KEY

Query parameters

Parameter	Type	Description
`strict`	boolean	Optional. Defaults to `false`. When `true`, missing, ignored, or incomplete orders make the whole request fail with `400`.

Request body

Pass either orderIds or orderFilters, not both.

Field	Type	Description
`orderIds`	array	Yuzu order IDs or order keys to print.
`orderFilters`	object	Filter object to select orders dynamically.
`excludeIds`	array	Order IDs to exclude when using `orderFilters`.
`name`	string	Optional print batch name.
`ref`	string	Optional external reference.
`filters`	object	Optional document filter. Supports `document.tag`, `document.templateId`, `document.templateOverrideId`, and `order.tags`.
`overrides`	object or array	Optional printer, template, and tray overrides. Array entries can include `filters` for document-specific overrides.
`force`	boolean	Optional. Defaults to `false`.
`sortBy`	string	Optional. `orderDate`, `orderNumber`, `updatedAt`, `firstName`, or `sku`.
`sortDir`	string	Optional. `asc` or `desc`.

Print one order

Use the single-order endpoint when you are printing one known order.

POST https://app.yuzu.so/api/orders/{orderIdOrKey}/print

orderIdOrKey can be the Yuzu order UUID or any order key returned on the order. If you use an order key in the URL path, URL-encode it first because keys can contain /, :, and other path-sensitive characters.

curl --request POST 'https://app.yuzu.so/api/orders/a2cb2c3d-4e5f-6g7h-8i9j-123a45c67890/print' \
  --header 'Content-Type: application/json' \
  --header 'X-API-Key: YOUR_API_KEY' \
  --data '{
    "overrides": {
      "printer": "printer_id_here"
    }
  }'

The body is optional. Pass overrides when you need to route the print to a specific printer, template, or tray. Use GET /api/printers to find printer IDs.

Print multiple orders

Use the batch endpoint when you need to print multiple orders or select orders by filter. orderIds accepts Yuzu order UUIDs and order keys. See Order keys for how keys are created.

curl --request POST 'https://app.yuzu.so/api/orders/print' \
  --header 'Content-Type: application/json' \
  --header 'X-API-Key: YOUR_API_KEY' \
  --data '{
    "orderIds": [
      "a2cb2c3d-4e5f-6g7h-8i9j-123a45c67890",
      "org_exampleTeam123456789/warehouse-east-WE-1001"
    ],
    "name": "Morning batch",
    "overrides": {
      "printer": "printer_id_here"
    }
  }'

When you send an order key in the JSON body, send it exactly as returned by Yuzu. You do not need to URL-encode it unless the key is part of a URL path.

Print by filters

curl --request POST 'https://app.yuzu.so/api/orders/print?strict=true' \
  --header 'Content-Type: application/json' \
  --header 'X-API-Key: YOUR_API_KEY' \
  --data '{
    "orderFilters": {
      "order.status": "ready",
      "order.tags": ["VIP"]
    },
    "filters": {
      "document.tag": "packing_slip"
    },
    "overrides": [
      {
        "filters": { "document.tag": "packing_slip" },
        "templateId": "template_id_here",
        "printer": "printer_id_here",
        "tray": "Tray 1"
      }
    ],
    "sortBy": "orderDate",
    "sortDir": "asc"
  }'

Response statuses

Successful HTTP responses return an array of print batch results. Inspect each item.

Pending

pending means Yuzu created print jobs for complete documents.

[
  {
    "id": "print_batch_id_here",
    "name": "Morning batch",
    "status": "pending",
    "team": {
      "authId": "org_exampleTeam123456789"
    },
    "printer": {
      "id": "printer_id_here",
      "name": "Warehouse printer"
    },
    "orders": [
      {
        "id": "a2cb2c3d-4e5f-6g7h-8i9j-123a45c67890",
        "orderKeys": ["org_exampleTeam123456789/warehouse-east-WE-1001"]
      }
    ],
    "createdAt": "2026-05-19T12:05:00.000Z",
    "updatedAt": "2026-05-19T12:05:00.000Z"
  }
]

Warning

warning means some requested orders were ignored. Non-strict requests can still print other complete orders.

[
  {
    "id": "ignored-orders",
    "name": "1 Orders Ignored",
    "status": "warning",
    "team": {
      "authId": "org_exampleTeam123456789"
    },
    "orders": [
      {
        "id": "ignored_order_id",
        "orderKeys": ["org_exampleTeam123456789/warehouse-east-WE-1002"]
      }
    ],
    "createdAt": "2026-05-19T12:05:00.000Z",
    "updatedAt": "2026-05-19T12:05:00.000Z"
  }
]

Error

error means a requested order was missing or a document could not resolve a required template, printer, paper size, or print config. With strict=true, Yuzu returns HTTP 400 and the same error details in the response body.

[
  {
    "id": "missing-orders",
    "name": "1 Orders Not Found",
    "status": "error",
    "team": {
      "authId": "org_exampleTeam123456789"
    },
    "orders": [
      {
        "id": "unknown-order-key",
        "orderKeys": ["unknown-order-key"]
      }
    ],
    "createdAt": "2026-05-19T12:05:00.000Z",
    "updatedAt": "2026-05-19T12:05:00.000Z"
  }
]

Common status codes:

Status	Meaning
`200`	Request processed. Check each batch `status`.
`400`	Invalid request body, both `orderIds` and `orderFilters` were provided, or strict mode failed.
`401`	Missing, malformed, or invalid API key.
`403`	API key cannot access the requested team resource.
`5xx`	Temporary service issue. Retry with backoff.

Fetch printers

Fetch Yuzu printers for print routing and overrides.

Fetch order PDF

Download the rendered PDF for a Yuzu order.