External Channel Integrations

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

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

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

Manifest Parameters

ChannelName Unique name of the channel, no spaces all upper cases - Must be unique (eg. No channels that are already integrated through native implementations)
ChannelFriendlyName Name of the channel
ChannelLogoURL Link to channel logo 57x57px
AddNewUserEndpoint Endpoint used for adding new users
UserConfigEndpoint Endpoint used for adding new users. Called when a customer clicks Integrate in the config screen.
SaveConfigEndpoint Endpoint used for either saving the user config or on every wizard step.
ShippingTagsEndpoint Endpoint which should return a list of Shipping tags and friendly names from the channel. For example if a customer selects “NextDay” on the channel.
PaymentTagsEndpoint Endpoint which should return a list of Payment tags and friendly names from the channel. For example if a customer selects “Sage Pay” on the channel.
ConfigDeletedEndpoint Endpoint which is called when a customer deletes the integration from Linnworks.
ConfigTestEndpoint Endpoint which is called when a customer presses test in the channel config. This should verify if the customer's integration is correct.
OrdersEndpoint Endpoint which is called with parameters of PageNumber and UTCTimeFrom and expected to return orders, it is suggested that using last update date of orders is used. This call should return Paid and unpaid orders.
DespatchEndpoint Endpoint which is called with a list of orders that have been despatched within linnworks.
ProductsEndpoint Endpoint which is called with parameters of PageNumber and expected to return a list of products.
InventoryUpdateEndpoint Endpoint which is called with a list of inventory changes to be updated on the channel. Note: Linnworks will only send changesand not the whole feed.
PriceUpdateEndpoint Endpoint which is called with a list of price changes to be updated on the channel. Note: Linnworks will only send changes and not the whole feed.
InventoryUpdateBatchSize Defines the number of inventory updates that can be sent at one time.
PriceUpdateBatchSize Defines the number of price updates that can be sent at one time.
DespatchUpdateBatchSize Defines the number of despatches will be sent at one time.
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 10 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.



Request
AddNewUserEndpoint
Field Name Type Description
LinnworksUniqueIdentifier GUID Uniqueidentifer of the linnworks customer's account. Will never change.
Email String Email of the customer, subject to change.
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 channel in Linnworks.
Sample Request


Response
AddNewUserEndpoint
Field Name Type Description
Error String Error string if there was an issue with the call.
AuthorizationToken String If successful the authorization token string of the customer. This will be used for all subsequent calls.
Sample Response


UserConfigEndpoint

This request is made in two situations:

Firstly when a customer is going through the integration wizard to integrate the channel. To complete the wizard returns “UserConfig” as the step name and this will indicate the wizard is complete.

The second instance is when the config is loaded the call is made to load any dynamic ConfigItems that may be required to show on the Linnworks config UI. SaveConfigEndpoint will be called on each wizard step and when the config is saved.

If the config is loaded and the StepName is not “UserConfig” it will load the config wizard and take them through the stages until “UserConfig” is returned. This can be especially useful if the user is required to go through additional steps down the line.



Request
UserConfigEndpoint
Field Name Type Description
AuthorizationToken String Token that you generated for this customer.
Sample Request


Response
UserConfigEndpoint
Field Name Type Description
Error String Error string if there was an issue with the request.
StepName String Current Step name, if returned “UserConfig” it will assume that the wizard is complete.
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 channel in Linnworks.
WizardStepDescription String Description of the current wizard step.
WizardStepTitle String User visible title displayed on the integration wizard.
ConfigItems ConfigItem[] See Config Item table.


Config Item
Field Name Type Description
ConfigItemId String Unique id of either the wizard item or config item.
Description String Description of the config item or wizard item. Will be displayed in tooltips .
Group Name String Used to group the config or wizard items.
ListValues ListValue[] See List Value table.
MustBeSpecified Boolean Defines if the user must enter this value in the wizard or config.
Name String Visible name on the wizard or config.
ReadOnly Boolean Defines if the field is a visible only field.
RegexError String Message that will be shown to the custmer if wizard field validation does not go through.
RegexValidation String JavaScript Regex validation script.
SelectedValue String Selected value either default value or value selected in the UI when sent back.
Sortorder Int Order of config item to be displayed on the UI.
ValueType String Valid values: STRING, INT, DOUBLE, BOOLEAN, PASSWORD, LIST.
List Value
Field Name Type Description
Display String Visible value.
Value String Value String SelectedValue.
Sample Rsponse


SaveConfigEndpoint

This request is made in two situations:

At the end of every config wizard step as a customer enters / edits the fields and on the config screen if custom config items are supplied back when the step name is “UserConfig”.

Linnworks will provide the entire object that was provided back with the only field ever changing being the SelectedValue. This is passed back cast as string as fields may be of many different types.



Request
SaveConfigEndpoint
Field Name Type Description
AuthorizationToken String Authorization Token from the customers integration.
ConfigItems ConfigItem[] See Config Item table.
StepName String The step name Linnworks thinks it’s on. It’s good to check this field incase wizards get out of sync for any reason.
Sample Request


