Endpoint - User Config

This request is made in two situations:

Firstly when a customer is going through the integration wizard to integrate the channel for the first time or when required updates are needed. The wizard StepName should be anything but UserConfig if you are flowing a user through integration steps. To complete the wizard then return the StepName as "UserConfig" this will indicate the wizard is complete and complete the wizard for the user.

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 such as updating an auth token.

This call is not called periodically and only when the user is editing their configuration.

Request

POST

UserConfigRequest

Field NameTypeDescription
AuthorizationTokenStringToken that you generated for this customer.

Sample

{
	"AuthorizationToken": "a8e53e86eead4b69beaa0afcc29b67fb",
}

Response

UserConfigResponse

Field Name

Type

Description

Error

String

Error string if there was an issue with the request.

StepName Required

String

Current Step name, if returned "UserConfig" it will assume that the wizard is complete.

AccountName Required

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 Required

String

Description of the current wizard step.

WizardStepTitle Required

String

User visible title displayed on the integration wizard.

ConfigItems Required

ConfigItem[]

See Config Item table.

GlobalConfigSettings Optional

GlobalConfigSettings

A set of global config settings for the individual integration. These include available price tags as well as options to disable UI config elements if not supported.

These options help sellers easily identify what is supported and what is not rather than raising support cases when something seemingly doesn't work.

The default behavior is that all features are supported if no settings are provided by the integration.

ConfigItem

Field Name

Type

Description

ConfigItemId Required

String

Unique id of either the wizard item or config item.

Description Required

String

Description of the config item or wizard item. Will be displayed in tooltips .

GroupName Required

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 Required

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 Required

Int

Order of config item to be displayed on the UI.

ValueType Required

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.

ListValue

Field Name

Type

Description

Display Required

String

User friendly visible value.

Value Required

String

Key value that Linnworks will then send back in the SelectedValue field on the SaveConfigEndpont.


GlobalConfigSettings

Field Name

Type

Description

PriceTags Optional

String[]

Price tags that are available to be used in conjunction with the price sync. For example this may be SALE_PRICE or UK

  • Formatting*:
  • Maximum Length - 20 Characters - Any longer than this and they will be truncated.
  • Full capitals
  • Instead of spaces either _ or - is used.
  • Do not repeat tags with different casing.

IsPriceChangeVisible Optional

Boolean

Defines if the price change tick box in the config should be visible for the users

True - Price change tick box will be shown False- Price change tick box will be hidden Not provided - Price change tick box will be shown.

IsRefundsVisible Optional

Boolean

Defines if the refunds tick box in the config should be visible for the users

True - Refunds tick box will be shown False- Refundstick box will be hidden Not provided - Refundstick box will be shown.

IsCancellationsVisible Optional

Boolean

Defines if the cancellations tick box in the config should be visible for the users

True - Cancellations tick box will be shown False- Cancellations tick box will be hidden Not provided - Cancellations tick box will be shown.

IsShippingMappingVisible Optional

Boolean

Defines if the shipping mapping button in the channel integrations screen should be enabled for the users.

True - Shipping mapping button will be enabled False- Shipping mapping button will be disabled Not provided - Shipping mapping button will be enabled

IsPaymentMappingVisible Optional

Boolean

Defines if the payment mapping button in the channel integrations screen should be enabled for the users.

True - Payment mapping button will be enabled False- Payment mapping button will be disabled Not provided - Payment mapping button will be enabled

IsInventoryMappingVisible Optional

Boolean

Defines if the inventory mapping button in the channel integrations screen should be enabled for the users.

True - Inventory mapping button will be enabled False- Inventorymapping button will be disabled Not provided - Inventory mapping button will be enabled

IsMultilocationEnabled Optional

Boolean

Defines if the channel supports multi location.

True - Customers UI will be switched to multi location style and inventory update will start providing the Multi location levels False- Customers UI will be classic inventory update style (Multiple Linnworks locations to combined channel quantity) Not provided - Inventory mapping button will be enabled

MultiLocationInventory Conditional

MultiLocationInventory

Object for multi location inventory settings


MultiLocationInventory

Field Name

Type

Description

OrdersLocationIdAlwaysProvided Required

Boolean

Defines if order location location Id is provided for all locations If not always then the location specific mapping will be supplied.

True - Customer will be provided an order location mapping for each specific MLI location

False- Customers will be provided an order location mapping at a global level. If then OrdersLocationIdProvided True provided for a specific location then they will be provided a order location mapping additionally

AutoPopulateLocations Required

Boolean

True - List of locations to the user will be automatically taken from the Locations array. False- If locations array can be null, this allows user input of locations via UI

Locations Conditional

Locations[]

List of MLI locations.


Locations

Field Name

Type

Description

Tag Required

String

Tag will be provided on Inventory update

Friendly Name Required

String

`Name will be provided to the end customer.

OrdersLocationIdProvided Required

Boolean

True - Customer will be provided an order location mapping for the specific location False- Order location mapping for the specific location will be hidden unless OrdersLocationIdAlwaysProvidedis True

Sample

{
  "Error": null,
  "StepName": "AddCredentials",
  "WizardStepDescription": "This is where you add your website credentials",
  "WizardStepTitle": "Add Credentials",
  "GlobalConfigSettings": {
    "PriceTags": [
      "UK",
      "DE",
      "SALE",
      "UK_SALE"
    ],
    "IsShippingMappingVisible": true,
    "IsPriceChangeVisible": true,
    "IsPaymentMappingVisible": false,
    "IsCancellationsVisible": false,
    "IsRefundsVisible": false,
    "IsInventoryMappingVisible": true,
		"IsMultilocationEnabled": true, 
    "MultiLocationInventory":
    {
            "OrdersLocationIdAlwaysProvided": false,
            "AutoPopulateLocations": true, //If false locations array below can be null, this allows user input of locations via UI 
            "Locations": [
                {
                  "Tag": "Location_1",
                  "Friendly Name": "Warehouse One",
                  "OrdersLocationIdProvided": true //This field can override IsMultilocationIsOrdersLocationsSpecific
                },
                {
                  "Tag": "Location_2",
                  "Friendly Name": "Other Warehouse",
                  "OrdersLocationIdProvided": false
                }
            ]
    	},
  },
  "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"
    }
  ]
}