Site Flow Order Structure

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:

ObjectDescription
destinationDestination account for the order, for example, the site where the order will be fulfilled.
orderDataContains the main order data, detailed below.
itemsAn 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

FieldRequiredDefaultOptionsDescription
nametrue  The account name that is order is to be sent to

 

OrderData

FieldRequiredDefaultOptionsDescription
sourceOrderIdtrue  Must be set by the sender and represents their internal order id
customerNamefalse  Customer Name
tagsfalse  Array of text between "".
instructionsfalse  Test to be shown in the Notes section at the Order UI.
extraDatafalse  Optional. An object that can be used to store structured data that can be included in postbacks

 

OrderData.Items

FieldRequiredDefaultOptionsDescription
descriptionfalse  Optional. Can provide a description for the order item. Different to the configured product description
shipmentIndexfalse0 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
sourceItemIdtrue  Unique within the order. Represents the internal item ID
skutrue  This must be a valid SKU code that has been previously set up in the destination account
dispatchAlertfalse  This message will show at dispatch when the item is scanned.
quantitytrue1 Item Quantity, defaults to 1
unitWeightfalse  unitWeight is the weight of the item. This can override what has been configured on the product.
barcodefalse  Customer specified barcode, can be used if the barcode is already on the artwork provided by the customer
extraDatafalse  An object that can be used to store structured data that can be included in postbacks

 

OrderData.StockItems

FieldRequiredDefaultOptionsDescription
codetrue  Stock code for lookup
namefalse  Item name
quantityfalse1 Item Quantity, defaults to 1
shipmentIndexfalse0 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
unitPricefalse0 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

FieldRequiredDefaultOptionsDescription
codetrue  Used to map this object to the corresponding component in the Site Flow product
pathtrue  The artwork for the component. You must set either ‘fetch’ to true or ‘localFile’ to true
fetchTrue if localFile is falsefalse If true, the file will be fetched from a URL (in the above ‘path’ field) into Site Flow's cloud storage
localFileTrue if fetch is falsefalse If true, the file won’t be fetched and must already exist on-site at the print company
preflightfalsefalse Tells Site Flow whether to preflight the submitted artwork. This is false if localFile = true
sourceComponentIdfalse  Provides a field for customer-specified component ID
duplicatefalse1 Number of duplications to make of the component. 1 means no duplication.
barcodefalse  The barcode for the component
attributesfalse  A dictionary of key-value pairs that specify attributes that define this component that has been configured in the destination account
extraDatafalse  Optional. An object that can be used to store structured data that can be included in postbacks

 

OrderData.Shipments

FieldRequiredDefaultOptionsDescription
sourceShipmentIdfalse  Optional field to specify a reference number for the sender’s shipment
shipmentIndexfalse  The index of this shipment (referenced by items.shipmentIndex)
shipByDatefalse  Date that it needs to be shipped, in the format “yyyy-mm-dd”
slaDaysfalse  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.
canShipEarlyfalsetrue Whether the shipment can be shipped earlier than shipByDate or not
shipTo.nametrue  Shipping Name
shipTo.companyNamefalse  Optional. Company Name
shipTo.address1true  Line 1 of Address
shipTo.address2false  Line 2 of Address
shipTo.address3false  Line 3 of Address
shipTo.towntrue  City / Town
shipTo.postcodetrue  Postcode or Zip code
shipTo.statefalse  Optional. State of address
shipTo.isoCountrytrue  2 Character ISO Country code
shipTo.phonefalse  Phone number for Address. Required for some carriers i.e. Fedex
returnAddress.nametrue  Shipping Name
returnAddress.companyNamefalse  Optional. Company Name
returnAddress.address1true  Line 1 of Address
returnAddress.address2false  Line 2 of Address
returnAddress.address3false  Line 3 of Address
returnAddress.towntrue  City / Town
returnAddress.postcodefalse  Postcode or Zip code
returnAddress.statefalse  Optional. State of address
returnAddress.isoCountrytrue  2 Character ISO Country code
carrier.aliastrue  The alias for the shipping service being used to ship the order
attachmentsfalse  Allows the attachment of additional files (fetch only) such as packing slips