Basic Structure
The contents of an order submitted to PrintOS Site Flow contains must match the JavaScript Object Notation (JSON) format described on this page
Structure of an order (minimum requirements):
- destination (the account that this order will be submitted to)
- orderData (general information about the order)
- items (one or more items contained within the order)
- components (one or more components of an item)
- shipments (one or more shipping destinations, which can contain one or more items)
- items (one or more items contained within the order)
Example JSON of the minimum order structure:
{
"destination": {
"name": "accountName"
},
"orderData": {
"sourceOrderId": "1234512345",
"items": [
{
"sku": "Business Cards",
"sourceItemId": "1234512346",
"components": [
{
"code": "Content",
"fetch": true,
"path": "http://www.w2psite.com/businessCard.pdf"
}
]
}
],
"shipments": [
{
"shipTo": {
"name": "John Doe",
"companyName": "Acme",
"address1": "1234 Main St.",
"town": "Capitol",
"postcode": "12345",
"isoCountry": "US"
},
"carrier":{
"code": "fedex",
"service": "ground"
}
}
]
}
}
For an order to be valid there are a number of fields that are required (Example above shows the minimum requirement):
- destination.name - (The account name of the Print Service Provider account)
- orderData.sourceOrderId - (This will become the order ID in Site Flow and must be unique)
- orderData.items.sku - (The SKU code for this particular item. Must match an existing SKU)
- orderData.items.sourceItemId - (The internal item Id.)
- orderData.items.components.code - (The Component code for this component. Must match an existing component code for this product)
- orderData.items.components.path - (The location of artwork for this component. Dependent on 'fetch' or 'localFile' values, see below for details)
- orderData.shipments.shipTo - (Shipping information for the order. See table below for required shipTo fields)
- orderData.shipments.carrier.code - (The code for the shipment service being used. Must match an existing carrier code)
- orderData.shipments.carrier.service - (The service name for the shipment service being used. Must match an existing carrier service)
An order JSON can contain multiple items, components and shipments.
To see additional samples go here: JSON Samples
Additional Order Fields
destination fields:
|
Field |
Required |
Default |
Options |
Description |
|---|---|---|---|---|
|
name |
Yes |
|
|
The account name that this order will be sent to |
orderData fields:
|
Field |
Required |
Default |
Options |
Description |
|---|---|---|---|---|
|
printType |
No |
digital |
digital |
|
|
sourceOrderId |
Yes |
|
|
The order ID value of the submitting application |
|
|
No |
|
|
email address to associate with the order. Either the end customer or account holder |
|
misCode |
No |
|
|
Customer ID field for MIS application |
|
amount |
No |
|
|
Price of order |
|
currency |
No |
|
|
Currency code to be used in financials |
|
customerName |
No |
|
|
Name of end customer |
|
purchaseOrderNumber |
No |
|
|
Holds purchase order data |
|
tags |
No |
|
|
String value for additional information about this order |
|
extraData |
No |
|
|
an object that can be used to store additional structured order data |
orderData.items fields:
|
Field |
Required |
Default |
Options |
Description |
|---|---|---|---|---|
|
description |
No |
|
|
General description for the order item |
|
shipmentIndex |
No |
0 |
|
Integer value that links to an order shipment. Not required for orders with a single shipment. |
|
sourceItemId |
Yes |
|
|
A unique ID value that is set by the sending application. Will become the internal item ID |
|
sku |
No |
variable |
|
Contains the SKU code. For orders that do not contain SKUs this will default to variable |
|
quantity |
No |
1 |
|
Quantity of this item that will be produced
|
| printQuantity | No | positive integer | If printQuantity is provided it will be sent to the destination device as the print quantity for that item. If printQuantity is not provided value will default to quantity. printQuantity should be left out of the order JSON If quantity is to be used for imposition etc. | |
|
shrinkWrap |
No |
false |
|
Boolean value that determines if an item will be shrink wrapped or not. |
|
binding |
No |
none |
perfect, saddle, wiro, pur, threadSawn |
Binding method for this item |
|
folding |
No |
none |
half, gate, cross, concert, z, 2, 3 |
Folding method for this item |
|
barcode |
No |
|
|
Barcode value provided by the submitting application. Used when barcode is already present on artwork |
|
extraData |
No |
|
|
Additional object-structured data that can be associated with an item. |
|
tags |
No |
|
|
Freeform string field that provides additional information about an item. |
orderData.items.components fields:
|
Field |
Required |
Default |
Options |
Description |
|---|---|---|---|---|
|
code |
Yes |
|
|
Value used to map this object to the corresponding component in the job management application |
|
path |
Yes |
|
|
Location of the artwork for this component. This value is dependent on either the ‘fetch’ or ‘localFile’ field being set to ‘true’. |
|
fetch |
No |
false |
|
If fetch is set to ‘true’ the artwork will be downloaded from a URL provided in the ‘path’ field into the local storage for the job management application. |
|
localFile |
No |
false |
|
If localFile is set to ‘true’ the artwork for this file will be a locally stored file in the job management’s storage which is referenced in the ‘path’ field. |
|
preflight |
No |
false |
|
Whether or not the artwork file should be preflighted using internal preflighting engine. |
|
sourceComponentId |
No |
|
|
Customer supplied ID for this component |
|
paper |
No |
|
|
Selects a media for this component to be printed on from a pre-defined list in the job management application. |
|
weight |
No |
90gsm |
|
Sets media weight |
|
width |
No |
|
|
Width of component piece. Only needed if ‘sku’ field is set to ‘variable’. |
|
height |
No |
|
|
Height of component piece. Only needed if ‘sku’ field is set to ‘variable’. |
|
pages |
No |
1 |
|
Number of pages for the component. Only needed if ‘sku’ field is set to ‘variable’. |
|
duplicate |
No |
1 |
|
Number of duplications of the component that will be made. ‘1’ means no duplications. |
|
colour.side1 |
No |
none |
4process, blackonly, none |
The colours of side 1 (front) of artwork |
|
colour.side2 |
No |
none |
4process, blackonly, none |
The colours of side 2 (back) of artwork |
|
finish.side1 |
No |
none |
mattlam, glosslam, uvcoat, none |
The finish of side 1 (front) of the artwork |
|
finish.side2 |
No |
none |
mattlam, glosslam, uvcoat, none |
The finish of side 2 (back) of the artwork |
|
attributes |
No |
|
|
A set of key-value pairs that specify additional attributes for this component |
|
extraData |
No |
|
|
Additional object-structured data that can be associated with a component. |
orderData.shipment fields:
|
Field |
Required |
Default |
Options |
Description |
|---|---|---|---|---|
|
sourceShipmentId |
No |
|
|
External application’s reference ID to this shipment |
|
shipmentIndex |
No |
|
|
The index of this shipment. Referenced in the order item by the ‘shipmentIndex’ field. |
|
shipByDate |
No |
|
|
The date that this shipment needs to be shipped by. Format is ‘yyyy-mm-dd’. Only used for products that don’t define the ‘sku’ value. |
| slaDays | No | Set the number of SLA days to produce this shipment item | ||
|
canShipEarly |
No |
true |
|
Boolean value that determines if the job can be shipped earlier than the ‘shipByDate’ date |
|
shipTo.name |
Yes |
|
|
Name of recipient |
|
shipTo.companyName |
No |
|
|
Name of Company |
|
shipTo.address1 |
Yes |
|
|
Line 1 of shipping address |
|
shipTo.address2 |
No |
|
|
Line 2 of shipping address |
|
shipTo.address3 |
No |
|
|
Line 3 of shipping address |
|
shipTo.town |
Yes |
|
|
City or Town of address |
|
shipTo.postcode |
Yes |
|
|
Postal code / zip code |
|
shipTo.state |
No |
|
|
State of address. NOTE: Although this field is not required for order submission, certain countries and shipping methods will require this field for a valid address. |
|
shipTo.isoCountry |
Yes |
|
|
ISO country code (2 digit ID) |
|
shipTo.phone |
No |
|
|
Phone number for shipping contact |
|
returnAddress.name |
No |
|
|
Name of return address shipping recipient |
|
returnAddress.companyName |
No |
|
|
Company name of return address |
|
returnAddress.address1 |
No |
|
|
Line 1 of return shipping address |
|
returnAddress.address2 |
No |
|
|
Line 2 of return shipping address |
|
returnAddress.address3 |
No |
|
|
Line 3 of return shipping address |
|
returnAddress.town |
No |
|
|
City or Town of return address |
|
returnAddress.postcode |
No |
|
|
Postal code / zip code |
|
returnAddress.state |
No |
|
|
State of return address |
|
returnAddress.isoCountry |
No |
|
|
ISO country code (2 digit ID) |
|
carrier.code |
Yes |
|
|
Short code of courier as listed in the job management settings |
|
carrier.service |
Yes |
|
|
Service required by selected carrier |
|
carrier.alias |
No |
|
|
An alias for the carrier (maps to code+service if set up in application) |
|
cost |
No |
|
|
Cost of shipment |
|
attachments |
No |
|
|
Links to additional files needed for shipping (i.e. packing slips) via fetched via URL. |