Here you will find the main structure of how the catalogs are organized in our systems. It's important to know that you will have categories, stores, products, and catalogs that are related as follow:
As you can see above, the "Catalog" is the interacts with the e-commerce experience. The attributes of "Stores", "Categories" and "Products" are displayed in the e-commerce associated to a Catalog. That means that the customer
Next, you will find the explanation of each resources ("Catalog", "Products", "Stores" and "Categories") with their attributes and what they are used for. Also, you will see an explanation of promotions associated a one catalog and how to create them.
The product that you want to have diplayed in the e-commerce must have a "Catalog" record.
The static information of a product is stores in a "Product" record.
A Catalog record will alway have a "Product", "Store" and at least one "Category" associated.
The first thing that you need to do, is create the Stores. Each "Store" record represents one store where the customer can purchase in e-commerce.
All The attributes that a "Store" returns when GET API is consumed, are described below:
|id||String||Unique store identifier. It's used to identify the store in the database and is the key that relates a Store with a Catalog.|
|name||String||Name of store. The name will appear in the e-commerce when the user selects "Pick up in store" method.|
|storeReference||String||Store identifier for the customer|
|phone||String||Phone number of the store|
|address||String||Address of the store. The address will appear in the e-commerce when the user selects "Pick up in store" method.|
|addressTwo||String||Auxiliary address of the store|
|country||String||Country where the store is located. The country will appear in the e-commerce when the user selects "Pick up in store" method.|
|self||String||Path to get the store through API|
For the first iteration, you are be able to create a Store through one ticket about "Configuration of ecommerce - Operation: create new Store".
In e-commerce, products are organized by categories and subcategories to simulate an online experience comparable to a physical store.
The attributes that one "Category" must have are described below:
|id||String||Unique category identifier|
|name||String||Name of the category|
|categoryReference||String||Category identifier for the customer|
|parentId||String||id of the parent category in the category tree. The parentId of the main categories must have the id of the "DEPARTMENT" category.|
|slug||String||It’s the last part of the URL after the last backslash when the user is viewing the category in the e-commerce|
|boost||Int32||It organizes the display order of the categories in one level of e-commerce (according to the category tree). To lower “boost”, greater prioritizing of the category (displayed from top to bottom)|
|isAvailableHome||Boolean||If this attribute is “TRUE”, the category is displayed in the home of e-commerce, otherwise no. Only apply for categories level 1|
|self||String||Path to get the category through API|
The categories are divided into levels that you can hierarchize with "parentId" attribute.
When you create an e-commerce, the system automatically creates one category type "DEPARTMENT", which will be the root level of the Category Tree. The "DEPARTMENT" category is not a real category but It's necessary for creating the categories that will be displayed in the e-commerce. All others categories will be sublevels of the "DEPARMENT" category and must be type "CATEGORY".
Bellow, you will see an example of an e-commerce with five categories: 3 categories level 1 (the parent category must be the "DEPARMENT" category) and two level 2 under "Dairy Products" category:
For a better user experience, It’s recommended that products be in the lower levels, because the higher levels show the products contained in their sublevels.
You can have the same product in different categories, such as “Dutch cheese” in the example above.
It's important to know that the categories contain "CATALOGS" and not "PRODUCTS", so you can have products within different categories per store. this is possible because each catalog record must have a store and category (one or more) associated with it. If you want to have one special category only in one store, the only thing that you need to do is create catalogs with the category and that Store.
For the first iteration, you are be able to create a Categories through one ticket about "Configuration of ecommerce - > Catalog: update categories".
A “Product” record stores the intrinsic attributes of a product, that usually don’t change and is used to feed the catalog records.
All the attributes that a "Product" must have are described below:
|id||String||Unique product identifier|
|sku||String||Product identifier for the customer|
|ean||Array of Strings||Type of barcode that encodes a product number. One product could have multiples ean.|
|name||String||name of the product|
|unit||String||Unit of measure or packaging form of the product. Example: "Pack" or "Kg"|
|photosUrl||Array of Strings||URLs that contain product photos|
|NutritionalDetails||String||URL that contain a photo that is show at the end of all photos|
|clickMultiplier||Int32||Number of products to add to the shopping cart when a user clicks on add product ("+" symbol)|
|subUnit||String||Subunit of measure or a single unit of the product. Examples: “Bottle” or “gr”|
|boost||Int32||It organizes the display order of the products in the same category (according to the category tree). To lower “boost”, greater prioritizing of the product (displayed from top to bottom)|
|description||String||Description of the product|
|slug||String||It’s the last part of the URL after the last backslash when the user is viewing the product on the e-commerce|
|Variants||Array of Objects||possibility of having variants of a product (In progress)|
|Formats||Array of Objects||possibility of having formats presentation of a product (In progress)|
|self||String||Path to get the product through API|
For the first iteration, you are be able to create a products through API with a POST request for Products(see the endpoint).
A “Catalog” record stores the attributes that frequently change such as “price” and “stock”, and will always have a “Product”, “Store” and at least one "Category" associated that feed the Catalog displayed in the e-commerce.
It's important to know, a “Product” stores the intrinsic attributes of a product that are equal for all stores that carry that product, and “Catalog” stores the attributes that change among stores.
All the attributes that a "Catalog" must have are described below:
|id||String||Unique catalog identifier|
|productId||String||Unique product identifier|
|storeId||String||Unique store identifier|
|price||Int32||Price of the product in one store|
|stock||Int32||Stock of the product in one store|
|categories||Array of String||list of categories where the product can be found in one store.|
|maxQty||Int32||Maximum quantity of units of a product in one store that the user can add to the shopping cart|
|minQty||Int32||Minimum quantity of units of a product in one store that the user can add to the shopping cart|
|isActive||Boolean||If the “active” attribute is “TRUE”, the category is displayed in the e-commerce, if it’s “FALSE” the category isn´t displayed|
|self||String||Path to get the catalog through API|
|securityStock||Int32||Minimum number of units to have the product available in one store|
|location||String||Location of the product. It could be as specific as you want, for example, warehouse, hallway, or shelf|
|Promotion||Array of Objects||Promotions associated with the product (see promotion section)|
For the first iteration, you are be able to create a catalog through API with a POST request for Catalogs (see the endpoint).
The promotions are associated with one "Catalog" record. All the attributes that a "Promotion" must have are described below:
|Type||String||Type of promotion. Only "specialPrice", "stepped" and "nx$"|
|Description||String||Description of the promotion|
|startDateTime||String||Date when the promotion begins in the e-commerce. (specialPrice don`t use this field)|
|endDateTime||String||Date when the promotion ends in the e-commerce (specialPrice don`t use this field)|
|isActive||Boolean||If this attribute is “TRUE” and is in range of dates, the promotion is displayed in the product in the store, otherwise no (specialPrice don`t use this field)|
|conditions||Array of Objects||Conditions of the promotion (see conditions)|
The conditions contain an array of objects and each object has only two attributes: “qty” and “price”. The way to use the “qty” and “price” attributes depend on the type of promotion.
SpecialPrice : the condition only has one object. The “price” attribute is the applicable price for the product just until the specified quantity (“qty” attribute). The user will only be able to purchase until the quantity specified in the promotion, the e-commerce will not allow the user to add more than this quantity.
nx$ : the condition only has one object. The “qty” attribute is the number of units that the user must buy to access the price specified in the promotion (“price” attribute). The special price is only applicable for the quantity specified, if the user adds or removes one or more units, the promotion will no longer valid.
stepped : the condition may have one or more. The “qty” attribute is the minimum order in one range to access the price specified (“price” attribute). For example, if the condition has two ranges: 1[qty: 4, price:30] and 2[qty:10, price: 26]. Between 1 and 3 units, the unit price is the original price, between 4 and 9 the unit price would be 30, and between 10 or more the unit price would be 26.
For the first iteration, you are be able to create a promotion through API with a POST request for Promotions (see the endpoint).
Updated 3 months ago