Home API
Resources
Videos Guides Channel Integrations Shipping Integrations
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.
CancelEndpoint Endpoint which is called with details of an order cancellation within linnworks.
RefundEndpoint Endpoint which is called with details of an order refund 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.
IsListingSupported Defines if external channel supports listing functionality via Linnworks. This needs to be set to True if it is supported and the below endpoints need to be provided then.
GetConfiguratorSettingsEndpoint Endpoint which contains settings that are then used to determine the listing screen layout in Linnworks, how Linnworks processes and validates data provided by the customer and which customer settings are required to be filled out by the customer in order to create a successful listing.
GetAttributesByCategoryEndpoint Endpoint which returns a list of required and optional attributes. This is used e.g. when configurator attribute window is opened. Request contains selected customer category ids and filled customer settings that can be used to determine the list of attributes to be returned.
GetVariationsByCategoryEndpoint Endpoint which returns a list of required variation options. This is used e.g. when configurator variation window is opened. Request contains selected customer category ids and filled customer settings that can be used to determine the list of required variations to be returned.
GetCategoriesEndpoint Endpoint which returns a list of categories. This is called e.g. when configurator categories window is first opened, or when categories are refreshed by customer.
ListingUpdateEndpoint Endpoint is used when customer selects a list of items to be created or updated.
ListingDeleteEndpoint Endpoint is used when customer selects a list of items to be deleted.
CheckFeedEndpoint Endpoint that is called to check status of submitted batch for listing creation, update or deletions.
OAuthAuthorizationEndpoint Endpoint that is called to get an access token via OAuth, using client credentials flow and passing in the client id and client secret set in the installation
OAuthScopesRequested Space delimited list of scopes requested when asking for an OAuth token (optional).
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.

If an endpoint is set for OAuthAuthorizationEndpoint, a bearer access token will be requested from this using "client_credentials" as a grant type with the client_id and client_secret set on installation. Any scopes set in OAuthScopesRequested will be sent in this request. Once received, this will be included in all calls in the Authorization Header as "Bearer <accesstoken>"

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.
HidesHeaderAttribute Boolean Determines whether a header-level attribute (e.g. InventorySync) should be hidden from the config. Used in conjunction with the Name property, where Name identifies the attribute to hide.
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 of the order. Valid values:
  • PAID - The order will be downloaded as a paid order in Linnworks
  • UNPAID - The order will be downloaded as an unpaid order in Linnworks
  • CANCELLED - If the order exists in Linnworks, it will be marked as cancelled. If it doesn't exist in Linnworks, it will be ignored
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.
DiscountType String Discount type of the order. Valid values:
  • AllEvenly - The given discount amount will be split evenly across all items and any applicable postage.
  • ItemsThenPostage - The discount amount will be split evenly across all items. Any remaining discount will be applied to the postage where applicable.
  • PostageThenItems - he discount amount will be applied to the postage cost where applicable. Any remaining discount will be split evenly across all items.
Discount Double The amount of discount.
MarketplaceTaxId String Marketplace Tax Id.
BuyerTaxNumber String Tax number of buyer.
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.
Qty Integer Quantity of the product.
TaxRate Decimal Tax rate of the product.
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 DateTime 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 are not allowed.
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 ProductInventory[] See Inventory Product table.
ProductInventory
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 ProductInventoryError[] Products process result.
ProductInventoryError
Field Name Type Description
SKU String Product SKU.
Error String If there was an error with SKU.
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 ProductPrice[] 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 ProductPriceError[] Product price process result.
ProductPriceError
Field Name Type Description
SKU String Product Unique SKU
Error String If there was an error with the product update.
Sample Response


PostSaleOptionsEndpoint

This call is made when creating an RMA or refund request for orders from this channel. It allows you to determine what kinds of refunds and returns are supported on the channel, so that the UI is presented accordingly.

Request
Get PostSale Options Request
Field Name Type Description
AuthorizationToken String Authorization Token from the customers integration.
Sample Request


