Getting Started

Five steps from zero to your first fulfilled order.

1 — Get an API key

Contact us through your Pictorem account to receive your ArtFlowKey. Every request must include it as an HTTP header. Keys can optionally be issued in test mode so you can integrate without placing real orders.

2 — Explore the catalog

Call getcatalog once to pull the full tree of materials, types, orientations, sizes and options, or use buildproductlist to expand a partial code interactively.

3 — Validate and price

Build a preordercode, confirm it with validatepreorder, then fetch the cost with getprice and the production time with getleadtime.

4 — Place the order

Submit with sendorder — upload the artwork file directly, point to a public URL, or reference a Pictorem collection ID. Always send a unique po: it makes retries safe (duplicates are rejected with HTTP 409 and the existing order ID) and lets you query by your own reference later.

5 — Track it

Register a webhook to be notified on every order status and production stage change (including tracking numbers on shipment), or poll getorderstatus / getorderlist. Pre-production orders can be cancelled with cancelorder.

Validate Pre-Order

Validate a pre-order code before placing an order. The code is run through the same sanitizer used by sendorder, then compared against what you submitted: status is true only when preordercode and preordersanitize come back identical. Any difference means your code was incomplete or invalid — use data.preordersanitize as the corrected code. The optional border color is validated at the same time. Looking for the thank-you card? It is an order-level sendorder field now (thanksnotemsg / thanksnoteurl), not a code option.

Not sure how to assemble a code? Build one visually with the interactive code builder.

Body

PHP cURL

$postData = [
  'preordercode' => '2|canvas|stretched|horizontal|30|24|303-12|semigloss|mirrorimage|c15|moulding|opt',

  // Only send this when the code actually calls for it:
  // 'bordercolorhex' => 'ffffff',   // required by the bordercolor canvas wrap
];

Response (JSON)

{
  "status": true,
  "data": {
    "preordercode":     "2|canvas|stretched|horizontal|30|24|303-12|semigloss|mirrorimage|c15|moulding|opt",
    "preordersanitize": "2|canvas|stretched|horizontal|30|24|303-12|semigloss|mirrorimage|c15|moulding|opt"
  }
}

Here da9 is not a real acrylic type, so the sanitizer replaced it with the first available one and filled in the missing orientation and size. The returned code differs from the one submitted, so status is false.

{
  "status": false,
  "data": {
    "preordercode":     "1|acrylic|da9",
    "preordersanitize": "1|acrylic|ac220",
    "error": "Preorder code was modified during sanitization — use data.preordersanitize",
    "errorlist": []
  }
}

Get Price

Returns a full pricing worksheet for a product configuration, including list price, discount, artist commission, taxes (GST/PST), and total in USD. Optionally scoped to a specific collection and delivery region for accurate tax calculation. Note: the optional thank-you card is a flat per-order fee (USD 2.99, free for Premium accounts) added at sendorder time — it is never part of a preordercode price.

Body

PHP cURL

$postData = [
  'preordercode'     => '2|canvas|stretched|horizontal|30|24|303-12|semigloss|mirrorimage|c15|moulding|opt',
  'deliveryprovince' => 'QC',
  'deliverycountry'  => 'Canada',
];

Response (JSON)

All prices are in USD $ — amounts rounded to 2 decimals, tax rates to 5

{
  "status": true,
  "msg": [],
  "worksheet": {
    "enabledDiscount": true,
    "price": {
      "list": {
        "main": 20.06,
        "cert": 5
      },
      "discount": {
        "main": 6.02,
        "cert": 1.5
      },
      "artistCommission": {
        "main": 25.06
      },
      "artistCommissionDiscount": {
        "main": 7.52
      },
      "listTotal": 25.06,
      "discountTotal": 7.52,
      "artistCommissionTotal": 25.06,
      "artistCommissionDiscountTotal": 7.52,
      "subTotal": 35.08,
      "taxes": {
        "taxPercentage": 0.14975,
        "taxGST": 1.75,
        "taxPST": 3.5
      },
      "total": 40.34
    }
  }
}

Reading the worksheet. list, discount, artistCommission and artistCommissionDiscount hold one key per component of the preordercode — main is only the product itself, and every option you priced (float, semigloss, cert, moulding codes…) gets its own key. The key names are dynamic, so never read main alone: you would drop everything the order is charged for. Use the listTotal, discountTotal, artistCommissionTotal and artistCommissionDiscountTotal aggregates instead — they already sum every component.

list is the price before discount, and discount is an amount to subtract — not a rate, and not something to add back onto list. The worksheet always balances as:

