Pexagon Order API (1.0.0-draft)

Download OpenAPI specification:

Standardized B2B contract-decoration order ingestion and fulfillment status.

Draft contract for approved Pexagon integration clients.

A successful POST normally returns 202 Accepted while Pexagon retrieves and validates artwork. The order is not production-accepted until its status becomes accepted and a Pexagon order number is assigned.

The authenticated credential identifies the client. Clients cannot choose prices, billing identities, WooCommerce product IDs, tax behavior, payment methods, or internal order statuses.

Orders

Submit and reconcile orders.

Submit an order

Authenticates the client, validates and stores an intake submission, and queues artwork retrieval. external_order_id is the idempotency key within the authenticated client.

Repeating an identical canonical request returns the existing result. Reusing the ID with different data returns 409.

Authorizations:

bearerAuth

header Parameters

X-Request-Id

string [ 1 .. 100 ] characters

Optional client correlation ID. Pexagon always returns its own accepted/generated value.

Request Body schema: application/json
required

external_order_id

required

string (ExternalOrderId) [ 1 .. 100 ] characters ^[A-Za-z0-9][A-Za-z0-9._:/-]*$

purchase_order

string or null [ 1 .. 100 ] characters

in_hands_date

string or null <date>

Requested recipient in-hands date; not a guaranteed ship or delivery 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^[A-Z]{2}$ ISO 3166-1 alpha-2 country code.
email	string or null <email> <= 254 characters
phone	string or null [ 7 .. 30 ] characters

required

Array of objects (OrderItemRequest) [ 1 .. 100 ] items

Array ([ 1 .. 100 ] items)

external_line_item_id required	string [ 1 .. 100 ] characters Unique within this order and stable in the client's system.
product_code required	string [ 1 .. 64 ] characters ^[A-Z0-9][A-Z0-9_-]*$
quantity required	integer [ 1 .. 10000 ] All units on this line use the same artwork.
required	object (RemoteArtwork)

Responses

Response Headers
X-Request-Id	string Pexagon request correlation ID.

Response Schema: application/json

success

required

any

Value: true

request_id

required

string

duplicate

required

boolean

required

object (Order)

external_order_id

required

string (ExternalOrderId) [ 1 .. 100 ] characters ^[A-Za-z0-9][A-Za-z0-9._:/-]*$

submission_id

required

string

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>

pexagon_order_id

required

integer or null >= 1

pexagon_order_number

required

string or null

required

object (ArtworkSummary)

total required	integer >= 0
ready required	integer >= 0
processing required	integer >= 0
failed required	integer >= 0

required

Array of objects (Shipment)

Array

shipment_id required	string
carrier required	string [ 1 .. 100 ] characters
service	string or null <= 100 characters
tracking_number required	string [ 1 .. 200 ] characters
tracking_url	string or null <uri>
shipped_at required	string <date-time>

Response Headers
X-Request-Id	string Pexagon request correlation ID.
Location	string Relative or absolute URL for order lookup.

Response Schema: application/json

success

required

any

Value: true

request_id

required

string

duplicate

required

boolean

required

object (Order)

external_order_id

required

string (ExternalOrderId) [ 1 .. 100 ] characters ^[A-Za-z0-9][A-Za-z0-9._:/-]*$

submission_id

required

string

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>

pexagon_order_id

required

integer or null >= 1

pexagon_order_number

required

string or null

required

object (ArtworkSummary)

total required	integer >= 0
ready required	integer >= 0
processing required	integer >= 0
failed required	integer >= 0

required

Array of objects (Shipment)

Array

shipment_id required	string
carrier required	string [ 1 .. 100 ] characters
service	string or null <= 100 characters
tracking_number required	string [ 1 .. 200 ] characters
tracking_url	string or null <uri>
shipped_at required	string <date-time>

Response Headers
X-Request-Id	string Pexagon request correlation ID.

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

field

string or null

retryable

required

boolean

object

property name*

additional property

any

Response Headers
X-Request-Id	string Pexagon request correlation ID.

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

field

string or null

retryable

required

boolean

object

property name*

additional property

any

Response Headers
X-Request-Id	string Pexagon request correlation ID.

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

field

string or null

retryable

required

boolean

object

property name*

additional property

any

Request samples

Payload

Content type

application/json

{"external_order_id": "VO-000123",
"purchase_order": "PO-9817",
"in_hands_date": "2026-08-21",
"shipping": {"company": "Example Recipient Company",
"first_name": "Taylor",
"last_name": "Smith",
"address_1": "250 Distribution Way",
"address_2": "Dock 3",
"city": "Manchester",
"state": "NH",
"postcode": "03101",
"country": "US",
"email": "receiving@example.com",
"phone": "+16035550100"
},
"items": [{"external_line_item_id": "1",
"product_code": "BOTTLE-WRAP-01",
"quantity": 1,
"artwork": {"url": "https://files.example.com/VO-000123/line-1.jpg?signature=redacted",
"filename": "VO-000123-line-1.jpg"
}
},
{"external_line_item_id": "2",
"product_code": "BOTTLE-WRAP-01",
"quantity": 1,
"artwork": {"url": "https://files.example.com/VO-000123/line-2.jpg?signature=redacted",
"filename": "VO-000123-line-2.jpg"
}
}
]
}