Response
Get PostSale Options Response
Field Name Type Description
Error String If there was an error with the product update.
CanCancel Boolean Determines whether the channel allows cancelling an order
CanCancelOrderLines Boolean Determines whether the channel allows cancelling individual order lines
CanCancelOrderLinesPartially Boolean Determines whether the channel allows cancelling only part of an order line (not the full quantity)
AutomaticRefundOnCancel Boolean Determines whether the channel will automatically refund an order when it is cancelled. When enabled, this will create a processed refund in Linnworks when an order is cancelled
CanRefund Boolean Determines whether the channel allows refunding an order
CanAttachRefundToItem Boolean Determines whether the channel allows attaching refunds to a particular order line
CanAttachRefundToService Boolean Determines whether the channel allows attaching refunds to service lines
RefundShippingTypes ShippingRefundType Determines how the channel deals with shipping refunds
CanRefundAdditionally Boolean Determines whether the channel allows creating refunds independent of any items/shipping
CanReturn Boolean Determines whether the channel allows creating returns
ShippingRefundType (Flagged Enum)
Flag Numeric Value Description
NotSupported 0 Shipping refunds are not supported
TiedToItem 1 Shipping refunds are only supported when attached to an item
Independent 2 Shipping refunds are supported as independent refunds
Sample Response

GetConfiguratorSettingsEndpoint

This endpoint contains settings that are then used to determine the listing screen layout in Linnworks, how Linnworks processes and validates data provided by the customer and which customer settings are required to be filled out by the customer in order to create a successful listing.

Request
GetConfiguratorSettings Request
Field Name Type Description
Sample Request

