External Shipping Integrations

External shipping integration via the App Store allows developers to integrate a shipping into the same process flow and interaction that a customer would go through integrating and interacting with a native shipping.

The following functions can be achieved via the integration:
Application Registration

In order to start creating an external shipping integration you must first register an account with Linnworks and then log in to http://developer.linnworks.com/ and create a Shipping Integration app. This will provide you with a default manifest which will require you to fill out the below properties.

Manifest Parameters

VendorName Unique name of the shipping, no spaces all upper cases - Must be unique (eg. No shippings that are already integrated through native implementations)
VendorFriendlyName Name of the shipping
VendorLogoURL Link to shipping logo 57x57px
AddNewUserEndpoint Create new integration for a user and default configuration profile for the integration. Note that the same customer may have multiple integrations with the same courier
UserConfigEndpoint Gets the current stage of the user config. The service method returns current stage of the config, description, title and config items the user has to enter. Linnworks will then render this config items on the UI and will send the config item list to the UpdateConfig
UpdateConfigEndpoint Update integration profile config stage with values entered by the user. The ConfigStatus must match the current config stage status
ConfigDeletedEndpoint Endpoint method which is called when the user deletes the integration in linnworks.net
UserAvailableServicesEndpoint Endpoint which should return a list of available services for a given integration profile
GenerateLabelEndpoint Endpoint which generates a Label PNG and associated shipping label documentation. This endpoint method accept a consignment request which contains the shipping address, list of packages and shipping service configuration options. The method will generate a label for each package and return all packages with the matching sequence number
CancelLabelEndpoint Endpoint which should cancel all labels for the consignment by OrderId. If your integration does not support label cancellation implement an error message from this method
CreateManifest Endpoint which is called by linnworks.net when a user files a manifest. The request will contain all order Id to be manifested (filed as the end of day)
PrintManifest If your carrier integration requires printed version of end-of-day manifest, you can generate PDF and the user will be able to print it from linnworks.net
ExtPropertyMap Endpoint which should return the list of extended property mapping values
Quote Endpoint which is called in order to retrieve a list of quotes
Endpoints

While the structure of the URL for the api endpoints doesn’t have to conform to any structure the requests and responses conform to a strict object structure.

Firstly each endpoint must respond within 100 seconds of a request otherwise the connection will be disconnected. You must choose an appropriate batch size for updates and ensure that when providing data it is done quickly and efficiently.

All requests sent and received are expected to be in JSON format. All endpoints apart from ​AddNewUserEndpoint will send the ​AuthorizationToken along with the request object.

All responses should return content-length. Streaming data is not supported. When you want to ignore one of your endpoints, send default response with no items in the response array, but with response code 200.



AddNewUserEndpoint

Create new integration for a user and default configuration profile for the integration.

Note that the same customer may have multiple integrations with the same courier.



Request
AddNewUserEndpoint
Field Name Type Description
Email String Email address of the customer requesting the integration
LinnworksUniqueIdentifier Guid Linnworks Unique Identifier of a user. Each LW account has a unique id
AccountName String Account name being integrated into the system. Will never change and on integration it is suggest that duplicates are checked for. Nb. Customers may expect to have multiple integrations of the same shipping in Linnworks
Sample Request
{
  "Email": "test@mycompany.com",
  "LinnworksUniqueIdentifier": "005d4263-5a0c-43ce-bdc5-526955604107",
  "AccountName": "My Account name"
}


Response
AddNewUserEndpoint
Field Name Type Description
AuthorizationToken String Authorization token of the newly created integration profile. All further requests associated with this integration must have this authorization token
IsError Boolean Indicates if there is an error
ErrorMessage String / null Error message
Sample Response
{
  "AuthorizationToken": "a8e53e86eead4b69beaa0afcc29b67fb",
  "IsError": false,
  "ErrorMessage": null
}




UserConfigEndpoint

Gets the current stage of the user config. The service method returns current stage of the config, description, title and config items the user has to enter.

Linnworks will then render this config items on the UI and will send the config item list to the UpdateConfigEndpoint.



Request
UserConfigEndpoint
Field Name Type Description
AuthorizationToken Guid Authorization token uniquely identifying each integration profile
Sample Request
{
  "AuthorizationToken": "a8e53e86eead4b69beaa0afcc29b67fb"
}


