Products API V2

Manage product and stock information

Products API allows you to manage your product catalog and its stock information. Product updates can be done either one by one or in batches. Products API is linked to Orders API so that when an order for a product is placed, product availability dictates what happens to the order next (which warehouse it is routed to, and so on).

As with other requests to the system, user must be authenticated as described in Posti Authentication API.

API Endpoints

Environment	Protocol	Host
Test	HTTPS	argon.ecom-api.posti.com
Prod	HTTPS	ecom-api.posti.com

Here is a list of all available API methods, followed by a detailed description for each one.

GET	/v2/products/{productId}	Get information of a single product.
GET	/v2/products/all/private	Get all privately published products.
GET	/v2/products/all/{warehouseId}	Get all products in a warehouse.
GET	/v2/products?externalId={id1}&externalId=...	Get information of multiple products.
POST	/v2/products/supplier/multiple/{retailer’s business ID}	Modify one or multiple products for a webshop.

Overview

Retrieve data of a single product, identified by the product id.

Response fields

Element	Type	Description
externalId	String	Unique identifier of the product from seller's system.
name	String	Name of product.
shortName	String	Short name of product.
description	Object	Longer description of the product in different languages.
.en	String	Longer description of the product in English.
.fi	String	Longer description of the product in Finnish.
EANCode	String	EAN code of product.
supplier	String	Name of the product supplier.
category	String	Product category, e.g. "Fishing/Fishing rods/Open reel fishing rods".
measurements	Object	Measurements of the product
.weight	Number	Gross weight of the product in `kg`, with packing materials
.length	Number	Length of the product in `m`
.width	Number	Width of the product in `m`
.height	Number	Height of product in `m`
.volume	Number	Volume of product in `m³`
isFragile	Boolean	Indicator of whether product is fragile.
hasBestBeforeDate	Boolean	Indicator of whether product has a best before date.
hasWarranty	Boolean	Indicator of whether product has a warranty.
vatPercentage	Number	Tax-rate of the product in percentage
totalPrice	Number	Recommended retail price, VAT included
currency	String	3-letter currency code of product (ISO 4217). If not given, "EUR" used as default.
stockBalance	Object	Product stock information. Mandatory for stock balance updates.
.totalQty	Number	Total stock of product (sum of all warehouses).
.maximumQty	Number	The greatest stock of product in a single warehouse.
.warehouseBalance	Array	Warehouse stock information. Includes objects with fields listed below.
..externalWarehouseId	String	Warehouse identifier in external system (OVT code). Mandatory for stock balance updates.
..quantity	Number	Current stock of product in the warehouse. Mandatory for stock balance updates.
..totalPrice	Number	Product wholesale price for a retailer, VAT 0%.
..currency	String	3-letter currency code of product (ISO 4217). If not given, "EUR" used as default.
additionalInfo	Object	Additional Info of the product e.g. pictures, notes, additional IDs.
.attachments	Array	Attachments regarding product.
..type	String	Type of additional info e.g. "productImage1" or "marketing".
..URI	String	URI to the document.
..fileType	String	Type of file e.g. "pdf" or "png".
..fileName	String	Name of the attachment file. e.g. "User Guide" or "Product Image".
.comments	Array	Comments regarding product.
..type	String	How the comment should be used e.g. "marketing".
..value	String	The comment text.
.classifications	Array	Classifications regarding product.
..type	String	Type of product classification. For classification use GS1 GPC Standard, december 2016
..value	String	The classification.
.productVariationIds	Array	Alternative ids for the product.
..type	String	Type of product id e.g. "supplierId".
..value	String	The id.
.dangerousGoodsDetail	Object	Details about dangerous goods (ADR).
..isDangerousGoods	Boolean	true/false value, is the product a dangerous good.
.warrantyDetail	Object	Details about product warranty.
..expiration	String	The extent of the warranty.
..serialControlled	Boolean	Whether the product is serial number controlled.
specifications	Array	List of product specifications or features. See picture below.
.type	String	Product specification group `Technical specifications, Materials and Care, Size and Fit, Details, Functions`
.property	Array	List of product property or feature value pairs.
..type	String	Product property or feature type e.g. "size".
..value	String	Product property or feature value e.g. "44".
..specifier	String	Product property or feature specifier e.g. "Eur".
..languageId	String	Language code of description, in two-letter ISO 639-1 format, e.g. "fi".
..description	String	Product property or feature description e.g. "Kengän koko".

Example response