Response
ConfiguratorSettingsResponse
Field Name Type Description
Settings CustomerSettings[] See CustomerSettings table. Various settings that are needed for listing creation. E.g. variation settings, returns settings etc. See CustomerSettings table.
MaxDescriptionLength Integer Is used to validate that the description set for the listing is not above the MaxDescriptionLength when the template description is saved.
ImageSettings ListingImage See ListingImage table. Settings that will be applied to images used in listings on given selling channel. See ListingImage table.
MaxCategoryCount Integer Currently does not get used.
MaxCustomAttributeLength Integer Currently does not get used.
IsCustomHtmlSupported Boolean If set to true, will have the description editor on template level that will allow customers to add html descriptions.
IsCustomAttributesAllowed Boolean If set to true allows the customer to add their own custom attribute and value which will be sent to the external application at the time of listing creation / update.
IsVariationsAllowed Boolean If set to true, allows customers to create variation listings. If set to false, variation window on configurator and template window will not display.
HasMainVariationPrice Boolean If set to true and the item is a variation listing, sets the price on the template.
IsTitleInVariation Boolean If set to true and the item is a variation listing, each variation child item can have its own title.
HasVariationAttributeDisplayName Boolean Not being used.
IsPriceInVariation Boolean If set to true and the item is a variation listing, then each variation child item will have its own price on the template.
IsShippingListingSpecific Boolean If true then shipping configurator and template window will display for the customer in Configurator screen. The list of shipping methods the customer can select from will be taken from the Channel Integration -> Channel Shipping (ShippingTagsEndpoint of channel integration endpoint). It will be possible also to set a price for a specific shipping method.
IsPaymentListingSpecific Boolean If true then payment configurator window will display for the customer. The list of payment methods the customer can select from will be taken from the PaymentTagsEndpoint list (channel integration endpoint).
Error String Dislays error if there was an error with the request and returns it.
CustomerSettings
Field Name Type Description
GroupName GroupNameValueType See GroupNameValueType table. This specifies which configurator window this setting will be displayed in. Anything that cannot be classified as "Returns", "Variations" etc – is "General".
ConfigItemId String Unique identifier for the setting. E.g. setting could be: "Site", "Currency", "Item condition" etc.
Subtitle String Name for Subtitle under which settings will be displayed in the window. E.g. "Site" and "Currency" could be displayed under "Account" Subtitle and "Item condition" under "Condition" Subtitle.
SubTitleSortOrder Integer Order in which Subtitle will be displayed in the window. E.g. "Account" could be displayed 1st and "Condition" 2nd.
ItemSortOrder Integer Order in which given setting will be displayed (e.g. "Site" could be displayed before "Currency").
Description String A short description that will be displayed as a tooltip to give the customer an idea of what the setting is used for.
FriendlyName String Is used to display the setting to the customer. E.g. "Site", "Currency", "Item Condition" etc.
MustBeSpecified Boolean Currently not used.
ExpectedType ListingValueType See ListingValueType table. Defines data type for the listing value.
ValueOptions String[] Provides a list of options the customer can select from.
InitialValues String[] Sets the initial value of the setting.
IsMultiOption Boolean Currently not used.
ValueFromOptionsList Boolean Currently not used.
RegExValidation String Currently not used.
RegExError String Currently not used.
IsWizardOnly Boolean Should be set to true, if the setting is used to determine attributes or variations. These settings will need to be set by the customer when a new configurator is created and cannot be changed once the configurator has been created. E.g. if you set "size-colour" theme for variations and created a configurator with this theme and listed some items, later you cannot change the theme to "size" or "colour" in this configurator – as there would be listings already listed using "sizecolour" theme. You could however create a new configurator with just "size" theme.
GroupNameValueType (Flagged Enum)
Flag Numeric Value Description
GENERAL 1 Configurator window called "General"
RETURN 2 Configurator window called "Return"
SHIPPING 3 Configurator window called "Shipping"
PAYMENT 4 Configurator window called "Payment"
VARIATION 5 Configurator window called "Variation"
ListingValueType (Flagged Enum)
Flag Numeric Value Description
STRING 1 Value of type String
INT 2 Value of type Integer
DECIMAL 3 Value of type DateTime
BOOL 4 Value of type Boolean
DATETIME 5 Value of type DateTime
LIST 6 Value of type list
ListingImage
Field Name Type Description
Type ImageListingType See ImageListingType table. Determines how the listing tool will deal with listing images.
MaxImages Integer See in ImageListingType how it is used.
MaxVariantImages Integer See in ImageListingType how it is used.
ImageTags ImageTag[] See ImageTag table. Image option tags that are available on the channel, e.g. "basket image", "large image", "thumbnail image" etc.
ImageListingType (Flagged Enum)
Flag Numeric Value Description
CountTogether 1 Uses MaxImages (see ListingImage) and MaxVariantImages(see ListingImage). For Non variation listings: A max of MaxVariantImages uploaded images will be taken from the stock item and a total of MaxImages images will be selected. For variation listings: The variation parent and each child item will have a section to select images. A total of MaxVariationImages uploaded images from the variation parent stock item will be added to the Main image section. Uploaded images from each variation child stock item will be added to each variation child item section. For each variation child section a max of MaxVariationImages will be taken. Starting from the variation parent images and following on to each variation child images, each Image will be marked as Selected until MaxTotalImages has been reached.
CountMainVariantsSeparately 2 Uses MaxImages and MaxVariantImages. For non variation listings: Uploaded images will be taken from the stock item and a total of MaxImages images will be selected. For variation listings: The Main Images will be taken from the variation parent item and a total of MaxImages will be selected. Uploaded images from each variation child stock item will be added to each variation child item section and a maximum of MaxVariantImages will be selected.
SelectVariationFromMain 3 Uses MaxImages and MaxVariantImages. For non variation listings:Uploaded images will be taken from the stock item and a total of MaxImages images will be selected. For variation listings: The Main Images will be taken from the variation parent item and each variation child item uploaded images and a total of MaxImages will be selected. Uploaded images from each variation child stock item will be added to each variation child item section and a maximum of MaxVariantImages will be selected.
ImageTag
Field Name Type Description
Name String E.g. Main Image, Thumbnail, Basket, Large Image etc.
ImageTagType ImageTagType See in ImageListingType how it is used.
ImageTagType (Flagged Enum)
Flag Numeric Value Description
SingleTag 1 Only one main image can be selected.
MultiTag 2 Multiple main images can be selected.
ImageListingType (Flagged Enum)
Flag Numeric Value Description
CountTogether 1 Uses MaxImages (see ListingImage) and MaxVariantImages(see ListingImage). For Non variation listings: A max of MaxVariantImages uploaded images will be taken from the stock item and a total of MaxImages images will be selected. For variation listings: The variation parent and each child item will have a section to select images. A total of MaxVariationImages uploaded images from the variation parent stock item will be added to the Main image section. Uploaded images from each variation child stock item will be added to each variation child item section. For each variation child section a max of MaxVariationImages will be taken. Starting from the variation parent images and following on to each variation child images, each Image will be marked as Selected until MaxTotalImages has been reached.
CountMainVariantsSeparately 2 Uses MaxImages and MaxVariantImages. For non variation listings: Uploaded images will be taken from the stock item and a total of MaxImages images will be selected. For variation listings: The Main Images will be taken from the variation parent item and a total of MaxImages will be selected. Uploaded images from each variation child stock item will be added to each variation child item section and a maximum of MaxVariantImages will be selected.
SelectVariationFromMain 3 Uses MaxImages and MaxVariantImages. For non variation listings:Uploaded images will be taken from the stock item and a total of MaxImages images will be selected. For variation listings: The Main Images will be taken from the variation parent item and each variation child item uploaded images and a total of MaxImages will be selected. Uploaded images from each variation child stock item will be added to each variation child item section and a maximum of MaxVariantImages will be selected.
Sample Response

