Order Structure

Site Flow Light

Site Guide Tutorial Open Source Software

Site Flow

About API Authentication Order Structure Order Endpoints Postbacks Shipments Errors SDKs Open Source Software Whitepapers

Api reference

Auto Flow Site Flow Pro Site Flow Light

Order Structure

The basic JSON order structure 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

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",
        "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"
                    }
                ]
            }
        ]
    }
}

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"
                }
            }
        ]
    }
}

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	Description
sourceOrderId	`true`	Must be set by the sender and represents their internal order id
customerName	false	Customer Name
extraData	false	Optional. An object that can be used to store structured data that can be included in postbacks

OrderData.Items

Field	Required	Default	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	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	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	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