Products API

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 all Posti APIs, requests need to be accompanied with a valid authentication token, which can be acquired from Posti Authentication API. This token must be placed in the Authentication header of the request.



GET/v2/products/{productId}

Overview

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

Response fields

ElementtypeDescription
externalIdStringUnique identifier of the product from seller's system.
nameStringName of product.
shortNameStringShort name of product.
descriptionObjectLonger description of the product in different languages.
.enStringLonger description of the product in English.
.fiStringLonger description of the product in Finnish.
EANCodeStringEAN code of product.
supplierStringName of the product supplier.
categoryStringProduct category, e.g. "Fishing/Fishing rods/Open reel fishing rods".
measurementsObjectMeasurements of the product
.weightNumberGross weight of the product in kg, with packing materials
.lengthNumberLength of the product in m
.widthNumberWidth of the product in m
.heightNumberHeight of product in m
.volumeNumberVolume of product in m3
isFragileBooleanIndicator of whether product is fragile.
hasBestBeforeDateBooleanIndicator of whether product has a best before date.
hasWarrantyBooleanIndicator of whether product has a warranty.
vatPercentageNumberTax-rate of the product in percentage
totalPriceNumberProduct list price, VAT 0%
currencyString3-letter currency code of product (ISO 4217). If not given, "EUR" used as default.
stockBalanceObjectProduct stock information. Mandatory for stock balance updates.
.totalQtyNumberTotal stock of product (sum of all warehouses).
.maximumQtyNumberThe greatest stock of product in a single warehouse.
.warehouseBalanceArrayWarehouse stock information. Includes objects with fields listed below.
..externalWarehouseIdStringWarehouse identifier in external system (OVT code). Mandatory for stock balance updates.
..quantityNumberCurrent stock of product in the warehouse. Mandatory for stock balance updates.
..totalPriceNumberProduct wholesale price for a webshop in the warehouse, VAT 0%.
..currencyString3-letter currency code of product (ISO 4217). If not given, "EUR" used as default.
additionalInfoObjectAdditional Info of the product e.g. pictures, notes, additional IDs.
.attachmentsArrayAttachments regarding product.
..typeStringType of additional info e.g. "productImage1" or "marketing".
..URIStringURI to the document.
..fileTypeStringType of file e.g. "pdf" or "png".
..fileNameStringName of the attachment file. e.g. "User Guide" or "Product Image".
.commentsArrayComments regarding product.
..typeStringHow the comment should be used e.g. "marketing".
..valueStringThe comment text.
.classificationsArrayClassifications regarding product.
..typeStringType of product classification. For classification use GS1 GPC Standard, december 2016
..valueStringThe classification.
.productVariationIdsArrayAlternative ids for the product.
..typeStringType of product id e.g. "supplierId".
..valueStringThe id.
.dangerousGoodsDetailArrayDetails about dangerous goods (ADR).
..isDangerousGoodsBooleantrue/false value, is the product a dangerous good.
.warrantyDetailArrayDetails about product warranty.
..expirationStringThe extent of the warranty.
..serialControlledBooleanWhether the product is serial number controlled.
specificationsArrayList of product specifications or features. See picture below.
.typeStringProduct specification group Technical specifications, Materials and Care, Size and Fit, Details, Functions
.propertyArrayList of product property or feature value pairs.
..typeStringProduct property or feature type e.g. "size".
..valueStringProduct property or feature value e.g. "44".
..specifierStringProduct property or feature specifier e.g. "Eur".
..languageIdStringLanguage code of description, in two-letter ISO 639-1 format, e.g. "fi".
..descriptionStringProduct 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 codeExplanation
200Request processed successfully.
404Requested resource was not found.
500An error occured while processing request.

GET/v2/products/all/private

Overview

Get all privately published products.

Response fields

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

ElementtypeDescription
productsArrayArray of products

Example response

Similar response as for all products.

Response codes

Same as when retrieving a single product.


GET/v2/products/all/{warehouseId}

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.

ElementtypeDescription
productsArrayArray of products

Example response

Similar response as for all products.

Response codes

Same as when retrieving a single product.