Response
UserConfigEndpoint
Field Name Type Description
IsConfigActive Boolean Identifies whether the integration profile is in Active mode. Meaning the customer completed the integration wizard and can use the integration
ConfigStatus String Configuration stage name. You must provide the same name to the UpdateConfig endpoint
ConfigStage ConfigStage Config stage class
IsError Boolean Indicates if there is an error
ErrorMessage String / null Error message


Config Stage
Field Name Type Description
WizardStepDescription String Description of the configuration stage
WizardStepTitle String Title of the configuration stage
ConfigItems ConfigItem[] List of ConfigItems


Config Item
Field Name Type Description
ConfigItemId String Unique name for the config item (MAX 40 chars)
Name String Value displayed on the user interface
Description String Tooltip text for the config item
GroupName String Config item group name. Config item will be rendered on the UI grouped by this value
SortOrder Integer Sort order of the config item. Config items will be rendered on the screen in this order
SelectedValue String Selected value
RegExValidation String / null RegEx validation
RegExError String / null Error message that will be displayed when RegEx validation fails
MustBeSpecified Boolean Identifies whether the config item must have value specified
ReadOnly Boolean Identifies whether the field is read only
ListValues ConfigItemListItem[] List of ConfigItemListItem. The config item ValueType =5 (LIST) can have a list of available values the user can select from the drop down list
ValueType Integer String = 0,
Integer = 1,
Double = 2,
Boolean = 3,
Password = 4,
List = 5
Config Item List Item
Field Name Type Description
Display String Value displayed in the drop down list
Value String Drop down item value
Sample Response
{
  "IsConfigActive": false,
  "ConfigStatus": "StageStatusName",
  "ConfigStage": {
    "WizardStepDescription": "Description of the stage.",
    "WizardStepTitle": "Title of the wizard Stage",
    "ConfigItems": [
      {
        "ConfigItemId": "ITEM1",
        "Name": "Config Item 1",
        "Description": "Description Item 1",
        "GroupName": "Group item",
        "SortOrder": 1,
        "SelectedValue": "",
        "RegExValidation": null,
        "RegExError": null,
        "MustBeSpecified": true,
        "ReadOnly": false,
        "ListValues": [
          {
            "Display": "List Value 1",
            "Value": "1"
          }
        ],
        "ValueType": 5
      }
    ]
  },
  "IsError": false,
  "ErrorMessage": null
}




UpdateConfigEndpoint

Update integration profile config stage with values entered by the user. The ConfigStatus must match the current config stage status.



Request
UpdateConfigEndpoint
Field Name Type Description
AuthorizationToken Guid Authorization token uniquely identifying each integration profile
ConfigStatus String Current config stage. UserConfig call returns a current stage status. The same status is sent back to the integration web service
ConfigItems ConfigItemValue[] List of config item values


Config Item Value
Field Name Type Description
ConfigItemId String Unique config item id (MAX 40 chars)
SelectedValue String Value entered by the user (MAX 255 chars)
Sample Request
{
  "AuthorizationToken": "a8e53e86eead4b69beaa0afcc29b67fb",
  "ConfigStatus": "StageName",
  "ConfigItems": [
    {
      "ConfigItemId": "ITEM1",
      "SelectedValue": "Itemvalue1"
    },
    {
      "ConfigItemId": "ITEM2",
      "SelectedValue": "Itemvalue2"
    }
  ]
}


Response
UpdateConfigEndpoint
Field Name Type Description
IsError Boolean Indicates if there is an error
ErrorMessage String / null Error message
Sample Response
{
  "IsError": false,
  "ErrorMessage": null
}




ConfigDeleteEndpoint

Method is called when the user deletes the integration in linnworks.net.



Request
ConfigDeleteEndpoint
Field Name Type Description
AuthorizationToken Guid Authorization token uniquely identifying each integration profile
Sample Request
{
  "AuthorizationToken": "a8e53e86eead4b69beaa0afcc29b67fb"
}


Response
ConfigDeleteEndpoint
Field Name Type Description
IsError Boolean Indicates if there is an error
ErrorMessage String / null Error message
Sample Response
{
  "IsError": false,
  "ErrorMessage": null
}




UserAvailableServicesEndpoint

Returns a list of available services for a given integration profile..