subTotal = listTotal - discountTotal + artistCommissionTotal - artistCommissionDiscountTotal
total    = subTotal + taxes.taxGST + taxes.taxPST

enabledDiscount reports whether the account discount applied at all. It is false when the account is on special pricing (pro price level or product-specific pricing); in that case discount comes back empty because the list figures are already the negotiated ones.

{
  "status": false,
  "msg": {
    "error": ["PreOrder Code is NOT valid."]
  }
}

Get Lead Time

Returns the estimated production lead time (in business days) for a given product configuration. Use this before placing an order to set customer delivery expectations.

Body

PHP cURL

$postData = [
  'preordercode' => '2|canvas|stretched|horizontal|30|24|303-12|semigloss|mirrorimage|c15|moulding|opt',
];

Response (JSON)

{
  "status": true,
  "msg": [],
  "data": {
    "productionLeadTime": 8
  }
}

{
  "status": false,
  "msg": {
    "error": ["PreOrder Code is NOT valid."]
  }
}

Get Shipping Quote

Returns every UPS service available for a shipment, priced, together with a quoteid you pass back to sendorder. Use this to show shipping and collect payment before placing the order: the quoted price is the price we bill, so you never end up charging your customer a different amount than we invoice you.

Send the whole order in one call. Lines are packed together the way they will actually ship — several small prints travel in one carton — so quoting item by item and adding up the results will overcharge.

Express and air-only destinations. There is no separate express price list and no fixed air surcharge to apply: the services UPS returns are the express options, at the real rate for that address. Hawaii, Alaska and Puerto Rico are air-only, so ground does not appear in services for them and groundavailable comes back false. Pick any service in the list and send its code.

Body

PHP cURL

$postData = [
  'deliveryInfo[city]'     => 'Honolulu',
  'deliveryInfo[province]' => 'HI',
  'deliveryInfo[country]'  => 'USA',
  'deliveryInfo[cp]'       => '96815',
  'orderList[0][code]'     => '2|canvas|stretched|horizontal|30|24|semigloss|mirrorimage|c15',
  'orderList[1][code]'     => '1|acrylic|da8|horizontal|16|12',
];

Response (JSON)

{
  "status": true,
  "msg": [],
  "quoteid": "q_8f14e45fceea167a5a36dedd4bea2543",
  "expires": "2026-09-14 15:42:00",
  "cached": false,
  "services": [
    {
      "service": "02",
      "name": "UPS 2nd Day Air",
      "price": 148.72,
      "currency": "USD",
      "transitdays": 2,
      "ground": false
    },
    {
      "service": "01",
      "name": "UPS Next Day Air",
      "price": 263.19,
      "currency": "USD",
      "transitdays": 1,
      "ground": false
    }
  ],
  "groundavailable": false,
  "packages": 2
}

services is sorted cheapest first, so services[0] is a safe default. transitdays is UPS's guaranteed business days in transit where UPS guarantees the service and null where it does not — it counts from dispatch, so add the production lead time from getleadtime to get a delivery date. packages is how many cartons the order consolidates into. cached is true when the same lines to the same address were quoted in the last hour and you are getting that quote back rather than a fresh one.

{
  "status": true,
  "msg": {
    "error": ["UPS returned no rate for this destination. Verify the postal code and country, or contact us for a manual quote."]
  },
  "quoteid": null,
  "services": []
}

HTTP 200 with an empty services list: the request was valid, but UPS would not rate that address. Handle it as "shipping unavailable, contact us" rather than as an error.

{
  "status": false,
  "msg": {
    "error": [
      "deliveryInfo[cp] is required.",
      "orderList[0][code]: PreOrder Code is NOT valid."
    ]
  }
}

Using the quote on sendorder

Pass quoteid plus the service code your customer paid for. We charge the price that was quoted for that service and it lands on the order as its shipping line.

$postData = [
  'quoteid'         => 'q_8f14e45fceea167a5a36dedd4bea2543',
  'shippingservice' => '02',
  // …the rest of your sendorder fields
];

A quote is valid for 60 minutes, is good for one order, and is tied to the postal code it was priced for — shipping to a different address needs a new quote. Sending quoteid is optional: omit it and the order is created with no shipping charge, exactly as before.

Send Order

Submit a production order to Pictorem. Supports three image sources per line item: direct file upload, a public image URL, or an artwork from a Pictorem collection. Returns the Pictorem order ID on success. An optional document (waybill, shipping label, PDF…) can be attached to the order via document (file upload) or documenturl (public URL). An optional 7x5″ printed thank-you card can be added to the package via thanksnotemsg (we typeset your message) or thanksnoteurl (your own print-ready design) — one card per order, USD 2.99 flat, free for Premium accounts.

