Pexagon Order API (1.1.0)

Download OpenAPI specification:

Standardized B2B order intake with Pexagon-controlled artwork upload.

How ordering works

The API accepts actual JPEG file uploads, not artwork URLs. You do not need public artwork hosting. Your software can read a local file or retrieve it from your own storage, then upload its bytes to Pexagon.

Ordering happens in four steps:

  1. Send the artwork. Upload the final JPEG for the product you want to order.
  2. Wait for artwork readiness. Ask for its status until Pexagon finishes validation and reports ready.
  3. Submit the order. Send the recipient, products and quantities, referencing the accepted artwork by its returned upload_id.
  4. Follow progress. Ask for the order status and current shipment tracking.

Your client software can automate all four steps. Polling means asking for the latest status again after a delay; it does not require someone to refresh a page. Pexagon does not currently send automatic callbacks when something changes.

Milestone What it means What to do next
Artwork received (202) Pexagon has stored the uploaded bytes; validation is still pending. Poll the upload status.
Artwork ready (ready) The file passed validation and is available for a new order assignment. Submit the order using its upload_id.
Order received (202) Pexagon received the order for asynchronous processing. Poll the order status.
Order accepted (accepted, with an order number) Pexagon created the order. This does not mean it has shipped. Continue checking production and shipment progress.

Production submissions can create real orders. No client sandbox is currently offered. Coordinate any test submissions with Pexagon in advance. Staging is for internal Pexagon testing only.

Use only the production access and product/location codes assigned to you by Pexagon. Documentation does not enable access or provision example products.

Connect securely

The base URL ends in /wp-json/pexagon/v1. Every endpoint below is relative to that base URL. Send Authorization: Bearer YOUR_ASSIGNED_CREDENTIAL on each request. Keep the actual credential in private configuration, never in a URL, source control, logs or support message.

The client API base URL is https://orders.pexagontech.com/wp-json/pexagon/v1.

Request Required permission
POST /artwork-uploads artwork:write
GET /artwork-uploads/{upload_id} artwork:read
POST /orders orders:write
GET /orders/{external_order_id} orders:read

The API returns only your client's resources. A missing resource and another client's resource both return a privacy-safe 404.

Prepare the JPEG

The current profile is PRINT_WRAP_JPEG_3000X2700_V1. It requires:

  • A nonempty JPEG of at most 5 MiB (5,242,880 bytes).
  • 3000 × 2700 pixels, allowing one pixel either way in each dimension.
  • An 8-bit baseline sequential JPEG with three RGB/YCbCr components.
  • EXIF Orientation absent or 1; no progressive, grayscale, CMYK, YCCK, multiple-image, malformed or truncated files.
  • sRGB artwork. The simplest export is valid sRGB artwork without an embedded ICC profile. Convert colors to sRGB first if necessary: removing a profile does not convert colors.

An embedded profile is allowed only when it exactly matches the canonical sRGB2014.icc v2 bytes (SHA-256 384b832de3412066743b52a75ee906b6fb9fb8d9e09e936fc2c43223815c6e0a). Other profiles, even other sRGB profiles, are rejected. Assembled ICC data must not exceed 1 MiB; incomplete, altered, reordered or duplicate profiles fail. DPI metadata and JPEG quality settings are not acceptance gates. Pexagon does not proofread, resize, repair or redesign your original.

Recommended: upload the exact final file from storage your software can reliably read. Your storage may remain private. If your software downloads a file first, it must receive the JPEG itself rather than an HTML preview, login page or error page. Check access permissions, expiry and redirects in your own retrieval step. Do not send storage credentials to Pexagon.

Unsupported by this API: submitting a download URL instead of JPEG bytes, including a direct .jpg URL. There is no artwork-URL field or remote-fetch step.

Common links that are not themselves JPEG file content include Google Drive /file/d/EXAMPLE/view preview pages, Dropbox links ending in ?dl=0, shared folder links, and links requiring an interactive sign-in or confirmation. Renaming a link or giving an HTML response a .jpg filename does not make it JPEG.

This is not a blanket rejection of those storage providers. Dropbox documents download and preview-link options, including redirects. Google documents file downloads and their access requirements. Your software may use an appropriate provider mechanism to obtain the file, then upload it. Provider-specific retrieval is unverified here and is not a Pexagon integration, endorsement or acceptance claim.

Upload and wait for readiness