{
    "externalId": "691196000582",
    "name": "Jack's Fishing Gear fishing rod model 123",
    "shortName": "jfg-rod-123",
    "description": {
        "en": "Forged aluminum spool. For left and right handed."
    },
    "EANCode": "59012341234567",
    "supplier": "Jack's Fishing Gear",
    "category": "Fishing/Fishing rods/Open reel fishing rods",
    "measurements": {
        "weight": 75.0,
        "length": 1.75,
        "width": 1.12,
        "height": 1.83,
        "volume": 5.92
    },
    "isFragile": false,
    "hasBestBeforeDate": false,
    "hasWarranty": true,
    "vatPercentage": 24.0,
    "totalPrice": 79.95,
    "currency": "EUR",
    "stockBalance": {
        "totalQty": 8.0,
        "maximumQty": 5.0,
        "warehouseBalance": [{
            "externalWarehouseId": "1234567",
            "quantity": 5.0,
            "totalPrice": 79.95,
            "currency": "EUR"
        },
        {
            "externalWarehouseId": "2345678",
            "quantity": 3.0,
            "totalPrice": 89.95,
            "currency": "EUR"
        }]
    },
    "additionalInfo": {
        "attachments": [{
            "type": "marketing",
            "URI": "www.mypictureoffishingrod.com/picture.png",
            "fileType": "png",
            "fileName": "Product Picture"
        }],
        "comments": [{
            "type": "marketing",
            "value": "Probably the best fishing rod in the world"
        }],
        "classifications": [
		{
            		"type": "Segment Description",
            		"value": "Footwear"
		},
		{
			"type": "Segment Code",
			"value": "63000000"
		},
		{
			"type": "Family Code",
			"value": "63010000"
		},
		{
			"type": "Family Description",
			"value": "Footwear"
		},
		{
			"value": "Class Code",
			"type": "63010100"
		},
		{
			"type": "Class Description",
			"value": "Athletic Footwear"
		},
		{
			"type": "Brick Code",
			"value": "1001070"
		},
		{
			"type": "Brick Description",
			"value": "Athletic Footwear - General Purpose"
		}

        ],
        "productVariationIds":[
           {
              "type":"supplierId",
              "value":"GFK6544256"
           }
        ],
        "dangerousGoodsDetail":{
           "isDangerousGoods":true
        },
        "warrantyDetail":{
           "expiration":"3 years",
           "serialControlled":true
        }
    },
    "specification": [{
        "type": "Technical Info",
        "property": [{
            "type": "weight",
            "value": "0.4",
            "specifier": "kg",
            "languageId": "fi",
            "description": "paino"
        }]
    }]
}

Response codes

Response code	Explanation
`200`	Request processed successfully.
`404`	Requested resource was not found.
`500`	An error occured while processing request.

Overview

Get all privately published products.

Response fields

Similar response as when requesting a single product, except that products are wrapped in an array.

Element	Type	Description
products	Array	Array of products

Example response

Similar response as for all products.

Response codes

Same as when retrieving a single product.

NB! If warehouse contains many thousands of products then it is recommended to enable response compression with the following header:

Header	Value
Accept-Encoding	gzip,deflate

Overview

Get all products in a warehouse.

Response fields

Similar response as when requesting a single product, except that products are wrapped in an array.

Element	type	Description
products	Array	Array of products

Example response

Similar response as for all products.

Response codes

Same as when retrieving a single product.

Overview

Retrieve information of multiple products

Query string parameters

Array of product IDs, given as multiple values for parameter externalId

Response fields

Similar response as when requesting a single product, except that products are wrapped in an array.

Element	type	Description
products	Array	Array of products

Example response

Similar response as for all products.

Response codes

Same as when retrieving a single product.

Overview

Update information of one or multiple products for a certain webshop. Can also be used to insert new products. The request body must be an array consisting of one or more product objects. Field stockBalance.warehouseBalance.externalWarehouseId must match the warehouse id given by webshop.

Query parameters

none

Request fields