Request
UserAvailableServicesEndpoint
Field Name Type Description
AuthorizationToken Guid Authorization token uniquely identifying each integration profile
Sample Request
{
  "AuthorizationToken": "a8e53e86eead4b69beaa0afcc29b67fb"
}


Response
UserAvailableServicesEndpoint
Field Name Type Description
Services CourierService[] List of available services
IsError Boolean Indicates if there is an error
ErrorMessage String / null Error message


Courier Service
Field Name Type Description
ServiceName String Service name as appears to the user
ServiceCode String Service code
ServiceTag String Service tag. Arbitrary value
ServiceGroup String Service grouping name
ServiceUniqueId Guid Unique Identifier for the service. Linnworks will use this ID in the generate consignment label request. It has to be unique for each service
ConfigItems ConfigItem[] Each service can have configuration items associated with it
ServiceProperty ServiceProperty[] Each service has a list of properties


Config Item
Field Name Type Description
ConfigItemId String Unique name for the config item (MAX 40 chars)
Name String Value displayed on the user interface
Description String Tooltip text for the config item
GroupName String Config item group name. Config item will be rendered on the UI grouped by this value
SortOrder Integer Sort order of the config item. Config items will be rendered on the screen in this order
RegExValidation String / null RegEx validation
RegExError String / null Error message that will be displayed when RegEx validation fails
MustBeSpecified Boolean Identifies whether the config item must have value specified
ReadOnly Boolean Identifies whether the field is read only
ListValues ListValue[] List of ListValues. The config item ValueType =5 (LIST) can have a list of available values the user can select from the drop down list
ValueType Integer String = 1,
Integer = 2,
Double = 3,
Boolean = 4,
Password = 4,
List = 5


List Value
Field Name Type Description
Display String Value displayed in the drop down list
Value String Drop down item value


Service Property
Field Name Type Description
PropertyName String Property Name
PropertyValue String Property Value
Sample Request
{
  "Services": [
    {
      "ServiceName": "Fast2Door Next Day",
      "ServiceCode": "CODE1",
      "ServiceTag": "SOMETAG",
      "ServiceGroup": "Fast2Door",
      "ServiceUniqueId": "6a47631504db4d25a25ce6917a1bcad9",
      "ConfigItems": [
        {
          "ListValues": [
            {
              "Display": "Up to 500",
              "Value": "500"
            },
            {
              "Display": "Up to 1000",
              "Value": "1000"
            }
          ],
          "ValueType": 5,
          "ConfigItemId": "InsuranceConver",
          "Name": "Insurance Cover",
          "Description": "Additional Insurance cover",
          "GroupName": "Insurance",
          "SortOrder": 1,
          "SelectedValue": "500",
          "RegExValidation": null,
          "RegExError": null,
          "MustBeSpecified": false,
          "ReadOnly": false
        }
      ],
      "ServiceProperty": [
        {
          "PropertyName": "LABELTAG",
          "PropertyValue": "Next Day"
        }
      ]
    }
  ],
  "IsError": false,
  "ErrorMessage": null
}




GenerateLabelEndpoint

Generate Label PNG and associated shipping label documentation.

This endpoint method accept a consignment request which contains the shipping address, list of packages and shipping service configuration options.

The method will generate a label for each package and return all packages with the matching sequence number.



Request
GenerateLabelEndpoint
Field Name Type Description
AuthorizationToken Guid Authorization token uniquely identifying each integration profile
Name String Customer name
CompanyName String Company name
AddressLine1 String Address Line 1
AddressLine2 String Address Line 2
AddressLine3 String Address Line 3
Town String Address Town / City
Region String Address State / County / Region
CountryCode String Country code ISO 3166-2
PostalCode String Postal code / Zip code
DeliveryNote String Delivery note
Email String Email address of the customer
Phone String Phone number of the customer
OrderId Integer Linnworks order id
OrderReference String Linnworks order reference number
OrderCurrency String Currency code (3 characters)
OrderValue Decimal Order value
PostageCharges Decimal Shipping cost
ServiceId Guid Unique Service Id as defined in UserAvailableServices response
Packages Package[] List of packages
OrderExtendedProperties OrderExtendedProperties[] List of extended properties items mapped to order extended properties
SaveConfigItems ServiceConfigItem[] List of config items value as defined by the user in the service configuration