GetCategoriesEndpoint

Endpoint which returns a list of categories. This is called e.g. when configurator categories window is first opened, or when categories are refreshed by customer.

Request
ProductCategoriesRequest
Field Name Type Description
AuthorizationToken String Authorization Token from the customers integration.
PageNumber Integer Will start with 1 and if more pages are required to return categories, will increase by 1.
Sample Request

Response
ProductCategoriesResponse
Field Name Type Description
HasMorePages Boolean If true is returned, then new category request will be made with increased PageNumber.
Categories ListingCategory[] See ListingCategory table. List of categories for the provided page number and customer.
Error String Defines if there was an error with the request and returns it.
ListingCategory
Field Name Type Description
CategoryId Long Category ID.
CategoryName String Category Name
Sample Response


GetAttributesByCategoryEndpoint

This endpoint returns a list of required and optional attributes. This is used e.g. when configurator attribute window is opened. Request contains selected customer category ids and filled customer settings that can be used to determine the list of attributes to be returned.

Request
ProductCategoryAttributeRequest
Field Name Type Description
AuthorizationToken String Authorization Token from the customers integration.
CategoryIds String[] Defines the category ids the customer has selected.
GeneralSettings Setting[] See Setting table. Defines the settings the customer has filled out based on what was provided by the developer in the GetConfiguratorSettings call.
Setting
Field Name Type Description
ID String ConfigItemId defined in GetConfiguratorSettings.
Values String[] The value(s) chosen by the customer for this setting.
Sample Request

Response
ProductCategoryAttributeResponse
Field Name Type Description
Attributes ListingCategoryAttribute[] See ListingCategoryAttribute table.
Error String Defines if there was an error with the request and returns it.
ListingCategoryAttribute
Field Name Type Description
ID String Id of the attribute.
FriendlyName String Name of the attribute displayed to the customer in the attributes window.
Description String Is used for the tooltip of the attribute to give the customer additional information to help him understand what this attribute is exactly.
MustBeSpecified MustBeSpecified See MustBeSpecified table. Defines how the attribute will be marked in the attributes window.
ExpectedType String Determines what type of value is expected.
ValueOptions String[] Provides a list of options the customer can select the attribute value from.
ValueFromOptionsList Boolean Currently not used.
MaxAttributeUse Integer Defines how often each attribute can be set by the customer for any given listing. E.g. you might only be allowed to set 1 condition, but have several different Tags.
AttribueReadFrom AttribueReadFrom Defines where the attribute will be read from.
RegExValidation String Currently not used.
RegExError String Currently not used.
MustBeSpecified (Flagged Enum)
Flag Numeric Value Description
Required 1 Means that the attribute has to be set by the customer in order to create the listing and cannot be left empty and will be auto added to the selected attributes in the attributes screen.
Desired 2 Means that the attribute value can remain empty in order to create/update the listing.
ExpectedType (Flagged Enum)
Flag Numeric Value Description
STRING 1 String
INT 2 Integer
DECIMAL 3 Decimal
BOOL 4 Boolean
DATETIME 5 DateTime
LIST 6 List
AttribueReadFrom (Flagged Enum)
Flag Numeric Value Description
Child 0 Means that the attribute will be read and added to each variation child item.
Parent 1 Means that the attribute will be read and added to the variation parent item (if a variation listing).
Optional 2 Means that the customer can decide themselves if it should be read from the parent or each child item..
Sample Response