Element	Mandatory	Type	Description
externalId	X	String	Unique identifier of the product from seller's system.
name		String	Name of product.
shortName		String	Short name of product.
description		Object	Longer description of the product in different languages.
.en		String	Longer description of the product in English.
.fi		String	Longer description of the product in Finnish.
EANCode		String	EAN code of product.
supplier		String	Name of the product supplier.
category		String	Product category, e.g. "Fishing/Fishing rods/Open reel fishing rods".
measurements		Object	Measurements of the product
.weight		Number	Gross weight of the product in `kg`, with packing materials
.length		Number	Length of the product in `m`
.width		Number	Width of the product in `m`
.height		Number	Height of product in `m`
.volume		Number	Volume of product in `m³`
isFragile		Boolean	Indicator of whether product is fragile.
hasBestBeforeDate		Boolean	Indicator of whether product has a best before date.
hasWarranty		Boolean	Indicator of whether product has a warranty.
vatPercentage		Number	Tax-rate of the product in percentage
totalPrice		Number	Product list price, VAT 0%.
currency		String	3-letter currency code of product (ISO 4217). If not given, "EUR" used as default.
stockBalance		Object	Product stock information. Mandatory for stock balance updates.
.warehouseBalance		Array	Warehouse stock information. Includes objects with fields listed below.
..externalWarehouseId		String	Warehouse identifier in external system (OVT code). Mandatory for stock balance updates.
..quantity		Number	Current stock of product in the warehouse. Mandatory for stock balance updates.
..totalPrice		Number	Product wholesale price for a webshop in the warehouse, VAT 0%.
..currency		String	3-letter currency code of product (ISO 4217). If not given, "EUR" used as default.
additionalInfo		Object	Additional Info of the product e.g. pictures, notes, additional IDs.
.attachments		Array	Attachments regarding product.
..type		String	Type of additional info e.g. "productImage1" or "marketing".
..URI		String	URI to the document.
..fileType		String	Type of file e.g. "pdf" or "png".
..fileName		String	Name of the attachment file. e.g. "User Guide" or "Product Image".
.comments		Array	Comments regarding product.
..type		String	How the comment should be used e.g. "marketing".
..value		String	The comment text.
.classifications		Array	Classifications regarding product.
..type		String	Type of product classification. For classification use GS1 GPC Standard, december 2016
..value		String	The classification.
.productVariationIds		Array	Alternative ids for the product.
..type		String	Type of product id e.g. "supplierId".
..value		String	The id.
.dangerousGoodsDetail		Object	Details about dangerous goods (ADR).
..isDangerousGoods		Boolean	true/false value, is the product a dangerous good.
.warrantyDetail		Object	Details about product warranty.
..expiration		String	The extent of the warranty.
..serialControlled		Boolean	Whether the product is serial number controlled.
specifications		Array	List of product specifications or features. See picture below.
.type		String	Product specification group `Technical specifications, Materials and Care, Size and Fit, Details, Functions`
.property		Array	List of product property or feature value pairs.
..type		String	Product property or feature type e.g. "size".
..value		String	Product property or feature value e.g. "44".
..specifier		String	Product property or feature specifier e.g. "Eur".
..languageId		String	Language code of description, in two-letter ISO 639-1 format, e.g. "fi".
..description		String	Product property or feature description e.g. "Kengän koko".

An example of a Product update JSON request

{
  "products": [
    {
        "externalId": "99999999999",
        "name": "Jack's Fishing Gear fishing rod model 123",
        "shortName": "jfg-rod-123",
        "description": {
            "en": "Forged aluminum spool. For left and right handed."
        },
        "EANCode": "59012341234567",
        "supplier": "Jack's Fishing Gear",
        "category": "Fishing/Fishing rods/Open reel fishing rods",
        "measurements": {
            "weight": 75.0,
            "length": 1.75,
            "width": 1.12,
            "height": 1.83,
            "volume": 5.92
        },
        "isFragile": false,
        "hasBestBeforeDate": false,
        "hasWarranty": true,
        "vatPercentage": 24.0,
        "totalPrice": 79.95,
        "currency": "EUR",
        "stockBalance": {
            "warehouseBalance": [{
                "externalWarehouseId": "1234567",
                "quantity": 5.0,
                "totalPrice": 79.95,
                "currency": "EUR"
            },
            {
                "externalWarehouseId": "2345678",
                "quantity": 3.0,
                "totalPrice": 89.95,
                "currency": "EUR"
            }]
        },
        "additionalInfo": {
            "attachments": [{
                "type": "marketing",
                "URI": "www.mypictureoffishingrod.com/picture.png",
                "fileType": "png",
                "fileName": "Product Picture"
            }],
            "comments": [{
                "type": "marketing",
                "value": "Probably the best fishing rod in the world"
            }],
            "classifications": [
    		{
                		"type": "Class Description",
                		"value": "Fishing/Angling Sports Equipment"
    		},
    		{
    			"type": "Class Code",
    			"value": "71012100"
    		},
    		{
    			"type": "Brick Code",
    			"value": "10001913"
    		},
    		{
    			"type": "Brick Description",
    			"value": "Fishing Rods/Poles"
    		}
            ],
            "productVariationIds":[
               {
                  "type":"supplierId",
                  "value":"GFK6544256"
               }
            ],
            "dangerousGoodsDetail":{
               "isDangerousGoods":true
            },
            "warrantyDetail":{
               "expiration":"3 years",
               "endDate":"2018-02-10",
               "serialControlled":true
            }
        },
        "specification": [{
            "type": "Technical specifications",
            "property": [{
                "type": "weight",
                "value": "0.4",
                "specifier": "kg",
                "languageId": "fi",
                "description": "paino"
            }]
        }]
    }

  ]
}

JSON Schema

POST products JSON schema

An example of a Product stock update JSON request

{
  "products": [{
    "externalId": "691196000582",
    "stockBalance": {
        "warehouseBalance": [
            {
                "externalWarehouseId": "1234567",
                "quantity": 5.0
            },
            {
                "externalWarehouseId": "2345678",
                "quantity": 3.0
            }
        ]
    }
  }]
}

JSON Schema

POST Product stock update JSON schema

Response codes

`200`	Request processed successfully.
`500`	An error occured while processing request.