Managing Variants

What is a variant in a marketplace?

A variant is essentially a different version of the same item. For example, a T-shirt (item) can have 3 variants : "Color", "Weight", "Material". 

Image caption: Buyer’s view of an item with variants


A variant option refers to the different types of a variant. For example, the variant "Color" of a T-shirt can have 3 variant options : "Red", "Blue", "Green".


What is the relationship between variants and the parent item?

The diagram below shows the relationship between a parent item and its variants , also known as the parent-child item relationship.

• The parent item is the T-shirt (in red). This is what the buyer will see on the client-side browser.

• The variants of the T-shirt are “Size”, “Color”, “Material” (in blue). These variants will be shown as individual options in the dropdown menu on the item detail page.

• The variant options of those variants, eg. “Red”, “Green” ,“Blue” (in yellow) will also be shown as individual options in the dropdown menu on the item detail page. 

Image caption: Relationship between parent item, variant groups, and variant options


Who creates the variants? 

Since parent items are created by merchants, the variants and its variant options are also created by merchants. They are in charge of choosing the names and types of variants and its variant options.

Image caption: merchant’s view when creating variants.


How is that relationship reflected in the system and APIs?

When a merchant creates an item with variants similar to the chart above, that means that there are (3 x 3 x 3) 27 possible variations of the same T-shirt. 


Of course, that doesn’t necessarily mean that the merchant must have all the possible combinations - that’s why we give the merchant the option to set a quantity for each one of them at the time of creation of the item.


In APIs:


For each possible combination, each variant will have its own unique item ID also known as a child item ID. In the example of the T-shirt, since there are 27 possible combinations of T-shirt variance, then there will be 27 child item IDs respectively. These child item IDs will be under the parent item ID. 


How is this important for developers?

Since a buyer has to choose a variant when buying a T-shirt like this, the Checkout and Cart APIs apply the same rule.

In other words, you have to use the child item ID to add the variant to the cart. In the example of the T-Shirt above, all 27 variants (child items) will have a unique item ID which is different from the parent item ID. 


Adding the parent item ID to the “Add Item to Cart API” will return a “null” response. So, do lookout for this!

Exact details can be found in the documentation here.


JSON structure of item details of an item with variants

Since a child item is basically an item on its own, all child items will be grouped in an array of child items, a.k.a, typical item detail responses nested within the parent item detail response.

The sample response below is that of an item with 2 variants (Child items): [Not all fields are shown]      

	ID: parent_item_ID
	SKU: "string"
	Price: 0
	Categories: [ ],
	CustomFields: [ ],
	HasChildItems: true,
	ChildItems: [{"Variants": [{"Name": "Black","GroupName": "Color"}],
	ID: child_item_ID,
	SKU: "string",
	Price: 1,
	Categories: [ ],
	CustomFields: [ ],
	HasChildItems: false,
	ChildItems: [ ],
	CreatedDateTime: 0,
	ModifiedDateTime: 0},
	{"Variants": [{"Name": "Black","GroupName": "Color",}],
	ID: child_item_ID,
	SKU: "string",
	Price: 1,
	Categories: [ ],
	CustomFields: [ ],
	HasChildItems: false,
	ChildItems: [ ],
	CreatedDateTime: 0,
	ModifiedDateTime: 0}],
	CreatedDateTime: 0,
	ModifiedDateTime: 0


Moving items across categories

All items that have been created in a marketplace must be under at least 1 category. In other words, an item cannot exist without a category. 

If you wish to shift items from one category to another , you should do so by shifting only the parent item. 

The only way to do this is via API. More details can be found here.

Changing the Category IDs in the request body will OVERWRITE the item's current categories it belongs to.


So if an item belongs to Category A, Category B and Category C, and you want to change Category A to Category D, then the request body should look like this:

