Product Catalog

In this guide we will go through how products and master data can be added and maintained using Sitoo API. The main goal is to get master data into Sitoo from an ERP or PIM.

Product Groups

Product Groups are used mainly to group products for bookkeeping purposes and it is also where the VAT values are set for a product. The product group can be one of three types: Product, Service or Gift Card which can also be used to group sales and POS behaviour for the products. The key property for a product group is vatid which is used to connect products to a product groups. A product is always connected to exactly 1(one) product group. The vatid is also what is returned when adding a new product group.

See the Product Groups endpoints for more information.

Default Product Group

If the product group is not set on a product (using the vatid field), then the product will belong to the default product group which always has the vatid value of 2. The default product group cannot be deleted.

Manufacturers

Manufacturers in Sitoo is also used to represent a brand or a designer. The key property for a manufacturer is named externalcompanyid and is be used to set the manufacturerid property of a product.

See the Manufacturers endpoints for more information.

Products

The key property for a product is named productid and is returned when adding products. Also not that the ´sku´ property for a product should be set to a unique and is used when for example setting stock values in a warehouse.

After adding product groups, categories and manufacturers, it’s time to create and update product data. To do that, use the batch operations towards the Products endpoint. The fields that Sitoo would like to receive are listed below.

Important Product Fields (POST/PUT)

Property	Description
sku	Unique stock keeping unit. Used as key in multiple endpoints, e.g. Stock
skumanufacturer	SKU for the manufacturer
title	Title of product
descriptionshort	Shown in Product Info in POS
description	Shown in Product Info ("Additional Info" tab) in POS
moneyprice	Price of the product (Incl. VAT). Will be set on the "Default" price list
moneypriceorg	Suggested Retail Price (SRP) (Incl. VAT)
moneypricein	The purchase price (Excl. VAT), can be used calculate profit on products
unitlabel	Unit label (eg. "pcs", "kg"). Suffix shown on product quantity if product has `allowdecimals` set to true
allowdecimals	Set this if the product can be purchased with fractional unit quantity. Triggers quantity pop-up
activepos	Set to false to hide product from all POS
vatid	The ID for the Product Group for this product
defaultcategoryid	Default category for the product
manufacturerid	The ID for the Manufacturer/Brand/Designer of this product
manufacturerurl	URL is shown in Product Info in POS
custom1	Searchable info, also shown in Product Info
custom2	Searchable info, also shown in Product Info
custom3	Searchable info, also shown in Product Info
custom4	Searchable info, also shown in Product Info
custom5	Searchable info, also shown in Product Info (Can also be used to change sortorder of products in POS)
stockcountenable	Turns on/off stock handling for the product
barcode	The unique EAN/barcode for the product
barcodealiases	Unique EAN/Barcode aliases for the product. Used if multiple barcodes exist for product

Prices on the Products endpoints

If moneyprice is sent (POST/PUT) to the products endpoint, it will be set on the "Default" price list. However, the recommended implementation of prices is to use multiple price lists and to make a separate integration to the Price Lists endpoints.

See the Products endpoints for more information.

Product Variants

Product Variants are used to group a set of products together which share the base values of one product (the "main" variant). The most common use of variants is to have different sizes of the same product grouped together. To group the products as variants, the Set Product Variants endpoint is used. The productid in the path has to be the main product variant which always needs to exist (created via the products endpoint) before creating variants. Note! All fields for the Set Product Variants endpoint always need to be sent.

Product Variant Fields (PUT)

The following properties needs to be set for each variant. Note! Some fields are deprecated, but still need to be sent in a PUT.

Property	Description
productid	The ID of the product. Set the value `0` to create a new product. The "main" variant needs to have it's `productid` set
activepos	Set to false to hide product from all POS
title	Title of product
sku	Unique stock keeping unit. Used as key in multiple endpoints, e.g. Stock
moneyprice	Price of the product (Incl. VAT). Will be set on the "Default" price list
moneypriceorg	Suggested Retail Price (SRP) (Incl. VAT)
moneypricein	The purchase price (Excl. VAT), can be used calculate profit on products
barcode	The unique EAN/barcode for the product
barcodealiases	Unique EAN/Barcode aliases for the product. Used if multiple barcodes exist for product
friendly	Deprecated, but for legacy reasons, you should pass this field with a unique value for the product. Using the `sku` field is good practice
attributes	The attributes for this variant. E.g.`{ "name": "Size", "options": [ "Extra Large" ] }`

Two methods for creating variants