Response
SaveConfigEndpoint
Field Name Type Description
AuthorizationToken String Authorization Token from the customers integration.
ConfigItems ConfigItem[] See Config Item table.
StepName String The next wizard step name.
WizardStepDescription String Description of the next wizard step.
WizardStepTitle String User visible title displayed on the integration wizard.
Sample Response


ShippingTagsEndpoint

This call is expected to return an array of shipping methods friendly names and their tags to generate a pre-populated list in the config shipping mapping screen.

Request
ShippingTagsEndpoint
Field Name Type Description
AuthorizationToken String Authorization Token from the customers integration.
Sample Request


Response
ShippingTags
Field Name Type Description
Error String If there was an error with the request.
ShippingTags ShippingTag[] See Shipping Tag table.
ShippingTag
Field Name Type Description
Tag String The shipping tag that is supplied on the order.
FriendlyName String Friendly name of the shipping tag.
Site String Site of the shipping tag, this is usually used when the channel has one set of credentials however has multiple sites for example UK, DE, US and so on. Leave blank if this is not applicable.
Sample Response


PaymentTagsEndpoint

This call is expected to return an array of shipping methods friendly names and their tags to generate a pre-populated list in the config shipping mapping screen.

Request
Payment Tags
Field Name Type Description
AuthorizationToken String Authorization Token from the customers integration.
Sample Request


Response
Payment Tags
Field Name Type Description
Error String If there was an error with the request.
PaymentTags PaymentTags[] See Payment Tag table.


Payment Tag
Field Name Type Description
Tag String The payment tag that is supplied on the order.
FriendlyName String Friendly name of the payment tag.
Site String Site of the payment tag, this is usually used when the channel has one set of credentials however has multiple sites for example UK, DE, US and so on. Leave blank if this is not applicable.
Sample Response


ConfigDeletedEndpoint

This call is made when the channel config is deleted from Linnworks. Note that this is a notification of deletion, if there is an error the config will still be deleted from Linnworks.

Request
Config Deleted
Field Name Type Description
AuthorizationToken String Authorization Token from the customers integration.
Sample Request


Response
Config Deleted
Field Name Type Description
Error String If there was an error with the request.
Sample Response


ConfigTestEndpoint

This call is made when the test button is pressed in the user config. It should test the customer's integration is valid. It may also be used in automation jobs to check if there is a constant or global error.

Request
Config Test
Field Name Type Description
AuthorizationToken String Authorization Token from the customers integration.
Sample Request


Response
Config Test
Field Name Type Description
Error String If there was an error with the request.
Sample Response


OrdersEndpoint

This call is made by Linnworks automation to get a list of orders since the last time it requested orders. These calls are made every 10 to 15 minutes usually. The request expects a page result back, if there are a lot of orders to return it is suggested to split the result into pages of 100 maximum.

Request
Orders
Field Name Type Description
AuthorizationToken String Authorization Token from the customers integration.
UTCTimeFrom DateTime Utc date from Linnworks since the last time we had a successful orders request. This may change from Linnworks side if the user want’s to back date the sync. It is suggested that if the channels API has the availability of filtering by the last time the order was updated to use this. Format: ​"yyyy-MM-dd HH:mm:ssZ".
PageNumber Int Page number of the request. Starts from 1.
Sample Request


Response
Orders
Field Name Type Description
Error String If there was an error with the request.
HasMorePages Boolean Indicates if there are more pages after the current page.
Orders Order[] See Order Table.
Order
Field Name Type Description
BillingAddress Address[] See Address Table.
DeliveryAddress Address[] See Address Table.
OrderItems OrderItem[] See Order Item Table.
ExtendedProperties ExtendedProperty[] See Extended Property Table.
Notes Note[] See Note table.
Site String Site of the order, this is usually used when the channel has one set of credentials however has multiple sites for example UK, DE, US and so on. Leave blank if this is not applicable. This field is used in Postal Service and Payment mapping.
MatchPostalServiceTag String Shipping tag used which is used for order mapping to map the channel shipping tag to the Linnworks shipping service.
MatchPaymentMethodTag String Payment tag used which is used for order mapping to map the channel payment tag to the Linnworks payment service.
PaymentStatus String Payment status or the order. Valid values: PAID, UNPAID
ChannelBuyerName String Name of the customer who bought the item. If the channel supports usernames it’s suggested to put the username instead of the actual name of the customer.
ReferenceNumber String Unique reference of the order. If two orders have the same reference then one will be ignored. This field will be sent back when marking orders as despatched.
ExternalReference String External reference is usually the payment gateway transaction id.
Currency String 3 digit ISO 4217 currency code of the order.
ReceivedDate DateTime Date the order was created. Where possible normalize to UTC Format: ​"yyyy-MM-dd HH:mm:ssZ".
DispatchBy DateTime Date the order should be shipped by. Where possible normalize to UTC Format: ​"yyyy-MM-dd HH:mm:ssZ".
PaidOn DateTime Date the order was paid. Where possible normalize to UTC Format: ​"yyyy-MM-dd HH:mm:ssZ".
PostalServiceCost Decimal Postal cost of the order including tax.
PostalServiceTaxRate Decimal Tax rate used for the postal service.
UseChannelTax Boolean If True Linnworks will not overwrite the PostalServiceTaxRate percentage.
Address
Field Name Type Description
FullName String Customer Full Name.
Company String Customer Company.
Address1 String First line of address.
Address2 String Second line of address.
Address3 String Third line of address.
Town String Town.
Region String Area, County, State or a Region.
PostCode String Postal / Zip Code.
Country String Country.
CountryCode String ISO 3166-2 Country Code.
PhoneNumber String Customer's phone number.
EmailAddress String Email Address.
Order Item
Field Name Type Description
TaxCostInclusive Boolean Indicates if the PricePerUnit includes tax.
UseChannelTax Boolean If True Linnworks will not overwrite the tax percentage.
IsService Boolean Indicates if the order line is a service.
OrderLineNumber String Unique per order line number. Any orders with non unique or duplicates will not be saved.
SKU String SKU of the product (used for Mapping).
PricePerUnit Decimal Individual price per unit.
LinePercentDiscount Decimal Percentage line discount.
ItemTitle String Title of the product.
Options Option[] See Option Table.
Option
Field Name Type Description
Name String Unique per order option Name.
Value String Option Value.
Extended Property
Field Name Type Description
Name String Unique per order option Name.
Value String Option Value.
Type String Type of property for example “Shipping”, “Tracking Number”.
Note
Field Name Type Description
Note String Note text, duplicates will be ignored.
NoteEntryDate DateTime Date of the note Format: ​"yyyy-MM-dd HH:mm:ssZ".
NoteUserName String User who entered the note, if left blank “Channel” will be entered.
IsInternal Boolean Indicates if the note is customer visible.
Sample Response


