Guide for Master data

In an enterprise setup, Master data source is always a 3rd party solution where production data is managed. Typically, it is your ERP being the master data source. 
At the minimum, the following data must be available at your master data source and pushed to Front Systems whenever there is new data available.

BASIC MASTER DATA

REQUIRED

We define the basic master data as:

  • ExtId e.g. M12345600001 (Typically productNumber + Color code is the unique VariantID in your master data source. M12345600001)

  • Product name e.g. Air Max

  • Product number (style no) e.g. M123456

  • Color code (Variant) e.g. 00001

  • Brand e.g. Nike

  • Group e.g. Sneakers

  • Season e.g. BASIC, 2104, etc.

  • Color e.g. Black diamond

  • EAN/GTIN e.g. 70451234567891

  • External SKU e.g. 123456789. This is the SKU identifier used in the master data system.

  • Size Eg. XL

PRODUCTS

Use the Products CRUD API to maintain products in Front Systems. A product in Front Systems is defining the master data on the number - variant level. It can have many sizes, but the sizes included in the variant must share prices. Products are instantly updated in Front Systems whenever you do updates in your master data source. This is especially interesting when it comes to prices. However, it can take up to 15 minutes before the changes are visible in the POS and in Portal.

When creating a product, be sure to use the property createProductSpecificSize as this will create a size-system (e.g. SML etc.) that is connected to only that product. Our solution then lets you easily add more sizes later on if needed and also lets you chose how you want the sizes sorted using the labelSortIndex for each size.

While importing or updating product if any of group/sub group, brand, season and color does not already exist, then they will be created with the information sent in the product body. For instance, "Winter 20202" would be created as a new season in the example below.

In the product CRUD API, the "extId" refers to the external ID of a product(variant) in the ERP (Enterprise Resource Planning) system or any other external system. This ID serves as a unique identifier for the product in the external system and is used to establish a connection between the external system and Front Systems.

When using the API's POST method, including the "extId" in the payload allows the operation to function as a "Create or update product" action. Here's how it works:

  • If the "extId" does not exist in the Front Systems from before, the POST method will create a new product based on the provided payload. It essentially acts as a "create" operation, adding a new entry to the Front Systems' database.

  • However, if the "extId" already exists in the Front Systems, the POST method will perform an update operation on the existing product. It will use the provided payload to update the relevant information associated with the identified product or variant in the Front Systems.

RECOMMENDATIONS
When creating products, you should include all available sizes from the master data source.
E.g. if a T-shirt can be available in XS, S, M, L, XL then you should include all those sizes and their GTINs in the payload.
To Create a Product
POST /api/Products

Example body request to create a product

{
"extId": "139539393-0045",
"createProductSpecificSize": true,
"name": "Letto Lady Jkt",
"number": "139539393",
"variant": "0045",
"groupName": "Jacket",
"color": "Jacket Shell",
"season": "Winter 2020",
"brand": "Bergans",
"price": 2500,
"description": "Letto er en meget lett 3-lags skalljakke i Dermizax®-membran, lav vekt og minimalt pakkvolum.",
"productSizes": [
{
"externalSKU": "053569470207",
"gtin": "7031582003441",
"label": "S",
"labelSortIndex": "1"
},
{
"externalSKU": "053569470209",
"gtin": "7031582003458",
"label": "M",
"labelSortIndex": "2"
},
{
"externalSKU": "053569470211",
"gtin": "7031582003465",
"label": "L",
"labelSortIndex": "3"
}
],
"images": [
"https://exampleurlfrompim.com/a4b4ec82-d655-4e46-ba11-87a250807d1a.jpg",
"https://exampleurlfrompim.com/49c26de8-8686-47d3-a90a-2de7238ec1ec.jpg",
"https://exampleurlfrompim.com/23c394bb-f381-4467-aade-bb4bbc7ab704.jpg"
],
"cost": 500
}

PRICES

REQUIRED FROM START

Prices can be divided into different price lists based on the retailer's needs. If the retailer has stores in several countries/currencies, use of price lists is mandatory.
E.g. one price list per currency. Each currency can be represented by one or more price lists. E.g. one price list of Flagship stores operating in Euro, and another price list for outlet stores in Euro. 

As soon as you have created the price lists that are relevant for you, assign the price lists to the relevant Stores or Regions using the Front Systems Portal | Admin | Settings | Store or Region | Edit store/region-level POS Settings.

As a minimum, one "recommended price list" needs to be assigned to each Store. Active products for a specific Store is defined by the price list assigned as the recommended retail price list. If a product does not have a price defined in the recommended retail price list, it will not be sellable in the POS.

As an alternative, the price lists can be used as a part of the Discount setup (Front Systems Portal | Product | Setup | Discounts). This is very useful if you for instance want to have price lists for customer club members, for members with a special tag assigned etc.

To Create or Update a PriceList
POST /api/PriceListV2

Example body request to create a pricelist

{
    "prices": [{
        "productExtId": "139539393-0045",
        "price": 899,
        "validFrom": "2019-01-01T08:30:00.000Z",
        "validTo": "2020-01-01T00:00:00.000Z"
    }],
    "name": "Retail Prices 2019"
}

While the GTIN may be used as an identifier, the productExtId is preferred. This recommendation arises because prices are ultimately applied at the product (variant) level.

Cost prices is maintained per Stock (usually 1-1 relationship with Store) in Front Systems. The simplest way to update the cost prices is using the cost price endpoint with update on the currency level.

To Create or Update cost prices
POST /api/Pricelist/cost

Example body request to update cost price for a product

{
    "costPrices": [{
        "productId": 54321234,
        "gtin": "7031582003441",
        "price": 550
    }],
    "currency": "EUR"
}

ENRICHED MASTER DATA

To enable the store associates to use front systems as a sales tool, they need to able to see the same images and product descriptions you already have available on your web shop. This integration is not necessary to begin with. You can easily set this up later during or after the pos rollout. On the other side, having images in the pos from day one, leaves a pretty nice first impression. Out of the box, Front Systems support the PIM InRiver. If that’s your PIM, jackpot! Just send the Api-token to your Front Systems contact person and we will have the integration up and running in no time. In case you have another PIM or you would like to control the integration your self, then go ahead and read.

Loop through your products and update them using
PUT /api/Products

Include only images and description in the body if you only are updating those.
In case you dont have the Front Systems ProductId, then look it up by using the GetProductByGTIN endpoint.

Example update payload

{
"description":" "Our model is 186cm long and is wearing a Medium",
"images":" [
"https://yourpimsourceurlexample/1",
"https://yourpimsourceurlexample/2",
"https://yourpimsourceurlexample/3"
]
}

TIP: The first url in the images array will be set as the main image in Front Systems.