Package
Field Name Type Description
SequenceNumber Integer Sequence number of a package. Response must contain the same sequence number for each package
PackageWeight Decimal Package weight (grams)
PackageWidth Decimal Package width (cm)
PackageHeight Decimal Package height (cm)
PackageDepth Decimal Package depth (cm)
PackageFormat String Packaging type:
BOX
PARCEL
PACKET
LETTER
Items Item[] Property title


Item
Field Name Type Description
ItemName String Name of the product
ProductCode String SKU
Quantity Integer Item quantity
UnitValue Decimal Product unit cost (OrderCurrency)
UnitWeight Decimal Product unit weight (gram)
Height Decimal Product height (cm)
Width Decimal Product width (cm)
Length Decimal Product length (cm)
ExtendedProperties ExtendedProperty[] Extended property as mapped to linnworks item extended property


Extended Property
Field Name Type Description
Name String Extended Property name as defined
Value String Linnworks item extended property value


OrderExtendedProperties
Field Name Type Description
Name String Extended Property name as defined
Value String Linnworks order extended property value


Service Config Item
Field Name Type Description
ConfigItemId String Config item Id as defined
SelectedValue String Value specified by the user in the config
Sample Request
{
  "AuthorizationToken": "a8e53e86eead4b69beaa0afcc29b67fb",
  "Name": "Customer name",
  "CompanyName": "Company name",
  "AddressLine1": "Great Russell St",
  "AddressLine2": "Bloomsbury",
  "AddressLine3": "",
  "Town": "London",
  "Region": "Greater London",
  "CountryCode": "GB",
  "Postalcode": "WC1B 3DG",
  "DeliveryNote": "Some note",
  "Email": "test@linnworks.com",
  "Phone": "+44 00000000000",
  "OrderId": 100001,
  "OrderReference": "ORDERREFERENCE",
  "OrderCurrency": "GBP",
  "OrderValue": 1,
  "PostageCharges": 1,
  "ServiceId": "6a47631504db4d25a25ce6917a1bcad9",
  "Packages": [
    {
      "SequenceNumber": 0,
      "PackageWeight": 1,
      "PackageWidth": 1,
      "PackageHeight": 1,
      "PackageDepth": 1,
      "PackageFormat": "BOX",
      "Items": [
        {
          "ItemName": "Product 1",
          "ProductCode": "SKU001",
          "Quantity": 1,
          "UnitValue": 1,
          "UnitWeight": 1,
          "Height": 1,
          "Width": 1,
          "Length": 1,
          "ExtendedProperties": [
            {
              "Name": "ExtendedCover",
              "Value": "True"
            }
          ]
        }
      ]
    }
  ],
  "OrderExtendedProperties": [
    {
      "Name": "SafePlace",
      "Value": "Some message"
    }
  ],
  "ServiceConfigItems": [
    {
      "ConfigItemId": "InsuranceConver",
      "SelectedValue": "500"
    }
  ]
}


Response
GenerateLabelEndpoint
Field Name Type Description
LeadTrackingNumber String Lead tracking number for the whole consignment
Cost Decimal Cost of all labels
Currency String Cost currency
Package Package[] List of Package Response classes
IsError Boolean Indicates if there is an error
ErrorMessage String / null Error message


Package
Field Name Type Description
SequenceNumber Integer Package sequence number. Must match to what is in the request
TrackingNumber String Package tracking number
PNGLabelDataBase64 String Base64 PNG label
PDFBytesDocumentationBase64 String[] Each element is Base64 PDF document. If no document must be an empty array. Null will result in error
LabelWidth Decimal Label width in inches
LabelHeight Decimal Label height in inches
Sample Response
{
  "LeadTrackingNumber": "GB1234567891",
  "Cost": 0,
  "Currency": "GBP",
  "Package": [
    {
      "SequenceNumber": 0,
      "TrackingNumber": "GB1234567891",
      "PNGLabelDataBase64": "DJHDD234872376478DDD….",
      "PDFBytesDocumentationBase64": [
        "DJHDD234872376478DDD….",
        "DJHDD234872376478DDD…."
      ],
      "LabelWidth": 4,
      "LabelHeight": 6
    }
  ],
  "IsError": false,
  "ErrorMessage": null
}