CheckFeedEndpoint

Endpoint that is called to check status of submitted batch for listing creation, update or deletions.

Request
FeedRequest Request
Field Name Type Description
ChannelFeedId String One of the feed ids returned by the developer from the ListingUpdate or ListingDelete call.
AuthorizationToken String Is used to determine which customer/channel we are asking regarding.
Sample Request

Response
FeedResponse Response
Field Name Type Description
ProductFeeds ProductFeed[] See ProductFeed table. List of products processed with the requested feedid.
IsFeedReady Boolean Lets Linnworks know if the feed has been processed and we know if it has been successful or not.
Error String Defines if there was an error with the request and returns it.

OAuthAuthorizationEndpoint

Endpoint that is called to get an access token via OAuth, using client credentials flow and passing in the client id and client secret set in the installation



Request
parameters
Field Name Type Description
grant_type String Set to client_credentials
client_id String Set to the client id added by the user on installation
client_secret String Set to the client secret added by the user on installation
scope String Set to the OAuthScopesRequested given in the application manifest. Space delimited.
Sample Request

Response
Response
Field Name Type Description
access_token String Valid OAuth2 bearer token
token_type String Should be set to "bearer".
expires_in String Denotes when the access_token expires in seconds.
scope String Space delimited string of the granted scopes.
Sample Response


ProductFeed
Field Name Type Description
Messages ProductMessage[] See ProductMessage table. Any warnings or errors that occurred for the specific sku/listing.
SKU String The SKU that was sent in the initial listing update/delete request.
ExternalListingId String The unique listing id on the channel for this product/listing.
TemplateId Integer The linnworks template id that was sent in the initial listingupdate/delete request.
URL String The url to view the listed product on the channel from within Linnworks listing tool.
ChannelReferences ChannelReference[] See ChannelReference table. List if it is variation listing, single if it is normal listing.
ChannelReference
Field Name Type Description
SKU String SKU that was submitted.
Reference String Same reference that would be returned by the ProductsEndpoint for the listed sku.
ProductMessage
Field Name Type Description
Type ProductFeedMessageType See ProductFeedMessageType table. Type of the message that was returned after listing update/creation.
Message String Content of the message.
ProductFeedMessageType (Flagged Enum)
Flag Numeric Value Description
Error 1 Returned when there was an error during listing update/creation.
Warning 2 Returned when there were warning during listing update/creation.
Recommendation 3 Returned when channel returned recommendations during listing update/creation.
Sample Response (for variation)


GetVariationsByCategoryEndpoint

This endpoint returns a list of required variation options. This is used e.g. when configurator variation window is opened. Request contains selected customer category ids and filled customer settings that can be used to determine the list of required variations to be returned

Request
ProductCategoryVariationsRequest
Field Name Type Description
AuthorizationToken String Authorization Token from the customers integration.
CategoryIds String[] Category IDs customer has selected.
GeneralSettings Setting[] See Setting table. The settings the customer has filled out based on what was provided by the developer in the GetConfiguratorSettings call. Settings to be sent here are those that have GroupName "GENERAL" and "VARIATION".
Setting
Field Name Type Description
ID String ConfigItemId defined in GetConfiguratorSettings.
Values String[] The value(s) chosen by the customer for this setting.
Sample Request

