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

{
  "imageReference": "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, so there is no need to track which images you have already uploaded.

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 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.