Body

PHP cURL

$postData = [
  'po'                         => 'MY-PO-2026-001',
  'deliveryInfo[firstname]'    => 'Kathleen',
  'deliveryInfo[lastname]'     => 'Bernal',
  'deliveryInfo[address1]'     => '3371 Sycamore Lake Road',
  'deliveryInfo[city]'         => 'Oshkosh',
  'deliveryInfo[province]'     => 'WI',
  'deliveryInfo[country]'      => 'USA',
  'deliveryInfo[cp]'           => '54901',
  'orderList[0][code]'         => '1|canvas|stretched|horizontal|16|12',
  'orderList[0][file]'         => new CURLFile('/path/to/file.jpg'),
  'orderList[0][bordercolorhex]' => 'ffffff',
  // Optional per-item note kept on the order line, e.g. who the print is for:
  'orderList[0][comment]'      => 'Caroline Courteau',
  // Optional 7x5" thank-you card - one per order, USD 2.99, free for Premium.
  // Use EITHER your text (we typeset it) OR your own print-ready image URL:
  'thanksnotemsg'              => 'Thank you for your purchase! We hope you enjoy your new custom print.',
  // 'thanksnoteurl'           => 'https://example.com/my-thankyou-card.jpg',
  // Optional document attachment (waybill, shipping label...) - pdf / jpg / jpeg / png
  // Use EITHER a direct upload OR a public URL, not both:
  'document'                   => new CURLFile('/path/to/waybill.pdf'),
  // 'documenturl'             => 'https://example.com/waybill-472175.pdf',
];

Response (JSON)

{
  "status": true,
  "msg": [],
  "orderid": 472175
}

failedstep names the pipeline stage that rejected the order. For code validation failures, msg.detail[] carries one entry per failing item: its orderList index, the submitted code, the code the validator expected (preordersanitize — same value validatepreorder returns) and the sanitizer error codes explaining what was changed or dropped. Internal failures (pricing, order creation, file transfer) answer HTTP 500 instead.

{
  "status": false,
  "msg": {
    "error": [
      "orderList[0]: PreOrder Code: 2|canvas|stretched|horizontal|30|24|303-12|semigloss|mirrorimage|c15|mouldin3g|opt is NOT valid."
    ],
    "detail": [
      {
        "item": 0,
        "preordercode":     "2|canvas|stretched|horizontal|30|24|303-12|semigloss|mirrorimage|c15|mouldin3g|opt",
        "preordersanitize": "2|canvas|stretched|horizontal|30|24|303-12|semigloss|mirrorimage|c15|moulding|opt",
        "processerror":     ["Error::5900::mouldin3g"]
      }
    ]
  },
  "orderid": null,
  "failedstep": "sanitizePreOrderList"
}

{
  "status": false,
  "msg": {
    "error": ["PO \"MY-PO-2026-001\" was already used on order 472174. Use a unique PO per order."]
  },
  "orderid": 472174,
  "duplicate": true
}

Get Order Status

Retrieve the full status of an existing order, including the production stage, tracking information, line items, and billing status. Query by Pictorem order ID or your own PO number. Results are always scoped to your API account.

Body

PHP cURL

// Search by Pictorem order ID
$postData = [
  'orderid' => '472174',
];

// — OR — search by your own PO number
$postData = [
  'po' => 'MY-PO-2026-001',
];

Response (JSON)

{
  "status": true,
  "msg": [],
  "order": {
    "orderid": 472174,
    "po": "MY-PO-2026-001",
    "date": "2026-03-15 10:22:00",
    "order_status": "0",
    "order_status_label": "Processing",
    "production_status": "27",
    "production_status_label": "Ready for Print",
    "production_progress": 30,
    "billing_status": "1",
    "billing_status_label": "Paid",
    "tracking_number": null,
    "tracking_carrier": null,
    "total": 125.40,
    "currency": "USD",
    "delivery": {
      "firstname": "Kathleen",
      "lastname": "Bernal",
      "company": null,
      "address1": "3371 Sycamore Lake Road",
      "address2": null,
      "city": "Oshkosh",
      "province": "WI",
      "country": "USA",
      "postal": "54901"
    },
    "lines": [
      {
        "line_id": 889421,
        "status": "27",
        "status_label": "Ready for Print",
        "is_option": false,
        "product": "canvas",
        "type": "stretched",
        "orientation": "horizontal",
        "width": "30",
        "height": "24",
        "qty": 1,
        "total": 125.40,
        "tracking": null
      }
    ]
  }
}