CancelLabelEndpoint

Cancels all labels for the consignment by OrderId. If your integration does not support label cancellation implement an error message from this method.



Request
CancelLabelEndpoint
Field Name Type Description
AuthorizationToken Guid Authorization token uniquely identifying each integration profile
OrderReference String Linnworks order reference
Sample Request
{
  "AuthorizationToken": "a8e53e86eead4b69beaa0afcc29b67fb",
  "OrderId": 100001
}


Response
CancelLabelEndpoint
Field Name Type Description
IsError Boolean Indicates if there is an error
ErrorMessage String / null Error message
Sample Response
{
  "IsError": false,
  "ErrorMessage": null
}




CreateManifest

The method is called by linnworks.net when a user files a manifest. The request will contain all order Id to be manifested (filed as the end of day)



Request
CreateManifest
Field Name Type Description
AuthorizationToken Guid Authorization token uniquely identifying each integration profile
OrderId String[] List of OrderIds. Although OrderId is int, note that this array of strings to avoid casting issues
Sample Request
{
  "AuthorizationToken": "a8e53e86eead4b69beaa0afcc29b67fb",
  "OrderId": [
    "100001",
    "100002"
  ]
}


Response
CreateManifest
Field Name Type Description
IsError Boolean Indicates if there is an error
ErrorMessage String / null Error message
ManifestReference String Manifest reference
Sample Response
{
  "IsError": false,
  "ErrorMessage": null,
  "ManifestReference" : "RF24789373331"
}




PrintManifest

If your carrier integration requires printed version of endofday manifest, you can generate PDF and the user will be able to print it from linnworks.net



Request
PrintManifest
Field Name Type Description
AuthorizationToken Guid Authorization token uniquely identifying each integration profile
ManifestReference String Manifest reference
Sample Request
{
  "AuthorizationToken": "a8e53e86eead4b69beaa0afcc29b67fb",
  "ManifestReference": "RF24789373331"
}


Response
PrintManifest
Field Name Type Description
IsError Boolean Indicates if there is an error
ErrorMessage String / null Error message
PDFbase64 String Base64 PDF file
Sample Response
{
  "IsError": false,
  "ErrorMessage": null,
  "PDFbase64": "DJHDD234872376478DDD…."
}




ExtPropertyMap

Get the list of extended property mapping values.



Request
ExtPropertyMap
Field Name Type Description
AuthorizationToken Guid Authorization token uniquely identifying each integration profile
Sample Request
{
  "AuthorizationToken": "a8e53e86eead4b69beaa0afcc29b67fb"
}


Response
ExtPropertyMap
Field Name Type Description
Items ExtendedPropertyMapping[] List of Extended Property Mapping
IsError Boolean Indicates if there is an error
ErrorMessage String / null Error message


Extended Property Mapping
Field Name Type Description
PropertyTitle String Property title
PropertyName String Property Name (MAX 255 chars)
PropertyDescription String Property Description
PropertyType String Property Type:
ORDER
ITEM
Sample Response
{
  "Items": [
    {
      "PropertyTitle": "Safe Place note",
      "PropertyName": "SafePlace1",
      "PropertyDescription": "Safe place note for delivery",
      "PropertyType": "ORDER"
    },
    {
      "PropertyTitle": "Extended Cover flag",
      "PropertyName": "ExtendedCover",
      "PropertyDescription": "Some description",
      "PropertyType": "ITEM"
    }
  ],
  "IsError": false,
  "ErrorMessage": null
}




Quote

Endpoint which should return the available quotes for an order



Request
Quote
Field Name Type Description
AuthorizationToken Guid Authorization token uniquely identifying each integration profile
Name String Customer name
CompanyName String Company name
AddressLine1 String Address Line 1
AddressLine2 String Address Line 2
AddressLine3 String Address Line 3
Town String Address Town / City
Region String Address State / County / Region
CountryCode String Country code ISO 3166-2
PostalCode String Postal code / Zip code
Email String Email address of the customer
Phone String Phone number of the customer
Packages Package[] List of package class
OrderReference String Linnworks order reference number
OrderCurrency String Currency code (3 characters)
OrderValue Decimal Order value
OrderExtendedProperties OrderExtendedProperties[] List of extended properties items mapped to order extended properties


