Order Structure
The basic JSON order structure for submitting an order to HP Site Flow is shown below
{
"destination": { },
"orderData": {
"items": [
{
"components":[ ]
}
],
"shipments": [
{
"shipTo": { },
"returnAddress": { },
"carrier": { }
}
]
}
}Orders are submitted using a predefined JSON structure, any additional fields or child elements in the structure will be ignored.
The key objects in the order data structure include:
| Object | Description |
|---|---|
| destination | Destination account for the order, for example, the site where the order will be fulfilled. |
| orderData | Contains the main order data, detailed below. |
| items | An array of the items objects contained within the order. At least 1 item is required. |
| components | An array of components that are contained within the order item, for example text or cover |
| shipments | An array of shipments (destinations). These are referenced by each order item, using the shipmentIndex field. At least 1 shipment is required. |
Minimum Valid Order Structure
A minimum order required for a single quantity SKU product with a file would be as follows
{
"destination": {
"name": "myPrintCompany"
},
"orderData": {
"sourceOrderId": "TestOrder",
"items": [
{
"sku": "card.123",
"sourceItemId": "my-card",
"quantity": 1,
"components": [
{
"code": "Card",
"fetch": true,
"path": "http://www.site.com/text.pdf"
}
]
}
],
"shipments": [
{
"shipTo": {
"name": "Peter Pan",
"address1": "17 Disney Way",
"town": "Los Angeles",
"postcode": "12345",
"isoCountry": "US"
},
"carrier": {
"alias": "pickup"
}
}
]
}
}
Full Order Structure
Below is an example of a full-order structure including fields that have default values.
It is not necessary to include all of these fields in the order.
{
"destination": {
"name": "myPrintCompany"
},
"orderData": {
"sourceOrderId": "TestOrder",
"customerName": "Customer Name",
"tags": ["test", "tag1"],
"instructions": "this is a note"
"extraData": {},
"items": [
{
"description": "Photo Book",
"shipmentIndex": 0,
"sourceItemId": "book-123",
"sku": "small book",
"dispatchAlert": "please wrap book 1 in blue paper",
"quantity": 1,
"unitWeight": 100,
"unitCost": 0.25,
"unitPrice": 25,
"barcode": "13243124",
"extraData": {},
"components": [
{
"sourceComponentId": "book-cover-123",
"code": "Cover",
"localFile": false,
"fetch": true,
"path": "http://www.site.com/cover.pdf",
"preflight": true,
"duplicate": 10,
"barcode": "13243124-1",
"attributes": {
"corners": "rounded"
},
"extraData": {}
},
{
"sourceComponentId": "book-text-123",
"code": "Text",
"localFile": false,
"fetch": true,
"path": "http://www.site.com/text.pdf"
"preflight": true,
"duplicate": 10,
"barcode": "13243124-1",
"attributes": {},
"extraData": {}
}
]
}
],
"stockItems": [
{
"code": "Promotional Flyer",
"name": "Promotional Flyer",
"quantity": 1,
"unitPrice": 0.25,
"shipmentIndex": 0
}
],
"shipments": [
{
"sourceShipmentId": "SHIPMENT-13243124-1",
"shipmentIndex": 0,
"shipByDate": "2022-04-30",
"slaDays": 1,
"canShipEarly": true,
"shipTo": {
"name": "Peter Pan",
"companyName": "Disney Corporation",
"address1": "17 Disney Way",
"address2": "",
"address3": "",
"town": "Los Angeles",
"postcode": "34757",
"state": "California",
"isoCountry": "US",
"country": "United States of America",
"email": "peter@disney.com",
"phone": "+12345678910"
},
"returnAddress": {
"name": "Peter Pan",
"companyName": "Disney Corporation",
"address1": "17 Disney Way",
"address2": "",
"address3": "",
"town": "Los Angeles",
"postcode": "34757",
"state": "California",
"isoCountry": "US",
"country": "United States of America",
"email": "peter@disney.com"
},
"carrier": {
"code": "customer",
"service": "pickup",
"alias": "pickup"
},
"attachments": [
{
"path": "http://www.site.com/insert.pdf"
"type": "insert"
}
]
}
]
}
}Field Definitions
Below are specifications for the fields defined above:
Destination
| Field | Required | Default | Options | Description |
|---|---|---|---|---|
| name | true | The account name that is order is to be sent to |
OrderData
| Field | Required | Default | Options | Description |
|---|---|---|---|---|
| sourceOrderId | true | Must be set by the sender and represents their internal order id | ||
| customerName | false | Customer Name | ||
| tags | false | Array of text between "". | ||
| instructions | false | Test to be shown in the Notes section at the Order UI. | ||
| extraData | false | Optional. An object that can be used to store structured data that can be included in postbacks |
OrderData.Items
| Field | Required | Default | Options | Description |
|---|---|---|---|---|
| description | false | Optional. Can provide a description for the order item. Different to the configured product description | ||
| shipmentIndex | false | 0 | An integer that corresponds to one of the items in the shipment array, it will default to the first one so should be ignored for single shipment orders | |
| sourceItemId | true | Unique within the order. Represents the internal item ID | ||
| sku | true | This must be a valid SKU code that has been previously set up in the destination account | ||
| dispatchAlert | false | This message will show at dispatch when the item is scanned. | ||
| quantity | true | 1 | Item Quantity, defaults to 1 | |
| unitWeight | false | unitWeight is the weight of the item. This can override what has been configured on the product. | ||
| barcode | false | Customer specified barcode, can be used if the barcode is already on the artwork provided by the customer | ||
| extraData | false | An object that can be used to store structured data that can be included in postbacks |
OrderData.StockItems
| Field | Required | Default | Options | Description |
|---|---|---|---|---|
| code | true | Stock code for lookup | ||
| name | false | Item name | ||
| quantity | false | 1 | Item Quantity, defaults to 1 | |
| shipmentIndex | false | 0 | An integer that corresponds to one of the items in the shipment array, it will default to the first one so should be ignored for single shipment orders | |
| unitPrice | false | 0 | unitPrice (RRP) is the price the item has been sold to the end consumer for. It is sent to the carrier and is used for customs purposes. |
OrderData.Items.Component
| Field | Required | Default | Options | Description |
|---|---|---|---|---|
| code | true | Used to map this object to the corresponding component in the Site Flow product | ||
| path | true | The artwork for the component. You must set either ‘fetch’ to true or ‘localFile’ to true | ||
| fetch | True if localFile is false | false | If true, the file will be fetched from a URL (in the above ‘path’ field) into Site Flow's cloud storage | |
| localFile | True if fetch is false | false | If true, the file won’t be fetched and must already exist on-site at the print company | |
| preflight | false | false | Tells Site Flow whether to preflight the submitted artwork. This is false if localFile = true | |
| sourceComponentId | false | Provides a field for customer-specified component ID | ||
| duplicate | false | 1 | Number of duplications to make of the component. 1 means no duplication. | |
| barcode | false | The barcode for the component | ||
| attributes | false | A dictionary of key-value pairs that specify attributes that define this component that has been configured in the destination account | ||
| extraData | false | Optional. An object that can be used to store structured data that can be included in postbacks |
OrderData.Shipments
| Field | Required | Default | Options | Description |
|---|---|---|---|---|
| sourceShipmentId | false | Optional field to specify a reference number for the sender’s shipment | ||
| shipmentIndex | false | The index of this shipment (referenced by items.shipmentIndex) | ||
| shipByDate | false | Date that it needs to be shipped, in the format “yyyy-mm-dd” | ||
| slaDays | false | slaDays can be used to override what has been configured on the SKU. PSPs can set a min SLA that will ensure that the item is given an agreed minimum amount of time to be produced. | ||
| canShipEarly | false | true | Whether the shipment can be shipped earlier than shipByDate or not | |
| shipTo.name | true | Shipping Name | ||
| shipTo.companyName | false | Optional. Company Name | ||
| shipTo.address1 | true | Line 1 of Address | ||
| shipTo.address2 | false | Line 2 of Address | ||
| shipTo.address3 | false | Line 3 of Address | ||
| shipTo.town | true | City / Town | ||
| shipTo.postcode | true | Postcode or Zip code | ||
| shipTo.state | false | Optional. State of address | ||
| shipTo.isoCountry | true | 2 Character ISO Country code | ||
| shipTo.phone | false | Phone number for Address. Required for some carriers i.e. Fedex | ||
| returnAddress.name | true | Shipping Name | ||
| returnAddress.companyName | false | Optional. Company Name | ||
| returnAddress.address1 | true | Line 1 of Address | ||
| returnAddress.address2 | false | Line 2 of Address | ||
| returnAddress.address3 | false | Line 3 of Address | ||
| returnAddress.town | true | City / Town | ||
| returnAddress.postcode | false | Postcode or Zip code | ||
| returnAddress.state | false | Optional. State of address | ||
| returnAddress.isoCountry | true | 2 Character ISO Country code | ||
| carrier.alias | true | The alias for the shipping service being used to ship the order | ||
| attachments | false | Allows the attachment of additional files (fetch only) such as packing slips |