Send raw file bytes to POST /artwork-uploads, not JSON, multipart form data, base64 or a URL. Required headers are Content-Type: image/jpeg, X-Pexagon-Artwork-Profile, and Idempotency-Key. The key is your stable retry reference: 16–128 characters from letters, digits, ., _, ~ and -. X-Pexagon-Filename is optional advisory text, not upload identity; follow its length and filename rules in the reference below. X-Request-Id is optional.

For developers, this curl example uploads a local file. PEXAGON_BASE_URL and PEXAGON_API_KEY stand for privately configured values; the filename and key are synthetic. Use a distinct stable key for each new upload operation.

curl --request POST "$PEXAGON_BASE_URL/artwork-uploads" \
  --header "Authorization: Bearer $PEXAGON_API_KEY" \
  --header 'Content-Type: image/jpeg' \
  --header 'X-Pexagon-Artwork-Profile: PRINT_WRAP_JPEG_3000X2700_V1' \
  --header 'Idempotency-Key: upkey_SYNTHETIC_001' \
  --header 'X-Pexagon-Filename: synthetic-wrap.jpg' \
  --data-binary @synthetic-wrap.jpg

Save the returned upload.upload_id. Poll the returned status_reference, relative to your base URL, with the same authentication:

curl "$PEXAGON_BASE_URL/artwork-uploads/upl_01K0SYNTHETIC001" \
  --header "Authorization: Bearer $PEXAGON_API_KEY"

Replace that fictional ID with the actual returned value. Wait while status is processing. A 200 status response can report failed: read the body, not just its HTTP code. A content failure needs corrected artwork and a new upload key. Do not submit a failed or expired upload.

A ready upload has seven days to be assigned to a new order. This is not the artwork retention period. Once submitted, it is sealed to that submission; it may cover compatible locations or lines within that order but cannot be used in a different order. An identical retry still returns the original result.

Submit the order

Send JSON to POST /orders with Content-Type: application/json. An imprint location is the named area receiving artwork, such as wrap; use your assigned location code and include every required location.

Part Required Optional
Order external_order_id, shipping, items purchase_order, in_hands_date
Shipping first_name, last_name, address_1, city, state, postcode, country (US) company, address_2, email, phone
Each item external_line_item_id, product_code, integer quantity, artwork_assignments None
Each artwork assignment imprint_location_code, ready upload_id None

in_hands_date is a calendar date (YYYY-MM-DD), not a timestamp. Response timestamps are UTC. US PO boxes and military addresses are allowed. Shipping phone/email are optional. Do not supply prices, billing identity, tax, payment gateway, WooCommerce IDs, order status or client identity.

Global limits are 40 lines, 1–100 units per line, 500 units per order, 8 artwork assignments per line and 100 per order. Your assigned product configuration may have lower limits. Quantity greater than one repeats that line's artwork. Different artwork needs a separate line with its own stable line reference.

This minimal request is entirely fictional. Substitute your assigned product and location codes, recipient details, and actual ready upload ID. Save the request before sending it so a retry can use the same data and external ID.

{
  "external_order_id": "SYN-UPLOAD-ONE",
  "shipping": {
    "first_name": "Morgan",
    "last_name": "Example",
    "address_1": "100 Example Avenue",
    "city": "Exampletown",
    "state": "NH",
    "postcode": "03101",
    "country": "US"
  },
  "items": [{
    "external_line_item_id": "line-1",
    "product_code": "SAMPLE-BOTTLE-01",
    "quantity": 1,
    "artwork_assignments": [{
      "imprint_location_code": "wrap",
      "upload_id": "upl_01K0SYNTHETIC001"
    }]
  }]
}

Order idempotency uses your external_order_id, not the upload header key. Repeating the same ID with the same normalized request returns the existing submission; changed data returns 409 duplicate_order_conflict. Preserve line order. Assignment ordering is normalized by location. Never change an ID just to work around a timeout or unknown result.

Follow order and shipment progress

Poll GET /orders/{external_order_id} with authentication. received and artwork_processing are pending. accepted with a non-null pexagon_order_number means the order was created; a later observation may already show in_production or shipped. action_required needs attention and rejected means processing was rejected. Read any current_issue and its recovery classification. Cancellation is reported as cancelled for a verified bound order; it is not a client-operated cancellation endpoint.

shipments lists current active tracking, which can appear before the whole order ships. shipping_progress is separate from the overall order status:

Shipping progress Meaning
not_recorded No shipping evidence is recorded; this does not prove nothing shipped.
partially_shipped One structured report covers a positive subset of the order.
awaiting_completion_confirmation Split reports, corrections, missing quantities or an exception need staff confirmation.
shipped Active tracking and confirmed reported fulfillment agree with the completed order. It does not prove carrier acceptance or delivery.

