Print-on-Demand API

Send orders to Ready2HangArt for production (print & frame) and fulfillment, and receive automatic status & tracking updates back. Built for integration partners such as Order Desk. This API implements Order Desk's POD Integration Specification v1.0.

Connection type: Custom API — REST over HTTPS, JSON request/response
Base URL: https://portal.ready2hangart.com
Authentication: API token in the X-AUTH-TOKEN request header
Format: Content-Type: application/json on all requests with a body
Role: Ready2HangArt acts as the print provider / order receiver
Shipping scope: United States addresses only at this time

Not EDI, SOAP or XML. This is a standard REST/JSON HTTPS API with token authentication. Each integration partner is issued a unique token by Ready2HangArt. Use of this API, and any account or token issued under it, is subject to the Ready2HangArt Terms of Service.

How the connection works

This API implements Order Desk's POD Integration Specification v1.0. Ready2HangArt hosts the endpoints and acts as the print provider / order receiver; Order Desk is the caller. The whole exchange is standard REST over HTTPS with a token in a request header — no EDI, SOAP, OAuth, IP allow-listing or dedicated connector required.

Order Desk → Ready2HangArt (orders). Order Desk sends each order to POST /api/pod/order at the base URL above, including the X-AUTH-TOKEN header we issue you. We reply with a Ready2HangArt fulfillmentId.
Ready2HangArt → Order Desk (status & tracking). As the order moves into production and ships, we POST status and tracking updates to the webhookUrl you include on the order. Order Desk can also poll GET /api/pod/order/{fulfillmentId} at any time.
Validate first. Call GET /api/pod/authentication-test to confirm the token works before sending live orders.

Direction: orders flow Order Desk → Ready2HangArt; status & tracking flow Ready2HangArt → Order Desk. Every request is authenticated with the X-AUTH-TOKEN we issue — the same token for all four endpoints below.

Authentication

Every request must include the API token issued to your account in the X-AUTH-TOKEN header. Requests without a valid token return 401.

X-AUTH-TOKEN: pod_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

Invalid or missing credentials:

{
  "success": false,
  "errors": [{ "errorCode": 1001, "message": "Invalid credentials" }],
  "errorMessage": "Invalid credentials"
}

Treat your X-AUTH-TOKEN like a password. Do not embed it in client-side code, public repositories, or any location a third party could read. If you believe a token has been exposed or compromised, contact info@ready2hangart.com immediately so we can issue a replacement.

1. Test connection

GET/api/pod/authentication-test

Verifies that your token is valid. Use this to confirm connectivity during setup.

Response `200`

{ "success": true }

2. Submit an order

POST/api/pod/order

Creates a new fulfillment order. Returns the Ready2HangArt fulfillmentId you use to track or cancel the order.

Request body

{
  "orderId": "12345",
  "poNumber": "PO-12345",
  "webhookUrl": "https://your-system.example.com/webhooks/r2h",
  "packingSlipUrl": "https://.../packing-slip.pdf",
  "shippingLabelUrl": "https://.../label.pdf",
  "shipping": { "method": "Ground" },
  "shippingAddress": {
    "firstName": "Jane",
    "lastName": "Doe",
    "address1": "123 Main St",
    "city": "Austin",
    "regionCode": "TX",
    "postalCode": "78701",
    "countryCode": "US",
    "phone": "+15125550123"
  },
  "items": [{
    "name": "Gallery-Wrapped Canvas",
    "quantity": "1",
    "printSku": "MTO-GWC2436",
    "customerSku": "ART-001",
    "printDetails": [{
      "printUrl": "https://.../print-file.tiff",
      "previewUrl": "https://.../preview.jpg"
    }],
    "options": { "size": "24x36", "color": "" }
  }]
}

countryCode must be "US" — Ready2HangArt does not currently produce or ship orders outside the United States.

Field reference

Field	Required	Description
`orderId`	Yes	Your unique order identifier. Used for duplicate detection.
`poNumber`	No	Purchase-order reference shown on paperwork.
`webhookUrl`	Recommended	URL we POST status & tracking updates to (see Webhooks).
`packingSlipUrl` / `shippingLabelUrl`	No	If your system already generated the documents/label, supply them here. See Data handling & links below — these must be reachable by Ready2HangArt without additional authentication.
`shippingAddress`	Yes	Recipient name, address and phone. U.S. addresses only.
`items[].printSku`	Yes	Ready2HangArt product SKU to produce, e.g. `MTO-GWC2436`. Must match an active SKU in the current Ready2HangArt catalog — contact info@ready2hangart.com if you need the current SKU list.
`items[].printDetails[].printUrl`	Yes	Print-ready artwork file (publicly downloadable URL).
`items[].options`	No	Size / color attributes.

