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.
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.
| 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. |
| IsListingSupported | Defines if external channel supports listing functionality via Linnworks. This needs to be set to 1 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. |
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.
| Field Name | Type | Description |
|---|---|---|
| LinnworksUniqueIdentifier | GUID | Uniqueidentifer of the linnworks customer's account. Will never change. |
| 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. |
{
"LinnworksUniqueIdentifier": "005d4263-5a0c-43ce-bdc5-526955604107", "Email": "test@mycompany.com",
"AccountName": "My Account name" }
| 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. |
{
"Error": null, "AuthorizationToken": "a8e53e86eead4b69beaa0afcc29b67fb", }
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.
| Field Name | Type | Description |
|---|---|---|
| AuthorizationToken | String | Token that you generated for this customer. |
{
"AuthorizationToken": "a8e53e86eead4b69beaa0afcc29b67fb", }
| 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. |
| 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. |
| Field Name | Type | Description |
|---|---|---|
| Display | String | Visible value. |
| Value | String | Value String SelectedValue. |
{
"Error": null,
"StepName": "AddCredentials",
"WizardStepDescription": "This is where you add your website credentials",
"WizardStepTitle": "Add Credentials",
"ConfigItems": [
{"ConfigItemId": "APIKey",
"Name": "API Key",
"Description": "Website API Key",
"GroupName": "API Credentials",
"SortOrder": 1,
"SelectedValue": "AnApiKeyGoesHere",
"RegExValidation": null,
"RegExError": null,
"MustBeSpecified": true,
"ReadOnly": false,
"ListValues": [],
"ValueType": "PASSWORD"
},
{"ConfigItemId": "APISecretKey",
"Name": "API Secret Key",
"Description": "Website API Secret Key",
"GroupName": "API Credentials",
"SortOrder": 2,
"SelectedValue": "MYSuperSecretKey",
"RegExValidation": null,
"RegExError": null,
"MustBeSpecified": true,
"ReadOnly": false,
"ListValues": [],
"ValueType": "PASSWORD"
},
{"ConfigItemId": "IsOauth",
"Name": "Is Oauth",
"Description": "Defines if the authentication type is Oauth",
"GroupName": "API Settings",
"SortOrder": 3,
"SelectedValue": "False",
"RegExValidation": null,
"RegExError": null,
"MustBeSpecified": true,
"ReadOnly": false,
"ListValues": [],
"ValueType": "BOOLEAN"
},
{"ConfigItemId": "Version",
"Name": "Version",
"Description": "Version of the API",
"GroupName": "API Settings",
"SortOrder": 3,
"SelectedValue": "False",
"RegExValidation": null,
"RegExError": null,
"MustBeSpecified": true,
"ReadOnly": false,
"ListValues": [
{"Display": "1.6 - Stable",
"Value": "1.6.0"},
{ "Display": "1.6 - Beta",
"Value": "1.6.1" },
{ "Display": "1.5 - Stable",
"Value": "1.5.0"}],
"ValueType": "LIST"}
]}
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.
| 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. |
{
"StepName": "AddCredentials",
"ConfigItems": [
{"ConfigItemId": "APIKey",
"Name": "API Key",
"Description": "Website API Key",
"GroupName": "API Credentials",
"SortOrder": 1,
"SelectedValue": "AnApiKeyGoesHere",
"RegExValidation": null,
"RegExError": null,
"MustBeSpecified": true,
"ReadOnly": false,
"ListValues": [],
"ValueType": "PASSWORD"
},
{"ConfigItemId": "APISecretKey",
"Name": "API Secret Key",
"Description": "Website API Secret Key",
"GroupName": "API Credentials",
"SortOrder": 2,
"SelectedValue": "MYSuperSecretKey",
"RegExValidation": null,
"RegExError": null,
"MustBeSpecified": true,
"ReadOnly": false,
"ListValues": [],
"ValueType": "PASSWORD"
},
{"ConfigItemId": "IsOauth",
"Name": "Is Oauth",
"Description": "Defines if the authentication type is Oauth",
"GroupName": "API Settings",
"SortOrder": 3,
"SelectedValue": "False",
"RegExValidation": null,
"RegExError": null,
"MustBeSpecified": true,
"ReadOnly": false,
"ListValues": [],
"ValueType": "BOOLEAN"}],
"AuthorizationToken": "1fdea65984c54a91ae8549de68844ca9"
}
| 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. |
{
"Error": null,
"StepName": "OrderSetup",
"WizardStepDescription": "Definition of tax settings and items to return",
"WizardStepTitle": "Order Setup",
"ConfigItems": [
{
"ConfigItemId": "PriceIncTax",
"Name": "Price Includes Tax",
"Description": "Defines if the price of an item includes tax",
"GroupName": "Tax",
"SortOrder": 1,
"SelectedValue": "False",
"RegExValidation": null,
"RegExError": null,
"MustBeSpecified": true,
"ReadOnly": false,
"ListValues": [],
"ValueType": "BOOLEAN"
},
{"ConfigItemId": "DownloadVirtualItems",
"Name": "Download Virtual Items",
"Description": "Check to allow the download of virtual items",
"GroupName": "Items",
"SortOrder": 2,
"SelectedValue": "False",
"RegExValidation": null,
"RegExError": null,
"MustBeSpecified": false,
"ReadOnly": false,
"ListValues": [],
"ValueType": "BOOLEAN"}]
}
| Field Name | Type | Description |
|---|---|---|
| AuthorizationToken | String | Authorization Token from the customers integration. |
{
"AuthorizationToken": "0dfdbaf3e4d5434f825e774e31bcc148"
}
| Field Name | Type | Description |
|---|---|---|
| Error | String | If there was an error with the request. |
| ShippingTags | ShippingTag[] | See Shipping Tag table. |
| 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. |
{
"Error": null,
"ShippingTags": [
{"Tag": "RM CLR01",
"FriendlyName": "Royal Mail First Class",
"Site": ""},
{"Tag": "RM_SpecialDelivery_9am",
"FriendlyName": "Royal Mail Special Delivery",
"Site": ""},
{"Tag": "dpd",
"FriendlyName": "DPD - Next Day",
"Site": ""},
{"Tag": "fedex_ground",
"FriendlyName": "Fedex - Ground",
"Site": ""},
{"Tag": "matrix_rate_10221",
"FriendlyName": "Some other service",
"ListValues": [],
"Site": ""}]
}
| Field Name | Type | Description |
|---|---|---|
| AuthorizationToken | String | Authorization Token from the customers integration. |
{
"AuthorizationToken": "0dfdbaf3e4d5434f825e774e31bcc148"
}
| Field Name | Type | Description |
|---|---|---|
| Error | String | If there was an error with the request. |
| PaymentTags | PaymentTags[] | See Payment Tag table. |
| 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. |
{
"Error": null,
"PaymentTags": [
{"Tag": "paypal_verified",
"FriendlyName": "PayPal",
"Site": ""},
{"Tag": "mastercard",
"FriendlyName": "Credit Card - Master Card",
"Site": ""},
{"Tag": "credit_unknown",
"FriendlyName": "Credit Card - Unknown",
"Site": ""},
{"Tag": "bank",
"FriendlyName": "Bank payments",
"Site": ""}]
}
| Field Name | Type | Description |
|---|---|---|
| AuthorizationToken | String | Authorization Token from the customers integration. |
{
"AuthorizationToken": "0dfdbaf3e4d5434f825e774e31bcc148"
}
| Field Name | Type | Description |
|---|---|---|
| Error | String | If there was an error with the request. |
{
"Error": "User config does not exist"
{
| Field Name | Type | Description |
|---|---|---|
| AuthorizationToken | String | Authorization Token from the customers integration. |
{
"AuthorizationToken": "0dfdbaf3e4d5434f825e774e31bcc148"
}
| Field Name | Type | Description |
|---|---|---|
| Error | String | If there was an error with the request. |
{
"Error": "User config does not exist"
{
| 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. |
{
"PageNumber": 1,
"UTCTimeFrom": "2016-08-26T09:43:14Z",
"AuthorizationToken": "f989a881a6a241d5ab81b4b03f3730f1"
{
| 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. |
| 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:
|
| 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. |
| 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. |
| 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. |
| Field Name | Type | Description |
|---|---|---|
| Name | String | Unique per order option Name. |
| Value | String | Option Value. |
| 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". |
| 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. |
{
"Error": null,
"HasMorePages": true,
"Orders": [{
"BillingAddress": {
"FullName": "Mr Billing Billington",
"Company": "Linn Systems Ltd",
"Address1": "2-4 Southgate",
"Address2": "",
"Address3": "",
"Town": "Chichester",
"Region": "West Sussex",
"PostCode": "PO19 8DJ",
"Country": "United Kingdom",
"CountryCode": "GB",
"PhoneNumber": "00000000002",
"EmailAddress": "test@test.com"
},
"DeliveryAddress": {
"FullName": "Mr Testing Testington",
"Company": "Linn Systems Ltd",
"Address1": "2-4 Southgate",
"Address2": "",
"Address3": "",
"Town": "Chichester",
"Region": "West Sussex",
"PostCode": "PO19 8DJ",
"Country": "United Kingdom",
"CountryCode": "GB",
"PhoneNumber": "00000000001",
"EmailAddress": "test@test.com"
},
"OrderItems": [{
"TaxCostInclusive": true,
"UseChannelTax": false,
"IsService": false,
"OrderLineNumber": "0",
"SKU": "ChannelProduct_0",
"PricePerUnit": 0.731495563281465,
"Qty": 479904921,
"TaxRate": 20.0,
"LinePercentDiscount": 0.0,
"ItemTitle": "Title for MyReference-2ChannelProduct_0",
"Options": [{
"Name": "Colour",
"Value": "Red"
}]}],
"ExtendedProperties": [{
"Name": "Prop0",
"Value": "Val0",
"Type": "Info"
}],
"Notes": [{
"Note": "A customer has left a note",
"NoteEntryDate": "2016-08-26T13:28:05Z",
"NoteUserName": "Channel",
"IsInternal": false
}],
"Site": "",
"MatchPostalServiceTag": "Royal Mail First Class",
"MatchPaymentMethodTag": "PayPal",
"PaymentStatus": "PAID",
"ChannelBuyerName": "A Channel Buyer Name",
"ReferenceNumber": "MyReference-2",
"ExternalReference": "MyExternalReference-1",
"SecondaryReferenceNumber": null,
"Currency": "GBP",
"ReceivedDate": "2016-08-26T13:23:05.1678193Z",
"DispatchBy": "2016-09-05T13:28:05.1678193Z",
"PaidOn": "2016-08-26T13:19:05.1678193Z",
"PostalServiceCost": 0.818234497130958,
"PostalServiceTaxRate": 20.0,
"UseChannelTax": false
}]
}
| Field Name | Type | Description |
|---|---|---|
| AuthorizationToken | String | Authorization Token from the customers integration. |
| Orders | DespatchOrder[] | See Despatch Order Table. |
| 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. |
| 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. |
{
"Orders": [{
"ReferenceNumber": "12345",
"ShippingVendor": "Royal Mail",
"ShippingMethod": "First Class",
"TrackingNumber": "TrackingNumber 1",
"SecondaryTrackingNumbers": null,
"ProcessedOn": "2016-08-29T07:49:51.5036339Z",
"Items": [{
"SKU": "SKU1234",
"OrderLineNumber": "1",
"DespatchedQuantity": 2
},
{
"SKU": "SKU1235",
"OrderLineNumber": "2",
"DespatchedQuantity": 2
}]
}],
"AuthorizationToken": "b7f4ee81bc4e4363adcd00eced0ea471"
}
| Field Name | Type | Description |
|---|---|---|
| Error | String | If there was an error with the request. |
| Orders | Order[] | See Despatch Order Response table. |
| Field Name | Type | Description |
|---|---|---|
| Error | String | If there was an error with the request. |
| ReferenceNumber | String | Reference number of the order. |
{
"Error": null,
"Orders": [{
"Error": "Despatch failed for some reason",
"ReferenceNumber": "12345"}]
}
| Field Name | Type | Description |
|---|---|---|
| AuthorizationToken | String | Authorization Token from the customers integration. |
| PageNumber | Int | Current page number in the fetch sequence, starts from 1. |
{
"AuthorizationToken": "0dfdbaf3e4d5434f825e774e31bcc148",
"PageNumber": 1
}
| 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. |
| 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. |
{
"Error": null,
"HasMorePages": true,
"Products": [{
"SKU": "ChannelProduct_1",
"Title": "Channel Tile of product ChannelProduct_1",
"Quantity": 68,
"Price": 9.15,
"Reference": "12458"}]
}
| Field Name | Type | Description |
|---|---|---|
| AuthorizationToken | String | Authorization Token from the customers integration. |
| Products | Product[] | See Inventory Product table. |
| Field Name | Type | Description |
|---|---|---|
| SKU | String | Product SKU. |
| Reference | String | Product Reference, e.g. Internal product id. |
| Quantity | Int | New available quantity. |
{
"Products": [{
"SKU": "ABC1234",
"Reference": "122440",
"Quantity": 10
}],
"AuthorizationToken": "4d1aa44d211641a48da9ae269ff68975"
}
| 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. |
{
"Error": null,
"Products": [{
"Error": "SKU does not exist",
"SKU": "MyNonExistantSKU"
}]
}
| Field Name | Type | Description |
|---|---|---|
| AuthorizationToken | String | Authorization Token from the customers integration. |
| Products | Product[] | See Price Product table. |
| 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. |
{
"Products": [{
"SKU": "ABC1234",
"Reference": "122440",
"Price": 10.99,
"Tag": ""
}],
"AuthorizationToken": "4d1aa44d211641a48da9ae269ff68975"
}
| Field Name | Type | Description |
|---|---|---|
| Error | String | If there was an error with the request. |
| Products | Product[] | See PriceProduct Response table. |
| Field Name | Type | Description |
|---|---|---|
| SKU | String | Product Unique SKU |
| Error | String | If there was an error with the product update. |
{
"Error": null,
"Products": [{
"Error": "SKU does not exist",
"SKU": "MyNonExistantSKU"
}]
}
| Field Name | Type | Description |
|---|---|---|
| AuthorizationToken | String | Authorization Token from the customers integration. |
{
"AuthorizationToken": "0dfdbaf3e4d5434f825e774e31bcc148"
}
| 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 |
| 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 |
{
"Error": null,
"CanCancel": true,
"CanCancelOrderLines": true,
"CanCancelOrderLinesPartially": true,
"AutomaticRefundOnCancel": false,
"CanRefund": true,
"CanAttachRefundToItem": true,
"CanAttachRefundToService": false,
"RefundShippingTypes": 0,
"CanRefundAdditionally": false,
"CanReturn": false,
}
| Field Name | Type | Description |
|---|---|---|
{
}
| 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. |
| 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. |
| 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" |
| 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 |
| 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. |
| 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. |
| Field Name | Type | Description |
|---|---|---|
| Name | String | E.g. Main Image, Thumbnail, Basket, Large Image etc. |
| ImageTagType | ImageTagType | See in ImageListingType how it is used. |
| Flag | Numeric Value | Description |
|---|---|---|
| SingleTag | 1 | Only one main image can be selected. |
| MultiTag | 2 | Multiple main images can be selected. |
| 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. |
{
"Error": null,
"Settings": [
{
"GroupName": "VARIATION",
"ConfigItemId": "VariationTheme",
"Subtitle": "General",
"SubTitleSortOrder": 1,
"ItemSortOrder": 1,
"Description": "Theme used for variation. Cannot be changed once config created",
"FriendlyName": "Variation Theme",
"MustBeSpecified": false,
"ExpectedType": "STRING",
"ValueOptions": ["Color", "Size", "Color-Size"],
"InitialValues": [],
"IsMultiOption": false,
"ValueFromOptionsList": true,
"RegExValidation": "",
"RegExError": "",
"IsWizardOnly": true
},
{
"GroupName": "RETURN",
"ConfigItemId": "ReturnCost",
"Subtitle": "General:",
"SubTitleSortOrder": 1,
"ItemSortOrder": 1,
"Description": "Please select who will cover return shipping cost",
"FriendlyName": "Return paid by:",
"MustBeSpecified": true,
"ExpectedType": "STRING",
"ValueOptions": ["Buyer", "Seller"],
"InitialValues": ["Buyer"],
"IsMultiOption": false,
"ValueFromOptionsList": true,
"RegExValidation": "",
"RegExError": "",
"IsWizardOnly": false
},
{
"GroupName": "RETURN",
"ConfigItemId": "ReturnDays",
"Subtitle: "General":",
"SubTitleSortOrder": 1,
"ItemSortOrder": 2,
"Description": "Please select number of days after sale return can be submitted within",
"FriendlyName": "Return within:",
"MustBeSpecified": true,
"ExpectedType": "INT",
"ValueOptions": [7, 14, 30, 60, 90],
"InitialValues": [14],
"IsMultiOption": false,
"ValueFromOptionsList": true,
"RegExValidation": "",
"RegExError": "",
"IsWizardOnly": false
},
{
"GroupName": "SHIPPING",
"ConfigItemId": "ShippedFromCountry",
"Subtitle": "General settings:",
"SubTitleSortOrder": 1,
"ItemSortOrder": 1,
"Description": "",
"FriendlyName": "Country:",
"MustBeSpecified": false,
"ExpectedType": "STRING",
"ValueOptions": ["United Kingdom", "USA"],
"InitialValues": [],
"IsMultiOption": false,
"ValueFromOptionsList": true,
"RegExValidation": "",
"RegExError": ""
,
"IsWizardOnly": false
},
"GroupName": "SHIPPING",
"ConfigItemId": "ShippedFromTown",
"Subtitle": "General settings:",
"SubTitleSortOrder": 1,
"ItemSortOrder": 2,
"Description": "",
"FriendlyName": "Town:",
"MustBeSpecified": false,
"ExpectedType": "STRING",
"ValueOptions": [],
"InitialValues": [],
"IsMultiOption": false,
"ValueFromOptionsList": false,
"RegExValidation": "",
"RegExError": "",
"IsWizardOnly": false
},
"GroupName": "SHIPPING",
"ConfigItemId": "ShippedFromPostCode",
"Subtitle": "General settings:",
"SubTitleSortOrder": 1,
"ItemSortOrder": 3,
"Description": "",
"FriendlyName": "Postcode:",
"MustBeSpecified": false,
"ExpectedType": "STRING",
"ValueOptions": [],
"InitialValues": [],
"IsMultiOption": false,
"ValueFromOptionsList": false,
"RegExValidation": "",
"RegExError": "",
"IsWizardOnly": false
},
"GroupName": "SHIPPING",
"ConfigItemId": "DomesticShippingExcl",
"Subtitle: "Domestic",
"SubTitleSortOrder": 2,
"ItemSortOrder": 1,
"Description": "Enter post codes where you do not ship",
"FriendlyName": "Shipping postcodes excluded:",
"MustBeSpecified": false,
"ExpectedType": "STRING",
"ValueOptions": [],
"InitialValues": [],
"IsMultiOption": true,
"ValueFromOptionsList": false,
"RegExValidation": "",
"RegExError": "",
"IsWizardOnly": false
},
"GroupName": "SHIPPING",
"ConfigItemId": "IntShippingExcl",
"Subtitle": "International:",
"SubTitleSortOrder": 3,
"ItemSortOrder": 1,
"Description": "Select countries where you do not ship",
"FriendlyName": "Shipping countries excluded:",
"MustBeSpecified": false,
"ExpectedType": "STRING",
"ValueOptions": ["Republic of Ireland", "France", "Italy", "Spain", "Germany", "Austria","Switzerland", "Sweden" , "Norway", "Finland", "Denmark", "Estonia", "Latvia","Lithuania", "Poland"],
"InitialValues": [],
"IsMultiOption": true,
"ValueFromOptionsList": true,
"RegExValidation": "",
"RegExError": "",
"IsWizardOnly": false
}],
"MaxDescriptionLength":10000,
"ImageSettings":
{
"Type":2,
"MaxImages":100,
"MaxVariantImages":4,
"ImageTags":[{
"Name":"Main_image",
"ImageTagType":2
},
{
"Name":"Large_image",
"ImageTagType":2
},
{
"Name":"Thumbnail_image",
"ImageTagType":1
},
{
"Name":"Basket_image",
"ImageTagType":1
}]
},
"MaxCategoryCount":1000,
"MaxCustomAttributeLength":1000,
"IsCustomHtmlSupported":true,
"IsCustomAttributesAllowed":true,
"IsVariationsAllowed":true,
"HasMainVariationPrice":true,
"IsTitleInVariation":false,
"HasVariationAttributeDisplayName":true,
"IsPriceInVariation":true,
"IsShippingListingSpecific":true,
"IsPaymentListingSpecific":true
}
| 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. |
{
"AuthorizationToken": "0dfdbaf3e4d5434f825e774e31bcc148",
"PageNumber": 1
}
| 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. |
| 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. |
| Field Name | Type | Description |
|---|---|---|
| CategoryId | Long | Category ID. |
| CategoryName | String | Category Name |
{
"HasMorePages": false,
"Categories":[
{
"CategoryId": 17,
"CategoryName": "Boots"
},
{
"CategoryId": 18,
"CategoryName": "Flip-flops"
}]
}
| 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. |
| Field Name | Type | Description |
|---|---|---|
| ID | String | ConfigItemId defined in GetConfiguratorSettings. |
| Values | String[] | The value(s) chosen by the customer for this setting. |
{
"AuthorizationToken": "0dfdbaf3e4d5434f825e774e31bcc148",
"CategoryIds": [
"3",
"8"
],
"GeneralSettings":[]
}
| Field Name | Type | Description |
|---|---|---|
| Attributes | ListingCategoryAttribute[] | See ListingCategoryAttribute table. |
| Error | String | Defines if there was an error with the request and returns it. |
| Field Name | Type | Description |
|---|---|---|
| Error | String | Defines if there was an error there was an error with the request and returns it. |
| 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 | String |
Defines where the attribute will be read from. |
| RegExValidation | String |
Currently not used. |
| RegExError | String |
Currently not used. |
| 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. |
| Flag | Numeric Value | Description |
|---|---|---|
| STRING | 1 | String |
| INT | 2 | Integer |
| DECIMAL | 3 | Decimal |
| BOOL | 3 | Boolean |
| DATETIME | 4 | DateTime |
| LIST | 5 | List |
| Flag | Numeric Value | Description |
|---|---|---|
| Child | 1 | Means that the attribute will be read and added to each variation child item. |
| Parent | 2 | 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.. |
{
"Attributes": [
{
"AttribueReadFrom": Parent,
"Description": "Free Shipping",
"ExpectedType": "BOOL",
"FriendlyName": "Free Shipping",
"MaxAttributeUse": 1,
"MustBeSpecified": "Desired",
"RegExError": null,
"RegExValidation": null,
"ValueFromOptionsList": true,
"ValueOptions": [
"true",
"false"
]}
],
"Error": null
| 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. |
{
"AuthorizationToken": "0dfdbaf3e4d5434f825e774e31bcc148",
"ChannelFeedId": "123"
}
| 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. |
| 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. |
| 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. |
| 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. |
| 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. |
{
"Error": null,
"IsFeedReady": true,
"ProductFeeds": [
"{
"
ChannelReferences": [
{
"Reference": "p145-n18-v75",
"SKU": "XYZ-1",
,}
{
"Reference": "p145-n18-v76",
"SKU": ""XYZ-3"
}]
"ExternalListingId": "1122",
"Messages": null,
"SKU": "XYZ",
"TemplateId": 14,
"URL": "http://www.mysite.co.uk/tshirt.html"
}]
}
| 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". |
| Field Name | Type | Description |
|---|---|---|
| ID | String | ConfigItemId defined in GetConfiguratorSettings. |
| Values | String[] | The value(s) chosen by the customer for this setting. |
{
"AuthorizationToken": "0dfdbaf3e4d5434f825e774e31bcc148",
"CategoryIds": [
"3",
"8"
],
"GeneralSettings": [
{
"ID": "VariationTheme"
"Values": ["Color-Size"]
} ]
}
| Field Name | Type | Description |
|---|---|---|
| ID | String | Setting ID. |
| Values | String[] | Values that can be selected for the given Setting ID. |
| 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. |
| 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. |
{
"Error": null,
"MaxVariationAttributes": 50,
"NeededVariations": {}
}
| 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. |
| Flag | Numeric Value | Description |
|---|---|---|
| CREATE | 0 | Create listing |
| UPDATE | 1 | Update listing |
| 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. |
| Field Name | Type | Description |
|---|---|---|
| Url | String | Url to an image. |
| Tags | String[] | Selected tags for the image (e.g "Basket image", "Large image" etc). |
| Field Name | Type | Description |
|---|---|---|
| Price | Double | Shipping price for the shipping method. |
| ShippingMethodID | String | Shipping method id/tag. |
| 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. |
| 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. |
| 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"). |
| 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"). |
| 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"). |
| 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. |
| Field Name | Type | Description |
|---|---|---|
| ID | String | ConfigItemId that was provided in GetConfiguratorSettings call. |
| Value | String[] | Customer selected value for this setting. |
{
"AuthorizationToken": "0dfdbaf3e4d5434f825e774e31bcc148",
"Listings":
[
{
"Attributes":[
{
"AttributeID": "Brand Name",
"AttributeValue": "CoolProducts",
"IsCustomAttribute": false
},
{
"AttributeID": "Condition",
"AttributeValue": "new",
"IsCustomAttribute": false
}],
"Categories": ["3"],
"ConfiguratorId": 13,
"Description": "This is a high quality item",
"ExternalListingId": "",
"Images":[
{
"Tags":["Main_image"],
"Url": "https://server.com/images.linnlive.com/f9a059eb1008300ab7eea8d586dd5000/bf24d3f3-1830-4ad4-ad8e-f01b9bbb00f1.jpg"
},
{
"Tags": ["Main_image"],
"Url": "https://server.com/images.linnlive.com/f9a059eb1008300ab7eea8d586dd5000/bf24d3f3-1830-4ad4-ad8e-f01b9bbb00f1.jpg"
}],
"Price": 10.00,
"Quantity": 1,"SKU": "XYZ",
"ShippingMethods": [
{
}],
"TemplateId": 2,
"Title": "T-shirt",
"VariationOptions": [
{
"Name": "Gender",
"Position": 1,
"Values": [
{
"Position": 1,
"value": "Women"
},
{
"Position": 2,
"value": "Men"
}]
}],
"Variations": [
{
"AttributeSettings": [
{}
],
"Images": [
{
}]
,"OptionValues": [
{
"Name": "Gender",
"Position":1,
"Value": "Women"
}],
"Price": 10.0,
"Quantity": 5,
"SKU": "XYZ-1",
"Title": "Nice Women’s T-shirt. One size."
},
{
"AttributeSettings": [
{}
],
"Images": [
{
}],
"OptionValues": [
{
"Name": "Gender",
"Position":2,
"Value": "Men"
}],
"Price": 10.0,
"Quantity": 3,
"SKU" "XYZ-2",
"Title": "Nice Men’s T-shirt. One size."
}],
"Settings": [
{
"ConfiguratorId": 13,
"Settings": {
"GeneralSettings": [
{
}],
"PaymentMethods": [],
"PaymentSettings": [
{}
],
"ReturnsSettings": [
{
"ID": "ReturnCost",
"Values": ["Buyer"]
},
{ "
ID": "ReturnDays",
"Values": ["14"]
}],
"ShippingSettings": [
{
"ID": "ShippedFromCountry",
"Values": ["United Kingdom"]
},
{
"ID": "ShippedFromTown",
"Values": ["Chichester"]
},
{
"ID": "ShippedFromPostCode",
"Values": ["PO19 8DJ"]
}],
"VariationSettings": [
{
"ID": "VariationTheme",
"Values": ["Color-Size"]
}]
],
"Type": "CREATE"
}
| 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. |
{
"ChannelFeedId": "123",
"Error": null
}
| Field Name | Type | Description |
|---|---|---|
| AuthorizationToken | String | Authorization Token from the customers integration. |
| ExternalListingIds | ListingDeleteData[] | Channel listing data. See ListingDeleteData table. |
| Field Name | Type | Description |
|---|---|---|
| ChannelSKU | String | Channels SKU used in the listing. |
| ExternalListingId | String | Channel listing ID. |
| TemplateId | Integer | Linnworks template ID. |
{
"AuthorizationToken": "0dfdbaf3e4d5434f825e774e31bcc148",
"ExternalListingIds": [
{
"ChannelSKU": "XYZ-1",
"ExternalListingId": "external2033"
"TemplateId": "2"
}]
}
| 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. |
{
"ChannelFeedId": "123"
}