Pexagon does not add shipment reports together to infer that everything shipped. Staff confirms split or ambiguous completion. Tracking may be corrected or withdrawn, and an order can return to an earlier shipping state. Refresh your stored tracking from the entire current shipments list instead of only adding records. Replaced/withdrawn entries are omitted. An empty list after a successful lookup can be meaningful; a failed lookup is not an instruction to erase tracking. updated_at reflects relevant order/shipping changes; duplicate shipment capture alone does not advance it. Tracking changes in Pexagon do not void carrier labels.

Poll at spaced intervals appropriate to your workflow; avoid tight loops and honor Retry-After. Upload creation and upload lookup have separate per-client buckets of 10 and 60 requests per minute, shared across credentials. Order limits are separate. These are safety limits, not a promised processing time or polling schedule. Automatic callbacks/webhooks remain deferred.

Handle errors and request changes

Response or issue Practical action
401 / 403 Check assigned environment, credential and required permission privately.
404 Check the resource reference and environment; it may be unavailable to your client.
409 Stop automatic retry and reconcile the original upload/order. Do not generate a new ID to bypass it.
400, 413, 415, 422 Read the error code and field; fix invalid input or wait for readiness when specifically indicated.
429 / 503 Honor Retry-After when present, then retry/poll without changing identity.
500 or a timeout Outcome may be unknown. Reconcile first; do not blindly create another order.

After an upload timeout, retry the same key, exact file bytes and profile. After an order timeout, look up its external ID; any POST retry must keep that ID and the exact semantic request. Never blindly repeat unchanged invalid input. platform_retrying means Pexagon is retrying. client_action_required, pexagon_action_required and not_recoverable need the indicated action or support. For assistance, provide the request ID, HTTP status, safe error code, time and opaque upload/order reference; omit credentials, artwork, recipient details and complete request bodies.

Contact Pexagon before correcting or cancelling an accepted order, especially once production has started. There is no client API to edit or cancel it. The current correction procedure requires staff-approved cancellation followed by a new external order ID and fresh uploads. Cancellation or Trash does not release the old ID. Ordinary order duplication is not an approved replacement procedure. For an agreed replacement/RMA, the client submits only after Brian's written go-ahead, using a new external ID, fresh uploads and new upload idempotency keys, even for the same correct artwork bytes. Confirm usable artwork first; request it again if unavailable. Preserve the original and link its reference to the accepted replacement. There is no self-service RMA or original-order reopening.

Coordinated TEST- walkthrough

After 1.0.0 and your development readiness, agree a small exact order list, window, contacts and expected results with Brian. TEST-TEAMLOCKER-001 is only a naming convention: TEST- submissions are ordinary production orders, with no automatic safeguard, special status or exclusion. Do not send unannounced submissions.

  1. Agree no manufacturing, postage purchase, real labels or dispatch, with notification-off settings preserved. Upload final JPEGs, poll readiness, submit and poll acceptance. Share external IDs and matching WooCommerce order numbers with Brian, without credentials or customer details.
  2. Coordinate the full agreed walkthrough with Brian. Confirm artwork readiness, order acceptance and the expected production/shipping results through polling. Any label-free shipment simulation needs advance agreement on the exact order, synthetic tracking, notification count and expected result; otherwise omit it. Simulated tracking/status is not proof of carrier acceptance or delivery.
  3. Finish checks before Brian coordinates cleanup. Retain order references, results, whether shipping was simulated and unresolved issues. Cleanup is limited to Brian-approved successful tests; failures need separate review. Do not assume cleanup in one system removes records elsewhere or releases used IDs/uploads.

If anything is uncertain, stop submissions and contact Brian with safe references; do not resend an uncertain notification, force a result or use a new ID to bypass uncertainty. Access shutdown also stops polling and may not stop shipment callbacks or undo accepted work.

Artwork availability and deferred features

Keep your own originals. The artwork availability window runs through 30 days after the order is completed in WooCommerce, subject to unresolved exceptions. It does not start at upload or order creation, and time spent On Hold does not start it. Unfinished orders, including long-held future orders, do not lose artwork merely because they are old.

After that window, originals and previews become eligible for permanent deletion from active storage; continued availability is not guaranteed. Automatic deletion is deferred and is not running. Deletion precisely on day 30 is not promised. Reopened/cancelled orders, holds, shared-file protection, backup interaction and exact deletion handling still need separate decisions. Missing or inaccessible artwork is not proof of permanent deletion.