Response `201`

{ "success": true, "fulfillmentId": "1087" }

Errors

// Missing required field
{ "success": false, "errors": [{ "errorCode": 3000, "message": "Missing orderId" }],
  "errorMessage": "Missing orderId" }

// Duplicate order
{ "success": false, "errors": [{ "errorCode": 2001, "message": "Duplicate order ID",
  "fulfillmentId": "1087" }], "errorMessage": "Duplicate order ID" }

3. Get order status

GET/api/pod/order/{fulfillmentId}

Returns the current status of an order, including shipment/tracking details once shipped.

Response `200`

{
  "success": true,
  "order": {
    "orderId": "12345",
    "fulfillmentId": "1087",
    "poNumber": "PO-12345",
    "status": "shipped",
    "shippingAddress": { "firstName": "Jane", "lastName": "Doe", "...": "..." },
    "items": [{ "printSku": "MTO-GWC2436", "quantity": "1", "...": "..." }],
    "shipments": [{
      "trackingNumber": "1Z999AA10123456784",
      "carrier": "UPS",
      "shipMethod": "Ground",
      "shipDate": "2026-06-19T14:05:00.000Z"
    }]
  }
}

Error `404`

{ "success": false, "errors": [{ "errorCode": 2004, "message": "Order not found" }],
  "errorMessage": "Order not found" }

4. Cancel an order

POST/api/pod/order/{fulfillmentId}/cancel

Cancels an order that has not yet entered production. Orders already in production, shipped or canceled cannot be canceled.

Response `200`

{ "success": true }

Rejected cancellations

errorCode	Meaning
`6001`	Order is already canceled
`6002`	Order is already in production
`6003`	Order is already shipped

Webhooks (status & tracking back to you)

When you provide a webhookUrl on an order, Ready2HangArt POSTs a JSON notification to it whenever the order status changes. When the order ships, the notification includes the tracking details.

Status update

{ "fulfillmentId": "1087", "status": "in production" }

Shipped (with tracking)

{
  "fulfillmentId": "1087",
  "status": "shipped",
  "shipment": {
    "trackingNumber": "1Z999AA10123456784",
    "carrier": "UPS",
    "shipMethod": "Ground",
    "shipDate": "2026-06-19T14:05:00.000Z"
  }
}

Order status values

Status	Meaning
`received`	Order received, queued for review
`accepted`	Accepted for production
`in production`	Being printed / framed
`printed`	Production complete
`shipped`	Shipped — tracking available
`delivered`	Delivered to recipient
`held` / `stalled`	On hold / blocked (e.g. file or address issue)
`canceled`	Order canceled

Data handling & links

Order data submitted in the JSON request body (including shippingAddress) is transmitted over HTTPS/TLS and encrypted at rest in Ready2HangArt's systems, consistent with our Privacy Policy.

printUrl, previewUrl, packingSlipUrl, and shippingLabelUrl are links you supply, not files uploaded into Ready2HangArt's systems. Ready2HangArt does not authenticate these links; they must be reachable by our systems without a login or token, which means anyone else with the link can access the same file. Because packing slips and shipping labels can contain the buyer's name and address, use the most restricted link option your own platform supports, and avoid reusing a single link across unrelated orders.

Getting started

Ready2HangArt issues you an X-AUTH-TOKEN.
Call Test connection to confirm it works.
Send orders with Submit an order, including a webhookUrl.
Receive automatic status & tracking via your webhook (or poll Get order status).

Integration support: info@ready2hangart.com

Print-on-Demand API

How the connection works

Authentication

1. Test connection

Response 200

2. Submit an order

Request body

Field reference

Response 201

Errors

3. Get order status

Response 200

Error 404

4. Cancel an order

Response 200

Rejected cancellations

Webhooks (status & tracking back to you)

Status update

Shipped (with tracking)

Order status values

Data handling & links

Getting started

Response `200`

Response `201`

Response `200`

Error `404`

Response `200`