DespatchEndpoint

When an order is despatched in Linnworks this call is made to update the channel with the correct despatch details. Entire orders may be submitted or partial orders depending if the order has been split.

Request
Despatch
Field Name Type Description
AuthorizationToken String Authorization Token from the customers integration.
Orders DespatchOrder[] See Despatch Order Table.
Despatch Order
Field Name Type Description
ReferenceNumber String Unique reference of the order.
ShippingVendor String Shipping Ventor / Carrier.
ShippingMethod String Linnworks shipping method.
TrackingNumber String Tracking Number.
SecondaryTrackingNumbers String Additional Tracking numbers.
ProcessedOn String Date order was processed Format: "yyyy-MM-dd HH:mm:ssZ".
Items Items[] See Despatch Item table.
Despatch Item
Field Name Type Description
SKU String Channel SKU from the order item.
OrderLineNumber String Unique line number from the order item.
DespatchedQuantity int Quantity despatched, due to splits this might be less than the original order and additional quantity may be provided later.
Sample Request


Response
Order Despatch
Field Name Type Description
Error String If there was an error with the request.
Orders Order[] See Despatch Order Response table.
Despatch Order Response
Field Name Type Description
Error String If there was an error with the request.
ReferenceNumber String Reference number of the order.
Sample Response


ProductsEndpoint

This call is used to get a list of Channel products for the purpose of mapping.

Request
Products
Field Name Type Description
AuthorizationToken String Authorization Token from the customers integration.
PageNumber Int Current page number in the fetch sequence, starts from 1.
Sample Request


Response
Products Response
Field Name Type Description
Error String If there was an error with the request.
HasMorePages Boolean Indicates if more pages are expected.
Products Product[] See Product table.
Product
Field Name Type Description
SKU String Product Unique SKU, duplicates will be ignored.
Title String Title of the product.
Quantity Int Current level on the channel.
Price Decimal Current price on the channel.
Reference String Reference from the channel e.g. internal product ID. This will be submitted alongside the SKU in inventory and price updates.
Sample Response


InventoryUpdateEndpoint

This call is made when inventory is updated in Linnworks and is required to push to the channel.

Request
Inventory Update Request
Field Name Type Description
AuthorizationToken String Authorization Token from the customers integration.
Products Product[] See Inventory Product table.
Inventory Product
Field Name Type Description
SKU String Product SKU.
Reference String Product Reference, e.g. Internal product id.
Quantity Int New available quantity.
Sample Request


Response
Inventory Update Response
Field Name Type Description
Error String If there was an error with the request.
Products Product[] See Inventory Product Response table.
SKU String Product Unique SKU, duplicates will be ignored.
Sample Response


PriceUpdateEndpoint

This call is made when inventory price is updated in linnworks and is required to push to the channel.

Request
Price Update Request
Field Name Type Description
AuthorizationToken String Authorization Token from the customers integration.
Products Product[] See Price Product table.
ProductPrice
Field Name Type Description
SKU String Product SKU.
Reference String Product Reference, e.g. Internal product id.
Price Decimal New price
Tag String Price tag, this is free text but can be used to identify different types of Prices for example the Price with no tag could be current selling price, and a tag submitted with “RETAILPRICE” could be the retail price.
Sample Request


Response
Product Price Response
Field Name Type Description
Error String If there was an error with the request.
Products Product[] See PriceProduct Response table.
PriceProduct Response
Field Name Type Description
SKU String Product Unique SKU, duplicates will be ignored.
Error String If there was an error with the product update.
Sample Response