Current features are direct JPEG upload, readiness polling, immutable order submission, order lookup and current tracking/shipping progress. Automatic callbacks, artwork-URL retrieval, automatic retention deletion, actual paid shipping-cost reporting and monthly statements are deferred. RMA handling uses the agreed manual procedure above; it is not a self-service feature.

The endpoint reference below supplies exact field syntax, response schemas and additional synthetic examples. Its downloadable specification describes the same supported operations as this guide.

Optional client order note

You may include order_note in POST /orders: a plain-text string of up to 500 Unicode characters after normalization. Ordinary punctuation, accents, repeated information and line breaks are welcome. For example:

"order_note": "#42 (repeat): O'Brien café—please group cartons.\nReference the PO on paperwork."

The note appears in WooCommerce order details and the Sales Order. It does not change products, quantity, artwork, addresses or other structured fields and does not send a customer-note notification. Markup and shortcodes are literal. Omit it or use an empty/whitespace-only string for no note; do not send null. Line endings normalize to LF, outer whitespace is trimmed and Unicode is NFC. Retry with the same normalized content. Changing a nonempty note on the same external ID conflicts; identical notes on different orders are valid.

Artwork uploads

Upload and inspect private client-owned artwork.

Upload exact final JPEG bytes

Requires artwork:write. The body is the client's declared final JPEG. The authenticated client, idempotency key, exact server-observed bytes, and profile define retry identity. Same identity returns the existing upload; changed bytes or profile returns 409. A 202 response means the complete immutable original is already durably stored with matching server-observed size and SHA-256. JPEG structure and decodability are not decided synchronously; inspection and preview remain async, and malformed/non-JPEG bytes later produce failed upload status.

Authorizations:
bearerAuth
header Parameters
Idempotency-Key
required
string [ 16 .. 128 ] characters ^[A-Za-z0-9._~-]+$
Example: upkey_01K0SYNTHETICRETRY

Client-scoped upload retry key. The server stores only the SHA-256 digest of the exact accepted Idempotency-Key bytes; never use an order ID or filename as storage authority.