Two Statuses Per Order

Pictorem tracks an order's progress on two separate axes and this endpoint returns both. Reading only one of them is the single most common integration mistake, so it is worth being explicit:

Order Status Codes

Values order_status takes. Labels below are read live from our status table, so they match order_status_label exactly.

Production Stage Codes

The stages you will see most often on production_status and lines[].status, in production order. The full pipeline has dozens more internal steps — treat any other code as "in production" and display production_status_label rather than mapping codes yourself.

{
  "status": false,
  "msg": {
    "error": ["Order not found."]
  }
}

Get Order List

Paginated list of all your orders, newest first, each with the same order status and production stage pair as getorderstatus. Optionally filter by order status or date range. Results are always scoped to your API account.

Body

PHP cURL

$postData = [
  'page'   => '1',
  'limit'  => '25',
  'status' => '2', // Shipped only
];

Response (JSON)

{
  "status": true,
  "msg": [],
  "data": {
    "total": 63,
    "page": 1,
    "limit": 25,
    "pages": 3,
    "orders": [
      {
        "orderid": 472174,
        "po": "MY-PO-2026-001",
        "date": "2026-03-15 10:22:00",
        "order_status": "2",
        "order_status_label": "Shipped",
        "production_status": "2",
        "production_status_label": "Shipped",
        "production_progress": 100,
        "billing_status": "1",
        "billing_status_label": "Paid",
        "tracking_number": "1Z999AA10123456784",
        "tracking_carrier": "UPS",
        "total": 125.40,
        "currency": "USD"
      }
    ]
  }
}

Cancel Order

Cancel an order before it enters production. Only orders in QUOTE - Waiting payment (9), Processing (0) or Action required (11) can be cancelled through the API — once production has started, contact support instead.

Body

PHP cURL

$postData = [
  'orderid' => '472174',
];

Response (JSON)

{
  "status": true,
  "msg": [],
  "order": {
    "orderid": 472174,
    "order_status": "3",
    "order_status_label": "Canceled"
  }
}

{
  "status": false,
  "msg": {
    "error": ["Order 472174 is already in production and can no longer be cancelled via the API. Please contact support."]
  }
}

Build Product List

Expands a partial pre-order code into the full set of valid product configurations available for that base selection. Unlike validatepreorder, a partial code is expected here — send as little as 1|canvas and you get back every choice that is still open, already filtered by the compatibility rules. Call it again after each selection to drive a step-by-step product picker.

The interactive code builder is this endpoint wired to a UI — a working reference for your own picker.

Note that each group of type one gets its first choice applied automatically, so preordersanitize normally comes back longer than what you sent. Whenever it differs from preordercode the response also carries data.error — on this endpoint that is a "your code was normalized" flag, not a failure. status is always true here; use validatepreorder when you need a strict yes/no.

Body

PHP cURL

$postData = [
  'preordercode' => '1|acrylic',
];

Response (JSON)

Only the groups that can still be resolved are returned. Here no orientation was given yet, so size and additional are absent — they appear once the code is complete enough.

{
  "status": true,
  "data": {
    "preordercode":     "1|acrylic",
    "preordersanitize": "1|acrylic|ac220",
    "products": {
      "material": {
        "title": "Material",
        "choices": [
          { "id": "canvas",  "title": "canvas" },
          { "id": "acrylic", "title": "acrylic" }
        ]
      },
      "type": {
        "title": "Type",
        "choices": [
          { "id": "ac220", "title": "acrylic print 1/4 ( 0.220 )" },
          { "id": "da8",   "title": "acrylic print 1/8" }
        ]
      },
      "shape": {
        "title": "Shape",
        "choices": [
          { "id": "vertical",   "title": "vertical" },
          { "id": "horizontal", "title": "horizontal" },
          { "id": "square",     "title": "square" }
        ]
      }
    },
    "error": "Errors Everywhere"
  }
}

Response — complete code

Once numCopies, material, type, orientation, width and height are all present, the size and additional groups are included too. Each additional group carries a choicetype: one (pick exactly one), multi (pick any number) or text (a free-text value sent as its own form field, such as bordercolorhex). Frames too large for the requested size come back flagged with isDisabled.

