GENERAL INFORMATION
Purpose
This endpoint is used for sharing the product information, which we call items.
How the data is used
The item information is of course the main dataset that we need as every action and transactional data is based on a product, making this a mandatory dataset.
Best practices
Make sure to update the item on a regular basis, recommended minimum once a day, to ensure the item information is up to date so the products will become available to use in the customer portal as soon as possible.
The all the item master data id’s (seasonId, brandId, etc. etc.) needs to allign with the id’s that you are sending to the corresponding item master data endpoints (POST /Brands, POST /Seasons etc. etc.). This also applies to the skus (sizeId matches POST /Sizes, colorId matches POST /Colors etc.).
We have a 3 layered structure:
a. Item
b. Style
c. SKU
The Item is the top level of a product, for example a T-Shirt that comes in multiple colors.
The Style is the T-Shirt in the color red.
The SKU (storage keeping unit) is the bottom level, the red T-Shirt in size L on which the stock is registered.
The API body has an Item and SKU object but no Style object. To successfully group for example all the SKU’s of the Red Colored T-Shirt, use the
styleIdfield. See json example below, where we have 2 different colors. The styleId’s for the different colors are 100001-10 and 100001-50 and the skus in different sizes are assigned to the correct style.We support the themeId, brandId, seasonId and collectionId on both item and style level. For example when you have the season assigned to the style level (e.g. the Red T-shirt is season summer25 and the black T-shirt is season NOOS) you need to assign the season in the sku object. If you have it on the item level you can fil it in the item object. There is a rule for this, when you fill it on both levels, the value in the sku object overrules the values on the item object.
If you use prepacks (pre-bundled set of products in predetermined size and quantity ratios) in your process make sure you also send the prepacks as a SKU for the item and make sure the skuId of the prepack aligns with the one used in POST /Prepacks endpoint. See example json below where the PP1 is a prepack.
Send us the product information of the tradeable goods. The non tradeable goods like plastic shopping bags are not necessary to share.
We recommend to send us the information for all products, even the outdated once. As we also ask for the historical sales, we need the product information these outdated products to match with the historical sales.
The Merchandise Category is mandatory for each product, as this established the type of product this is. For example the Women’s T-Shirt with Short Sleeve. More information about what we mean by merchandise categories here: POST /MerchandiseCategories
If you have additional product information, which the business heavily relies on in the buying/merchandising/allocation process, which is not covered by any of our standards fields in this API, we recommend to use the
styleAttributes. This allows you to send your own custom attributes which can be used in our portal. For example I use a target customer segments (Young Men's, Women’s Premium) in my process, using thestyleAttributesI can assign a target customer segment (key) Women’s Premium (value) to a specific style using the correct styleId I also send in the skus object. See an example in the json below where we assign 2 different target customer segments to the 2 different styles.If you do not have a unique Id for the skus we recommend combining the itemId/code with the colorId/code and sizeId/code (seperated by - to keep unique). See example json below.
If there is a change in product information, send us the entire product information again to this endpoint.
Common pitfalls
Making the assumption the brandId/seasonId/collectionId/themeId, being technically non mandatory fields, can be skipped while the business is heavily depending on this information their processes.
When using the
attributes/styleAttributesit is a common mistake to re-use theattributeId/styleAttributeIdbut this needs to be unique across all attributes/styleAttributes. If you do not have an id at this level combining the styleId with the key (separated by - to ensure uniqueness) will also do the trick, see example json below.Avoid using the barcode as a skuId if possible, because if barcode changes, so does the skuId. And the skuId is also used for the transactional data like sales/stock, which means we lose the relation to all your historical sales/stock data, which could lead to incorrect stock levels and a decrease of the models performance for this sku.
TECHNICAL INFORMATION
Authentication
Bearer token, information on page POST /Token
Headers
Name | Description | Example |
|---|---|---|
X-Tenant | Tenant code supplied by Wair | “TENANT” |
Body example:
{
"items": [
{
"itemId": "877bb4f2-7e72-4a25-a8f9-20baad1a8133",
"code": "100001",
"description": "Basic T-Shirt",
"themeId": "71eb2dfa-6d23-43d9-a04d-ef8231b5dd62",
"brandId": "d55c2b18-01a6-45ed-a50e-fa939f76e4ff",
"seasonId": "ec286479-5e1c-458c-95de-2495f09f4eb1",
"collectionId": "3152765d-c0f3-4482-b2a1-da74f2dd4f0d",
"merchandiseCategoryId": "58202ee4-59cb-4897-9f84-8bbabfec7373",
"attributes": [
{
"attributeId": "100001-FIT",
"key": "FIT",
"value": "Straight Fit"
}
],
"styleAttributes": [
{
"styleAttributeId": "100001-10-targetCustomerSegment",
"key": "targetCustomerSegment",
"value": "Women’s Premium",
"styleId": "100001-10"
},
{
"styleAttributeId": "100001-50-targetCustomerSegment",
"key": "targetCustomerSegment",
"value": "Women’s Basic",
"styleId": "100001-50"
}
],
"skus": [
{
"skuId": "100001-10-M",
"code": "10-M",
"themeId": "71eb2dfa-6d23-43d9-a04d-ef8231b5dd62",
"brandId": "d55c2b18-01a6-45ed-a50e-fa939f76e4ff",
"seasonId": "ec286479-5e1c-458c-95de-2495f09f4eb1",
"collectionId": "3152765d-c0f3-4482-b2a1-da74f2dd4f0d",
"colorId": "10",
"sizeId": "M",
"styleId": "100001-10",
"barcodes": [
{
"barcodeId": "02d709a1-c9b1-4ebd-95d4-55ee7e402472",
"code": "4003994155486",
"isPrimary": true
}
]
}
{
"skuId": "100001-10-L",
"code": "10-L",
"themeId": "71eb2dfa-6d23-43d9-a04d-ef8231b5dd62",
"brandId": "d55c2b18-01a6-45ed-a50e-fa939f76e4ff",
"seasonId": "ec286479-5e1c-458c-95de-2495f09f4eb1",
"collectionId": "3152765d-c0f3-4482-b2a1-da74f2dd4f0d",
"colorId": "10",
"sizeId": "L",
"styleId": "100001-10",
"barcodes": [
{
"barcodeId": "0f067e3e-d421-4fc9-91b7-9b01f7c885c2",
"code": "4003994155496",
"isPrimary": true
}
]
},
{
"skuId": "100001-10-PP1",
"code": "10-PREPACK1",
"themeId": "71eb2dfa-6d23-43d9-a04d-ef8231b5dd62",
"brandId": "d55c2b18-01a6-45ed-a50e-fa939f76e4ff",
"seasonId": "ec286479-5e1c-458c-95de-2495f09f4eb1",
"collectionId": "3152765d-c0f3-4482-b2a1-da74f2dd4f0d",
"colorId": "10",
"sizeId": "PP1",
"styleId": "100001-10",
"barcodes": [
{
"barcodeId": "dda8907a-cc14-4c72-848d-49dcb78fbf17",
"code": "4003994155526",
"isPrimary": true
}
]
},
{
"skuId": "100001-50-M",
"code": "50-M",
"themeId": "a1e6f297-6962-4619-baf5-4dfc5c72a7a4",
"brandId": "5d46aaa3-406a-4ecc-ab9c-7d6b40d04305",
"seasonId": "09e3833f-1e50-4915-a2c1-707fac7ac5d4",
"collectionId": "3152765d-c0f3-4482-b2a1-da74f2dd4f0d",
"colorId": "50",
"sizeId": "M",
"styleId": "100001-50",
"barcodes": [
{
"barcodeId": "267991f7-d072-4e26-b54f-a9ca6f3d9001",
"code": "4003994155506",
"isPrimary": true
}
]
}
{
"skuId": "100001-50-L",
"code": "50-L",
"themeId": "a1e6f297-6962-4619-baf5-4dfc5c72a7a4",
"brandId": "5d46aaa3-406a-4ecc-ab9c-7d6b40d04305",
"seasonId": "09e3833f-1e50-4915-a2c1-707fac7ac5d4",
"collectionId": "3152765d-c0f3-4482-b2a1-da74f2dd4f0d",
"colorId": "50",
"sizeId": "L",
"styleId": "100001-50",
"barcodes": [
{
"barcodeId": "aed60d11-fc55-41bc-a9de-fe2d0a16cf19",
"code": "4003994155516",
"isPrimary": true
}
]
},
{
"skuId": "100001-50-PP1",
"code": "50-PREPACK1",
"themeId": "a1e6f297-6962-4619-baf5-4dfc5c72a7a4",
"brandId": "5d46aaa3-406a-4ecc-ab9c-7d6b40d04305",
"seasonId": "09e3833f-1e50-4915-a2c1-707fac7ac5d4",
"collectionId": "3152765d-c0f3-4482-b2a1-da74f2dd4f0d",
"colorId": "50",
"sizeId": "PP1",
"styleId": "100001-50",
"barcodes": [
{
"barcodeId": "dda8907a-cc14-4c72-848d-49dcb78fbf17",
"code": "4003994155536",
"isPrimary": true
}
]
}
]
}
]
}Field information:
Fieldname | Context | Mandatory | Type / max field length |
|---|---|---|---|
itemId | Unique identifier for this item, for example a uuid, needs to be unique across all items. If you want to update an item, send the item again using this id. | Yes | string / 80 characters max |
code | A business key of the item, recognizable by users | Yes | string / 60 characters max |
description | The name of the item | No, but highly preferred | string / 255 characters max |
themeId | The themeId of the theme assigned to the item | Technically no, but read common pitfalls point 1 about this | string / 80 characters max |
brandId | The brandId of the brand assigned to the item | Technically no, but read common pitfalls point 1 about this | string / 80 characters max |
seasonId | The seasonId of the season assigned to the item | Technically no, but read common pitfalls point 1 about this | string / 80 characters max |
collectionId | The collectionId of the collection assigned to the item | Technically no, but read common pitfalls point 1 about this | string / 80 characters max |
merchandiseCategoryId | The merchandiseCategoryId of the merchandise category assigned to the item. Read best practices (point 6) about this. | Yes | string / 80 characters max |
sku > skuId | Unique identifier for this sku, needs to be unique across all skus. | Yes | string / 80 characters max |
sku > code | A business key of the sku, recognizable by users | Yes | string / 60 characters max |
sku > colorId | The colorId of the color assigned to the sku | Yes | string / 80 characters max |
sku > sizeId | The sizeId of the size assigned to the sku | Yes | string / 80 characters max |
sku > styleId | The styleId of assigned to the sku, carefully read best practices (point 4) about this. | Yes | string / 80 characters max |
sku > barcodes > barcodeId | Unique identifier for this barcode, needs to be unique across all barcodes. | Yes | string / 80 characters max |
sku > barcodes > code | The actual barcode of the sku | Yes | string / 60 characters max |
sku > barcodes > isPrimary | We support multiple barcodes for each sku, use this field to indicate if this is the primary barcode. In some cases you could have a GS1 barcode that is also on the products label, but also an internal barcode and in this case the GS1 barcode is primary, | No | boolean |
RESPONSE
StatusCodes:
200 = OK
401 = Unauthorized, which means an expired/missing/invalid token
400 = Bad request, see body of the response to check which validation errors have occured
500 = System error, see body of the response to check which error has occured or contact integration support
Body Example:
No body in the response