Response
ProductCategoryVariationsResponse
Field Name Type Description
MaxVariationAttributes Integer How many variation attributes (e.g. color, size) can be used for a listing.
NeededVariations ListingCategoryVariation[] See ListingCategoryVariation table. For the selected category IDs and filled in settings, any variation attributes that have to be specified if it is a variarion listing. E.g. if a variation listing was created each variation has to have color and size set. See ListingCategoryVariation table.
Error String Defines if there was an error with the request and returns it.
ListingCategoryVariation
Field Name Type Description
VariationName String Variation attribute name e.g. color, size, gender etc.
Description String Is used for the tooltip of the variation attribute to give the customer additional information to help him understand what this attribute is exactly.
Sample Response

ListingUpdateEndpoint

Endpoint is used when customer selects a list of items to be created or updated.

Request
ProductsListingsRequest
Field Name Type Description
AuthorizationToken String Authorization Token from the customers integration.
Type ListingUpdateType See ListingUpdateType table. Determines if the relevant products need creating or updating on the channel.
Listings ProductListing[] See ProductsListing table. Array of listings for which the above action to be performed.
Settings ConfiguratorGeneralSetting[] See ConfiguratorGeneralSetting table. The filled out customer settings that were provided in ConfiguratorSettings response by the developer.
ListingUpdateType (Flagged Enum)
Flag Numeric Value Description
CREATE 0 Create listing
UPDATE 1 Update listing
ProductListing
Field Name Type Description
ConfiguratorId Integer Is used to lookup settings, if required.
TemplateId Integer Linnworks unique reference.
ExternalListingId Integer Unique listingid.
SKU String Channel SKU.
Title String Listing title.
Description String Listing description.
Quantity Integer Available quantity to sell.
Images ProductImage[] See ProductImage table. List of images for the non variation item along with the selected tags/ list of images for the variation parent item along with the selected tags.
Price Decimal Listing price.
Categories String[] Selected categories.
ShippingMethods ProductShipping[] See ProductShipping table. Selected shipping.
Attributes ListingAttribute[] See ListingAttribute table. Attributes associated with non variation/variation parent item.
Variations ProductVariation[] See ProductVariationtable. List of variation items (will be empty for non variation items).
VariationOptions ProductOption[] See ProductOption table. List of variation options.
ProductImage
Field Name Type Description
Url String Url to an image.
Tags String[] Selected tags for the image (e.g "Basket image", "Large image" etc).
ProductShipping
Field Name Type Description
Price Double Shipping price for the shipping method.
ShippingMethodID String Shipping method id/tag.
ListingAttribute
Field Name Type Description
IsCustomAttribute Boolean Will be false, unless attribute was created by the customer.
AttributeID String Will not be set if it is a custom attribute created by the customer (only available if IsCustomAttributesAllowed is set to true). Attribute id will be based on the ID provided in the GetAttributesByCategory call).
AttributeValue String Value set by the customer for the given attribute.
ProductVariation
Field Name Type Description
SKU String Variation child SKU.
Title String Variation child title.
Quantity Integer Variation child available quantity.
Images ProductImage[] See description above in ProductImage table.
Price Decimal Variation listing price.
OptionValues VariationOption[] See VariationOption table. Option values set for given variation item.
AttributeSettings ListingAttribute[] See ListingAttribute table. List of attributes for this variation child item.
VariationOption
Field Name Type Description
Value ProductOptionValue See ProductOptionValue table. The value set for this variation option for the given variation item (e.g. "S" or "M" ).
Position Integer The position this option name should be used (e.g. size should be before colour).
Name String Option name (e.g. "Size").
ProductOptionValue
Field Name Type Description
Position Integer Which position this option value should be displayed for this option.
Value String Option value (e.g. "S", "M", "L").
ProductOption
Field Name Type Description
Values ProductOptionValue See ProductOptionValue table. All available values associated with this option name.
Position Integer The position this option name should be used (e.g. size should be before colour).
Name String Option name (e.g. "Size").
ConfiguratorGeneralSetting
Field Name Type Description
ConfiguratorId Integer Related configurator Id.
ProductSettings ProductSettings Product Setting.
ProductSettings
Field Name Type Description
PaymentMethods String[] List of payment methods tags selected on the configurator by the customer. Will be empty if IsPaymentListingSpecific is set to false.
GeneralSettings Setting[] See Setting table. List of general settings. Will be empty if not general settings were provided by the developer.
ReturnsSettings Setting[] See Setting table. List of return settings. Will be empty if not return settings were provided by the developer.
ShippingSettings Setting[] See Setting table. List of shipping settings. Will be empty if not return settings were provided by the developer.
PaymentSettings Setting[] See Setting table. List of payment settings. Will be empty if not return settings were provided by the developer.
VariationSettings Setting[] See Setting table. List of variation settings. Will be empty if not return settings were provided by the developer.
AttributeSettings Setting[] Not in use.
Setting
Field Name Type Description
ID String ConfigItemId that was provided in GetConfiguratorSettings call.
Value String[] Customer selected value for this setting.
Sample Request

