Data Import

Table of contents

Introduction

The Looklet data import works by contacting an HTTP endpoint created by the customer. Looklet polls this endpoint for information about items (garments). The data import improves upon the Looklet experience in the following ways:

  • Item Creator Time Saver: Item information is automatically filled in the sidebar.

  • Look Creator Search: Search for items using custom properties.

  • Image Metadata: Custom properties that were imported can be used in Look Creator and exported together with the images as a JSON sidecar file.

HTTP Endpoint Basics

The HTTP endpoints receives the item’s externalId as a parameter. This “external id” is typically the SKU of the item. It’s the barcode scanned into the Item Creator sidebar.

Example URL: https://example.com/something/something?externalId=1400099535764

The request type will be GET and the response should be JSON.

Response Code

Response code “200 OK” should be used if the item was successfully found in the customer system.
Response code “404 Not Found” should be used if the item could not be found.

Any other response code will be treated as failure. This will show as a warning message in Item Creator and the item information sidebar will not be automatically filled as expected.

Authentication

Two types of authentication are supported:

  • Basic auth (username and password)
  • API key header

Basic Auth

Basic auth is also known as username and password auth.

We need the following information

  1. The username, e.g., “Looklet”
  2. The password, e.g., “ZZGFZBH8YTLG76EYK41H”

API Key Header Auth

API key header auth works by sending a custom HTTP header containing an API key.

We need the following information

  1. The header name, e.g., “X-API-KEY” or “api_key”
  2. The header value, e.g., “ZZGFZBH8YTLG76EYK41H”

Response Example

This is an example of what the response from the customer HTTP endpoint should look like:

{
    "id": "1400099535764",
    "properties": {
        "CustomDate1": "2018-01-20",
        "CustomDate2": "2020-12-31",
        "CustomNumber1": "105",
        "CustomNumber2": "3.14",
        "CustomBoolean1": "True",
        "CustomBoolean2": "False",
        "CustomString1": "Custom String Here",
        "CustomString2": ""
    },
    "warnings": [
        "A red warning message to be displayed in Item Creator."
    ],
    "messages": [
        "A green information message to be displayed in Item Creator."
    ],
    "categoryName": "Dress",
    "designerName": "Adidas",
    "batchNames": [
        "example-batch-1",
        "example-batch-2"
    ],
    "preStylingItemIds": [
        "1100099535764",
        "2200099535764",
        "3300099535764"
    ],
    "colorLabelName": "GREEN",
    "fastTrack": false,
    "comment": "This comment will be placed in the text area at the bottom of the the Item Creator sidebar."
}

Response Fields

Field Required Description Auto Creation Editable After Item Creator
id yes The externalId/SKU if the item. Same value as in the externalId request parameter. - -
properties yes Custom properties defined by the customer. Values are always strings in the JSON. They are later interpreted as types date, number, boolean, and string. Requires setup together with Looklet. More documentation about this in the next section. no yes
warnings no Custom warnings to be displayed to the studio operator in Item Creator. Appears with green text and an info icon. - no
messages no Custom messages to be displayed to the studio operator in Item Creator. Appears with red text and a warning icon. - no
categoryName no The name of a single item category such as “Dress” or “Shoes”. Defined together with Looklet. Does not auto create. no no
designerName no The name of the designer. yes no
batchNames no The names of the batches. yes no
preStylingItemIds no The externalIds/SKUs of the items to use for pre styling. - no
colorLabelName no “NONE”, “RED”, “ORANGE”, “YELLOW”, “GREEN”, “BLUE”, or “PURPLE”. Has no meaning to Looklet. For the customer to use as they see fit. no no
fastTrack no Use either “true” or “false”. Defaults to “false” for new items. Decides if the item should be prioritised higher for faster processing. - no
comment no The contents of a comment added to the item. Will be shown in both Item Creator and Look Creator. - no

Properties

The properties field requires an extra setup step. It’s used for custom customer specific properties. The properties need to be configured by Looklet before they import correctly and become searchable in the Look Creator GUI.

We support 4 different types:

Type Format Description
Date “YYYY-MM-DD” ISO standard date without time and zone.
Number “105” or “3.14” Integer or decimal number with a period.
Boolean “True” or “False” A boolean property.
String “arbitrary content” An arbitrary text/string property.

Remember to always pass all external properties for all items. Use “” (the empty string) if the property has no value for the item.

The properties have no maximum length. Pretty much all characters are allowed. Newlines are for example allowed.

Value Auto Creation

The auto creating properties are designerName and batchNames.

If a designer or batch mathcing the provided value does not yet exist, it’s created automatically in the Looklet system.
The values are case-insensitive, meaning “Adidas“ and “aDiDAS“ will result in the same designer. The casing used for display is set the first time the value is used.

Optional Fields

Only id and properties are required. All other fields are optional. This means the minimal response looks like this:

{
    "id": "1400099535764",
    "properties": {
        "CustomDate1": "2018-01-20",
        "CustomDate2": "2020-12-31",
        "CustomNumber1": "105",
        "CustomNumber2": "3.14",
        "CustomBoolean1": "True",
        "CustomBoolean2": "False",
        "CustomString1": "Custom String Here",
        "CustomString2": ""
    }
}

Only supplied fields will be changed.

So if you for example don’t supply the field colorLabelName the dropdown in Item Creator will remain at the value manually selected by the studio operator.

The properties field should always contain all custom properties setup for the customer. Use the empty string (“”) if the property has no value in your system.

Modified Data Import

Some external properties may change over time. Perhaps you have a custom property for whether the item is in stock or not? It can be useful to avoid styling with items that are out of stock in Look Creator.

A second endpoint must be implemented for continuous updates of the custom properties. It is similar to the previous one but return a JSON array instead.

The HTTP endpoints receives an offset parameter. This offset is in milliseconds. It is the amount of milliseconds passed since the last time Looklet asked the customer endpoint. The endpoint should return only the items changed during that time frame.

Example URL: https://example.com/this/that/something?offset=2700000

The request type will be GET and the response should be JSON.

Only properties can be altered from this endpoint. You are free to return the other fields as well, but the data will be ignored.

Example response:

[
    {
        "id": "ABCD-1234",
        "properties": {
            "CustomDate1": "2018-01-20",
            "CustomDate2": "2020-12-31",
            "CustomNumber1": "105",
            "CustomNumber2": "3.14",
            "CustomBoolean1": "True",
            "CustomBoolean2": "False",
            "CustomString1": "Custom String Here",
            "CustomString2": ""
        }
    },
    {
        "id": "EFGH-1234",
        "properties": {
            "CustomDate1": "2018-01-20",
            "CustomDate2": "2020-12-31",
            "CustomNumber1": "105",
            "CustomNumber2": "3.14",
            "CustomBoolean1": "True",
            "CustomBoolean2": "False",
            "CustomString1": "Custom String Here",
            "CustomString2": ""
       }
    }
]