{
  "status": true,
  "data": {
    "preordercode":     "1|canvas|stretched|horizontal|30|24",
    "preordersanitize": "1|canvas|stretched|horizontal|30|24|boxclassic|c15|imagewrap|none|regular",
    "products": {
      "material": { "title": "Material", "choices": [ ... ] },
      "type":     { "title": "Type",     "choices": [ ... ] },
      "shape":    { "title": "Shape",    "choices": [ ... ] },
      "size": {
        "title": "Size",
        "choices": [
          { "width": "30", "height": "24" },
          { "width": "36", "height": "24" }
        ]
      },
      "additional": {
        "title": "Additional",
        "choices": [
          {
            "id": "packaging",
            "title": "Packaging",
            "choicetype": "one",
            "choices": [
              { "id": "boxclassic", "title": "Classic Boxes 2 Ply" },
              { "id": "cra",        "title": "Wooden Crate Packaging On A Pallet" }
            ]
          },
          {
            "id": "frames",
            "title": "decorative moulding",
            "choicetype": "one",
            "choices": [
              { "id": "303-12", "title": "303-12 natural wood floating frame" },
              { "id": "360-29", "title": "360-29 black floating frame", "isDisabled": true }
            ]
          }
        ]
      }
    },
    "error": "Errors Everywhere"
  }
}

An unrecognised segment is not rejected — it is replaced with the first valid value for that position. Here da9 is not a real acrylic type, so it became ac220. Always read preordersanitize back rather than assuming your input survived.

{
  "status": true,
  "data": {
    "preordercode":     "1|acrylic|da9",
    "preordersanitize": "1|acrylic|ac220",
    "products": { ... },
    "error": "Errors Everywhere"
  }
}

Get Catalog

Returns the complete product configuration tree as structured JSON — every material, type, orientation, size, additional option and frame, including compatibility requirements. This is the same source data the validator uses, so you can build product pickers programmatically instead of hardcoding values from the field reference. Cache it: the catalog changes rarely.

Body

No parameters — just the ArtFlowKey header.

PHP cURL

$ch = curl_init('https://www.pictorem.com/artflow/0.1/getcatalog/');
curl_setopt($ch, CURLOPT_POST, true);
curl_setopt($ch, CURLOPT_POSTFIELDS, ['fetch' => '1']);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_HTTPHEADER, ['ArtFlowKey: YOUR_API_KEY']);
$catalog = json_decode(curl_exec($ch), true);
curl_close($ch);

Response (JSON)

{
  "status": true,
  "msg": [],
  "data": {
    "preordercodeFormat": "numCopies|material|type|orientation|width|height|additional|additional…",
    "products":     { "material": { "canvas": { ... }, "acrylic": { ... }, ... } },
    "orientations": { "shapes": { "choices": { "vertical": { ... }, "horizontal": { ... }, "square": { "requirements": [...] } } } },
    "sizes":        { ... },
    "additionals":  { "packaging": { "title": "Packaging", "choices": { ... } }, ... },
    "frames":       { "moulding": { "title": "Decorative Moulding", "choices": { "303-12": { "title": "303-12 Natural Wood Floating Frame" }, ... } } }
  }
}

Get Artist Artwork Listing

Returns a paginated list of your own artworks — name, keywords, categories, description, orientation, stats and a ready-to-use image set. Generated print renders (acrylic, metal, wood, murals, canvas, framed, puzzle…) are available on request through previews.

Every URL returned is verified to resolve before it is sent. An image that has not been generated is omitted rather than returned as a dead link, so you can hand any URL from this response straight to a downstream importer. Absence of a key means "not generated", never "broken".

Body

Image Set — always returned

Print Renders — previews values

Pass any combination as a comma-separated list. Each key that resolves comes back as a single URL; keys whose render does not exist are left out of the previews object.

Code Example

$ch = curl_init('https://www.pictorem.com/artflow/0.1/getartworklist/');
curl_setopt($ch, CURLOPT_POST, true);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_HTTPHEADER, ['ArtFlowKey: YOUR_API_KEY']);
curl_setopt($ch, CURLOPT_POSTFIELDS, [
  'page'     => '1',
  'limit'    => '24',
  'sort'     => 'newest',
  // Optional: ask for specific print renders (omit for metadata + image only)
  'previews' => 'wallpreview,book,acr1',
  // Optional: include what you earn per artwork
  'pricing'  => '1',
]);
$response = curl_exec($ch);
curl_close($ch);
$data = json_decode($response, true);

const body = new FormData();
body.append('page',     '1');
body.append('limit',    '24');
body.append('sort',     'newest');
body.append('previews', 'wallpreview,book,acr1');
body.append('pricing',  '1');