Creating all variants as simple products first and then grouping them using the Set Product Variants Endpoint. Best practice is to use one of the custom[1-5] fields or skumanufacturer on the products to set a variantkey that all variants have in common. This key should be used to group the products. In this case the productid of the simple product needs to be used in the set.
Creating only the first variant as the “Main Product” and then creating new variants under it, using the Set Product Variants Endpoint. Here the productid of the "main" variant is set for the first one of the products in the array. The following “new” variants should have productid: 0.

See the Product Variants endpoints for more information.

Updating product variants

The Set Product Variants endpoint should only be used when changing the variant structure i.e. adding products with new attributes for a set of variants. All other updates to variant products should be done via the Batch Update Products endpoint or Batch Set Price List Items endpoint depending on the use case.

Adding new products to a variant

When using the Set Product Variants endpoint to update the structure of an existing set of variants, all properties for the variant objects need to be provided. Therefore, best practice for this is to always use the Get Product Variants endpoint to fetch the current state before updating, to not overwrite any existing properties or products.

Product Images

Product Images are added to products in Sitoo by using the Add Product Image endpoint. The resourceid should contain the filename and needs to be unique for the image. The property filedata should contain the base64-encoded data of the image in it. Example:

{
  "resourceid": "message.gif",
  "filedata": "R0lGODlhHwAJAPABAAAAAP///yH5BAAAAAAALAAAAAAfAAkAAAItjI+pi3AOYgyuJTnp07ZvU1WaCF5mSWFpRnIfJ0Lni8Jbi8/hrWJQr2IIh4gCADs="
}

Image Limitations

Supported image formats: JPEG, PNG, GIF
Supported filename extensions: .jpg, .jpe, .jpeg, .gif, .png
Recommended max image size: 5 000 x 5 000 pixels
Recommended max image file size: 8 MB

Image Processing

Sitoo expects the file format to be the same as the file extension. If not, the upload will fail.

See the Product Images & Files endpoints for more information.

Product Integration Process

Recommendation when running a product sync is to always run delta changes and avoid doing the same updates over and over. E.g. you have 1000 SKUs, the recommendation from Sitoo is to run the product flow in batches of 200 SKUs to avoid lenghty requests. You should aim to do as much updates as possible in batches.

Basic process for creating and updating products in Sitoo

Basic Product Integration

Fetch existing products

GET /sites/{siteid}/products.json?sku=["sku1","sku2"...,"sku200"]&fields=sku,productid,variantparentid
Get all existing products in Sitoo for the batch that you are processing.

Loop batch of products

Loop products to find matches in between the existing products and the batch. If a match is found you know that it is an "update" else it is "new". Convert to Sitoo object. Can also use the property "variantparentid" to know if an existing product is a master product to update specific fields or if some fields should be excluded since it is a variant product.

Batch update

PUT /sites/{siteid}/products.json
Update the existing products in 1 batch.

Batch create

POST /sites/{siteid}/products.json
Create the new products in 1 batch.
In the reply when adding new items you will receive the product ID of the product, either store it and add to your object to have it in the variant grouping or do a GET products based on SKU again once all products are added to have the product ID for all products.

Create variants

Since current variants will either be replaced or deleted with the new variants. It is recommended to first do:
GET /sites/{siteid}/products/{productid}/productvariants.json
This to avoid accidentally removing products from the system. Once you have the existing variant structure you compare/concatenate/replace/merge to have the new structure of that specific variant, then call this endpoint to set the variant:
PUT /sites/{siteid}/products/{productid}/productvariants.json

Done!

Using this approach, you will have synched 1 000 products in 15 requests. And then it depends how many variants you have in the batch and how many variant requests are needed. The variant endpoint only use case it to group the products, adding and updating products should be done on the product endpoint.

Batch Call Response Handling

Always read the response from Sitoo to make sure that the request was sucessful. Batch calls can return a 200 response on the request even though individual items in the batch could have failed. Therefore you must go through the response to validate each item response outcome.

Manufactures, Categories and Product Groups

Depending on the data structure and how the master system handles manufacturers, categories and product groups you will have different approaches to when the get the Sitoo IDs for these properties. Either you create and update manufactures, categories and product groups before the product sync starts to make sure that you will have all details in Sitoo before starting the product sync process. This will then let you do 1 GET request for each property (manufactures, categories and product groups) before the product sync to be able to map identifiers between the different systems. Alternately you will create and update the properties for each batch, process is similar, but the second approach will require more requests.