X-Pexagon-Artwork-Profile
required
string
Value: "PRINT_WRAP_JPEG_3000X2700_V1"
X-Pexagon-Filename
string [ 1 .. 180 ] characters ^(?!.*[\\/])(?!.*\.\.)(?!.*[\u0000-\u001F\u00...
Example: synthetic-wrap.jpg

Bounded advisory display/audit value; not upload identity or storage authority.

X-Request-Id
string <= 100 characters
Request Body schema: image/jpeg
required
string <binary>

Client-declared final JPEG bytes; nonempty and maximum 5 MiB. Structural JPEG validation is asynchronous after durable receipt.

Responses

Response Headers
X-Request-Id
string

Correlation identifier safe to provide to support.

Response Schema: application/json
success
required
any
Value: true
request_id
required
string
duplicate
required
boolean
required
object (ArtworkUpload)
upload_id
required
string (UploadId) ^upl_[A-Za-z0-9]{12,64}$
profile
required
string (ArtworkProfile)
Value: "PRINT_WRAP_JPEG_3000X2700_V1"
status
required
string (UploadStatus)
Enum: "processing" "ready" "failed" "expired"
availability
required
string (UploadAvailability)
Enum: "unsealed" "sealed" "attached" "unavailable"
created_at
required
string <date-time>
updated_at
required
string <date-time>
ready_at
required
string or null <date-time>
expires_at
required
string or null <date-time>

Seven days after readiness; null until ready.

byte_size
required
integer [ 1 .. 5242880 ]

Server-authoritative exact received bytes.

sha256
required
string^[a-f0-9]{64}$

Server-authoritative lowercase SHA-256 of received bytes.

status_reference
required
string^/artwork-uploads/upl_[A-Za-z0-9]{12,64}$
required
UploadIssue (object) or null
One of
code
required
string^[a-z][a-z0-9_]*$
message
required
string [ 1 .. 300 ] characters
retryable
required
boolean

False for terminal content failures that require a new corrected upload.

recovery_classification
required
string (RecoveryClassification)
Enum: "platform_retrying" "client_action_required" "pexagon_action_required" "not_recoverable"
Response Headers
X-Request-Id
string

Correlation identifier safe to provide to support.

Location
string
Example: "/artwork-uploads/upl_01K0SYNTHETIC001"

Authenticated status reference for this upload.

Response Schema: application/json
success
required
any
Value: true
request_id
required
string
duplicate
required
boolean
required
object (ArtworkUpload)
upload_id
required
string (UploadId) ^upl_[A-Za-z0-9]{12,64}$
profile
required
string (ArtworkProfile)
Value: "PRINT_WRAP_JPEG_3000X2700_V1"
status
required
string (UploadStatus)
Enum: "processing" "ready" "failed" "expired"
availability
required
string (UploadAvailability)
Enum: "unsealed" "sealed" "attached" "unavailable"
created_at
required
string <date-time>
updated_at
required
string <date-time>
ready_at
required
string or null <date-time>
expires_at
required
string or null <date-time>

Seven days after readiness; null until ready.

byte_size
required
integer [ 1 .. 5242880 ]

Server-authoritative exact received bytes.

sha256
required
string^[a-f0-9]{64}$

Server-authoritative lowercase SHA-256 of received bytes.

status_reference
required
string^/artwork-uploads/upl_[A-Za-z0-9]{12,64}$
required
UploadIssue (object) or null
One of
code
required
string^[a-z][a-z0-9_]*$
message
required
string [ 1 .. 300 ] characters
retryable
required
boolean

False for terminal content failures that require a new corrected upload.

recovery_classification
required
string (RecoveryClassification)
Enum: "platform_retrying" "client_action_required" "pexagon_action_required" "not_recoverable"
Response Headers
X-Request-Id
string

Correlation identifier safe to provide to support.

Response Schema: application/json
success
required
any
request_id
required
string
required
object (Error)
code
required
string^[a-z][a-z0-9_]*$
message
required
string <= 300 characters
field
string or null
retryable
required
boolean
object
object
Response Headers
X-Request-Id
string

Correlation identifier safe to provide to support.

Response Schema: application/json
success
required
any
request_id
required
string
required
object (Error)
code
required
string^[a-z][a-z0-9_]*$
message
required
string <= 300 characters
field
string or null
retryable
required
boolean
object
object
Response Headers
X-Request-Id
string

Correlation identifier safe to provide to support.

Response Schema: application/json
success
required
any
request_id
required
string
required
object (Error)
code
required
string^[a-z][a-z0-9_]*$
message
required
string <= 300 characters
field
string or null
retryable
required
boolean
object
object

Response samples

Content type
application/json
{
  • "success": true,
  • "request_id": "string",
  • "duplicate": true,
  • "upload": {
    }
}

Get private upload status

Requires artwork:read. Returns only uploads owned by the authenticated client. Nonexistent and wrong-client IDs use the same privacy-safe 404.

Authorizations:
bearerAuth
path Parameters
upload_id
required
string (UploadId) ^upl_[A-Za-z0-9]{12,64}$
Example: upl_01K0SYNTHETIC001
header Parameters
X-Request-Id
string <= 100 characters

Responses

Response Headers
X-Request-Id
string

Correlation identifier safe to provide to support.

Response Schema: application/json
success
required
any
Value: true
request_id
required
string
required
object (ArtworkUpload)
upload_id
required
string (UploadId) ^upl_[A-Za-z0-9]{12,64}$
profile
required
string (ArtworkProfile)
Value: "PRINT_WRAP_JPEG_3000X2700_V1"
status
required
string (UploadStatus)
Enum: "processing" "ready" "failed" "expired"
availability
required
string (UploadAvailability)
Enum: "unsealed" "sealed" "attached" "unavailable"
created_at
required
string <date-time>
updated_at
required
string <date-time>
ready_at
required
string or null <date-time>
expires_at
required
string or null <date-time>

Seven days after readiness; null until ready.

byte_size
required
integer [ 1 .. 5242880 ]

Server-authoritative exact received bytes.

sha256
required
string^[a-f0-9]{64}$

Server-authoritative lowercase SHA-256 of received bytes.

status_reference
required
string^/artwork-uploads/upl_[A-Za-z0-9]{12,64}$
required
UploadIssue (object) or null
One of
code
required
string^[a-z][a-z0-9_]*$
message
required
string [ 1 .. 300 ] characters
retryable
required
boolean

False for terminal content failures that require a new corrected upload.

recovery_classification
required
string (RecoveryClassification)
Enum: "platform_retrying" "client_action_required" "pexagon_action_required" "not_recoverable"

Response samples

Content type
application/json
Example
{
  • "success": true,
  • "request_id": "req_01K0READY",
  • "upload": {
    }
}

Orders

Submit and reconcile immutable orders.

Submit an immutable order

Requires orders:write. After static validation, the server normalizes and hashes the request and looks up (client_id, external_order_id) before consulting mutable upload, mapping, product, readiness, expiry, profile, or sealing state. Identical canonical data returns the existing submission and attachments without mutation or current-authority revalidation. Changed data returns 409 before mutable validation.

Only a new submission validates current ownership, readiness, failure, expiry, sealing availability, mapped locations/products, and profile compatibility, then atomically creates the submission, assignments, attachments, and seals. Line order is meaningful. Assignment order is not: after duplicate-location rejection, canonicalization sorts it by imprint_location_code. Limits are 8 assignments per line and 100 per order; product configuration may impose lower limits.

Authorizations:
bearerAuth
header Parameters
X-Request-Id
string <= 100 characters
Request Body schema: application/json
required
external_order_id
required
string (ExternalOrderId) [ 1 .. 100 ] characters ^[A-Za-z0-9][A-Za-z0-9._:/-]*$
order_note
string <= 500 characters

Optional plain text; maximum 500 Unicode code points after NFC, outer whitespace trim and CRLF/CR to LF normalization. Internal whitespace and useful line breaks remain. Empty normalized notes are omitted from canonical identity. Nonempty notes participate in order-level idempotency; changed notes on an accepted external ID conflict. Identical notes on different orders and repeated order information are valid. Literal display only; no structured-field override or customer-note notification. Null is invalid.

purchase_order
string or null <= 100 characters
in_hands_date
string or null <date>
required
object (ShippingAddress)
company
string or null <= 100 characters
first_name
required
string [ 1 .. 60 ] characters
last_name
required
string [ 1 .. 60 ] characters
address_1
required
string [ 1 .. 100 ] characters
address_2
string or null <= 100 characters
city
required
string [ 1 .. 80 ] characters
state
required
string [ 1 .. 80 ] characters
postcode
required
string [ 1 .. 20 ] characters
country
required
string
Value: "US"
email
string or null <email> <= 254 characters
phone
string or null [ 7 .. 30 ] characters ^(?=(?:[^0-9]*[0-9]){7,15}[^0-9]*$)[0-9 +().-...
required
Array of objects (OrderItemRequest) [ 1 .. 40 ] items
Array ([ 1 .. 40 ] items)
external_line_item_id
required
string [ 1 .. 100 ] characters
product_code
required
string [ 1 .. 64 ] characters ^[A-Z0-9][A-Z0-9_-]*$
quantity
required
integer [ 1 .. 100 ]
required
Array of objects (ArtworkAssignmentRequest) [ 1 .. 8 ] items

Input order is insignificant; normalized location codes must be unique. Maximum 8 per line and 100 across the order; product configuration may impose lower limits.

Responses

Response Headers
X-Request-Id
string

Correlation identifier safe to provide to support.

Response Schema: application/json
success
required
any
Value: true
request_id
required
string
duplicate
required
boolean
required
object (PublicOrder)
external_order_id
required
string (ExternalOrderId) [ 1 .. 100 ] characters ^[A-Za-z0-9][A-Za-z0-9._:/-]*$
submission_id
required
string (SubmissionId) ^sub_[A-Za-z0-9]{12,64}$
status
required
string (OrderStatus)
Enum: "received" "artwork_processing" "accepted" "in_production" "action_required" "rejected" "shipped" "cancelled"
submitted_at
required
string <date-time>
updated_at
required
string <date-time>

Latest submission, shipment evidence, unresolved shipping warning or native order modification time. Duplicate shipment capture alone does not advance this value.

pexagon_order_number
required
string or null
required
object (ArtworkSummary)

Counts derived line statuses, never uploads, assignments, objects, or revisions. ready + processing + failed = total. held is an overlapping subset of lines and is not added to that equality.

total
required
integer >= 0

Total order lines.

ready
required
integer >= 0

Lines whose required assignments are all ready.

processing
required
integer >= 0

Nonfailed lines with at least one pending or processing assignment.

failed
required
integer >= 0

Lines with at least one failed required assignment.

held
required
integer >= 0

Overlapping count of lines with any active applicable assignment hold.

required
Array of objects (OrderLine) [ 1 .. 40 ] items
Array ([ 1 .. 40 ] items)
external_line_item_id
required
string
product_code
required
string
quantity
required
integer
artwork_status
required
string (ArtworkStatus)
Enum: "pending" "processing" "ready" "failed"

Failed if any required assignment failed; otherwise processing if any is pending/processing; otherwise ready.

production_hold
required
boolean

True when any assignment has an active applicable hold; orthogonal to artwork status.

required
Array of objects (PublicArtworkAssignment) non-empty
required
SafeIssue (object) or null
required
SafeIssue (object) or null
One of
code
required
string^[a-z][a-z0-9_]*$
message
required
string [ 1 .. 300 ] characters
recovery_classification
required
string (RecoveryClassification)
Enum: "platform_retrying" "client_action_required" "pexagon_action_required" "not_recoverable"
shipping_progress
string
Enum: "not_recorded" "partially_shipped" "awaiting_completion_confirmation" "shipped"

Optional for compatibility; the current implementation always returns it. No recorded evidence does not prove nothing shipped. Partial means one explicit positive proper-subset report. Distinct split reports, legacy/missing quantities, corrections or unresolved exceptions require staff confirmation. Shipped requires active tracking, confirmed reported fulfillment and fresh WooCommerce Completed; it proves neither carrier acceptance nor delivery. Overall lifecycle status remains separate.

required
Array of objects (Shipment)

Active valid tracking, visible before whole-order completion. Withdrawn and replaced records are excluded.

Array
shipment_id
required
string
carrier
required
string
service
string or null
tracking_number
required
string
tracking_url
string or null <uri>
Response Headers
X-Request-Id
string

Correlation identifier safe to provide to support.

Location
string
Example: "/orders/SYN-UPLOAD-ONE"

Order lookup reference.

Response Schema: application/json
success
required
any
Value: true
request_id
required
string
duplicate
required
boolean
required
object (PublicOrder)
external_order_id
required
string (ExternalOrderId) [ 1 .. 100 ] characters ^[A-Za-z0-9][A-Za-z0-9._:/-]*$
submission_id
required
string (SubmissionId) ^sub_[A-Za-z0-9]{12,64}$
status
required
string (OrderStatus)
Enum: "received" "artwork_processing" "accepted" "in_production" "action_required" "rejected" "shipped" "cancelled"
submitted_at
required
string <date-time>
updated_at
required
string <date-time>

Latest submission, shipment evidence, unresolved shipping warning or native order modification time. Duplicate shipment capture alone does not advance this value.

pexagon_order_number
required
string or null
required
object (ArtworkSummary)

Counts derived line statuses, never uploads, assignments, objects, or revisions. ready + processing + failed = total. held is an overlapping subset of lines and is not added to that equality.

total
required
integer >= 0

Total order lines.

ready
required
integer >= 0

Lines whose required assignments are all ready.

processing
required
integer >= 0

Nonfailed lines with at least one pending or processing assignment.

failed
required
integer >= 0

Lines with at least one failed required assignment.

held
required
integer >= 0

Overlapping count of lines with any active applicable assignment hold.

required
Array of objects (OrderLine) [ 1 .. 40 ] items
Array ([ 1 .. 40 ] items)
external_line_item_id
required
string
product_code
required
string
quantity
required
integer
artwork_status
required
string (ArtworkStatus)
Enum: "pending" "processing" "ready" "failed"

Failed if any required assignment failed; otherwise processing if any is pending/processing; otherwise ready.

production_hold
required
boolean

True when any assignment has an active applicable hold; orthogonal to artwork status.

required
Array of objects (PublicArtworkAssignment) non-empty
required
SafeIssue (object) or null
required
SafeIssue (object) or null
One of
code
required
string^[a-z][a-z0-9_]*$
message
required
string [ 1 .. 300 ] characters
recovery_classification
required
string (RecoveryClassification)
Enum: "platform_retrying" "client_action_required" "pexagon_action_required" "not_recoverable"
shipping_progress
string
Enum: "not_recorded" "partially_shipped" "awaiting_completion_confirmation" "shipped"

Optional for compatibility; the current implementation always returns it. No recorded evidence does not prove nothing shipped. Partial means one explicit positive proper-subset report. Distinct split reports, legacy/missing quantities, corrections or unresolved exceptions require staff confirmation. Shipped requires active tracking, confirmed reported fulfillment and fresh WooCommerce Completed; it proves neither carrier acceptance nor delivery. Overall lifecycle status remains separate.

required
Array of objects (Shipment)

Active valid tracking, visible before whole-order completion. Withdrawn and replaced records are excluded.

Array
shipment_id
required
string
carrier
required
string
service
string or null
tracking_number
required
string
tracking_url
string or null <uri>
Response Headers
X-Request-Id
string

Correlation identifier safe to provide to support.

Response Schema: application/json
success
required
any
request_id
required
string
required
object (Error)
code
required
string^[a-z][a-z0-9_]*$
message
required
string <= 300 characters
field
string or null
retryable
required
boolean
object
object
Response Headers
X-Request-Id
string

Correlation identifier safe to provide to support.

Response Schema: application/json
success
required
any
request_id
required
string
required
object (Error)
code
required
string^[a-z][a-z0-9_]*$
message
required
string <= 300 characters
field
string or null
retryable
required
boolean
object
object
Response Headers
X-Request-Id
string

Correlation identifier safe to provide to support.

Response Schema: application/json
success
required
any
request_id
required
string
required
object (Error)
code
required
string^[a-z][a-z0-9_]*$
message
required
string <= 300 characters
field
string or null
retryable
required
boolean
object
object

Request samples

Content type
application/json
Example
{
  • "external_order_id": "SYN-UPLOAD-ONE",
  • "shipping": {
    },
  • "items": [
    ]
}

Response samples

Content type
application/json
{
  • "success": true,
  • "request_id": "string",
  • "duplicate": true,
  • "order": {
    }
}

Look up an order by client external ID

Requires orders:read and returns only the authenticated client's order. Read current shipments and shipping_progress separately from overall status. Withdrawn/replaced tracking is omitted; refresh the complete active list. Temporary shipping lookup failures return 503, not an empty tracking result.

Authorizations:
bearerAuth
path Parameters
external_order_id
required
string (ExternalOrderId) [ 1 .. 100 ] characters ^[A-Za-z0-9][A-Za-z0-9._:/-]*$
Example: SYN-UPLOAD-ONE
header Parameters
X-Request-Id
string <= 100 characters

Responses

Response Headers
X-Request-Id
string

Correlation identifier safe to provide to support.

Response Schema: application/json
success
required
any
Value: true
request_id
required
string
required
object (PublicOrder)
external_order_id
required
string (ExternalOrderId) [ 1 .. 100 ] characters ^[A-Za-z0-9][A-Za-z0-9._:/-]*$
submission_id
required
string (SubmissionId) ^sub_[A-Za-z0-9]{12,64}$
status
required
string (OrderStatus)
Enum: "received" "artwork_processing" "accepted" "in_production" "action_required" "rejected" "shipped" "cancelled"
submitted_at
required
string <date-time>
updated_at
required
string <date-time>

Latest submission, shipment evidence, unresolved shipping warning or native order modification time. Duplicate shipment capture alone does not advance this value.

pexagon_order_number
required
string or null
required
object (ArtworkSummary)

Counts derived line statuses, never uploads, assignments, objects, or revisions. ready + processing + failed = total. held is an overlapping subset of lines and is not added to that equality.

total
required
integer >= 0

Total order lines.

ready
required
integer >= 0

Lines whose required assignments are all ready.

processing
required
integer >= 0

Nonfailed lines with at least one pending or processing assignment.

failed
required
integer >= 0

Lines with at least one failed required assignment.

held
required
integer >= 0

Overlapping count of lines with any active applicable assignment hold.

required
Array of objects (OrderLine) [ 1 .. 40 ] items
Array ([ 1 .. 40 ] items)
external_line_item_id
required
string
product_code
required
string
quantity
required
integer
artwork_status
required
string (ArtworkStatus)
Enum: "pending" "processing" "ready" "failed"

Failed if any required assignment failed; otherwise processing if any is pending/processing; otherwise ready.

production_hold
required
boolean

True when any assignment has an active applicable hold; orthogonal to artwork status.

required
Array of objects (PublicArtworkAssignment) non-empty
required
SafeIssue (object) or null
required
SafeIssue (object) or null
One of
code
required
string^[a-z][a-z0-9_]*$
message
required
string [ 1 .. 300 ] characters
recovery_classification
required
string (RecoveryClassification)
Enum: "platform_retrying" "client_action_required" "pexagon_action_required" "not_recoverable"
shipping_progress
string
Enum: "not_recorded" "partially_shipped" "awaiting_completion_confirmation" "shipped"

Optional for compatibility; the current implementation always returns it. No recorded evidence does not prove nothing shipped. Partial means one explicit positive proper-subset report. Distinct split reports, legacy/missing quantities, corrections or unresolved exceptions require staff confirmation. Shipped requires active tracking, confirmed reported fulfillment and fresh WooCommerce Completed; it proves neither carrier acceptance nor delivery. Overall lifecycle status remains separate.

required
Array of objects (Shipment)

Active valid tracking, visible before whole-order completion. Withdrawn and replaced records are excluded.

Array
shipment_id
required
string
carrier
required
string
service
string or null
tracking_number
required
string
tracking_url
string or null <uri>

Response samples

Content type
application/json
Example
{
  • "success": true,
  • "request_id": "req_01K0PARTIAL",
  • "order": {
    }
}