fetch('https://www.pictorem.com/artflow/0.1/getartworklist/', {
  method:  'POST',
  headers: { 'ArtFlowKey': 'YOUR_API_KEY' },
  body:    body,
})
  .then(r => r.json())
  .then(data => console.log(data));

Response (JSON)

{
  "status": true,
  "msg": [],
  "data": {
    "total": 147,
    "page": 1,
    "limit": 24,
    "pages": 7,
    "artworks": [
      {
        "id": 2452666,
        "name": "Mona Lisa",
        "author": "Stock Photography",
        "keywords": ["classical", "portrait", "renaissance"],
        "description": "...",
        "categories": [
          { "id": 12, "name": "Classical Portraits" }
        ],
        "url": "https://www.pictorem.com/2452666/Mona-Lisa.html",
        "orientation": "vertical",
        "ratio": 0.6693,
        "image": {
          "thumb":   "https://www.pictorem.com/uploads/collection/A/ABC123/small_2452666.jpg",
          "preview": "https://s3.pictorem.com/images/collection/A/ABC123/rand_2452666.webp",
          "full":    "https://www.pictorem.com/uploads/collection/A/ABC123/big_2452666.jpg",
          "source":  "https://www.pictorem.com/uploads/collection/A/ABC123/2452666.jpg"
        },
        "stats": { "rating": 4.5, "nbRating": 12, "views": 340 },
        "createdAt": "2024-01-15 10:22:00",
        "previews": {
          "wallpreview": "https://s3.pictorem.com/images/collection/A/ABC123/rand_2452666.webp",
          "book":        "https://s3.pictorem.com/images/collection/A/ABC123/book_2452666.jpg"
        },
        "commission": { "strategy": "percentage", "value": 30, "source": "collection" }
      }
    ]
  }
}

previews is present only when the previews parameter was sent, and commission only when pricing=1 was sent. In the example above acr1 was requested but no acrylic render exists for this artwork, so the key is absent rather than pointing at a 404.

commission.strategy is one of percentage, sqft, dynamic or fixed — whichever is set takes effect, checked in that order. source tells you whether the value comes from the artwork itself (collection) or from your account default (account). A strategy of null means no commission is configured.

{
  "status": false,
  "msg": {
    "error": ["userid must be your own account (ABC123). This endpoint only lists artwork belonging to the API key used."]
  }
}

{
  "status": false,
  "msg": {
    "error": [
      "Unknown previews value(s): book2, splitPanels.",
      "Valid values: acr1, acr1small, acr2, ... , wallpreview, wallsmall."
    ]
  }
}

{
  "status": false,
  "error": "Access Denied"
}

System Health Check

Lightweight ping to verify that the ArtFlow API is reachable and that your ArtFlowKey is recognized. Intended for uptime monitors and pre-flight checks before heavier calls like sendorder. Does not count toward the rate limit and is not logged in API request reports.

Body

Empty multipart/form-data — no fields. Authentication is via the ArtFlowKey header only.

Response fields

PHP cURL

$ch = curl_init('https://www.pictorem.com/artflow/0.1/shc/');
curl_setopt($ch, CURLOPT_POST, true);
curl_setopt($ch, CURLOPT_POSTFIELDS, []);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_HTTPHEADER, ['ArtFlowKey: YOUR_API_KEY']);
$health = json_decode(curl_exec($ch), true);
curl_close($ch);

Response (JSON)

{
  "status": true,
  "artFlowKey": true
}

{
  "status": true,
  "artFlowKey": false
}

{
  "status": false,
  "artFlowKey": false
}

When status is false (maintenance mode), artFlowKey is not checked and is always false. Unlike other endpoints, an invalid key does not return HTTP 401 — check artFlowKey in the JSON body instead (only meaningful when status is true). Non-POST requests return HTTP 405 with {"status": false, "artFlowKey": false}.

Webhooks — Overview

Instead of polling getorderstatus, register a callback URL and Pictorem will POST a JSON payload to your server whenever one of your ArtFlow orders changes status — including every production stage such as Ready for Print, and the tracking number the moment an order ships. Only orders placed after the webhook was registered generate notifications.

What triggers a delivery

A delivery is queued whenever order_status or production_status moves — the same two fields getorderstatus returns. The changed array tells you which of the two it was, so you can ignore production noise and react only to commercial changes if that is all you need.

Changes are detected on a schedule rather than the instant a status is written, so expect a delay of a few minutes. If an order moves through two stages inside the same window, you receive a delivery for each one, in order.

Delivery, retries & signature