Response samples

Content type

application/json

{"success": true,
"request_id": "string",
"duplicate": true,
"order": {"external_order_id": "VO-000123",
"submission_id": "string",
"status": "received",
"submitted_at": "2019-08-24T14:15:22Z",
"updated_at": "2019-08-24T14:15:22Z",
"pexagon_order_id": 1,
"pexagon_order_number": "string",
"artwork": {"total": 0,
"ready": 0,
"processing": 0,
"failed": 0
},
"shipments": [{"shipment_id": "string",
"carrier": "string",
"service": "string",
"tracking_number": "string",
"tracking_url": "http://example.com",
"shipped_at": "2019-08-24T14:15:22Z"
}
]
}
}

Look up an order by client external ID

Returns only an order belonging to the authenticated integration client. Use this endpoint for reconciliation after a timeout or missed webhook.

Authorizations:

bearerAuth

path Parameters

external_order_id

required

string (ExternalOrderId) [ 1 .. 100 ] characters ^[A-Za-z0-9][A-Za-z0-9._:/-]*$

Examples: VO-000123

Client external order ID, unique within the authenticated client.

header Parameters

X-Request-Id

string [ 1 .. 100 ] characters

Optional client correlation ID. Pexagon always returns its own accepted/generated value.

Responses

Response Headers
X-Request-Id	string Pexagon request correlation ID.

Response Schema: application/json

success

required

any

Value: true

request_id

required

string

duplicate

required

boolean

required

object (Order)

external_order_id

required

string (ExternalOrderId) [ 1 .. 100 ] characters ^[A-Za-z0-9][A-Za-z0-9._:/-]*$

submission_id

required

string

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>

pexagon_order_id

required

integer or null >= 1

pexagon_order_number

required

string or null

required

object (ArtworkSummary)

total required	integer >= 0
ready required	integer >= 0
processing required	integer >= 0
failed required	integer >= 0

required

Array of objects (Shipment)

Array

shipment_id required	string
carrier required	string [ 1 .. 100 ] characters
service	string or null <= 100 characters
tracking_number required	string [ 1 .. 200 ] characters
tracking_url	string or null <uri>
shipped_at required	string <date-time>

Response samples

Content type

application/json

{"success": true,
"request_id": "req_01K0LOOKUP",
"duplicate": false,
"order": {"external_order_id": "VO-000123",
"submission_id": "sub_01K0EXAMPLE",
"status": "shipped",
"submitted_at": "2026-07-29T15:42:10Z",
"updated_at": "2026-08-02T18:10:00Z",
"pexagon_order_id": 31842,
"pexagon_order_number": "31842",
"artwork": {"total": 2,
"ready": 2,
"processing": 0,
"failed": 0
},
"shipments": [{"shipment_id": "shp_01K0SHIP",
"carrier": "UPS",
"tracking_number": "1Z999AA10123456784",
"shipped_at": "2026-08-02T00:00:00Z"
}
]
}
}

Order accepted Webhook

Sent after artwork is ready and the WooCommerce order has been created. Delivery is at-least-once; deduplicate with event_id.

Authorizations:

bearerAuth

header Parameters

X-Pexagon-Event-Id required	string Same stable event identifier included in the JSON body.
X-Pexagon-Timestamp required	string <date-time> UTC signature timestamp.
X-Pexagon-Signature required	string^v1=[a-f0-9]{64}$ HMAC-SHA256 signature over timestamp, a period, and the exact raw body.

Request Body schema: application/json
required

event_id

required

string

event_type

required

string

Enum: "order.accepted" "order.rejected" "artwork.failed" "order.shipped"

Value: "order.accepted"

api_version

required

any

Value: "v1"

created_at

required

string <date-time>

required

object

external_order_id required	string (ExternalOrderId) [ 1 .. 100 ] characters ^[A-Za-z0-9][A-Za-z0-9._:/-]*$
pexagon_order_id required	integer >= 1
pexagon_order_number required	string
status required	any Value: "accepted"

Responses

Request samples

Payload

Content type

application/json

{"event_id": "string",
"event_type": "order.accepted",
"api_version": "v1",
"created_at": "2019-08-24T14:15:22Z",
"data": {"external_order_id": "VO-000123",
"pexagon_order_id": 1,
"pexagon_order_number": "string",
"status": "accepted"
}
}

Artwork processing failed Webhook

Authorizations:

bearerAuth

header Parameters

X-Pexagon-Event-Id required	string Same stable event identifier included in the JSON body.
X-Pexagon-Timestamp required	string <date-time> UTC signature timestamp.
X-Pexagon-Signature required	string^v1=[a-f0-9]{64}$ HMAC-SHA256 signature over timestamp, a period, and the exact raw body.

