Creating Orders

Learn how to create orders through the API, including image uploads, shipping options, and address handling.

Overview

Creating an order is a two-step process: upload print images, then place the order. The flow looks like this:

                Upload print image (JPEG/PNG)
                        POST /images
                             │
         Browse catalog      │
         GET /products       │
                 │           │
                 ▼           ▼
           Product_xxx + Image_xxx + quantity
                   POST /orders
                         │
                         ▼
                    Order_xxx
                         │
            ┌────────────┴────────────┐
            ▼                         ▼
       "dropship"                "combined"
   Ships to customer         Ships to your location

Images

Print products require a print image. Upload each image as a POST /images request with the raw image bytes in the body.

curl -X POST https://api.printeers.com/v2/images \
  -H "X-Printeers-Secret-Key: $KEY" \
  -H "Content-Type: application/octet-stream" \
  --data-binary @design.png

{
  "image": {
    "reference": "Image_pdcptbw3k48sv03wy338bb8jzm"
  }
}

Accepted formats are JPEG and PNG. Images larger than 7000x7000 pixels are automatically downsized. Uploading the same image twice returns the same reference. Image uploads count against the uploads rate-limit bucket; see the Rate Limiting guide.

Orderlines with non-print products (e.g. a screenprotector) must not have an image reference.

Shipping Kinds

Every order has a shipping kind that determines where the package is sent.

Dropship orders ship directly to your customer. You provide the destination address and can optionally set a minimal shipping level and preferred packaging.

Combined orders are consolidated with other orders and shipped to your business address. No address or shipping options are needed; they use the combined address configured on your store.

Creating an Order

Dropship

curl -X POST https://api.printeers.com/v2/orders \
  -H "X-Printeers-Secret-Key: $KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "order": {
      "storeReference": "Store_9jmn3dewwvy13rv12k7aannqzy",
      "shippingKind": "dropship",
      "customIdentifier": "my-order-123",
      "dropshipAddress": {
        "company": "",
        "firstname": "John",
        "lastname": "Doe",
        "streetname": "Koelmalaan",
        "housenumber": "330",
        "housenumberAddition": "",
        "additionalInfo": "",
        "state": "",
        "zipcode": "1432 PV",
        "city": "Aalsmeer",
        "countryCode": "NL",
        "phonenumber": "+31612345678",
        "email": "john@example.com"
      },
      "dropshipMinimalShippingLevel": "tracked",
      "orderlines": [
        {
          "productReference": "Product_4j8k2m5n7p9q1r3s6t8v0w2x4y",
          "imageReference": "Image_pdcptbw3k48sv03wy338bb8jzm",
          "quantity": 1
        }
      ]
    }
  }'

{
  "order": {
    "reference": "Order_5jcavdegg8n9pvgxq887jq0zbc"
  }
}

Combined

curl -X POST https://api.printeers.com/v2/orders \
  -H "X-Printeers-Secret-Key: $KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "order": {
      "storeReference": "Store_9jmn3dewwvy13rv12k7aannqzy",
      "shippingKind": "combined",
      "orderlines": [
        {
          "productReference": "Product_4j8k2m5n7p9q1r3s6t8v0w2x4y",
          "imageReference": "Image_pdcptbw3k48sv03wy338bb8jzm",
          "quantity": 5
        }
      ]
    }
  }'

{
  "order": {
    "reference": "Order_j2rznt7qr6ra78zb0aq2hsp3fd"
  }
}

When order creation fails, the response includes an error code and a human-readable message:

{
  "code": "missing_address",
  "message": "Dropship address is required for dropship orders"
}

Common errors include missing_address (dropship order without a destination address) and missing_image_reference (print product without an uploaded image). For the full list of request fields and error codes, see the Orders API Reference.

Canceling Orderlines

As long as an order is not in production, you can cancel (part of) the quantity of its orderlines with POST /orders/{orderReference}/cancel.

The endpoint uses absolute totals: for every orderline you list, canceledQuantity is the desired total canceled quantity of that line, exactly as returned by GET /orders/{orderReference}. It is not the amount to cancel on top of the current value. Orderlines you do not list keep their current canceled quantity.

A typical flow is to fetch the order first and then submit the new totals:

curl https://api.printeers.com/v2/orders/Order_5jcavdegg8n9pvgxq887jq0zbc \
  -H "X-Printeers-Secret-Key: $KEY"

Response:

{
  "order": {
    …
    "orderlines": [
      { "index": 1, "quantity": 5, "canceledQuantity": 0, "shippedQuantity": 0, … },
      { "index": 2, "quantity": 2, "canceledQuantity": 0, "shippedQuantity": 0, … }
    ]
  }
}

To cancel 3 pieces of the first line and the complete second line:

curl -X POST https://api.printeers.com/v2/orders/Order_5jcavdegg8n9pvgxq887jq0zbc/cancel \
  -H "X-Printeers-Secret-Key: $KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "orderlines": [
      { "index": 1, "canceledQuantity": 3 },
      { "index": 2, "canceledQuantity": 2 }
    ]
  }'

A successful request returns 204 No Content. Because the request describes the desired end state, sending the same request again also returns 204 without canceling anything further. This makes retries after a timeout safe.

The request is atomic: when any listed orderline fails validation, nothing is canceled.

Canceling cannot be undone. If you send a canceledQuantity below the current canceled quantity of a line, the request is rejected with 409 canceled_quantity_below_current. This usually means the order changed since you last fetched it, for example because our support team canceled quantity on your behalf. Fetch the order again to see the current state.

Other things to know:

• Once a quantity has been shipped it can no longer be canceled. The canceled quantity is limited to quantity - shippedQuantity per line (409 canceled_quantity_exceeds_shippable).
• Orders that are in production cannot be canceled (409 already_in_production).
• Orders in stores backed by an upstream platform such as Shopify or WooCommerce must be canceled in that platform instead (403 store_not_writable_via_api).

For the full list of error codes, see the Orders API Reference.

Typical Integration

A typical order creation flow follows these steps:

1. Browse the catalog: call GET /products to find available products and their references.
2. Upload images: send each print image to POST /images and store the returned references.
3. Create the order: call POST /orders with the product references, image references, quantities, and shipping details.
4. Track the order: use GET /orders/{orderReference} to check order status and retrieve shipment references.
5. Track shipments: once shipped, use GET /shipments/{shipmentReference} for tracking information. See the Shipments and Tracking guide.