URL: api/v2/merchants/{ { merchantID } } /items/{ { itemId } }
Method: PUT
Auth:  Bearer { { merchant-token } } or Bearer { { admintoken } }
	"Categories" :[
			ID: "category_D_id"
			ID: "category_B_id"
			ID: "category_C_id"

Omitting categories B and C will simply remove the item from them.


Visibility and Item Vetting

There are 3 free fields that can be edited in the Item API that affect the item’s visibility. Each is controlled by a different group of users:

“IsVisibletoCustomer” - controlled by Admin

“IsAvailable” - controlled by Merchants

“Active” - controlled by Arcadier

 All 3 of them are booleans, i.e, they only take either 'true' or 'false' as values.



Outside API context, there is a toggle for merchants to decide if an item is purchasable or not. It is found on the merchant’s item list, as seen below:

Purchasable toggle on merchant’s list of items

This toggle affects the “IsAvailable” field.



On the Admin portal, admins also have some level of control over an item’s visibility. The toggle (shown below), affects the “IsVisibletoCustomer” field.

Purchasable toggle on admin item list



Setting the “Active” field to false will soft delete it from the marketplace and will not be retrievable by anyone; not even APIs. If an item is set to “Active” falsely by mistake, contact


Free Field





Setting ‘true’ to this field will allow the respective item to be displayed on the marketplace and will be visible to all group users unless :

  • Admin set “IsVisibleToCustomer” to false 

  • Merchants set “Is Available” to false

Setting ‘false’ to this field will soft delete the item. It will not be displayed on the marketplace and will be invisible to all group users.

The item will still reside in the Arcadier system but will be non-existent in the marketplace.



Custom Fields

Our APIs provides many fields which contain a lot of useful information. But sometimes certain builds need to have customised fields in order for them to function at their maximum potential.

This is why we brought Custom Fields to our API ecosystem.

In our system, there are 3 different approaches to manipulate and create custom fields. Different methods are used to interact with the custom fields such as graphical user interface methods and the calling of API method.


The 3 main approaches to creating custom fields are through :


 Admin Portal Creates custom fields for items and for merchants to fill up
Developer Dashboard Creates custom fields for items, users, orders and the marketplace itself, for the developer to fill up, or for the developer to choose who should fill it up
Using APIs Use APIs if specific custom fields need to be created only on demand. It creates custom fields for items, users, orders and the marketplace itself, for the developer to fill up, or for the developer to choose who should fill it up


Admin Portal

Admins can create custom fields by accessing the Admin Portal of the respective marketplace. 

You can find out more about admin control on custom fields by clicking here.


Developer Dashboard

Custom fields created on the Developer Dashboard are those which the developer knows he/she will need while building plug-ins. 

Example 1:
A particular integration with a 3rd party needs an authentication token, and this token needs to be saved by the Admin, so that it can be used across the plug-in. This token can be saved in a custom field that:

1. Is associated with the marketplace (Reference Table : marketplace)

2. Stores a string (DataInputType : textfield , DataFieldType : string)

Once it’s created, the developer will be given the custom field’s code, and he/she can use it to save/retrieve its contents.


Example 2:

A plug-in creates custom fields to store the age of users. This custom field can be created using the developer dashboard.

Once it’s created, each user will have an additional field given to them to fill up with a number. That field will stick to them as a property/attribute; this can then be used for various purposes like targeted searches/censorship.


Using API

The Create Custom API provides full flexibility in the way you want your custom fields to be created and used. One good way to look at it is that the API allows on demand creation of Custom Fields.

Details on how to use this API can be found on our API Documentation and Tutorials on GitHub.


Search Filtering, Grouping & Categorization using Custom Fields

Knowing which way is the best to create the custom fields you want is half of your work done. With Custom Fields attached to :


  1. Items

  2. Orders

  3. Users

  4. The marketplace itself,

It becomes possible to group/categorize/filter them according to your needs. 

For example, a custom field called “Brand” can be created from the Admin Portal. This gives a “Brand” custom field to all items which merchants will have to fill up. A plug-in can then filter out items with a specific "Brand A" and promote them more over others. Below shows further examples of filtering and categorising via Custom Fields :