General Usage Product API
Overview Model
Product Creation Workflow
API Reference Docs

Using Product API

The product API consists of 3 core groups of endpoints: product models, products and attribute types. Product models define configurable elements of a product, namely attributes and variant types. A product's attributes are a collection of key value value pairs defining content enrichment attributes of the product, for example: "description":"A red summer dress". These attributes map to content displayed on the website for a given product, the available attribute keys which can be used for a given product are defined in a product model.

Product Model

The model outlines the necessary attributes for each product entity. These attributes are defined in a dedicated section of the product model JSON, termed 'availableAttributes'. Each available attribute can have associated constraints which the attribute value must conform to, read more about attribute models.

A product model can be used to define many products. More information about your collection of product models can be found in the API Reference Documentation.

Products

When a product is created, it is validated against a product model using the provided name and version of that model. The API validates whether the product complies with the model, and if the validation fails, it provides a detailed error message.

Example Validation Error
{"errors": [{"id": "91b4543f-a717-49f3-a629-2bd2b8e4fe3c", "status": "422", "code": "RequestValidationError", "title": "Request Field Failed Validation", "detail": "weight_g must be a float greater than 0.", "source": {"pointer": "weight_g"}}, {"id": "ur384hr3-a717-49f3-a629-2bd2b8e4fe3c", "status": "422", "code": "RequestValidationError", "title": "Request Field Failed Validation", "detail": "height_mm must be a float greater than 0", "source": {"pointer": "height_mm"}}]}

More information on error codes and responses can be found here.

Example Product
An example product is given below, where the top level product is a "summer dress" which conforms to the "product_model" product model; this "summer dress" then has a collection of colour variations (the type of variation is defined in the product model). Each colour varitaion, for example "purple summer dress", conforms to its own product model, in this example it conforms to "dress" product model which has size variations. 
{"name": "summer dress", "modelName": "dress", "modelVersion": "0.1", "attributes": {}, "variants": [{"name": "purple summer dress", "modelName": "coloured_dress", "modelVersion": "0.1", "attributes": {"title": "Purple Summer dress"}, "variants": [{"sku": "30493049304903", "barcode": {"EAN": "93849384398493"}, "prices": {"DE": {"EUR": 30.99, "GBP": 27.99}}, "mass_g": 45, "height_mm": 32, "width_mm": 24, "length_mm": 13, "countryOfOrigin": "GB", "harmonizedSystemCode": "839402943859", "variantType": {"size": "38"}}], "variantType": {"colour": "purple"}}]}
Then the final level is a non-content product, these contain physical attributes of the product. A non-content product conforms to a predefined static model (vInventory class within the API reference documentation) which lists required keys and any value constraints. vInventory example can be seen below: 
            {"sku": "30493049304903", "barcode": {"EAN": "93849384398493"}, "prices": {"DE": {"EUR": 30.99, "GBP": 27.99}}, "mass_g": 45, "height_mm": 32, "width_mm": 24, "length_mm": 13, "countryOfOrigin": "GB", "harmonizedSystemCode": "839402943859", "variantType": {"size": "38"}}
Every non-content product is composed of 4 main collections of information, the first being identification. Each non-content product will have a unique "sku" associated to it for identification as well as a barcode for the physical product. The second set of information is price, this is a collection of currency price pairs grouped by region/country, in the given example above the price is given in both British pounds and Euro for Germany. A list of available regions/country as well as required currencies for that region will be provided by THG. Thirdly there is set of physical attributes of the product: mass (given in grams), height, width, and length (given in millimeters). Final section of a non-content product is the legal/policy/regulatory attributes.