Each delivery is an HTTPS POST with Content-Type: application/json and four headers: X-ArtFlow-Event (the event name), X-ArtFlow-Delivery (a unique ID for this change, stable across retries), X-ArtFlow-Attempt (1 on the first try) and X-ArtFlow-Signature — an HMAC-SHA256 hex digest of the raw request body, signed with your API key. Always verify the signature before trusting a payload.

Respond with any 2xx status within 10 seconds. Anything else — a 5xx, a timeout, an unreachable host — is retried with a growing delay of roughly 10, 30, 60, 180 and 480 minutes, so your endpoint can be down for about half a day without you losing a status change. Deliveries for the same order are always attempted in order: a failing one holds the rest of that order's queue until it succeeds or runs out of attempts.

A retry re-sends the change that was detected, not the order's current state, and reuses the same X-ArtFlow-Delivery ID. Because a slow acknowledgement can be retried after we already recorded a failure, treat that ID as an idempotency key.

Payload

{
  "event": "order.status_changed",
  "orderid": 472174,
  "po": "MY-PO-2026-001",
  "changed": ["production_status"],
  "order_status": "0",
  "order_status_label": "Processing",
  "previous_order_status": "0",
  "production_status": "27",
  "production_status_label": "Ready for Print",
  "production_progress": 30,
  "previous_production_status": "20",
  "tracking_number": null,
  "tracking_carrier": null,
  "queued_at": "2026-07-15T10:28:00-04:00",
  "delivery_id": 91233,
  "attempt": 1,
  "sent_at": "2026-07-15T10:30:00-04:00"
}

previous_status is still present as an alias of previous_order_status for integrations written against the original payload. It will be removed in a future version — read previous_order_status instead.

Verifying the signature (PHP)

$rawBody   = file_get_contents('php://input');
$signature = $_SERVER['HTTP_X_ARTFLOW_SIGNATURE'] ?? '';
$expected  = hash_hmac('sha256', $rawBody, 'YOUR_API_KEY');

if (!hash_equals($expected, $signature)) {
  http_response_code(401);
  exit;
}

$payload = json_decode($rawBody, true);
// handle $payload['event'] ...

Register Webhook

Subscribe a callback URL to an event. Re-registering the same URL + event re-activates it.

Body

Response (JSON)

{
  "status": true,
  "msg": [],
  "webhook": {
    "webhookid": 12,
    "url": "https://your-app.com/webhooks/pictorem",
    "event": "order.status_changed",
    "active": true
  }
}

List Webhooks

Returns every webhook registered on your account, active and inactive.

Body

No parameters — just the ArtFlowKey header.

Response (JSON)

{
  "status": true,
  "msg": [],
  "webhooks": [
    {
      "webhookid": 12,
      "url": "https://your-app.com/webhooks/pictorem",
      "event": "order.status_changed",
      "active": true,
      "createdAt": "2026-07-15 10:22:00"
    }
  ]
}

Delete Webhook

Deactivates a webhook. Delivery history is preserved; re-register the same URL to re-activate it.

Body

Response (JSON)

{
  "status": true,
  "msg": [],
  "webhook": {
    "webhookid": 12,
    "active": false
  }
}

Authentication Header

Every request must include your ArtFlow API key as an HTTP header.

Required Header

Errors & HTTP Status Codes

Every response carries a boolean status field. Failures also return a meaningful HTTP status code, with human-readable messages in msg.error[].

Status Codes

Error Body

{
  "status": false,
  "msg": {
    "error": [
      "deliveryInfo[address1] is required.",
      "orderList[0] needs an image source: file, fileurl or collectionID."
    ]
  }
}

sendorder failures may additionally include failedstep (the pipeline stage that rejected the order) and msg.detail[] with a per-item diagnosis — the failing orderList index, the submitted and expected codes, and the sanitizer error codes. See the sendorder fail example.

Rate Limits

Each API key may make up to 120 requests per minute. Beyond that, requests are rejected with HTTP 429 until the window rolls over. If you need a higher limit for a launch or batch import, contact us. To stay well under the limit: cache getcatalog, batch order lines into a single sendorder call, and prefer webhooks over polling.

429 Response

{
  "status": false,
  "error": "Rate limit exceeded — max 120 requests per minute.",
  "msg": {
    "error": ["Rate limit exceeded — max 120 requests per minute."]
  }
}

Sandbox / Test Mode

Test your integration end-to-end without creating real orders. In test mode, sendorder runs the full validation pipeline (delivery fields, image sources, preorder codes) but no order is created, no file is stored, no card is charged and no email is sent. All read endpoints (getprice, validatepreorder, getcatalog…) behave normally.

