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 the ERP.

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.

Categories

Categories are used to group products together for different purposes, e.g. filtering and sales reports. The key property for a category is categoryid which is used to connect products to categories. A product does not have to belong to a category, but is it recommended to at least set the defaultcategoryid of the product. To connect a product to multiple categories, use the categories property of the product.

Tree Structure

Categories can be structured as a tree by using the categoryparentid indicating that a category belongs to another one, with a value of null indicating a "root" category.

See the Categories endpoints for more information.

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 manufacturer is named productid as is returned when adding products.

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 from the ERP are listed below.

Important Product Fields (POST/PUT)

PropertyDescription
skuUnique stock keeping unit. Used as key in multiple endpoints, e.g. Stock
skumanufacturerSKU for the manufacturer
title stringTitle of product
descriptionshortShown in Product Info in POS
descriptionShown in Product Info ("Additional Info" tab) in POS
moneypricePrice of the product (Incl. VAT). Will be set on the "Default" price list
moneypriceorgSuggested Retail Price (SRP) (Incl. VAT)
moneypriceinThe purchase price (Excl. VAT), can be used calculate profit on products
unitlabelUnit label (eg. "pcs", "kg"). Suffix shown on product quantity if product has allowdecimals set to true
allowdecimalsSet this if the product can be purchased with fractional unit quantity. Triggers quantity pop-up
activeposSet to false to hide product from all POS
vatidThe ID for the Product Group for this product
defaultcategoryidDefault category for the product
manufactureridThe ID for the Manufacturer/Brand/Designer of this product
manufacturerurlURL is shown in Product Info in POS
custom1Searchable info, also shown in Product Info
custom2Searchable info, also shown in Product Info
custom3Searchable info, also shown in Product Info
custom4Searchable info, also shown in Product Info
custom5Searchable info, also shown in Product Info (Can also be used to change sortorder of products in POS)
stockcountenableTurns on/off stock handling for the product
barcodeThe unique EAN/barcode for the product
barcodealiasesUnique 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, or they will be overridden by default values.

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.

PropertyDescription
productidThe ID of the product. Set the value 0 to create a new product. The "main" variant needs to have it's productid set
activeposSet to false to hide product from all POS
title stringTitle of product
skuUnique stock keeping unit. Used as key in multiple endpoints, e.g. Stock
moneypricePrice of the product (Incl. VAT). Will be set on the "Default" price list
moneypriceorgSuggested Retail Price (SRP) (Incl. VAT)
moneypriceinThe purchase price (Excl. VAT), can be used calculate profit on products
barcodeThe unique EAN/barcode for the product
barcodealiasesUnique EAN/Barcode aliases for the product. Used if multiple barcodes exist for product
friendlyDeprecated, but for legacy reasons, you should pass this field with a unique value for the product. Using the sku field is good practice
attributesThe attributes for this variant. E.g.{ "name": "Size", "options": [ "Extra Large" ] }

Two methods for creating variants

  1. 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.

  2. 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.

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="
}

See the Product Images & Files endpoints for more information.