Product Creation Primer

This primer document takes you through the high-level concepts you need to be aware of to ensure you successfully create products in Marketplacer.

7 minute read

Introduction

There are a number of concepts in Marketplacer that you should be aware of when creating products, this guide provides a high-level end to end to end view of that process, with a focus on using the Seller and Operator APIs.

Intended audience

This document is aimed at anyone interested in creating products on Marketplacer using the API, specifically:

Sellers
Channel Managers

This guide can also be used by operators that create products on the platform, although this is a less common use-case.

Terms and concepts

The following are key terms and concepts that we’ll reference in this article:

Term	Alias	Description
Advert	Product	Adverts are essentially just products, but are referred to as adverts in the API domain. This document will use each term interchangeably, but will typically use advert when discussing the API domain, and product at all other times.
Advert Vetting	Product Vetting	Advert Vetting is an optional workflow that an Operator can enable. Vetting allows the Operator to ensure that Products (Adverts) adhere to their own publishing standards before they can be placed for sale on the marketplace.
Catalog Rules		Catalog rules allow the marketplace operator to set further validation criteria for products and variants that have to be satisfied in order for a product to be considered valid. E.g. A product must have a minimum of 3 images and a description length of at least 250 characters. Catalog rules complement Advert Vetting.
Golden Record	Golden Product	Catalog rules allow the marketplacer operator to set further validation criteria for products and variants that have to be satisfied in order for a product to be considered valid. E.g. A product must have a minimum of 3 images and a description length of at least 250 characters. Catalog rules complement Advert Vetting.
Option Type	Attribute	Option Types refer to the way an Advert or Variant can be defined. So common Option Types would be color and Size. Option Types will then have 1 or move Option Values, which contain the range of values that it is possible for the Option Type to have.
Option Value	Attribute Value	The values that an Option Type can have. In the example where we have an Option Type of Color, possible Option Values would be: Red, Green, Blue etc.
Prototype	Attribute Group	Prototypes are the glue between a Taxon and the Option Types that Taxon has. So we assign Option Types to a Prototype, and then assign a Prototype to the Taxon. This means we can assign that same defined Prototype to any number of other Taxons.
Taxon	Category	A taxon represents where the product sits in the categorization hierarchy. The products taxon, determines the Option Values that can be assigned to it, this relationship is enabled via the prototype.

Product Validity

Before discussing the workflows for creating products, it can be useful to determine what makes a product valid.

The following table describes 3 boolean (true or false) fields that a product has: published, displayable and online. The values of these 3 fields in combination determine overall product state or “validity”.

Field Name	Type	Description
`published`	boolean	Describes the intent of the Seller. A Product may be correctly defined and have inventory (at least 1 variant has a positive value for `countOnHand`), however the Seller may choose not to Sell this item, e.g. it has been withdrawn because a newer version is available. In this example `published` would be `false`. Setting the value of `published` to `false` has a cascading effect on the values of the remaining fields outlined in this section, i.e. they too will have the value of `false`.
`displayable`	boolean	System defined value, (unlike `published` which is set by the Seller), this value represents whether it is possible to Sell this Product in its current state. The value of `displayable` is determined by Marketplacer and is based on a number of criteria, including but not limited to: 1. whether there is positive inventory (`countOnHand`) for at least 1 variant, 2. whether all mandatory attributes are configured, (including Catalog Rules if enabled) 3. if product vetting is enabled, that the vetting process has been successfully completed, 4. whether `published` is `true`
`online`	boolean	This state is determined by the status of the Seller of the Advert. I.e. if the Seller has been taken offline by the Operator, then the value of `online` will be `false`.

Combinations of these 3 fields and the overall product state are shown below:

Published	Displayable	Online	Description	“State”
`true`	`true`	`true`	Advert is available to sell. The seller has the intent to sell (`published` is `true`), the advert has been successfully constructed, with inventory (`displayable` is `true`), and the Seller account is online (`online` is `true`)	Online / Published
`true`	`false`	`false`	Advert is not available to sell. While the Seller has the intent to sell (`published` is `true`), for some other reason the advert cannot be displayed, (`displayable` is `false`), e.g. vetting is required. In this scenario the value of `online` is also impacted by the value of `displayable`	Offline / Unpublished
`true`	`true`	`false`	Advert is not available to sell. While the Seller has the intent to sell (`published` is `true`), and the advert is technically valid (`displayable` is `true`), the Operator has taken the Seller offline.	Offline / Unpublished
`false`	`false`	`false`	Advert is not available to sell. The Seller does not have the intent to sell this item (`published` is `false`). The value of `published` also impacts the values of `displayable` and `online`	Offline / Unpublished

Ultimately the goal of a seller listing products on Marketplacer is to have their products in the “Online / Published” state.

Product create flow

The high-level product create flow is shown below:

Product Create Flow

Let’s take a look at each stage in turn:

Create product via API

There are 3 variations on the way products can be created, these are described below with links to more detailed documentation:

Method	Description	Doc links
Supply Marketplacer Ids	This is the “classic” way of creating products in Marketplacer where you first retrieve the taxonomy (category) and associated data from Marketplacer, then use that reference data as input when creating products using the API.	Guide Video
Use Mapping Values	This method allows you to supply free-text values for (some) fields that would have otherwise required a Marketplacer Id, e.g. Brand.	Guide Video
Golden Product	With this method the barcode is supplied via API, and the remaining product details are back-filled from the Central Product Database using the barcode as a lookup. This method is available at the discretion of the marketplace operator.	Guide Video

Mandatory Data

The following fields are always mandatory when creating products:

Attribute	Description	Supplied As
Taxon	The category where the product sits	- Taxon Id - Mapping Value
Brand	The brand of the product	- Brand Id - Mapping Value
Title	The headline for the product	- String
Description	The detailed product description	- String
Price	The current price of the product	- String
Image	At least 1 image must be supplied at the Advert level	- URl - Base64
1x Variant	Products need to have at least 1 variant	- Object

Catalog Rules

Catalog rules are an automated validation solution that operators can use to further specify requirements on the data that must be supplied with a product in order for it to be considered valid.

Catalog rules may or may not be used by an operator.

Some points to note about catalog rules:

If both catalog rules and product vetting are being used, the product will not progress to vetting unless the catalog rules are passed
Products already online will remain so, even if catalog rules are subsequently introduced

Product Vetting

Product vetting is a workflow that can be employed by operators to allow for further checks on a product’s suitability for listing. Vetting is complementary to catalog rules. If enabled a product must pass vetting in order for it to be considered valid.

Product vetting may or may not be used by an operator.