Two Ways to Enable It

Test Mode Response

{
  "status": true,
  "msg": [],
  "orderid": null,
  "testmode": true
}

PHP cURL — Full Example

Complete authenticated request with file upload.

Example

$url       = 'https://www.pictorem.com/artflow/0.1/sendorder/';
$apiKey    = 'YOUR_API_KEY';

$postData = [
  'deliveryInfo[firstname]'    => 'Kathleen',
  'deliveryInfo[lastname]'     => 'Bernal',
  'deliveryInfo[address1]'     => '3371 Sycamore Lake Road',
  'deliveryInfo[city]'         => 'Oshkosh',
  'deliveryInfo[province]'     => 'WI',
  'deliveryInfo[country]'      => 'USA',
  'deliveryInfo[cp]'           => '54901',
  'orderList[0][code]'         => '1|canvas|stretched|horizontal|16|12',
  'orderList[0][file]'         => new CURLFile('/path/to/file.jpg'),
  'orderList[0][bordercolorhex]' => 'ffffff',
  'thanksnotemsg'              => 'Thank you for your order!', // optional 7x5" card, one per order
];

$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, $url);
curl_setopt($ch, CURLOPT_POST, true);
curl_setopt($ch, CURLOPT_POSTFIELDS, $postData);
curl_setopt($ch, CURLOPT_HTTPHEADER, [
  'ArtFlowKey: ' . $apiKey,
]);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);

$response = curl_exec($ch);

if ($response === false) {
  echo 'cURL Error: ' . curl_error($ch);
} else {
  $data = json_decode($response, true);
  var_dump($data);
}

curl_close($ch);

JavaScript Fetch — Full Example

Complete authenticated request using the Fetch API with FormData.

Example

const apiKey   = 'YOUR_API_KEY';
const endpoint = 'https://www.pictorem.com/artflow/0.1/sendorder/';

const formData = new FormData();
formData.append('deliveryInfo[firstname]',    'Kathleen');
formData.append('deliveryInfo[lastname]',     'Bernal');
formData.append('deliveryInfo[address1]',     '3371 Sycamore Lake Road');
formData.append('deliveryInfo[city]',         'Oshkosh');
formData.append('deliveryInfo[province]',     'WI');
formData.append('deliveryInfo[country]',      'USA');
formData.append('deliveryInfo[cp]',           '54901');
formData.append('orderList[0][code]',         '1|canvas|stretched|horizontal|16|12');
formData.append('orderList[0][fileurl]',      'https://images.unsplash.com/photo-xxxx');
formData.append('orderList[0][filetype]',     'jpg');
formData.append('orderList[0][bordercolorhex]', 'ffffff');
formData.append('thanksnotemsg', 'Thank you for your order!'); // optional 7x5" card, one per order

fetch(endpoint, {
  method:  'POST',
  headers: { 'ArtFlowKey': apiKey },
  body:    formData,
})
  .then(response => {
    if (!response.ok) {
      throw new Error('HTTP error: ' + response.status);
    }
    return response.json();
  })
  .then(data  => console.log('Order placed:', data))
  .catch(error => console.error('Error:', error));

OpenAPI Specification

The full API is described in a machine-readable OpenAPI 3.0 document. Import it into Postman or Insomnia for a ready-made collection, generate typed client SDKs with openapi-generator, or feed it to AI coding assistants for accurate integrations.

Spec URL

https://www.pictorem.com/artflow/0.1/openapi/

Changelog & Versioning

The API version is part of every URL (/artflow/0.1/…). Within a version we only make additive changes — new endpoints, new optional fields, new response keys. Breaking changes ship as a new version, and previous versions keep working for at least 6 months after a replacement is announced on this page.

Changelog

PreOrder Code — Field Reference

The preordercode is a pipe-delimited string: numCopies|material|type|orientation|width|height|additional|additional…. Expand each section below to see the accepted values.

¹ Requires a specific material  |  ² Requires a specific option

Product Codes

Every valid material|type combination. Use these two values as the second and third segments of your preordercode.

Option Codes

All valid values for the additional segments of the preordercode. ¹ Requires a specific material  |  ² Requires a specific prior additional  |  ³ Only available on some sizes or some frame models — buildproductlist marks it isDisabled when it cannot be used.

Frame Models

All valid frame codes for the additional (frames) segment. Decorative Moulding requires moulding in additionals. Picture Frame requires frame in additionals.