GET/v2/products?externalId={id1}&externalId={id2}...

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.

ElementtypeDescription
productsArrayArray of products

Example response

Similar response as for all products.

Response codes

Same as when retrieving a single product.


POST/v2/products/multiple

Overview

Update information of one or multiple products. Can also be used to insert new products. The request body must be an array consisting of one or more product objects.

Query parameters

none

Request fields

ElementtypeDescription
externalIdStringUnique identifier of the product from seller's system.
nameStringName of product.
shortNameStringShort name of product.
descriptionObjectLonger description of the product in different languages.
.enStringLonger description of the product in English.
.fiStringLonger description of the product in Finnish.
EANCodeStringEAN code of product.
supplierStringName of the product supplier.
categoryStringProduct category, e.g. "Fishing/Fishing rods/Open reel fishing rods".
measurementsObjectMeasurements of the product
.weightNumberGross weight of the product in kg, with packing materials
.lengthNumberLength of the product in m
.widthNumberWidth of the product in m
.heightNumberHeight of product in m
.volumeNumberVolume of product in m3
isFragileBooleanIndicator of whether product is fragile.
hasBestBeforeDateBooleanIndicator of whether product has a best before date.
hasWarrantyBooleanIndicator of whether product has a warranty.
vatPercentageNumberTax-rate of the product in percentage
totalPriceNumberProduct list price, VAT 0%
currencyString3-letter currency code of product (ISO 4217). If not given, "EUR" used as default.
stockBalanceObjectProduct stock information. Mandatory for stock balance updates.
.warehouseBalanceArrayWarehouse stock information. Includes objects with fields listed below.
..externalWarehouseIdStringWarehouse identifier in external system (OVT code). Mandatory for stock balance updates.
..quantityNumberCurrent stock of product in the warehouse. Mandatory for stock balance updates.
..totalPriceNumberProduct wholesale price for a webshop in the warehouse, VAT 0%.
..currencyString3-letter currency code of product (ISO 4217). If not given, "EUR" used as default.
additionalInfoObjectAdditional Info of the product e.g. pictures, notes, additional IDs.
.attachmentsArrayAttachments regarding product.
..typeStringType of additional info e.g. "productImage1" or "marketing".
..URIStringURI to the document.
..fileTypeStringType of file e.g. "pdf" or "png".
..fileNameStringName of the attachment file. e.g. "User Guide" or "Product Image".
.commentsArrayComments regarding product.
..typeStringHow the comment should be used e.g. "marketing".
..valueStringThe comment text.
.classificationsArrayClassifications regarding product.
..typeStringType of product classification. For classification use GS1 GPC Standard, december 2016
..valueStringThe classification.
.productVariationIdsArrayAlternative ids for the product.
..typeStringType of product id e.g. "supplierId".
..valueStringThe id.
.dangerousGoodsDetailArrayDetails about dangerous goods (ADR).
..isDangerousGoodsBooleantrue/false value, is the product a dangerous good.
.warrantyDetailArrayDetails about product warranty.
..expirationStringThe extent of the warranty.
..serialControlledBooleanWhether the product is serial number controlled.
specificationsArrayList of product specifications or features. See picture below.
.typeStringProduct specification group Technical specifications, Materials and Care, Size and Fit, Details, Functions
.propertyArrayList of product property or feature value pairs.
..typeStringProduct property or feature type e.g. "size".
..valueStringProduct property or feature value e.g. "44".
..specifierStringProduct property or feature specifier e.g. "Eur".
..languageIdStringLanguage code of description, in two-letter ISO 639-1 format, e.g. "fi".
..descriptionStringProduct 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

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

POST/v2/products/supplier/multiple/{webshopId}

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 rows.externalWarehouseId must match the warehouse id given by webshop.

Query parameters

none

Request fields

An array of objects, same request fields as for updating multiple products.

Response codes

Same as when updating multiple products.


POST/v2/products/{productId}

Overview

Update information of a product. Can also be used to insert a new product. The request body must be a product object.

Query parameters

none

Request fields

Same request fields as for updating multiple products.

Example Request

{
    "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 Product update JSON schema

Response codes

Same as when updating multiple products.