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 Default Options 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 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. This is a case sensitive field.
dispatchAlert false     This message will show at dispatch when the item is scanned.
quantity true 1   Item Quantity, defaults to 1
unitWeight false Defined in product configuration   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 postback

OrderData.Items.Component

Field Required Default Options Description
code true     Used to map this object to the corresponding component in the Site Flow product of the destination account. This is a case sensitive field.
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 Defined in product configuration   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 postback

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.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 Defined in product configuration   Date that it needs to be shipped, in the format “yyyy-mm-dd”
slaDays false Defined in product configuration   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 as defined in the destination account.
carrier.code false     Optional. To be used when alias is not used. This the carrier code to be used to ship the order as defined in the destination account.
carrier.service false     Optional. To be used when alias is not used. This the shipping service being used to ship the order as defined in the destination account.
attachments false     Allows the attachment of additional files (fetch only) such as packing slips