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.
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.
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 |
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.
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.
Field Name | Type | Description |
---|---|---|
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 |
{ "Email": "test@mycompany.com", "LinnworksUniqueIdentifier": "005d4263-5a0c-43ce-bdc5-526955604107", "AccountName": "My Account name" }
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 |
{ "AuthorizationToken": "a8e53e86eead4b69beaa0afcc29b67fb", "IsError": false, "ErrorMessage": null }
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.
Field Name | Type | Description |
---|---|---|
AuthorizationToken | Guid | Authorization token uniquely identifying each integration profile |
{ "AuthorizationToken": "a8e53e86eead4b69beaa0afcc29b67fb" }
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 |
Field Name | Type | Description |
---|---|---|
WizardStepDescription | String | Description of the configuration stage |
WizardStepTitle | String | Title of the configuration stage |
ConfigItems | ConfigItem[] | List of ConfigItems |
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 |
Field Name | Type | Description |
---|---|---|
Display | String | Value displayed in the drop down list |
Value | String | Drop down item value |
{ "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 }
Update integration profile config stage with values entered by the user. The ConfigStatus must match the current config stage status.
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 |
Field Name | Type | Description |
---|---|---|
ConfigItemId | String | Unique config item id (MAX 40 chars) |
SelectedValue | String | Value entered by the user (MAX 255 chars) |
{ "AuthorizationToken": "a8e53e86eead4b69beaa0afcc29b67fb", "ConfigStatus": "StageName", "ConfigItems": [ { "ConfigItemId": "ITEM1", "SelectedValue": "Itemvalue1" }, { "ConfigItemId": "ITEM2", "SelectedValue": "Itemvalue2" } ] }
Field Name | Type | Description |
---|---|---|
IsError | Boolean | Indicates if there is an error |
ErrorMessage | String / null | Error message |
{ "IsError": false, "ErrorMessage": null }
Method is called when the user deletes the integration in linnworks.net.
Field Name | Type | Description |
---|---|---|
AuthorizationToken | Guid | Authorization token uniquely identifying each integration profile |
{ "AuthorizationToken": "a8e53e86eead4b69beaa0afcc29b67fb" }
Field Name | Type | Description |
---|---|---|
IsError | Boolean | Indicates if there is an error |
ErrorMessage | String / null | Error message |
{ "IsError": false, "ErrorMessage": null }
Returns a list of available services for a given integration profile..
Field Name | Type | Description |
---|---|---|
AuthorizationToken | Guid | Authorization token uniquely identifying each integration profile |
{ "AuthorizationToken": "a8e53e86eead4b69beaa0afcc29b67fb" }
Field Name | Type | Description |
---|---|---|
Services | CourierService[] | List of available services |
IsError | Boolean | Indicates if there is an error |
ErrorMessage | String / null | Error message |
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 |
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 |
Field Name | Type | Description |
---|---|---|
Display | String | Value displayed in the drop down list |
Value | String | Drop down item value |
Field Name | Type | Description |
---|---|---|
PropertyName | String | Property Name |
PropertyValue | String | Property Value |
{ "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 }
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.
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 |
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 |
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 |
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 |
Field Name | Type | Description |
---|---|---|
Name | String | Extended Property name as defined |
Value | String | Linnworks item extended property value |
Field Name | Type | Description |
---|---|---|
Name | String | Extended Property name as defined |
Value | String | Linnworks order extended property value |
Field Name | Type | Description |
---|---|---|
ConfigItemId | String | Config item Id as defined |
SelectedValue | String | Value specified by the user in the config |
{ "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" } ] }
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 |
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 |
{ "LeadTrackingNumber": "GB1234567891", "Cost": 0, "Currency": "GBP", "Package": [ { "SequenceNumber": 0, "TrackingNumber": "GB1234567891", "PNGLabelDataBase64": "DJHDD234872376478DDD….", "PDFBytesDocumentationBase64": [ "DJHDD234872376478DDD….", "DJHDD234872376478DDD…." ], "LabelWidth": 4, "LabelHeight": 6 } ], "IsError": false, "ErrorMessage": null }
Cancels all labels for the consignment by OrderId. If your integration does not support label cancellation implement an error message from this method.
Field Name | Type | Description |
---|---|---|
AuthorizationToken | Guid | Authorization token uniquely identifying each integration profile |
OrderReference | String | Linnworks order reference |
{ "AuthorizationToken": "a8e53e86eead4b69beaa0afcc29b67fb", "OrderId": 100001 }
Field Name | Type | Description |
---|---|---|
IsError | Boolean | Indicates if there is an error |
ErrorMessage | String / null | Error message |
{ "IsError": false, "ErrorMessage": null }
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)
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 |
{ "AuthorizationToken": "a8e53e86eead4b69beaa0afcc29b67fb", "OrderId": [ "100001", "100002" ] }
Field Name | Type | Description |
---|---|---|
IsError | Boolean | Indicates if there is an error |
ErrorMessage | String / null | Error message |
ManifestReference | String | Manifest reference |
{ "IsError": false, "ErrorMessage": null, "ManifestReference" : "RF24789373331" }
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
Field Name | Type | Description |
---|---|---|
AuthorizationToken | Guid | Authorization token uniquely identifying each integration profile |
ManifestReference | String | Manifest reference |
{ "AuthorizationToken": "a8e53e86eead4b69beaa0afcc29b67fb", "ManifestReference": "RF24789373331" }
Field Name | Type | Description |
---|---|---|
IsError | Boolean | Indicates if there is an error |
ErrorMessage | String / null | Error message |
PDFbase64 | String | Base64 PDF file |
{ "IsError": false, "ErrorMessage": null, "PDFbase64": "DJHDD234872376478DDD…." }
Get the list of extended property mapping values.
Field Name | Type | Description |
---|---|---|
AuthorizationToken | Guid | Authorization token uniquely identifying each integration profile |
{ "AuthorizationToken": "a8e53e86eead4b69beaa0afcc29b67fb" }
Field Name | Type | Description |
---|---|---|
Items | ExtendedPropertyMapping[] | List of Extended Property Mapping |
IsError | Boolean | Indicates if there is an error |
ErrorMessage | String / null | Error message |
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 |
{ "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 }
Endpoint which should return the available quotes for an order
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 |
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 |
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 |
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 |
Field Name | Type | Description |
---|---|---|
Name | String | Extended Property name as defined |
Value | String | Linnworks item extended property value |
Field Name | Type | Description |
---|---|---|
Name | String | Extended Property name as defined |
Value | String | Linnworks order extended property value |
{ "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" } ] }
Field Name | Type | Description |
---|---|---|
QuoteItems | QuoteItem[] | List of Quote Item class |
IsError | Boolean | Indicates if there is an error |
ErrorMessage | String / null | Error message |
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 |
Field Name | Type | Description |
---|---|---|
Title | String | Property title |
Value | String | Property value |
Field Name | Type | Description |
---|---|---|
OptionName | String | Option name |
OptionValue | String | Option value |
{ "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 }