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.

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.