Response
ProductsListingResponse
Field Name Type Description
ChannelFeedId String Id for the feed that corresponds to the batch of products that were created, updated or deleted. If the channel does not use feeds, a feed id needs to be generated by the external developer.
Error String Defines if there was an error with the request and returns it.
Sample Response

ListingDeleteEndpoint

This endpoint is used when customer selects a list of items to be deleted.

Request
ProductsListingDeleteRequest
Field Name Type Description
AuthorizationToken String Authorization Token from the customers integration.
ExternalListingIds ListingDeleteData[] Channel listing data. See ListingDeleteData table.
ListingDeleteData
Field Name Type Description
ChannelSKU String Channels SKU used in the listing.
ExternalListingId String Channel listing ID.
TemplateId Integer Linnworks template ID.
Sample Request

ProductsListingResponse
Field Name Type Description
ChannelFeedId String ID for the feed that corresponds to the batch of products that were created, updated or deleted. If the channel does not use feeds, a feed id needs to be generated by the external developer.
Error String Defines if there was an error with the request and returns it.
Sample Response

CancelEndpoint

This endpoint is used when the customer cancels an open order in Linnworks.net.

Request
OrderCancelRequest
Field Name Type Description
AuthorizationToken String Authorization Token from the customers integration.
Cancellation OrderCancellation Information about the order/items to cancel.
OrderCancellation
Field Name Type Description
Items OrderCancellationItem[] A collection of order items to cancel on the marketplace.
ReferenceNumber String The order reference number within Linnworks.
ExternalReference String The external reference number within Linnworks. This is usually the marketplace reference.
OrderCancellationItem
Field Name Type Description
SKU String The unique Linnworks SKU of the item.
OrderLineNumber String The order item number for this item. This is usually the marketplace ID for the order item.
CancellationQuantity Integer The quantity of this item to submit for cancellation.
Reason String If the marketplace supports tag-based cancellation reasons, this field will contain the selected tag. Otherwise, it will include the freetext reason submitted by the customer.
SecondaryReason String If the marketplace supports tag-based cancellation reasons, this field will contain the selected sub-tag.
Sample Request

Response
OrderCancelResponse
Field Name Type Description
Error String Defines if there was an error with the request and returns it.
Sample Response

RefundEndpoint

This endpoint is used when the customer refunds an order in Linnworks.net.

Request
OrderRefundRequest
Field Name Type Description
AuthorizationToken String Authorization Token from the customers integration.
Refund OrderRefund Information about the order/items to refund.
OrderRefund
Field Name Type Description
Items OrderRefundItem[] A collection of order items to refund on the marketplace.
ReferenceNumber String The order reference number within Linnworks.
ExternalReference String The external reference number within Linnworks. This is usually the marketplace reference.
RefundShippingAmount Decimal The amount to refund for shipping.
OrderRefundItem
Field Name Type Description
SKU String The unique Linnworks SKU of the item.
OrderLineNumber String The order item number for this item. This is usually the marketplace ID for the order item.
RefundAmount Decimal The amount to submit as a refund for this item.
Reason String If the marketplace supports tag-based refund reasons, this field will contain the selected tag. Otherwise, it will include the freetext reason submitted by the customer.
SecondaryReason String If the marketplace supports tag-based refund reasons, this field will contain the selected sub-tag.
Sample Request

Response
OrderRefundResponse
Field Name Type Description
RefundReference String Returns the created refund reference from the marketplace.
Error String Defines if there was an error with the request and returns it.
Sample Response