Request Body schema: application/json
required

event_id

required

string

event_type

required

string

Enum: "order.accepted" "order.rejected" "artwork.failed" "order.shipped"

Value: "artwork.failed"

api_version

required

any

Value: "v1"

created_at

required

string <date-time>

required

object

external_order_id required	string (ExternalOrderId) [ 1 .. 100 ] characters ^[A-Za-z0-9][A-Za-z0-9._:/-]*$
external_line_item_id required	string
code required	string^[a-z][a-z0-9_]*$
message required	string
retryable required	boolean

Responses

Request samples

Payload

Content type

application/json

{"event_id": "string",
"event_type": "artwork.failed",
"api_version": "v1",
"created_at": "2019-08-24T14:15:22Z",
"data": {"external_order_id": "VO-000123",
"external_line_item_id": "string",
"code": "string",
"message": "string",
"retryable": true
}
}

Order submission rejected Webhook

Authorizations:

bearerAuth

header Parameters

X-Pexagon-Event-Id required	string Same stable event identifier included in the JSON body.
X-Pexagon-Timestamp required	string <date-time> UTC signature timestamp.
X-Pexagon-Signature required	string^v1=[a-f0-9]{64}$ HMAC-SHA256 signature over timestamp, a period, and the exact raw body.

Request Body schema: application/json
required

event_id

required

string

event_type

required

string

Enum: "order.accepted" "order.rejected" "artwork.failed" "order.shipped"

Value: "order.rejected"

api_version

required

any

Value: "v1"

created_at

required

string <date-time>

required

object

external_order_id required	string (ExternalOrderId) [ 1 .. 100 ] characters ^[A-Za-z0-9][A-Za-z0-9._:/-]*$
code required	string^[a-z][a-z0-9_]*$
message required	string
retryable required	boolean

Responses

Request samples

Payload

Content type

application/json

{"event_id": "string",
"event_type": "order.rejected",
"api_version": "v1",
"created_at": "2019-08-24T14:15:22Z",
"data": {"external_order_id": "VO-000123",
"code": "string",
"message": "string",
"retryable": true
}
}

Order shipment recorded Webhook

Authorizations:

bearerAuth

header Parameters

X-Pexagon-Event-Id required	string Same stable event identifier included in the JSON body.
X-Pexagon-Timestamp required	string <date-time> UTC signature timestamp.
X-Pexagon-Signature required	string^v1=[a-f0-9]{64}$ HMAC-SHA256 signature over timestamp, a period, and the exact raw body.

Request Body schema: application/json
required

event_id

required

string

event_type

required

string

Enum: "order.accepted" "order.rejected" "artwork.failed" "order.shipped"

Value: "order.shipped"

api_version

required

any

Value: "v1"

created_at

required

string <date-time>

required

object

external_order_id

required

string (ExternalOrderId) [ 1 .. 100 ] characters ^[A-Za-z0-9][A-Za-z0-9._:/-]*$

pexagon_order_number

required

string

required

object (Shipment)

shipment_id required	string
carrier required	string [ 1 .. 100 ] characters
service	string or null <= 100 characters
tracking_number required	string [ 1 .. 200 ] characters
tracking_url	string or null <uri>
shipped_at required	string <date-time>

Responses

Request samples

Payload

Content type

application/json

{"event_id": "evt_01K0SHIP",
"event_type": "order.shipped",
"api_version": "v1",
"created_at": "2026-08-02T18:10:00Z",
"data": {"external_order_id": "VO-000123",
"pexagon_order_number": "31842",
"shipment": {"shipment_id": "shp_01K0SHIP",
"carrier": "UPS",
"tracking_number": "1Z999AA10123456784",
"shipped_at": "2026-08-02T00:00:00Z"
}
}
}

Pexagon Order API (1.0.0-draft)

Orders

Submit an order

Authorizations:

header Parameters

Request Body schema: application/jsonrequired

Responses

Response Schema: application/json

Response Schema: application/json

Response Schema: application/json

Response Schema: application/json

Response Schema: application/json

Request samples

Response samples

Look up an order by client external ID

Authorizations:

path Parameters

header Parameters

Responses

Response Schema: application/json

Response samples

Order accepted Webhook

Authorizations:

header Parameters

Request Body schema: application/jsonrequired

Responses

Request samples

Artwork processing failed Webhook

Authorizations:

header Parameters

Request Body schema: application/jsonrequired

Responses

Request samples

Order submission rejected Webhook

Authorizations:

header Parameters

Request Body schema: application/jsonrequired

Responses

Request samples

Order shipment recorded Webhook

Authorizations:

header Parameters

Request Body schema: application/jsonrequired

Responses

Request samples

Request Body schema: application/json
required

Request Body schema: application/json
required

Request Body schema: application/json
required

Request Body schema: application/json
required

Request Body schema: application/json
required