Package
Field Name Type Description
SequenceNumber Integer Sequence number of a package. Response must contain the same sequence number for each package
PackageWeight Decimal Package weight (grams)
PackageWidth Decimal Package width (cm)
PackageHeight Decimal Package height (cm)
PackageDepth Decimal Package depth (cm)
PackageFormat String Packaging type:
BOX
PARCEL
PACKET
LETTER
Items Item[] Property title


Item
Field Name Type Description
ItemName String Name of the product
ProductCode String SKU
Quantity Integer Item quantity
UnitValue Decimal Product unit cost (OrderCurrency)
UnitWeight Decimal Product unit weight (gram)
Height Decimal Product height (cm)
Width Decimal Product width (cm)
Length Decimal Product length (cm)
ExtendedProperties ExtendedProperty[] Extended property as mapped to linnworks item extended property


Extended Property
Field Name Type Description
Name String Extended Property name as defined
Value String Linnworks item extended property value


OrderExtendedProperties
Field Name Type Description
Name String Extended Property name as defined
Value String Linnworks order extended property value
Sample Request
{
  "AuthorizationToken": "a8e53e86eead4b69beaa0afcc29b67fb",
  "Name": "Customer name",
  "CompanyName": "Company name",
  "AddressLine1": "Great Russell St",
  "AddressLine2": "Bloomsbury",
  "AddressLine3": "",
  "Town": "London",
  "Region": "Greater London",
  "CountryCode": "GB",
  "Postalcode": "WC1B 3DG",
  "DeliveryNote": "Some note",
  "Email": "test@linnworks.com",
  "Phone": "+44 00000000000",
  "Packages": [
    {
      "SequenceNumber": 0,
      "Items": [
        {
          "ExtendedProperties": [
            {
              "Name": "ExtendedCover",
              "Value": "True"
            }
          ],
          "ItemName": "Product 1",
          "ProductCode": "SKU001",
          "Quantity": 1,
          "UnitValue": 1,
          "UnitWeight": 1,
          "Height": 1,
          "Width": 1,
          "Length": 1
        }
      ],
      "PackageWeight": 1,
      "PackageWidth": 1,
      "PackageHeight": 1,
      "PackageDepth": 1,
      "PackageFormat": "BOX"
    }
  ],
  "OrderReference": "ORDERREFERENCE",
  "OrderCurrency": "GBP",
  "OrderValue": 1,
  "OrderExtendedProperties": [
    {
      "Name": "SafePlace",
      "Value": "Some message"
    }
  ]
}


Response
Quote
Field Name Type Description
QuoteItems QuoteItem[] List of Quote Item class
IsError Boolean Indicates if there is an error
ErrorMessage String / null Error message


Quote Item
Field Name Type Description
ServiceName String Service name as appears to the user
ServiceCode String Service code
ServiceId Guid Service Id defined in UserAvailableServices
ServiceTag String Service Tag
CollectionDate DateTime Date on which the parcel will be sent / collected
EstimatedDeliveryDate DateTime Estimated delivery date
Cost Decimal Cost of the service
Tax Decimal Service tax
TotalCost Decimal Total cost of the delivery
Currency String Currency code (3 chars)
PropertyItem QuoteProperty[] List of Quote Property class
Options QuoteServiceOption[] List of Quote Service Option class


Quote Property
Field Name Type Description
Title String Property title
Value String Property value


Quote Service Option
Field Name Type Description
OptionName String Option name
OptionValue String Option value
Sample Response
{
  "QuoteItems": [
    {
      "ServiceName": "Fast2Door Next Day",
      "ServiceCode": "CODE1",
      "ServiceId": "6a47631504db4d25a25ce6917a1bcad9",
      "ServiceTag": "SOMETAG",
      "CollectionDate": "/Date(1565283600000)/",
      "EstimatedDeliveryDate": "/Date(1565370000000)/",
      "Cost": 1,
      "Tax": 1,
      "TotalCost": 2,
      "Currency": "GBP",
      "PropertyItem": [
        {
          "Title": "PropertyName",
          "Value": "PropertyValue123"
        }
      ],
      "Options": [
        {
          "OptionName": "OptionName",
          "OptionValue": "OptionValue123"
        }
      ]
    }
  ],
  "IsError": false,
  "ErrorMessage": null
}